Reference for the Mosaic class Core::Root

Core::Root
ActiveDialog
ActiveDialogClass
CursorDragLimit
CursorSequelDelay
Language
Styles
VirtualKeyboard
BeginAnimation()
BeginModal()
BeginUpdate()
CaptureCursor()
DeflectCursor()
DoesNeedUpdate()
DriveCursorHitting()
DriveCursorMovement()
DriveKeyboardHitting()
DriveMultiTouchHitting()
DriveMultiTouchMovement()
EndAnimation()
EndModal()
EndUpdate()
GetFPS()
GetModalGroup()
GetUpdateRegion()
Initialize()
RetargetCursor()
RetargetCursorWithReason()
SetUserInputTimestamp()
Update()
UpdateCanvas()
UpdateGE20()
Core::Group
AlphaBlended
Buffered
ClipViews
DeriveEnabledState
Embedded
Enabled
Focus
Opacity
Visible
Add()
AddBehind()
BroadcastEvent()
BroadcastEventAtPosition()
CountDialogs()
CountViews()
DismissDialog()
DispatchEvent()
DrawBackground()
DrawForeground()
ExtendClipping()
FadeGroup()
FindActiveDialogByClass()
FindCurrentDialog()
FindDialogByClass()
FindNextView()
FindPrevView()
FindSiblingView()
FindViewAtPosition()
FindViewInDirection()
FindViewWithStackingPriority()
FindViewWithinArea()
GetContentArea()
GetDialogAtIndex()
GetIndexOfDialog()
GetIndexOfView()
GetMaximalSize()
GetMinimalSize()
GetViewAtIndex()
GlobalPosition()
HasViewState()
Init()
InvalidateArea()
InvalidateLayout()
InvalidateViewState()
IsActiveDialog()
IsCurrentDialog()
IsDialog()
LocalPosition()
ObtainFocus()
PresentDialog()
Remove()
RemoveAll()
Restack()
RestackBack()
RestackBehind()
RestackTop()
SwitchToDialog()
UpdateLayout()
UpdateViewState()
Core::RectView
Bounds
Core::View
Layout
Owner
StackingPriority
AdjustDrawingArea()
ArrangeView()
ChangeViewState()
CursorHitTest()
Draw()
GetClipping()
GetExtent()
GetRoot()
HandleEvent()
MoveView()

SEE ALSO

How to create the root (main) application GUI component?.

The class Core::Root provides the base functionality for the entire GUI application. Due to its ancestry, the application provides the entire set of functionality implemented in the Core::Group class. It serves as the root container for all GUI components, menus, panels, etc.

The application also provides an interface to the underlying target system and to the screen. The coordinate system of the application corresponds therefore to the coordinate system of the screen. Every Embedded Wizard application needs one application object.

The interface of the Core::Root class provides several methods and properties to control the application and to coordinate the screen update and the event dispatching. For example:

The property Keyboard allows the management of virtual keyboard components. A keyboard component is an ordinary GUI component you can design and fill e.g. with buttons. Its job is to generate keyboard events in response to other user interaction events, like the touch event. For this purpose the application will provide the virtual keyboard component with all necessary touch events before these are passed to the remaining parts of the GUI. Additionally, the application ensures that the virtual keyboard always remains visible on the top of the screen.

property Core::Group ActiveDialog = null;

The property 'ActiveDialog' determines the GUI component presented actually as the active dialog within the application. Alternatively you can use the property ActiveDialogClass to determine the class of the active dialog GUI component instead of an instance.

Changing this property triggers automatically a transition to the new dialog. In such case, the specified component is presented by using the method SwitchToDialog() directly in context of the application component. In turn, setting this property to the value 'null' triggers the DismissDialog() operation for the actually existing active dialog.

This is a convenience property to simply switch the dialogs existing in the application component. Please note, the transition between two dialogs is performed instantly without any animations. If you expect the transition to be performed with an animation, please use the method SwitchToDialog(). Similarly, if you want the dialogs to be stacked (or nested) you have to use the methods PresentDialog() and DismissDialog().

property class ActiveDialogClass = null;

The property 'ActiveDialogClass' determines the class of a GUI component presented actually as the active dialog within the application. Alternatively you can use the property ActiveDialog to determine the active dialog GUI component instead of its class.

Changing this property triggers automatically a transition to the new dialog. In such case, a new instance of the specified class is created and presented by using the method SwitchToDialog() directly in context of the application component. In turn, setting this property to the value 'null' triggers the DismissDialog() operation for the actually existing active dialog.

