API Reference | developer.brewmp.com API Reference | developer.brewmp.com

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