Reference for the Mosaic class Core::Group
SEE ALSO
How to compose the appearance of a GUI component?
How to define and implement the programming interface to a GUI component?
How to store and manage the internal state of a GUI component?
Overview of Mosaic touchscreen and mouse event handler components.
Using the Key Handler to process keyboard and button input events.
How to create a new GUI component from an existing one?
How to manage the dialog between user and the GUI application?
The class Core::Group provides the base functionality for all kinds of complex GUI components, like the push button, the slider or the entire menu panel. All user defined GUI components do descend from this class.
Groups serve as containers for other views. They are able to manage any number of enclosed views, to arrange these views, to redraw them automatically and to deliver user input events to the views. They act as the unique Owner of the enclosed views. At the same time the groups borderline determines the area where its views can appear. Parts of views lying outside this Bounds area are clipped and not visible.
Each group defines its own coordinate system starting with the origin <0,0> at the top-left corner of the group. All views enclosed within the group are placed relatively to this origin. Moving a group automatically moves the corresponding coordinate system and thus the enclosed views. You don't need to take care about it.
Since the Core::Group class descends from the very basic ordinary Core::View class, groups can be enclosed within other groups, by what nesting of GUI components is possible. For example, several push button components can be enclosed within a superior menu component in order to design a more complex component. It's up to you to compose these view hierarchies.
The interface of the Core::Group class provides a wide range of methods and some properties to control the group and the enclosed views. For example:
method void Add
(
arg Core::View
aView,
arg int32 aOrder
);
The method Add() inserts the given view aView into this component and places it at a Z-order position resulting primarily from the parameter aOrder. The parameter determines the number of sibling views the view has to skip over starting with the top most view. If aOrder == 0, the newly added view will obtain the top most position. If the value is negative, the view will be lowered to the background accordingly to the absolute value of aOrder. After this operation the view belongs to the component - the view can appear on the screen and it can receive events.
The effective stacking position of the view can additionally be affected by the value of the view's property StackingPriority. Concrete, the view is prevented from being arranged in front of any sibling view configured with a higher StackingPriority value. Similarly the view can't be arranged behind any sibling view having lower StackingPriority value.
Please note, adding of views to a component containing a Core::Outline view can cause this outline to update its automatic row or column formation.
method void AddBehind
(
arg Core::View
aView,
arg Core::View
aSibling
);
The method AddBehind() inserts the given view aView into this component and places it immediately behind the view aSibling. If no sibling was specified (aSibling == null), the view is arranged in front of all other views of the component. After this operation the view belongs to the component - the view can appear on the screen and it can receive events.
If the StackingPriority value of the view does not match the StackingPriority of the view lying in front nor lying behind the affected view, the StackingPriority property of the view will be adjusted automatically.
Please note, adding of views to a component containing a Core::Outline view can cause this outline to update its automatic row or column formation.
property bool AlphaBlended = true;
The property 'AlphaBlended' determines the drawing mode for the component. Components with disabled alpha-blending will override the affected screen areas. If this mode is enabled, the aspect of the component is combined with the origin screen content by alpha-blending.
method object BroadcastEvent
(
arg Core::Event
aEvent,
arg Core::ViewState
aFilter
);
The method BroadcastEvent() feeds the component with the event passed in the parameter aEvent and propagates it to all views enclosed within the component until the event has been handled or all views are evaluated. If the event remains still unhandled, it will be passed to the component itself.
The additional parameter aFilter can be used to limit the operation to special views only, e.g. to visible and touchable views. To broadcast the event to all views pass in the parameter aFilter the value 'Core::ViewState[]'.
BroadcastEvent() is very useful to provide all views with one and the same event in order e.g. to inform all views about an important global state alteration. To send events to views enclosing a given position use the method BroadcastEventAtPosition().
BroadcastEvent() returns the value returned by the HandleEvent() method of the view which has handled the event. In the case, the event was not handled, the method returns 'null'.
method object BroadcastEventAtPosition
(
arg Core::Event
aEvent,
arg point aPosition,
arg Core::ViewState
aFilter
);
The method BroadcastEventAtPosition() feeds the component with the event passed in the parameter aEvent and propagates it to all views, which do exist within the component and do enclose the given position aPosition until the event has been handled or all affected views are evaluated. If the event remains still unhandled, it will be passed to the component itself.
Beside the position, the additional parameter aFilter can be used to limit the operation to special views only, e.g. to visible and touchable views.
BroadcastEventAtPosition() is very useful to provide views with one and the same event in order e.g. to inform the views about an important global state alteration. The parameters aPosition and aFilter limit the operation to particular views. To send events to all views regardless of their position use the method BroadcastEvent().
BroadcastEventAtPosition() returns the value returned by the HandleEvent() method of the view which has handled the event. In the case, the event was not handled, the method returns 'null'.
property bool Buffered = false;
The property 'Buffered' determines whether the affected component does store its own aspect in an internal off-screen bitmap. Such buffered components are drawn faster when they are moved or faded-in/out because the drawing of the enclosed views can be omitted. The activation of the buffered feature is also necessary if you want to replicate the aspect of the component by other views like Views::Group or Views::WarpGroup. For example, the WarpGroup view allows you to display a 2D/3D warped aspect of the origin component.
Please note, buffered components may occupy a lot of video memory. Use this feature with prudence, e.g. during active animations only. After the animation is done, set the property to the value 'false' in order to free the video memory.
method int32 CountDialogs();
The method CountDialogs() returns the total number of dialog components subordinated to 'this' component. In case of an empty component without any embedded dialogs, 0 is returned. To present a dialog use the method PresentDialog() or SwitchToDialog().
method int32 CountViews();
The method CountViews() returns the total number of views belonging to this component. In case of an empty component without any views, 0 is returned.
method void DismissDialog
(
arg Core::Group
aDialogGroup,
arg Effects::Transition
aOverrideDismissTransition,
arg Effects::Transition
aOverrideOverlayTransition,
arg Effects::Transition
aOverrideRestoreTransition,
arg slot aComplete,
arg slot aCancel,
arg bool aCombine
);
The method DismissDialog() schedules an operation to hide again the component passed in the parameter aDialogGroup. The component has to be presented by a preceding PresentDialog() or SwitchToDialog() method invocation. Calling the method DismissDialog() causes the corresponding entry to be removed from the internal stack containing all dialogs existing at the moment in context of 'this' owner component. The dialog component on top of the stack is considered as the active dialog - the dialog, the user may interact with. Other dialogs lying in the background are automatically deactivated and they are suppressed from being able to receive and process user inputs. Accordingly, applying the dismiss operation on the actually active (top) dialog causes the dialog existing eventually behind it to restore its active state.
The operation to hide the component is performed with an animation specified at its presentation time (in the parameter aDismissTransition of the method PresentDialog() or SwitchToDialog()). Alternatively, other transition to hide the component can be specified in the parameter aOverrideDismissTransition.
Dismissing a dialog may affect the visibility state of the dialog component lying further in the background. In particular, the component in the background will schedule a restore transition as expected to be after the dialog overlaying it is dismissed. When dismissing a dialog, which is not the active one (not on top of the stack), the component in the background will also schedule an overlay transition as resulting from the new overlaying dialog component. Which transitions are performed results primarily from the parameters aOverlayTransition and aRestoreTransition specified at the presentation time of the background dialog component and the parameters aOverrideRestoreTransition specified at the presentation time of the overlaying (just dismissed) dialog component. Furthermore, you can override this behavior by specifying other animations in the parameters aOverrideOverlayTransition and aOverrideRestoreTransition in the invocation of the method DismissDialog().
The both parameters aComplete and aCancel can be provided with references to slot methods, which are signaled as soon as the dismiss operation is finished (aComplete) or it has been canceled (aCancel) due to other transition being scheduled for the same GUI component aDialogGroup making the actual operation obsolete.
The dismiss operation is enqueued, so calling SwitchToDialog(), PresentDialog() and DismissDialog() several times in sequence for different components in context of 'this' owner component causes the resulting transitions to be executed strictly one after another. This behavior can be changed by passing the value 'true' in the parameter aCombine. In this case, the new operation will be executed together with last prepared but not yet started operation. In this manner several independent transitions can run simultaneously.
method object DispatchEvent
(
arg Core::Event
aEvent
);
The method DispatchEvent() feeds the component with the event passed in the parameter aEvent and propagates it along the so-called focus path. This focus path leads to the currently selected keyboard event receiver view. If the event is rejected by the view, the same operation is repeated for the next superior view. This permits the hierarchical event dispatching until a willing view has handled the event or all views in the focus path have been evaluated. If the event remains still unhandled, it will be passed to the component itself.
The focus path is established by the property Focus.
DispatchEvent() returns the value returned by the HandleEvent() method of the view which has handled the event. In the case, the event was not handled, the method returns 'null'.
method void DrawBackground
(
arg Graphics::Canvas
aCanvas,
arg rect aClip,
arg point aOffset,
arg int32 aOpacity,
arg bool aBlend
);
The method DrawBackground() is invoked automatically if parts of the GUI component should be redrawn on the screen. This can occur when e.g. the component has been moved or the appearance of the enclosed views has changed before.
DrawBackground() is invoked before all other views existing inside the component are drawn. Thus it can be used to implement sophisticated background filling operations. By overriding this method in a descending class the desired drawing operations can be implemented individually.
This method is invoked by the framework, so you never will need to invoke this method directly. However you can request an invocation of this method by calling the method InvalidateArea().
The passed parameters determine the drawing destination aCanvas and the area to redraw aClip in the coordinate space of the canvas. The parameter aOffset contains the displacement between the origin of the GUI component and the origin of the canvas. You will need it to convert the drawing coordinates into these of the canvas.
The parameter aOpacity contains the resulting Opacity value to apply on the drawn contents. It lies in range 0 .. 255. The parameter aBlend contains the resulting AlphaBlended mode to apply. It determines, whether the drawing operations should be performed with alpha-blending active or not. If aBlend is false, the drawn contents should overwrite the corresponding pixel in the drawing destination aCanvas. If aBlend is true, the outputs should be mixed with the pixel already stored in aCanvas. For this purpose all Graphics Engine functions provide a parameter to specify the mode for the respective drawing operation.
Please note also the method DrawForeground(), which is invoked after all views belonging to the component have finalized their drawing operations.
method void DrawForeground
(
arg Graphics::Canvas
aCanvas,
arg rect aClip,
arg point aOffset,
arg int32 aOpacity,
arg bool aBlend
);
The method DrawForeground() is invoked automatically if parts of the GUI component should be redrawn on the screen. This can occur when e.g. the component has been moved or the appearance of the enclosed views has changed before.
DrawForeground() is invoked after all other views existing inside the component are drawn. Thus it can be used to implement sophisticated foreground drawing operations. By overriding this method in a descending class the desired drawing operations can be implemented individually.
This method is invoked by the framework, so you never will need to invoke this method directly. However you can request an invocation of this method by calling the method InvalidateArea().
The passed parameters determine the drawing destination aCanvas and the area to redraw aClip in the coordinate space of the canvas. The parameter aOffset contains the displacement between the origin of the GUI component and the origin of the canvas. You will need it to convert the drawing coordinates into these of the canvas.
The parameter aOpacity contains the resulting Opacity value to apply on the drawn contents. It lies in range 0 .. 255. The parameter aBlend contains the resulting AlphaBlended mode to apply. It determines, whether the drawing operations should be performed with alpha-blending active or not. If aBlend is false, the drawn contents should overwrite the corresponding pixel in the drawing destination aCanvas. If aBlend is true, the outputs should be mixed with the pixel already stored in aCanvas. For this purpose all Graphics Engine functions provide a parameter to specify the mode for the respective drawing operation.
Please note also the method DrawBackground(), which is invoked before the views belonging to the component have begun their drawing operations.
property bool Embedded = false;
The property 'Embedded' controls how the component should appear and behave within its superior Owner. If this property == 'true', the affected component will be embedded (limited) to the boundary of a preceding Core::Outline sibling view. This is as if the component had been embedded within this outline. Beside the appearance limitation of the outline boundary, the outline also provides more sophisticated arrangement mechanisms and the content scrolling. It is therefore useful to create scrollable menus or lists.
If this property is 'false', the component is considered as a regular view of its Owner - it doesn't belong to any outline.
property bool Enabled = true;
The property 'Enabled' determines whether the component is able to react to user input events. Disabled components will never receive these events.
The Enabled property is reflected in the current state of the component Core::ViewState.Enabled. This state can be evaluated in the implementation of the UpdateViewState() method. For example, the method may show disabled components with pale colors, etc.
Please note, changing the enabled state of the component currently selected in the Focus property will cause the framework to select other sibling view, which will be able to react to keyboard events.
method void FadeGroup
(
arg Core::Group
aGroup,
arg Effects::Fader
aFader,
arg slot aComplete,
arg slot aCancel,
arg bool aCombine
);
The method FadeGroup() schedules an operation to fade-in or fade-out the GUI component passed in the parameter aGroup in context of 'this' GUI component. The kind of the fade-in/out animation is determined by the fader object specified in the parameter aFader. In this manner, depending on the used fader, individual transitions to show or hide the GUI component can be determined.
The operation is enqueued, so calling FadeGroup() several times in sequence for different groups in context of 'this' owner component causes the resulting transitions to be executed strictly one after another. This behavior can be changed by passing the value 'true' in the parameter aCombine. In this case, the new operation will be executed together with last prepared but not yet started operation. In this manner several independent transitions can run simultaneously.
If the affected GUI component aGroup is already scheduled for an animation, but this animation is not yet started, the new animation aFader replaces this old one, so that always only one animation per affected GUI component is pending for execution.
The both parameters aComplete and aCancel can be provided with references to slot methods, which are signaled as soon as the transition is finished (aComplete) or it has been canceled (aCancel) because of a newer transition being scheduled for the same GUI component aGroup.
method Core::Group FindActiveDialogByClass
(
arg class aDialogClass
);
The method FindActiveDialogByClass() searches the tree of subordinated components for the one, which acts actually as an active dialog and it is an instance of the specified class aDialogClass. If there is no dialog presented in context of 'this' component, 'this' component however is itself presented as dialog in context of its owner and 'this' component is an instance of the specified class, the method returns 'this'. If 'this' component is actually not acting as dialog, there are no subordinated dialogs inside it and 'this' component does not descend from aDialogClass, the method returns 'null'.
Using the method FindActveDialogByClass() in context of the application root component searches the entire set of all active dialogs existing actually in the GUI application (see also IsActiveDialog()).
method Core::Group FindCurrentDialog();
The method FindCurrentDialog() searches the tree of subordinated components for the one, which acts actually as the current dialog. In other words, it searches for the absolutely top-most dialog of all dialogs shown actually in context of 'this' component. If there is no dialog presented in context of 'this' component, 'this' component however is itself presented as dialog in context of its owner, the method returns 'this'. If 'this' component is actually not acting as dialog and there are no subordinated dialogs inside it, the method returns 'null'.
Using the method FindCurrentDialog() in context of the application root component returns the dialog which is globally current in the GUI application (see also IsCurrentDialog()).
method Core::Group FindDialogByClass
(
arg class aDialogClass
);
The method FindDialogByClass() searches the tree of subordinated components for the one, which acts actually as a dialog and it is an instance of the specified class aDialogClass. If there is no dialog presented in context of 'this' component, 'this' component however is itself presented as dialog in context of its owner and 'this' component is an instance of the specified class, the method returns 'this'. If 'this' component is actually not acting as dialog, there are no subordinated dialogs inside it and 'this' component does not descend from aDialogClass, the method returns 'null'.
Using the method FindDialogByClass() in context of the application root component searches the entire set of all dialogs existing actually in the GUI application (see also IsDialog()).
method Core::View FindNextView
(
arg Core::View
aView,
arg Core::ViewState
aFilter
);
The method FindNextView() searches for the view lying in front of the view specified in the parameter aView - aView itself will be excluded from the search operation. This allows you to enumerate all affected views, view by view from the background to the front. If the parameter aView == null, the search operations will start with the view lying in the background of the component.
The additional parameter aFilter can be used to limit the search operation to special views only, e.g. to visible and touchable views.
If there is no other view lying above the start view aView, the method returns 'null'.
method Core::View FindPrevView
(
arg Core::View
aView,
arg Core::ViewState
aFilter
);
The method FindPrevView() searches for the view lying behind the view specified in the parameter aView - aView itself will be excluded from the search operation. This allows you to enumerate all affected views, view by view from the front to the background. If the parameter aView == null, the search operations will start with the top most view.
The additional parameter aFilter can be used to limit the search operation to special views only, e.g. to visible and touchable views.
If there is no other view lying behind the start view aView, the method returns 'null'.
method Core::View FindSiblingView
(
arg Core::View
aView,
arg Core::ViewState
aFilter
);
The method FindSiblingView() searches for a sibling view of the view specified in the parameter aView - aView itself will be excluded from the search operation.
The method combines the functionality of FindNextView() and FindPrevView() and tries to find any neighbor view (regarding the Z-order not the position).
The additional parameter aFilter can be used to limit the search operation to special views only, e.g. to visible and touchable views.
If there are no other views complying the filter condition, the method returns 'null'. In contrast to other find methods, FindSiblingView() will fail, if it has been invoked with aView == 'null'.
method Core::View FindViewAtPosition
(
arg Core::View
aView,
arg point aPosition,
arg Core::ViewState
aFilter
);
The method FindViewAtPosition() searches at the given position aPosition within the component for a view.
The search operation starts with the view lying behind the view specified in the parameter aView - aView itself will be excluded from the search operation. This allows you to enumerate all affected views, view by view from the front to the background. If the parameter aView == null, the search operations will start with the top most view.
Beside the position, the additional parameter aFilter can be used to limit the search operation to special views only, e.g. to visible and touchable views.
If there is no other view at the given position lying behind the start view aView, the method returns 'null'.
method Core::View FindViewInDirection
(
arg Core::View
aView,
arg Core::Direction
aDirection,
arg Core::ViewState
aFilter
);
The method FindViewInDirection() searches within the component for a view lying in the direction aDirection relative to the center of the origin view aView. For example, invoked with the parameter aDirection == Core::Direction.Right the method tries to find a view placed on the right hand side to the origin view.
Beside the direction, the additional parameter aFilter can be used to limit the search operation to special views only, e.g. to visible and touchable views.
If more than one view does meet the search condition, the method selects the view with the shortest distance to the origin view. If no view could be found the method return 'null'.
This method is useful e.g. to navigate between GUI components of a complex menu or panel by the left, right, up and down keyboard keys.
method Core::View FindViewWithinArea
(
arg Core::View
aView,
arg rect aArea,
arg bool aFullyEnclosed,
arg Core::ViewState
aFilter
);
The method FindViewWithinArea() searches within the component for a view lying completely or partially within the designated components area aArea. The respective mode is determined by the parameter aFullyEnclosed.
The search operation starts with the view lying behind the view specified in the parameter aView - aView itself will be excluded from the search operation. This allows you to enumerate all affected views, view by view from the front to the background. If the parameter aView == null, the search operations will start with the top most view.
Beside the area, the additional parameter aFilter can be used to limit the search operation to special views only, e.g. to visible and touchable views.
If there is no other view within the area lying behind the start view aView, the method returns 'null'.
property Core::View Focus = null;
The property 'Focus' selects the view to which the component should forward all keyboard events. If a keyboard event arrives to the component, the event is first propagated to this selected view before the component can handle it.
In a hierarchy of nested components, their Focus properties will establish a kind of focus path which leads directly from the application object to the current keyboard event receiver view. In this context all views along this focus path are 'focused' and able to react to keyboard events.
The Focus property affects the state of the selected view. The view will obtain the state Core::ViewState.Selected. Views really belonging to the focus path are additionally signed with the state Core::ViewState.Focused. These states can be evaluated in the views implementation of the UpdateViewState() method. For example, the method can highlight the view if it is focused.
Please note, it is not possible to select a view which is not able to react to keyboard events. Whether a view is able or not is determined by its property Enabled. If this property changes for the currently selected view, the framework will automatically select other able sibling view.
method rect GetContentArea
(
arg Core::ViewState
aFilter
);
The method GetContentArea() determines a rectangular area within the component occupied by its views. The additional parameter aFilter can be used to limit the operation to special views only, e.g. to visible and touchable views.
If there are no views complying the filter condition, the method returns an empty area.
method Core::Group GetDialogAtIndex
(
arg int32 aIndex
);
The method GetDialogAtIndex() returns the dialog component stored at position aIndex on the dialog stack of 'this' component. The dialog lying top-most (the current dialog in context of 'this' component) has the index 0. The dialog next below has the index 1, and so far. The total number of dialogs managed by this component can be asked by the method CountDialogs().
If the passed index is negative or the desired dialog doesn't exist, the method returns 'null'. To present a dialog use the method PresentDialog() or SwitchToDialog().
method int32 GetIndexOfDialog
(
arg Core::Group
aDialog
);
The method GetIndexOfDialog() returns the position of the subordinated dialog component aDialog where it is stored on the dialog stack of 'this' component. The dialog lying top-most (the current dialog in context of 'this' component) has the index 0. The dialog next below has the index 1, and so far. The total number of dialogs managed by this component can be asked by the method CountDialogs().
If the method has been invoked with 'null' as parameter, or the dialog has not been presented by preceding PresentDialog() or SwitchToDialog() invocation, the method returns the negative index -1.
method int32 GetIndexOfView
(
arg Core::View
aView
);
The method GetIndexOfView() returns the Z-order position of the view determined by the parameter aView. The view lying in the background of the component has the index 0. The next above view has the index 1, and so far. The total number of views enclosed within this component can be asked by the method CountViews().
If the method has been invoked with 'null' as parameter, or the view doesn't belong to this component, the method returns the negative index -1.
method point GetMinimalSize();
The method GetMinimalSize() provides a common interface to ask the component for the minimum possible size it can assume by still correctly displaying the contents enclosed inside it. This information can thereupon be used in complex layout application cases to equally adjust multiple components, etc.
The default implementation of this method does nothing and returns <0,0> value. If necessary, you can override the method and implement an algorithm to calculate from the actual content of the GUI component its minimum size. For example, if the component displays some text, the calculation can take in account the space needed for this text.
method Core::View GetViewAtIndex
(
arg int32 aIndex
);
The method GetViewAtIndex() returns the view stored at the Z-order position aIndex within the component. The view lying in the background of the component has the index 0. The next above view has the index 1, and so far. The total number of views enclosed within this component can be asked by the method CountViews().
If the passed index is negative or the desired view doesn't exist, the method returns 'null'.
method point GlobalPosition
(
arg point aPoint
);
The method GlobalPosition() converts the given position aPoint from the coordinate space of this component to the screen coordinate space and returns the calculated position. In the case the component isn't visible within the application, the method can fail and return a wrong position.
method bool HasViewState
(
arg Core::ViewState
aState
);
The method HasViewState() verifies whether the specified state aState is currently valid for the component. It is useful e.g. if you need to test whether a component is really focused and thus able to receive user keyboard inputs, etc.
method Init();
The method Init() is invoked automatically after the component has been created. This method can be overridden and filled with logic containing additional initialization statements.
method void InvalidateArea
(
arg rect aArea
);
The method InvalidateArea() declares the given area of the component as invalid, this means this area should be redrawn at the next screen update.
method void InvalidateLayout();
The method InvalidateLayout() declares the state of this component as changed, so its layout possibly doesn't reflect its current state anymore. To update the layout, the framework will invoke the UpdateLayout() method.
method void InvalidateViewState();
The method InvalidateViewState() declares the state of this component as changed, so its visual aspect possibly doesn't reflect its current state anymore. To update the visual aspect, the framework will invoke the UpdateViewState() method.
method bool IsActiveDialog
(
arg bool aRecursive
);
The method IsActiveDialog() returns 'true' if 'this' component does actually act as a dialog (see the method IsDialog()) and it is the current (top-most) dialog in context of its owner component. If the parameter aRecursive is 'true', the owner in context of which 'this' component actually exists and all superior owners have also to be active dialogs or the owner has to be the application root component.
If the component is not a dialog, or other dialog has been presented in the meantime overlying 'this' component, the method returns 'false'. Similarly, if the parameter aRecursive is 'true' and the owner of the component is itself not an active dialog, the method returns 'false'.
method bool IsCurrentDialog();
The method IsCurrentDialog() returns 'true' if 'this' component and all of its owners do actually act as active dialogs (see the method IsActiveDialog()) and there are no further subordinated dialogs existing in context of 'this' component. In other words, 'this' component is absolutely the top-most dialog of all dialogs shown actually in the GUI application, so all user interactions are primarily directed to 'this' dialog.
If the component has not been presented, it has been dismissed, other dialog has been presented in meantime overlying 'this' component, the owner of the component is not itself an active dialog, or there is other dialog presented in context of 'this' component, the method returns 'false'.
method bool IsDialog
(
arg bool aRecursive
);
The method IsDialog() verifies whether 'this' component serves actually as a dialog. The component is considered as a dialog if it has been presented by a preceding invocation of the method PresentDialog() or SwitchToDialog() without the corresponding DismissDialog() invocation. If the parameter aRecursive is 'true', the owner in context of which 'this' component actually exists and all superior owners have also to be valid dialogs or the owner has to be the application root component.
If the component has not been presented by preceding PresentDialog() or SwitchToDialog() invocation or it has been dismissed by using the method DismissDialog() the method returns 'false'. Similarly, if the parameter aRecursive is 'true' and the owner of the component is itself not a dialog, the method returns 'false'.
method point LocalPosition
(
arg point aPoint
);
The method LocalPosition() converts the given position aPoint from the screen coordinate space to the coordinate space of this component and returns the calculated position. In the case the component isn't visible within the application, the method can fail and return a wrong position.
method void ObtainFocus();
The method ObtainFocus() establishes the focus path to this component by switching the Focus properties of all superior Owner components. This ensures that the component may receive user keyboard inputs.
property int32 Opacity = 255;
The property 'Opacity' controls the translucence of the component. This property can take values in range of 0 .. 255. If the value is 255, the component will appear with its full opacity. The value equal to zero results in a fully transparent component. Other values in the range 1 .. 254 show a semitransparent component.
method void PresentDialog
(
arg Core::Group
aDialogGroup,
arg Effects::Transition
aPresentTransition,
arg Effects::Transition
aDismissTransition,
arg Effects::Transition
aOverlayTransition,
arg Effects::Transition
aRestoreTransition,
arg Effects::Transition
aOverrideOverlayTransition,
arg Effects::Transition
aOverrideRestoreTransition,
arg slot aComplete,
arg slot aCancel,
arg bool aCombine
);
The method PresentDialog() schedules an operation to show in context of 'this' component another component passed in the parameter aDialogGroup. The operation to show the component is performed with an animation specified in the parameter aPresentTransition. If the parameter aPresentTransition is 'null', the show operation uses the default transition presenting the new dialog component instantly in the center of 'this' component without performing any smooth animation effects. Calling the method PresentDialog() causes the new dialog component to be pushed on top of an internal stack containing all dialogs existing at the moment in context of 'this' owner component. The dialog component on top of the stack is considered as the active dialog - the dialog, the user may interact with. Other dialogs lying in the background are automatically deactivated and they are suppressed from being able to receive and process user inputs. If not needed anymore, the dialog component can be hidden again by calling the method DismissDialog() or SwitchToDialog(), which causes the corresponding dialog stack entry to be removed or replaced. Accordingly, if there was already an active dialog component presented in context of 'this' owner, this old component looses its active state and it is overlaid by the new component.
With the parameter aDismissTransition you can specify the animation to perform when the just presented dialog component is dismissed again, which is caused when calling the method DismissDialog() or SwitchToDialog(). If the parameter aDismissTransition is 'null', the dialog will disappear with the same transition as used to show it (resulting from the parameter aPresentTransition).
With the parameter aOverlayTransition you determine an optional animation to apply on the just presented component when a further dialog component is presented overlying it. In this way you can control, whether and how the component should disappear when a new component is presented above it. With the parameter aRestoreTransition you specify the opposite animation to perform when after dismissing the overlaying component, the component in the background becomes active again. When calling PresentDialog(), you can override these originally specified transitions to overlay and restore the component in the background. With the parameter aOverrideOverlayTransition you can specify the animation to hide the component in the background instead of using the animation specified at its own presentation time. Similarly, with the parameter aOverrideRestoreTransition you can specify another animation to use when the component in the background restores its active state again.
The both parameters aComplete and aCancel can be provided with references to slot methods, which are signaled as soon as the present operation is finished (aComplete) or it has been canceled (aCancel) due to other transition being scheduled for the same GUI component aDialogGroup making the actual operation obsolete.
The present operation is enqueued, so calling PresentDialog(), SwitchToDialog() and DismissDialog() several times in sequence for different components in context of 'this' owner component causes the resulting transitions to be executed strictly one after another. This behavior can be changed by passing the value 'true' in the parameter aCombine. In this case, the new operation will be executed together with last prepared but not yet started operation. In this manner several independent transitions can run simultaneously.
method void Remove
(
arg Core::View
aView
);
The method Remove() removes the given view aView from the component. After this operation the view doesn't belong anymore to the component - the view is not visible and it can't receive any events.
Please note, removing of views from a component containing a Core::Outline view can cause this outline to update its automatic row or column formation.
Please note, it the removed view is currently selected by the Focus property, the framework will automatically select other sibling view, which will be able to react to keyboard events.
method void RemoveAll();
The method RemoveAll() removes all views from the component. After this operation the component is empty.
method void Restack
(
arg Core::View
aView,
arg int32 aOrder
);
The method Restack() changes the Z-order of views in the component. Depending on the parameter aOrder the method will elevate or lower the given view aView. If aOrder is negative, the view will be lowered to the background. If aOrder is positive, the view will be elevated to the foreground. If aOrder == 0, no modification will take place.
The absolute value of aOrder determines the maximum number of sibling views the view has to skip over in order to reach its new Z-order. The effective stacking position of the view can additionally be affected by the value of the view's property StackingPriority. Concrete, the view is prevented from being arranged in front of any sibling view configured with a higher StackingPriority value. Similarly the view can't be arranged behind any sibling view having lower StackingPriority value.
Please note, changing the Z-order of views within a component containing a Core::Outline view can cause this outline to update its automatic row or column formation.
method void RestackBack
(
arg Core::View
aView
);
The method RestackBack() puts the view aView to the background of the component. After this operation the view is usually covered by any other sibling view. This method modifies the Z-order of the view. The effective stacking position of the view can additionally be affected by the value of the view's property StackingPriority. Concrete, the view can't be be arranged behind any sibling view configured with lower StackingPriority value. In such case calling the method RestackBack() will arrange the view just above the sibling view with next lower StackingPriority value.
Please note, changing the Z-order of views within a component containing a Core::Outline view can cause this outline to update its automatic row or column formation.
method void RestackBehind
(
arg Core::View
aView,
arg Core::View
aSibling
);
The method RestackBehind() arranges the view aView behind the view aSibling. If no sibling is specified (aSibling == 'null'), the view is arranged in front of all other views of the component. This method modifies the Z-order of the view.
If the StackingPriority value of the view does not match the StackingPriority of the view lying in front nor lying behind the affected view, the StackingPriority property of the view will be adjusted automatically.
Please note, changing the Z-order of views within a component containing a Core::Outline view can cause this outline to update its automatic row or column formation.
method void RestackTop
(
arg Core::View
aView
);
The method RestackTop() elevates the view aView to the top of its component. After this operation the view is usually not covered by any sibling views. This method modifies the Z-order of the view. The effective stacking position of the view can additionally be affected by the value of the view's property StackingPriority. Concrete, the view can't be be arranged in front of any sibling view configured with higher StackingPriority value. In such case calling the method RestackTop() will arrange the view just behind the sibling view with next higher StackingPriority value.
Please note, changing the Z-order of views within a component containing a Core::Outline view can cause this outline to update its automatic row or column formation.
method void SwitchToDialog
(
arg Core::Group
aDialogGroup,
arg Effects::Transition
aPresentTransition,
arg Effects::Transition
aDismissTransition,
arg Effects::Transition
aOverlayTransition,
arg Effects::Transition
aRestoreTransition,
arg Effects::Transition
aOverrideDismissTransition,
arg Effects::Transition
aOverrideOverlayTransition,
arg Effects::Transition
aOverrideRestoreTransition,
arg slot aComplete,
arg slot aCancel,
arg bool aCombine
);
The method SwitchToDialog() schedules an operation to show in context of 'this' component another component passed in the parameter aDialogGroup. The operation to show the component is performed with an animation specified in the parameter aPresentTransition. If the parameter aPresentTransition is 'null', the show operation uses the default transition presenting the new dialog component instantly in the center of 'this' component without performing any smooth animation effects. Calling the method SwitchToDialog() causes the new dialog component to replace the entry on top of an internal stack containing all dialogs existing at the moment in context of 'this' owner component. The dialog component on top of the stack is considered as the active dialog - the dialog, the user may interact with. Other dialogs lying in the background are automatically deactivated and they are suppressed from being able to receive and process user inputs. If not needed anymore, the dialog component can be hidden again by calling the method DismissDialog() or SwitchToDialog(), which causes the corresponding dialog stack entry to be removed or replaced. Accordingly, with the method PresentDialog() new dialog component can be pushed on top of this stack overlaying all other dialogs in the background. If there was already an active dialog component presented in context of 'this' owner, this old component looses its active state and it is dismissed.
With the parameter aDismissTransition you can specify the animation to perform when the just presented dialog component is dismissed again, which is caused when calling the method DismissDialog() or SwitchToDialog(). If the parameter aDismissTransition is 'null', the dialog will disappear with the same transition as used to show it (resulting from the parameter aPresentTransition).
With the parameter aOverlayTransition you determine an optional animation to apply on the just presented component when a further dialog component is presented overlying it (by using the method PresentDialog()). In this way you can control, whether and how the component should disappear when a new component is presented above it. With the parameter aRestoreTransition you specify the opposite animation to perform when after dismissing the overlaying component, the component in the background becomes active again.
Usually, when presenting a new component by using the method SwitchToDialog(), the previously presented component disappears with the dismiss transition specified at its own presentation time (see the parameter aDismissTransition). This behavior can be overridden by specifying in the parameter aOverrideDismissTransition other animation to hide the old component.
Switching the dialog in foreground may affect the visibility state of the dialog component lying further in the background. In particular, the component in the background will schedule a restore transition as expected to be after the dialog in foreground is dismissed, and an overlay transition as resulting from the just presented new dialog component. Which transitions are performed results primarily from the parameters aOverlayTransition and aRestoreTransition specified at the presentation time of the background dialog component and the parameter aOverrideRestoreTransition specified at the presentation time of the overlaying (just dismissed) dialog component. Furthermore, you can override this behavior by specifying other animations in the parameters aOverrideOverlayTransition and aOverrideRestoreTransition in the invocation of the method SwitchToDialog().
The both parameters aComplete and aCancel can be provided with references to slot methods, which are signaled as soon as the present operation is finished (aComplete) or it has been canceled (aCancel) due to other transition being scheduled for the same GUI component aDialogGroup making the actual operation obsolete.
The present operation is enqueued, so calling SwitchToDialog(), PresentDialog() and DismissDialog() several times in sequence for different components in context of 'this' owner component causes the resulting transitions to be executed strictly one after another. This behavior can be changed by passing the value 'true' in the parameter aCombine. In this case, the new operation will be executed together with last prepared but not yet started operation. In this manner several independent transitions can run simultaneously.
method void UpdateLayout
(
arg point aSize
);
The method UpdateLayout() is invoked automatically after the size of the component has been changed. This method can be overridden and filled with logic to perform a sophisticated arrangement calculation for one or more enclosed views. In this case the parameter aSize can be used. It contains the current size of the component.
Usually, all enclosed views are arranged automatically accordingly to their Layout property. UpdateLayout() gives the derived components a chance to extend this automatism by a user defined algorithm.
method void UpdateViewState
(
arg Core::ViewState
aState
);
The method UpdateViewState() is invoked automatically after the state of the component has been changed. This method can be overridden and filled with logic to ensure the visual aspect of the component does reflect its current state. For example, the 'enabled' state of the component can affect its colors (disabled components may appear pale). In this case the logic of the method should modify the respective color properties accordingly to the current 'enabled' state.
The current state of the component is passed as a set in the parameter aState. It reflects the very basic component state like its visibility or the ability to react to user inputs. Beside this common state, the method can also involve any other variables used in the component as long as they reflect its current state. For example, the toggle switch component can take in account its toggle state 'on' or 'off' and change accordingly the location of the slider, etc.
Usually, this method will be invoked automatically by the framework. Optionally you can request its invocation by using the method InvalidateViewState().
property bool Visible = true;
The property 'Visible' determines the visibility state of the component. Invisible components will not appear on the screen. Whether a component is really visible depends on the visibility of its Owner and the position of the component within the owners boundary area.