Class that encapsulates a UI View Provides all manipulation and query functions for the view. More...

#include <Coherent/UI/View.h>

Inheritance diagram for Coherent::UI::View:

Public Member Functions
virtual ViewContext *	GetContext () const =0
	Get the view context. More...

virtual ViewType	GetViewType ()=0
	Get the type of the view. More...

virtual void	Destroy ()=0
	Destroys this view. More...

virtual void	SetFocus ()=0
	Sets this view on focus.

virtual void	KillFocus ()=0
	Removes the focus from this view.

virtual void	MouseEvent (const MouseEventData &event)=0
	Sends a mouse event to the UI renderer. More...

virtual void	KeyEvent (const KeyEventData &event)=0
	Sends a key event to the UI renderer. More...

virtual void	TouchEvent (const TouchEventData *events, unsigned count)=0
	Sends a touch event to the UI renderer. More...

virtual void	MouseActivate ()=0
	Sends a mouse event to the UI renderer.

virtual int	GetWidth () const =0
	Gets the width of the View. More...

virtual int	GetHeight () const =0
	Gets the height of the View. More...

virtual void	Resize (unsigned width, unsigned height)=0
	Send a resize event to the UI renderer. More...

virtual void	IssueMouseOnUIQuery (float normX, float normY)=0
	Issues a query on the View to check of the mouse is on the user interface or not. More...

virtual ViewErrorType	HasMouseQueryFinished ()=0
	Returns the status of the mouse query. More...

virtual void	FetchMouseOnUIQuery ()=0
	Ends a mouse-on-UI query. Waits for the result. 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	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 void	SetTargetFramerate (int target)=0
	Sets the target frame-rate for the View. The View's rendering will never exceed the target frame-rate. It also will never exceed the frame-rate set when initializing the view. (available only in Full versions of Coherent UI) More...

virtual int	GetTargetFramerate () const =0
	Get the currently set target frame-rate for the View. More...

virtual bool	IsOnDemand () const =0
	Tells if this is an on-demand view. Frames must be explicitly requested for on-demand views (available only in Full versions of Coherent UI) More...

virtual ViewErrorType	RequestFrame ()=0
	Requests a new frame for rendering. All triggered events before this call will be accounted for in the rendered view. Only one frame per-view could be requested simultaneously (available only in Full versions of Coherent UI) More...

virtual ViewErrorType	RequestFrame (double timeSinceArbitraryMoment)=0
	Requests a new frame for rendering. All triggered events before this call will be accounted for in the rendered view. Only one frame per-view could be requested simultaneously (available only in Full versions of Coherent UI) This function can be called from a thread different than the main UI context thread in order to support client applications with multi-threaded rendering. More...

virtual ViewErrorType	PeekFrameReady ()=0
	Tells if the last requested frame is ready or not. Does not block. This call must always be made between calls to RequestFrame and FetchSurface. (available only in Full versions of Coherent UI) This function can be called from a thread different than the main UI context thread in order to support client applications with multi-threaded rendering. More...

virtual ViewErrorType	FetchSurface ()=0
	Returns the requested surface. Works only for on-demand views. All buffered view should use the context's FetchSurfaces method. This call will block until the surface is ready. (available only in Full versions of Coherent UI) This function can be called from a thread different than the main UI context thread in order to support client applications with multi-threaded rendering. More...

virtual ViewErrorType	DrawSurface ()=0
	[EXPERIMENTAL - DO NOT USE]

virtual bool	UsesSharedMemory () const =0
	Tells if this view uses shared memory for image transport. More...

virtual bool	IsTransparent () const =0
	Tells if this view is transparent or not. More...

virtual bool	SupportsClickThrough () const =0
	Tells if this view supports click-through queries or not. More...

virtual void	Redraw () const =0
	Request a redraw of the current view.

virtual void	DownloadUrl (const wchar_t *path)=0
	Initiates a download request on the specified path.

virtual void	Load (const wchar_t *path)=0
	Loads a new path in the View. More...

virtual void	Reload (bool ignoreCache)=0
	Reloads the last requested or navigated-to path. More...

