PtAppSetResources()

Set application-level resources

Synopsis:

int PtAppSetResources(int n_args,
                      PtArg_t const *args);

Arguments:

n_args

The number of items in the args array.

args

An array of PtArg_t

Library:

ph

Description:

This function sets the resources specified in the args array for the application. This function operates identically to its widget counterpart, PtSetResources(), except it doesn't have a widget argument.

---

If you're setting only one resource, it's easier to call PtAppSetResource().

---

If you are setting a single callback resource, it is easier to use PtAppAddCallback().

For more information, see the Manipulating Resources in Application Code chapter of the Photon Programmer's Guide.

The following resources can be set for an application:

Pt_CB_APP_EXIT

A list of PtAppCallback_t structures that define the callbacks invoked when the application is exiting via a call to PtExit(). All exit points from the library call PtExit(), but it is up to the application designer to exit via this method also. Callbacks should unconditionally return Pt_CONTINUE — other return values may be interpreted differently in future versions.

---

Although an application might call PtExit() more than once (for example, from different threads in a multi-threaded application), the callbacks in this list are invoked only once.

---

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_APP_EXIT

reason_subtype

0 (not used).

event

NULL

cbdata

NULL

Pt_CB_APP_WCLASS_CREATED

A list of PtAppCallback_t structures that define the callbacks invoked immediately after a new widget class is created.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_APP_WCLASS_CREATED

reason_subtype

0 (not used).

event

NULL

cbdata

A pointer to a PtAppWClassCallback_t structure that contains at least PtWidgetClass_t *wclass, which indicates the class that has been created.

Pt_CB_FILTER

A list of PtAppRawCallback_t structures that define the callbacks invoked when an event that matches the provided event mask is to be passed to the application. Application-level event filters are invoked prior to any widget processing (including the widget event filters), and can preempt events in a similar fashion

---

Your application must have at least one region open for this resource to work.

---

Each callback is passed a PtCallbackInfo_t structure. See the Pt_CB_FILTER resource for PtWidget for a description of what this structure contains.

Pt_CB_RAW

A list of PtAppRawCallback_t structures that define the callbacks that the application invokes if the event it receives matches the event mask provided in the PtAppRawCallback_t structure. Application-level raw callbacks are invoked after all widget processing has been done, if the event has not been consumed.

---

Your application must have at least one region open for this resource to work.

---

Each callback is passed a PtCallbackInfo_t structure. See the Pt_CB_RAW resource for PtWidget for a description of what this structure contains.

Pt_CB_HOTKEY

A list of PtAppHotkeyCallback_t structures. If the application receives a key event that matches a structure's key cap and key modifiers, the application calls the function specified in that structure.

Application-level hotkey handlers are invoked after widget processing is completed, and after any application-level Pt_CB_FILTER callbacks.

---

Your application must have at least one window for this resource to work. Also, you cannot bind application-level hotkey handlers to widgets. Therefore you must supply a callback function (this is different from the widget-level hotkey handlers).

---

Each callback is passed a PtCallbackInfo_t structure. See the Pt_CB_HOTKEY resource for PtWidget for a description of what this structure contains.

PtAppCallback_t

An application callback structure.

typedef struct Pt_app_callback {
  int  (*event_f)( void *, PtCallbackInfo_t * ),
  void *data;
} PtAppCallback_t;

The PtAppCallback_t structure lets you specify an application's callbacks. This structure contains at least:

event_f

A pointer to the callback function.

data

A pointer to data you want to pass as the second parameter to the callback function when it's invoked.

The callback function takes the following arguments:

void *client_data

The data from the PtAppCallback_t structure.

PtCallbackInfo_t *cbinfo

A pointer to a common Photon callback structure. The structure provides information related to the widget callback being invoked, the Photon event, and some widget-specific callback data. The format of the data varies with the widget class and callback type. For more information, see PtCallbackInfo_t.

Callback functions should return Pt_CONTINUE unless the description of the widget's callback resource tells you to return something else.

PtAppRawCallback_t

The PtAppRawCallback_t structure lets you specify event handlers (raw and filter callbacks) for your application. You use this structure when setting the Pt_CB_RAW or Pt_CB_FILTER resource of your application.

typedef struct Pt_app_raw_callback {
  unsigned long  event_mask;
  int            (*event_f)( void *, PtCallbackInfo_t * );
  void           *data;
} PtAppRawCallback_t;

The structure contains at least the following members:

event_mask

A bitmap that specifies which events trigger the function specified in event_f. See PhEvent_t in the Photon Library Reference.

event_f

A pointer to the callback function.

data

A pointer to data that you want to be passed as the second argument to the callback function.

PtAppHotkeyCallback_t

An application hotkey callback structure.

typedef struct Pt_app_hotkey_callback {
  unsigned short      key_sym_cap;
  short               flags;
  unsigned long       key_mods;
  void                *data;
  int                  (*event_f)( void *, PtCallbackInfo_t * );
} PtAppHotkeyCallback_t;

The PtAppHotkeyCallback_t structure lets you specify hotkeys or hotkey handlers, or both, for your application. It contains at least the following members:

key_sym_cap

Depending on the specified flags, this member contains either the symbol or cap of the key to be interpreted as a hotkey. For valid key_sym_cap values, see <photon/PkKeyDef.h>.

flags

Determines how key_sym_cap is interpreted and whether or not key_mods is used. Valid bits include:

Pt_HOTKEY_SYM

Interpret key_sym_cap as a key symbol; the default is to interpret it as a key cap.

Pt_HOTKEY_IGNORE_MODS

Ignore the key_mods argument. This flag is typically used in menus, where you want both upper- and lowercase letters to be accepted as hotkeys.

key_mods

Key modifiers that must be active for the key to be considered a hotkey. If the Pt_HOTKEY_IGNORE_MODS flag is set, this member is ignored.

For valid key modifiers, see <photon/PkKeyDef.h>. All key-modifier manifests begin with Pk_KM_.

data

A pointer to any data that you want to pass as the second argument to the callback function.

event_f

A pointer to the hotkey function.

Returns:

0

At least one of the resources was applied to the application.

-1

The application wasn't modified because it doesn't contain the given resources or the values of the resources were the same as those already stored in the application.

Examples:

Set the Pt_CB_APP_EXIT callback resource for an application:

int exit_cb(void *data,
                    PtCallbackInfo_t *cbinfo)
{
  printf( "I\'m exiting\n" );
  return( Pt_CONTINUE );
};
...
PtAppCallback_t exit_callbacks[] = {{exit_cb, NULL}};
PtArg_t args[1];
PtSetArg( &args[0], Pt_CB_APP_EXIT, exit_callbacks,
          sizeof(exit_callbacks)/sizeof(exit_callbacks[0]));
PtAppSetResources( 1, args );

Classification:

Photon

See also:

PtAppAddCallback(), PtAppGetResources(), PtAppGetResource(), PtAppRemoveCallback(), PtAppSetResource(), PtSetArg().