1.14.0.5
Hummingbird
A modern user interface library for games
cohtml::View Class Referenceabstract

The View represents a UI page with its DOM, styles and JavaScript context. Think of the View as a whole UI or UI element. The View for instance could be the whole HUD of a game. More...

Public Member Functions

virtual void Destroy ()=0
 Destorys the View. Should be called before the destruction of the System and Library.
 
virtual void LoadURL (const char *url)=0
 Loads a page in the View. More...
 
virtual void Reload ()=0
 Reloads the current page in the view.
 
virtual void UnloadDocument ()=0
 Unloads the HTML document. This will remove the entire DOM tree, so nothing will rendered but the view object will still be usable and another document might be loaded using View::LoadURL.
 
virtual unsigned Advance (TimePoint timeMilliseconds)=0
 Advances the internal timer of the View and runs all animations. If changes have happened in the page, this call will also trigger a new layout and render on the other threads. More...
 
virtual unsigned GetId () const =0
 Retuens the unique ID of the View.
 
virtual TaskFamilyId GetTaskFamilyId () const =0
 Returns the Task Family Id that can be used to schedule Layout work in an auxilliary thread.
 
virtual void Resize (unsigned width, unsigned height)=0
 Resizes the View contents. More...
 
virtual unsigned GetWidth () const =0
 Gets the View width.
 
virtual unsigned GetHeight () const =0
 Gets the View height.
 
virtual void ContinuousRepaint (bool enable)=0
 Debugging flag. This will cause the View to re-draw itself each frame. More...
 
virtual void ShowPaintRectangles (bool show)=0
 Debugging flag. This will cause the View show which parts of the texture are re-drawn each frame. More...
 
virtual void ShowElementAABBs (bool show)=0
 Debugging flag. This will cause the View to draw the bounding-boxes of all elements. More...
 
virtual DebugDumpDebugDumpDOMTree (unsigned flags)=0
 Debugging helper. Collects a comprehensive DOM structure dump.
 
virtual void TouchEvent (const cohtml::TouchEventData *events, unsigned count, bool *handled, void *userData)=0
 Sends a touch input event to the View. More...
 
virtual void GestureEvent (const cohtml::GestureEventData &event, bool *handled, void *userData)=0
 Sends a gesture input event to the View. More...
 
virtual void MouseEvent (const cohtml::MouseEventData &event, bool *handled, void *userData)=0
 Sends a mouse input event to the View. More...
 
virtual void KeyEvent (const cohtml::KeyEventData &event, bool *handled, void *userData)=0
 Sends a keyboard input event to the View. More...
 
virtual bool IMESetComposition (const char *composition, 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 SetUserAgent (const char *userAgent)=0
 Sets the User Agent string. 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. 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)
 Expose object as global variable. More...
 
virtual void DestroyExposedObject (void *object)=0
 Remove exposed object from JavaScript. More...
 
virtual bool IsReadyForBindings () const =0
 Checks whether the CoherentHummingbird.js bindings are initialized and ready to use. More...
 
virtual void ExecuteScript (const char *script)=0
 Execute arbitrary JavaScript code. This should be called only with a valid script context created. More...
 
virtual void AddInitialScript (const char *script)=0
 Schedules execution of JavaScript code on every page load. Can be called at any time. The scripts will be executed on the next page load in the same order they were added. More...
 
virtual void ResetInitialScripts ()=0
 Resets the list of initial scripts executed on every page load.
 
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.
 

Data-binding

Methods related to data-binding

typedef void(* CoherentInternalBindGenericFunc) (cohtml::Binder *, void *)
 
template<typename T >
void CreateModel (const char *name, T *model)
 Creates a model for binding. More...
 
virtual void UpdateWholeModel (void *model)=0
 Marks a model as dirty. Properties will be synchronized using the View::SynchronizeModels call. More...
 
virtual void SynchronizeModels ()=0
 Applies the changes accumulated by View::UpdateWholeModel and View::UpdateModelProperty to the corresponding JavaScript objects.
 
virtual void RegisterModel (const char *name, void *model, CoherentInternalBindGenericFunc func)=0
 Registers a model with a given name. More...
 
virtual void UnregisterModel (void *model)=0
 Unregisters a model. More...
 

Detailed Description

The View represents a UI page with its DOM, styles and JavaScript context. Think of the View as a whole UI or UI element. The View for instance could be the whole HUD of a game.

Member Function Documentation

◆ AddInitialScript()

virtual void cohtml::View::AddInitialScript ( const char *  script)
pure virtual

Schedules execution of JavaScript code on every page load. Can be called at any time. The scripts will be executed on the next page load in the same order they were added.

Parameters
scriptcode to be evaluated in the context of the main frame of the view

◆ Advance()

virtual unsigned cohtml::View::Advance ( TimePoint  timeMilliseconds)
pure virtual

Advances the internal timer of the View and runs all animations. If changes have happened in the page, this call will also trigger a new layout and render on the other threads.

Parameters
timeMillisecondsthe time in milliseconds since arbitrary point in time. The time must be monotonically increasing

◆ BeginCaptureDebugFrame()

virtual void cohtml::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.

Note
If you need to capture whole screen call ContinuousRepaint(true) to redraw the whole screen.
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
Call Release() on the FrameCapture object to release the memory allocated for the data.
callback will be called on the Main thread

◆ BindCall()

virtual BoundEventHandle cohtml::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

◆ CaptureSingleDebugFrame()

virtual void cohtml::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.

Note
If you need to capture whole screen call ContinuousRepaint(true) to redraw the whole screen.
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
Call Release() on the FrameCapture object to release the memory allocated for the data.
callback will be called on the Main thread

