Developer

API Reference

AEECLSID_SoftkeyWidget

Brew Release
Brew MP 1.0.2
See Also
Model Events Widget Events ISHELL_CreateInstance() IWidget AEECLSID_StaticWidget
Description
The softkey widget is a user interface element that provides software navigation to devices that possess a pair of hardware buttons directly below the display. These buttons are commonly referred to as "softkey buttons" and are usually accompanied by a pair of commands placed on the display directly above each button -- one command for the left button, and one for the right. The commands to which the buttons map can be changed, which is why they're referred to as soft keys.
To illustrate, imagine a device with a pair of buttons -- completely separate from the rest of the keypad -- placed directly below the screen. The illustration below depicts such an environment:
             |                                         |
             |      Do you want to send this photo?    |
             |                                         |
             +--------------------+--------------------+
             |       Cancel       |         OK         | <--- Softkey Widget
             +--------------------+--------------------+
                  ============         ============
                 |            |       |            |
Left Softkey --> |            |       |            | <-- Right Softkey
                  ============         ============

In the above example, when the user presses the left softkey button, they would be selecting the command positioned immediately above -- "Cancel" -- which would be designated as softkey one in the softkey widget. Pressing the right softkey would select the item on the right of the widget, softkey two.
As the user navigates through an application, the commands presented in the softkey widget would change to reflect the current application context, as revealed through the main body of the display.
Functionally, the softkey widget is a prop container consisting of a pair of embedded static text widgets: softkey one and softkey two. Though the layout and interaction of these widgets are handled together by the softkey widget, each is displayed and their functions are independent of the other. For example, an application may 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 class ID of AEECLSID_SoftkeyWidget to
          create a softkey widget.  ISHELL_CreateInstance() will retrieve a reference
          counted instance of the class that manages the widget.
       2. IWIDGET_SetText() to specify the text to be displayed within each of the
          softkeys.
       3. Call IWidget_SetExtent() to set the size of the softkey widget.
       4. As necessary, call various IWIDGET_Setxxxxxx() functions to override any of
          the default visual characteristics of the widget.  For example, if the
          text of one softkey should be bright blue, or if the border of the widget
          should possess a shadow. 

The softkey widget, by default, will be created with the following characteristics:
         Active border width:  0 pixels
       Inactive border width:  0 pixel
               Right Padding:  4 pixels 
                Left Padding:  4 pixels                
            Foreground color:  RGB_BLACK
            Background color:  RGB_NONE
                 Label Flags:  Middle/Left (Softkey One)
                               Middle/Right (Softkey Two)
                Extent Width:  50
               Extent Height:  10

Supported Events: The softkey widget, as a widget that embeds multiple objects in a prop container, will first pass all received events to the property container, returning TRUE if the event is accepted and handled by the container. These events will include those that manipulate the border, shadow, color and other visual attributes of the widget. If the event is not handled by the container, the softkey widget will attempt to process the event itself. Finally, if the event is handled by neither the container nor the softkey widget, it will be passed to each of the widgets embedded in the container.
The softkey widget will accept and handle the following softkey-specific events:
Event                 Description
-----                 ------------------------------------------------------------
EVT_WDG_SETPROPERTY:  The softkey widget responds to this event by attempting to set the
                      property identified by the 'wParam' parameter.  The softkey widget
                      recognizes those properties defined in the "Properties" section, below.

EVT_WDG_GETPROPERTY:  The softkey widget responds to this event by attempting to retrieve the
                      property identified by the 'wParam' parameter.  The softkey widget
                      recognizes those properties defined in the "Properties" section, below.


Properties:
Property              Description
--------              ------------------------------------------------------------
PROP_SOFTKEY1:        This property contains a pointer to the widget that will be displayed
                      in softkey one -- i.e. the static text widget on the left side of the
                      softkey widget.  When setting this property, BREW will retrieve and
                      release the existing widget assigned as softkey one, prior to adding
                      the new widget.
                             
                        Property Value:  IWidget **

PROP_SOFTKEY2:        This property contains a pointer to the widget that will be displayed
                      in softkey two -- i.e. the static text widget on the right side of the
                      softkey widget.  When setting this property, BREW will retrieve and
                      release the existing widget assigned as softkey two, prior to adding
                      the new widget.
                             
                        Property Value:  IWidget **
Required Model: None
Model Data: None
Instantiaion
The softkey widget is instantiated by passing AEECLSID_SoftkeyWidget into ISHELL_CreateInstance.
Cleanup
The softkey widget is reference-counted. When you are done with your reference to the softkey widget, you should Release that reference. Any softkey widget specific cleanup will be handled for you when all references are released.
Default Interface Name
Comment
It is very important to note that the softkey widget only creates the softkeys. It does not handle EVT_KEY events. Applications must separately create an appropriate wrapper around the widget, so that when AVK_SOFT1/AVK_SOFT2 is pressed, applications change the visual representation of underlying static widgets. Static widgets can be retrieved by PROP_SOFTKEY1/PROP_SOFTKEY2 properties.
  • Follow