This is a convenience property to simply switch the dialogs existing in the application component. Please note, the transition between two dialogs is performed instantly without any animations. If you expect the transition to be performed with an animation, please use the method SwitchToDialog(). Similarly, if you want the dialogs to be stacked (or nested) you have to use the methods PresentDialog() and DismissDialog().

method void BeginAnimation();

The method BeginAnimation() suppresses temporarily the handling of keyboard and mouse/touch panel events. It is useful during animated screen transitions to avoid interferences between the transition and user interactions. To restore the origin event flow, the method EndAnimation() is intended.

Please note, the deactivation doesn't affect the grab cycles which were active before the animation begun. In such case the affected target view will continue receiving user input events associated with this grab cycle. For example, when the animation begun while the user held a button GUI component pressed, the component will still be fed with drag events until the user has released the touch screen. Similarly the delivery of keyboard events continues when the user has pressed a keyboard key before the animation begun. In contrast any new touch screen or keyboard interaction reported during a running animation are rejected.

Please note, if the method BeginAnimation() has been called several times, you will also need to call EndAnimation() method the same number of times in order to restore the event flow.

method void BeginModal
(
arg Core::Group aGroup
);

The method BeginModal() initiates the modal state of the given GUI component aGroup. Usually, this forces the framework to limit all user inputs to this component and its sub-views. If there is already another modal GUI component active, this method puts this component on the modal stack and redirects its user inputs events to the new component.

Whether a GUI component is currently modal or not is reflected in its state Core::ViewState.Modal. This state can be evaluated in the implementation of the UpdateViewState() method. For example, the method may highlight the component if it has obtained the modal state, etc.

method int32 BeginUpdate();

The method BeginUpdate() belongs to an interface required for integration purpose with the underlying target system. You will never need to invoke this method directly from your GUI application.

Calling this method initiates a new screen update cycle. Subsequently the method UpdateCanvas() can be called in order to perform all waiting drawing operations. If necessary UpdateCanvas() can be called multiple times in order to draw multiple screen areas individually. Finally the update cycle is terminated by calling the method EndUpdate().

The method BeginUpdate() returns the number of invalid regions waiting currently for the update. If there is nothing to update, the method returns 0 (zero). The position and the size of the invalid regions can be queried by using the method GetUpdateRegion().

method void CaptureCursor
(
arg Core::View aNewTarget
);

The method CaptureCursor() limits the delivery of cursor events to the given view aNewTarget and to its sub-views. The limitation remains active until the method is invoked again with the value 'null' as parameter.

As long as the cursor events are captured, the framework will deliver the events to the given target view and its sub-views only irrespective of the position where the user has touched the screen. Invoking this method does not affect already existing grab cycles.

property int32 CursorDragLimit = 8;

The property 'CursorDragLimit' determines how precise the touch screen can recognize the areas touched by the user. This value is expressed in pixel and defines the maximum displacement the user can move his finger between two taps in a double or triple tap sequence. It's up to you to select the appropriate value for this property. The valid values lie in the range 0 .. 64 pixel.

property int32 CursorSequelDelay = 250;

The property 'CursorSequelDelay' determines the maximum delay in milliseconds between two taps, which will be recognized as a continuous sequence of taps. This is the time between two taps in a double or triple tap.

The valid values for this property lie in the range 50 .. 2000 milliseconds. This value determines how fast or slow the user can interact with the touch screen.

method void DeflectCursor
(
arg Core::View aNewTarget,
arg point aHitOffset
);

The method DeflectCursor() changes the currently active cursor event target view. Usually, the target view is determined when the user presses the finger on the touch screen. Once determined, the target view remains active until the user has released the finger. In the meantime the framework will provide this target view with all cursor events. This entire cycle is called 'grab cycle'. The method DeflectCursor() allows you to select a new target view without the necessity to wait until the user has released the touch screen and thus has finalized the grab cycle.

Unlike the method RetargetCursor() this DeflectCursor() method hands over the cursor event flow to the new target regardless its position or state. If no new target view has been specified, the current grab cycle is finalized as if the user had released the touch screen.

When switching the target view, the framework provides the old and the new target views with cursor events. The old view will receive a Core::CursorEvent with variables Down == 'false' and AutoDeflected == 'true' - this simulates the release operations. The new target view will receive a Core::CursorEvent with the variable Down == 'true' as if it had been just touched by the user.

