ApCreateModule()

Create an instance of a module that was built with PhAB

Synopsis:

#include <Ap.h>

PtWidget_t * ApCreateModule(
                ApEventLink_t const *link_callback,
                PtWidget_t *widget,
                PtCallbackInfo_t *cbinfo );

Arguments:

link_callback
The manifest that PhAB created for the module.
widget
A pointer to a widget. The way that the function uses this argument depends on whether or not the module is a picture; for more information, see Usage with window, dialog, menu, and other modules and Usage with picture modules,” below.
cbinfo
NULL, or a pointer to the PtCallbackInfo_t structure (see the Photon Widget Reference) that was passed to the callback. It's used only if you're creating a module that's positioned relative to the pointer.

Library:

Ap

Description:

You can use ApCreateModule() to manually create instances of modules built with PhAB. Its behavior depends on the type of module that you're creating, as described below.

Usage with window, dialog, menu, and other modules

Before you can create an instance of a module, you must create an internal link to the module using the Internal Links dialog accessible from PhAB's Application menu. For every internal link in the list, PhAB generates a manifest that you can use with ApCreateModule() to create the module.

This function and PhAB's link callbacks behave in very similar ways. If you define a location and a setup function for the internal link, the module appears at the specified location, and the setup function is called. All link callbacks that are attached to widgets inside the module are handled properly.

This function can be very handy in situations where you can't use a regular link callback. For example, a menu item may need to display one dialog or another, depending on certain conditions in your application code. In this case, you can attach a code link callback to the menu item and in the code function you can create the appropriate module.


Note: A module created with ApCreateModule() becomes a standard Photon widget (e.g. PtWindow, PtMenu) that you can destroy later using PtDestroyWidget() if you want to close the module.

ApCreateModule() is also useful when you need to display modules without direct user interaction.

This function uses the widget argument only if you're creating a module with a location relative to another widget. Otherwise, you can set it to NULL. It's passed to the module's setup function as apinfo->widget.

The cbinfo argument is a pointer to the PtCallbackInfo_t structure (see the Photon Widget Reference) that was passed to the callback. It's used only if you're creating a module relative to the pointer position. Otherwise, you can set it to NULL.

This code creates one of two dialogs:

int mycallback( PtWidget_t *widget,
                ApInfo_t *apinfo,
                PtCallbackInfo_t *cbinfo )
{
    /* check conditions */
    if ( condition1 ) {
        ApCreateModule( ABM_mydialog1, widget, cbinfo );
    } else {
        ApCreateModule( ABM_mydialog2, widget, cbinfo );
    }

    return (Pt_CONTINUE);
}

To specify the parent for a window or dialog module, use ApModuleParent().

Usage with picture modules

ApCreateModule() is the only way to create picture modules because pictures don't have a direct link callback. You can't attach a link callback from a widget to a picture module. Instead, design your picture module as you would a window or dialog module, and then add the picture to the internal callbacks list. PhAB generates the necessary manifests for you to access the picture from within your application code.

For a more detailed description of picture modules and how to use them, see Picture modules in the Working with Modules chapter of the Programmer's Guide.

ApCreateModule() uses the widget argument in a different way when you're creating pictures instead of other modules. Since pictures don't have an associated location, you use the widget argument to specify the picture module's container widget:

Returns:

A pointer to the instance of the created module, or NULL if an error occurred or a setup function aborted the creation. There are some special cases:

Classification:

Photon

Safety:
Interrupt handler No
Signal handler No
Thread No

See also:

ApModuleLocation(), ApModuleFunction(), ApModuleParent(), PtDestroyWidget(), PtSetParentWidget()

PtCallbackInfo_t in the Photon Widget Reference

Module setup functions in the Working with Code chapter, Picture modules in the Working with Modules chapter, and the Accessing PhAB Modules from Code chapter of the Photon Programmer's Guide.