virtual const wchar_t *	GetCurentViewPath () const =0
	Get the last requested or navigated-to path. More...

virtual const wchar_t *	GetLastRequestedPath () const =0
	Get the last requested path to load for the View. More...

virtual const wchar_t *	GetLastLoadedPath () const =0
	Get the last successfully loaded path for the View. More...

virtual const wchar_t *	GetLastFailedPath () const =0
	Get the last failed path for the View. 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...

virtual void	ExecuteScript (const char *script)=0
	Execute arbitrary JavaScript code. More...

virtual void	ReplyToJavaScriptMessage (bool success, const char *userInput) const =0
	Sends a reply to a javascript message triggered for the view. More...

virtual void	AuthCredentialsResponse (const wchar_t username, const wchar_t password, bool success) const =0
	Sends credentials for a pending authentication request for the view. More...

virtual void	SetScriptError (ScriptCallErrorType error, const char *message)=0
	Sets an error for the currently executing handler. More...

virtual void	InterceptURLRequests (bool intercept)=0
	Controls intercepting URL requests. For each request `ViewListener::OnURLRequest` will be called. More...

virtual void	IMEActivate (bool active)=0
	Sets if the View should notify the client about IME-related events and if it will process IME messages. More...

virtual bool	IMEIsActive () const =0
	Tells if IME events are currently active for this view. More...

virtual bool	IMESetComposition (const wchar_t *composition, unsigned cursorPos, unsigned targetStart, unsigned targetEnd)=0
	Updates the internal state of the IME composition in the View. More...

virtual bool	IMEConfirmComposition (const wchar_t *composition)=0
	Confirms the current IME composition. More...

virtual bool	IMECancelComposition ()=0
	Cancels the current IME composition. More...

virtual ImageData *	CreateImageData (const char name, int width, int height, void data, bool flipY)=0
	Create an ImageData object in the View that can be updated fast from the client application itself. More...

virtual int	GetAudioData (int streamId, void *buffer, int bufferSize, int timeoutMs)=0
	Obtains audio data for the specified stream in the current view and copies it into the client-provided buffer. More...

virtual void	SetZoomLevel (double zoomLevel)=0
	Sets the page zoom level. Specifying 0.0 will reset to the default zoom level. More...

virtual void	SetMasterVolume (double volume)=0
	Sets the master volume for all audio and video streams. More...

Triggering events
These overloads trigger an event in JavaScript with the supplied arguments
virtual void	TriggerEvent (const char *eventName)=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.

Detailed Description

Class that encapsulates a UI View Provides all manipulation and query functions for the view.

Member Function Documentation

virtual void Coherent::UI::View::AuthCredentialsResponse	(	const wchar_t *	username,
		const wchar_t *	password,
		bool	success
	)		const

pure virtual

Sends credentials for a pending authentication request for the view.

Parameters

username	the username
password	the password
success	defines whether the response is valid, i.e. if the request should be answered or canceled

See Also: ViewListener::OnGetAuthCredentials

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

pure virtual

Expose C++ handler to be called from UI.

Parameters

name	name for the handler in the UI
handler	handler to be executed

Returns: bound handle so the handler can be unbound later

Note: BindCall takes ownership of the handler

virtual ImageData* Coherent::UI::View::CreateImageData	(	const char *	name,
		int	width,
		int	height,
		void *	data,
		bool	flipY
	)

pure virtual

Create an ImageData object in the View that can be updated fast from the client application itself.

Parameters

name	the name of the image data object
width	the width of the image
height	the height of the image
data	initial data to fill the image data with
flipY	flips vertically the content of the source image

Returns: the image data object created in the DOM of this View

virtual void Coherent::UI::View::Destroy ( )

pure virtual

Destroys this view.

Warning: After a call to Destroy calling any other method except the destructor results in undefined behavior

virtual void Coherent::UI::View::ExecuteScript ( const char * script )

pure virtual

Execute arbitrary JavaScript code.

Parameters

script code to be evaluated in the context of the main frame of the view

virtual void Coherent::UI::View::FetchMouseOnUIQuery ( )

