Developer

API Reference

IDecorator

Brew Release
Brew MP 1.0.2
Description
IDecorator is an abstract interface meant to be a base from which more complex widget implementations are based. A decorator is, essentially, a container that manages one and only one widget. Widget implementations of the decorator widget typically function as a "visual enhancers" for the user interface. For example, the list, grid and pick widgets all lend unique organization and layout to the information displayed by a list widget. The blend widget -- also a decorator -- provides a color mixing filter to the widgets it wraps. The scrollbar is used as a list decorator to show relative position as the user moves through the widget that the scrollbar widget wraps (or, decorates). The border widget (yes, another decorator) manages the visual properties of another widget's physical border.
Decorators are wrapped around another widget and function as the parent to that widget. To illustrate, consider the decorator implementation of the tab widget and the content widget it will decorate. Visually, a tabbed interface looks like the following.
                                                                        
        +-----------------+ +-----------------+ +-----------------+
        |     Tab One     | |     Tab Two     | |    Tab Three    | <---- Tab Widget
        |                 | +-----------------+ +-----------------+
      +-+                 +-------------------------------------------+
      |                                                               |
      |                                                               |
      |                                                               | <--- Wrapped
      |                      Content for Tab One                      |      Content
      |                                                               | 
      |                                                               |
      |                                                               |
      +---------------------------------------------------------------+
      
                  A typical tab widget with attached content


The tab widget itself consists of only the tabs, with this decorator acting as the parent to the content widget it wraps. On the display, while the tabs and content appear to be one unified object, conceptually there are really two separate objects with a well defined parent/child relationship working together to create the illusion of a single interface object.
         Parent
   +------------------+        
   |                  |            Child
   |    Decorator   +------> +----------------+
   |                  |      |                |
   +------------------+      |     Widget     | 
        Tab Widget           |                |
                             +----------------+
                               Content Widget


The decorator is the parent of the widget it wraps and manages various aspects of that widget's display and behavior.

Supported Events: The base decorator passes all received events to its child widget with the possible exception of the following properties.
EVT_WDG_SETPROPERTY: The decorator widget responds to this event by attempting to set the property identified by the 'wParam' parameter. The decorator widget allows the following properties to be set.
PROPEX_PASS_WIDGETELEMINFO -- Sets whether the widget is handling PROPEX_WIDGETELEMINFO properties or passing them onto their child.

EVT_WDG_GETPROPERTY: The decorator widget respond to this event by attempting to retrieve the property identified by the 'wParam' parameter. The decorator widget allows the following properties to be retrieved.
PROPEX_PASS_WIDGETELEMINFO -- Retrieves whether the widget is handling PROPEX_WIDGETELEMINFO properties or passing them onto their child. Defaults to TRUE. PROPEX_WIDGETELEMINFO -- Will only handle this property if the widget's PROPEX_PASS_WIDGETELEMINFO property is FALSE.
Usage
See description of how the already defined decorator classes can be used.
- To create an instance of a decorator an application would call the following.
ISHELL_CreateInstance() with a class ID of the decorator. - To associate a child widget with the decorator applications should use
the api: IDECORATOR_SetWidget() - Insert the decorator in a container that up the hierarchy leads to the root container,
to make sure that the container is displayed on the screen.
  • Follow