ui widgets techgd dev

Widgets Technology Guide forDevelopers

QUALCOMM Incorporated5775 Morehouse Drive

San Diego, CA. 92121-1714U.S.A

.

This documentation was written for use with Brew MP, software version 1.0. This document and the Brew MP software describedin it are copyrighted, with all rights reserved. This document and the Brew MP software may not be copied, except as otherwiseprovided in your software license or as expressly permitted in writing by QUALCOMM Incorporated.

Copyright© 2010 QUALCOMM IncorporatedAll Rights Reserved

Not to be used, copied, reproduced in whole or in part, nor its contents revealed in any manner to others without the express writtenpermission of Qualcomm.

This technical data may be subject to U.S. and international export, re-export or transfer ("export") laws. Diversion contrary to U.S.and international law is strictly prohibited.

The BREW MP logo is a trademark of QUALCOMM Incorporated.Brew, and BREW SDK are registered trademarks of QUALCOMMIncorporated.

QUALCOMM is a registered trademark of QUALCOMM Incorporated in the United States and may be registered in other countries.Other product and brand names may be trademarks or registered trademarks of their respective owners.

Sample Code Disclaimer:This QUALCOMM Sample Code Disclaimer applies to the sample code of QUALCOMM Incorporated (“QUALCOMM”) to which itis attached or in which it is integrated (“Sample Code”). Qualcomm is a trademark of, and may not be used without express writtenpermission of, QUALCOMM.

Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, QUALCOMM provides the Sample Code on an"as is" basis, without warranties or conditions of any kind, either express or implied, including, without limitation, any warranties orconditions of title, non-infringement, merchantability, or fitness for a particular purpose. You are solely responsible for determiningthe appropriateness of using the Sample Code and assume any risks associated therewith. PLEASE BE ADVISED THATQUALCOMM WILL NOT SUPPORT THE SAMPLE CODE OR TROUBLESHOOT ANY ISSUES THAT MAY ARISE WITH IT.

Limitation of Liability. In no event shall QUALCOMM be liable for any direct, indirect, incidental, special, exemplary, or consequentialdamages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or businessinterruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence orotherwise) arising in any way out of the use of the Sample Code even if advised of the possibility of such damage.

HT80-VT500-103February 02, 2010

Widgets Technology Guide for Developers

i

ContentsWidgets Technology Guide for Developers....................................................................... 3

High level architecture .............................................................................................3UI Widget basics ..................................................................................................... 6Widget view and extent........................................................................................... 8View model .............................................................................................................. 8Container basics........................................................................................................ 9Root container............................................................................................................9Prop container..........................................................................................................11Grid container.......................................................................................................... 12Card container..........................................................................................................13Constraint container ...............................................................................................14XY container............................................................................................................. 15Model basics ..........................................................................................................16

Value model.........................................................................................................17Text model...........................................................................................................18List model............................................................................................................ 18Array model......................................................................................................... 19Vector model....................................................................................................... 19Menu model.........................................................................................................19Interface model....................................................................................................20Frame model....................................................................................................... 21Media frame model............................................................................................. 21Camera frame model...........................................................................................21

Controller basics......................................................................................................22Touch controller.......................................................................................................22Touch controller types............................................................................................ 23Touch controller interfaces used...........................................................................26Touch controller helper functions......................................................................... 27Using touch controller............................................................................................ 27Text controller.......................................................................................................... 28Touch observer........................................................................................................ 28Touch observer interfaces used............................................................................ 29Touch observer helper functions...........................................................................30Using touch observer ............................................................................................ 31Transitions................................................................................................................ 32Transition manager..................................................................................................33Transition types....................................................................................................... 33Transition helper functions.................................................................................... 34Using Transitions.....................................................................................................35Widgets ...................................................................................................................36

Bitmap widget .....................................................................................................37Blend widget .......................................................................................................39Border widget ..................................................................................................... 41Button widget ..................................................................................................... 47Caret widget ....................................................................................................... 50Check widget ......................................................................................................52Cursor widget ..................................................................................................... 55Date and time widget .........................................................................................56


ii

Frame widget ..................................................................................................... 60HTML widget ...................................................................................................... 63Image static widget ............................................................................................ 66Image widget ......................................................................................................69List, pick and grid widget ................................................................................... 72List, pick and grid widget interfaces used...........................................................74List, pick and grid widget helper functions..........................................................75Using list, pick and grid widget........................................................................... 76Progress widget ................................................................................................. 77Scrollbar and scroll indicator widget .................................................................. 79Slider widget .......................................................................................................83Softkey widget ....................................................................................................86Static widget .......................................................................................................88Tab widget ..........................................................................................................91Text widget .........................................................................................................95Title widget ......................................................................................................... 99Viewport widget ................................................................................................101

Glossary.................................................................................................................. 103

Widgets Technology Guide for Developers High level architecture

Qualcomm Confidential and Proprietary | © 2010 QUALCOMM Incorporated 3


Base version: Brew MP 1.0

This technology guide covers Brew® MP UI Widgets. A Widget is an extension of Brew MP and uses theBrew MP APIs to provide a framework for developers to quickly build a highly customized UI. This guideprovides information about Widget View, Model and Controllers, as well as the widgets themselves andhow to use them.

High level architectureBrew MP UI Widgets are a C-based framework for creating UI applications.

The following diagram shows the Brew MP application environment, which provides the foundation forapplications running on Brew MP, and supports core application services such as UI, which includesWidgets.

Each widget represents a visible element on the display, and lives inside of a container that manages thelayout, z-ordering, focus, and event-routing for the widgets and other containers that it contains.

Widgets represent the basic UI drawing model in Brew MP that is leveraged by the Brew MP windowmanager as well as the Flash and Trig application models. While widgets have default built-in and/or



associated controllers to handle events, it is also possible to attach additional controllers (event handlers)to a widget to perform custom logic.

Some widgets are used with multiple different models to achieve different goals. For example, FrameWidget can accept media frames from a camera viewfinder (CameraFrameModel), a video player(MediaFrameModel), or other source that provides frame-based data for playback.

Widgets support properties that are exposed to controllers and applications through get/set methods,shown below. Each widget supports properties that are specific to its function, in addition to commonproperties such as location and extent. The visual appearance of a widget can be vastly modified bychanging its properties.

Widgets Technology Guide for Developers UI Widget basics


UI Widget basics

The Widgets framework is comprised of pre-packaged basic UI components representing thefundamental parts of a UI, such as support for radio buttons, soft keys, text entry, scrollbars and otherfunctions.

To use Brew MP Widgets in a BREW application, you need an understanding of patterns and containers.Patterns are the underlying framework that Brew MP UI Widgets uses to create the widgets. A widget isused to create a complex view by using containers.

MVC Pattern

Brew MP UI Widgets are loosely based on a model-view-controller (MVC) pattern, which separates UI,controller logic, and data, as shown by the following illustration.

Most of the widgets provided deviate from the notion of separate classes for the model, view, andcontroller. Often widgets combine the view and the controller in a single object, but keep the model aseparate object.

The text widget is an example of when a model that maintains distinct model, view, and controller objects.These are the TextModel, TextWidget and TextController, respectively.

Decorator and observer patternsThe decorator and observer patterns are commonly used in Widgets.

Widgets Technology Guide for Developers UI Widget basics


• The decorator pattern is implemented by certain widgets to provide a common means to enhancethe aesthetics or behavior of widgets. Some common examples of widgets that implement thisbehavior are scrollbars, viewports, and buttons.

• The observer pattern is used by Widgets to provide advanced functionality by listening to changesin view state and model values, a critical part of the MVC pattern. This is not only used internallyby Widgets, but is also commonly used by applications to implement cohesive user interfaceexperiences.

Widgets interfaces

The diagram shows the implementation of the MVC pattern through a series of interfaces that define theresponsibilities of each prepackaged component that the Widgets framework contains. See the C/C++API Reference for more information on some commonly used interfaces.

MVC pattern implementation

When focus and key events are delivered to the widget, the view handles them and delegates the keyevents to its controller. This falls in line with the Chain of Responsibility Pattern. Events are passed downa chain of objects that implement the IHandler interface until the object it is intended for receives it andgives each object a chance to handle the event. The event handling mechanism can also be extendedby supplying a custom handler, which is called in the place of the default handler. This enables anapplication to extend the event handler for any component that has support for the IHandler interface.

Widgets Technology Guide for Developers Widget view and extent


Widgets life cycle

Widgets are dependent on their reference count. The reference count changes when the widget isinstantiated, inserted into a container, retrieving a pointer via an API, explicitly increased or decreased, orreleased from a container.

The Widget object is released when the reference count is zero.

Drawing

Widgets draw to the display through a cooperative invalidate-draw cycle. When a widget needs to updateits view, it invalidates its content. This is done by calling IWidget_Invalidate(). This call can invalidatepart or all of a widget, which causes the invalidation to travel up the container tree to the Root Container,where it will be collated into a single draw request that will be asynchronously served by the BREWsystem as appropriate. The draw cycle controls which widgets draw their content, and in what order. Itpreserves z-ordering of all elements, and only re-draws those widgets that need to be re-drawn.

Since drawing does not immediately occur, calling invalidate multiple times will not cause multipleredraws to occur (unless they occur in different draw cycles).

Widget view and extentThe widget view is responsible for rendering the model's data to the display. Since rendering thedata to the display hinges on the view knowing when the data has been updated, it listens for modelnotifications. When a change occurs in the model, or an event is received that impacts the presentation ofthe widget, the view will send an invalidation request to its parent container.

The size of the content area is important so that the view can draw. The content area is also referred toas the widget's extent. This information is given to the widget by the application or container. Note: Be sure that the extent is set; otherwise, odd behavior may be observed.

The extent is used during the drawing phase, or when sending the invalidation request. One of theparameters that can be sent in the invalidation request is the invalid region/rectangle of the widget. Itis especially useful in the event that the entire content area does not need to be redrawn. The invalidrectangle is relative to the parent container's coordinates, so the rectangle is adjusted and passed tothe parent's parent, where the process repeats until the request is delivered to the root container. Theposition of the widget within its parent container is not known by the child; it is maintained by its parentcontainer, and a widget is unable to set it.

View modelThe view model is used to observe events that have an impact on the visible state of a widget.

The view model serves as a notification agent to all registered observers. Those observers can beinternal to the widget as well as external (for example, another widget or an application might beinterested in view model events). Notifications can contain information such as the following:

• Extent changes• Invalidations• New data models being set to the widget• Widget element selection (such as in lists)

The view model can be accessed through the IWidget_GetViewModel() inline. A good example of theuse of view models in widgets is the symbiotic relationship of the Tab widget and the card container.The tab widget view notifies the card container when the user changes the currently selected tab and

Widgets Technology Guide for Developers Container basics


correspondingly, the card container will notify the tab widget when the currently active 'card' (widget) ischanged by an entity besides the tab widget.

Container basicsA container manages a collection of components that are used for a more complex view than a widgetoffers. This view is made up of a combination of widgets, decorators, and even child containers.

Widgets in a container can also be containers. A container keeps track of the relative order of eachwidget, their position or layout within the extent of the container and the currently focused widget and thefocus to the widgets.

Widgets in a container are drawn from the bottom up, meaning that the bottom-most widget in thecontainer is drawn first and the top-most widget is drawn last. When a widget is inserted in a container, itis added by default to the top of the stack. It is possible to insert a widget at any position in the container'sstack.

A widget can be located:• Completely inside the container• Partially (the widget is clipped) inside the container• Completely outside of the container (the widget is not drawn)

Using containers

To get the widget form of a container, query the container form of the interface for an IWidget by usingIxxxContainer_QueryInterface(), passing the interface ID of an IWidget to the QueryInterface function.

IPropContainer_QueryInterface(myContainer, AEEIID_WIDGET, (void**)&myContainerWidget);

Here is an example of how developers can use containers in their application:

• Create an instance of a particular container by calling ISHELL_CreateInstance() with a ClassID ofthe container type. For example AEECLSID_ConstraintContainer, AEECLSID_XYContainer, andAEECLSID_CardContainer.

• Insert the container's widget in a container that, up the hierarchy, leads to a root container tomake sure that the container is displayed on the screen. To insert widgets in a container, useIConstraintContainer_Insert(), ICardContainer_Insert(), IPropContainer_Insert(), etc.

• Query the interface to the container widget. This will allow the user to utilize the IWidget APIs, forexample to set/get extent, border properties, background color, etc.

• The IContainer APIs can be used for manipulating the container, such as inserting a widget,invalidating, getting/removing a widget, etc.

Root containerRoot Container is the highest level container defined for a single display. It manages when its children aredrawn.

Root container derived from the XY container. Each display will have at its base, one root container intowhich all other objects (including containers) will be placed. The root container is laid out in absolute(x, y) coordinates, occupying the entire extent of the display. It is at the base of all other drawing. Rootcontainer generally has a single child widget as sibling container interfaces (IConstraintContainer,IPropContainer, etc), which is easier to use when creating cohesive UIs. All other widgets would then beplaced into this container rather than being inserted directly into the root container.

In addition to handling drawing and invalidation, applications can also query the root container for thetouch observer and transition manager. The root container will create these objects dynamically the first

Widgets Technology Guide for Developers Root container


time it receives a query for them. Root container will create these objects when it receives a query forthem.

Applications should create an instance of root container and attach a canvas to it. The ICanvas interfaceprovides a drawing surface for widgets to draw upon. Root containers will then draw all the widgets intothis attached canvas. Applications that want to enable touch on a widget canvas should enable touch onroot container using the function IWidget_EnableTouch(). This call will then be propagated to all elementscurrently in the widget tree.

Once the touch is enabled in the root container, children added to the widget canvas through the rootcontainer will be automatically touch support enabled. These widgets will instantiate default touchcontrollers as appropriate.

In the following diagram, the root container is at the base of every other object to be shown on thedisplay. Within the root container, a constraint container has been created which is responsible formanaging the layout of a static widget and two softkeys. The object hierarchy is illustrated to the right ofthe diagram, with the root container at the base, and all other objects being "contained" within this rootcontainer.

The root container is the background for everything else appearing on a display, and by default,the root container is created with a white background, This color may be changed by setting thePROP_BGCOLOR for the container, using the inline function IWidget_SetBGColor().

Using root container

In the example shown below of creating a root container, the application calls IShell_CreateInstance() tocreate the root container. It then calls IRootContainer_QueryInterface() to obtain the widget object for usein widget API calls.

nErr = ISHELL_CreateInstance(piShell, AEECLSID_RootContainer,

Widgets Technology Guide for Developers Prop container


(void**)&me->picRoot);if (AEE_SUCCESS == nErr) { nErr = IRootContainer_QueryInterface(me->picRoot, AEEIID_IWidget, (void**)&me->piwRoot) ;}

In this example, the application handles the start, stop, suspend, and resume events, and callsIWidget_HandleEvent() to send all other events to the root container.

switch (eCode) { case EVT_APP_START: return TRUE; case EVT_APP_STOP: return TRUE; case EVT_APP_SUSPEND: return TRUE; case EVT_APP_RESUME: IRootContainer_Invalidate(me->picRoot, NULL, NULL, 0); return TRUE; default: break;}

// pass any unhandled events to the RCreturn IWidget_HandleEvent(me->piwRoot, eCode, wParam, dwParam);

The following example sets up the the display canvas for the root container.

IDisplayCanvas *piDisplayCanvas = NULL;AEERect rect;

int nErr = 0;// Create the display canvas.ERR_TRY( ISHELL_CreateInstance(pMe->pIShell, AEECLSID_DisplayCanvas, (void **)&(piDisplayCanvas)) );ERR_TRY( IDisplayCanvas_SetDisplay(piDisplayCanvas, pMe->pIDisplay));// Create the root container.ERR_TRY( ISHELL_CreateInstance(pMe->pIShell, AEECLSID_RootContainer, (void **) &(pMe->picRoot)) );// Get root container's widget interface.ERR_TRY( IRootContainer_QueryInterface(pMe->picRoot, AEEIID_IWidget, (void**) &pMe->piwRoot) );

// Pass the canvas to the root container with the rect that has the dimensions. SETAEERECT(&rect, 0, 0, pMe->DeviceInfo.cxScreen, pMe->DeviceInfo.cyScreen);IRootContainer_SetCanvas(pMe->picRoot, CAST(ICanvas*, piDisplayCanvas), &rect);

Prop containerThe prop container, short for proportional container, is used to manage widgets that should be laid outalong one vertical or horizontal axis. These widgets will be laid out such that their sizes are proportional toeach other and set at insertion time by the application developer.

The prop container will lay out all of its widgets in a single direction, either vertically or horizontally, usingwidget extents and proportions relative to other widgets as the determining factor in placing the widget onthe display. For example, three widgets laid out vertically -- each of which has been assigned a differentproportional value -- will be sized and positioned in the container based on the size of the container andvertical extent of each widget.

Having derived from the base container, the prop container maintains each of the characteristics commonto the container object, while an additional attribute describes the direction of the objects are to be laid outwithin the container.

Widgets Technology Guide for Developers Grid container


Objects are laid out left to right or top to bottom in the order that the widgets appear in the container'swidget stack, with the prop container dictating the extent granted to each object. The prop container willdetermine each object's extent based on that object's proportional value -- a value that is expressed eitherexplicitly of as a ratio component that is measured in relationship to all other objects within that container,or implicitly as a constant that will determine the size of the object independent of other objects heldwithin the container. Therefore, depending on the requirements of each object held in the container, therelative size of the objects within that container may vary as the size of the container changes.

The prop container is described in greater detail in the C/C++ API Reference, under IPropContainer.

Grid containerWidgets in the grid container are laid out in the matrix form, vertically and horizontally.

The grid container is derived from the base container object and is used to manage widgets. As thename suggests, grid container lays widgets out in a grid format. Each column and row has a configurableproperties which can be set to change the appearance of grid container. This is done by setting thevalues of the GridDescriptors.

Using grid container

Cell type flags determine layout in either the x or y direction.

• CELL_FIXED: fixed height and width• CELL_PROPORTIONAL - proportional height and width.• CELL_KEEP_EXTENT - row will use the largest widget's height and width.• CELL_SIZE_TO_FIT - widget's preferred extent.

The following is an example of the setup for a grid container.

1. Create an array of GridDescriptors that describe the properties of each row and column. EachGridDescriptor would be set to the following values.

uint16 nRows = (uint16) ARRAYSIZE(aGridRows);uint16 nCols = (uint16) ARRAYSIZE(aGridCols);// Update grid size based on screen sizeint gridCellSize = MIN(58, MIN(me->rcClient.dx, me->rcClient.dy) / 3);aGridRows[0].iValue = aGridRows[1].iValue = aGridRows[2].iValue = (uint16)gridCellSize;aGridCols[0].iValue = aGridCols[1].iValue = aGridCols[2].iValue = (uint16)gridCellSize;

