2.9.16
Coherent GT
A modern user interface library for games
Coherent::UIGT::View Class Referenceabstract

Class that encapsulates a UI View (an HTML5 page and JS context) Provides all manipulation and query functions for the view. More...

#include <Coherent/Coherent/UIGT/View.h>

Public Member Functions

virtual void Destroy ()=0
 Destroys this view. More...
 
virtual unsigned GetId () const =0
 Returns a unique id of the View. More...
 
virtual const char * GetTitle () const =0
 Gets the "<title>" of the View. More...
 
virtual const char * GetInputGroupUnderCoordinates (float normX, float normY) const =0
 Gets the value of the data-input-group attribute of the element under the given mouse coordinates. If the element does not have the attribute, it will return the value of the attribute of the first ancestor that has it. Useful when you need to customize mouse queries and need extra data besides whether the mouse is on the view. More...
 
virtual unsigned GetWidth ()=0
 Gets the width of the View. More...
 
virtual unsigned GetHeight ()=0
 Gets the height of the View. More...
 
virtual void Resize (int width, int height)=0
 Resizes the View contents. More...
 
virtual void KeyEvent (const Coherent::UIGT::KeyEventData &event)=0
 Sends a key event to the UI renderer. More...
 
virtual void MouseEvent (const Coherent::UIGT::MouseEventData &event)=0
 Sends a mouse event to the UI renderer. More...
 
virtual void SetFocus ()=0
 Sets this view on focus. This must be called in order for the text caret to appear.
 
virtual void KillFocus ()=0
 Removes the focus from this view.
 
virtual bool IsTransparent () const =0
 Tells if this view is transparent or not. More...
 
virtual unsigned Layout ()=0
 Layouts the content of the page. You should call this method each frame after calling Advance on the UI system. More...
 
virtual void ExecuteJSTimers ()=0
 Executes all JS timers (setTimeout/requestAnimationFrame) for the View. More...
 
virtual void UpdateStylesAndLayout ()=0
 Updates the styles of the View and performs an eventual re-layout of it. More...
 
virtual unsigned RecordRenderingCommands ()=0
 Records rendering commands that will later be replayed in the "Paint(frameId)" method. More...
 
virtual bool HasLastLayoutCompleted ()=0
 Checks whether the last issued Layout operation has completed. More...
 
virtual void ShowPaintRects (bool show)=0
 Will render the rects in the page that get re-drawn each frame. More...
 
virtual void ShowLayerBorders (bool show)=0
 Will render the borders of the layers in the page. More...
 
virtual const char * GetLastLoadedURL () const =0
 Returns the last loaded URL by the View. More...
 
virtual bool IsDocumentReady () const =0
 Tells if the Document object is ready in JS. More...
 
virtual void StopLoading ()=0
 Interrupts the loading process of the View. More...
 
virtual void LoadURL (const char *url, ViewLoadPolicy policy=VLP_UseCacheOrLoad)=0
 Loads a new page in the View. More...
 
virtual void Reload ()=0
 Reloads the current HTML5 page.
 
virtual void RedrawAll ()=0
 Causes the whole frame to be re-submitted for painting.
 
virtual bool CanGoBack () const =0
 Tells if the View can go back in history. More...
 
virtual bool GoBack ()=0
 Goes back in the View history. More...
 
virtual bool CanGoForward () const =0
 Tells if the View can go forward in history. More...
 
virtual bool GoForward ()=0
 Goes forward in the View history. More...
 
virtual bool CookiesEnabled () const =0
 Tells if cookies are enabled for this View. More...
 
virtual bool IsMouseOnView ()=0
 Checks if the mouse is currently on the logical view (a part of the view that has elements on it) or not (click-through). Uses the coordinates last set in IssueMouseOnUIQuery. More...
 
virtual void SetMediaType (MediaType type)=0
 Change the media type of the view. More...
 
virtual bool IMESetComposition (const char *composition, unsigned cursorPos, unsigned targetStart, unsigned targetEnd)=0
 Updates the internal state of the IME composition in the View. More...
 
virtual bool IMEConfirmComposition (const char *composition)=0
 Confirms the current IME composition. More...
 
virtual bool IMECancelComposition ()=0
 Cancels the current IME composition. More...
 
virtual void SetClickThroughAlphaThreshold (float threshold)=0
 The alpha value of the pixels is used to determine if the mouse is on an element or on the background (click-through). All pixels below or equal to the alpha threshold (default = 0) are marked as not-belonging to the View and IsMouseOnView for them return false. More...
 
virtual float GetClickThroughAlphaThreshold () const =0
 Get the currently set alpha threshold for click-through queries. More...
 
virtual float GetAnimationFrameDefer () const =0
 Returns the minimum delay between animation frames in seconds. More...
 
virtual void SetAnimationFrameDefer (float valueSec)=0
 Sets the minimum delay between animation frames in seconds. More...
 
