HelloWorld Appendix - 6 / 7 -
Code Overview
Boot Loader and Factory Function
The Boot Loader is where the license code for the application is set. If this license code is not properly set, the application will not run on the actual device.
It also checks classIDs and launches the appropriate class (in this case AEECLSID_HELLOWORLD). Multiple classIDs can be registered on a single MIF file, and the mod file can contain two or three applications.
The class is launched through an SFCInvokerPtr function. The function invoked by the Boot loader, in this case Factory, is initialized and the HelloWorld class is constructed inside it.
Constructor
The constructor registers the event handlers through the RegisterHandler function.
The RegisterHandler is thrown by static_throw ( ). The first RegisterHandler's argument starts with an SFCEventEnum type, representing the event type. The second of type UINT16 has event information; in this case it indicates that the contents area should be redrawn. The third argument of type HandlerEnum, dictates when the handler is called (before or after).
-
A setting of before means the event will be processed before event settings are posted to child objects of the event tree. If the setting is after, event processing only starts when all valid child objects have obtained event settings.
The last argument is a VoidPtr and it points to the HANDLER_FUNCTION.
The second RegisterHandler has a similar signature minus the UINT16 parameter.
If the RegisterHandler succeeds, NO_ERROR is returned and if there is an exception, then the error number is returned as an SFCError value.
In case an exception does occur, error handling is not done within the application; rather the error information is saved within the class and may be handled outside the class. A detected exception causes the value of static_try ( ) to be false and the code is skipped.
Error Information
//To access the error information,
//add the following code to HelloWorld.cpp:
class thrower : public static_exception {
public:
explicit thrower(Void) static_throws;
};
thrower::thrower(Void) static_throws
{
if (static_try()) {
static_throw(SFERR_FAILED);
}
return;
}
HelloWorld::HelloWorld(Void) static_throws
{
thrower obj;
SFCError err;
err = obj.static_catch();
TRACE("err = %d", err);
return;
}
//The SFCError value will then be printed.
The Event Handlers
HANDLER_IMPLEMENT_VOIDRENDER
Its first argument is the application class name and the second is the HANDLER_FUNCTION. The HANDLER_FUNCTION defines a specific implementation dictating how an event is handled.
The third argument, varies according to the kind of Handler being used. For drawing handlers, it is a graphics object.
A custom color is created with the AtomRec structure defined in the SFXRGBColor class. ContentHandler, the base Handler of the SFRApplication class, clears the screen (painting it white).
The DrawText function from the SFXGraphics class draws the text. The text itself is this function's first parameter, the second is the rectangle where the text should be drawn ( in this case it is given by GetContentWorld( ) ) and the third is the font color.
HANDLER_IMPLEMENT_BOOLEVENT
This is a general-purpose event handler. Its arguments are the application class name, the HANDLER_FUNCTION and an event object.
A switch statement detects the type of the event. This switch statement's expression, event.GetP16( ), is a public function of the SFXEvent class. GetP16( ) acquires a bit parameter (status variable) from the event object, which is compared to the cases of the switch statement.
In this program only the select key event, which ends the application, is expected. The public function Terminate( ) of the SFRApplication takes care of ending the application.
Brew Native vs. SophiaFramework UNIVERSE
Application Creation
BREW Native
The constructor used by BREW native is AEEClsCreateInstance( ). The arguments of this constructor are an AEECLSID ( for the class id ), a pointer of type IShell ( to point to the BREW shell ), a pointer of type Imodule ( to point to the current module ) and a pointer to a pointer of type void ( to point to the created application ).
If the classIDs match, the helper function AEEAplet_NEW( ) is used to create an instance of the application. All the arguments of AEEClsCreateInstance( ) must now be passed to AEEAplet_NEW( ) along with the event handlers.
AEEAplet_NEW( ) creates an instance of the Iapplet class that references the application and registers the event handlers. If it succeeds, it returns true, else it returns false.
BREW native HelloWorld source code
SophiaFramework UNIVERSE
SophiaFramework UNIVERSE's Boot Loader checks the ids, the Factory function is roughly equivalent to AEEAplet_NEW( ), yet does not require any arguments be passed to it.
SophiaFramework UNIVERSE's constructors allows for a form of exception handling and distinguishes the different types of events even during registration.
They also allow for the timing of the event handlers to be defined, and they offer a series of pre-defined HANDLER_FUNCTIONs.
Event Hanlders
BREW Native
The BREW native version of HelloWorld handles all events in the same place. The arguments to this function are an Iapplet pointer to the application, the AEEEvent event code, a wParam word argument and a dwParam double word.
The message to be printed must be entered into an AECHAR character buffer, one character at a time.
Variables for the result and a new reference pointer to the application need to be created. Even App_Start must be handled by the application.
The drawing event uses the IDISPLAY_DrawText function, which requires a reference to the message, the font, the number of characters, the position and the alignment. After all this, the IDISPLAY_Update function that implement the changes, must be called manually.
SophiaFramework UNIVERSE
In the SophiaFramework UNIVERSE version, the application does not need to deal with App_Start or screen update, the GUI framework automatically executes both screen initialization and updating.
Specific colors can be selected for drawing and SophiaFramework UNIVERSE allows for the message to be entered in a continuous string. No need to deal with character buffers.
SophiaFramework UNIVERSE also takes care of the message size, font, positioning, alignment and update automatically. Following the Object Oriented approach, each event is encapsulated within it's own function.