Objective

This document explains how custom touch controllers can be created by using touch controllers from the Brew MP UI Widgets platform. This document references an implementation of a custom touch controller similar to the CheckTC (Touch Controller), which is provided in the Brew MP platform. The difference is that this touch controller selects the widget (like CheckWidget) on a pointer down event as oposed to on a pointer up event. This custom touch controller uses GenericTC as a base. This takes advantage of its provision-like click notifications.

Requirements

A simple way to create a custom touch controller is to create an extension using an existing Brew MP UI Touch Controller. The following steps provide an overview of what needs to be done to achieve this. Each step is described in more detail in the example. For more information on Brew MP extensions, see the C Extension Visual Studio Primer.

To create a custom touch controller

1. Define the internal structure of the touch controller.
2. Define the constructor of a custom touch controller.
3. Set the widget.
4. Customize event handling.
5. Free memory.

Sample code location

Related information

• See the Widgets Touch Technology Guide
• See the C Extension Visual Studio Primer

Objective

This document describes how to create and set up an ICamera object, preview a snapshot or movie, and save a snapshot or movie within a Brew^® Mobile Platform (Brew MP) application.

The example code included is from the c_samplecamera application, which you can download from the How To section of the Brew Mobile Library. You can extract the contents of the .zip file, compile the application, and run it on the Brew MP Simulator.

Note: Brew MP devices do not display camera preview frames on screen sizes 176x144, 128x96, and 96x80. This is a problem in the platform code. This capability will be added in a future release.

Requirements

To use the ICamera interface, you must have:

• A Brew MP enabled device with camera hardware and support.
• If testing on the Simulator, a direct-show compliant web cam attached to the computer.
• Brew MP 1.0 SDK rev 1.0 or greater.
• A MIF file with privileges for AEEPRIVID_PLFILE and AEECLSID_CAMERA. If your device has multiple cameras, then AEECLSID_CAMERA2, AEECLSID_CAMERA3, and AEECLSID_CAMERA4 might be necessary.

This document assumes that you are familiar with the Brew MP C Application Primer.

ICamera Modes

ICamera has four modes: Ready, Preview, Snapshot and Movie. These modes are a state machine. You can find the current mode by calling the ICAMERA_GetMode() function.

ICamera starts in the Ready mode, and can transition to the other modes. The Preview, Snapshot, and Movie modes can only transition to the Ready mode. To transition from the Preview mode to the Movie mode, you must transition to the Ready mode, and then from the Ready mode to the Movie mode.

State transitions are not complete until the callback function is called. For transitions to the Ready mode, the callback function has the status CAM_STATUS_DONE in nStatus. For transitions to the other modes, the callback function has the status CAM_STATUS_START in nStatus.

Return Values

ICamera has both synchronous and asynchronous functions. A return value of SUCCESS for a synchronous function means the operation was successfully completed.

An asynchronous function initiates an action and returns control to the application. A return value of SUCCESS for an asynchronous function means the command was accepted. You find out about the result of the action from the callback function.

If a function returns CAM_PENDING, the operation is asynchronous and the success of the operation will be in the AEECameraNotify structure in the callback function. An asynchronous operation is complete when the callback function nStatus is equal to CAM_STATUS_DONE.

Refer to the Brew MP API Reference for information on specific ICamera functions, their use, and return values.

Sample code location

This document describes how to create a custom widget to use in widget-based applications. Modifying the Brew^® MP UI Widgets code is strongly discouraged. Instead, it is recommended that your own widgets be implemented outside of Brew MP UI Widgets in their own extension.

Objective

This document explains how custom widgets can be created by using widgets from the Brew MP UI Widgets platform. The custom widget implemented is a CheckBoxStatic Widget, consisting of both a text label and a radio button. Prop container is used as a base widget to implement this widget. Prop container has a checkbox and static Widget inserted in it. This creates the basic look and feel of the CheckBoxStatic widget. This example overrides the event handler for custom event handling.

A model is needed to store the data associated with this widget. The CheckBoxStatic widget has a value model attached to it that uses the CheckBoxStaticWidget_ModelData as the model. CheckBoxStaticWidget_ModelData has two members, the text that can be used by the label, and checkState to denote whether checkbox is enabled or not.

Requirements