virtual bool GetOffscreenCanvasRendering () const =0
 Returns offscreen canvas command execution mode. More...
 
virtual void SetOffscreenCanvasRendering (bool force)=0
 Sets the offscreen canvas command execution mode. More...
 
virtual void EnableOnScreenPerformanceInfo (bool enable, unsigned x=0u, unsigned y=0u)=0
 Will display performance information on-screen. Enabling this option will also force compositing mode on the View. More...
 
virtual void BeginCaptureDebugFrame (void *userData, FrameCaptureCallback callback)=0
 Will begin serializing every rendered frame to a memory blob which will be passed in the callback. The saved frames can be inspected for debug purposes. More...
 
virtual void EndCaptureDebugFrame ()=0
 Ends serializing rendered frames.
 
virtual void CaptureSingleDebugFrame (void *userData, FrameCaptureCallback callback)=0
 Will serialize next rendered frame to a memory blob which will be passed in the callback. The saved frames can be inspected for debug purposes. This will force redraw of the whole UI for the frame. More...
 
virtual void AuditPerformance (bool shouldDisplayOnScreen=false, const char *frameSelector=nullptr)=0
 Executes an auditing script that detects sub-optimal parts of your UI and reports them on screen and via ViewListener::OnPerformanceAudit. By default the main frame will be audited but you can specify a CSS selector to any iframe in the page. More...
 
virtual void InspectorTimelineBeginEvent (const char *name)=0
 Marks the beginning of an event in the Inspector timeline. Events must be 'ended' with InspectorTimelineEndEvent to get a measure of their duration. More...
 
virtual void InspectorTimelineEndEvent (const char *name)=0
 Marks the end of an event in the Inspector timeline. More...
 
virtual void GetCacheCountStats (InternalCaches cache, unsigned &filled, unsigned &capacity)=0
 Get info about the number of objects statistic of a particular internal cache. More...
 
virtual void GetCacheBytesStats (InternalCaches cache, unsigned &filled, unsigned &capacity)=0
 Get info about the bytes statistic of a particular internal cache. More...
 
virtual void QueueSetCacheCountSize (InternalCaches cache, unsigned capacity)=0
 Queue task to set the maximum number of objects in internal cache. More...
 
virtual void QueueSetCacheBytesSize (InternalCaches cache, unsigned capacity)=0
 Queue task to set the maximum bytes allowed for internal cache. More...
 
virtual void QueueClearCaches (unsigned caches)=0
 Queue a task to clear an internal caches list. More...
 
virtual void SetScriptError (ScriptCallErrorType error, const char *message)=0
 Sets an error for the currently executing handler. More...
 
virtual BoundEventHandle RegisterForEvent (const char *name, IEventHandler *handler)=0
 Expose C++ handler to be called when a specific event occurs. More...
 
virtual void UnregisterFromEvent (BoundEventHandle handle)=0
 Remove a registered C++ handler. More...
 
virtual BoundEventHandle BindCall (const char *name, IEventHandler *handler)=0
 Expose C++ handler to be called from UI. More...
 
virtual void UnbindCall (BoundEventHandle handle)=0
 Remove a bound C++ handler. More...
 
virtual void UnbindObject (const void *object)=0
 Remove all handlers bound to a specific object. More...
 
template<typename T >
void ExposeAsGlobal (const char *name, T *object, Binder::BindingMode mode=Binder::BindingMode::BM_ScopedUnsafe)
 Expose object as global variable. More...
 
template<typename T >
void RemoveExposedInstance (T *object)
 Remove exposed object from JavaScript. More...
 
virtual void RemoveExposedArray (void *array)=0
 Remove exposed array from JavaScript. More...
 
virtual bool IsReadyForBindings () const =0
 Checks whether the coherent.js bindings are initialized and ready to use. More...
 
virtual void ExecuteScript (const char *script, const char *frameSelector=nullptr)=0
 Execute arbitrary JavaScript code in a given frame in the page. By default the code will be executed inside the main frame but you can specify a CSS selector to any iframe in the page. More...
 
template<typename T >
ModelHandle CreateModel (const char *name, T *model, Binder::BindingMode mode=Binder::BindingMode::BM_ScopedUnsafe)
 Creates a model for binding. More...
 
template<typename T >
void UpdateWholeModel (T *model)
 Marks a model as dirty. Properties will be synchronized using the View::SynchronizeModels call. More...
 
template<typename T >
void UpdateModelProperty (T *model, Property *prop)
 Marks a model's property as dirty. The property will be synchronized using the View::SynchronizeModels call. More...
 
template<typename T >
void UpdateModelArrayPropertyIndex (T *model, Property *prop, size_t index)
 Marks a model's item at a specified index for a given property as dirty. The property will be synchronized using the View::SynchronizeModels call. More...
 
virtual void SetZoom (ZoomType type, float value)=0
 Sets the zoom value of the view. More...
 