◆ ContinuousRepaint()

virtual void cohtml::View::ContinuousRepaint ( bool  enable)
pure virtual

Debugging flag. This will cause the View to re-draw itself each frame.

Parameters
enablewhether to enable the continuous repaint mode
Note
this flag will have a significant impact on performance. Use for debugging purposes ONLY.

◆ CreateModel()

template<typename T >
void cohtml::View::CreateModel ( const char *  name,
T *  model 
)
inline

Creates a model for binding.

Parameters
namethe name for the model
modelpointer to the object used as model (must be even aligned)

◆ DestroyExposedObject()

virtual void cohtml::View::DestroyExposedObject ( void *  object)
pure virtual

Remove exposed object from JavaScript.

Parameters
objectthe C++ object that to be removed from JavaScript

◆ ExecuteScript()

virtual void cohtml::View::ExecuteScript ( const char *  script)
pure virtual

Execute arbitrary JavaScript code. This should be called only with a valid script context created.

Parameters
scriptcode to be evaluated in the context of the main frame of the view

◆ ExposeAsGlobal()

template<typename T >
void cohtml::View::ExposeAsGlobal ( const char *  name,
T *  object 
)
inline

Expose object as global variable.

Parameters
namename of the global variable
objectthe instance for the global variable

◆ GestureEvent()

virtual void cohtml::View::GestureEvent ( const cohtml::GestureEventData event,
bool *  handled,
void *  userData 
)
pure virtual

Sends a gesture input event to the View.

Parameters
eventa gesture event
handleda boolean that indicates whether the event was handled by the UI. Can be nullptr.
userDataan opaque pointer passed to the ViewListener::OnNodeGestureEvent method. Can be nullptr.

◆ IMECancelComposition()

virtual bool cohtml::View::IMECancelComposition ( )
pure virtual

Cancels the current IME composition.

Returns
the outcome of the operation (will fail if IME is inactive for this view)

◆ IMEConfirmComposition()

virtual bool cohtml::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)

◆ IMESetComposition()

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

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

Parameters
compositionthe composition string so far
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)

◆ IsReadyForBindings()

virtual bool cohtml::View::IsReadyForBindings ( ) const
pure virtual

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

Returns
true, if the view is ready to accept JavaScript bindings, false otherwise.

◆ KeyEvent()

virtual void cohtml::View::KeyEvent ( const cohtml::KeyEventData event,
bool *  handled,
void *  userData 
)
pure virtual

Sends a keyboard input event to the View.

Parameters
eventa keyboard event
handleda boolean that indicates whether the event was handled by the UI. Can be nullptr.
userDataan opaque pointer passed to the ViewListener::OnNodeMouseEvent method. Can be nullptr.

◆ LoadURL()

virtual void cohtml::View::LoadURL ( const char *  url)
pure virtual

Loads a page in the View.

Parameters
urlA URL for the page to be loaded. Must be a valid URL. Spaces aren't allowed.

◆ MouseEvent()

virtual void cohtml::View::MouseEvent ( const cohtml::MouseEventData &  event,
bool *  handled,
void *  userData 
)
pure virtual

Sends a mouse input event to the View.

Parameters
eventa mouse event
handleda boolean that indicates whether the event was handled by the UI. Can be nullptr.
userDataan opaque pointer passed to the ViewListener::OnNodeMouseEvent method. Can be nullptr.

◆ RegisterForEvent()

virtual BoundEventHandle cohtml::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 cohtml::View::RegisterModel ( const char *  name,
void *  model,
CoherentInternalBindGenericFunc  func 
)
pure virtual

Registers a model with a given name.

Parameters
namethe name of the model
modelthe model pointer (must be even aligned)
funcoverload of CoherentBindInternal for the custom type
Warning
For internal use only. Use View::CreateModel to create a model, which wraps the usage of this internal method.

◆ Resize()

virtual void cohtml::View::Resize ( unsigned  width,
unsigned  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

◆ SetUserAgent()

virtual void cohtml::View::SetUserAgent ( const char *  userAgent)
pure virtual

Sets the User Agent string.

Parameters
userAgentthe user agent string

◆ ShowElementAABBs()

virtual void cohtml::View::ShowElementAABBs ( bool  show)
pure virtual

Debugging flag. This will cause the View to draw the bounding-boxes of all elements.

Parameters
showwhether to show the bounding-boxes of elements

◆ ShowPaintRectangles()

virtual void cohtml::View::ShowPaintRectangles ( bool  show)
pure virtual

Debugging flag. This will cause the View show which parts of the texture are re-drawn each frame.

Parameters
showwhether to show the paint rectangles

◆ TouchEvent()

virtual void cohtml::View::TouchEvent ( const cohtml::TouchEventData events,
unsigned  count,
bool *  handled,
void *  userData 
)
pure virtual

Sends a touch input event to the View.

Parameters
eventsan array of 'count' events
countthe count of events passed
handledan array of 'count' booleans indicating whether the events were handled by the UI. Can be nullptr.
userDataan opaque pointer passed to the ViewListener::OnNodeTouched method. Can be nullptr.

◆ UnbindCall()

virtual void cohtml::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 cohtml::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 cohtml::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()

virtual void cohtml::View::UnregisterModel ( void *  model)
pure virtual

Unregisters a model.

Parameters
modelthe model to be unregistered.

◆ UpdateWholeModel()

virtual void cohtml::View::UpdateWholeModel ( void *  model)
pure virtual

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

Parameters
modelthe model to be marked as dirty