---

Editing Resources and Callbacks in PhAB

Once you've created widgets in PhAB, you'll probably need to edit their resources and callbacks. This chapter discusses:

• Editing widget resources
• Pixmap editor
• Color editor
• Flag/option editor
• Font editor
• List editor
• Number editor
• Text editor
• Multiline text editor
• Function editor
• Callbacks
• Editing callbacks
• Module callbacks
• Code callbacks
• Hotkey callbacks
• Raw-event callbacks

Editing widget resources

A widget typically has many resources that let you change its appearance and behavior. Each type of resource has its own editor.

To open any resource editor:

1. Select one or more widgets.

   ---

   When you select two or more widgets, the Control Panel displays only the resources that those widgets have in common. Editing any of these resources will affect all the selected widgets.

   ---

2. Switch the Control Panel to Resource mode, if necessary.

   If a resource's value has been changed from the default value set for the widget, the resource's label is displayed in bold.

3. Click on a resource in the Control Panel. The appropriate resource editor will pop up.

Every resource editor provides the following buttons:

---

---

Common buttons for resource editors.

When you want to:	Use this button:
Apply any changes and close the editor	Done
Apply any changes and continue editing	Apply
Restore the resource to the default value (or values if more than one widget is selected)	Default
Cancel any changes made since you opened the editor or last clicked on Apply	Cancel

The editors for different types of resources are described in the sections that follow.

To edit:	See this section:
Bitmaps or images	Pixmap editor
Colors	Color editor
Flags	Flag/option editor
Fonts	Font editor
Lists of text items	List editor
Numbers	Number editor or Flag/option editor
Single-line text strings	Text editor
Multiline text strings	Multiline text editor
Functions	Function editor

Pixmap editor

The pixmap editor lets you customize a widget's pixmap. The editor provides a complete range of tools, so you can draw virtually any pixmap your application might need.

In this section we discuss:

• setting the pixmap's size
• choosing colors
• how to draw and erase
• drawing freehand
• drawing lines, rectangles, and circles
• filling an enclosed area
• selecting an area
• using the Pixmap Tools window
• other pixmap controls

To open the pixmap editor for any widget that can contain an image (for example, PtBitmap, PtButton), click on the widget, then click on a Bitmap or Label resource in the Control Panel.

---

---

Sample pixmap editor session.

The editor has several drawing modes and tools. The default is freehand mode-you simply drag the pointer across the drawing grid.

Setting the pixmap's size

The editor contains fields for the pixmap's height and width, both specified in pixels. To change a dimension, edit the field and press Enter.

---

If you reduce the size of a pixmap, part of the image may be cut off.

---

Choosing colors

To choose the draw color:

1. Click on the following color selector:

   

   If you're editing a bitmap, you'll see the color editor. If you're editing an image, you'll see the palette color selector.

2. Click on the color of your choice. All drawing will be done in that color until you select a new color.

Choosing a background color

If you're editing a bitmap, the background color is always transparent. If you're editing an image resource, you can choose the background color (which you draw using the right mouse button). To choose the background color:

1. Click on the following color selector:

   

2. Click on the color of your choice.

For more info, see the Color editor section.

How to draw and erase

The following applies to all drawing tools:

In order to:	Use the:
Draw in the current color	Left mouse button
Erase a pixel or area (i.e. draw in the background color)	Right mouse button

Drawing freehand

The freehand tool lets you draw freeform lines and erase single pixels for quick fix-ups.

To draw in freehand mode:

1. Click on the freehand tool:

   

2. Point to where you'd like to start drawing.
3. Drag the pointer, moving it as if you were drawing with a pencil, then release the mouse button when you're done.

   You can repeat this step as often you'd like.

To erase the pixel under the pointer, click the right mouse button.

Drawing lines, rectangles, and circles

To draw lines, rectangles, or circles, you use one standard method:

1. Click on the appropriate tool.
2. Point to where you'd like the object to begin.
3. Drag the pointer to where you'd like the object to end, then release the mouse button.

   You can repeat this step as often as you'd like.

Filling an enclosed area

To fill any enclosed area (i.e. any area made up of a single color):

1. Click on the fill tool:

   

2. Move the pointer inside the area you wish to fill, then click.

---

