Developer

API Reference

AEECLSID_ImageWidget

Brew Release
Brew MP 1.0.2
See Also
- Model Events
- ISHELL_CreateInstance()
- IWidget_SetImage()
- IWidget_SetFlags()
Description
The image widget is used to create an object in the widget framework that contains an IImage bitmap or animated bitmap graphic image. For example, the image of a map showing the directions to a fancy downtown club could be displayed using an image widget. An application could also choose to use an image widget to provide a background graphic for a form or dialog.
The graphic image displayed by an image widget is provided by the model attached to the widget when it is created. Therefore, as the data in the model changes, the image represented by the image widget will be updated on the display.
An application may specify the image to be displayed by the image widget by calling IWidget_SetImage(), passing in a pointer to the IImage image to be displayed. The image itself will be displayed within the rectangle that defines the widget's border, positioned by default with its origin aligned to the upper left corner of the border, clipped to the widget's extent. The position of the image can be altered by changing the setting the PROP_FLAGS property, specifying horizontal and vertical alignments, as follows:
       Alignment Mask     Results
       --------------     -------
       IDF_ALIGN_LEFT     The image is displayed relative to the left coordinate of the
                          widget's border rectangle.  If the width of the image extends
                          beyond the border's right coordinate, it will be cropped on
                          the right side.
       IDF_ALIGN_RIGHT    The image is displayed relative to the right coordinate of the
                          widget's border rectangle.  If the width of the image extends
                          beyond the border's left coordinate, it will be cropped on the
                          left side.
       IDF_ALIGN_CENTER   The image is displayed horizontally centered in the widget's
                          border rectangle.  If the width of the image is wider than the
                          border rectangle, it will be cropped on both the left and right
                          sides.
       IDF_ALIGN_TOP      The image is displayed relative to the top coordinate of the
                          widget's border rectangle.  If the height of the image extends
                          below the border's bottom coordinate, it will be cropped on
                          the bottom side.
       IDF_ALIGN_BOTTOM   The image is displayed relative to the bottom coordinate of the
                          widget's border rectangle.  If the height of the image extends
                          above the border's top coordinate, it will be cropped on the
                          top side.
       IDF_ALIGN_MIDDLE   The image is displayed vertically centered in the widget's
                          border rectangle.  If the height of the image is larger than the
                          height of the border rectangle, the image will be cropped on both
                          the top and bottom sides.

The image is always displayed at its full size, cropped to the clip rectangle of the destination port. The size, position, animation rate and many other attributes of the image may be further customized by calling IWidget_SetImageParm(), passing in an ImageParm date structure that identifies the attribute to be set, along with the attribute's associate value. See AEEImage.h for a discussion of each of the image parameters that can be set.
The image widget assumes the IImage to be displayed has been fully loaded and decoded. Some image formats such as png, jpg and gif require the image data to be decompressed before being displayed. When loading these images via BREW's ISHELL_LoadResImage() or related routines, it is the application's responsibility to use IIMAGE_Notify() to wait for the image decoding to complete before passing the IImage to the image widget for display. If the application fails to do this, screen updates immediately following an image change may not happen as expected.
Image tiling is also supported by providing the ability to copy (tile) a source image multiple times across a larger region. Tiling can be simple multiple copies of the source, or it can be a bordered tile pattern.
The following diagram shows a source image that consists of a 3x3 grid of colored squares.
   
   +---+---+---+
   | 1 | 2 | 3 |
   +---+---+---+
   | 4 | 5 | 6 |
   +---+---+---+
   | 7 | 8 | 9 |
   +---+---+---+


If the tile source image were to simply fill an Image Widget, the result would be the following:

   +---+---+---+---+---+---+
   | 1 | 2 | 3 | 1 | 2 | 3 |
   +---+---+---+---+---+---+
   | 4 | 5 | 6 | 4 | 5 | 6 |
   +---+---+---+---+---+---+
   | 7 | 8 | 9 | 7 | 8 | 9 |
   +---+---+---+---+---+---+
   | 1 | 2 | 3 | 1 | 2 | 3 |
   +---+---+---+---+---+---+
   | 4 | 5 | 6 | 4 | 5 | 6 |
   +---+---+---+---+---+---+
   | 7 | 8 | 9 | 7 | 8 | 9 |
   +---+---+---+---+---+---+
   

In addition to simple tiling, the tile element can preserve the border of a source image. Such tiles are specified with the border width attributes bdt, bdr, bdb and bdl. In the example of simple tiling above, the values of bdt, bdb, bdr, and bdl would all be zero. By default, the values of bdt, bdb, bdr, and bdl are zero, which essentially means simple tiling is the default behavior of Image Widget when tiling is enabled and these values have not been explicitly set. If the border attributes are used on this example such that the top, left, right and bottom border widths all fit the internal squares, then the region is tiled as follows.

   +---+---+---+---+---+---+
   | 1 | 2 | 2 | 2 | 2*| 3 |
   +---+---+---+---+---+---+
   | 4 | 5 | 5 | 5 | 5*| 6 |
   +---+---+---+---+---+---+
   | 4 | 5 | 5 | 5 | 5*| 6 |
   +---+---+---+---+---+---+
   | 4 | 5 | 5 | 5 | 5*| 6 |
   +---+---+---+---+---+---+
   | 4*| 5*| 5*| 5*| 5*| 6*|
   +---+---+---+---+---+---+
   | 7 | 8 | 8 | 8 | 8*| 9 |
   +---+---+---+---+---+---+
   