If the application is running within a multi-touch environment, the invocation of the DeflectCursor() method does affect the event flow corresponding only to the finger which has lastly generated touch events.

method bool DoesNeedUpdate();

The method DoesNeedUpdate() returns a value indicating whether an area of the application needs an update. If there is no invalid area to redraw, DoesNeedUpdate() returns 'false'.

method bool DriveCursorHitting
(
arg bool aDown,
arg int32 aFinger,
arg point aPos
);

The method DriveCursorHitting() exists for the integration purpose with the underlying target system. Usually the method will be invoked in response to to touch events received in the main() message loop from the target specific touch screen driver.

The parameters passed to the method determine the event. aDown determines whether the user has pressed (== 'true') or released (== 'false') his finger at the position aPos relative to the top-left origin of the GUI application area. The parameter aFinger specifies the finger (or mouse button) the user pressed for this operation. The first finger (mouse button) has the number 0, the second 1, and so far.

Please note, this method is limited to process a single touch (or mouse) event at the same time. When integrating with a target system supporting multi-touch please use the method DriveMultiTouchHitting().

method bool DriveCursorMovement
(
arg point aPos
);

The method DriveCursorMovement() exists for the integration purpose with the underlying target system. Usually the method will be invoked in response to to drag events received in the main() message loop from the target specific touch screen driver.

The method expects only one parameter aPos. This parameter determines the current cursor (or finger in the touch screen analogy) position. aPos lies relative to the top-left corner of the application coordinate system.

Please note, this method is limited to process a single touch (or mouse) event at the same time. When integrating with a target system supporting multi-touch please use the method DriveMultiTouchMovement().

method bool DriveKeyboardHitting
(
arg Core::KeyCode aCode,
arg char aCharCode,
arg bool aDown
);

The method DriveKeyboardHitting() exists for the integration purpose with the underlying target system. Usually the method will be invoked in response to events received in the main() message loop from the target specific hardware keyboard driver.

The parameters passed to the method determine the event. aDown determines whether the user has pressed (== 'true') or released (== 'false') a key. The parameters aCode and aCharCode are used exclusively. They determine the affected key. If the method is called with a valid aCode then aCharCode should be '\0'. If the method is called with a valid aCharCode then aCode should be Core::KeyCode.NoKey.

method bool DriveMultiTouchHitting
(
arg bool aDown,
arg int32 aFinger,
arg point aPos
);

The method DriveMultiTouchHitting() exists for the integration purpose with the underlying target system. Usually the method will be invoked in response to touch events received in the main() message loop from the target specific touch screen driver.

The parameters passed to the method determine the event. aDown determines whether the user has pressed (== 'true') or released (== 'false') his finger at the position aPos relative to the top-left origin of the GUI application area. The parameter aFinger identifies the associated finger. The first finger has the number 0, the second 1 and so far till 9.

Please note, unlike the method DriveCursorHitting() this method is able to process and dispatch several multi-touch events simultaneously.

method bool DriveMultiTouchMovement
(
arg int32 aFinger,
arg point aPos
);

The method DriveMultiTouchMovement() exists for the integration purpose with the underlying target system. Usually the method will be invoked in response to to drag events received in the main() message loop from the target specific touch screen driver.

The parameter aPos determines the current cursor (or finger in the touch screen analogy) position. aPos lies relative to the top-left corner of the application coordinate system. The number of the finger is specified in the parameter aFinger. The first finger has the number 0, the second 1, and so far till 9.

Please note, unlike the method DriveCursorMovement() this method is able to process and dispatch several multi-touch events simultaneously.

method void EndAnimation();

The method EndAnimation() provides the counterpart of the method BeginAnimation(). It reactivates the handling of keyboard and mouse/touch panel events. It is useful during animated screen transitions to avoid interferences between the transition and user interactions.

Please note, if the method BeginAnimation() has been called several times, you will also need to call EndAnimation() method the same number of times in order to restore the event flow.

method void EndModal
(
arg Core::Group aGroup
);

The method EndModal() terminates the modal state of the given GUI component aGroup. Usually, this forces the framework to restore the origin user input event flow unless there are other components on the modal stack. In this case the event flow is redirected to the next component on this stack.

Whether a GUI component is currently modal or not is reflected in its state Core::ViewState.Modal. This state can be evaluated in the implementation of the UpdateViewState() method. For example, the method may highlight the component if it has obtained the modal state, etc.

