Resources | developer.brewmp.com Resources | developer.brewmp.com

Developer

resources

Attaching to a Model and Handling Model Events

Base version:

Brew MP 1.0

Tested version:

Brew MP 1.0

Phone tested:

Yes

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

ZIP filename

Location

Run app

c_touchtransparency_app

Brew® MP Resources

  • Download and extract the ZIP file.

  • Compile the app.

  • Run it on the Brew MP Simulator.

c_listwidgettouch_app Brew MP Resources
  • Download and extract the ZIP file.

  • Compile the app.

  • Run it on the Brew MP Simulator.

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;       
      ...       
   }       
}

View model example: create the host widget

Create a widget as normal using ISHELL_CreateInstance() or other suitable function.

...       
ERR_TRY( ISHELL_CreateInstance(piShell, AEECLSID_ListWidget, (void**) &pidList) );       
ERR_TRY( IDecorator_QueryInterface(pidList, AEEIID_IWidget, (void**) &piwList) );       
...

View model example: create a model listener and initialize it with the listener function and user data

Tell the model listener what callback function and user data it should use. The first parameter is the model listener, the second is the callback function, and the third is the user data that will be sent to your function when the callback occurs.

...       
LISTENER_Init(pml, c_listwidgettouch_app_ListListen, (void*)pszListenerData);       
...

View model example: get the View model using IWidget_GetViewModel

...       
ERR_TRY( IWidget_GetViewModel(piwList, &piViewModel) );       
...

View model example: attach your model listener to the model

...       
(void)IModel_AddListener(piViewModel, pml);       
...

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);       
}       

Value model example: create the host widget

Create a widget as normal using ISHELL_CreateInstance() or other suitable function.

...       
ERR_TRY( ISHELL_CreateInstance(me->pIShell, AEECLSID_RadioWidget,        
                                           (void**)&piwButton) );       
...       

Value model example: Create a model listener and initialize it with the listener function and user data

Tell the model listener what callback function and user data it should use. The first parameter is the model listener, the second is the callback function, and the third is the user data that will be sent to your function when the callback occurs.

...       
LISTENER_Init(&me->radioButtonChanged[i], c_touchtransparency_app_TouchModeListener,       
                                               &me->listenerData[i]);       
...       

Get the Value model using IWidget_GetViewModel().

...       
ERR_TRY( IWidget_GetModel(piwButton, AEEIID_IValueModel, &piValueModel) );       
...       

Attach your model listener to the model.

...       
(void) IModel_AddListener(piValueModel, &me->radioButtonChanged[i]);       
...       

Value model example: cancel a model listener

...       
LISTENER_Cancel(&me->mlAlways);       
...       

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