virtual float GetZoom (ZoomType type)=0
 Returns the current zoom level for the given zoom type. More...
 
virtual void RegisterModel (const char *name, void *model)=0
 Registers a model with a given name. More...
 
template<typename T >
ComponentHandle InstantiateComponent (const char *name, const char *selector, T *model=nullptr)
 Instantiates data binding component. More...
 
virtual void RemoveInstantiateComponent (ComponentHandle instance)=0
 Removes an instance of a data binding component. More...
 
template<typename T >
void UnregisterModel (T *model)
 Unregisters a model. More...
 
virtual void SynchronizeModels ()=0
 Applies the changes accumulated by View::UpdateWholeModel and View::UpdateModelProperty to the corresponding JavaScript objects.
 
template<typename T >
const char * GetModelTypename (T *model)
 Gets tye typename for a given model. More...
 
template<typename T >
TypeInfo * CoherentGetTypeInfo (T *model)
 
Triggering events

These overloads trigger an event in JavaScript with the supplied arguments

virtual void TriggerEvent (const char *name)=0
 Triggers a UI event.
 
template<typename T1 >
void TriggerEvent (const char *name, const T1 &argument1)
 Triggers a UI event.
 
template<typename T1 , typename T2 >
void TriggerEvent (const char *name, const T1 &argument1, const T2 &argument2)
 Triggers a UI event.
 
template<typename T1 , typename T2 , typename T3 >
void TriggerEvent (const char *name, const T1 &argument1, const T2 &argument2, const T3 &argument3)
 Triggers a UI event.
 
template<typename T1 , typename T2 , typename T3 , typename T4 >
void TriggerEvent (const char *name, const T1 &argument1, const T2 &argument2, const T3 &argument3, const T4 &argument4)
 Triggers a UI event.
 
template<typename T1 , typename T2 , typename T3 , typename T4 , typename T5 >
void TriggerEvent (const char *name, const T1 &argument1, const T2 &argument2, const T3 &argument3, const T4 &argument4, const T5 &argument5)
 Triggers a UI event.
 
template<typename T1 , typename T2 , typename T3 , typename T4 , typename T5 , typename T6 >
void TriggerEvent (const char *name, const T1 &argument1, const T2 &argument2, const T3 &argument3, const T4 &argument4, const T5 &argument5, const T6 &argument6)
 Triggers a UI event.
 
template<typename T1 , typename T2 , typename T3 , typename T4 , typename T5 , typename T6 , typename T7 >
void TriggerEvent (const char *name, const T1 &argument1, const T2 &argument2, const T3 &argument3, const T4 &argument4, const T5 &argument5, const T6 &argument6, const T7 &argument7)
 Triggers a UI event.
 
template<typename T1 , typename T2 , typename T3 , typename T4 , typename T5 , typename T6 , typename T7 , typename T8 >
void TriggerEvent (const char *name, const T1 &argument1, const T2 &argument2, const T3 &argument3, const T4 &argument4, const T5 &argument5, const T6 &argument6, const T7 &argument7, const T8 &argument8)
 Triggers a UI event.
 

Detailed Description

Class that encapsulates a UI View (an HTML5 page and JS context) Provides all manipulation and query functions for the view.

Note
all methods MUST be called from the main UI thread

Member Function Documentation

◆ AuditPerformance()

virtual void Coherent::UIGT::View::AuditPerformance ( bool  shouldDisplayOnScreen = false,
const char *  frameSelector = nullptr 
)
pure virtual

Executes an auditing script that detects sub-optimal parts of your UI and reports them on screen and via ViewListener::OnPerformanceAudit. By default the main frame will be audited but you can specify a CSS selector to any iframe in the page.

Warning
ViewListener::OnPerformanceAudit won't be called if coherent.js is missing OR if auditing an iframe (frameSelector != nullptr). Specify shouldDisplayOnScreen as true to see the results on screen.
Parameters
shouldDisplayOnScreenwhether to display the resulting report as an overlay on the page
frameSelectorCSS selector to the target iframe. Leave nullptr if for the main frame.

◆ BeginCaptureDebugFrame()

virtual void Coherent::UIGT::View::BeginCaptureDebugFrame ( void *  userData,
FrameCaptureCallback  callback 
)
pure virtual

Will begin serializing every rendered frame to a memory blob which will be passed in the callback. The saved frames can be inspected for debug purposes.

Warning
the option must be used only for debug and performance measurements. It slows down the application significantly.
Parameters
userDataopaque pointer which will be passed in the callback
callbackPointer to function which will be called with the serialized data. The callback will be called on the Main thread.
Note
callback will be called in the Main thread when in non-async mode and in UI thread in async mode
Call Release() on the FrameCapture object to release the memory allocated for the data.

◆ BindCall()

virtual BoundEventHandle Coherent::UIGT::View::BindCall ( const char *  name,
IEventHandler *  handler 
)
pure virtual