The cells marked with a asterisk (*) might be clipped in order to fill the area. The usage of the border attributes is defined by the following diagram.
          bdl     bdr
         |---|   |---|

       - +---+---+---+
   bdt | | 1 | 2 | 3 |
       - +---+---+---+
         | 4 | 5 | 6 |
       - +---+---+---+
   bdb | | 7 | 8 | 9 |
       - +---+---+---+
In order to set the value of bdt, bdb, bdl, or bdr, use IWidget_SetProperty() with one of the following prop flags and the pixel distance(uint16).
   PROP_TILED_BDT
   PROP_TILED_BDB
   PROP_TILED_BDL
   PROP_TILED_BDR


Image tiling also supports a selected image. Use the selected image just as you would in an non-tiled Image Widget.
The widget interface provides APIs that allow applications to directly set many of the attributes associated with an image, as well as interfaces to start or stop animating the image.
The image widget is created with the following default characteristics:
           Border width:  0
       Background color:  RGB_NONE
                Padding:  0
           Transparency:  0 (fully opaque)

To create an image widget, an application would do the following:
       1. Call ISHELL_CreateInstance() with a class ID of AEECLSID_ImageWidget to
          retrieve a reference counted instance of the image widget.
       2. Call IWidget_SetImage()  to identify the image to be displayed by the widget.
       3. Call IWidget_SetFlags() if the application wishes to override the default
          alignment of the image within its border.

Supported Events: The image widget processes events in three passes. In the first pass the image widget will attempt to process any property events related to the widget's border. If the event is handled during this first pass, the image widget will invalidate itself and be redrawn, using any updated border property values. The second pass attempts to handle events that may be directly intended for the image widget, including those events that set image specific properties and the selection state of the widget. Finally, events not handled during either of the first two passes will be passed to the parent decorator.
The image widget handles the following events in the described manner:
Event                 Description
-----                 ------------------------------------------------------------
EVT_WDG_SETPROPERTY:  The image widget responds to this event by attempting to set the
                      property identified by the 'wParam' parameter.  The image widget
                      allows the following properties to be set.
                      
                          PROP_SELECTED       --  If the widget supports selection (as
                                                  indicated by the IWF_HASSELECTIMAGE
                                                  flag) this property will toggle the
                                                  current selection state on screen.
                          PROP_IMAGE_PARM     --  Retrieve the current image's AEERasterOp.
                          PROP_IMAGE_ANIMATE  --  Sets the current animation state of the
                                                  image being displayed.
                          PROP_ANIMATE        --  Same as PROP_IMAGE_ANIMATE
                          PROP_IMAGE_FRAME    --  Sets which frame of the image contained
                                                  within the Image Widget is drawn.
                          PROP_FLAGS          --  Set various image widget flags.
                          PROP_ANIMATE_FLAGS  --  Set various animation-specific flags.
                          PROP_TRANSP_COLOR   --  Sets the transparency color to be used
                                                  when transferring the bitmap image to
                                                  the screen.(Applicable only for bitmaps).

                      These properties are discussed below in greater detail.

EVT_WDG_GETPROPERTY:  The image 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_FLAGS          --  Retrieves various image widget flags.
                          PROP_IMAGE_ANIMATE  --  Retrieves the animation state of the image
                                                  being displayed
                          PROP_ANIMATE        --  Same as PROP_IMAGE_ANIMATE
                          PROP_IMAGE_FRAME    --  Retrieves which frame of the image 
                                                  contained in the Image Widget is drawn.
                          PROP_IMAGE_NFRAMES  --  Restrieves the number of frames in
                                                  the image contained in the Image Widget.
                          PROP_ANIMATE_FLAGS  --  Retrieves the animation flags.
                          PROP_TRANSP_COLOR   --  Retrieves the transparency color used
                                                  when transferring the bitmap image to
                                                  the screen.(Applicable only for bitmaps).
Properties:
Property             Description
--------             ------------------------------------------------------------
PROP_SELECTED:       Though this property contains the selection state of the image widget, the
                     actual toggling of the property value is handled by the widget border, with
                     the widget border's event handler returning FALSE to allow child objects to
                     also handle the event.  The image widget will respond to requests to set this
                     property by togging the image display from its selected to unselected states
                     (or vice versa), but only if the image widget supports selection (as indicated
                     by the IWF_HASSELECTIMAGE flag).
                             
                         Property Value:  boolean (handled by border widget)