pure virtual

Ends a mouse-on-UI query. Waits for the result.

Note: Should be called as far apart from IssueMouseOnUIQuery in order to maximize the chances that the query has finished at the time of this call and no waiting will be performed

virtual ViewErrorType Coherent::UI::View::FetchSurface ( )

pure virtual

Returns the requested surface. Works only for on-demand views. All buffered view should use the context's FetchSurfaces method. This call will block until the surface is ready. (available only in Full versions of Coherent UI) This function can be called from a thread different than the main UI context thread in order to support client applications with multi-threaded rendering.

Returns: the outcome of the operation

virtual int Coherent::UI::View::GetAudioData	(	int	streamId,
		void *	buffer,
		int	bufferSize,
		int	timeoutMs
	)

pure virtual

Obtains audio data for the specified stream in the current view and copies it into the client-provided buffer.

Parameters

streamId	the stream for which to get PCM data
buffer	the client buffer into which the data is copied
bufferSize	the size of the client buffer
timeoutMs	the timeout in milliseconds to wait for audio data. Use 0 to wait indefinitely.

Note: the data is copied in the format which the stream reported in Coherent::UI::ViewListener::OnAudioStreamCreated; the current maximum buffer size is set to 16KB. The client is guaranteed to receive at most that much data.

Returns: the actual number of bytes read. A negative number is returned if the stream is exhausted or does not exist.

virtual float Coherent::UI::View::GetClickThroughAlphaThreshold ( ) const

pure virtual

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

Returns: the currently set alpha threshold

virtual ViewContext* Coherent::UI::View::GetContext ( ) const

pure virtual

Get the view context.

Returns: pointer to the view context used for creating this view

virtual const wchar_t* Coherent::UI::View::GetCurentViewPath ( ) const

pure virtual

Get the last requested or navigated-to path.

Returns: the path as null-terminated string

virtual int Coherent::UI::View::GetHeight ( ) const

pure virtual

Gets the height of the View.

Returns: the height of the View

virtual const wchar_t* Coherent::UI::View::GetLastFailedPath ( ) const

pure virtual

Get the last failed path for the View.

Returns: the path as null-terminated string

Warning: the pointer is guaranteed to be valid only until the next UI Context update

virtual const wchar_t* Coherent::UI::View::GetLastLoadedPath ( ) const

pure virtual

Get the last successfully loaded path for the View.

Returns: the path as null-terminated string

Warning: the pointer is guaranteed to be valid only until the next UI Context update

virtual const wchar_t* Coherent::UI::View::GetLastRequestedPath ( ) const

pure virtual

Get the last requested path to load for the View.

Returns: the path as null-terminated string

Warning: the pointer is guaranteed to be valid only until the next UI Context update

virtual int Coherent::UI::View::GetTargetFramerate ( ) const

pure virtual

Get the currently set target frame-rate for the View.

Returns: the current target frame-rate (available only in Full versions of Coherent UI)

virtual ViewType Coherent::UI::View::GetViewType ( )

pure virtual

Get the type of the view.

Returns: the type of the view

Implemented in Coherent::UI::BrowserView.

virtual int Coherent::UI::View::GetWidth ( ) const

pure virtual

Gets the width of the View.

Returns: the width of the View

virtual ViewErrorType Coherent::UI::View::HasMouseQueryFinished ( )

pure virtual

Returns the status of the mouse query.

Returns: the result will be Success if the query has finished, QueryNotReady otherwise. If no query has been issued InvalidCall will be returned.

virtual void Coherent::UI::View::IMEActivate ( bool active )

pure virtual

Sets if the View should notify the client about IME-related events and if it will process IME messages.

Parameters

active whether to activate IME handling for this view

virtual bool Coherent::UI::View::IMECancelComposition ( )

pure virtual

Cancels the current IME composition.

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

virtual bool Coherent::UI::View::IMEConfirmComposition ( const wchar_t * composition )

pure virtual

Confirms the current IME composition.

Parameters

composition the string to confirm

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

virtual bool Coherent::UI::View::IMEIsActive ( ) const