Expose C++ handler to be called from UI.

Parameters
namename for the handler in the UI
handlerhandler to be executed
Returns
bound handle so the handler can be unbound later
Note
BindCall takes ownership of the handler

◆ CanGoBack()

virtual bool Coherent::UIGT::View::CanGoBack ( ) const
pure virtual

Tells if the View can go back in history.

Returns
true if there's a URL to go back to
Warning
Do not use it in asynchronous mode. It is not thread safe.

◆ CanGoForward()

virtual bool Coherent::UIGT::View::CanGoForward ( ) const
pure virtual

Tells if the View can go forward in history.

Returns
true if there's a URL to go forward to
Warning
Do not use it in asynchronous mode. It is not thread safe.

◆ CaptureSingleDebugFrame()

virtual void Coherent::UIGT::View::CaptureSingleDebugFrame ( void *  userData,
FrameCaptureCallback  callback 
)
pure virtual

Will serialize next rendered frame to a memory blob which will be passed in the callback. The saved frames can be inspected for debug purposes. This will force redraw of the whole UI for the frame.

Warning
the option must be used only for debug and performance measurements. It slows down the application significantly.
Parameters
userDataopaque pointer which will be passed in the callback
callbackPointer to function which will be called with the serialized data. The callback will be called on the Main thread.
Note
callback will be called in the Main thread when in non-async mode and in UI thread in async mode
Call Release() on the FrameCapture object to release the memory allocated for the data.

◆ CoherentGetTypeInfo()

template<typename T >
TypeInfo* Coherent::UIGT::View::CoherentGetTypeInfo ( T *  model)
inline
Parameters
modelthe model which would be checked for existing TypeInfo
Warning
If there is no registerd type for the model result would be nullptr
Returns
a TypeInfo for T

◆ CookiesEnabled()

virtual bool Coherent::UIGT::View::CookiesEnabled ( ) const
pure virtual

Tells if cookies are enabled for this View.

Returns
true if cookies are enabled
Warning
Do not use it in asynchronous mode. It is not thread safe.

◆ CreateModel()

template<typename T >
ModelHandle Coherent::UIGT::View::CreateModel ( const char *  name,
T *  model,
Binder::BindingMode  mode = Binder::BindingMode::BM_ScopedUnsafe 
)
inline

Creates a model for binding.

Parameters
namethe name for the model
modelpointer to the object used as model
Returns
a handle for the created model
Warning
The object will be accessed on the UI thread in asynchronous mode when using BM_ScopedUnsafe mode
Note
: When using the BM_Scoped mode, method of the C++ object will not be accessible to JavaScript

◆ Destroy()

virtual void Coherent::UIGT::View::Destroy ( )
pure virtual

Destroys this view.

Warning
After a call to Destroy calling any method results in undefined behavior
This method is ALWAYS synchronous

◆ EnableOnScreenPerformanceInfo()

virtual void Coherent::UIGT::View::EnableOnScreenPerformanceInfo ( bool  enable,
unsigned  x = 0u,
unsigned  y = 0u 
)
pure virtual

Will display performance information on-screen. Enabling this option will also force compositing mode on the View.

Parameters
enableWhether to enable or disable the perf info.
xScreen x (in pixels) position of the performance info.
yScreen y (in pixels) position of the performance info.

◆ ExecuteJSTimers()

virtual void Coherent::UIGT::View::ExecuteJSTimers ( )
pure virtual

Executes all JS timers (setTimeout/requestAnimationFrame) for the View.

Note
You must always call in turn ExecuteJSTimers(), UpdateStylesAndLayout() and RecordRenderingCommands(). The functions are split for easier profiling. You can also call just "Layout" that internally calls all of them.

◆ ExecuteScript()

virtual void Coherent::UIGT::View::ExecuteScript ( const char *  script,
const char *  frameSelector = nullptr 
)
pure virtual

Execute arbitrary JavaScript code in a given frame in the page. By default the code will be executed inside the main frame but you can specify a CSS selector to any iframe in the page.

Parameters
scriptcode to be evaluated in the context of the main frame of the view
frameSelectorCSS selector to the target iframe. Leave nullptr if for the main frame.

◆ ExposeAsGlobal()

template<typename T >
void Coherent::UIGT::View::ExposeAsGlobal ( const char *  name,
T *  object,
Binder::BindingMode  mode = Binder::BindingMode::BM_ScopedUnsafe 
)
inline

Expose object as global variable.

Parameters
namename of the global variable
objectthe instance of the global variable
Warning
The object will be accessed on the UI thread in asynchronous mode when using BM_ScopedUnsafe mode
Note
: When using the BM_Scoped mode, method of the C++ object will not be accessible to JavaScript

◆ GetAnimationFrameDefer()

virtual float Coherent::UIGT::View::GetAnimationFrameDefer ( ) const
pure virtual

Returns the minimum delay between animation frames in seconds.

Returns
the minimum delay

