ApGetImageRes()

Extract the image data from a widget

Synopsis:

#include <Ap.h>

PhImage_t *ApGetImageRes( 
              ApDBase_t const *dbase, 
              char const *wgt_name );

Description:

ApGetImageRes() lets you extract images from a widget in a PhAB widget database.

The dbase argument is the widget database pointer returned from ApOpenDBase(). wgt_name is the name of widget within the database which has the image you're trying to extract.

This function is mainly used to perform simple animation. You can create a series of tiles, using any widget that supports images, in a PhAB widget database; to create the animation, cycle through the tiles by pulling out the images in sequence, updating another widget that is visible within the application window.

Since images can't be transparent, they're opaque when drawn. This results in no flicker, regardless of size.

Returns:

A pointer to a PhImage_t structure, or NULL if the widget or image data couldn't be found.

Only the image structure is copied when updating the label widget. The image's data and palette aren't copied; they still point back into the widget database's data space. This means you can close the database only after the updated widget is destroyed. Otherwise, the widget ends up pointing to data that's been freed.

If you must close the widget database, do the following before you update the widget:

Copy the image data and palette.
Update the PhImage_t structure to point to the new copies of the data.

Examples:

PhImage_t   *image;
PtArg_t     args[1];

mydbase = ApOpenDBase( ABM_mypicture );

image = ApGetImageRes( mydbase, "myimage" );

/* update the label widget with the new image */

if ( image ) {
    PtSetArg( &args[0], Pt_ARG_LABEL_DATA, 
              image, sizeof( *image ) );
    PtSetResources( ABW_label_wgt, 1, args );
    }

Classification:

Photon

Safety:
Interrupt handler	No
Signal handler	No
Thread	No