Reference for the Mosaic class Views::Applet

Views::Applet
AlphaBlended
Color
ColorBL
ColorBR
ColorTL
ColorTR
Embedded
Enabled
Opacity
ProgressTimer
Visible
Create()
Destroy()
GetHandle()
GetVersionNumber()
GetVersionString()
InvalidateArea()
OnAdjustSize()
OnCreate()
OnCursorEvent()
OnCursorHitTest()
OnDestroy()
OnDragEvent()
OnDraw()
OnGetBitmap()
OnGetVersionNumber()
OnKeyEvent()
OnMove()
OnProgress()
OnResize()
OnUpdate()
Core::RectView
Bounds
Core::View
Layout
Owner
StackingPriority
AdjustDrawingArea()
ArrangeView()
ChangeViewState()
CursorHitTest()
Draw()
GetExtent()
GetRoot()
HandleEvent()
MoveView()

SEE ALSO

How to integrate an external existing application with Embedded Wizard created GUI application.

The class Views::Applet implements an environment for the integration of external applications, already existing for the target system. For example an existing computer game, or a JPG viewer may be integrated into the Embedded Wizard environment by deriving and customization of this Applet class.

This class defines several OnXXX() methods, which should be overridden in the derived class in order to interact with the external application:

Depending on how the external application will perform its screen update operations following modes are reasonable:

property bool AlphaBlended = true;

The property 'AlphaBlended' determines the drawing mode for the view. Views with disabled alpha-blending will override the affected screen areas. If this mode is enabled, the pixel of the view are combined with the origin screen content by alpha-blending.

Please note, this property doesn't affect the appearance of the view, if the external application shows its content in a separate layer. In this case it is up to you to setup the layer's composition modes, if these are available.

property color Color = #FFFFFFFF;

The property 'Color' controls the color of the entire applet. Thus this property is useful if no gradients are desired. The resulting colors can additionally be modulated by the values specified in the properties ColorTL, ColorTR, ColorBL and ColorBR.

The effect of this color value depends on how the application manages its visible content:

property color ColorBL = #FFFFFFFF;

The property 'ColorBL' stores the color at the bottom-left corner of the view's Bounds area. This color value can additionally be modulated by the common color value stored in the property Color.

The effect of this color value depends on how the application manages its visible content:

property color ColorBR = #FFFFFFFF;

The property 'ColorBR' stores the color at the bottom-right corner of the view's Bounds area. This color value can additionally be modulated by the common color value stored in the property Color.

The effect of this color value depends on how the application manages its visible content:

property color ColorTL = #FFFFFFFF;

The property 'ColorTL' stores the color at the top-left corner of the view's Bounds area. This color value can additionally be modulated by the common color value stored in the property Color.

The effect of this color value depends on how the application manages its visible content:

property color ColorTR = #FFFFFFFF;

The property 'ColorTR' stores the color at the top-right corner of the view's Bounds area. This color value can additionally be modulated by the common color value stored in the property Color.

The effect of this color value depends on how the application manages its visible content:

method void Create();

The Create() method prepares an environment for the external application. Beside others tasks Create() will call the method OnCreate() which should contain your specific initialization steps of your external application.

In derived classes, the Create() method should be invoked immediately after or during the initialization of the applet view - preferably from its Init() constructor.

method void Destroy();

The Destroy() method de-initializes the external application. Beside other tasks Destroy() will call the method OnDestroy() which should contain your specific de-initialization steps of your external application.

In derived classes, the Destroy() method should be invoked during the de-initialization of the applet view - preferably from its Done() destructor.

property bool Embedded = false;

The property 'Embedded' controls how the view should appear and behave within its superior Owner. If this property == 'true', the affected view will be embedded (limited) to the boundary of a preceding Core::Outline sibling view. This is as if the view 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 view 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 applet view is able to react to user input events. Disabled views will never receive these events.

Please note, changing the enabled state of the view 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 handle GetHandle();

The GetHandle() method returns the handle (can be a pointer) identifying the instance of the external application. The handle can be used for all further access operations to this external application. Please see OnCreate().

method uint32 GetVersionNumber();

This method returns a 32-bit version number of the external application. To give the applet object a possibility to obtain this version number, the method OnGetVersionNumber() should be overridden in the derived class.

method string GetVersionString();

This method returns the version number of the external application as a human readable string. To give the applet object a possibility to obtain this version number, the method OnGetVersionNumber() should be overridden in the derived class.

GetVersionString() converts the obtained 32-bit version number into a string with the form "A.B.C.D". The part 'A' corresponds to the value of the bits 24-31 in the version number. The part 'B' corresponds to the bits 16-23. The part 'C' corresponds to the bits 8-15. The value of the bits 0-7 is formatted into the part 'D'.

Usually only the parts 'A' and 'B' are important. The part 'A' is the major version number. The part 'B' is the minor version number. The parts 'C' and 'D' are for special purpose like release, build, etc. version. If these optional parts are 0 (zero), they are ignored and the method returns only "A.B" string.