method void EndUpdate();

The method EndUpdate() belongs to an interface required for integration purpose with the underlying target system. You will never need to invoke this method directly from your GUI application.

Calling this method finalizes the screen update cycle initiated by the preceding BeginUpdate() invocation.

method int32 GetFPS();

The method GetFPS() returns the screen update performance expressed in frames per second. The performance is estimated for the period between the current and the preceding invocation of the GetFPS() method.

method Core::Group GetModalGroup();

The method GetModalGroup() returns the currently active modal GUI component. This is the component for which the framework does limit the event delivery. As long as a modal component exists, other components can't receive any user input events. If there is no active modal component, the method returns 'null'. To make a GUI component modal, the method BeginModal() should be used.

method rect GetUpdateRegion
(
arg int32 aRegionNo
);

The method GetUpdateRegion() belongs to an interface required for integration purpose with the underlying target system. You will never need to invoke this method directly from your GUI application.

This method returns the position and the size of the invalid region with the number specified in the parameter aRegionNo. If the desired region does not exist, the method returns an empty area.

method Core::Root Initialize
(
arg point aSize
);

The method Initialize() exists for the integration purpose with the underlying target system. You will never need to invoke this method directly from your GUI application. The method is responsible for the preparation of the application object to work with a screen with the given size aSize.

property language Language = Default;

The property 'Language' determines in multi-lingual applications the name of the currently valid user language. This language affects the variant selection in case of multi-lingual resources and constants.

This property covers the Chora build-in variable 'language'. A modification of this property forces the framework to broadcast events of the type Core::LanguageEvent to all GUI components of the application. In this manner, the components can react and update themselves to the new language.

method Core::View RetargetCursor
(
arg Core::View aNewTarget,
arg Core::View aFallbackTarget,
arg Core::View aStartView
);

The method RetargetCursor() changes the currently active cursor event target view. Usually, the target view is determined when the user presses the finger on the touch screen. Once determined, the target view remains active until the user has released the finger. In the meantime the framework will provide this target view with all cursor events. This entire cycle is called 'grab cycle'. The method RetargetCursor() allows you to select a new target view without the necessity to wait until the user has released the touch screen and thus has finalized the grab cycle.

At first the method asks the new potential target view aNewTarget whether it or one of its sub-views is willing to handle the cursor events. If successful, the method hands over the cursor event flow to this determined view. If there is no view willing to handle these events, the method hands over the event flow directly to the view specified in the parameter aFallbackTarget. If no willing view could be found and no fall-back view was given, the current grab cycle is finalized as if the user had released the touch screen.

Unlike the method DeflectCursor() this RetargetCursor() method performs the cursor hit test for all views of the new potential target. This is as if the user had tapped the screen and the framework tries to determine the view affected by this interaction. This search operation is limited to views at the current cursor position.

The parameter aStartView, if it is not 'null', restricts the operation to be handled by the specified view or another view lying behind it. In other words, views found in front of aStartView are not taken in account during the hit-test operation.

When switching the target view, the framework provides the old and the new target views with cursor events. The old view will receive a Core::CursorEvent with variables Down == 'false' and AutoDeflected == 'true' - this simulates the release operations. The new target view will receive a Core::CursorEvent with the variable Down == 'true' as if it had been just touched by the user.

If the application is running within a multi-touch environment, the invocation of the RetargetCursor() method does affect the event flow corresponding only to the finger which has lastly generated touch events.

The return value of the method identifies the view which becomed the new target of the events.

Please note the alternative version of this method RetargetCursorWithReason().

method Core::View RetargetCursorWithReason
(
arg Core::View aNewTarget,
arg Core::View aFallbackTarget,
arg Core::View aStartView,
arg Core::RetargetReason aRetargetReason
);

The method RetargetCursorWithReason() changes the currently active cursor event target view. Usually, the target view is determined when the user presses the finger on the touch screen. Once determined, the target view remains active until the user has released the finger. In the meantime the framework will provide this target view with all cursor events. This entire cycle is called 'grab cycle'. The method RetargetCursorWithReason() allows you to select a new target view without the necessity to wait until the user has released the touch screen and thus has finalized the grab cycle.

