ApGetBitmapRes()

Extract bitmap data from a widget in a widget database

Synopsis:

#include <Ap.h>

ApBitmap_t *ApGetBitmapRes( 
               ApDBase_t const *dbase, 
               char const *wgt_name );

Description:

This function lets you extract bitmap images from a PtBitmap widget in a PhAB widget database.

The dbase argument points to a widget database opened with either ApOpenDBase() or ApOpenDBaseFile(). The wgt_name argument is the instance name of one of the widgets inside the database.

This function doesn't give you the height and width of the extracted image. You must use the extracted bitmap data in another PtBitmap widget that has the exact same dimensions.

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

Depending on the size of the bitmaps being used and the background colors, the animation will be relatively free of flicker. To get the best look and performance out of your animations, we recommend that you use PtLabel widgets and images rather than PtBitmap widgets, especially if the bitmaps are fairly large (that is, greater than 64 pixels); see ApGetImageRes().

You can't change the number of planes in a PtBitmap widget unless the Pt_FREE_MEMORY flag is set in the widget's Pt_ARG_FLAGS resource. If you set this flag in conjunction with ApGetBitmapRes(), you must make a copy of the data before setting the resources, so that bitmap data isn't freed from the widget database.

Returns:

A pointer to the bitmap data structure (see ApBitmap_t), or NULL if the widget or data couldn't be found.

Don't free the pointer returned by the function. It points directly to the data within the widget database. When the database is closed, the pointer is freed automatically.

Examples:

This example replaces the image stored in a bitmap widget. For this example to work, the old and new bitmaps must have the same dimensions, number of colors/planes, and order of colors.

ApBitmap_t  *bitmap;
PtArg_t     args[1];

mydbase = ApOpenDBase( ABM_mypicture );

bitmap = ApGetBitmapRes( mydbase, "mybitmap" );

if ( bitmap ) {
    PtSetArg( &args[0], Pt_ARG_BITMAP_DATA, 
              bitmap->data, 0 );
    PtSetResources( ABW_bitmap_wgt, 1, args );
    }

   ApCloseDBase( mydbase );

Classification:

Photon

Safety:
Interrupt handler	No
Signal handler	No
Thread	No