method void InvalidateArea
(
arg rect aArea
);

The method InvalidateArea() declares the given area of the Applet view as invalid, this means this area should be redrawn at the next screen update.

method point OnAdjustSize
(
arg handle aHandle,
arg point aSize
);

This method will be called when the size of the applet view is about to be changed. You can override this method in order to give your external application a chance to verify the new applet size. If necessary, you can override the suggested aSize value. Anyway OnAdjustSize() should return the verified, valid size. If not overridden, this method returns the passed aSize value.

The handle to the affected instance of the external application is passed in the parameter aHandle. Please note, that aHandle can be 'null' if there is no external application instance created yet.

Note: this method is for size validation purpose only - no applet size modifications should be performed here! This can be done in the methods OnResize() and OnMove().

method handle OnCreate
(
arg point aPosition,
arg point aSize
);

This method will be invoked automatically during the initialization of the applet view in order to create a new instance of the external application. This method is thus intended for any initialization steps regarding your external application.

If successful, this method should return a handle (can be a pointer) to identify the instance of the external application. This instance handle is then stored within the applet view and used for all further access operations to this external application. If the initialization is failed, the method should return 'null'.

The both parameters aPosition and aSize determine the screen area where the applet will appear. These will be necessary if during the initialization of the external application off-screen bitmaps or layers are created and arranged on the screen.

To modify the position and size of the applet at the runtime, the both methods OnMove() and OnResize() are intended.

method bool OnCursorEvent
(
arg handle aHandle,
arg Core::CursorEvent aEvent
);

This method is invoked automatically, after the applet view has received a cursor (or touch screen) down/release event. Within this method the event can be handled and passed to the external application. If the event could be handled, the method should return 'true'.

After the OnCursorEvent() method returns the value 'true', the OnProgress() and OnUpdate() methods are called in order to perform background tasks and screen updates in the external application.

The handle to the affected instance of the external application is passed in the parameter aHandle.

method bool OnCursorHitTest
(
arg handle aHandle,
arg point aPosition,
arg int32 aFinger,
arg int32 aStrikeCount
);

This method is invoked automatically in order to determine whether the applet view is interested in the receipt of cursor events or not. If the applet view is willing to process the event, the method should return 'true'. Otherwise the method should return 'false'.

In the implementation of the method the applet view can evaluate the passed aPosition parameter. It determines the place where the user has tapped the view with his fingertip expressed in the coordinates relative to the top-left corner of the applet view. The affected finger is identified in the parameter aFinger. The first finger (or the first mouse device button) has the number 0.

The parameter aStrikeCount determines how many times the same area has been tapped in series. This is useful to detect series of multiple touches, e.g. in case of the double click, aStrikeCount == 2.

The handle to the affected instance of the external application is passed in the parameter aHandle.

method void OnDestroy
(
arg handle aHandle
);

This method will be invoked automatically during the de-initialization of the applet view. This method is thus intended for any de-initialization steps regarding your external application. The parameter aHandle identifies the instance of the affected external application (see OnCreate()).

method bool OnDragEvent
(
arg handle aHandle,
arg Core::DragEvent aEvent
);

This method is invoked automatically, after the applet view has received a cursor (or touch screen) drag event. Within this method the event can be handled and passed to the external application. If the event could be handled, the method should return 'true'.

If the OnDragEvent() method returns the value 'true', the OnProgress() and OnUpdate() methods are called in order to perform background tasks and screen updates in the external application.

The handle to the affected instance of the external application is passed in the parameter aHandle.

method void OnDraw
(
arg handle aHandle,
arg Graphics::Canvas aCanvas,
arg rect aClip,
arg rect aDstRect,
arg color aColorTL,
arg color aColorTR,
arg color aColorBR,
arg color aColorBL,
arg bool aBlend
);

This method will be invoked automatically, when a part of the applet view needs to be redrawn. By overriding this method, the external application can redraw its content directly into the main frame buffer. The behavior of this method depends on how the external application manages its visible content:

The passed parameters determine the drawing destination aCanvas (frame buffer) and the area to redraw aClip in the coordinate space of the canvas. The parameter aDstRect defines the area of the applet view also expressed in the coordinate space of the canvas. The value of the four color parameters correspond to the properties ColorTL .. ColorBR. These values can be used to modulate the opacity or to tint the outputs of your external application. The last parameter aBlend determines whether the drawn content should be alpha-blended in aCanvas or whether the canvas pixel should be overwritten by the pixel drawn by the external application.

The handle to the affected instance of the external application is passed in the parameter aHandle.

method handle OnGetBitmap
(
arg handle aHandle
);

This method will be invoked by the applet view in order to obtain a temporary access to the off-screen bitmap containing the external application's appearance. In this manner the applet view can use the bitmap and it can show the application's content. The behavior of this method depends on how the external application manages its visible content:

Please note, the applet view will never store the determined off-screen bitmap. The bitmap belongs exclusively to the external application, which on its part can recreate the bitmap if necessary. For example, the external application can maintain two off-screen bitmaps. One of them can store the current application content while the other is filled with new content. In this case OnGetBitmap() should return the already filled bitmap. This double-buffering technique is very useful to avoid ugly artifacts during screen update.

The handle to the affected instance of the external application is passed in the parameter aHandle.

method uint32 OnGetVersionNumber();

This method should be overridden in the derived class in order to give the applet view an ability to determine the version of the external application. This method should return a 32-bit version number, which consists of 4 parts.

The major (most important) part of the version number is stored in the bits 24-31. The minor version number is stored in the bits 16-23. The values stored in the bits 8-15 and 0-7 are optional for release or build version purposes.

If this method is not overridden, 0x00000000 is returned.

method bool OnKeyEvent
(
arg handle aHandle,
arg Core::KeyEvent aEvent
);

This method is invoked automatically, after the applet view has received a key-down event. Within this method the event can be handled and passed to the external application. If the event could be handled, the method should return 'true'. If 'false' is returned, the event remains as unhandled and is passed to the next view in the focus path.

After the OnKeyEvent() method returns, the OnProgress() and OnUpdate() methods are called in order to perform background tasks and screen updates in the external application.

The handle to the affected instance of the external application is passed in the parameter aHandle.

method handle OnMove
(
arg handle aHandle,
arg point aPosition
);

This method will be invoked automatically if the screen position of the applet has been changed. This method is thus intended for any re-initialization steps of the separate layer used to show the applet's content. If the applet's content is not shown in a separate layer, the method can be ignored. The parameter aHandle identifies the instance of the affected external application (see OnCreate()).

If successful, this method should return the handle (can be a pointer) to the instance of the external application. Usually this is the value passed in aHandle. If the operation requires the external application to be recreated, the method should destroy the old application instance and return the handle to the new instance. If the reinitialization is failed, the method should return 'null'.

method bool OnProgress
(
arg handle aHandle,
arg uint32 aTime
);

This method is invoked by the applet view in order to give the external application a chance to perform some background tasks. For example the progress of an animation within a game application can be performed by this method. For your convenience the method is called with the current time expressed in milliseconds.

Usually this method is triggered periodically every 100 ms by the timer ProgressTimer. If desired, you can override the delay value of this timer. Additionally the method is called after each user interaction handled by the method OnKeyEvent(). In this manner the external application can perform its background tasks immediately after the user interaction is done.

The return value of this method determines, whether the progress operation is finished or whether the external application requires more OnProgress() invocations. If the returned value is 'true', the OnProgress() method is invoked as soon as possible again. If this value is 'false' the method is called after the next ProgressTimer expiration or after the next user interaction. The handle to the affected instance of the external application is passed in the parameter aHandle.

After the OnProgress() method returns, the method OnUpdate() is invoked automatically in order to determine whether the operation has affected the visible applet's content.

method handle OnResize
(
arg handle aHandle,
arg point aSize
);

This method will be invoked automatically if the size of the applet view has been changed. This method is thus intended for any re-initialization steps of the separate layers and off-screen bitmaps used to show or to store the applet's content. The parameter aHandle identifies the instance of the affected external application (see OnCreate()).

If successful, this method should return the handle (can be a pointer) to the instance of the external application. Usually this is the value passed in aHandle. If the operation requires the external application to be recreated, the method should destroy the old application instance and return the handle to the new instance. If the reinitialization is failed, the method should return 'null'.

If not explicitly overridden, the method destroys the old application instances and then creates a new instance with the new applet size. This is done by the methods OnCreate() and OnDestroy().

method rect OnUpdate
(
arg handle aHandle
);

This method is invoked by the applet view in order to determine and return the area of the applet view, which needs to be redrawn by the next screen update cycle. The behavior of this method depends on how the external application manages its visible content:

If there is no area to update, the method should always return an empty rectangle <0,0,0,0>.

The handle to the affected instance of the external application is passed in the parameter aHandle.

property int32 Opacity = 255;

The property 'Opacity' controls the translucence of the view. This property can take values in range of 0 .. 255. If the value is 255, the view will appear with its full opacity. The value equal to zero results in a fully transparent view. Other values in the range 1 .. 254 show a semitransparent view.

Please note, this property doesn't affect the appearance of the view, if the external application shows its content in a separate layer. In this case it is up to you to setup the layer's composition modes, if these are available.

object Core::Timer ProgressTimer
{
preset OnTrigger = progressSlot;
preset Period = 100;
preset Enabled = true;
}

This timer object triggers the external application background activities. Each time the timer expires, the method OnProgress() is called. In this manner the external application can perform some animations and do some background tasks.

Per default the timer expires every 100 ms. The timer intervals can be changed in the derived class by assigning a new value to the timer's property 'Period'.

property bool Visible = true;

The property 'Visible' determines the visibility state of the view. Invisible views will not appear on the screen. Whether a view is really visible depends on the visibility of its Owner and the position of the view within the owners boundary area.