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.
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 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.
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.
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 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 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'.
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 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 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 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 void 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 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 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 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 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 number of sibling views the view has to skip over in order to reach its new Z-order.
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 can be covered by any other sibling view. This method modifies the Z-order of the view.
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.
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 not covered by its sibling views anymore. This method modifies the Z-order of the view.
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 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.