To create a CheckBoxStatic Widget, you need to create an extension using existing Brew MP UI Widgets. The following steps provide an overview of what needs to be done. Each step is described in more details in the examples. For more information on Brew MP extensions, see the C Extension Visual Studio Primer.

1. Create a public header file for CheckBoxStatic Widget.
2. Define the internal structure of the widget.
3. Update a CheckBoxStatic_New function.
4. Property handling.
5. Freeing memory.

Sample code location

Related information

• See the Widgets Technology Guide
• See the C Extension Visual Studio Primer

Attaching to a model and handling the events that model sends is one of the core components of the Widgets user interface system. It allows for many powerful things, ranging from defining actions to be taken on state changes, to creating a custom widget without even creating a single actual widget of your own.

Models generally come in two categories for widgets: View Models and Value models. View models are read-only models used to pass state change information the user. This can be used to create custom actions based on state change, such as loading a file when the user clicks a button or updating the contents of an email pane when a new message is selected in a list. Value models are mutable models used by widgets to represent core values that affect the look of the widget. Examples of these are the boolean state of a Check widget or the list of items that will be displayed by a List widget.

In general, View Model notifications are be used by application-level logic to provide for links between different components of the user interface. Value model notifications are be used to implement custom widgets that display based on more complicated value information.

Objective

This document explains the process for attaching to a model, determining whether the event sent out by the model was desired, and taking actions based on those events. It provides the steps necessary to detach yourself from a model when you no longer need the notifications.

Requirements

To attach to the View Model of a widget, an application needs to do the following. Each item is described in greater detail in the example sections found below.

1. Create a listener function.
2. Create the widget to which you wish to attach.
3. Create a model listener and initialize it with the listener function and user data.
4. Get the view model using IWidget_GetViewModel().
5. Attach your model listener to the model.

To attach to the value model of a widget, an application follows a similar process. Each item is described in greater detail in the example sections found below.

1. Create a listener function.
2. Create the widget to which you wish to attach.
3. Create a model listener and initialize it with the listener function and user data.
4. Get the value model using IWidget_GetModel().
5. Attach your model listener to the model.

To remove yourself from a model, an application calls LISTENER_Cancel() on their model listener. This is described in greater detail in the example sections found below.

Sample code location

View model example: create a listener function

A listener callback is a function that takes the form specified below. The first parameter is user-specified data, specified when the listener is created. The second parameter is the model event that caused the callback to occur.

static void c_listwidgettouch_app_ListListen(char* listType, ModelEvent* pEvt)       
{       
   if (pEvt->evCode == EVT_MDL_SCROLL_CHANGE) {       
      ScrollEvent* pse = CAST(ScrollEvent*, pEvt);       
      ...       
   }       
   else if (pEvt->evCode == EVT_MDL_FOCUS_CHANGE) {       
      FocusEvent* pfe = (FocusEvent*)pEvt;       
      ...       
   }       
   else if (pEvt->evCode == EVT_MDL_FOCUS_WRAP) {       
      FocusEvent* pfe = (FocusEvent*)pEvt;       
      ...       
   }       
   else if (pEvt->evCode == EVT_MDL_WIDGETELEM_STATE) {       
      WidgetElemStateEvent* pwese = (WidgetElemStateEvent*)pwese;       
      ...       
   }       
}

Value model example: create a listener function

A listener callback is a function that takes the form specified below. The first parameter is user specified data, specified when the listener is created. The second parameter is the model event that caused the callback to occur.

static void c_touchtransparency_app_TouchModeListener       
                       (TouchModeData* pData, ModelEvent* pEvt)       
{       
   AEEResult nErr;       
   IValueModel *piValueModel = NULL;       
   boolean isEnabled;       
       
   // Get the state of the radio button.       
   ERR_TRY( IModel_QueryInterface(pEvt->pModel, AEEIID_IValueModel,        
                                          (void**)&piValueModel) );       
   isEnabled = IValueModel_GetBool(piValueModel);       
   // If the radio button is now enabled, set our touch mode on the target        
   // (the top widget)       
   if (isEnabled) {       
      (void)IWidget_SetTouchMode(pData->piwTarget, pData->nTouchMode);       
   }       
       
ERR_CATCH:       
   RELEASEIF(piValueModel);       
}       

Error handling

Make sure that all of the executed APIs have returned AEE_SUCCESS in order to proceed with the next step and for correct execution.

Related information

• See the Widgets Technology Guide
• See the C/C++ API Reference