pure virtual

Tells if IME events are currently active for this view.

Returns: if the view has IME active

virtual bool Coherent::UI::View::IMESetComposition	(	const wchar_t *	composition,
		unsigned	cursorPos,
		unsigned	targetStart,
		unsigned	targetEnd
	)

pure virtual

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

Parameters

composition	the composition string so far
the	cursor position in the composition
targetStart	the index at the start of the selection
targetEnd	the index at the end of the selection

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

virtual void Coherent::UI::View::InterceptURLRequests ( bool intercept )

pure virtual

Controls intercepting URL requests. For each request ViewListener::OnURLRequest will be called.

Parameters

intercept whether to intercept all URL requests

Warning: Intercepting all URL requests will have negative impact of the loading speed of the view; Intercepting all URL requests with On-Demand views may cause a deadlock. See the detailed guide for On-Demand views.

virtual bool Coherent::UI::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) results in a warning and the return result is undefined

Returns: true if the mouse is on the view

virtual bool Coherent::UI::View::IsOnDemand ( ) const

pure virtual

Tells if this is an on-demand view. Frames must be explicitly requested for on-demand views (available only in Full versions of Coherent UI)

See Also: 'Coherent::UI::View::RequestFrame'

Returns: true if this is an on-demand view

virtual void Coherent::UI::View::IssueMouseOnUIQuery	(	float	normX,
		float	normY
	)

pure virtual

Issues a query on the View to check of the mouse is on the user interface or not.

Warning: Calling IsMouseOnView while a query is in-flight is an error and will be logged - the result returned by IsMouseOnView in that case is undefined.

Put as much processing as possible between IssueMouseOnUIQuery and the corresponding FetchMouseOnUIQuery, this allows leveraging the cost of the query and to reduce it to ~0. The best way to do this is call IssueMouseOnUIQuery early in the frame, perform all game rendering and the call FetchMouseOnUIQuery followed by IsMouseOnView to update the needed data.

Parameters

normX	the x coordinate of the mouse in the normalized space of the view [0..1]
normY	the y coordinate of the mouse in the normalized space of the view [0..1]

virtual bool Coherent::UI::View::IsTransparent ( ) const

pure virtual

Tells if this view is transparent or not.

Returns: true if the view is transparent

virtual void Coherent::UI::View::KeyEvent ( const KeyEventData & event )

pure virtual

Sends a key event to the UI renderer.

Parameters

event the key event

virtual void Coherent::UI::View::Load ( const wchar_t * path )

pure virtual

Loads a new path in the View.

Parameters

path	the path to load

virtual void Coherent::UI::View::MouseEvent ( const MouseEventData & event )

pure virtual

Sends a mouse event to the UI renderer.

Parameters

event the mouse event

virtual ViewErrorType Coherent::UI::View::PeekFrameReady ( )

pure virtual

Tells if the last requested frame is ready or not. Does not block. This call must always be made between calls to RequestFrame and FetchSurface. (available only in Full versions of Coherent UI) This function can be called from a thread different than the main UI context thread in order to support client applications with multi-threaded rendering.

See Also: 'Coherent::UI::View::RequestFrame'; 'Coherent::UI::View::FetchSurface'

Returns: VE_Success; VE_FrameNotReady; VE_FrameNotRequested; VE_InvalidCall

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

pure virtual

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

Parameters

name	name of the event
handler	handler to be executed

Returns: bound handle so the handler can be unregistered

Note: RegisterForEvent takes ownership of the handler

virtual void Coherent::UI::View::Reload ( bool ignoreCache )

pure virtual

Reloads the last requested or navigated-to path.

Parameters

ignoreCache whether to ignore the cache for the reload

virtual void Coherent::UI::View::ReplyToJavaScriptMessage	(	bool	success,
		const char *	userInput
	)		const

pure virtual

Sends a reply to a javascript message triggered for the view.

Parameters

success	defines whether the user replies positively to the message (i.e. clicks the OK button)
userInput	the user reply message (only used in prompt messages)

See Also: ViewListener::OnJavaScriptMessage