If an outline area has a break, the fill operation will spill out of the hole and potentially fill the entire pixmap display.

---

Selecting an area

To use some tools, you first select an area of the pixmap.

To select an area:

1. Click on the Select tool:

   

2. Point to where you'd like the selection to begin.
3. Drag the pointer to where you'd like the selection to end, then release the mouse button.

   You can now "nudge" the area or perform any of the operations described in "Using the Pixmap Tools window," below.

Nudging an area

To nudge a selected area one pixel at a time:

1. Select the area you wish to nudge.
2. Click on a nudge arrow:

   

Some things to note:

• PhAB overwrites any pixels in the direction of the nudge.
• A nudge can't push an area out of the pixmap.
• PhAB introduces blank space into the pixmap to fill the space left by the area you've nudged.

Using the Pixmap Tools window

The pixmap editor provides several other tools in their own window; if you click on the Tools button, the Pixmap Tools window opens:

---

---

Pixmap Tools window.

Using this window, you can:

• rotate
• flip
• cut, copy, and paste
• insert or delete a row or column

Rotating an area

To rotate an area 90 degrees clockwise or counterclockwise:

1. Select the area you wish to rotate.
2. Open the Tools window and click on a rotate tool.

Some things to note:

• If you rotate an area that isn't perfectly square, the area may overwrite some pixels.
• If part of the rotated area falls out of the pixmap, that part may be deleted.

Flipping an area

To flip an area sideways or upside-down (where the first pixel in the area will become the last, and so on):

1. Select the area you want to flip.
2. Open the Tools window and click on a flip tool.

---

By using the flip tools with the copy tool, you can create mirror images.

---

Inserting or deleting a row or column

To insert or delete either a row or column of pixels:

1. Choose the Select tool, then click on a row or column.
2. Click on the icon that represents the action you want.

---

When you insert a row or column, the last row or column will shift off the pixmap.

---

Cutting, copying, and pasting

To cut or copy an area of pixels:

1. Select the area you wish to move or copy.
2. Open the Tools window and click on either cut or copy.

To paste an area of pixels:

1. Click on the paste icon.
2. Point to the new location, then click. This click specifies the top-left corner of the area's new position.

---

Using the pixmap clipboard, you can: copy images from one widget to another copy an image to its "set" version to make minor modifications

---

Other pixmap controls

The pixmap editor also includes the following buttons:

When you want to:	Use this button:
Quickly erase the pixmap	Clear
Toggle the grid on and off	Grid
See the pixmap drawn to its actual size	View
Delete the pixmap and dismiss the pixmap editor	Delete
Import an image (for image-type resources only)	Import

For a description of the standard editor buttons at the bottom of the editor, see the "Editing widget resources" section.

Color editor

The color editor lets you modify any color resource. To open the color editor:

1. Select one or more widgets.
2. Click on a color resource in the Control Panel. You'll see the color editor:

---

---

Color Editor.

The color editor provides 16 base colors that you can't change. It also provides an additional 48 colors that you can customize using either the RGB (red/green/blue) or the HSB (hue/saturation/brightness) color model, whichever you prefer.

To change a color resource:

1. Click on the color you want. If you click on a custom color, you can modify it with the sliders.
2. Click on Apply or Done.

Ensuring color consistency

The Mix box helps ensure that your application colors look as accurate as possible on target systems where the graphics card doesn't support the actual color you've chosen. With Mix enabled, the graphics driver dithers available colors to get a closer match.

For a description of the standard editor buttons at the bottom of the editor, see the "Editing widget resources" section.

Flag/option editor

Whenever you click on a flags resource or on a resource that lets you select only one of several preset values, you'll see the flag/option editor. For example:

---

---

Flag/Option Editor.

Flag resources

If you click on a flag resource, this editor lets you make multiple selections from the displayed list.

To edit a flag list:

1. Select (or deselect) the flags you want. Since each flag is a separate toggle, you can select any number of flags or leave them all unselected.
2. Apply your changes. The widget changes to reflect the new flags.

Option list resources

If you click on a resource that can have only one value, the flag/option editor lets you make only one selection from the displayed list.

To choose an option from a list:

1. Click on the option. The previously selected option is deselected.
2. Apply your changes. The widget changes to reflect the new option.

