Developer

API Reference

AEECLSID_ImageStaticWidget

Brew Release
Brew MP 1.0.2
See Also
Model Events Widget Events ISHELL_CreateInstance() IWidget_SetImageStaticInfo() IWidget
Description
The image static widget is used to display a single interface element that consists of both an image and a text label. For example, a real estate application could use the image static widget to display a photo of a home for sale with the price and address immediately to the right.
The static image widget is actually three objects in one:
- A static text widget containing the text that is used to label the image.
- An image widget containing the graphic image to be displayed.
- A prop container into which the above elements will be placed.

Applications specify the image to be displayed in the widget by calling IWidget_SetImageStaticInfo(), passing in a pointer to an ImageStaticInfo data structure, which contains the text and image to be displayed.
By default, the layout of the image has the image on the left and the label on the right, with the height of the label dictating the overall height of the parent container enclosing both objects. This orientation can be changed, however, with the label on the left and the image on the right, by setting the appropriate bit in the widget's property flags (ISWF_LAYOUT_IMAGERIGHT bit of PROP_FLAGS).
The label text will be vertically centered in the parent container, immediately to the right (or left, if the image/label orientation has been changed) of the image. By default, there is a two pixel padding between the image and the start of the label text -- a value that could be overridden by calling IWidget_SetLeftPadding() on the label portion of the image. An application could change this or any other property of the label or image widgets to customize color, alignment or justification.
The widget interface provides APIs to allow applications to access either the image or label parts of the image static widget, thereby allowing an application to have great control over how the widget is to act and be displayed. For example, the application could retrieve the label portion of the object, then alter the font, color or alignment of the text. Likewise, the image portion could be retrieved and manipulated -- for example, to add a transparency effect to the graphic.
To create a static image widget, an application would do the following:
       1. Call ISHELL_CreateInstance() with a class ID of AEECLSID_ImageStaticWidget to
          retrieve a reference counted instance of the static image widget.
       2. Call IWidget_SetImageStaticInfo() to identify the image and text to be displayed by
          the widget.

Supported Events: The image static widget processes events in three passes. In the first pass, events are passed on to the widget's container, providing the container the opportunity to intercept events that affect the layout of any child objects. If the event is not handled during the first pass, the image static widget will attempt to handle the any property events specific to the image static widget. Finally, events not handled during either of the first two passes will be passed to the base widget event handler.
The image static widget handles the following events in the described manner:
Event                 Description
-----                 ------------------------------------------------------------
EVT_WDG_SETPROPERTY:  The image static widget responds to this event by attempting to set the 
                      property identified by the 'wParam' parameter.  The image static widget 
                      allows the following properties to be set: 
                       
                          PROP_SELECTED                 --  Sets the selected state of the image 
                                                            static widget to either selected 
                                                            (TRUE) or unselected (FALSE). 
                          PROP_IMAGESTATIC_IMAGEWIDGET  --  Sets the image widget to be displayed 
                                                            by the image static widget. 
                          PROP_IMAGESTATIC_STATICWIDGET --  Sets the static text widget to be 
                                                            displayed by the image static widget. 
                          PROP_FLAGS                    --  Set various image static widget flags. 
                       
                      These properties are discussed below in greater detail. 

EVT_WDG_GETPROPERTY:  The image static widget responds to this event by attempting to retrieve the 
                      property identified by the 'wParam' parameter.  These properties are 
                      discussed below in greater detail. 
                       
                          PROP_IMAGESTATIC_IMAGEWIDGET  --  Retrieves a pointer to the image widget 
                                                            to be displayed by the image static widget.
                          PROP_IMAGESTATIC_STATICWIDGET --  Retrieves a pointer to the static text 
                                                            widget to be displayed by the image static
                                                            widget. 
                       
                      These properties are discussed below in greater detail.


Properties:
Property                        Description
--------                        ------------------------------------------------------------
PROP_SELECTED:                  This property contains the selection state of the image static widget. 
                                Set this property to TRUE to indicate that the image static widget is 
                                in its selected state, FALSE to indicate that the widget is unselected. 
                              
                                    Property Value:  boolean 
 
PROP_IMAGESTATIC_IMAGEWIDGET:   This property contains a pointer to the widget that will be displayed 
                                the graphic image contained within the image static widget.   
 
                                    Property Value:  IWidget * 
 
PROP_IMAGESTATIC_STATICWIDGET:  This property contains a pointer to the widget that will be displayed 
                                the static text contained within the image static widget.  
 
                                    Property Value:  IWidget * 
 
PROP_FLAGS:                     This property contains a set of flag masks that dictate 
                                the layout and display characteristics for the image static widget. 
                                These flags are passed in the 'dwParam' of the event and include 
                               
                                  ISWF_LAYOUT_IMAGERIGHT 
                                  ---------------------- 
                                  When this flag is set the widget will be laid out with its image 
                                  displayed to the right of the text string (normally, the image is 
                                  placed on the widget's left side, with the text laid out to the 
                                  right). 
                               
                                  ISWF_NOIMAGE 
                                  ---------------------- 
                                  When this flag is set the image portion of the widget will not be 
                                  displayed.  The image widget managed by the image static widget is 
                                  still present, but it is, essentially, hidden from view.  When this 
                                  flag is cleared, the image will again be displayed.  
                               
                                  ISWF_NOTEXT 
                                  ---------------------- 
                                  When this flag is set the static text portion of the widget will not 
                                  be displayed.  The static text widget managed by the image static 
                                  widget is still present, but it is, essentially, hidden from view. 
                                  When this flag is cleared, the static text will again be displayed. 
                               
                                    Property Value:  uint32 

Required Model: IValueModel
Model Data:
   
   ImageStaticInfo *modelData;

The image static widget relies on an value model that represents its data as a pointer to an ImageStaticInfo data structure. The model stores only a pointer to the data structure, not a copy of the data itself, and should always return this pointer in response to data queries from a client widget.
A default model is created and assigned to the widget when the widget is created with ISHELL_CreateInstance(). The client can replace the widget's model at any time with the method: IWidget_SetModel(), as long as the supplied model interface is of the type that the widget expects.
The data supplied in the value model must be a pointer to type ImageStaticInfo.
Instantiaion

The Image Static Widget is instantiated by passing AEECLSID_ImageStaticWidget into ISHELL_CreateInstance.
Cleanup

The Image Static Widget is reference counted. When you are done with your reference to the image static widget, you should Release that reference. Any widget specific cleanup will be handled for you when all references are released.
Default Interface Name
Comment
None
  • Follow