◆ GetCacheBytesStats()

virtual void Coherent::UIGT::View::GetCacheBytesStats ( InternalCaches  cache,
unsigned &  filled,
unsigned &  capacity 
)
pure virtual

Get info about the bytes statistic of a particular internal cache.

Warning
only the ICACHE_Textures and the ICACHE_ScratchLayerTextures have the bytes statistic
Parameters
cachespecifies for which cache to return the info about the bytes statistic
filledbytes in the cache
capacitymaximum bytes that the cache can contain
Warning
Do not use it in asynchronous mode. It is not thread safe.

◆ GetCacheCountStats()

virtual void Coherent::UIGT::View::GetCacheCountStats ( InternalCaches  cache,
unsigned &  filled,
unsigned &  capacity 
)
pure virtual

Get info about the number of objects statistic of a particular internal cache.

Warning
the ICACHE_ScratchLayerTextures doesn't currently have the count statistic
Parameters
cachespecifies for which cache to return the info about the count statistic
fillednumber of existing objects in the cache
capacitymaximum number of objects that can coexist in the cache
Warning
Do not use it in asynchronous mode. It is not thread safe.

◆ GetClickThroughAlphaThreshold()

virtual float Coherent::UIGT::View::GetClickThroughAlphaThreshold ( ) const
pure virtual

Get the currently set alpha threshold for click-through queries.

Returns
the currently set alpha threshold

◆ GetHeight()

virtual unsigned Coherent::UIGT::View::GetHeight ( )
pure virtual

Gets the height of the View.

Returns
the height of the View

◆ GetId()

virtual unsigned Coherent::UIGT::View::GetId ( ) const
pure virtual

Returns a unique id of the View.

Returns
the id of the View

◆ GetInputGroupUnderCoordinates()

virtual const char* Coherent::UIGT::View::GetInputGroupUnderCoordinates ( float  normX,
float  normY 
) const
pure virtual

Gets the value of the data-input-group attribute of the element under the given mouse coordinates. If the element does not have the attribute, it will return the value of the attribute of the first ancestor that has it. Useful when you need to customize mouse queries and need extra data besides whether the mouse is on the view.

Parameters
normXthe x coordinate of the point in the normalized space of the view [0..1]
normYthe y coordinate of the point in the normalized space of the view [0..1]
Returns
the value of the data-input-group attribute of the element under the given mouse coordinates or null if no ancestor has the attribute
Warning
the pointer is valid until the next call to the method
Do not use it in asynchronous mode. It is not thread safe.
Note
Under async mode, this method will return the value from the last query. This makes it behave like IssueMouseQuery / FetchMouseQuery. Use UISystem::WaitFor if you need immediate result.

◆ GetLastLoadedURL()

virtual const char* Coherent::UIGT::View::GetLastLoadedURL ( ) const
pure virtual

Returns the last loaded URL by the View.

Returns
the last URL loaded by the view, UTF8 encoded
Warning
Do not use it in asynchronous mode. It is not thread safe.

◆ GetModelTypename()

template<typename T >
const char* Coherent::UIGT::View::GetModelTypename ( T *  model)
inline

Gets tye typename for a given model.

Parameters
modelthe model pointer
Returns
the typename for a given model, or null if the model is not found
Warning
Do not use it in asynchronous mode. It is not thread safe.

◆ GetOffscreenCanvasRendering()

virtual bool Coherent::UIGT::View::GetOffscreenCanvasRendering ( ) const
pure virtual

Returns offscreen canvas command execution mode.

Returns
true if offscreen canvas command execition is forced every frame, false if command execution is deferred until the canvas is visible

◆ GetTitle()

virtual const char* Coherent::UIGT::View::GetTitle ( ) const
pure virtual

Gets the "<title>" of the View.

Warning
the pointer is valid until the next change to the title which may happen during Layout / TriggerEVent or UISystem::Advance
Returns
the title of the View
Warning
Do not use it in asynchronous mode. It is not thread safe.

◆ GetWidth()

virtual unsigned Coherent::UIGT::View::GetWidth ( )
pure virtual

Gets the width of the View.

Returns
the width of the View

◆ GetZoom()

virtual float Coherent::UIGT::View::GetZoom ( ZoomType  type)
pure virtual

Returns the current zoom level for the given zoom type.

Parameters
typethe type of zoom for which the values is returned.
Returns
the current zoom level for the specified ZoomType
Warning
Do not use it in asynchronous mode. It is not thread safe.

◆ GoBack()

virtual bool Coherent::UIGT::View::GoBack ( )
pure virtual

Goes back in the View history.

Warning
This method is ALWAYS synchronous
Returns
the outcome of the operation (true if the operation completes successfully)
Warning
Do not use it in asynchronous mode. It is not thread safe.

◆ GoForward()

virtual bool Coherent::UIGT::View::GoForward ( )
pure virtual

Goes forward in the View history.