For a description of the standard editor buttons at the bottom of the editor, see the "Editing widget resources" section.

Font editor

Whenever you select any font resource in the Control Panel you'll see the font editor:

---

---

Font Editor.

Control	Function
Typeface field	Lets you view or change the typeface of the widget. Just click on this field or its adjacent menu button, then choose from the displayed list of typefaces.
Point size field	Lets you view or change the point size. Works just like the typeface field.
Bold	Toggles the font to bold, if available for the current typeface and size.
Italic	Toggles the font to italic, if available for the current typeface and size.
A/A	Anti-Aliased. This smooths the font edges to make the font look nicer. A/A is available only for scalable fonts such as Swiss or Dutch.

---

If a typeface doesn't support bold or italic at a given type size, the corresponding toggle will dim or become unselectable.

---

For a description of the standard editor buttons at the bottom of the editor, see the "Editing widget resources" section.

List editor

Widgets such as PtList provide a list of text-based items. To edit the list, you use PhAB's list editor.

To open the editor and add the first item:

1. Select the widget, then click on the appropriate resource in the Control Panel (usually "List of Items"). You'll see the editor:

   ---

   

   ---

   List Editor.

2. Click on the text field near the bottom of the dialog, then type the text you want.

   ---

   If you need to type characters that don't appear on your keyboard, you can use the compose sequences listed in the International Character Support chapter of the Photon User's Guide.

   ---

3. Press Enter or click on Insert After.
4. Click on Apply or Done.

To add more items to the list:

1. Click on an existing item, then click on Insert After or Insert Before. You'll see a new item added to the list.
2. Using the text field, edit the new item's text.
3. Click on Modify, then click on Apply or Done.

---

You can't create blank lines within the list of items.

---

Editing existing list items

To edit an existing item:

1. Click on the item.
2. Edit the item's text.
3. Click on Modify, then click on Apply or Done.

---

For text-editing shortcuts, see the "Text editor" section.

---

Deleting list items

To delete an item:

1. Click on the item, then click on Delete.
2. Click on Apply or Done.

For a description of the standard editor buttons at the bottom of the editor, see the "Editing widget resources" section.

Number editor

Whenever you select any resource that's specified as a number you'll see the number editor:

---

---

Number Editor.

To change the value that the editor displays, you can:

• Use the text-editing techniques described in the Text editor section.

  Or

• Click on the editor's increase/decrease buttons.

For a description of the standard editor buttons at the bottom of the editor, see the "Editing widget resources" section.

Text editor

Whenever you click on a single-line text resource in the Control Panel (e.g. the Text String resource for PtText), you'll see the text editor:

---

---

Text Editor.

In order to:	Do this:
Delete the character before the text cursor	Press Backspace
Delete the character after the cursor	Press Del
Delete several characters all at once	Drag the pointer across the characters, then press Del
Delete the entire line	Press Ctrl -U
"Jump" the cursor to any position in the line	Click on that position
Move the cursor character by character	Press <-- or -->
Move the cursor to the start or end of the line	Press Home or End
Process a text change	Press Enter, or click on Done or Apply

---

If you need to type international characters that don't appear on your keyboard, you can use the compose sequences listed in the International Character Support chapter of the Photon User's Guide.

---

To edit widgets that support multiline text, see the "Multiline text editor" section.

For a description of the standard editor buttons at the bottom of the editor, see the "Editing widget resources" section.

Multiline text editor

When you select any multiline text resource-such as the Text String resource of a PtLabel or PtMultiText widget-you'll see the multiline text editor:

---

---

Multiline Text Editor.

In order to:	Do this:
Enter a new line of text	Press Enter
Delete the character before the text cursor	Press Backspace
Delete the character after the cursor	Press Del
Delete several characters or lines all at once	Drag the pointer across the characters, then press Del
Delete the current line	Press Ctrl -U
"Jump" the cursor to any position in a line	Click on that position
Move the cursor character by character	Press <-- or -->
Move the cursor to the start or end of a line	Press Home or End
Move the cursor to the start or end of the text string	Press Ctrl -Home or Ctrl -End
Apply your changes and dismiss the editor	Press Ctrl -Enter

---

If you need to type characters that don't appear on your keyboard, you can use the compose sequences listed in the International Character Support chapter of the Photon User's Guide.