PROP_IMAGE_PARM:     This property contains a pointer to an ImageParm data structure, which
                     provides access to a single attribute of the image wrapped within the image
                     widget.  Setting this property effectively queries the image to interact with
                     one of the image attributes -- which could result in either setting that
                     attribute, or, actually retrieving the value of the attribute that parameter
                     represents.  For example, when the 'parm' field is set to IPARM_OFFSET, the
                     image wrapped by the image widget, would set its offset to the horizontal and
                     vertical coordinates identified by the 'arg1' and 'arg2' fields.  See
                     AEEImage.h for a discussion of each of the image parameters that can be
                     accessed when setting the  PROP_IMAGE_PARM property.  Note that some viewers 
                     may not support all IPARM parameters.  The image widget only responds to 
                     requests to set this property.
                             
                         Property Value:  ImageParm *

PROP_IMAGE_ANIMATE:  This property contains a boolean flag indicating whether or not animation of
                     the image widget should be started or stopped.  Image Widget responds to both
                     set and get of this property.
                             
                         Property Value:  boolean

PROP_TILED_BDT:      This property defines the border distance top (bdt) for a tiled Image Widget.
                     See the class description for usage of this property in context.

                         Property Value:  uint16

PROP_TILED_BDB:      This property defines the border distance bottom (bdb) for a tiled Image Widget.
                     See the class description for usage of this property in context.

                         Property Value:  uint16

PROP_TILED_BDL:      This property defines the border distance left (bdl) for a tiled Image Widget.
                     See the class description for usage of this property in context.

                         Property Value:  uint16

PROP_TILED_BDR:      This property defines the border distance right (bdr) for a tiled Image Widget.
                     See the class description for usage of this property in context.

                         Property Value:  uint16

PROP_IMAGE_FRAME:    This property specifies which frame of the contained IImage the Image Widget
                     will draw..

                         Property Value:  int


PROP_FLAGS:          This property contains a set of flag masks that dictate how an
                     image widget will behave.  These flags are passed in the 'dwParam' of the
                     event.  The following flags are identified for the image widget.
                              
                       IWF_HASSELECTIMAGE
                       ------------------
                       When this flag is set the image displayed by the image widget actually
                       consists of a pair of images of precisely the same size.  The first
                       image will be displayed by the image widget when the widget is in its
                       unselected state -- the second image is displayed when the image is
                       selected.  By default, this flag is OFF, indicating that the image
                       contains only a single item to be displayed, regardless of the current
                       selection state.
                              
                         Property Value:  uint32

                       IWF_TILED
                       ---------
                       This flag indicates that the image displayed by image widget should
                       be tiled inside the widget's extent.  The image will fill the full
                       extent of the widget.  If the image does not proportionately
                       fit inside the extent, the image will be clipped to fit.  For more
                       information about the layout of basic tiled mode, see the Image
                       Widget class description. 

                         Property Value:  uint32

PROP_ANIMATE_FLAGS:  This property holds the flags related to image widget's animation.

                        AF_ENABLE_EVT_STEP
                        ------------------
                        This flag enables the EVT_MDL_STEP event to be from the image 
                        widget's view model during animation. When image widget animates, 
                        EVT_MDL_STEP will only be passed to model listeners if this flag is 
                        set to true.
                       
                        AF_ANIMATE_ONCE
                        ---------------
                        This flag causes image animation to stop on the last frame 
                        after one animation sequence has completed. The default behavior is 
                        for the animation sequence to continue until explicitly stopped with
                        PROP_IMAGE_ANIMATE(FALSE). 

                        Property Value:  uint32

PROP_TRANSP_COLOR:   This property determines how the bitmap will be transferred to the
                     display.  Set PROP_TRANSP_COLOR to RGB_NONE to copy the bitmap without
                     any transparency (i.e. every pixel in the source bitmapped will be
                     copied to the display), otherwise the bitmapped will be transferred
                     with transparency. Note that this property is applicable only for
                     bitmaps.


Required Model: IInterfaceModel (default)
Model Data:
   
   IImage *modelData;

The image widget relies on an interface model that represents its data as a pointer to an IImage data structure. The model stores only a pointer to the image not a copy of the image itself, and should always return this pointer in response to data queries from a client widget.
The IImage pointer passed as the model data must point to an image that has been fully loaded and decoded. It is the application's responsibility to wait for image formats such as png, jpg and gif to complete decoding before passing them to the image widget. See the BREW documentation on IImage and IIMAGE_Notify() for details.
The image widget may be created with a specific interface model identified, rather than the default interface model assigned by the widget framework. Clients that identify their own model interface to be attached to the image widget must abide by the data conventions described above, returning a pointer to an IImage when queried for the model data.
Instantiaion
The Image Widget is instantiated by passing AEECLSID_ImageWidget into ISHELL_CreateInstance.
Cleanup
The Image Widget is reference counted. When you are done with your reference to the image widget, you should Release that reference. Any widget specific cleanup will be handled for you when all references are released.
Default Interface Name
AEEIID_IDecorator
Other Interfaces
-AEEIID_IContainer,-AEECLSID_QueryInterface,-AEEIID_IHandler,-AEEIID_IWidget,-AEEIID_IDrawHandler,
Comment
None
  • Follow