ApCreateDBWidget()

Create a widget by copying it from a PhAB widget database, specifying a parent

Synopsis:

#Include <Ap.h>

PtWidget_t *ApCreateDBWidget( 
               ApDBase_t const *db,
               char const *wgt_name,
               PtWidget_t *parent,
               PhPoint_t const *pos,
               int nargs,
               PtArg_t const *args );

Library:

Ap

Description:

This function is used to create widgets by copying a widget from a PhAB widget database. This is very useful when you need to create many instances of the same widget. For example, a file manager may want to draw a file folder for each directory it displays.

Before loading widgets from an external database, you should call ApAddClass() for each widget class that you'll likely encounter in it. This will add the widget classes to the internal widget class table.

The arguments to ApCreateDBWidget() are as follows:

db

Points to a widget database opened with either ApOpenDBase() or ApOpenDBaseFile().

wgt_name

The instance name of one of the widgets inside the database.

parent

The parent for the widget. If parent is NULL, the widget has no parent. (Contrast this with ApCreateWidget(), which makes the widget a child of the current default parent.)

pos

A pointer to a PhPoint_t structure that specifies the position of the widget when it's created. If pos is NULL, the widget's original position is used.

nargs and args

The standard resource argument counter and argument list (of type PtArg_t) used by PtCreateWidget().

ApCreateDBWidget() creates only the widget named by wgt_name regardless of its class. ApCreateDBWidgetFamily() creates the named widget and, for container class widgets, any children of the widget.

Returns:

A pointer to the widget created for wgt_name, or NULL on failure.

Examples:

ApDBase_t         *mydbase;
PtArg_t           args[2];
PhPoint_t         pos;
PtWidget_t        *my_label;

mydbase = ApOpenDBase( ABM_mypicture );

PtSetArg( &args[0], Pt_ARG_TEXT_STRING, 
          "This Widget", 0 );
pos.x = 10;
pos.y = 10;
ApCreateDBWidget( mydbase, "my_label_widget", 
  my_window, &pos, 1, args );

PtSetArg( &args[0], Pt_ARG_TEXT_STRING, 
          "That Widget", 0 );
PtSetArg( &args[1], Pt_ARG_FILL_COLOR, Pg_WHITE, 0 );
pos.y = 30;
my_label = ApCreateDBWidget( mydbase, "my_label_widget",
                             my_window, &pos, 1, args );
if (my_label != NULL)
{
  PtRealizeWidget( my_label );
}

ApCloseDBase( mydbase );

Classification:

Photon

See also:

ApCloseDBase(), ApCreateDBWidgetFamily(), ApCreateWidget(), ApCreateWidgetFamily(), ApGetDBWidgetInfo(), ApOpenDBase(), ApOpenDBaseFile(), ApSaveDBaseFile(), PhPoint_t, PtArg_t, PtCreateWidget()

Accessing PhAB Modules from Code chapter of the Photon Programmer's Guide