---

For a description of the standard editor buttons at the bottom of the editor, see the "Editing widget resources" section.

Function editor

When you select a function resource, such as the Draw Function (Pt_ARG_RAW_DRAW_F) resource of a PtRaw widget, you'll see the Function editor:

---

---

Function Editor.

Type the name of the function-see "Function names and filenames" in the Working with Code chapter. You can edit the function by clicking the button to the right of the text field.

For a description of the standard editor buttons at the bottom of the editor, see the "Editing widget resources" section.

Callbacks

Callbacks form the link between your application interface and your application code. For example, let's say you want your application to perform an action when the user selects a certain button. In that case, you would attach a callback function to that button's Activate callback. When the user selects the button, the widget invokes the callback function, and your application takes the appropriate action in the callback code.

Almost all widgets support several types of callbacks. These callbacks can be specific to the widget or inherited from its parent classes. Some of these types (defined in the PtBasic widget) are defined in the following table:

Type	Resource	Typically invoked when the user:
Activate	Pt_CB_ACTIVATE	Presses and releases the left mouse button
Arm	Pt_CB_ARM	Presses the left mouse button
Disarm	Pt_CB_DISARM	Releases the left mouse button
Repeat	Pt_CB_REPEAT	Holds down the left mouse button
Menu	Pt_CB_MENU	Presses the right mouse button

For more information about these callbacks, see the Widget Reference. If you're interested in using Pt_CB_MENU to display a menu module, see the Accessing PhAB Modules from Code chapter.

All Photon widgets inherit two other types of callbacks:

hotkey callbacks

link callback code to a key or keychord. When the application window gets focus, the hotkeys will become active. Pressing one will invoke the appropriate hotkey link callback.

raw-event callbacks or event handlers

link callbacks directly to Photon events

In the development environments for most windowing systems, you can attach only callback code functions to a widget's callbacks. But whenever you use PhAB to create a callback, you can go one step further and attach windows, dialogs, menus, and much more. As we mentioned earlier, this extended functionality is provided by PhAB's special form of callback, called the link callback.

Link callbacks also let you add functionality that isn't available when you attach callbacks "by hand." For example, if you link a dialog to a button widget, you can specify where the dialog will appear. You can also specify a setup function that will be automatically called before the dialog is realized, after the dialog is realized, or both.

PhAB provides two general categories of link callbacks:

module-type link callbacks

let you attach an application module to any widget callback. PhAB provides the following categories of module-type link callbacks:

• Dialog
• Window
• Menu
• Picture
• Other

For more information, see "Module callbacks" later in this chapter.

code-type link callbacks

let you run a code function when the widget's callback is invoked. PhAB provides the following categories of code-type link callbacks:

• Code
• Done
• Cancel

The Done and Cancel types provide an additional feature: they'll automatically close or destroy the widget's parent module after the callback function is called. You'll find these types useful for creating any button that closes a dialog window.

---

A Done callback in the base window exits the application. A Cancel callback in the base window closes the application's windows but doesn't exit the application.

---

For more information, see "Code callbacks" later in this chapter.

Editing callbacks

The callback editor lets you add, change, delete, or view a widget's list of callbacks.

To add a callback to a command item or toggle item in a menu, see the "Editing menus" section of the Working with Modules chapter.

---

If you're adding a link callback to a widget, the widget's instance name must be unique. If PhAB tells you the name isn't unique, use the Control Panel's Widget Instance Name field to edit the name.

---

To open the callback editor and edit a widget's list of callbacks:

1. Select the widget, then switch the Control Panel to Callbacks mode.
2. Choose the callback type from the widget's callback list. (For example, to add an Pt_CB_ACTIVATE callback, click on Activate.)

Here's a sample callback-editor session, with information filled in for a module-type link callback:

---

---

Callback Editor.

1. To add a new callback, click on <NEW>. To edit an existing callback, click on that callback in the Callbacks list.
2. If you're adding a new callback, choose the type of callback you want to add. To do this, choose from from either "Module Types" or "Code Types."
3. Fill in the information in the "Link to Callback/Module Info" section. The fields in this section depend on the type of callback chosen. For more information, see the sections in this chapter on specifying:
   • module callbacks
   • code callbacks
   • hotkey callbacks
   • raw-event callbacks