2. Call ISHELL_CreateInstance with the ClassID AEECLSID_GridContainer.

ERR_TRY( ISHELL_CreateInstance(me->piShell, AEECLSID_GridContainer, (void**) &picGrid) );

3. Call IGridContainer_QueryInterface().

ERR_TRY( IGridContainer_QueryInterface(picGrid, AEEIID_IWidget, (void**) &me->piwGridC) );

4. Call IGridContainer_SetGridDescriptors(). The parameters aGridRows and aGridCols are arrayscontaining initialized GridDescriptors to describe each row and column.

ERR_TRY( IGridContainer_SetGridDescriptors(picGrid, CAST(GridDescriptor*,aGridRows), &nRows, CAST(GridDescriptor*,aGridCols), &nCols) );

5. Insert the grid container into the root container so it draws to the screen, usingIRootContainer_Insert().

Widgets Technology Guide for Developers Card container


ERR_TRY(IRootContainer_Insert(me->piwRoot, piwGrid, WIDGET_ZNORMAL, &widPos) );

6. Using the widget interface to grid container, set the extent to the desired size you want the containerto be.

IWidget_SetExtentEx(me->piwGridC, me->rcClient.dx, me->rcClient.dy);7. Insert widgets.

SampleTouchApp_InsertWidget(me, me->piwGridC, 0, 0, 0);

Grid container knows which widget inside the container has focus. By default the upper leftmost widgethas focus. To explicitly set focus to a different widget, say for example the last widget, call:

IWidget_MoveFocus(me->piwMyGridContainer, (IWidget*)WIDGET_FOCUS_LAST);

Grid container helper functions

IGridContainer provides methods to get and set grid descriptors throughIGridContainer_GetGridDescriptors() and IGridContainer_SetGridDescriptors(), and methods to set andget visibility of the container through IGridContainer_SetVisibility() and IGridContainer_GetVisibility().

Card containerThe card container organizes widgets much like a deck of cards -- one on top of another, managing whichis visible at the top of the deck.

Only the widget currently having focus is displayed. The underlying widgets are hidden, regardless of thetop widgets' size, position or opacity. However, the single visible widget could be implemented as anothercontainer, which itself could manage a collection of many widgets, all of which would be visible dependingon the type of container being used.

The card container is derived from the container object. Widgets in card containers do not have 'x' and'y' coordinates on the display -- only 'z' ordering, with one widget at each level of the display. Only one ofthe widgets managed by the container will be visible on the display, with the others hidden from view as ifthey were the remaining cards in the deck.

The diagram below illustrates how the widgets managed by a card container are related to one another.

Widgets Technology Guide for Developers Constraint container


The topmost widget is the one that will occupy the entire extent of the container, and will be the widgetthat has the current focus (if it can take focus). However, it is possible to activate a widget that cannottake focus, but note that this will cause the container to have no-focused widget, as focus usually goes tothe activated widget. There are two ways to set the activated widget:

1. Move focus to a widget which can take focus2. Activate a non-focusable widget using ICardContainer_Activate(). In this case, the container will not

have a focused widget if the newly activated widget is unable to take focus.

The card container is described in greater detail in AEEICardContainer.h.

Constraint containerIn a constraint container, widgets are laid out relative to the placement of other widgets and/or thecontainer.

The constraint container is derived from the base container object, and is used to manage the widgetswithin a container where those widgets are either laid out relative to the container itself, or relative to eachof the other objects held in the container. Objects are laid out in the order that the widgets appear in thecontainer's widget stack, with the position of each object determined by the set of constraint elements.Each widget in the container has a constraint element per dimension (top, bottom, left, and right). Theconstraint element specifies its position relative to the parent, previous widget, or its own extent.

The position and size of a widget will be determined by the size of the parent container, and the positionand size of all the other widgets in the container. As the size and shape of the constraint containerchanges, so do the size, shape and position of each of the widgets it manages. Regardless of the sizeand shape of the container, the widgets it manages will maintain consistent appearance relative to oneanother. Likewise, as objects are added or removed from the container, or as individual constraint pointsare modified, the dimensions and placement of other objects will change.

Widgets Technology Guide for Developers XY container


So, if a constraint point has been defined relative to the previous object, and that object is invisible,BREW will traverse over the widget stack until it finds the first visible widget, and base theconstraint point on that widget's layout. The constraint container is described in greater detail inAEEConstraintContainer.h.

Using constraint container

The constraint container object can be used whenever the position of the objects within the containerare to be laid out based on their constraints relative to the parent, previous visible object, or thecenter of the container. To insert widgets in a container, use IConstraintContainer_Insert(), wherethe type of the constraint used for inserting a widget is be specified in WidgetConstraint. UseIConstraintContainer_Remove() to remove the inserted widgets.

XY containerXY container is used to manage the widgets within a container, where those widgets are positioned withinthe container at absolute (x, y) locations.

The XY container is derived from the base container object. The coordinates of each object managed byan XY container are expressed relative to the enclosing container. Therefore, a widget placed at (2, 5)within an XY container would be placed 2 pixels from the container's left edge, and 5 pixels from the top.Objects are positioned by specifying their point of origin, with the object extent entirely under the controlof the object itself (unlike objects placed in card, prop or constraint containers, where the container grantsan extent to each object).

Objects within an XY container may overlap one another with the widgets at the top of the widget stackbeing those that appear to lay "on top" of lower objects.

Widgets Technology Guide for Developers Model basics


The XY container is the simplest container among all available containers. The XY container does not setextent on its child widget, but relies on the extent the application has set on the widget. The XY containerdoesn't do any layout, which makes it the most efficient container. It depends on the application to insert achild at a particular (x, y) position within the widget.

With this simplicity, an application needs to explicitly provide the location and size for each child widget.It needs to have logic to layout the screen contents based on screen resolution. The XY container isdescribed in greater detail in AEEIXYContainer.h, and the C/C++ API Reference.Using XY container

The following sample code shows how a XY container is created and how child widgets are inserted intothe XY container.

int AEEResult nErr;IXYContainer *piXYContainer = NULL;IWidget *piStaticWidget1 = NULL;IWidget *piStaticWidget2 = NULL;WidgetExtent we;WidgetPos WidPos;

do{ nErr = ISHELL_CreateInstance(pIShell, AEECLSID_XYContainer, (void **)&piXYContainer); BREAKIF(nErr);

nErr = ISHELL_CreateInstance(pIShell, AEECLSID_StaticWidget, (void**) &piStaticWidget1); BREAKIF(nErr);

nErr = ISHELL_CreateInstance(pIShell, AEECLSID_StaticWidget, (void**) &piStaticWidget2); BREAKIF(nErr);

we.width = 45; we.height = 20; IWidget_SetExtent(piStaticWidget1, &we); IWidget_SetExtent(piStaticWidget2, &we);

WidPos.bVisible = TRUE; WidPos.x = 1; WidPos.y = 1; IXYContainer_Insert(piXYContainer, piStaticWidget1, WIDGET_ZNORMAL, &WidPos);

WidPos.y = 20; IXYContainer_Insert(piXYContainer, piStaticWidget2, WIDGET_ZNORMAL, &WidPos);}while(0);

RELEASEIF(piXYContainer);RELEASEIF(piStaticWidget1);RELEASEIF(piStaticWidget2);

Model basicsThe data that drives the widget content is stored within a model. Models don't know about the visualrepresentation of the data driving the widget content. A model also has a notification mechanism to informits client of a state change. Models provide an API that enables the application to manipulate the data



and register listeners. It is possible to register multiple listeners with a model, or to cancel a listener.Model listeners receive all event notifications, it is not possible to register for a subset of events.

The following are model types available in Brew MP UI Widgets.

• IValueModel: A model for data that can be represented in an arbitrarily complex form• ITextModel: A model for text strings such as in text entry• IListModel: A base class for IArrayModel and IVectorModel• IArrayModel: A model for a collection of objects with a constant number or elements• IVectorModel: A model for a collection of objects that might be of a variable size• IMenuModel: Derived from IListModel• IInterfaceModel: A model interface for objects that model their data in an interface that does not

have a query interface, for example, bitmap and image widgets• IFrameModel: Base class for IMediaFrameModel and ICameraFrameModel• IMediaFrameModel: Provides image frames from a video• ICameraFrameModel: Provides image frames from a camera

Using models

IModel is the interface for a model in the Model-View-Controller triad. A model consists of data along witha notification mechanism to inform its client of changes to that data.

The model interface provides object reference counting mechanisms that allow objects to manage theirown memory instances. The interface also provides APIs for registering a listener with a model, andinterfaces for manipulating the data represented by a model.

The code snippet below shows how to initialize and use the IModel interface.

The code is querying for the model of ITelephone and adding a listener to it. After getting an IModelinstance, the user can call IModel_AddListener() to receive future notifications. IModel_Notify() will notifylistening entities. The user data will be of type IPhonectl and any change in model of ITelephone will firethe listener.

static void ModelCallBackFunction(void *pUserData, ModelEvent *pEvent);ModelListener ListenerObj;

// The pIPhoneCtl is sent as user data to the listener and should be freed // in the listener function.ITelephone *pTelephone = NULL;IModel *pModel;if(AEE_SUCCESS == ISHELL_CreateInstance(pShell, AEECLSID_PHONECTL, (void **) &pIPhoneCtl)){ LISTENER_Init((ModelListener *)&ListenerObj, ModelCallBackFunction, (void *) pIPhoneCtl); if(AEE_SUCCESS == ISHELL_CreateInstance(pShell, AEECLSID_TELEPHONE, (void **) &pTelephone)){ if(AEE_SUCCESS == ITelephone_QueryInterface(pTelephone, AEEIID_IModel, (void **) &pModel)){ ITelephone_Release(pTelephone); IModel_AddListener(pModel, (ModelListener *)&ListenerObj); IModel_Release(pModel); } }}

Value model



IValueModel is inherited from the IModel interface and is the most basic model. It models data that canbe represented in arbitrarily complex form, modeling anywhere from simple text or integer or to a complexdata structure.

For example, a thermometer that measures temperature in absolute values could be modeled usingIValueModel to represent degrees Fahrenheit or Centigrade as a simple integer. A more complexillustration of a value model could be a personnel record extracted from a company database. The recordmight include fields for an employee's name, office number, extension, or even a bitmapped photo. In thiscase, the value model would store an entire data structure.

The interface provides object reference counting mechanisms that allow objects to manage their ownmemory instances. In addition, the interface provides APIs for registering a listener with a value model, aswell as interfaces for manipulating the data represented by the model.

See Brew MP web site for the How To on attaching view model and handle model events.

Text model

ITextModel is inherited from the IModel interface and is used to model data that can be represented byBrew MP AECHAR text strings.

The interface provides object reference counting mechanisms that allow objects to manage their ownmemory instances. In addition, the interface provides APIs for registering a listener with a text model, aswell as interfaces for manipulating the text represented by the model.

List model

IListModel is inherited from the IModel interface and is used as a base class for models that manage dataorganized in lists or collections.

The IListModel interface is not intended to be used directly, instead serving as a base from which othermore sophisticated models will be derived. Two examples of models that derive from IListModel are thearray and vector models.

As a minimal base class, it is important to note that the IListModel interface models only the structure of asimple list -- the size and current position of the list -- not the data actually stored in each item of the list.

IListModel provides object reference counting mechanisms that allow objects to manage their ownmemory instances. In addition, the interface provides APIs for registering a listener with a list model, aswell as interfaces for manipulating the structural information stored in the model.

