BREW Cartoon Appendix - 6 / 6 -
Note
The SophiaFramework UNIVERSE classes of interest here are the SFBBitmap class for creating bitmaps, the SFBTransform class for displaying bitmaps and the SFRPlainWindow class for handling windows.
* This appendix assumes readers have already gone through the HelloWorld tutorial and appendix.
Cartoon Class Code Overview
Cartoon.hpp
Class Cartoon inherits from the SFRApplication class to use SophiaFramework UNIVERSE's GUI framework.
The first private variable, m_devsize, saves the dimensions of the screen and is of type SFXSize ( the class that expresses size data ).
m_pict_index and m_qvga_ratio, both of type SintN ( signed integer type ), respectively manage the image displayed on screen and the enlargement factor ( 2 for QVGA devices and 1 for non-QVGA devices ).
The bitmap that is to be displayed, is saved in m_bitmap, of type SFBBitmapSmp. SFBBitmapSmp is a SophiaFramework UNIVERSE wrapper class for the SFBBitmap class, it uses smart pointers to automatically manage memory allocation, meaning memory does not have to be explicitly released.
The rest of the header file does the usual declaring of factory function, constructor, destructor and handlers. The only new function here is LoadBitmap(), which loads a new bitmap to m_bitmap.
Constructor
The constructor registers the event handlers using exception handling ( for details see HelloWorld tutorial appendix ).
The width and height of the handset's screen are obtained through the GetDeviceSize() function of the SFXGraphics class, and saved in m_devsize.
If the both the width and the height of the screen are bigger or equal to 240, the handset is QVGA compatible and m_qvga_ratio is set to 2. Else, m_qvga_ratio is set to 1.
The Event Handlers
HANDLER_IMPLEMENT_VOIDRENDER
This drawing handler clears the display with the FillRectangle() function of the SFBGraphics class, by filling the background with a grey color defined in an instance of the SFXRGBColor class.
blank1 represents the perpendicular distance between the image and the screen edge, for the right, left and top sides of the image. blank2 represents the perpendicular distance between the bottom of the image and the navigation keys.
The SFBGraphics member function DrawRectangle(), draws the frame of the image with an instance of SFXRectangle. The 4 parameters of the SFXRectangle constructor are the x and y coordinates of the upper left corner of the frame, the width of the frame and the height.
The navigation keys are drawn with the SFBGraphics DrawRoundRectangle() function. It also creates an instance of SFXRectangle, but the corners are rounded off using an oval whose width and height are defined with an SFXSize variable.
The navigation keys are labeled with the SFBGraphics DrawText() function. If current screen is "Start", only Next" should be displayed. If current screen is "End", only "Prev" should be displayed.
m_bitmap is configured for a PC Windows system, a limitation of the BREW API that m_bitmap must be converted to a QVGA device compatible form before it can be displayed. A bitmap instance of the device compatible form is created with CreateBitmap() and stored in pSourceBitmap.
A bit block from the image stored in m_bitmap is transferred to pSourceBitmap using the BltIn() function of the SFBBitmap class. An SFXRectangle() parameter is used for the destination coordinates and a SFXGrid() parameter represents the source coordinates. A parameter of "( 0, 0 )" means that the entire image will be copied and stored starting from the top left corner.
pTransform is an instance of SFBTransform, and it uses the GetDestination() function to get the the handset display area where the image may be rendered.
Finally, the TransformBltSimple function, of the SFBTransform class, transforms pSourceBitmap and draws it in with the proper TRANSFORM_SCALE in the destination address. The first parameter of TransformBltSimple is the coordinates of the destination, the second is the source bitmap, the third is the source coordinates, and the last is the scale factor.
For non-QVGA devices, the bitmap is drawn using the DrawBitmap() function of the SFXGraphics class. Its m_bitmap parameter contains the bitmap, and SFXGrid() the destination coordinates.
HANDLER_IMPLEMENT_BOOLEVENT
-
They Key handler declares a Uint16 ( unsigned int ) variable key, where a bit parameter identifying the event is saved. The bit parameter is obtained by the GetP16() function of the SFXEvent class.
If the right directional key ( AVK_RIGHT ) is pressed, the next bitmap is loaded into m_bitmap using the LoadBitmap() function and an incremented value of m_pict_index.
If the left directional key ( AVK_LEFT ) is pressed, m_pict_index is decremented and the previous bitmap is loaded.
Pressing the select key ( AVK_SELECT ), generates the ImageWindow.
In the event diagram to the left, the select key is never pressed. Therefore the ImageWindow is never invoked, and all events are handled in the application layer.
* The handling of EVT_APP_STOP is omitted.
Loading Bitmaps
LoadBitmap() is responsible for loading a new bitmap into m_bitmap.
If the parameter index has a value from 1 to 4, LoadBitmap() gets an instance of SFBShell using SFBShell::GetInstance(), and loads the image through the LoadResBitmap() function.
LoadResBitmap() matches the ID of a bitmap in the specified resource file to the ID it is passed, and returns the matched bitmap to m_bitmap.
Once again, the use of the wrapper class SFBShellSmp automates memory allocation.
For any index bigger then 4, or smaller then 1, NULL is returned as the bitmap.
ImageWindow Class Overview
ImageWindow.hpp
ImageWindow.hpp inherits from SFRPlainWIndow, meaning that the display window will have no frame or title.
An SFXBrewPointer m_bitmap, of type SFBBitmap, is declared to save the displayed bitmap.
The SFXGrid m_transferred_point, saves the top left coordinates of the enlarged image.
Both m_devsize and m_bitmap_size are of type SFXSize, and they respectively represent the display size of the handset and the bitmap size before enlargement.
Constructor
The parameters of the constructor are an SFRApplicationPtr papp pointing to the application ( Cartoon ), a SFXRectangleConstRef rect representing the bitmap coordinates, and a SFBBitmapSmpConstRef bmp pointing to the bitmap.
The generation of the window itself is automatically handled by the SFRPlainWindow( ) constructor.
m_bitmap is initialized with the bitmap bmp, and the size of the bitmap, obtained by the GetInfo() function of the SFBBitmap class, is saved in bmpinfo. The width and height of m_bitmap are saved in m_devsize using the SetWidth() and SetHeight() functions of the SFXSize class.
The bmp_aspect_ratio is calculated by dividing the bitmaps's width, by its height. The dev_aspect_ratio is calculated in the same way with the device's width and height.
If the device's aspect ratio is bigger or equal to that of the bitmap, the bitmap may be enlarged to encompass the full screen area without distortion, the m_scale_ratio may be calculated by dividing the device's height, by the bitmap's height, and isheight_fit is set to TRUE.
Else, m_scale_ratio is the device width divided by the bitmap width, and isheight_fit is FALSE.
If isheight_fit is TRUE, the bitmap is enlarged with respect to width without worrying about height. In case isheight_fit is FALSE, the bitmap is enlarged taking height restrictions into consideration ( there might be some empty space on sides ).
Generating and Canceling the Window
ImageWindow is generated within the Cartoon class key handler when select key is pressed.
The new operator is used to allocate memory for ImageWindow.
The window is canceled, not by the delete operator, but by invoking an SFXEvent. Specifically, SREVT_RESPONDER_TERMINATE is invoked to destroy the window when either the select or clear keys are pressed.
The Event Handlers
HANDLER_IMPLEMENT_VOIDRENDER
-
The drawing handler uses an AEETransforMatrix matrix to modify the rendered image.
An AEETransforMatrix operates according to the laws of vector algebra and a scale ratio may be defined by inputting the scale factor multiplied by 256 in the A and D entries of matrix.
The process for enlarging and displaying the bitmap is the same as in the drawing handler of Cartoon, except for the TransformBltComplex() function.
The TransformBltComplex() allows for the use of the AEETransforMatrix where custom transformations may be defined, while the TransformBltSimple() function uses flags to specify predefined transformations.
In Event diagram A, the ImageWindow has not been created yet.
Event 1, AVK_RIGHT, is handled by the key handler of the Cartoon class.
Event 3, AVK_SELECT, is also handled by Cartoon"s key handler, but it generates the ImageWindow.
In event diagram B, The ImageWindow has been created, and now has focus. The events are handled by the ImageWindow handlers.
Event 5, AVK_CLR, invokes the event SREVT_RESPONDER _TERMINATE which cancels the ImageWindow.
The default handler for SREVT_RESPONDER _TERMINATE is TerminateHandler.
In event diagram C, the ImageWindow has been canceled, and events are once again handled within the Cartoon class.
After every event, SREVT_RESPONDER _RENDER is invoked to update the screen.
* The handling of EVT_APP_STOP is omitted.
HANDLER_IMPLEMENT_BOOLEVENT
-
The key handler only expects two keys to be pressed, the select key ( AVK_SELECT ), or the clear key ( AVK_CLEAR ).
Both keys execute the same window termination code.