4. After you've added or edited any callback, click on the appropriate button:
   • Apply-Apply any changes; be sure to do this before you start working on other callbacks.
   • Reset-Restore the callback information to the original values.
   • Remove-Delete the callback from the callback list.

Module callbacks

A module-type link callback can be used to connect a widget to a module. For example, selecting a button could create a module.

---

You can use an internal link to create the module in your application's code. For more information, see the Accessing PhAB Modules from Code chapter.

---

Depending on the kind of module-type link callback you're creating, PhAB's callback editor displays some or all of these fields:

---

---

Callback Editor fields for module-type link callbacks.

Name

The name of the module. If you click on the icon next to this field, you'll see a list of existing modules. Either choose from this list or enter the name of a module that doesn't exist (PhAB will create the module for you when you add the callback).

If you wish to create a link callback to an "Other" module, you must create the module first, then bring up the callback editor.

Location

Lets you specify where the module will display. By default, a menu module is located below the widget that invokes it. For all other modules, the default location is determined by the Window Manager. For more info, see the "Location dialog" section in the Working with Modules chapter.

Setup Function

Lets you specify a function that can be called at two different times (as specified by the Called field):

• before the module is displayed (prerealize)
• after the module is displayed (postrealize)

You can specify only one setup function-the PhAB API calls the same function for both pre- and postrealization of the module. To distinguish which pass is being invoked, check the PhAB reason code.

Click on the icon beside the Setup Function field to edit the function.

Hotkey-(hotkey callbacks only)

The keyboard key and modifier (such as Alt or Ctrl) that will trigger the callback. See the section "Specifying hotkey callbacks."

Event Mask-(raw-event callbacks/event handlers only)

Lets you specify which Photon events the widget will be sensitive to. See the section "Specifying raw-event callbacks."

Prerealize setup function

The prerealize setup function lets you preset a module. For example, let's say your application needs to "fill in the blanks" of a dialog before displaying that dialog. In the setup function, you would use PhAB-generated manifest names to preset the resources of the dialog's various widgets.

After the setup function runs, it returns Pt_CONTINUE. The dialog is then realized and displayed on the screen, using all the preset values.

Postrealize setup function

The postrealize function works much like the prerealize function, except that it's called after the dialog is displayed on the screen. You typically use this type of function when you need to update the module after it's become visible. PhAB's code-generation dialog provides a good example. It displays on the screen and then, using a postrealize function, updates a progress bar continuously as the application code is generated.

---

The setup function for a menu module is called only before the menu is displayed. For most applications, you would use this function to set the initial states of the menu items. For example, you could use it to disable certain menu items before the menu is displayed.

---

Setup functions are stored in stub files

When you specify a setup function, PhAB generates a stub function; for information on specifying the language (C or C++) and the filename, see "Function names and filenames" in the Working with Code chapter.

Code callbacks

When you're creating a code-type link callback, the callback editor asks you to specify the following:

Function

This is the function that's called when the widget invokes the callback. For the Done and Cancel types, this function is optional, so you can attach the callback just to close the module.

---

There's no real difference between Done and Cancel-they simply provide different reason codes in the callback. For example, let's say you have a dialog with a Done button and a Cancel button. If you attach a Done-type callback to the Done button and a Cancel-type callback to the Cancel button, you could use the same code function in both and just look at the reason code to determine which button the user selected.

---

Hotkey-(Hotkey callbacks only)

The keyboard key and modifier (such as Alt or Ctrl) that will trigger the callback. See the section "Specifying hotkey callbacks."

Event Mask-(raw-event callbacks/event handlers only)

Lets you specify which Photon events the widget will be sensitive to. See the section "Specifying raw-event callbacks."

Callback functions are stored in stub files

When you specify a callback function, PhAB generates a stub function; for information on specifying the language (C or C++) and the filename, see "Function names and filenames" in the Working with Code chapter.

Hotkey callbacks

Widgets support hotkey callbacks. These callbacks let you attach keyboard keys to specific callback functions. When the application window gets focus, the hotkeys become active. Pressing one invokes the appropriate hotkey link callback.

This section includes:

• Hotkeys - the basics
• Specifying the hotkey label
• Specifying the callback
• Processing hotkeys
• Disabling hotkeys

Hotkeys - the basics

Here's some basic information about hotkeys:

• Hotkeys are a combination of a character key and a modifier key (Alt, Shift or Ctrl). Most of the time, Alt is used for hotkeys.
• You can use a modifier on its own as a hotkey, but it's probably not a good idea.
• A hotkey isn't invoked if any ancestor of the widget that owns it is blocked.
• A hotkey is processed after the widgets have been given the key event. If a widget consumes the event, no hotkey callback is called. So when a text field has focus, the Enter key, arrow keys, Space, and all displayable characters won't work as hotkeys because the widget consumes those events. This is usually the desired behavior (consider editing in an application which has hotkeys defined for all the arrow keys).

  You can force the hotkey processing to be done first by setting Pt_HOTKEYS_FIRST in the Pt_ARG_CONTAINER_FLAGS resource of the container widget (window, pane, ...) that contains the widgets that would normally consume your would-be hotkey events. Setting this flag on the window guarantees all hotkey processing is done before any widgets get the key event. For more information, see "Processing hotkeys," below.

• Widgets must be selectable for their hotkeys to be active (with the exception of disjoint widgets such as windows and menus). Make sure the widget's Pt_ARG_FLAGS has Pt_SELECTABLE and Pt_GETS_FOCUS set.

  If the widget isn't normally selectable and you don't want its appearance to change when selected, you'll also want to set the Pt_SELECT_NOREDRAW widget flag.

• Often it doesn't matter which widget a callback is connected to. In those cases, just attach the hotkey to the window.

Specifying the hotkey label

Setting up a hotkey isn't enough-you need to tell your user about it! You should display a hotkey label in the widget invoked by the hotkey:

• For most widgets, edit the Accelerator Key (Pt_ARG_ACCEL_KEY) resource. Specify the character in the widget's label that you want underlined. You can't include any modifier keys in the label.
• For menu items, the underlined character is the shortcut that you can use to select an item when the menu's displayed. The hotkey label is displayed separately, to the right of the menu item's label. Specify the hotkey (including the modifier keys) in the menu editor's Accel Text field.

Specifying the callback

In PhAB, each widget's callback list displays an entry called "Hotkey" or Pt_CB_HOTKEY that you use to define hotkeys. Before you define the hotkey, you need to determine where to do so. Where you define the hotkey callback depends on:

• where you want a module (such as a menu) to appear
• what widget you need in the callback function
• where the user is going to type the hotkey

Where you want a module to appear

When you define the hotkey, you can specify where the module is to appear. For example, if the hotkey is meant to display the menu module associated with a PtMenuButton widget in your window's PtMenuBar, define the hotkey in the menu button. Use the Location dialog to have the menu appear under the menu button.

What widget you need in the callback function

The widget that owns the callback is the one passed to the callback function.

Where the user is going to type the hotkey

For example, if the hotkey is an accelerator for a menu item, add the hotkey to the window in which the menu is used, not to the menu module.

---

The hotkeys in a given module should be unique. If you define the same hotkey more than once, the last one is used. If you're developing a multilingual application, you'll need to choose hotkeys carefully so they'll be relevant in each language, or you'll need a different set of hotkeys for each language. See the International Language Support chapter for more information.

---

When you select the Pt_CB_HOTKEY callback, the callback editor pops up with a Hotkey field in the link-information area:

---

---

Hotkey field in the Callback Editor.

You must fill in the Hotkey field when creating a hotkey callback. There are two ways to set up the hotkey: one easy, the other not so easy.

• the not-so-easy way-you can type the hotkey value, in hex, in the Hotkey field. To find the value for the keycap you want to use, see the header file <photon/PkKeyDef.h>, and search for the name of the keycap, prefixed by Pk_.

  ---

  Use lowercase letters for hotkeys; uppercase letters won't work. For example, for a hotkey Alt -F , look up the hex value for Pk_f, not Pk_F.

  ---

  The field also has 3 toggle buttons-Ctrl, Shift, and Alt-to let you specify modifiers for the hotkey value.

• the easy way-press the button to the right of the Alt toggle button, then press the keychord you want to use for the hotkey. PhAB automatically determines the key and modifiers you pressed.