IListModel *piListModel = NULL;int index;int size;for (index = 0; index < size; index++){ void* data = NULL; IListModel_GetAt(piListMode, index, &data); nErr = IWidget_GetModel(me->piw, AEEIID_IListModel, (IModel**)(void**) &piListmModel); if(AEE_SUCCESS != nErr){ size = ....; // manipulate this data }}



Array model

IArrayModel is derived from the IListModel interface and is used to model a collection of objects, all of anequal fixed size.

The data of an array model is stored as one contiguous block of memory, each item stored one after theother in equal sized blocks. When queried to retrieve a particular item, the array model returns a pointerto the location within the array where the requested item is stored. The array model operates on wholearray structures and lacks facilities for adding, inserting, deleting or replacing individual items. Changesrequire that the entire existing array structure be replaced with a new array.

The array model is best suited for small lists of items, or lists that will not be changing. For more complexdata collections the vector model may be used.

The IArrayModel interface provides APIs for manipulating the data stored in the array model, as well asroutines for managing reference counting of the interface object, and functions that allow widgets and UIcontrols to register for a listener with the array model.

Usage

After getting an IArrayModel interface, you typically set its items from an array usingIArrayModel_SetItems(), then set it on a widget that supports IArrayModel as its IModel. For more detailsplease refer to the IModel interface in the C/C++ API Reference.

Vector model

IVectorModel is derived from the IListModel interface and is used to model a collection of objects that maybe of some variable size.

Vector models benefit from APIs that provide the ability to add, insert, delete and replace items stored inthe model and allow each item to vary in size and structure.

Basically, the vector model is stored as an array of pointers. Each item in a vector model is referencedby a pointer, with all the item pointers collected together in one contiguous block of memory. The blockof item pointers is accessed by the vector model through a second pointer. The contents of each item inthe vector could be of a different size and structure. When the he vector model is queried to retrieve aparticular item, it returns a pointer to the location where that item's contents are stored.

The IVectorModel interface provides APIs for manipulating the data stored in the vector model, as well asroutines for managing reference counting of the interface object, and functions that allow widgets and UIcontrols to register for a listener with the vector model.

Menu model

IMenuModel is derived from the IListModel interface and is used to model a collection of objects, each ofwhich is considered to be an item in a menu.

Typically, the menu model is used to manage the storage of data for a user interface object that takesthe appearance of a menu -- such as a popup menu form. The menu model stores menu item data fromwhich a menu may be easily built, maintaining that data in the order that it would appear in a menu on thedisplay.

In general (though depending on the object that is attached to the menu model), the items in the menumodel will be displayed top-to-bottom from items 0 through item (n - 1), with item zero being at the top ofthe menu and item (n - 1) at the bottom.



The menu model interface provides APIs for accessing or modifying the data, as well as routines formanaging reference counting of the interface object, and functions that allows widgets and UI controls toregister for a listener with the menu model.

Using menu model

While this is a fairly simple menu, having only one layer, it is possible using flags such asMMF_SUBMENU to create hierarchical trees of menus.

int result;IMenuModel *piMenuModel = NULL;result = ISHELL_CreateInstance(piShell, AEECLSID_MenuModel, (void **)&piMenuModel);// Perform actions such as adding listenersif (result == AEE_SUCCESS) { for(i=0; i<DATA_SIZE; ++i) { nErr = IMenuModel_Add(piMenuModel, data[i], i + 1, MMF_ENABLED); }}// Do everything else you may need to do with the menu model, such as attaching it// to a widget so that it can actually be displayed to the user.RELEASEIF(piMenuModel);

Interface model

The Interface model models data that can be represented as a pointer to a BREW interface that can'tnatively support an interface query, such as IImage or IBitmap.

IInterfaceModel is inherited from the IModel interface and is used for objects that wish to model datastored in an interface that lacks a formal query interface, while still ensuring strict data type enforcementon the data stored in the model interface (where the IValueModel interface would not). This is particularlyimportant for standard BREW data types. For example, the bitmap and image widgets rely on their nativeBREW interfaces (IBitmap and IImage, respectively) for storing data. However, neither of these interfacessupport a query interface. Thus, changes to the data stored in these objects may be funneled throughIInterfaceModel.

IInterfaceModel provides object reference counting mechanisms that allow objects to manage their ownmemory instances. In addition, the interface provides APIs for registering a listener with a value model, aswell as interfaces for manipulating the interface reference information stored in the model.

Using interface model

InterfaceModels are used as a wrapper around objects that do not support a query interface. Onepossible use for this would be to insert a bitmap into an image widget. This example details the retrieval ofa bitmap (pib) that has already been inserted into the widget (piw).

IInterfaceModel *piim = NULL;// Get the current bitmap from the widget. It is stored via an interface model.nErr = IWidget_GetModel(me->piw, AEEIID_IInterfaceModel, (IModel**)&piim);if (AEE_SUCCESS != nErr) { // Perform cleanup}nErr = IInterfaceModel_GetIPtr(piim, AEECLSID_Bitmap, (void**)&pib);if (AEE_SUCCESS != nErr) { // Perform cleanup}// use bitmap obtained from widget through interface model



Frame model

IFrameModel is an abstract base class representing a media source such as video or a camera that isgenerally associated with a Frame widget. The IFrameModel notifies its listener through IModel_Notify()whenever a new frame is available, and the listener can then retrieve the current frame and display it.

IFrameModel usage

IFrameModel can be used to retrieve the current frame through IFrameModel_GetFrame(), get and setframe size through IFrameModel_GetSize() and IFrameModel_SetSize(), get and set frame offset usingIFrameModel_GetOffset() and IFrameModel_SetOffset().

Media frame model

IMediaFrameModel is derived from IFrameModel and provides image frames from a video.

Using media frame model1. Create an instance of the FrameWidget using AEECLSID_FrameWidget.2. Create an instance of the IMediaUtil object using AEECLSID_MediaUtil.3. Create an instance of the IMedia interface and load the video file using IMediaUtil_CreateMedia.4. Create an instance of the MediaFrameModel using AEECLSID_MediaFrameModel.5. Set the IMedia instance on the MediaFrameModel using IMediaFrameModel_SetIMedia.6. Set the model on the frame widget using IWidget_SetModel.7. Start video using IMedia_Play.

Camera frame model

ICameraFrameModel is derived from IFrameModel and provides image frames from a camera.

The camera image is managed by an ICamera object and wrapped by the camera frame model. Framechanges are sent to listeners, usually frame widgets.

Using camera frame model1. Create an instance of the frame widget using AEECLSID_FrameWidget.

ISHELL_CreateInstance(me->piShell, AEECLSID_FrameWidget, (void**)&me->piwFrame);

2. Create an instance of the ICamera object using AEECLSID_Camera.

ISHELL_CreateInstance(me->piShell, AEECLSID_CAMERA, (void**)&me->piCamera);3. Set the camera size and display size using ICamera_SetSize and ICamera_SetDisplaySize.

if (AEE_SUCCESS == nErr) { AEESize size; size.cx = me->rcContainer.dx; size.cy = me->rcContainer.dy - BUTTON_WIDTH; if (AEE_SUCCESS == nErr) { nErr = ICamera_SetSize(me->piCamera, &size); nErr = ICamera_SetDisplaySize(me->piCamera, &size); }}

4. Create an instance of the CameraFrameModel using AEECLSID_CameraFrameModel.

Widgets Technology Guide for Developers Controller basics


ISHELL_CreateInstance(me->piShell, AEECLSID_CameraFrameModel, (void**)&piModel);

5. Set the ICamera instance on the CameraFrameModel using ICameraFrameModel_SetICamera.

ICameraFrameModel_SetICamera(piModel, me->piCamera);6. Set the model on the frame widget using IWidget_SetModel.

nErr = IWidget_SetModel(me->piwFrame, (IModel*)(void *)piModel);7. Start camera using ICamera_Preview.

ICamera_Preview(me->piCamera);

Controller basicsThe widget controller handles user interaction, such as key events.

The controller is used to interpret certain events passed to widgets. It updates the widget's view andmodel based on these events.

The controller interface provides object reference counting mechanisms that allow objects to managetheir own memory instances. In addition, the interface provides APIs for registering a handler with acontroller.

IController is the interface for a controller in the Model-View-Controller triad. This part of MVC is oftencombined with the view part of the widget. Many of the widgets that Brew MP UI Widgets offers combinethe view and the controller in a single object, but keep the model as a separate object. The fact that theview and the controller are combined in these cases is because these two portions of the MVC triad aresimplistic, intertwined, and specific to one another. Therefore it is unlikely that the controller could bereusable by another view.

A common exception to this is the touch controller, which is always separate regardless of the widget.The touch controller is maintained as a separate object for these reasons:

• Not every embedded device has touch support.• Developers may have specific requirements for touch behavior that necessitate supplying a more

custom controller.

Developers can use the IController interface to implement their own controllers, or customize alreadyexisting controllers such as TextController, widget touch controllers, etc., through the base IHandlerinterface.

Using controller

General usage of the controller is as follows:

• Create an instance of a controller in an application by calling ISHELL_CreateInstance() with theClassID of the controller.

• For managing the instances of the controller, an application would use IController_AddRef() andIController_Release().

• The application calls IController_SetWidget() to associate a widget with the controller.• The application forwards any events that need to be handled by the controller to the registered

handler via the API call IController_HandleEvent().

Touch controllerTouch controlles are implementations of IController that can be used by their corresponding widgets tohandle pointer events provided to the widget by BREW.

Widgets Technology Guide for Developers Touch controller types


These touch-enabled widgets will create a default touch controller, and pass all received touch events tothe touch controller. This default touch controller can be overriden using IWidget_SetTouchController().

The following figure illustrates the architecture of the default touch controller.

As shown in the diagram, the widget handles the events in the following steps:

1. The user touches the screen and/or moves the finger (stylus), which generatesEVT_POINTER_DOWN/EVT_POINTER_MOVE/EVT_POINTER_UP events.

2. The event is passed to the widget.3. Widget checks if the event it received is a pointer event. If it has a valid touch controller, it will pass

the event to the touch controller.4. The controller gets the relative coordinates of the hit from the event and queries the widget for the

widget element under the hit, such as a scrollbar arrow.5. Based on the widget element being hit, the controller can then take different action like setting a

property on the widget or performing a view model notification.

If an application needs to customize the behavior of this touch controller, it can do so by overriding thetouch controller handler, or implement a new touch controller, set as the widget's touch controller by usingIWidget_SetTouchController().

Touch controller typesTouch controller types are implementations of IController that can be used by their corresponding widgetsto handle pointer events provided to the widget by BREW.

Button

ButtonTC is an implementation of IController that can be used by Button Widget to handle BREW pointerevents. It is used as the default touch controller for Button Widget if AEECLSID_OEMButtonTC is notfound.



The Button Touch Controller is instantiated by passing AEECLSID_ButtonTC intoISHELL_CreateInstance

When the default button touch controller receives a pointer down event, it begins to track the movementof the pointer and puts the button into a depressed (selected) state. If the pointer ever leaves thebounding rectangle of the button, it will revert to the 'natural' state until the pointer returns to the button'sconfines or the press is released (at which point the button will no longer capture touch events until it isonce again pressed). If the user releases the press within the confines of the button, it will count it as abutton press which will return the button to its natural state and send a EVT_MDL_WIDGETELM_CLICKevent out through the view model.

Check

CheckTC is an implementation of IController that is used by Check Widget and Radio Widgetto handle BREW pointer events. It is used as the default touch controller for these widgets ifAEECLSID_OEMButtonTC is not found.

The default Touch Controller for check and radio widgets is very simple. When it receives a pointer downfollowed by a pointer up within the extent of the bounding rectangle of the check or radio widget, it eithertoggles the value model of the widget (in the case of the Check widget) or sets the value model to true (inthe case of the radio button widget). The pointer may be moved throughout the widget canvas as long asthe pointer up occurs within the confines of the same widget who received the pointer down.

Container

ContainerTC is an implementation of IController that can be used by any Container to handle pointerevents provided to the widgets by Brew MP.

ContainerTC handles Brew MP pointer events for any type of Container and responds by:

• Moving focus between the children. On EVT_POINTER_DOWN, ContainerTC checks if the eventis for a child that does not currently have focus. If that is the case, it will ask the child widget if it cantake focus (using EVT_WDG_CANTAKEFOCUS) and move focus to this child widget, if it can takefocus. (This will result in EVT_MDL_FOCUS_CHANGE viewmodel event).

• Localizing all events and passing them to the child widgets. ContainerTC processes allEVT_POINTER_XXX events. After it determines the child widget to which the event needs to besent, it localizes the event in the child widget's co-ordinate system and passes it to that widget.

Note that the above ContainerTC behavior is implemented by containers themselves by default, i.e.Containers do not need any explicit controller for this behavior. A new instance of the ContainerTC classobject may be created by calling ISHELL_CreateInstance() and passing in AEECLSID_ContainerTC.

DateTime

DateTimeTC is an implementation of IController that is used by the Date and Time Widgetsto handle BREW pointer events. It is used as the default touch Contoller for these widget ifAEECLSID_OEMDateTimeTC is not concrete.

The default Touch Controller for date and time widgets performs two actions. The first, is that pressingthe pointer down on a date/time field will change the focus to that field. The second requires theDTWF_SHOWARROWS flag to have been applied to the date/time widget to which the controller isattached. In this case, holding the pointer down on the arrow will increment or decrement the value ofthe field in the date/time widget. If the pointer is continuously held down on the arrow, the increment ordecrement will continue repeatedly following a specified delay (the amount of time between the first andsecond repeat) and repeat rate (the amount of time between any successive repeats).



The Date Time Touch Controller is instantiated by passing AEECLSID_DateTimeTC intoISHELL_CreateInstance.

Grid container

GridContainerTC is an implementation of IController that can be used by GridContainer to handle pointerevents provided to the widget by BREW. GridContainerTC is an extension to ContainerTC that addsnotifications when clicks have occurred.

GridContainerTC performs the following three actions:

• Moving focus• Localizing the events for its children• Sending ViewModel notifications about click events. On first EVT_POINTER_DOWN,

GridContainerTC uses the viewmodel to notify with WECLTYPE_CLICK. If EVT_POINTER_DOWNhappens at the same time, and click count in the event is 2, then GridContainer notifies withWETYPE_DOUBLECLICK.

If the application wants to take advantage of this extended behavior, it can add a listener to theGridContainer's ViewModel and listen for EVT_MDL_WIDGETELEM_CLICK to know when an item wasclicked or double-clicked.

To create a Grid Container Touch Controller object, pass AEECLSID_GridContainerTC intoISHELL_CreateInstance.

List

ListTC is an implementation of IController that can be used by a List Widget to handle BREW pointerevents. It is used as the default touch controller for List Widget if AEECLSID_OEMListTC is not found.

The default list touch controller performs numerous operations based on the current state of the pointer.When it receives a EVT_POINTER_DOWN, the list immediately switches focus to the widget under thepointer. The behavior of the controller then varies based on whether or not LWF_LIVESCROLL has beenset. If Live Scroll has not been enabled, the focus will follow the pointer as it moves up and down acrossthe items. If Live Scroll has been enabled, the item clicked on will follow the pointer as it moves acrossthe screen. This gives the impression that the user is physically "dragging" the item (and the surroundingitems) across the list.

The List Touch Controller is instantiated by passing AEECLSID_ListTC into ISHELL_CreateInstance.

Radio

CheckTC is an implementation of IController that is used by Check Widget and Radio Widgetto handle BREW pointer events. It is used as the default touch controller for these widgets ifAEECLSID_OEMButtonTC is not found.

When the default Touch Controller for check and radio widgets receives a pointer down followed by apointer up within the extent of the bounding rectangle of the check or radio widget, it either toggles thevalue model of the widget (in the case of the Check widget) or sets the value model to true (in the case ofthe radio button widget). The pointer may be moved throughout the widget canvas as long as the pointerup occurs within the confines of the same widget who received the pointer down.

Root

RootTC is an implementation of IController that can be used by Root Container to handle pointer eventsprovided to the container by BREW. RootTC queries Touch observer to detect single tap occurrence on

Widgets Technology Guide for Developers Touch controller interfaces used


pointer down event and double tap occurrence on pointer up event and updates the pointer event stringprovided to the container by BREW with single/double tap information.

The Root Touch Controller is instantiated by passing AEECLSID_RootTC into ISHELL_CreateInstance.

Scroll

ScrollTC is an implementation of IController that can be used by ScrollbarWidget andScrollIndicatorWidget to handle pointer events provided to the widget by BREW.

The scroll touch controller is instantiated by passing AEECLSID_ScrollTC into ISHELL_CreateInstance.

Slider

SliderTC is an implementation of IController that can be used by SliderWidget to handle pointer eventsprovided to the widget by BREW.

The slider touch controller is instantiated by passing AEECLSID_SliderTC into ISHELL_CreateInstance.

Softkey

SoftkeyTC is an implementation of IController that can be used by Softkey Widget to handle pointerevents provided to the widget by BREW. SoftkeyTC handles BREW pointer events for a SoftkeyWidget and responds by listening to EVT_POINTER_DOWN and sending view model notification withWECLTYPE_CLICK.

The softkey touch controller is instantiated by passing AEECLSID_SoftkeyTC intoISHELL_CreateInstance.

Tab

TabTC is an implementation of IController that can be used by TabWidget to handle pointer eventsprovided to the widget by BREW.

The tab widget touch controller is instantiated by passing AEECLSID_TabTC intoISHELL_CreateInstance.

Touch controller interfaces usedTouch controllers use the IController interface.

IControllerThe controller interface provides object reference counting mechanisms that allow objects to managetheir own memory instances. In addition, the interface provides APIs for registering a handler with acontroller. All of the touch controllers are an implementation of IController.

Required Files

AEEIController.h

Interface ID

AEEIID_IController

Widgets Technology Guide for Developers Touch controller helper functions


Touch controller helper functionsFor more information on touch controller helper functions, see AEEWidgetTCProperties.h

Helper functions

IController_GetMaxLLMAngleRange

IController_SetMaxLLMAngleRange

IController_GetMinLiveScrollDist

IController_SetMinLiveScrollDist

IController_GetFlickStepTime

IController_SetFlickStepTime

IController_GetItemSelectionTimeout

IController_SetItemSelectionTimeout

IController_SetSettings

IController_SetScrollRepDelay

IController_GetScrollRepDelay

IController_SetScrollRepRate

IController_GetScrollRepRate

IController_SetWidgetPressedState

IController_GetWidgetPressedState

Using touch controllerWidgets instantiate touch controller when they receive an EnableTouch event.

When the root container gets EnableTouch events, it propagates the event to all children and to anywidgets inserted after touch has been enabled.

To enable touch support for all Widgets, the application calls IWidget_EnableTouch(), passing the IWidgetinterface object for the root container, as shown in this example:

nErr = ISHELL_CreateInstance(piShell, AEECLSID_RootContainer, (void**)&me->picRoot);if (AEE_SUCCESS == nErr) { nErr = IRootContainer_QueryInterface(me->picRoot, AEEIID_IWidget, (void**)&me->piwRoot);}if (AEE_SUCCESS == nErr) { nErr = IWidget_EnableTouch(piwRoot);}

An application can also disable touch support, using IWidget_DisableTouch on the root container.

An application can customize some default touch controller behavior by setting properties. For example,if an application wants to configure the minimum distance which a pointer should travel before the list

Widgets Technology Guide for Developers Text controller


starts flicking, then the application should retrieve the list touch controller from the list widget by usingIWidget_GetTouchController(), and then call IController_SetMinLiveScrollDist() to set the value.

Text controllerThe TextController is instantiated by passing AEECLSID_TextController into ISHELL_CreateInstance.

The TextController is reference counted. When you are done with your reference to the TextController,you should release that reference. Any controller specific cleanup will be handled for you when allreferences are released.

The default controller process involves the following steps.

1. The user presses the key, which generates an event.2. The event is passed to the text widget.3. The text widget asks the text controller to handle the event. If the event is not handled by the text

controller, then the text widget attempts to process the event internally.4. The text controller knows the current mode, so when the key press event is received, the text

controller cross-checks with the current mode and inserts an appropriate character in the text model.5. The text model sends an event to the text widget through its registered listeners. The text widget

(after doing all the internal processing) updates the screen.

Touch observerTouch observer analyzes pointer events, and stores pointer information such as movement, position,velocity and angle.

Widgets Technology Guide for Developers Touch observer interfaces used


Touch observer watches events like EVT_POINTER_DOWN, EVT_POINTER_MOVE andEVT_POINTER_UP, to analyze pointer movements. Controllers and applications can query the touchobserver for various properties that are recorded or derived, such as magnitude and angle of themovement, initial velocity, pointer up or pointer down information, or linear movement deviation.

The root container manages the touch observer instance. An application should query the root containerto retrieve the touch observer. The root container passes all the pointer events which it receives to thetouch observer.

The following diagram shows how widgets handle touch events and recognize gestures, illustrating theusage of touch observer with the root container.

Touchscreen events (EVT_POINTER_DOWN, EVT_POINTER_UP, EVT_POINTER_MOVE,EVT_POINTER_STALE_MOVE) come into the application from BREW's event queue via the applet'sIAPPLET_HandleEvent() function. The applet is generally expected to forward all events to the rootcontainer's _HandleEvent() function. The root container on page 9 is responsible for routing theevents to the proper widgets for handling. Unlike other events that are sent to the widget that hasfocus, pointer events are sent to the widget that was touched, based on the coordinates in the pointerevent. As the pointer events are propagated to the proper widget, they are "localized", or adjusted inrelation to the container/widget to which the event is being sent. Each widget has an associated TouchController associated with it that is responsible for processing the pointer events directed at the widgetand responding with updates to the UI. Depending on the gestures of interest to the touch controller,the touch controller would invoke APIs on the touch observer to start and stop observation, and get theobserved gesture. The touch observer is the entity responsible for recognizing gestures.

Touch observer interfaces usedThe touch observer is an implementation of IObserver.

Widgets Technology Guide for Developers Touch observer helper functions


For more information on the API listed below, see the C/C++ API Reference.

IObserverIObserver is a simple interface that inherits the IHandler and its reference is kept within the RootContainer. It analyzes touch events, and can also be used to get information about touch events, andget or set touch observer properties. Widgets and controllers query IObserver to get information aboutevents.

Required Files

AEEIObserver.h

Interface ID

AEEIID_IObserver

Touch observer helper functions

Helper functions

IObserver_GetDoubleTap

IObserver_GetLastPointerDownEvent

IObserver_GetLastPointerUpEvent

IObserver_GetLLMAngle

IObserver_GetLLMDist

IObserver_GetLLMSpeed

IObserver_GetLLMTime

IObserver_SetMaxTapDelay

IObserver_SetMaxTapXDif

IObserver_SetMaxTapYDif

IObserver_SetPointerEvtExpirationTimer

IObserver_SetProperty

IObserver_SetPropertyEx

IObserver_GetMaxDoubleTapDelay

IObserver_GetMaxDoubleTapXDif

IObserver_GetMaxDoubleTapYDif

IObserver_GetObservation

IObserver_GetPointerEvtExpirationTimer

IObserver_GetProperty

IObserver_GetPropertyEx

IObserver_GetSingleTap

IObserver_SetHandler

IObserver_SetMaxDoubleTapDelay

Widgets Technology Guide for Developers Using touch observer


IObserver_SetMaxDoubleTapXDif

IObserver_SetMaxDoubleTapYDif

List related APIs (TOUCHOBSF_LLM)• IObserver_GetLLMAngle• IObserver_GetLLMDist• IObserver_GetLLMTime• IObserver_GetLLMSpeed

Tap related APIs (TOUCHOBSF_TAP)• IObserver_GetSingleTap• IObserver_GetLastPointerUpEvent• IObserver_GetLastPointerDownEvent• IObserver_GetMaxTapDelay• IObserver_SetMaxTapDelay• IObserver_GetMaxTapXDif• IObserver_SetMaxTapXDif• IObserver_GetMaxTapYDif• IObserver_SetMaxTapYDif

Double tap related APIs (TOUCHOBSF_DBLTAP)• IObserver_GetDoubleTap• IObserver_GetMaxDoubleTapDelay• IObserver_SetMaxDoubleTapDelay• IObserver_GetMaxDoubleTapXDif• IObserver_SetMaxDoubleTapXDif• IObserver_GetMaxDoubleTapYDif• IObserver_SetMaxDoubleTapYDif

Observer related APIs• IObserver_StartObservation• IObserver_StopObservation• IObserver_GetObservation• IObserver_GetPointerEvtExpirationTimer• IObserver_SetPointerEvtExpirationTimer

Using touch observerBefore an application can query the Touch Observer, it must query the root container to obtain the TouchObserver object by using IWidget_GetTouchObserver().

nErr = IWidget_GetTouchObserver(piwRoot, &pito);

After obtaining the Touch Observer object, the application can start observation, retrieve informationabout the Touch Observer or gestures, and stop observation.

Starting observation

There are five types of gestures that can be observed.

• Last linear movement determination (TOUCHOBSF_LLM)

Widgets Technology Guide for Developers Transitions


• Tap (TOUCHOBSF_TAP)• Double tap (TOUCHOBSF_DBLTAP)• TOUCHOBSF_TAPANDHOLD• TOUCHOBSF_MULT_LM

To retrieve information about a gesture, an application needs to call IObserver_StartObservation() for thatparticular gesture. For example, to start observing the last linear determination and double tap, make thefollowing calls:

nErr = IObserver_StartObservation(pif, TOUCHOBSF_LLM);if (AEE_SUCCESS == nErr) { nErr = IObserver_StartObservation(pif, TOUCHOBSF_DBLTAP);}

To check which gestures the Touch Observer is monitoring, call IObserver_GetObservation(), as follows:

nErr = IObserver_GetObservation(pif, &observe);

Retrieving information

To retrieve specific information about a gesture, an application can call one of the IObserver APIsassociated with the gesture. For more information on IObserver APIs, see touch observer interfaces usedon page 29.

Stopping observation

When an application is finished with observation, it should stop the observation, as follows:

nErr = IObserver_StopObservation(pif, TOUCHOBSF_LLM); if (AEE_SUCCESS == nErr) { IObserver_StopObservation(pif, TOUCHOBSF_DBLTAP);}

For more information please refer to the document How to handle tap and double tap, on the Brew MPweb site.

TransitionsTransitions apply a given effect over a period of time.

The base transition2 interface is an interface from which transition implementations should be based. Thetransition2 interface acts as timed event that can be used to schedule events or can be used as a gradualmodifier of another object, providing a special visual effect to the object it wraps. For example, a transitioncould create the effect of an object disappearing into a cloud of smoke. Five basic transitions are providedby default: fader transition, mover transition, scaler transition, scroller transition and resizer transition.

Each transition implementation is defined by its effect and duration. For example, the mover transition hasthe effect of moving a wrapped object from one point to another over a specific period of time. Likewise,the fader transition has the effect of applying a fade out effect to a wrapped object, over some periodof time. The interface provides APIs for stepping a transition effect and supplying notification at thecompletion of a transition effect. A transition is a passive object; it will not do anything on its own. In orderto progress through a transition, it must be inserted within a transition manager or be manually stepped byan application. The manager is responsible for sending the step events to the transition.

Widgets Technology Guide for Developers Transition manager


Transition managerTransition manager helps improve performance for transitions running in parallel or series.

The base ITransitionMgr interface is an interface from which a transition manager implementation shouldbe based. The ITransitionMgr interface is responsible for managing a collection of transition2 objects,resulting in consolidated updates across multiple transitions. This optimizes performance when resultingtransition updates occur, such as invalidates and draws with Widget objects.

A transition manager updates all managed transitions via step calls. This will occur when the timer expiresif the manager is in active mode, or when it is stepped by another manager in passive mode. Transitionswill be kept in the manager until they report their completion. A transition that is set to repeat will bereset and kept in the manager. KeepTransitions mode is used when the manager should keep track oftransitions that have been completed. Combining this mode with managers and transitions set to repeatallows complex series of transitions to be looped through.

A transition manager is also an ITransition2 object, and it can receive step calls from another manager.Although any manager may be set in active mode, it is recommended that non-critical manager beinserted within the root container's transition manager to maintain performance. A passive manager willsimply step through all its internal transitions based on the offset provided by its overarching manager.

Using transition manager

The default transition manager implements all the functionality described by the ITransitionMgr interface.A manager that is not explicitly initialized will have its step time set to the default value and memorymode will be turned off. Transitions may be added to the manager by using ITransitionMgr_Add().Although a transition manager is also a transition, there are some properties of transitions that do notapply to the manager; for example PROP_STEPS and PROP_RUNTIME. The manager will returnAEE_ECLASSNOTSUPPORT if one of the unsupported properties is queried. A manager set to activemode will put itself to sleep if there are no transitions left in its queue. If the manager is in passive mode,it will return ITransition2_STATUS_STEP_DONE, and therefore may be cleaned up by its top manager.It is therefore recommended to fully populate a manager before starting it or inserting it within anothermanager.

To create a transition manager, an application would do the following:

1. Call ISHELL_CreateInstance() with a ClassID of AEECLSID_TransitionMgr to retrieve a referencecounted instance of the transition manager.

2. Insert transitions into the manager via ITransitionMgr_Add().3. Call ITransitionMgr_Start() to start the manager in master mode.4. Call ITransitionMgr_Insert() to insert the manager into another manager.

This class will free itself if the reference count reaches zero. Queued transitions will be released.

Transition typesThe mover, fader, resizer, scaler, and scroller transition types are described below.

Please not that it is recommended to insert noncritical transitions within the root container's transitionmanager to maintain performance. Applications can query the root container to get the transition managerinstance by using IWidget_GetTransitionMgr(). Applications can use this transition manager instead ofcreating one.

Widgets Technology Guide for Developers Transition helper functions


Mover

The mover transition moves a widget across a specified path, or animates an object across the display.For example, an application could wrap a mover transition around an image widget, then begin movingthat images vertically, horizontally or diagonally across the display, specifying each movement as a seriesof point-to-point destinations. The mover transition places the target object at a particular location (relativeto a container that defines the movement's coordinate plane), then gradually moves the target object in alinear manner to a final destination location. For this transition to work properly, the target widget must bethe direct child of XY Container.

Fader

The fader transition applies a visual fade in/out effect to the widget it wraps. For example, a popup menucould be wrapped by a fader. Once dismissed, the fader could be instructed to fade out the wrappedpopup over some period of time. As the fade out effect begins, the wrapped popup would be drawn withan initial level of transparency (which could, initially, be fully opaque), and then would gradually loseopacity until it reached a final level of transparency.

Resizer

The resizer transition modifies the size of an object over time. For example, an application could wrap aresizer transition around a menu item, and have the selection grow when the user selects it. The resizertransition will gradually modify the size of the target in a linear manner to reach the final desired size. Forthis transition to work properly, the target widget must support SetExtent. For example, a widget usingproportional extents in a prop container would be able to use this effect.

Scaler

The scaler transition modifies the scale of an object over time. Unlike the resizer transition which modifiesthe extent of a widget, the scaler modifies the size of the target. For example, an application could wrapa scaler transition around an menu item, and have the selection grow when the user selects it. The scalertransition will gradually modify the scale of the target in a linear manner to reach the final desired size. Forthis transition to work properly, the target widget must support IPARM_SCALE. This is usually supportedby images.

Scroller

The scroller transition sends scroll events to an object over time. For example, a list could start a scrollerif the "up" key is pressed long enough, or when the user flick a finger across the screen. An applicationcould also use the scroller to create a slot-machine roulette. The scroller transition will keep sendingscroll events with the scroll distance decreasing or increasing based upon the provided accelerationfactor until it reaches zero. This transition is initialized by specifying initial velocity, acceleration and scrolldirection. While the transition is running, it will calculate the new offset, based on velocity, accelerationand direction of scroll, and it will send a scroll event calls to the target widget. Please note that for thistransition to work, the widget on which scroller transition is running should have a valid reference for theduration of the transition (the transition does not addref the widget), and the target widget must supportEVT_WDG_SCROLL.

Transition helper functionsFor more information on transition helper functions. see AEETransition2Helpers.h

Widgets Technology Guide for Developers Using Transitions


Helper functions

ITransition2_GetSteps

ITransition2_SetSteps

ITransition2_GetRuntime

ITransition2_SetRuntime

ITransition2_GetStepTime

ITransition2_SetStepTime

ITransition2_GetStepMode

ITransition2_SetStepMode

ITransition2_GetEndAction

ITransition2_SetEndAction

ITransition2_GetCurrentStep

ITransition2_SetCurrentStep

ITransition2_GetCurrentTime

ITransition2_SetCurrentTime

ITransition2_OnStep

ITransition2_OnStart

ITransition2_OnEnd

ITransition2_GetWidget

ITransition2_SetWidget

ITransition2_GetBitmap

ITransition2_SetBitmap

ITransition2_GetContainer

ITransition2_SetContainer

ITransition2_GetDescriptor

ITransition2_SetDescriptor

Using Transitions

Using mover

To create a mover transition, an application would do the following.

1. Create the object that will be the target of the mover transition2. Call ISHELL_CreateInstance () with a ClassID of AEECLSID_Transition2_Mover to retrieve a

reference counted instance of the mover transition.3. Call Transition2Mover_Init () to setup the initialize the mover's custom properties, including the

widget it is to wrap, the container holding the widget, and the starting and ending coordinates.4. Call ITransitionMgr_Add () to add the transition to a manager.

Widgets Technology Guide for Developers Widgets


Using fader

To create a fader transition, an application would do the following

1. Create the object that will be the target of the fader transition2. Call ISHELL_CreateInstance() with a ClassID of AEECLSID_TRANSITION2_FADER to retrieve a

reference counted instance of the fader transition.3. Call Transition2Fader_Init() to setup and initialize the fader's custom properties, including the target

widget and the start/end alpha values.4. Call ITransitionMgr_Add() to add the transition to a manager.

Using resizer

To create a resizer transition, an application would do the following.

1. Create the object that will be the target of the resizer transition.2. Call ISHELL_CreateInstance() with a ClassID of AEECLSID_TRANSITION2_RESIZER to retrieve a

reference counted instance of the resizer transition.3. Call Transition2Resizer_Init() to setup and initialize the resizer's custom properties, including the

widget it is to wrap and the start/end width and height.4. Call ITransitionMgr_Add() to add the transition to a manager.

Using scaler

To create a scaler transition, an application would do the following.

1. Create the object that will be the target of the scaler transition2. Call ISHELL_CreateInstance() with a ClassID of AEECLSID_TRANSITION2_SCALER to retrieve a

reference counted instance of the scaler transition.3. Call Transition2Scaler_Init() to setup and initialize the scaler's custom properties, including the

widget it is to wrap and the start/end x and y scales.4. Call ITransitionMgr_Add() to add the transition to a manager.

Using scroller

To create a scoller transition, an application would do the following.

1. Create the object that will be the target of the scroller transition2. Call ISHELL_CreateInstance() with a ClassID of AEECLSID_TRANSITION2_SCROLLER to retrieve

a reference counted instance of the scroller transition.3. Call Transition2Scroller_Init() to setup and initialize the scroller's custom properties, including the

widget it is to wrap, the starting speed, the acceleration, and the direction.4. Call ITransitionMgr_Add() to add the transition to a manager.

WidgetsThis section covers the following widgets:

• Bitmap widget• Blend widget• Border widget• Button widget• Caret widget• Check widget• Cursor widget• Date and time widget



• Frame widget• HTML widget• Image static widget• Image widget• List, pick and grid widget• Progress widget• Scrollbar and scroll indicator widget• Slider widget• Softkey widget• Static widget• Tab widget• Text widget• Title widget• Viewport widget

For additional information, see the C/C++ API Reference.

Widget header files are located at platform\ui\inc in the Brew MP SDK.

Bitmap widget

The Bitmap widget is used to display a bitmap image on the display.

For additional information, refer to the C/C++ API Reference.

Files to include:

Header File ClassID File

AEEBitmapWidget.h AEEBitmapWidget.bid

An example of the bitmap widget in use is shown in the form of a cursor widget that shows the system isprocessing the current request.



Bitmap widget helper functions

Helper function

IWidget_GetTranspColor

IWidget_SetTranspColor

Bitmap widget interfaces used

Bitmap widget uses the IWidget and IBitmap interfaces.

IWidgetThe IWidget interface provides many common controls, and can used as a base class for new customwidgets and UI objects.

Required Files

AEEIModel.h

AEEIHandler.bid



AEEICanvas.h

AEEStdErr.h

Interface ID

AEEIID_IWidget

IBitmapThis interface provides a way to manipulate bitmaps. Each IBitmap instance represents a bitmap.

Required Files

AEEIBitmap.h

Interface ID

AEEIID_IBitmap

Using bitmap widget

A new instance of the bitmap widget class object may be created by calling ISHELL_CreateInstance() andpassing in AEECLSID_BitmapWidget.

1. Call ISHELL_CreateInstance() with a ClassID of AEECLSID_BitmapWidget to retrieve a referencecounted instance of the bitmap widget.

2. Call IWidget_SetBitmap() to identify the IBitmap image to be displayed by the widget, passing in apointer to the IBitmap image to be displayed.

3. If the bitmap is to be displayed with transparency, call IWidget_SetTranspColor() passing in theRGB value of the transparency color.

4. Applications specify the bitmap to be displayed in the widget by calling IWidget_SetBitmap(),passing in a pointer to the IBitmap image to be displayed.

The image itself will be displayed with its origin at the top-left corner of the widget's destinationrectangle, cropped to the width and height of the widget's extent. The image is neither stretched,shrunk nor scaled to fit into the destination rectangle. See the C/C++ API Reference for flags thatcan alter the alignment of the bitmap image within the widget's destination rectangle.

The bitmap widget relies on an interface model that represents its data as a pointer to an IBitmapdata structure. The model stores only a pointer to the bitmap, not a copy of the bitmap itself, andshould always return this pointer in response to data queries from a client widget.

A default model is created and assigned to the widget when the widget is created withISHELL_CreateInstance(). The client can replace the widget's model at any time with the method:IWidget_SetModel(), as long as the supplied model interface is of the type that the widget expects.

Blend widget

This is a decorator widget that is used as a visual filter through which a child widget is blended to thedisplay. An example of the blend widget is shown in the bitmap widget example. The background imageis using the blend capability of the blend widget to appear slightly muted.


Files to include:



Header file ClassID file

none AEEBlendWidget.bid

Blend widget interfaces used

Blend widget uses the IWidget interface.


Required Files

AEEIModel.h

AEEIHandler.bid

AEEICanvas.h

AEEStdErr.h



Interface ID

AEEIID_IWidget

Blend widget helper functions

Helper functions

IWidget_GetTransparency

IWidget_SetTransparency

IWidget_GetAlpha

IWidget_SetAlpha

IWidget_GetBufferedStatus

IWidget_SetBufferedStatus

Using blend widget

A blend widget is created by calling ISHELL_CreateInstance() and passing AEECLSID_BlendWidget asthe ClassID. If successful, a pointer to the blend widget object will be returned in the ppobj parameter ofISHELL_CreateInstance().

Applications may control the degree to which the underlying widget will be blended by setting thePROP_TRANSPARENCY property of the blend widget. A PROP_TRANSPARENCY value of 0 wouldproduce a fully opaque result. A value of 1 would add a small degree of transparency to the widget. AValue of up to 255 can be used. 255 would render the widget completely transparent, or invisible. Thedefault is to apply a completely transparent blend. Setting the PROP_TRANSPARENCY on a blendwidget will invalidate the widget's parent container.

To create a blend widget, an application would do the following.

1. Call ISHELL_CreateInstance() with a ClassID of AEECLSID_BlendWidget to retrieve a referencecounted instance of the blend widget.

ISHELL_CreateInstance(me->piShell, AEECLSID_BlendWidget, (void**)&piwBlend);

2. If the blend widget is to be displayed with a degree of transparency, callIWidget_SetTransparency().

Once a blend widget has been created, it can be used to affect the display of other widgets. Continuingthe example above, the newly created blend widget could be attached as a decorator to the child widgetyou want to display with some level of transparency.

Border widget

Border widget is a decorator widget used to draw borders and backgrounds for widgets. The borderframes the widget's content rectangle.

Although most widgets now natively support borders, a border widget could be used to provide additionalborder effects. For example, an application could implement a focus effect on a widget by adding a two



pixel gray active border widget around the normal two pixel black border set on the widget. This allowsyou to have a multi-colored focused border instead of the default, which will just change the size andcolor.

Properties

The following properties define color, transparency, width, style, gradients, rounded corners, backgroundimage, and shadow:

• PROP_BORDERSTYLE - sets or retrieves the display style of the border.• PROP_BORDERWIDTH - sets or retrieves the width of the border.• PROP_ACTIVE_BORDERWIDTH - sets or retrieves the width that the border will display with when

the widget is the active state (has focus).• PROP_INACTIVE_BORDERWIDTH - sets or retrieves the width that the border will display with

when the widget is in the inactive state (does not have focus).• PROP_BORDERRADIUS - sets or retrieves the radius that will be used by the border when it is in

the BORDERSTYLE_ROUNDED mode. This value is constrained to be between 0 and one-half ofthe smaller of the border's height and width.

• PROP_BORDERCOLOR - sets or retrieves the color that will be used to display the border for allstates of the widget. If the widget uses multiple border colors, PROP_BORDERCOLOR will retrievethe color that is used in the active, unselected state.

• PROP_ACTIVE_BORDERCOLOR - sets or retrieves the color that will be used to display the borderwhen it is in the active, unselected state.

• PROP_INACTIVE_BORDERCOLOR - sets or retrieves the color that will be used to display theborder when it is in the inactive, unselected state.

• PROP_SELECTED_BORDERCOLOR - sets or retrieves the color that will be used to display theborder when it is in either of the selected states. If differing colors have been set for the SACTIVEand SINACTIVE states, the SACTIVE color will be retrieved.

• PROP_SACTIVE_BORDERCOLOR - sets or retrieves the color that will be used by the widgetwhen it is in the selected, active state.

• PROP_SINACTIVE_BORDERCOLOR - sets or retrieves the color that will be used by the widgetwhen it is in the selected, inactive state.


Files to include:


none AEEBorderWidget.bid

The border widget is presented around the progress dialog and the progress bar.



Border widget helper functions

Helper functions

IWidget_GetViewModel

IWidget_SetViewModel

IWidget_GetPropertyEx

IWidget_SetPropertyEx

IWidget_GetTouchController

IWidget_SetTouchController

IWidget_GetUserData

IWidget_SetUserData

IWidget_GetTouchMode

IWidget_SetTouchMode

IWidget_SetBorderStyle

IWidget_GetBorderStyle



Helper functions

IWidget_SetBorderWidth

IWidget_GetBorderWidth

IWidget_SetActiveBorderWidth

IWidget_GetActiveBorderWidth

IWidget_SetInactiveBorderWidth

IWidget_GetInactiveBorderWidth

IWidget_SetBorderRadius

IWidget_GetBorderRadius

IWidget_SetBorderColor

IWidget_SetActiveBorderColor

IWidget_GetActiveBorderColor

IWidget_SetInactiveBorderColor

IWidget_GetInactiveBorderColor

IWidget_SetSelectedBorderColor

IWidget_SetSelectedActiveBorderColor

IWidget_GetSelectedActiveBorderColor

IWidget_SetSelectedInactiveBorderColor

IWidget_GetSelectedInactiveBorderColor

IWidget_SetBorderTransparency

IWidget_GetBorderTransparency

IWidget_SetPadding

IWidget_SetLeftPadding

IWidget_GetLeftPadding

IWidget_SetRightPadding

IWidget_GetRightPadding

IWidget_SetTopPadding

IWidget_GetTopPadding

IWidget_SetBottomPadding

IWidget_GetBottomPadding

IWidget_SetShadowOffset

Widget_SetShadowOffsetX

IWidget_GetShadowOffsetX

IWidget_SetShadowOffsetY

IWidget_GetShadowOffsetY

IWidget_SetShadowColor



Helper functions

IWidget_GetShadowColor

IWidget_SetSelectedShadowOffset

IWidget_SetSelectedShadowOffsetX

IWidget_GetSelectedShadowOffsetX

IWidget_SetSelectedShadowOffsetY

IWidget_SetSelectedShadowOffsetY

IWidget_SetSelectedShadowColor

IWidget_SetBGColor

IWidget_SetActiveBGColor

IWidget_GetActiveBGColor

IWidget_SetInactiveBGColor

IWidget_GetInactiveBGColor

IWidget_SetSelectedBGColor

IWidget_SetSelectedActiveBGColor

IWidget_GetSelectedActiveBGColor

IWidget_SetSelectedInactiveBGColor

IWidget_GetSelectedInactiveBGColor

IWidget_SetTransparency

IWidget_SetBGTransparency

IWidget_GetTransparency

IWidget_GetBGTransparency

IWidget_SetGradientStyle

IWidget_SetGradientColor

IWidget_SetActiveGradientColor

IWidget_SetInactiveGradientColor

IWidget_SetSelectedGradientColor

IWidget_SetSelectedActiveGradientColor

IWidget_SetSelectedInactiveGradientColor

IWidget_SetBGImage

IWidget_GetBGImage

IWidget_SetBGImageFlags

IWidget_GetBGImageFlags

IWidget_SetBGImageParms

IWidget_SetBGImageAnimate

IWidget_SetBGImageAnimateFlags



Helper functions

IWidget_GetBGImageAnimateFlags

IWidget_SetBGImageTiledBorder

IWidget_SetBGImageFrame

Border widget interfaces used

Border widget uses the IWidget and IImage interfaces.


Required Files

AEEIModel.h

AEEIHandler.bid

AEEICanvas.h

AEEStdErr.h

Interface ID

AEEIID_IWidget

IImageThe IImage Interface is used for drawing bitmap images and displaying animated bitmaps to the screen.

Required Files

AEEImage.h

Interface ID

AEEIID_IImage

Using border widget

The border widget is instantiated by passing AEECLSID_BorderWidget into ISHELL_CreateInstance().

ISHELL_CreateInstance(me->piShell, AEECLSID_BorderWidget, (void**)&piwSpacer1)#define toolbox_insert_spacer(piw) ERR_TRY(SceneApp_IPropContainer_InsertEx (picToolboxProp,piw,1,TRUE))toolbox_insert_spacer(piwSpacer1);

Applications can customize border properties like color, background, shadow, gradient etc using thehelper functions.



Button widget

This is a decorator widget that is used to provide the look and feel of a button.

Button widget supports the border widget properties and functions, and decorates a given widget.


Files to include:


none AEEButtonWidget.bid

Button widget interfaces used

Button widget uses the IWidget and IImage interfaces.

IWidget



The IWidget interface provides many common controls, and can used as a base class for new customwidgets and UI objects.

Required Files

AEEIModel.h

AEEIHandler.bid

AEEICanvas.h

AEEStdErr.h

Interface ID

AEEIID_IWidget

IImageThe IImage Interface is used for drawing bitmap images and displaying animated bitmaps to the screen.

Required Files

AEEImage.h

Interface ID

AEEIID_IImage

Button widget helper functions

Helper functions





IWidget_GetTouchController

IWidget_SetTouchController

IWidget_GetUserData

IWidget_SetUserData

IWidget_GetTouchMode

IWidget_SetTouchMode

Using button widget

The button widget is instantiated by passing AEECLSID_ButtonWidget into ISHELL_CreateInstance.



The button widget is derived from the border widget class (AEECLSID_BorderWidget) and supports allproperties and functions supported by the border widget class. The button widget acts as a decorator todecorate a given widget to give it the look and feel of a button.

The following code implements a button widget.

//---------------------------------------------------------------// ButtonWidget//---------------------------------------------------------------

#define HI_INT16(l) (int16)((l) >> 16)#define LO_INT16(l) (int16)((l) & 0xFFFF)

// get pointer to vtbl from object allocated w/ MALLOCREC_VTBL

#define BUTTON_OFFSETX 1#define BUTTON_OFFSETY 1

static int SampleTouchApp_IShell_CreateButtonWidget(IShell *piShell, IWidget **ppo, const AECHAR *pwszText, int nWidth);{ IController *pitc = NULL; WidgetExtent we; int nErr = AEE_SUCCESS;

// button widget is actually a static widget ERR_TRY( ISHELL_CreateInstance(piShell, AEECLSID_StaticWidget, (void**)ppo) );

// setup button widget ERR_TRY( IWidget_SetText(*ppo, pwszText, 0)); ERR_TRY( IWidget_SetFontClass(*ppo, AEECLSID_FONTSYSBOLD)); ERR_TRY( IWidget_SetFlags(*ppo, IDF_ALIGN_CENTER|IDF_ALIGN_MIDDLE)); ERR_TRY( IWidget_SetBorderWidth(*ppo, 2)); ERR_TRY( IWidget_SetBorderStyle(*ppo, BORDERSTYLE_ROUNDED)); ERR_TRY( IWidget_SetBorderRadius(*ppo, 12)); ERR_TRY( IWidget_SetPadding(*ppo, 1));

ERR_TRY( IWidget_SetShadowOffsetX(*ppo, BUTTON_OFFSETX)); ERR_TRY( IWidget_SetSelectedShadowOffsetX(*ppo, -BUTTON_OFFSETX)); ERR_TRY( IWidget_SetShadowOffsetY(*ppo, BUTTON_OFFSETY)); ERR_TRY( IWidget_SetSelectedShadowOffsetY(*ppo, -BUTTON_OFFSETY));

ERR_TRY( IWidget_SetGradientStyle(*ppo, GRADIENT_STYLE_HORZ));

ERR_TRY( IWidget_SetBorderColor(*ppo, RGB_DLGBUTTON_BDR)); ERR_TRY( IWidget_SetSelectedBorderColor(*ppo, RGB_DLGBUTTON_SELBDR));

ERR_TRY( IWidget_SetBGColor(*ppo, RGB_DLGBUTTON_BG)); ERR_TRY( IWidget_SetGradientColor(*ppo, PROP_GRADIENT, RGB_DLGBUTTON_BGEND));

ERR_TRY( IWidget_SetSelectedBGColor(*ppo, RGB_DLGBUTTON_SELBG)); ERR_TRY( IWidget_SetSelectedGradientColor(*ppo, PROP_SELECTED_GRADIENT, RGB_DLGBUTTON_SELBGEND));

ERR_TRY( IWidget_SetFGColor(*ppo, RGB_DLGBUTTON_FG)); ERR_TRY( IWidget_SetSelectedFGColor(*ppo, RGB_DLGBUTTON_SELFG));

IWidget_GetPreferredExtent(*ppo, &we); if (nWidth > 0) { we.width = nWidth; } IWidget_SetExtent(*ppo, &we);

ERR_TRY( ISHELL_CreateInstance(piShell, AEECLSID_BUTTONTC,



(void **)&pitc)); ERR_TRY( IWidget_SetTouchController(*ppo, pitc) );

ERR_CATCH: RELEASEIF(pitc); return nErr;}

Caret widget

This widget is typically used to indicate where the next character will be inserted within a text widget.


Files to include:


AEECaretWidget.h AEECaretWidget.bid

This is the caret widget at the end of the body of an email message.

Caret widget interfaces used

Caret widget uses the IWidget interface.




Required Files

AEEIModel.h

AEEIHandler.bid

AEEICanvas.h

AEEStdErr.h

Interface ID

AEEIID_IWidget

Caret widget helper functions

Helper functions

IWidget_SetFGColor

IWidget_SetBGColor

IWidget_GetCaretPulse

IWidget_SetCaretPulse

IWidget_GetAnimateFlags

IWidget_SetAnimateFlags

IWidget_GetOffsetX

IWidget_SetOffsetX

IWidget_GetOffsetY

IWidget_SetOffsetY

Using caret widget

The caret widget is used to display a text marker inside other widgets to indicate where the next characterwill be inserted.

It is most commonly used by the text widget. The caret widget exposes properties for setting its colorand pulse rate (i.e. blinking caret). An OEM may further customize the appearance of all carets using theAEECLSID_CaretWidget ClassID.

Any widget that wishes to contain a caret widget should try to instantiate it using a call toISHELL_CreateInstance() with the ClassID of AEECLSID_CaretWidget.



Check widget

The check widget is derived from the widget object and comes in two types, checkboxes and radiobuttons.

• Checkbox indicates an on or off state. The appearance depends on the checkbox value (checked/unchecked) and activation state (active/inactive).

• Radio button allows users to select from a group of choices. Appearance depends on the radiobutton's value (selected/unselected) and activation state (active/inactive)

By default, checkboxes are drawn as a square box at the origin of the widget's bounding rectangle withtwo modifications based on the checkbox's current state. If the checkbox has been selected, a checkmarkis drawn within the bounding rectangle, and if the checkbox currently has focus, it will draw an externalborder around the outside to draw attention. Radio buttons are drawn as a circle at the origin of thewidget's bounding rectangle and vary in a manner that is similar to checkboxes.

Checkboxes and radio buttons are attached to value models, which store the widget's state (on oroff) as a boolean value. Applications can identify and assign a specific value model to each widget atthe time it is created, or can choose instead to use the default IValueModel implementation managedby the check widget class. Radio buttons should additionally be attached to a view model that willmanage the association of a group of radio buttons. The model functions as a notifier, sendingEVT_MDL_GROUP_ITEMACTIVE events to each listening radio button as the user changes the currentselection. The widgets in a radio button group should, therefore, be created to all share the samemanaging view model.

For additional information, refer to the C/C++ API Reference, How to group radio buttons, and How toattach view model and handle model events, on the Brew MP web site.

Files to include:

Header file ClassID file for Checkbox ClassID file for radio button

none AEECheckWidget.bid AEERadioWidget.bid

An example of the checkbox and radio button widgets in use is shown. The box next to the text "Copysent messages" is a checkbox. The circles next to the text "Send now" and "Send on exit" are radiobuttons in a group.



Check widget interfaces used

Check widget uses the IWIdget interface.


Required Files

AEEIModel.h

AEEIHandler.bid

AEEICanvas.h

AEEStdErr.h

Interface ID

AEEIID_IWidget



Check widget helper functions

Helper functions

IWidget_SetPropImageStrip

IWidget_GetNFrames

IWidget_GetNFrames

IWidget_GetSelected

IWidget_SetSelected



Using check widget

The check widget is instantiated by passing AEECLSID_CheckWidget into ISHELL_CreateInstance. Theradio widget is similarly created by passing AEECLSID_RadioWidget into ISHELL_CreateInstance.

The default images used to represent each of the states associated with a checkbox or radio button arestored as resources in the 'widgets.mif' file. One resource is used to represent various portions of thewidget and has 3 frames associated with it: the check mark, the inactive border, and the active border.These images may be overridden using the PROP_IMAGESTRIP property to specify a new bitmap to beused as the image frames.

Group buttons can be grouped using a single view model.

IValueModel_GetBool() IValueModel_SetBool() // Register listener with value model

The text that usually accompanies a checkbox or radio button is not part of the checkbox or radio widget.Applications must separately create a static text widget and position that widget alongside the checkboxor radio button in order to create the appearance of a button followed by text.

Check widget's support of border properties can be used to create a distinctive appearance. For example,an application could set PROP_IMAGE_NFRAMES to 1 via IWidget_SetNFrames(), which only appliesan extra image when the widget is checked. It could then set the widget background to a color gradientand use the border properties to give the widget a shadow to create a 3D effect.

The following is an example of creating a check widget.

ERR_TRY( ISHELL_CreateInstance(piShell, AEECLSID_CheckWidget, (void**)&piwCheck) );ERR_TRY( IWidget_GetModel(piwCheck, AEEIID_IValueModel, (IModel**)(void**)&pivmCheck) );LISTENER_Init(pmlCheck, c_backlight_app_CheckCallback, pibl);IBACKLIGHT_AddRef(pibl);IValueModel_SetBool(pivmCheck, bEnabled);IValueModel_AddListener(pivmCheck, pmlCheck);



Cursor widget

This widget is typically used to indicate progress or a period to wait. An example of the cursor widget isthe hour glass.


Files to include:


AEECursorWidget.h AEECursorWidget.bid

Cursor widget helper functions

Helper functions



Helper functions

Cursor widget interfaces used

Cursor widget uses the IWidget interface.


Required Files

AEEIModel.h

AEEIHandler.bid

AEEICanvas.h

AEEStdErr.h

Interface ID

AEEIID_IWidget

Using cursor widget

A cursor widget is created by calling ISHELL_CreateInstance() and passing AEECLSID_CursorWidget asthe ClassID.

If successful, a pointer to the cursor widget object will be returned in the ppobj parameter ofISHELL_CreateInstance.

The cursor widget is derived from the decorator object and is used to show or hide an element on screen(the cursor). It is typically used in BREW as an overlay to show progress (such as a spinning beach ball)or a period to wait (such as a watch or an hourglass).

The cursor widget can also be used to track user-directed movements of a visual pointer on the display.

The bitmap used to represent the default cursor is stored as resource ID 100 in the "widgets.mif" file. Thedefault bitmap could be overridden by retrieving an alternate bitmap and assigning it to the cursor widgetby calling IWidget_SetBitmap().

To create a cursor widget, an application would do the following.

1. Call ISHELL_CreateInstance() with a ClassID of AEECLSID_CursorWidget to retrieve a referencecounted instance of the cursor widget.

2. If a bitmap other than the default cursor is to be displayed, the application should callIWidget_SetBitmap() on the cursor widget, passing in a pointer to the desired graphic.

Date and time widget

The date and time widget is used to display/set a date/time variable. The format can be specified by aformat pattern string or an ILocale object. The field order and delimiter are configurable.




Files to include:

Header file ClassID file for date widget ClassID file for time widget

AEEDateTimeWidget.h AEEJulianDateWidget.bid AEEJulianTimeWidget.bid

An example of the date and time widgets in use is shown here.

This document describes two similar widgets -- a date widget and a time widget -- each of which is usedto display and set a date/time variable. These widgets share common behaviors, such as how theyhandle events or interact with their attached model, but differ in what fields they contain and what datathey expose from their model.

Features common to both the date and time widgets:

• Automatic field verification and date/time validation.• Field order is configurable• Fields specified by a format pattern string or ILocale object• Field delimiter specified by a string or ILocale object• Value model updating and notification performed in two different configurable modes, on field

change or on focus change.• Fields auto-incremented and decremented with the up/down arrow keys.



The julian date and julian time widgets rely on a value model that contains a julian date structure (ratherthan a uint32) representing the date and time. A default model is created and assigned to the widgetwhen the widget is created with ISHELL_CreateInstance(). The client can replace the widget's model atany time with IWidget_SetModel(), as long as the supplied model interface is of the type that the widgetexpects.

The julian date and julian time widgets both perform validation of the AEEDateTime date structure set intheir model to ensure a valid date is stored and displayed. If an invalid date is passed in, the widgets willchange the offending fields to make the date valid. This keeps their behavior in line with their non-juliancounterparts.

The data supplied in the value model must be of type AEEDateTime.

Date and time widget interfaces used

Julian date and julian time widgets use the IWidget interface.


Required Files

AEEIModel.h

AEEIHandler.bid

AEEICanvas.h

AEEStdErr.h

Interface ID

AEEIID_IWidget

Date and time widget helper functions

Helper functions

IWidget_GetJulianTypeValueModel

IWIdget_GetAEEDateTime

IWidget_SetFont

IWidget_GetFont

IWidget_SetFontClass

IWidget_SetFontOutlineWidth

IWidget_GetFontOutlineWidth

IWidget_SetLocale

IWidget_SetFormatString



Helper functions

IWidget_GetFormatString

IWidget_SetFontOutlineColor

IWidget_GetFontOutlineColor

IWidget_SetFieldPad

IWidget_GetFieldPad

IWidget_SetFlags

IWidget_AddFlags

IWidget_RemoveFlags

IWidget_GetFlags

IWidget_SetPropImageStrip

IWidget_SetFocusIndex

IWidget_GetFocusIndex

IWidget_SetArrowPad

IWidget_GetArrowPad

IWidget_SetFGColor

IWidget_GetFGColor

IWidget_SetSelectedFGColor

IWidget_SetSelectedActiveFGColor

IWidget_GetSelectedActiveFGColor

IWidget_SetSelectedInactiveFGColor

IWidget_GetSelectedInactiveFGColor

IWidget_SetActiveFGColor

IWidget_GetActiveFGColor

IWidget_SetInactiveFGColor

IWidget_GetInactiveFGColor

Using date and time widget

The date and time widgets are instantiated by passing AEECLSID_JulianDateWidget orAEECLSID_JulianTimeWidget into ISHELL_CreateInstance.

static AEEResult SampleTouchApp_ICardContainer_AddDateTime(ICardContainer *picc, IShell *piShell, SampleTouchApp *me){ IWidget *piDateWidget = NULL; IWidget *piTimeWidget = NULL; IPropContainer *picProp = NULL; IWidget *piwProp = NULL; int nErr = AEE_SUCESS; WidgetProp WidProp; WidgetExtent we;



IBitmap *pib = NULL;

ERR_TRY( ISHELL_CreateInstance(piShell, AEECLSID_PropContainer, (void**) &picProp)); ERR_TRY( IPropContainer_QueryInterface(picProp, AEEIID_IWidget, (void**) &piwProp)); ERR_TRY( ISHELL_CreateInstance(piShell, AEECLSID_JulianDateWidget, (void**) &piDateWidget)); ERR_TRY( ISHELL_CreateInstance(piShell, AEECLSID_JulianTimeWidget, (void**) &piTimeWidget)); pib = ISHELL_LoadBitmap(piShell, "images/arrows.bmp"); if (NULL == pib) { ERR_THROW(EFAILED); }

// Set arrow image for date/time widget ERR_TRY( IWidget_SetImageStrip(piDateWidget, pib)); ERR_TRY( IWidget_SetImageStrip(piTimeWidget, pib));

// Set arrow padding for date/time widget ERR_TRY( IWidget_SetArrowPad(piDateWidget, 5)); ERR_TRY( IWidget_SetArrowPad(piTimeWidget, 5));

we.height = 60; we.width = me->rcContainer.dx;

IWidget_SetExtent(piDateWidget, &we); IWidget_SetExtent(piTimeWidget, &we);

ERR_TRY(IWidget_SetTopPadding(piwProp, 20)); ERR_TRY( IWidget_SetBGColor(piwProp, RGB_TAB_2)); ERR_TRY( IWidget_SetFlags(piDateWidget, DTWF_USEUPDOWNKEYS | DTWF_SHOWUPDOWNARROWS)); ERR_TRY( IWidget_SetFlags(piTimeWidget, DTWF_USEUPDOWNKEYS | DTWF_SHOWUPDOWNARROWS));

WidProp.bVisible = TRUE; WidProp.prop = WIDGET_KEEP_EXTENT; ERR_TRY( IPropContainer_Insert(picProp, piDateWidget, WIDGET_ZNORMAL, &WidProp)); ERR_TRY( IPropContainer_Insert(picProp, piTimeWidget, WIDGET_ZNORMAL, &WidProp)); ERR_TRY( ICardContainer_Insert(picc, piwProp, WIDGET_ZBOTTOMMOST) );

ERR_CATCH: RELEASEIF(piDateWidget); RELEASEIF(piTimeWidget); RELEASEIF(picProp); RELEASEIF(piwProp); RELEASEIF(pib); return nErr;}

Frame widget

This widget is used to display images from the camera and video.

The frame widget is a user interface element for displaying frames from a media source such as video orcamera. This media source is contained in a frame model which sends events to the widget indicating theframe has changed. When receiving the frame event, the widget requests the new frame from the modeland displays it within the widget's extent.




Files to include:


AEEFrameWidget.h AEEFrameWidget.bid

Frame widget interfaces used

Frame widget uses the IWidget, IFrameModel, IMediaFrameModel, ICameraFrameModel, andIDirectMode interfaces.


Required Files

AEEIModel.h

AEEIHandler.bid

AEEICanvas.h

AEEStdErr.h

Interface ID

AEEIID_IWidget

IFrameModelAn abstract base class representing a media source such as video or a camera.

Required Files

AEEIModel.h

Interface ID

AEEIID_IFrameModel

IMediaFrameModelIMediaFrameModel is derived from IFrameModel and provides image frames from a video.

Required Files

AEEIMediaFrameModel.h

Interface ID

AEEIID_IMediaFrameModel



ICameraFrameModelICameraFrameModel is derived from IFrameModel and provides image frames from a camera.

Required Files

AEECameraFrameModel.h

Interface ID

AEEIID_ICameraFrameModel

IDirectModeIDirectMode is derived from IQueryInterface. It is expected to be implemented by FrameModel whichsupports DirectMode.

Required Files

AEEIDirectMode.h

Interface ID

AEEIID_IDirectMode

Frame widget helper functions

Helper function

IWidget_SetBGColor


IWIdget_SetPropertyEx

IWidget_SetRasterOp

IWidget_GetRasterOp

Using frame widget

The frame widget is a user interface element for displaying frames from a media source such as video orcamera.

This media source is contained in a frame model which sends events to the widget indicating the framehas changed. When receiving the frame event, the widget requests the new frame from the model anddisplays it within the widget's extent.

To create a frame widget, an application would do the following.

1. Create an instance of the frame widget using AEECLSID_FrameWidget.

nErr = ISHELL_CreateInstance(me->piShell, AEECLSID_FrameWidget, (void**)&me->piwFrame);



2. Configure the widget and set the extent using IWidget_SetExtent.

if (AEE_SUCCESS == nErr) { IWidget_SetExtentEx(me->piwFrame, me->rcContainer.dx, me->rcContainer.dy - BUTTON_WIDTH); nErr = (IWidget_SetBGColor(me->piwFrame, MAKE_RGBA(0,0,0,255)));}

3. Create an instance of IFrameModel and call IWidget_SetModel on the frame widget.

IFrameModel *piModel = NULL;if (AEE_SUCCESS == nErr) { nErr = IWidget_SetModel(me->piwFrame, (IModel*)(void *)piModel);}

Typically, widget sets the frame size based on its own extent, by calling IFrameModel_SetSize().However, the frame size could be different because of underlying media object limitations or applicationschanging the frame size explicitly by calling IFrameModel_SetSize(). If the frame size is smaller than thewidget extent, the frame is drawn at the center of the widget. If the frame size is larger than the widgetextent, the bottom or the right portion of the frame will be clipped to the widget's extent. To create aFrame widget object, pass AEECLSID_FrameWidget into ISHELL_CreateInstance().

HTML widget

This widget supports basic rendering of HTML content.

Its HTML formatting features and its ability to deal with malformed content are limited. HTML presentedto the widget should be properly constructed, with start and end tags for nonempty elements and nomismatched end tags. As a result, HTML that is tested with the particular application is advised, and it isnot intended to support for arbitrary content (as obtained from various web sites).

HTML features supported include:

• Hypertext links• Simple HTML FORM support: text input, lists, submit buttons, check boxes, and radio buttons• Inline images or plug-ins• Horizontal alignments: left, center, right• Bold text (displayed using the AEE_FONT_BOLD font)• Large text (displayed using the AEE_FONT_LARGE font)• Text colors• Html document background colors when specified in hex format using body tag• Link colors using body tag

For additional information, including HTML features not supported by the HTML widget, refer to the C/C++API Reference.

Files to include:


none AEEHtmlWidget.bid

This is an example of the HTML widget in use.



HTML widget interfaces used

The HTML widget uses the IWidget and IWeb interfaces.


Required Files

AEEIModel.h

AEEIHandler.bid

AEEICanvas.h

AEEStdErr.h

Interface ID

AEEIID_IWidget

IWebThe IWeb interface is the context in which web transactions are conducted and completed. IWeb is theinterface the widget uses to obtain sub-objects for PROP_HTMLW_IWEB.

Required Files

Interface ID

AEECLSID_WEB



HTML widget helper functions

Helper functions

IWIdget_SetURL

IWidget_GetIndent

IWidget_SetIndent

IWIdget_GetVSpace

IWIdget_GetBufferSize

IWidget_SetBufferSize

IWidget_GetFocusPos

IWidget_SetFocusPos

IWidget_GetScrollPos

IWidget_SetScrollPos

IWidget_GetLinkColor

IWidget_SetLinkColor

IWIdget_GetDocBackgroundColor

IWIdget_SetDocBackgroundColor

IWidget_GetMultilineLinkScroll

IWidget_SetMultilineLinkScroll

Using HTML widget

The HTML Widget is instantiated by passing AEECLSID_HTMLWidget into ISHELL_CreateInstance().

HTML Widget has touch screen support for links. On EVT_POINTER_DOWN event, the HTMLwidget touch controller sets PROP_HTMLW_FOCUSPOS on the widget for the hit link element.This will cause the focus to move to the touched link if it did not have focus prior to touching. OnEVT_POINTER_UP, if the pointer was still on the same link, the HTML widget touch controllersets PROP_HTMLW_SELECTPOS on HTML widget. This causes the view model to send outEVT_HVM_JUMP.

PROPEX_HTMLW_WIDATPOS gets the widget at given position and forwards the event to it.

To implement an HTML widget, do the following.

1. Call ISHELL_CreateInstance() with the ClassID AEECLSID_HTMLWidget.

if(AEE_SUCCESS == nErr) { nErr = ISHELL_CreateInstance(me->pIShell, AEECLSID_HTMLWIDGET, (void**)&(me->piwHtml)); }if(AEE_SUCCESS == nErr) { ERR_TRY(IWidget_SetBGColor(me->piwHtml, MAKE_RGBA(255,255,255,255))); we.width = (me->rcRoot).dx-nScrollHndlWidth-nScrollPad-4; we.height = (me->rcRoot).dy;



IWidget_SetExtent(me->piwHtml,&we); ERR_TRY(IWidget_SetIWeb(me->piwHtml, me->piWeb)); IDecorator_SetWidget(me->piwScrollBar, me->piwHtml);}

// Add Listeners for HTML Widgetif(AEE_SUCCESS == nErr) { LISTENER_SetListenerInfo(&me->mlHtmlDoc, samplehtmlwidgettouchapp_htmldoclistener, me); LISTENER_SetListenerInfo(&me->mlHtmlView, samplehtmlwidgettouchapp_htmlviewlistener, me); ERR_TRY(IDocModel_AddListener(me->piDocModel, &me->mlHtmlDoc)); ERR_TRY(IHTMLViewModel_AddListener(me->piViewModel, &me->mlHtmlView));}

dwpos.x = 0;dwpos.y = 0;dwpos.bVisible = TRUE;

// insert widget into root containerif(AEE_SUCCESS == nErr) { nErr = IRootContainer_Insert(me->picRoot, CAST(IWidget *, me->piwScrollBar), WIDGET_ZNORMAL, &dwpos);}nErr =(IWidget_MoveFocus(me->piwRoot, CAST(IWidget*, me->piwScrollBar)));

Image static widget

This widget is used to display an image accompanied with text; however, both text and an image do nothave to be displayed. A variety of image formats are supported.

The image static widget is used to display a single interface element that consists of both an image and atext label. For example, a real estate application could use the image static widget to display a photo of ahome for sale with the price and address immediately to the right.

The static image widget is actually three objects in one:

• A static text widget containing the text that is used to label the image.• An image widget containing the graphic image to be displayed.• A prop container into which the above elements will be placed.

Applications specify the image to be displayed in the widget by calling IWidget_SetImageStaticInfo(),passing in a pointer to an ImageStaticInfo data structure, which contains the text and image to bedisplayed.

Files to include:


AEEImageStaticWidget.h AEEImageStaticWidget.bid

The image and static text, "Inbox", at the top of the screen is an example of an Image static widget.



For additional information, refer to the C/C++API Reference.

Image static widget interfaces used

Image static widget uses the IWidget interface.


Required Files

AEEIModel.h

AEEIHandler.bid

AEEICanvas.h

AEEStdErr.h

Interface ID

AEEIID_IWidget



Image static widget helper functions

Header files

IWidget_GetSelected

IWidget_SetSelected

IWidget_GetImageStaticImageWidget

IWidget_SetImageStaticImageWidget

IWidget_GetImageStaticStaticWidget

IWidget_SetImageStaticStaticWidget

IWidget_GetFlags

IWidget_SetFlags

Image static widget usage

The image static widget is used to display a single interface element that consists of both an image and atext label.

The static image widget is actually three objects in one:

• A static text widget containing the text that is used to label the image.• An image widget containing the graphic image to be displayed.• A prop container into which the above elements will be placed.

By default, the layout of the image has the image on the left and the label on the right, with the height ofthe label dictating the overall height of the parent container enclosing both objects. This orientation canbe changed, however, with the label on the left and the image on the right, by setting the appropriate bit inthe widget's property flags (ISWF_LAYOUT_IMAGERIGHT bit of PROP_FLAGS).

The label text will be vertically centered in the parent container, immediately to the right (or left, ifthe image/label orientation has been changed) of the image. By default, there is a two pixel paddingbetween the image and the start of the label text -- a value that could be overridden by callingIWidget_SetLeftPadding() on the label portion of the image. An application could change this or any otherproperty of the label or image widgets to customize color, alignment or justification.

The widget interface provides APIs to allow applications to access either the image or label parts of theimage static widget, thereby allowing an application to have great control over how the widget is to actand be displayed. For example, the application could retrieve the label portion of the object, then alter thefont, color or alignment of the text. Likewise, the image portion could be retrieved and manipulated -- forexample, to add a transparency effect to the graphic.

To create a static image widget, an application would do the following.

1. Call ISHELL_CreateInstance() with a ClassID of AEECLSID_ImageStaticWidget to retrieve areference counted instance of the static image widget.

ISHELL_CreateInstance(me->piShell, AEECLSID_ImageStaticWidget, (void**)&pisw);



2. Applications specify the image to be displayed in the widget by callingIWidget_SetImageStaticInfo(), passing in a pointer to an ImageStaticInfo data structure, whichcontains the text and image to be displayed. Call IWidget_SetImageStaticInfo() to identify the imageand text to be displayed by the widget.

// Pass the static info obj to the widget.IWidget_SetImageStaticInfo(piw, pImgStaticInfo, free);

Image widget

This widget is typically used to display an image.

A variety of image formats are supported. The graphic image displayed by an image widget is providedby the model attached to the widget when it is created. Therefore, as the data in the model changes, theimage represented by the image widget will be updated on the display.


Files to include:


AEEImageWidget.h AEEImageWidget.bid



Image widget interfaces used

Image widget uses the IWidget and IFrameModel interfaces.

IWidgetThe IWidget interface provides APIs that allow applications to directly set many of the attributesassociated with an image, as well as interfaces to start or stop animating the image.

Required Files

AEEIModel.h

AEEIHandler.bid

AEEICanvas.h

AEEStdErr.h

Interface ID

AEEIID_IWidget

IFrameModelIFrameModel is an abstract base class representing a media source such as video or a camera. TheIFrameModel notifies it's listener through IModel_Notify whenever a new frame is available, and thelistener can then retrieve the current frame and display it.

Required Files

AEEIFrameModel.h

Interface ID

AEEIID_IFrameModel

Image widget helper functions

Helper functions

IWidget_GetSelected

IWidget_SetSelected

IWidget_GetImageAnimate

IWidget_SetImageAnimate

IWidget_GetTiledBorderDistanceTop

IWidget_SetTiledBorderDistanceTop

IWidget_GetTiledBorderDistanceBottom



Helper functions

IWidget_SetTiledBorderDistanceBottom

IWidget_GetTiledBorderDistanceLeft

IWidget_SetTiledBorderDistanceLeft

IWidget_GetTiledBorderDistanceRight

IWidget_SetTiledBorderDistanceRight

IWidget_GetImageFrame

IWidget_SetImageFrame

IWidget_GetFlags

IWidget_SetFlags



IWidget_GetTranspColor

IWidget_SetTranspColor

Using image widget

The image widget is instantiated by passing AEECLSID_ImageWidget into ISHELL_CreateInstance.

The image itself will be displayed within the rectangle that defines the widget's border, positioned bydefault with its origin aligned to the upper left corner of the border, clipped to the widget's extent. Theimage is always displayed at its full size, cropped to the clip rectangle of the destination port. The size,position, animation rate and many other attributes of the image may be further customized by callingIWidget_SetImageParm(), passing in an ImageParm date structure that identifies the attribute to beset, along with the attribute's associate value. See AEEImage.h for a discussion of each of the imageparameters that can be set.

The image widget assumes the IImage to be displayed has been fully loaded and decoded. Someimage formats such as png, jpg and gif require the image data to be decompressed before beingdisplayed. When loading these images via BREW's ISHELL_LoadResImage() or related routines, it isthe application's responsibility to use IIMAGE_Notify() to wait for the image decoding to complete beforepassing the IImage to the image widget for display. If the application fails to do this, screen updatesimmediately following an image change may not happen as expected.

To create an image widget, an application would do the following:

1. Call ISHELL_CreateInstance() with a ClassID of AEECLSID_ImageWidget to retrieve a referencecounted instance of the image widget.

ISHELL_CreateInstance(pMe->a.m_pIShell, AEECLSID_ImageWidget, (void**) &pMe->piwWid);

2. Call IWidget_SetImage() to identify the image to be displayed by the widget, passing in a pointer tothe IImage image to be displayed.

(void) IWidget_SetImage(pMe->piwWid, pMe->piImageWidClose);3. Call IWidget_SetFlags() if the application wishes to override the default alignment of the image

within its border.



The image widget relies on an interface model that represents its data as a pointer to an IImage datastructure. The model stores only a pointer to the image not a copy of the image itself, and should alwaysreturn this pointer in response to data queries from a client widget.

The IImage pointer passed as the model data must point to an image that has been fully loaded anddecoded. It is the application's responsibility to wait for image formats such as PNG, JPG and GIF tocomplete decoding before passing them to the image widget. See the C/C++ API Reference on IImageand IImage_Notify() for details.

The image widget may be created with a specific interface model identified, rather than the defaultinterface model assigned by the widget framework. Clients that identify their own model interface to beattached to the image widget must abide by the data conventions described above, returning a pointer toan IImage when queried for the model data.

List, pick and grid widget

This section covers three widgets used to implement either a vertical list, horizontal list, or grid.

List widget can display multiple items as a vertical list, horizontal row, or grid. It appears to be composedof multiple items; however, there is only a single object. This is possible because the list widget is adecorator that wraps around a single object that is used to draw each item.

Files to include:

Header file ClassID file for list ClassID file for pickwidget

ClassID file for gridwidget

AEEListWidget.h AEEListWidget.bid AEEPickWidget.bid AEEGridWidget.bid

This is the List widget in use.

List widgetThe list widget lays out its items in a vertical list. For example, an application that manages baseballstatistics might choose to present to the user a list of player names in alphabetic order. This list could beimplemented using a list widget that displays each item as static text.

Pick widget

The pick widget lays out its items horizontally, in much the same manner as a toolbar. For example, apainting application that offers a palette of editing tools might choose to implement the presentation ofthese tools as a pick widget, with each item in the pick list representing a particular tool.

Grid widget

The grid widget also lays out its items horizontally, but wraps once it is out of horizontal space. The netresult is a widget that lays out its items in a grid with the appearance of a table (though the widget doesnot, technically, behave as a table). The items are laid out left to right, with the wrapped item left justifiedunder the row above. By default, the grid widget is set to contain three rows and three columns.

The grid widget is ideal for implementations that call for the user to select from a long list of similarlyshaped items -- for example, a virtual art gallery application might choose to display thumbnail images of



great works of art laid out in a grid, allowing the user to scroll through this list to locate an image to view atfull screen size.

List, grid, and pick widget

These widgets are user interface objects that display multiple items that the user can view or select.For example, a list widget may display a vertical list of names, pick widget may display a horizontal rowof icons, or grid widget may display a palette of drawing tools laid out in a grid. The concept is one ofpresenting many items, and providing an interface for interacting with these items.

From an implementation standpoint, these widgets are actually decorators that wrap around anotherwidget. As a decorator, the purpose of the list widget is to modify the appearance of the widget it wraps.Just as a blend widget or border widget are used to effect the shading, color or transparency of anotherwidget, the list widget alters the draw location and model data of the child widget.

Though a list widget generally contains and manages what appear to be multiple items, there is only onewidget wrapped within the list widget, and the list widget uses the services of that single widget (throughthe model/widget relationship of the widget framework) to draw each individual item in the list. See thefollowing diagram, which explains how the list widget manages this relationship.

• List widget's model

One must consider the models that support both the list widget and the widget that will be used torender each item within the list.

The list widget is attached to a list model, which -- as an abstract class -- could be realized as avector model, an array model, or any model that manages indexed collections of data. This modelwill contain all the data to be presented in the list. It could be a simple list of strings, or it could be acomplex data structure containing strings, icons or anything else an application may need to renderitems in a list.

• Item's value model

When attached to by the list widget, the item widget should already have a value model attachedto it, presumably with no corresponding data. At draw time, or certain other times such as when



the preferred extent is requested, the list widget will loop through its list model and apply each dataelement in succession to the Item widget's value model.

Variable-sized list itemsA special feature of both the list widget and pick widget is the ability to have list items that vary in sizefrom one index to another, or change size when the item is selected. For list widgets the height may vary,and for pick widgets the width may vary. There are two types of variable-sized lists. In the first type, everyitem in the list could be set to a unique size. In the second type, all items are of equal size except thecurrently selected item.

• All Items of variable size

For the first type of variable-sized list, the flag LWF_VARIABLEITEMSIZE must be set on thewidget, and an indexer callback function must be installed (see IWidget_SetIndexer). In the indexercallback, the application can control the height (or width) by calling IWidget_SetVarItemSize() toset the new size of the item. This size may be based on the original size of the item, which may beretrieved by calling IWidget_GetVarItemSize().

For example, to create a list widget which sizes the list item based on the content of the item, theindexer callback might look like this.

static voidListIndexer(IWidget *piw, int nIndex, boolean bSelected) { // calculate the height based on the content int height = CalcNewHeight(piw, nIndex); IWidget_SetVarItemSize(piw, size); }

• Selected item variable size

For the second type of list, no special flag of indexer function is needed, just simply set the size ofthe selected item using IWidget_SetSelectedItemSize(), and the list will take care of changing thesize of the selected item when it is drawn.


List, pick and grid widget interfaces used

List, pick and grid widget use the IWidget, IHandler and IDecorator interfaces.


Required Files

AEEIModel.h

AEEIHandler.bid

AEEICanvas.h

AEEStdErr.h

Interface ID

AEEIID_IWidget



IHandlerIHandler is an abstract interface meant to be a base from which more complex object implementationsare based.

Required Files

AEEIHandler.h

Interface ID

AEEIID_IHandler

IDecoratorIDecorator is an abstract interface meant to be a base from which more complex widget implementationsare based.

Required Files

AEEIDecorator.h

Interface ID

AEEIID_IDecorator

List, pick and grid widget helper functions

This section lists helper functions.

Helper functions

IWidget_SetIndexer

IWidget_GetTopIndex

IWidget_SetTopIndex

IWidget_GetFocusIndex


IWidget_GetItemHeight

IWidget_SetItemHeight

IWidget_GetItemWidth

IWidget_SetItemWidth

IWidget_GetHintRows

IWidget_SetHintRows

IWidget_GetHintCols

IWidget_SetHintCols



Helper functions

IWidget_GetRows

IWidget_SetRows

IWidget_GetCols

IWidget_SetCols

IWidget_GetFlags

IWIdget_SetFlags



IWidget_GetItemRect

IWidget_SetVarItemSize

IWidget_GetSelItemSize

IWidget_SetSelItemSize

IWidget_GetIncrement

IWidget_SetIncrement

IWidget_GetOffsetX

IWidget_SetOffsetX



IWidget_GetItemHeight

IWidget_SetItemHeight

IWidget_GetItemWidgth

IWidget_SetItemWidgth

IWidget_GetSelItemSize

IWidget_SetSelItemSize

IWidget_GetOrientation

Using list, pick and grid widget

To create a list, pick or grid widget object, pass the ClassID of the widget into ISHELL_CreateInstance.

To create a list widget, an application would do the following.

1. Call ISHELL_CreateInstance() with a ClassID of either AEECLSID_ListWidget,AEECLSID_PickWidget, or AEECLSID_GridWidget.

ERR_TRY( ISHELL_CreateInstance(me->piShell, AEECLSID_ListWidget, (void**)&piw));

2. Create the item widget that will be wrapped by the list widget, and identify the value model that is tobe associated with this widget.



ERR_TRY( ISHELL_CreateInstance(me->piShell, AEECLSID_StaticWidget, (void**)&pisw)); ERR_TRY( ISHELL_CreateInstance(me->piShell, AEECLSID_VectorModel (void**)&pivm));

3. Call IWidget_SetModel() to attach the appropriate model to the list.

ERR_TRY( IWidget_SetModel(piw, IVectorModel_TO_IMODEL(pivm)));4. Call IDecorator_SetWidget() to wrap the list widget around the item widget.

// StaticWidget to use as 'item' widget IDecorator_SetWidget((IDecorator *)(void*) piw, pisw);

5. Retrieve the height of the item widget by calling IWidget_GetPreferredExtent(), then set the height ofthe list widget by calling IWidget_SetItemHeight().

IWidget_GetPreferredExtent(pisw, &weStatic); ERR_TRY( IWidget_SetItemWidth(piw, weStatic.width)); ERR_TRY( IWidget_SetItemHeight(piw, weStatic.height));

Progress widget

This widget is used to show a simple progress indicator on the display illustrating the "percentagecomplete" of a finite operation or an infinite looping.

The progress widget is drawn as a rectangle, with some percentage of that rectangle filled, as indicatedby the attached value model.

For additional information, refer to the C/C++ API Reference. Files to include:


none AEEProgressWidget.bid

This progress widget is used within a progress dialog.



Progress widget interfaces used

The progress widget uses the IWidget interface.


Required Files

AEEIModel.h

AEEIHandler.bid

AEEICanvas.h

AEEStdErr.h

Interface ID

AEEIID_IWidget

Progress widget helper functions



Helper functions

IWidget_SetFGColor



Progress widget usage

To create a progress widget, an application would do the following:

1. Call ISHELL_CreateInstance() with a ClassID of AEECLSID_ProgressWidget to retrieve a referencecounted instance of the cursor widget.

2. Set any properties the application may wish to use to enhance the progress widget's appearance(border color, fill color, etc).

The progress widget relies on a value model that represents its data as an integer ranging from 0 to 100to indicate the "percent complete" of the operation being tracked.

A special "indeterminate-progress" mode is supported. To trigger this mode, set the value model data toa negative value. The progress widget will begin displaying an animated progress bar repeatedly movingfrom left to right within the display area. The animation will continue until a positive value is set in themodel.

A default model is created and assigned to the widget when the widget is created withISHELL_CreateInstance(). The client can replace the widget's model at any time with the method:IWidget_SetModel(), as long as the supplied model interface is of the type that the widget expects.

The data supplied in the value model must be a pointer to type 'int'.

Scrollbar and scroll indicator widget

The scrollbar and the scroll indicator widgets derive from the decorator object.

The scrollbar is wrapped around a content based widget to indicate the position and proportion of thecontent that is being displayed, while the user navigates over the content. The scrollbar can be usedto provide this visual indication vertically, horizontally, or even both simultaneously. The scroll indicatorwidget decorates viewable content as well by providing a pair of arrows beside the content. Like itssibling, the scroll indicator has the capability to display the indicator vertically, horizontally, or both.

The graphic images used to represent the scroll arrows associated with a scrollbar are stored asresources in the "widgets.bar" file. One resource is used to store both arrows in an orientation -- i.e. theup and down arrows used at the ends of a vertical scrollbar are stored in the same resource as individualdisplay "tiles". The tiles are exactly the same size and are laid out in the resource one after the other in ahorizontal strip, sort of like the frames of an animation sequence.

Files to include:

Header file ClassID file for scrollbarwidget

ClassID file for scroll indicatorwidget

AEEScrollWidget.h AEEScrollbarWidget.bid AEEScrollIndicatorWidget.bid



The following image shows a scroll widget displaying a vertical and horizontal scrollbar.


Scrollbar and scroll indicator widget interfaces used

Scroll widget (scrollbar and scroll indicator) uses the IWidget interface.


Required Files

AEEIModel.h

AEEIHandler.bid

AEEICanvas.h

AEEStdErr.h

Interface ID



AEEIID_IWidget

Scrollbar and scroll indicator widget helper functions

Helper functions

IWidget_GetScrollStyle

IWidget_SetScrollStyle

IWidget_GetScrollPad

IWidget_SetScrollPad

IWidget_GetScrollHandleWidth

IWidget_SetScrollHandleWidth

IWidget_GetScrollFillColor

IWidget_SetScrollFillColor

IWidget_SetScrollHandleColor

IWidget_GetActiveScrollHandleColor

IWidget_SetActiveScrollHandleColor

IWidget_GetInactiveScrollHandleColor

IWidget_SetInactiveScrollHandleColor

IWidget_GetInactiveScrollColor

IWidget_SetInactiveScrollColor

IWidget_GetActiveScrollColor

IWidget_SetActiveScrollColor



IWidget_GetScrollEndPad

IWidget_GetFlags

IWidget_SetFlags

IWidget_GetScrollbarRect

IWidget_GetVScrollbarRect

IWidget_GetHScrollbarRect

IWidget_GetScrollHandleRect

IWidget_GetVScrollHandleRect

IWidget_GetHScrollHandleRect

IWidget_GetScrollFillRect

IWidget_GetVScrollFillRect



Helper functions

IWidget_GetHScrollFillRect

IWidget_GetElementDragThreshold

IWidget_SetElementDragThreshold

IWidget_GetHScrollHandleMinWidth

IWidget_SetHScrollHandleMinWidth

IWidget_GetVScrollHandleMinHeight

IWidget_SetVScrollHandleMinHeight

IWidget_GetVScrollHandleWidget

IWidget_GetHScrollHandleWidget

IWidget_SetHScrollHandleWidget

IWidget_GetHScrollLeftArrowWidget

IWidget_SetHScrollLeftArrowWidget

IWidget_GetHScrollRightArrowWidget

IWidget_SetHScrollRightArrowWidget

IWidget_GetVScrollUpArrowWidget

IWidget_SetVScrollUpArrowWidget

IWidget_SetVScrollDnArrowWidget

IWidget_GetVScrollDnArrowWidget

IWidget_GetScrollBorderWidth

IWidget_SetScrollBorderWidth

IWidget_GetScrollElementFlash

IWidget_SetScrollElementFlash

IWidget_GetTargetWidget

IWidget_SetTargetWidget

Using scrollbar and scroll indicator widgets

The scroll widget is instantiated by passing AEECLSID_ScrollWidget into ISHELL_CreateInstance.

To wrap a scrollbar widget around a content widget, an application would do the following.

1. Create the content widget that will be wrapped by a scrollbar.2. Call ISHELL_CreateInstance() with a ClassID of AEECLSID_ScrollbarWidget to retrieve a reference

counted instance of the scrollbar widget.3. Call IDecorator_SetWidget() to wrap the scrollbar around the content widget.

Scrollbar Widget can be also used in Standalone mode i.e, No Child Mode. When used in standalonemode, an external widget (for e.g..TextWidget/ListWidget/ViewportWidget) can be attached to scrollbarwidget using PROPEX_TARGETWIDGET property.

To wrap a standalone scrollbar widget around a target widget, an application would do the following.



1. Create the content widget that will be wrapped by a scrollbar.2. Call ISHELL_CreateInstance() with a ClassID of AEECLSID_ScrollbarWidget to retrieve a reference

counted instance of the scrollbar widget.3. Call IWidget_SetTargetWidget() to wrap the scrollbar around the target widget.

The graphic images used to represent the scroll arrows associated with a scrollbar are stored asresources in the "widgets.mif" file.

The scroll widget takes a dummy scroll model, primarily as an event driving mechanism for tracking andhandling position changes to the scrollable content that a scroll widget wraps. As these changes aredetected, the wrapped widget will create the scroll model on demand and generate the scroll event andnotification that will drive the scroll widget to update itself to reflect the user's movements through thescrollable content.

Slider widget

This widget is typically used to provide a means to control a setting over a predetermined range. Slidersare best used for settings that have continuous variable values, such as display brightness or contrast.

• Positioned horizontally or vertically. Horizontal layout is typically used• Does not include a text label• Range is set through a property

Sliders can be aligned horizontally or vertically. Horizontal layout is recommended. Sliders do not includetext labels, however, an application could use one or more static text widgets to create labels for a slider.Slider widgets use a value model to supply the value for the slider setting. The slider bar has bordersupport and all border properties can be applied to the slider bar.


Files to include:


AEESliderWidget.h AEESliderWidget.bid

Here is an example of the slider widget being used.



Slider widget interfaces used

Slider widget uses the IWidget interface.


Required Files

AEEIModel.h

AEEIHandler.bid

AEEICanvas.h

AEEStdErr.h

Interface ID

AEEIID_IWidget

Slider widget helper functions



Header function

IWIdget_GetSliderMaxPos

IWidget_SetSliderMaxPos

IWidget_GetSliderHandleBorderColor

IWIdget_SetSliderHandleBorderColor

IWIdget_GetLayoutStyle

IWidget_SetLayoutStyle

IWIdget_GetInactiveBorderColor

IWidget_SetInactiveBorderColor

IWIdget_GetActiveBorderColor

IWidget_SetActiveBorderColor

IWidget_SetBorderColor

IWIdget_GetInactiveBGColor

IWidget_SetInactiveBGColor

IWidget_GetActiveBGColor

IWidget_SetActiveBGColor

IWidget_SetBGColor

IWidget_GetFlags

IWidget_SetFlags

IWidget_GetSliderHandleWidget

IWIdget_SetSliderHandleWidget

Using slider widget

The following code implements a slider widget.

To create a slider widget, an application would do the following:

1. Call ISHELL_CreateInstance() with a ClassID of AEECLSID_SliderWidget to create an instance ofthe slider widget.

ERR_TRY( ISHELL_CreateInstance(me->piShell, AEECLSID_SliderWidget, (void**)&piw) );

2. Set properties to control the widget's appearance or function.

// setup the slider widgetERR_TRY( IWidget_SetLayoutStyle(piw, LAYOUT_HORZ));ERR_TRY( IWidget_SetPadding(piw, 2));ERR_TRY( IWidget_SetBorderWidth(piw, 2));ERR_TRY( IWidget_SetBorderColor(piw, RGB_BORDER));ERR_TRY( IWidget_SetBGColor(piw, RGB_8));ERR_TRY( IWidget_SetSliderHandleBorderColor(piw, RGB_7));ERR_TRY( IWidget_SetSliderMaxPos(piw, 50));



3. Set the extent of the widget.

we.height = 14;we.width = 80;IWidget_SetExtent(piw, &we);

4. Place the widget in a container.

ERR_TRY( SampleTouchApp_IXYContainer_InsertEx(pixy, piw, -1, 8) );

Softkey widget

The softkey widget class provides software navigation to devices that possess a pair of hardware buttonsdirectly below the display.

• Associate text with these buttons• Application is responsible for listening for the key events• One command for each key

The softkey widget is a user interface element that provides software navigation to devices that possessa pair of hardware buttons directly below the display. These buttons are commonly referred to as "softkeybuttons" and are usually accompanied by a pair of commands placed on the display directly above eachbutton -- one command for the left button, and one for the right. The commands to which the buttons mapcan be changed, which is why they're referred to as softkeys.


Files to include:


none AEESoftkeyWidget.bid

An example of the softkey widget can be seen under the slider widget.



Softkey widget interfaces used

The softkey widget uses the IWidget interface.


Required Files

AEEIModel.h

AEEIHandler.bid

AEEICanvas.h

AEEStdErr.h

Interface ID

AEEIID_IWidget

Softkey widget helper functions



Header functions

IWidget_GetSoftKey

IWIdget_SetSoftkey

IWidget_GetSoftKey

IWIdget_SetSoftkey

Using softkey widget

The softkey widget is instantiated by passing AEECLSID_SoftkeyWidget into ISHELL_CreateInstance.

The softkey widget is a prop container consisting of a pair of embedded static text widgets: softkey oneand softkey two. Though the layout and interaction of these widgets are handled together by the softkeywidget, each is displayed and their functions are independent of the other. For example, an applicationmay choose to alter the color or font of one softkey to place emphasis on one button or the other.

To create a softkey widget, an application would do the following:

1. Call ISHELL_CreateInstance() with a ClassID of AEECLSID_SoftkeyWidget to create a softkeywidget. ISHELL_CreateInstance() will retrieve a reference counted instance of the class thatmanages the widget.

ERR_TRY( ISHELL_CreateInstance(me->piShell, AEECLSID_SoftkeyWidget, (void**)&piw));

2. IWidget_SetText() to specify the text to be displayed within each of the softkeys.

ERR_TRY( IWidget_SetText(piwsk1, awszLeft, 0));3. Call IWidget_SetExtent() to set the size of the softkey widget.

IWidget_GetPreferredExtent(me->piwSoftkey, &we);we.width = me->rcContainer.dx;IWidget_SetExtent(me->piwSoftkey, &we);

4. As necessary, call various IWidget_Setxxxxxx() functions to override any of the default visualcharacteristics of the widget.

ERR_TRY( IWidget_SetFGColor(piwsk1, RGB_MENU_FG));ERR_TRY( IWidget_SetFGColor(piwsk2, RGB_MENU_FG));

It is very important to note that the softkey widget only creates the softkeys. It does not handle EVT_KEYevents. Applications must separately create an appropriate wrapper around the widget, so that whenAVK_SOFT1/AVK_SOFT2 is pressed, applications change the visual representation of underlying staticwidgets. Static widgets can be retrieved by PROP_SOFTKEY1/PROP_SOFTKEY2 properties.

Static widget

The static widget displays read-only text on the display. The text is displayed within a border, which isinitially configured to have zero widget to give the appearance of no border. The font, alignment, color aswell as other properties are configurable via properties.

Files to include:



Header File ClassID File

AEEStaticWidget.h AEEStaticWidget.bid

An example of the static widget in use can be seen as the list item being used by the list widget below.


Static widget interfaces used


Required Files

AEEIModel.h

AEEIHandler.bid

AEEICanvas.h

AEEStdErr.h



Interface ID

AEEIID_IWidget

Static widget helper functions

Header files

IWIdget_GetFont

IWidget_SetFont






IWidget_GetFlags

IWidget_SetFlags

IWidget_SetFGColor

IWIdget_SetSelectedFGColor

IWIdget_GetSelectedActiveFGColor

IWIdget_SetSelectedActiveFGColor

IWidget_GetSelectedInactiveFGColor

IWidget_SetSelectedInactiveFGColor

IWidget_GetActiveFGColor

IWidget_SetActiveFGColor

IWidget_GetInactiveFGColor

IWidget_SetInactiveFGColor

IWidget_GetHIntWidth

IWidget_SetHintWidth

IWidget_GetHintRows

IWidget_SetHintRows

IWidget_SetScrollText

IWidget_Animate





Using static widget

To create a static widget, an application would do the following.

1. Call ISHELL_CreateInstance() with a ClassID of AEECLSID_StaticWidget to create a static widget.ISHELL_CreateInstance() will retrieve a reference counted instance of the class that manages thewidget.

static int SampleTouchApp_IShell_CreateStaticWidget(IShell *piShell, IWidget **ppo, const AECHAR *pwszText, int nHintWidth){ WidgetExtent we; int nErr = NULL; ERR_TRY( ISHELL_CreateInstance(piShell, AEECLSID_StaticWidget, (void**)ppo) );

2. Call IWidget_SetText() to specify the text to be displayed within the static widget.

if (pwszText) {IValueModel *pivm = 0;if (AEE_SUCCESS == IWidget_GetModel(*ppo, AEEIID_ValueModel, (IModel **) (void**) &pivm)) { ERR_TRY( IValueModel_SetText(pivm, pwszText, -1)); ERR_TRY( IValueModel_Release(pivm)); }}

3. Call various IWidget_Setxxxxxx() functions to override any of the default visual characteristics of thewidget. For example, if the text should be displayed in red, or if the border is to be displayed, ratherthan hidden.

ERR_TRY( IWidget_SetBorderWidth(*ppo, 0));ERR_TRY( IWidget_SetPadding(*ppo, 2));ERR_TRY( IWidget_SetFGColor(*ppo, RGB_STATIC_FG));ERR_TRY( IWidget_SetBGColor(*ppo, RGB_BG));

4. Call IWidget_SetFlags() to specify how the text is to be aligned or wrapped.

ERR_TRY( IWidget_SetFlags(*ppo, SWF_WRAPTEXT));5. Call IWidget_SetExtent() to set the size of the rectangle enclosing the text.

ERR_TRY( IWidget_SetHintWidth(*ppo, nHintWidth));IWidget_GetPreferredExtent(*ppo, &we);IWidget_SetExtent(*ppo, &we);

The static widget provided facilities for managing how the text should be wrapped and how the widgetshould display text that would otherwise flow well beyond the boundaries of the widget's extent. Twoproperty flags are used to manage how the text will be displayed. SWF_WRAPTEXT indicates that thetext should be wrapped to fit within the widget's extent.

Tab widget

The tab widget is a decorator, which is used to simulate the appearance of multiple tabs across an area ofcontent.

• Decorates a card container• Image static widget is used to display tab information.

A tab widget uses ImageStaticInfo structure as a data structure for holding information about eachof its tabs. The ImagestaticInfo structure needs to be prepared with the image pointer filled in. ThenImagestaticinfo pointers are added to the tab vectormodel, one each for each tab.



Files to include:


AEETabWidget.h AEETabWidget.bid

Here is an example of the tab widget.


Tab widget interfaces used

Tab widget uses the IWidget interface.


Required Files

AEEIModel.h



AEEIHandler.bid

AEEICanvas.h

AEEStdErr.h

Interface ID

AEEIID_IWidget

Tab widget helper functions

Header Files



IWIdget_GetFlags

IWidget_SetFlags

IWidget_SetIndexer

IWIdget_GetFocusIndex


IWidget_GetTabHeight

IWidget_SetTabHeight

IWIdget_GetTabSpacingH

IWidget_SetTabSpacingH

IWIdget_GetTabSpacingV

IWidget_SetTabSpacingV

IWidget_GetActiveTabWidth

IWIdget_SetActiveTabWidth

IWIdget_GetInactiveTabWidth

IWidget_SetInactiveTabWidth

IWidget_GetTabActiveFontClass

IWidget_SetTabActiveFontClass

IWIdget_GetTabInactiveFontClass

IWidget_SetTabInactiveFontClass

IWidget_GetImageStaticWidget

IWidget_SetImageStaticWidget



Using tab widget

The tab widget renders each tab using a single wrapped widget that the tab widget creates and managesitself, internally.

By default, this rendering widget is an image static widget which therefore provides the ability for anapplication to display a label and an optional icon on each tab. This is especially useful when several tabsare present, or if the extent of the constraining container is such that the label text won't fit, but an imagewill suffice to communicate the tab's contents.

The data to be displayed on the label of each tab is, by default, stored in a vector model and it is up tothe application using the tab widget to initialize the data in the model to contain the information to bedisplayed on each tab label.

On a more macro level, applications typically wrap the tab widget around a content widget that becomesthe destination for the content specific to each tab. While the tab widget does not manage the content tobe displayed within each tab, it is responsible for displaying what is on each tab -- i.e. the labels or iconsdisplayed, as above, for tab one, two or three.

To create a tab widget, an application would do the following.

1. Create an instance of the decorator by calling ISHELL_CreateInstance() with a ClassID of thedecorator, AEECLSID_TabWidget, to retrieve a reference counted instance of the tab widget.

IWidget *piw = 0;ERR_TRY( ISHELL_CreateInstance(me->piShell, AEECLSID_TabWidget, (void**)&piw) );

2. Create the content widget that will be used to render the content of each tab.

ERR_TRY( ISHELL_CreateInstance(me->piShell, AEECLSID_CardContainer, (void**)&picc) );ERR_TRY( ICardContainer_QueryInterface(picc, AEEIID_Widget, (void**)&piwc) );

3. To associate a child widget with the decorator, applications should use IDecorator_SetWidget().This wraps the tab widget around the content widget.

// SetWidget also connects the child's ViewModel to the decorator's ViewModelIDecorator_SetWidget((IDecorator*)(void*) piw, piwc);

4. Store the text and icon for each tab label in an ImageStaticInfo data structure and add this item tothe tab widget's vector model.

// set up the tab dataERR_TRY( IWidget_GetModel(piw, AEEIID_VectorModel, (IModel**)(void**) &pimVector) );ERR_TRY( IVectorModel_SetPfnFree(pimVector, (PFNNOTIFY)ImageStaticInfo_Delete));

5. Insert the decorator in a container that up the hierarchy leads to the root container, to makesure that the container is displayed on the screen. See the C/C++ API Reference for details onIDecorator and IWidget_SetTabXXX.

// create and add static widgets to the card containerpw = awTabs;pszzTab = awzzTabImages;pszzChild = awzzChildImages;

for (I=0; I < (int) NTABS; I++) { ImageStaticInfo *pisi = 0; pii = ISHELL_LoadImage(me->piShell, pszzTab);

ERR_TRY( ImageStaticInfo_New(&pisi, pii, pw) ));



RELEASEIF(pii);

ERR_TRY( IVectorModel_Add(pimVector, pisi));

if (I == (int) NTABS-3) { ERR_TRY( SampleTouchApp_ICardContainer_AddDateTime(picc, me->piShell, me)); } else if (I == (int) NTABS-2) { ERR_TRY( SampleTouchApp_ICardContainer_AddPropChild2(picc, me->piShell, me)); } else if (I == (int) NTABS-1) { ERR_TRY( SampleTouchApp_ICardContainer_AddPropChild(picc, me->piShell, rgb[i]) ); } else { ERR_TRY( SampleTouchApp_ICardContainer_AddImageChild(picc, me->piShell, pszzChild, rgb[i]) ); }

pw += WSTRLEN(pw) + 1; pszzTab += STRLEN(pszzTab) + 1; pszzChild += STRLEN(pszzChild) + 1;}

Text widget

The text widget provides text entry facilities to the widget framework.

• Text controller implements the text entry modes.• Properties allow configuration of alignment, font, multi-line support, and colors.

Files to include:


AEETextWidget.h AEETextWidget.bid

The text widget is being used to input an email message.




Text widget interfaces used

Text widget uses the IWidget interface.


Required Files

AEEIModel.h

AEEIHandler.bid

AEEICanvas.h

AEEStdErr.h

Interface ID

AEEIID_IWidget



Text widget helper functions

Header files

IWidget_GetFont

IWidget_SetFont






IWidget_GetFlags

IWidget_SetFlags

IWidget_SetFGColor

IWIdget_SetSelectedFGColor

IWIdget_SetSelectedBGColor



IWIdget_GetCaretPos

IWIdget_GetCaretWidget

IWidget_SetCaretWidget

IWIdget_GetStartLine

IWidget_GetPreviousLine

IWidget_GetNextLine

IWidget_GetTextController

IWidget_SetTextController

IWidgetSetPasswordMaskChar

IWidget_GetPasswordMaskDelay

IWidget_SetPasswordMaskDelay

IWidget_GetTextControllerModeKey

IWidget_SetTextControllerModeKey

IWidget_GetTextRects

IWidget_GetAvoidRects

IWidget_SetAvoidRects

IWidget_GetTabStops



Header files

IWIdget_SetTabStops

Using text widget

The widget manages interaction between the application and OEM provided services for supportingvarious text entry methods (multitap, T9, etc), handles display of the text entry caret, and providesaccessor functions for storing and retrieving entered text.

...// Set alignment, multi-lineIWidget_SetFlags(piw, flags); // Set font to be usedIWidget_SetFontClass(piw, fontClsId);...

Text widget uses ITextModel for data. Text widgets are usually implemented in conjunction with a staticwidget, to provide data entry fields in an application. By default, the text widget is displayed withina border and the widget can be set to support either single or multiline text entry. When configuredto support multiline text entry, the text widget will set its preferred height to at least two lines. Theborder abides to all the same properties as other borders in the widget framework (color, thickness,transparency, etc).

The text widget is implemented as using a controller that is usually provided by the OEM asAEECLSID_TextController. However, if the OEM has not provided a text controller, the text widget willuse the default text controller provided by the widget framework. Text entry is actually captured by andhandled by the text controller, with that object modifying the text model tied to both the controller and thetext widget. The text widget listens for changes to the text model and will be notified of changes to themodel, which in turn triggers the text widget to update what the user sees on the display in response tokey presses. The relationship between the text widget, controller and text model can be illustrated withthe following diagram, which illustrates how the keys the user presses go from the user's thumb to thedisplay.

The text widget is also attached to a view model, which will send scroll events (with 'evCode' set toEVT_MDL_SCROLL_CHANGE) to other objects registered with the text widget's view (i.e. scroll bars,etc).

Text entry keys are handled (absorbed) by the TextWidget even if they did not result in a visible change tothe widget or data change in the model. For instance when the cursor is at the beginning of text, the CLRkey will be absorbed (TRUE will be returned) but will not affect the cursor or current focus of the widget.



If an application wishes to act different in these situations, the cursor position of the TextWidget can beanalyzed, and if necessary the key can be handled by the application instead.

To create a text widget, an application would do the following.

1. Call ISHELL_CreateInstance() with a ClassID of AEECLSID_TextWidget to create a text widget.

ERR_TRY( ISHELL_CreateInstance(piShell, AEECLSID_TextWidget, (void**)ppo) );

ISHELL_CreateInstance() will retrieve a reference counted instance of the class that manages thewidget.

2. Call IWidget_GetModel() to retrieve the text model associated with the text widget and populate thismodel with any existing text.

if (AEE_SUCCESS == IWidget_GetModel(*ppo, AEEIID_TextModel, (IModel **) (void**) &pitm)) { ITextModel_SetSel(pitm, -1, -1); ERR_TRY( ITextModel_ReplaceSel(pitm, pwszText, -1)); ERR_TRY( ITextModel_Release(pitm));}

3. If the text widget is to contain multiple lines of text, call IWidget_SetFlags() with theTWF_MULTILINE flag set.

ERR_TRY( IWidget_SetFlags(*ppo, TWF_MULTILINE | TWF_VERTICALNAV));4. Call IWidget_SetExtent() to establish the extent of the text widget.

IWidget_SetExtent(piw, &we);5. If the widget is to support some indication that the text can be scrolled, create and attach a scrollbar

by calling IDecorator_SetWidget(), making sure that the scrollbar and text widget share the sameview model.

ERR_TRY( SampleTouchApp_IShell_CreateTextWidget(me->piShell, &piw, awWaveSpeech, 150) );ERR_TRY( SampleTouchApp_IWidget_WrapInScrollbar(&piw, me->piShell) );we.width = MIN(120, me->rcClient.dx - 4);we.height = MIN(150, me->rcClient.dy - 4);IWidget_SetExtent(piw, &we);

Title widget

This widget is a decorator that provides a user interface element that displays a text label above thewidget it wraps.


Files to include:


none AEETitleWidget.bid

Title widget interfaces used

Title widget uses the IWidget interface.

IWidget



The IWidget interface provides many common controls, and can used as a base class for new customwidgets and UI objects.

Required Files

AEEIModel.h

AEEIHandler.bid

AEEICanvas.h

AEEStdErr.h

Interface ID

AEEIID_IWidget

Title widget helper functions

Header files

IWidget_GetTitleWidget

Using title widget

The text displayed by the title widget is a static widget and responds to all of the property and displaycharacteristics common to text objects.

Clients that wish to directly manipulate the text or text characteristics of a title widget would first need toobtain a pointer to the static widget by requesting the PROP_TITLEWIDGET from the title widget, thenmanipulate this widget (or the value model associated with the static widget) directly.

Though the title widget by default will bind itself to a static widget as the object displayed as the wrappedwidget's decorator, an application may choose to replace the static widget with a more complex elementsuch as an image static, a bitmap, or something much more elaborate.

To create a title widget, an application would do the following.

1. Call ISHELL_CreateInstance() with a ClassID of AEECLSID_TitleWidget to create a title widget.ISHELL_CreateInstance() will retrieve a reference counted instance of the class that manages thewidget.

2. Make any desired modifications to the title widget's border. For example, setting the extent, definingthe border color (if a visible border is desired), etc.

3. Retrieve the PROP_TITLEWIDGET property from the title widget to gain access to the static widgetused to manage the title's text.

4. Make any desired modifications to the static widget. For example, setting the font, text color andposition of the text.

5. Create the widget that will be wrapped by the title widget.6. Call IDecorator_SetWidget() to wrap the title widget around the widget it decorates



Viewport widget

This widget provides a visual view into some larger content area. Imagine a window that floats abovethe content area that limits the current field of view, but is able to move over the content to bring hiddencontent into view.

Viewports are usually adorned with scrollbars or scroll indicators which would allow the user to scrollmore (or less) of a display into view

Files to include:

Header file ClassID File

none AEEViewportWidget.bid

An example of the viewport widget wrapping a static widget is seen being decorated by scrollbars.


Viewport widget interfaces used

Viewport widget uses the IWidget, IContainer and IDecorator interfaces.




Required Files

AEEIModel.h

AEEIHandler.bid

AEEICanvas.h

AEEStdErr.h

Interface ID

AEEIID_IWidget

IContainerThe IContainer interface is an abstract interface intended as the base from which more complex containerinterfaces inherit.

Required Files

AEEIContainer.h

Interface ID

AEEIID_IContainer

IDecoratorIDecorator is an abstract interface meant to be a base from which more complex widget implementationsare based.

Required Files

AEEIDectoror.h

Interface ID

AEEIID_IDecorator

Viewport widget helper functions

Helper functions

IWidget_GetIncrement

IWidget_SetIncrement

IWidget_GetOffsetX

Widgets Technology Guide for Developers Glossary


Helper functions

IWidget_SetOffsetX

IWidget_GetOffsetY

IWidget_SetOffsetY



IWIdget_GetLayoutStyle

IWidget_SetLayoutStyle

IWidget_GetFlags

IWidget_SetFlags

Using viewport widget

The Viewport Widget is instantiated by passing AEECLSID_ButtonWidget into ISHELL_CreateInstance.

To create an image widget, an application would do the following:

1. Create the content widget that will use the viewport as a decorator.2. Call ISHELL_CreateInstance() with a ClassID of AEECLSID_ViewportWidget to retrieve a reference

counted instance of the viewport widget.3. Call IDecorator_SetWidget() to attach the viewport as a decorator of the widget providing the

content to be viewed.

To enable your XY container to be scrollable, you need to decorate it with a viewport widget (a decoratorwidget). The reason for this is an XY container does not know how to handle the scroll events, a viewportwidget does. In your code you will have the XY container that is wrapped (decorated) by a viewportwidget, that is wrapped by a scrollbar widget. You would then use the IWidget pointer from the scrollbaras the primary widget (WID_FORM) for the form. You should also ensure that the extent is being set forthe container, the viewport and the scrollbar, so that it displays as expected.

Glossary

APIApplication Programming Interface

Applet classesIdentified by an AppletID and declared via an Applet primitive in the CIF.

AppletIDA ClassID for an Applet class.

BARBREW Applet Resource file; binary output file from the Brew MP Resource Editor that contains thefollowing resources in binary format - string, object, binary.

BIDBREW Class ID file; generated by the BREW ClassID Generator, and contains the ClassID

BREW

Mobile application development platform; versions 1.0 through BREW SDK® 4.0.xAn open, extensible client platform developed by Qualcomm to support system and applicationsoftware, including personalized and branded user interfaces. May be used with most wirelessdevices and networks. A component of the BREW System.



Brew MPBrew Mobile PlatformA flexible operating system platform for mobile devices. It is open and extensible and works with anysoftware ecosystem throughout the global operator and manufacturer communities.

Brew MP ApplicationA self-contained software package that exposes an applet class (implements the IApplet interface)that can be loaded and executed in BREW Shell (or Thread), and defined in interface header files (orIDL file if using qidl.exe).

CARComponent application resource file; Lua-based source resource file for BAR, defines resources thatare available to the module at runtime

CIFComponent information file; Lua-based source file for MIF, defines resources that a module requiresto execute in the Brew MP application execution environment; replaces XML-based MFX format

ClassA user-defined type that encapsulates data and behavior (i.e. functions) to provide implementation ofone or more interfaces it exposes.

ClassIDA 32-bit globally unique numeric ID, typically in the form of AEECLSID_XXX, that is defined in a BIDfile generated by the BREW ClassID Generator. ClassIDs are a unique ID given to each class whenit is defined, specifying an entry subroutine to create an instance of that class. ClassIDs can also beused as a privilege to use the class.

ControllerIn the MVC pattern, the controller manages the communication of data and the business rules used tomanipulate the data to and from the model.

Decorator patternA design pattern that allows new/additional behavior to be added to an existing class.

ExtensionsA self-contained software package that exposes one or more "Non-Applet classes" with interfaces thatcan be accessed by any number of Brew MP applications for extended functionality

InterfaceSimilar to a C++ abstract base class having only pure virtual methods that provide a specificationcontract that a implementing class must meet

Interface IDA unique ID given to each interface when it is defined in interface header files (or IDL file if usingqidl.exe); typically in the form of AEEIID_XXX.

MIFModule information file; Binary file containing module-specific information (e.g., classes declared,privileges), and resources (e.g., applet names, icon image). Created by compiling a module's CIF andCAR files. Every Brew MP module requires one MIF file.

ModelIn the MVC pattern, the model represents the data of the application.

ModuleAn executable binary file that consists of one or more components compiled into a single image

MVCModel-View-Controller pattern; isolates business logic from the user interface to produce anapplication where either the visual appearance of the application or the underlying business logic canbe modified with affecting the other.

Observer patternDesign pattern in which an object maintains a list of its dependents, called observers, and notifiesthem automatically of any state changes, usually by calling one of their methods

Root container



The highest level container defined for a display that can contain widgets, decorators, and childcontainers and manages the drawing of all children.

StaticWidgetA widget used when a region of read-only text is needed on the display for a dialog box or for a textualportion of a containing widget

TextWidgetA widget used when user text input is needed for a dialog box or for a textual portion of a containingwidget

ViewIn the MVC pattern, the view corresponds to the elements of the user interface such as text, radiobuttons, etc.

WidgetRepresents a visible element on the display, such as a radio button or scrollbar

ui widgets techgd dev

Documents