Warning
This method is ALWAYS synchronous
Returns
the outcome of the operation (true if the operation completes successfully)
Warning
Do not use it in asynchronous mode. It is not thread safe.

◆ HasLastLayoutCompleted()

virtual bool Coherent::UIGT::View::HasLastLayoutCompleted ( )
pure virtual

Checks whether the last issued Layout operation has completed.

Note
the single Layout call and the group of ExecuteJSTimers, UpdateStylesAndLayout and RecordRenderingCommands are both referred to as "Layout operation".
Returns
true for a synchronous UI System, or if the last Layout operation has completed for an async UI System. Returns false If the last Layout operation is still being processed in an async UI System and a new Layout operation would block waiting for the last one to complete.

◆ IMECancelComposition()

virtual bool Coherent::UIGT::View::IMECancelComposition ( )
pure virtual

Cancels the current IME composition.

Returns
the outcome of the operation (will fail if IME is inactive for this view)
Warning
This method is ALWAYS synchronous

◆ IMEConfirmComposition()

virtual bool Coherent::UIGT::View::IMEConfirmComposition ( const char *  composition)
pure virtual

Confirms the current IME composition.

Parameters
compositionthe string to confirm
Returns
the outcome of the operation (will fail if IME is inactive for this view)
Warning
This method is ALWAYS synchronous

◆ IMESetComposition()

virtual bool Coherent::UIGT::View::IMESetComposition ( const char *  composition,
unsigned  cursorPos,
unsigned  targetStart,
unsigned  targetEnd 
)
pure virtual

Updates the internal state of the IME composition in the View.

Parameters
compositionthe composition string so far
cursorPosthe cursor position in the composition
targetStartthe index at the start of the selection
targetEndthe index at the end of the selection
Returns
the outcome of the operation (will fail if IME is inactive for this view)
Warning
This method is ALWAYS synchronous

◆ InspectorTimelineBeginEvent()

virtual void Coherent::UIGT::View::InspectorTimelineBeginEvent ( const char *  name)
pure virtual

Marks the beginning of an event in the Inspector timeline. Events must be 'ended' with InspectorTimelineEndEvent to get a measure of their duration.

Parameters
namethe 'name' of the event that will be displayed in the Timeline

◆ InspectorTimelineEndEvent()

virtual void Coherent::UIGT::View::InspectorTimelineEndEvent ( const char *  name)
pure virtual

Marks the end of an event in the Inspector timeline.

Parameters
namethe 'name' of the event that will be displayed in the Timeline

◆ InstantiateComponent()

template<typename T >
ComponentHandle Coherent::UIGT::View::InstantiateComponent ( const char *  name,
const char *  selector,
T *  model = nullptr 
)
inline

Instantiates data binding component.

Parameters
nameThe name of the component.
selectorThe element selector is a pattern used to select HTML elements based on their id, classes, types, attributes, values of attributes, etc.
modelpointer to the object used as model
Returns
handle to the component used for its removal

◆ IsDocumentReady()

virtual bool Coherent::UIGT::View::IsDocumentReady ( ) const
pure virtual

Tells if the Document object is ready in JS.

Returns
true if the document has been loaded. Equivalent to the document load event in JS.

◆ IsMouseOnView()

virtual bool Coherent::UIGT::View::IsMouseOnView ( )
pure virtual

Checks if the mouse is currently on the logical view (a part of the view that has elements on it) or not (click-through). Uses the coordinates last set in IssueMouseOnUIQuery.

Warning
Calling the method while a query is in-flight (between a call to IssueMouseOnUIQuery and FetchMouseOnUIQuery) returns the result of the last successful query
Returns
true if the mouse is on the view

◆ IsReadyForBindings()

virtual bool Coherent::UIGT::View::IsReadyForBindings ( ) const
pure virtual

Checks whether the coherent.js bindings are initialized and ready to use.

Returns
true, if the view is ready to accept JavaScript bindings, false otherwise.
Warning
Do not use it in asynchronous mode. It is not thread safe.

◆ IsTransparent()

virtual bool Coherent::UIGT::View::IsTransparent ( ) const
pure virtual

Tells if this view is transparent or not.

Returns
true if the view is transparent

◆ KeyEvent()

virtual void Coherent::UIGT::View::KeyEvent ( const Coherent::UIGT::KeyEventData event)
pure virtual

Sends a key event to the UI renderer.

Parameters
eventthe key event

◆ Layout()

virtual unsigned Coherent::UIGT::View::Layout ( )
pure virtual

Layouts the content of the page. You should call this method each frame after calling Advance on the UI system.

Note
this method actually does 3 things - executes all JS timers for this frame (setTimeout/requestAnimationFrame), updates styles and the page layout, records rendering commands that will later be replayed in the ViewRenderer::Paint command.
this method is equivalent to calling in turn ExecuteJSTimers(), UpdateStylesAndLayout() and RecordRenderingCommands(). You can choose to call the individual functions to get a more clear picture of the times they take during profiling.
Returns
the id of the rendering commands recorded for this frame

