ApCreateWidgetFamily()

Create a widget family by copying it from a PhAB widget database

Synopsis:

#Include <Ap.h>

PtWidget_t *ApCreateWidgetFamily( 
               ApDBase_t const *db,
               char const *wgt_name,
               int x,
               int y,
               int nargs,
               PtArg_t const *args );

Description:

This function is used to create widgets by copying a widget family 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.

The root of the widget family is created as a child of the default parent, which is usually the most recently created container. To change the default parent, call PtSetParentWidget().

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 ApCreateWidgetFamily() 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

x and y

convenience arguments for specifying the position of the widget when it's created

---

If y is -1, the widget's original position is used.

---

nargs and args

the standard resource argument counter and argument list used by PtCreateWidget()

ApCreateWidgetFamily() creates the named widget and, for container class widgets, any children of the widget.

The pointers of the widget's children aren't directly available using this function. If you need access to the container's children, you'll need to call ApCreateWidget() for the container and each widget inside it. If you create them in the same hierarchical order as defined in the database, the parent-child relationship will be maintained.

Returns:

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

Classification:

Photon

See also:

ApCloseDBase(), ApCreateWidget(), ApOpenDBase(), ApOpenDBaseFile(), ApSaveDBaseFile(), PtCreateWidget(), PtSetParentWidget()

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