Objective

This topic describes how to

• Connect a Brew^® MP application to a PC via USB/IPort

• Send Attention (AT) commands to the Attention Command Processor (ATCOP)

Requirements

The application needs to use the correct COM port and the correct commands.

Example - Determining which COM port to use

To determine which COM port to use:

1. Open Device Manager.

   Under Modems, you should see a modem corresponding to the device.

2. Right-click on the modem and select Properties.

3. In the Properties dialog box for the modem, click the Modem tab.

   At the top of the Modem tab, the Port value indicates the COM port to use.

Example - Sending AT commands to the ATCOP

After the application successfully sends an AT$BREW command, the application communicates with the Brew MP Serial Command Processor (BSCOP). The BSCOP commands have numbers prepended to them, such as 01ver or 02app.

If the application opens AEESIO_PORT_INCOMING, the application gains control of the port that enters (or is already in BSCOP). The port also only opens when the transition into BSCOP occurs.

Note: If you're writing an internal tool for the device, you may want to consider using Connect. It handles the serial port/connectivity issues, provides reliability, and has other features such as the ability to copy files, send events, and start applets.

The following sample code is from a file called siousage.c. SIO is a protected class. To create it, you must declare a dependency on AEECLSID_SERIAL in your MIF.

// Our applet's structure
typedef struct SIOUsage
{
   AEEApplet      a;
   IPort         *piPort;
   AEECallback    cbReadable;
   AEECallback    cbWriteable;
} SIOUsage;

static int SIOUsage_Init(SIOUsage *pme)
{
   int nErr;

   nErr = ISHELL_CreateInstance(pme->a.m_pIShell, AEECLSID_SERIAL,
                                (void**)&pSioPort->piPort);

   if (nErr != SUCCESS)
   {
      return EFAILED;
   }

   // The following line opens the USB serial port.  To open the RS-232
   // serial port, use AEESIO_PORT_SIO1
   nErr = IPORT_Open(pme->piPort, AEESIO_PORT_USB1);
   if (nErr != SUCCESS && nErr != AEEPORT_WAIT)
   {
   // There was some unknown error opening the port
      DBGPRINTF("Error opening port");
      return EFAILED;
   }

   // Setup our callbacks.  These are called when there is *probably* data
   // to be written or read.
   CALLBACK_Init(&pme->cbReadable, SIOUsage_TryRead, (void*)pme);
   CALLBACK_Init(&pme->cbWriteable, SIOUsage_TryWrite, (void*)pme);
   IPORT_Readable(pme->piPort, &pme->cbReadable);
   IPORT_Writeable(pme->piPort, &pme->cbWriteable);

   // At this point, if nErr is AEEPORT_WAIT, the serial port is opening.
   // We'll know this is complete when our cbWriteable callback fires.
   // Normally, we'll receive AEEPORT_WAIT instead of SUCCESS.
}

static void SIOUsage_TryRead(void *po)
{
   SIOUsage *pme = (SIOUsage*)po;
   int32 dwRead;
   char buf[100];

   // We can *probably* read data here
   dwRead = IPORT_Read(pme->piPort, buf, sizeof(buf));

   // Log a message if we did read data
   if (dwRead > 0)
   {
      DBGPRINTF("Read %ld bytes of data", dwRead);
   }

   // Remember that we need to reset our readable callback
   IPORT_Readable(pme->piPort, &pme->cbReadable);
}

static void SIOUsage_TryWrite(void *po)
{
   SIOUsage *pme = (SIOUsage*)po&
   int32 dwWrite&
   char *pBuf = "Hello World!";

   // If you want to know if the port successfully got opened, do it here.
   //   what you want to do is nErr = IPORT_Open(pme->piPort, NULL);

   // We can *probably* write data here
   dwWrite = IPORT_Write(pme->piPort, pBuf, STRLEN(pBuf));

   // Log a message if we did read data
   if (dwWrite > 0)
   {
      DBGPRINTF("We wrote %ld bytes of data", dwWrite);
   }

   // Remember that we need to reset our writeable callback
   IPORT_Writeable(pme->piPort, &pme->cbWriteable);
}

Objective

This topic describes how to create an application for handsets with extended keyboards. The interfaces described were implemented with full support in Brew^® 3.1.5 SP01 unless otherwise noted in a handset's device pack. Handsets with earlier Brew versions may have partial or modified support of the interfaces described. Always consult a handset's device pack specification listing to determine handset capabilities.

