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:

ApCreateModule() is used to manually create instances of modules built with PhAB. It's used differently when creating a picture module; see "Usage with picture modules," 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 attached to widgets inside the module are handled properly.

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

/* 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 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 their usage, see "Picture modules" in the Working with Modules chapter of the Programmer's Guide.

The widget argument is used differently by pictures. Since pictures don't 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, and "Picture modules" in the Working with Modules chapter of the Programmer's Guide.