virtual ViewErrorType Coherent::UI::View::RequestFrame ( )

pure virtual

Requests a new frame for rendering. All triggered events before this call will be accounted for in the rendered view. Only one frame per-view could be requested simultaneously (available only in Full versions of Coherent UI)

Note: This function must be called on the ViewContext thread. This overload let's Coherent UI control the time in the view. You should have set ViewInfo::ControlTimeOnDemand to false to use it. If you need to control timing - use the other overload and create the view with ViewInfo::ControlTimeOnDemand set to true.

Returns: the outcome of the operation

virtual ViewErrorType Coherent::UI::View::RequestFrame ( double timeSinceArbitraryMoment )

pure virtual

Requests a new frame for rendering. All triggered events before this call will be accounted for in the rendered view. Only one frame per-view could be requested simultaneously (available only in Full versions of Coherent UI) This function can be called from a thread different than the main UI context thread in order to support client applications with multi-threaded rendering.

Parameters

timeSinceArbitraryMoment a time point - in seconds from an arbitary moment in the past(i.e. the start of the application) used as a reference for the requested frame. Time differences will be calculated between successive calls to the method and animations, javascript etc. will respect these times. Pass a time only if ViewInfo::ControlTimeOnDemand was set during the view initialization. If you don't need to control times use the overload.

Returns: the outcome of the operation

virtual void Coherent::UI::View::Resize	(	unsigned	width,
		unsigned	height
	)

pure virtual

Send a resize event to the UI renderer.

Note: Resize will result in multiple calls to CreateBuffers and DestroyBuffers in the listener

Parameters

width	the new width of the View
height	the new height of the View

virtual void Coherent::UI::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

threshold sets the new alpha threshold

virtual void Coherent::UI::View::SetMasterVolume ( double volume )

pure virtual

Sets the master volume for all audio and video streams.

Parameters

volume coefficient between 0.0 and 1.0

Note: if you are using client audio playback, the master volume will not affect the audio streams and you can control the volume in your playback code

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

pure virtual

Sets an error for the currently executing handler.

Parameters

error	the type of the error
message	the error message

virtual void Coherent::UI::View::SetTargetFramerate ( int target )

pure virtual

Sets the target frame-rate for the View. The View's rendering will never exceed the target frame-rate. It also will never exceed the frame-rate set when initializing the view. (available only in Full versions of Coherent UI)

Parameters

target the new target frame-rate

virtual void Coherent::UI::View::SetZoomLevel ( double zoomLevel )

pure virtual

Sets the page zoom level. Specifying 0.0 will reset to the default zoom level.

Warning: The zoom factor operates on protocol and host level, meaning that all views with the same protocol and host as the current URL will be scaled as well.

virtual bool Coherent::UI::View::SupportsClickThrough ( ) const

pure virtual

Tells if this view supports click-through queries or not.

Returns: true if click-through is supported

virtual void Coherent::UI::View::TouchEvent	(	const TouchEventData *	events,
		unsigned	count
	)

pure virtual

Sends a touch event to the UI renderer.

Parameters

events	array of touch events
count	the count of the passed touch events in the array

virtual void Coherent::UI::View::UnbindCall ( BoundEventHandle handle )

pure virtual

Remove a bound C++ handler.

Parameters

handle the handle of the handler to be unbound

Warning: Unbinding a handler inside the handler callback is not supported and will result in undefined behavior

virtual void Coherent::UI::View::UnbindObject ( const void * object )

pure virtual

Remove all handlers bound to a specific object.

Parameters

object the object whose handlers will be removed

Warning: Unbinding the object inside the handler callback is not supported and will result in undefined behavior

virtual void Coherent::UI::View::UnregisterFromEvent ( BoundEventHandle handle )

pure virtual

Remove a registered C++ handler.

Parameters

handle the 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

virtual bool Coherent::UI::View::UsesSharedMemory ( ) const

pure virtual

Tells if this view uses shared memory for image transport.

Returns: true if the view uses shared memory, false if shared textures

Public Member Functions

Detailed Description

Member Function Documentation