Requirements

Use the IKeysMapping and IKeysConfig interfaces in applications to decode the key event information. Key events contain extra information to communicate the meaning of key presses to an application.

For handsets with extended keyboards, such as QWERTY, a single key can have multiple input values. For example, an [A] key may also be capable of giving an input of 'a' or a symbol such as '@'. In addition, a combination such as [Function] + [A] can mean an input of '#' on one handset while it means '@' on another.

Device pack requirements

To support IKeysMapping, the device pack must include a map.csv file that provides [key] + [modifier] = [character] mappings. The device pack field IDS_DD_EXTENDED_KEYPAD_SUPPORT indicates whether the device supports an extended keypad using the standard Brew MP behavior described in this topic.

If the device pack contains a map.csv file, IKeysMapping is supported on the Brew MP Simulator, which provides the correct key events as described in this document. When using the Simulator, you can use the PC keyboard to press key combinations, such as [Shift] + [A]. In the Properties tab of the Simulator, a device pack that provides support for IKeysMapping will have a value of Yes for the Extended keypad support field, as shown below.

Event handling

Key events contain the following information:

There are two types of key events:

• Primary key events

  • All pressed keys generate the standard key events: EVT_KEY_PRESS, EVT_KEY, and EVT_KEY_RELEASE.
  • For primary keys mapped to a character with a Unicode value, the wParam for the event contains the Unicode value for the character.
  • For primary keys that are alphabetical (A - Z), wParam contains the lower case Unicode value for the letter.
  • The AVK codes, AVK_A through AVK_Z are defined in AEEVCodes.h for convenience, and are equal to the lower case Unicode values for the key press. For example, pressing the [A] key will generate EVT_KEY events with wParam = 97 (the value of AVK_A and the Unicode value for 'a').

• Secondary key events

  • Secondary key events include one or more modifiers in addition to the primary key information.
  • The combination of the primary key and the modifiers identifies the secondary key.
  • When secondary key events occur, the wParam (primary key code) of an event is the same as it would be for a primary key event and the dwParam value contains the modifiers for the event.
  • The value reported in dwParam is a bitwise OR combination of all currently active modifiers.
  • All keypad event modifiers are defined in AEEVCodes.h. For example, with the [Left Shift] modifier set, pressing [A] will generate an event with the following parameters:

  eCode = EVT_KEY_PRESS (EVT_KEY and EVT_KEY_RELEASE events will
  be received in a similar fashion)
  wParam = AVK_A
  dwParam = KB_LSHIFT

  In the above example, dwParam may be replaced by any combination of modifiers that are valid on the handset, such as KB_SYMBOL, KB_CAPSLOCK, etc., and communicates to the application the modifier(s) that are active when the key is pressed. The possible combinations of modifiers are handset specific. The IKeysMapping interface provides methods to decode overloaded key values. The device pack field IDS_DD_EXTENDED_KEYPAD_SUPPORT specifies the support (YES/NO) of this feature for each specific handset.

Sample code location

Note: To use IKeysMapping on the Simulator, you must copy the map.csv file to the tools\simulation directory in the Brew MP SDK. Make sure to turn off Numlock, Capslock, and Scrolllock on the PC keyboard to avoid interference with keys mapping.

ITextCtl Support for extended keyboard functionality

If your application is using ITextCtl to receive text input from the the user, a new input mode, AEE_TM_EXTENDED_KEYS, was added to the ITextCtl interface in Brew 3.1.5 SP01. (Earlier Brew versions that use extended keypads may have partial support or no support for ITextCtl and may require application support to operate correctly.)

In the AEE_TM_EXTENDED_KEYS mode, ITextCtl automatically decodes key events by internally calling IKeysMapping and displays the correct character in the text box for the current sticky key state. For handsets supporting this input mode, an application should make the following call at the beginning of execution:

ITEXTCTL_SetInputMode(pMe->pITextCtl, AEE_TM_EXTENDED_KEYS);

Applications do not need to modify further the input mode of ITextCtl to properly display key events that are passed using the ITEXTCTL_HandleEvent() interface. Because ITextCtl is internally calling IKeysMapping on events it receives, the application should only pass in the raw key event values sent to the application by Brew MP, without any modification to these values.