Except the additional parameter aRetargetReason, this method works similarly to RetargetCursor(). At first the method asks the new potential target view aNewTarget whether it or one of its sub-views is willing to continue processing the cursor events for the gesture specified in aRetargetReason. If successful, the method hands over the cursor event flow to this determined view. If there is no view willing to handle these events, the method hands over the event flow directly to the view specified in the parameter aFallbackTarget. If no willing view could be found and no fall-back view was given, the current grab cycle is finalized as if the user had released the touch screen.

Unlike the method DeflectCursor() this RetargetCursorWithReason() method performs the cursor hit test for all views of the new potential target. This is as if the user had tapped the screen and the framework tries to determine the view affected by this interaction. This search operation is limited to views at the current cursor position. Unlike RetargetCursor(), this method limits additionally to candidates willing to handle the gesture specified in the parameter aRetargetReason.

The parameter aStartView, if it is not 'null', restricts the operation to be handled by the specified view or another view lying behind it. In other words, views found in front of aStartView are not taken in account during the hit-test operation.

When switching the target view, the framework provides the old and the new target views with cursor events. The old view will receive a Core::CursorEvent with variables Down == 'false' and AutoDeflected == 'true' - this simulates the release operations. The new target view will receive a Core::CursorEvent with the variable Down == 'true' as if it had been just touched by the user.

If the application is running within a multi-touch environment, the invocation of the RetargetCursor() method does affect the event flow corresponding only to the finger which has lastly generated touch events.

The return value of the method identifies the view which becomed the new target of the events.

method void SetUserInputTimestamp
(
arg uint32 aTimestamp
);

The method 'SetUserInputTimestamp()' exists for optional purpose to provide the exact timestamp when the last user interaction took place. With this exact information the GUI application can calculate better interactions like touch screen gestures, etc. The time is expressed in milliseconds.

Usually the method will be invoked in response to user input events received in the main() message loop from the target specific keyboard or touch screen driver. The method should be called before the event is fed to the GUI system.

property styles Styles = [];

The property 'Styles' determines in multi-variant applications the set of the currently active styles. These styles affect the variant selection in case of multi-variant resources, constants, classes or autoobjects.

This property covers the Chora build-in variable 'styles'. A modification of this property forces the framework to broadcast events of the type Core::StylesEvent to all GUI components of the application. In this manner, the components can react and update themselves to the new style.

method rect Update();

The method Update() exists for the integration purpose with the underlying target system. You will never need to invoke this method directly from your GUI application. The method is responsible for the redrawing of invalid screen areas.

This method forces the redraw of all affected views and returns the position and the size of the redrawn area. If there is no invalid area to redraw,

method rect UpdateCanvas
(
arg Graphics::Canvas aCanvas,
arg point aOffset
);

The method UpdateCanvas() belongs to an interface required for integration purpose with the underlying target system. You will never need to invoke this method directly from your GUI application.

This method redraws all invalid screen regions into the canvas passed in the parameter aCanvas. The parameter aOffset determines the origin where to map the top-left corner of the canvas on the screen. All update areas lying outside the canvas are clipped.

The method returns the position and the size of the resulting area within the canvas affected by the update. If there is no intersection between the canvas and any of the invalid areas, UpdateCanvas() returns an empty rectangle.

method rect UpdateGE20
(
arg Graphics::Canvas aCanvas
);

The method UpdateGE20() exists for the integration purpose with the underlying target system. You will never need to invoke this method directly from your GUI application. The method is responsible for the redrawing of invalid screen areas.

This method forces the redraw of all affected views into the given drawing destination aCanvas and returns the position and the size of the redrawn area. If there is no invalid area to redraw, UpdateGE20() returns an empty rectangle. This method is intended to work with the new Graphics Engine 2.0 only.

property Core::Group VirtualKeyboard = null;

The property 'VirtualKeyboard' refers to the GUI component, which serves as the virtual keyboard. The virtual keyboard can be considered as the replacement for a non available or limited real keyboard. It appears on the screen and allows the user to input the text, numbers, etc. in a very convenient way. Usually, virtual keyboards are needed, when the affected device only provides the touch screen or if the available real keyboard is limited to few keys (for example the TV remote control).

The framework provides the virtual keyboard with all user input events and ensures that the keyboard GUI component remains visible on the top of the screen. The GUI component itself has the job to react to the user input events and to feed the resulting key events to the application by using the method DriveKeyboardHitting(). In this manner the events from a real keyboard are simulated.

This property affects only the event flow and not the visibility of the keyboard GUI component. It's up to you to show or fade-in this component. See the methods Add() and FadeGroup(). To detach the virtual keyboard assign 'null' to this property.