◆ LoadURL()

virtual void Coherent::UIGT::View::LoadURL ( const char *  url,
ViewLoadPolicy  policy = VLP_UseCacheOrLoad 
)
pure virtual

Loads a new page in the View.

Parameters
urlthe url of the new page to load
policydefines if the View should use cached resources or reload everything from disk/server. The parameter is important during development with the 'coui' protocol. A resource might be modified but still available in the in-memory cache. In that case the View might use the cached version ignoring the cache. It's advisable to ignore the cache if loading a View that is being actively developed. In shipped builds always use the cache as it substantially improves load-speed and resources in shipped titles should be immutable.
Warning
This method is ALWAYS synchronous

◆ MouseEvent()

virtual void Coherent::UIGT::View::MouseEvent ( const Coherent::UIGT::MouseEventData event)
pure virtual

Sends a mouse event to the UI renderer.

Parameters
eventthe mouse event

◆ QueueClearCaches()

virtual void Coherent::UIGT::View::QueueClearCaches ( unsigned  caches)
pure virtual

Queue a task to clear an internal caches list.

Note
This takes effect at the next Layout/Paint cycle
Parameters
cachesa bit field listing all caches to clear

◆ QueueSetCacheBytesSize()

virtual void Coherent::UIGT::View::QueueSetCacheBytesSize ( InternalCaches  cache,
unsigned  capacity 
)
pure virtual

Queue task to set the maximum bytes allowed for internal cache.

Note
This takes effect at the next Layout/Paint cycle
Warning
only the ICACHE_Textures and the ICACHE_ScratchLayerTextures have the bytes statistic
Parameters
cachespecifies for which cache to set the count size
capacitymaximum bytes allowed in the cache

◆ QueueSetCacheCountSize()

virtual void Coherent::UIGT::View::QueueSetCacheCountSize ( InternalCaches  cache,
unsigned  capacity 
)
pure virtual

Queue task to set the maximum number of objects in internal cache.

Note
This takes effect at the next Layout/Paint cycle
Warning
the ICACHE_ScratchLayerTextures doesn't have this statistic
Parameters
cachespecifies for which cache to set the bytes size
capacitymaximum number of objects allowed in the cache

◆ RecordRenderingCommands()

virtual unsigned Coherent::UIGT::View::RecordRenderingCommands ( )
pure virtual

Records rendering commands that will later be replayed in the "Paint(frameId)" method.

Note
You must always call in turn ExecuteJSTimers(), UpdateStylesAndLayout() and RecordRenderingCommands(). The functions are split for easier profiling. You can also call just "Layout" that internally calls all of them.
Returns
the id of the rendering commands recorded for this frame

◆ RegisterForEvent()

virtual BoundEventHandle Coherent::UIGT::View::RegisterForEvent ( const char *  name,
IEventHandler *  handler 
)
pure virtual

Expose C++ handler to be called when a specific event occurs.

Parameters
namename of the event
handlerhandler to be executed
Returns
bound handle so the handler can be unregistered
Note
RegisterForEvent takes ownership of the handler

◆ RegisterModel()

virtual void Coherent::UIGT::View::RegisterModel ( const char *  name,
void *  model 
)
pure virtual

Registers a model with a given name.

Parameters
namethe name of the model
modelthe model pointer
Warning
FOR INTERNAL USE ONLY. DO NOT USE DIRECTLY!

◆ RemoveExposedArray()

virtual void Coherent::UIGT::View::RemoveExposedArray ( void *  array)
pure virtual

Remove exposed array from JavaScript.

Parameters
arrayexposed array to be removed
Warning
This function is asynchronous in asynchronous mode. Use events between the JavaScript and C++ code for make sure that the JavaScript is no longer using the instance.

◆ RemoveExposedInstance()

template<typename T >
void Coherent::UIGT::View::RemoveExposedInstance ( T *  object)
inline

Remove exposed object from JavaScript.

Parameters
objectexposed object to be removed
Warning
This function is asynchronous in asynchronous mode. Use events between the JavaScript and C++ code for make sure that the JavaScript is no longer using the instance.

◆ RemoveInstantiateComponent()

virtual void Coherent::UIGT::View::RemoveInstantiateComponent ( ComponentHandle  instance)
pure virtual

Removes an instance of a data binding component.

Parameters
instanceThe instance handle given from InstantiateComponent.

◆ Resize()

virtual void Coherent::UIGT::View::Resize ( int  width,
int  height 
)
pure virtual

Resizes the View contents.

Note
You must also update the texture for the ViewRenderer with the SetRenderTarget method
Parameters
widththe new width of the View
heightthe new height of the View

◆ SetAnimationFrameDefer()

virtual void Coherent::UIGT::View::SetAnimationFrameDefer ( float  valueSec)
pure virtual

