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.

---

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:

• If widget is non-NULL, the children of the picture module become children of widget, and the picture module itself isn't created. For example:

  int mycallback( PtWidget_t *widget,
                  ApInfo_t *apinfo,
                  PtCallbackInfo_t *cbinfo )
  {
      /* Clear the container widget. */
      PtClearWidget( ABW_mycontainer );
  
      /* Create the picture's children inside mycontainer. */
      ApCreateModule( ABM_mypicture, ABW_mycontainer, 
                      cbinfo );
  
      /* Force the container to be updated. */
      PtReRealizeWidget( ABW_mycontainer );
  
      return (Pt_CONTINUE);
  }
    

• If widget is NULL, the picture module becomes a child of the current parent widget, and the picture module's children become grandchildren of the current parent widget. You can call PtSetParentWidget() to change the current parent. For example:

  int mycallback( PtWidget_t *widget,
                  ApInfo_t *apinfo,
                  PtCallbackInfo_t *cbinfo )
  {
      /* Clear the container widget. */
      PtClearWidget( ABW_mycontainer );
  
      /* Create the picture inside mycontainer. */
      PtSetParentWidget( ABW_mycontainer );
      ApCreateModule( ABM_mypicture, NULL, cbinfo );
  
      /* Display the picture. */
      PtRealizeWidget( ABM_mypicture );
  
      return (Pt_CONTINUE);
  }
    

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:

• If the module is a dialog that's already instantiated, a pointer to the existing instance is returned.
• If the module is a picture and the widget argument to ApCreateModule() isn't NULL, a pointer to that widget (which now contains the contents of the picture module) is returned. If widget is NULL, a pointer to module created is returned.

Classification:

Photon

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.