ApCreateModule()

Create an instance of modules built with PhAB

Synopsis:

#include <Ap.h>

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

Description:

Usage with window, dialog, menu, and other modules

ApCreateModule() is used to manually create instances of modules built with PhAB. 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 will generate 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 will appear at the specified location, and the setup function will be called. All link callbacks attached to widgets inside the module will be handled properly.

This function can be very handy in situations where a regular link callback cannot be used. 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.

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 modules need to be displayed without direct user interaction.

The widget argument is only used if you are creating a module with a location relative to another widget. Otherwise the value can be set to NULL. It's passed to the module's setup function as apinfo->widget.

The cbinfo argument is only used if you are creating a module relative to the pointer position. Otherwise the value can be set to NULL.

The following code illustrates the use of ApCreateModule() when creating a dialog.

/* the following 2 lines are generated by PhAB */
#define ABM_mydialog1   &internal_links[ABI_mydialog1]
#define ABM_mydialog2   &internal_links[ABI_mydialog2]

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

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

Usage with picture modules

ApCreateModule() is the only way to create picture modules because pictures do not have a direct link callback. You cannot attach a link callback from a widget to a picture module. Instead, you design your picture module as you would a window or dialog module, and then add the picture to the internal callbacks list. PhAB will generate the necessary manifests for you to access the picture from within your application code. For a more detailed description of picture modules and their usage, see the "Picture modules" section in the Programmer's Guide.

The widget argument is used differently by pictures. Since pictures do not have an associated location, widget is used to specify the picture module's container widget.

The following example illustrates the use of ApCreateModule() when creating a picture:

/* the following line is generated by PhAB */
#define ABM_mypicture   &internal_links[ABI_mypicture]

mycallback( PtWidget_t *widget, ..., 
            PtCallbackInfo_t *cbinfo )
{
    /* clear out container widget */
    PtClearWidget( ABW_mycontainer );

    /* create the picture inside 'mycontainer' */
    ApCreateModule( ABM_mypicture, ABW_mycontainer, 
                    cbinfo );

    /* force the container to be updated */
    PtReRealizeWidget( ABW_mycontainer );
}

Returns:

• If there are no setup functions associated with the internal link:

  Pt_CONTINUE

  Success.

  -1

  An error occurred.

• If there are any setup functions associated with the internal link, ApCreateModule() returns the value returned by the last one called:

  Pt_CONTINUE

  Normal return value.

  Pt_END

  (Prerealize function for window and dialog modules only) The creation of the module was aborted and the widgets were destroyed.

  Pt_HALT

  (Prerealize functions for window modules only) The module wasn't realized. The widgets weren't destroyed and the module can be realized later.

Classification:

Photon

See also:

ApModuleLocation(), ApModuleFunction(), ApModuleParent()

"Module setup functions" in the Working with Code chapter of the Photon Programmer's Guide