Sets the minimum delay between animation frames in seconds.

Parameters
valueSecthe minimum delay

◆ SetClickThroughAlphaThreshold()

virtual void Coherent::UIGT::View::SetClickThroughAlphaThreshold ( float  threshold)
pure virtual

The alpha value of the pixels is used to determine if the mouse is on an element or on the background (click-through). All pixels below or equal to the alpha threshold (default = 0) are marked as not-belonging to the View and IsMouseOnView for them return false.

Parameters
thresholdsets the new alpha threshold

◆ SetMediaType()

virtual void Coherent::UIGT::View::SetMediaType ( MediaType  type)
pure virtual

Change the media type of the view.

Parameters
typethe type of media we want to change to

◆ SetOffscreenCanvasRendering()

virtual void Coherent::UIGT::View::SetOffscreenCanvasRendering ( bool  force)
pure virtual

Sets the offscreen canvas command execution mode.

Parameters
forcewhether to force execute canvas commands every frame or to defer the execution until the canvas is visible

◆ SetScriptError()

virtual void Coherent::UIGT::View::SetScriptError ( ScriptCallErrorType  error,
const char *  message 
)
pure virtual

Sets an error for the currently executing handler.

Parameters
errorthe type of the error
messagethe error message

◆ SetZoom()

virtual void Coherent::UIGT::View::SetZoom ( ZoomType  type,
float  value 
)
pure virtual

Sets the zoom value of the view.

Parameters
typethe type of zoom for which the values is set.
valuevalue the value by which to zoom

◆ ShowLayerBorders()

virtual void Coherent::UIGT::View::ShowLayerBorders ( bool  show)
pure virtual

Will render the borders of the layers in the page.

Note
use for Debug purposes only as it decreases performance
Parameters
showwhether to show the layers' borders or not

◆ ShowPaintRects()

virtual void Coherent::UIGT::View::ShowPaintRects ( bool  show)
pure virtual

Will render the rects in the page that get re-drawn each frame.

Note
use for Debug purposes only as it decreases performance
Parameters
showwhether to show the paint rectangles or not

◆ StopLoading()

virtual void Coherent::UIGT::View::StopLoading ( )
pure virtual

Interrupts the loading process of the View.

Warning
This method is ALWAYS synchronous

◆ UnbindCall()

virtual void Coherent::UIGT::View::UnbindCall ( BoundEventHandle  handle)
pure virtual

Remove a bound C++ handler.

Parameters
handlethe handle of the handler to be unbound
Warning
Unbinding a handler inside the handler callback is not supported and will result in undefined behavior

◆ UnbindObject()

virtual void Coherent::UIGT::View::UnbindObject ( const void *  object)
pure virtual

Remove all handlers bound to a specific object.

Parameters
objectthe object whose handlers will be removed
Warning
Unbinding the object inside the handler callback is not supported and will result in undefined behavior

◆ UnregisterFromEvent()

virtual void Coherent::UIGT::View::UnregisterFromEvent ( BoundEventHandle  handle)
pure virtual

Remove a registered C++ handler.

Parameters
handlethe handle of the event handler to be unregistered
Warning
Unregistering a handler inside the handler callback is not supported and will result in undefined behavior

◆ UnregisterModel()

template<typename T >
void Coherent::UIGT::View::UnregisterModel ( T *  model)
inline

Unregisters a model.

Parameters
modelthe model to be unregistered.

◆ UpdateModelArrayPropertyIndex()

template<typename T >
void Coherent::UIGT::View::UpdateModelArrayPropertyIndex ( T *  model,
Property *  prop,
size_t  index 
)
inline

Marks a model's item at a specified index for a given property as dirty. The property will be synchronized using the View::SynchronizeModels call.

Parameters
modelthe model instance whose property will be marked as dirty
propthe array property containing the item to be dirtified
indexthe index of the item within the array property that will be marked as dirty

◆ UpdateModelProperty()

template<typename T >
void Coherent::UIGT::View::UpdateModelProperty ( T *  model,
Property *  prop 
)
inline

Marks a model's property as dirty. The property will be synchronized using the View::SynchronizeModels call.

Parameters
modelthe model instance whose property will be marked as dirty
propthe property to be marked as dirty

◆ UpdateStylesAndLayout()

virtual void Coherent::UIGT::View::UpdateStylesAndLayout ( )
pure virtual

Updates the styles of the View and performs an eventual re-layout of it.

Note
You must always call in turn ExecuteJSTimers(), UpdateStylesAndLayout() and RecordRenderingCommands(). The functions are split for easier profiling. You can also call just "Layout" that internally calls all of them.

◆ UpdateWholeModel()

template<typename T >
void Coherent::UIGT::View::UpdateWholeModel ( T *  model)
inline

Marks a model as dirty. Properties will be synchronized using the View::SynchronizeModels call.

Parameters
modelthe model to be marked as dirty