PtAddHotkeyHandler()

Add a single hotkey handler entry to a widget

Synopsis:

void PtAddHotkeyHandler( PtWidget_t *widget,
                         unsigned  key_sym_cap,
                         unsigned  key_mods,
                         short flags,
                         void *data,
                         PtCallbackF_t *callback );

Library:

ph

Description:

This function adds the specified callback to the Pt_CB_HOTKEY callback list that belongs to the specified widget. The widget will invoke this callback whenever all three of the following conditions are met:

• The widget's window has focus.
• The widget is selectable (not required if the widget is a window).
• The widget's window receives a key event that matches key_sym_cap and key_mods (that is, the key is not consumed by another widget).

The flags argument can contain the following:

Pt_HOTKEY_SYM

Interpret key_sym_cap as a key sym; 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 hot keys.

Pt_HOTKEY_CHAINED

Let the hotkey be bound to more than one widget. The callbacks for all widgets with the hotkey are invoked (instead of just the callback for the last widget to register the hotkey).

The callback argument points to a function that takes this form:

int (*callback)(PtWidget_t *, void *, PtCallbackInfo_t *)

Hotkey entries are stacked. As a result, the last hotkey attached is the first to be checked.

If a hotkey callback is triggered, the key event is consumed and no other hotkey callbacks are invoked. If callback is NULL, the widget's Pt_CB_ACTIVATE callback list is invoked when the hotkey is pressed.

Note the following:

• Key caps, key mods, and key syms are defined in <photon/PkKeydef.h>.
• Key mods are prefixed with Pk_KM_.
• Key caps and key syms are prefixed with only Pk_.

Hotkeys are handled at the window level. So if two widgets within the same window happen to register the same hotkey definition without specifying the Pt_HOTKEY_CHAINED flag, only the callback for the last duplicate hotkey is invoked.

Hotkey callbacks are automatically registered when the owner widget is realized, and automatically removed when the owner widget is unrealized.

Examples:

PtWidget_t *widget1, *widget2, *widget3,  *window;
...
// add a hotkey to the window on the key sym 
// for Escape.

PtAddHotkeyHandler( window, Pk_Escape, 0,
                    Pt_HOTKEY_SYM, 
                    NULL, escape_callback );

// add a hotkey handler for the digit "1" to                      
// widget1 that ignores the states of Ctrl/Alt/Shift.

PtAddHotkeyHandler( widget1, Pk_1, 0,
                    Pt_HOTKEY_IGNORE_MODS, 
                    NULL, one_callback );

// add a hotkey handler for the digit "2" to widget2 
// that will be triggered only if the CTRL modifier            
// is pressed when "2" is hit.

PtAddHotkeyHandler( widget2, Pk_2, Pk_KM_CTRL, 0, 
                    NULL, ctrl_2_callback );

// add a hotkey handler for the digit 3 to widget3. 
// When triggered, widget3's activate callback will be 
// invoked with a reason type of Pt_CB_ACTIVATE and a
//  reason_subtype of Pt_CB_HOTKEY.

PtAddHotkeyHandler( widget3, Pk_3, 0, 0, NULL, NULL );

// Remove the hotkey handlers.

PtRemoveHotkeyHandler( window, Pk_Escape, 0,
                       Pt_HOTKEY_SYM, 
                       NULL, escape_callback );
PtRemoveHotkeyHandler( widget1, Pk_1, 0,
                       Pt_HOTKEY_IGNORE_MODS, 
                       NULL, one_callback );
PtRemoveHotkeyHandler( widget2, Pk_2, Pk_KM_CTRL, 0, 
                       NULL, ctrl_2_callback );
PtRemoveHotkeyHandler( widget3, Pk_3, 0, 0,
                       NULL, NULL );

Classification:

Photon

See also:

PtAddCallback(), PtAddCallbacks(), PtAddEventHandler(), PtAddEventHandlers(), PtAddFilterCallback(), PtAddFilterCallbacks(), PtRemoveHotkeyHandler()

PtCallbackInfo_t in the Photon Widget Reference

"Hotkey callbacks" in the Editing Resources and Callbacks in PhAB chapter of the Photon Programmer's Guide.