Resources | Resources |



Using image widget

The image widget is instantiated by passing AEECLSID_CImageWidget into ISHELL_CreateInstance.

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 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 associated 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 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.

To create an image widget, an application would do the following:

  1. Call ISHELL_CreateInstance() with a ClassID of AEECLSID_CImageWidget to retrieve a reference counted instance of the image widget.
    ISHELL_CreateInstance(pMe->a.m_pIShell, AEECLSID_CImageWidget, 
                (void**) &pMe->piwWid);
  2. Call IWidget_SetImage() to identify the image to be displayed by the widget, passing in a pointer to the IImage image to be displayed.
    (void) IWidget_SetImage(pMe->piwWid, pMe->piImageWidClose);
  3. Call IWidget_SetFlags() if the application wishes to override the default alignment of the image within its border.

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 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.