Developer

API Reference

IWidget_SetImageParm()

Brew Release
Brew MP 1.0.2
See Also
IWidget IWidget_SetProperty() IBitmap AEERasterOp PFNNOTIFY
Description
This function provides an interface to setting or retrieving many of the individual attributes of a widget's underlying image. For example, IWidget_SetImageParm() could be used to establish the position of an image within its enclosing border, or used to retrieved the AEERasterOp identifying how the pixel data of the image will behave. Image attributes are managed through a parameter block interface, with the parameter block identifying the attribute to be accessed, as well as the values associated with that attribute. Again, to illustrate, the attribute of image size is identified by the constant IPARM_SIZE, as well as a pair of values that specify the horizontal width and vertical height of the image. These items are collected in the ImageParm data structure, with this structure then passed to IWidget_SetImageParm() to set (or get) a given attribute.
Parameters
  • pif
    []:
    [in] Pointer to the image widget object.
  • p
    []:
    [in] Pointer to an ImageParm data structure identifying the image attribute to be set (or retrieved when the 'parm' field is IPARM_GETROP). For those 'parm' values that set image attributes, this data structure will also contain, as arguments, the value for the associate attribute. These argument fields serve as pointers to returned values when the 'parm' value indicates a request to retrieve attribute values from the image.
Interface
Prototype
   int IWidget_SetImageParm(IWidget *pif, ImageParm *p)
Return
   AEE_SUCCESS - If BREW was able to successfully set or retrieve the requested image attribute.
   AEE_EFAILED - If the requested image attribute could not be set or retrieved.
Side Effect
None.
Comment
The behavior of IWidget_SetImageParm() depends on the image attribute identified in the 'parm' field of the parameter block passed to the function in the 'p' parameter, as presented in the following table. Image Widget only supports a subset of all IImage IPARM parameters. Note that some viewers might not support all IPARM parameters listed below.
      'parm' field       Behavior of IWidget_SetImageParm()
      ------------       -----------------------------
      IPARM_SIZE         This parameter will set the width and height of the image bitmap
                         to the values defined in the 'arg1' and 'arg2' fields.
                         
                             arg1  -  Contains the width of the image
                             arg2  -  Contains the height of the image
                         
                         Note, however, that changing the bitmap dimensions does not scale
                         the image to fit the requested size.  Rather, the size passed in
                         'arg1' and 'arg2' define a section of the overall bitmap to be used
                         in image operations, effectively providing a mechanism for cropping
                         a bitmap's contents.  For example, a single bitmap image of 64 x 64
                         pixels could actually be the concatenation of four separate 32 x 32
                         pixel images, each occupying a quadrant of the overall image.  An
                         application could identify a portion of the larger image by setting
                         the IPARM_SIZE of the image to 32 x 32 to indicate that only a portion
                         of the larger bitmap is to be used for image operations.  Normally,
                         the image size is set to the full dimensions of the bitmap.
                             
      IPARM_OFFSET       This parameter will set the horizontal and vertical offset of the
                         image's origin within the stored bitmap, to the values defined in
                         the 'arg1' and 'arg2' fields.
                         
                             arg1  -  Contains the horizontal coordinate for the origin
                             arg2  -  Contains the vertical coordinate for the origin
                         
                         Carrying forward the example presented above, consider a 64 x 64
                         pixel bitmap containing four separate 32 x 32 images.  Any of the
                         four smaller sub-images could be accessed by setting the IPARM_SIZE
                         attribute to 32 x 32, and the IPARM_OFFSET parameter to different
                         points of origin
                           -  The upper left image would leave the IPARM_OFFSET at (0, 0)
                           -  The upper right image would set the IPARM_OFFSET to (32, 0)
                           -  The lower left image would set the IPARM_OFFSET to (0, 32)
                           -  The lower right image would set the IPARM_OFFSET to (32, 32)
                             
      IPARM_CXFRAME      This parameter will set the width, in pixels, of each frame in an
                         animated bitmap.  For example, an animated bitmap that stores all
                         of its frames in a single 512 x 80 pixel bitmap might indicate a
                         frame width of 64 pixels -- meaning that each frame of the animation
                         is 64 pixels wide, by the bitmap height of 80 pixels.  All told,
                         this would specify 8 frames of animation (512 pixels divided by 64
                         pixels).  The frame size would be specified in the 'arg1' field,
                         with the 'arg2' field being ignored.
                         
                             arg1  -  Contains the width of each animation frame
                             arg2  -  Ignored
                             
      IPARM_ROP          This parameter specifies the raster operation that will be applied
                         when transferring the bitmap to the display.
                         
                             arg1  -  Contains a constant identifying how each pixel of the
                                      image should be logically combined with those already
                                      appearing on the display.  See the description of
                                      IPARM_ROP in AEEImage.h for a full description of the
                                      available transfer modes and constants.
                             arg2  -  Ignored
                             
      IPARM_NFRAMES      This parameter will set the number of frames that together comprise
                         the frames of an animated bitmap.  For example, an animated bitmap
                         that stores all of its frames in a single 512 x 80 pixel bitmap might
                         indicate that the animation sequence consists of 8 frames -- meaning
                         that each frame of the animation will be 64 pixels wide (512 pixels
                         divided by 8 frames equals 64 pixels per frame).  The number of frames
                         would be specified in the 'arg1' field with the 'arg2' field being
                         ignored.
                         
                             arg1  -  Contains the number of animation frames contained in the
                                      bitmap.
                             arg2  -  Ignored
                             
                         Note that when the number of animation frames is specified explicitly,
                         the size of each frame (represented by IPARM_CXFRAME) is calculated.
                             
      IPARM_RATE         This parameter will set the rate of animation -- i.e. the time, in
                         milliseconds, to be observed between each frame of the animation.  The
                         rate is specified in the 'arg1' field and the 'arg2' field is ignored.
                         
                             arg1  -  Contains the number of milliseconds that should be
                                      observed between frames while displaying the frames of an
                                      animated bitmap.
                             arg2  -  Ignored
                             
      IPARM_OFFSCREEN    This parameter is not currently supported.
                         
                             arg1  -  Ignored
                             arg2  -  Ignored
                             
      IPARM_REDRAW       This parameter will set the private redraw callback for a given image.
                         BREW will issue this callback whenever an update is needed, thereby
                         providing the image widget the opportunity to perform any special
                         processing needed when an update occurs.
                         
                             arg1  -  Contains a pointer to the redraw callback defined as a
                                      PFNNOTIFY function.
                             arg2  -  Contains a pointer to the image widget itself.
                             
      IPARM_GETROP       This parameter is used to retrieve the raster operation constant that
                         will be applied to the pixels of the bitmap when it is transferred to
                         the display.  The arguments identified in the data structure are
                         actually used as destinations for the data returned by the call to
                         IWidget_SetImageParm().
                         
                             arg1  -  Contains a pointer to an AEERasterOp into which the
                                      current transfer mode will be copied.
                             arg2  -  Contains a pointer to an integer into which the
                                      results of fetching the raster op will be copied.
                                      If NULL is passed for 'arg2', no results are returned.

      IPARM_SCALE        This parameter will scale the width and height of the image bitmap
                         to the values defined in the 'arg1' and 'arg2' fields.
                         
                             arg1  -  Contains the scaled width of the image
                             arg2  -  Contains the scaled height of the image
                         
                         Note, image scaling is only supported on BREW versions 3.0 and newer.  


  • Follow