Processing hotkeys

Here's how a hotkey works:

• When a key event arrives at a window, the window passes the event to its child widgets.
• If a child consumes the event, nothing further happens.
• Otherwise, the event is checked against the window's list of hotkeys. If the hotkey is found, its callback is invoked.
• If the hotkey isn't found, the parent window's hotkey list is searched, and so on up the hierarchy of windows.

The Pt_ARG_CONTAINER_FLAGS resource of container-class widgets includes some flags that affect the processing of hotkeys:

Pt_HOTKEY_TERMINATOR

Prevent the hotkey search from going up to the parent container.

The Pt_HOTKEY_TERMINATOR flag works only if it's set in a disjoint container-class widget.

Pt_HOTKEYS_FIRST

Process key events that reach this container as hotkeys before passing them to the container's children. If the event is a hotkey, it's consumed, so it isn't passed to the children.

Disabling hotkeys

Giving the user a visual indication that a hotkey is disabled is different from actually disabling the hotkey.

To give the visual indication, use the technique appropriate to the widget:

• If the hotkey is associated with a button, set the Pt_GHOST flag and remove the Pt_SELECTABLE and Pt_GETS_FOCUS flags in the button's Pt_ARG_FLAGS resource.
• If the hotkey is associated with a menu item created in PhAB, call ApModifyItemState().
• ...

To disable the hotkey, use one of the following techniques:

• Don't disable the hotkey. Instead, as the first thing you do in your hotkey's callback code, check to see if anything should be done. If not, just return from the callback. For example, if the hotkey callback is the one for pasting text, check to see if there's anything to paste. If there isn't, simply return.

  Or

• With the exception of disjoint widgets, if the widget that the hotkey callback is attached to isn't selectable, the hotkey will be treated as if it didn't exist. For a widget to be selectable, the Pt_SELECTABLE flag must be set in the Pt_ARG_FLAGS resource.

  One good reason for this approach is that it works even if your application has the same hotkey defined in more than one window. For example, we might have an Edit menu in the base window and an Erase button in a child window, both with Alt -E as a hotkey. If the child window currently has focus and the user presses Alt -E , the child window's Erase button callback is called.

  Now, if we disable the Erase button in the child window, we would want Alt -E to cause the base window's Edit menu to appear. In this scenario, as long as the Erase button is selectable, its callback would be called. So we simply make the Erase button unselectable. Now when the user presses Alt -E , the base window's Edit menu appears, even though the child window still has focus.

  Or

• You could call PtRemoveHotkeyHandler() to remove the hotkey and later call PtAddHotkeyHandler() to enable it again.

Raw-event callbacks

Raw-event callbacks (also called event handlers) let you respond directly to Photon events. PhAB lets you attach raw callbacks to any widget. A raw callback is like a standard widget callback, but with the addition of an event mask. Using this mask, you can choose which events you'll receive.

You'll find them particularly useful for getting the Ph_EV_DRAG events for a particular window. For more information on dragging, see "Dragging" in the Events chapter.

---

The Pt_CB_RAW callbacks defined for PtWidget are invoked after the widget has processed the event, and then only for events that the widget doesn't consume. In contrast, the Pt_CB_FILTER callbacks defined for PtContainer are invoked before the event is passed to the child widget.

---

To attach a raw callback:

1. Select the widget, then switch the Control Panel to Callbacks mode.
2. Click on the Pt_CB_RAW or Raw Event resource to open the callback editor.
3. The editor pops up with an Event Mask field in the link information area:

   ---

   

   ---

   Event Mask field in the Callback Editor.

   The Event Mask field lets you specify which Photon events you want the widget to be sensitive to. When any of those low-level events occur, the widget will invoke the callback.

   Click on the icon next to this field to open the event selector.

4. Select the events you want the widget to be sensitive to, then close the selector.

---

When you attach raw events to a widget, the widget library creates a region, if necessary, that will pick up specific events for the widget. This increases the number of regions the Photon Manager must manage and, as a result, may reduce performance. For that reason, use raw events only when you have to do something that can't be done using standard widget callbacks. If you do use raw events, consider using them only on window widgets, which already have regions.

---

For more info, see the event types described for the PhEvent_t structure in the Photon Library Reference.

---