Developer

API Reference

IWidget

Brew Release
Brew MP 1.0.2
Description

IWidget is the interface for describing user interface elements of a wide variety of types and capabilities including containers, forms, controls such as checkboxes and radio button, static and editable text, decorators and many other UI objects. The IWidget interface provides many common controls, and can used as a base class for new custom widgets and UI objects. Widgets, in general, possess characteristics of both display and behavior. For example, a checkbox maintains a visual appearance on the device display depending on its current state, and also acts in a particular way when the user checks or unchecks the control. Other widgets may not invite operator interaction and possess only display characteristics. For example, a decorator widget that adds a shadow effect to a popup menu, will support interfaces to draw itself on the display, but will not expect to receive operator events such as key presses.
The following APIs are provided to support an object reference counting mechanism for objects to manage their own memory instances.
       IWidget_AddRef()
       IWidget_Release()

The widget framework notifies its objects of various states or property changes by sending the appropriate BREW Widget events in addition to the common BREW interface events. The interface provides APIs to receive and handle events passed to the widget as well as to hook its own event handler into the normal widget event handling mechanism. The following APIs are provided to support event handling to the object:
       IWidget_HandleEvent()
       IWidget_SetHandler()

The widgets contain defined bounds within which they will get drawn. In addition each widget can determine the size under ideal circumstances. The following APIs are provided to retrieve or set a widget's extent (the relative width and height of a widget's bounding rectangle).
       IWidget_GetPreferredExtent()
       IWidget_SetPreferredExtent()
       IWidget_GetExtent()
       IWidget_SetExtent()

Objects within the widget framework maintain a hierarchy of parent/child relationships, wherein a container may enclose and manage one or more child objects. The children of a parent container may be widgets, or additional containers, with each child receiving events and being managed by its parent. The following APIs are provided to retrieve or set a widget's container object.
       IWidget_GetParent()
       IWidget_SetParent()

Each widget will draw itself within the bounds defined by its current extent, clipped to the clipRect defined in ICanvas, at a specific position on the device display. The following APIs are provided to manage the drawing of a widget's contents.
       IWidget_Draw()
       IWidget_IntersectOpaque()

The specified widget model handles the data associated with the widget. The following APIs are provided to retrieve or set the model that manages the value of the data represented by a widget.
       IWidget_GetModel()
       IWidget_SetModel()

Required header files:
   AEEIModel.h
   AEEIHandler.h
   AEEICanvas.h
   AEEStdErr.h
Usage
The typical usage of a class implementing IWidget would be to create an instance of a class that implements IWidget, such as AEEClSID_CheckWidget. Then set any properties desired in order to customize the appearance or behavior of this instance, such as background colors, border colors, and the initial model data. Finally attach the widget to a parent container (hopefully one that eventually chains up to the RootContainer so the user can see the widget) and, of course, enjoy your new widget based application.
Methods
Comment
The IWidget interface used with the AEECLSID_HTMLWidget replaces the IHTMLViewer interface, which has been deprecated.
The IWidget interface used with the AEECLSID_ImageWidget class replaces the IImageCtl interface, which has been deprecated.
The IWidget interface used with the AEECLSID_ListWidget class replaces the IMenuCtl interface, which has been deprecated.
  • Follow