[Previous] [Contents] [Index] [Next]

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

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.
    Note: 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:


Resource editor 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:

=>> 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.

Pixmap editor


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.


Note: 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:

    Pixmap 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:

    Pixmap 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:

    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:

    Fill tool

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

Note: 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:

    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:

    Nudge arrows

Some things to note:

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


Pixmap Tools window.


Using this window, you can:

Rotating an area

Pixmap editor rotate tools

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:

Flipping an area

Pixmap editor flip tools

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.

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

Inserting or deleting a row or column

Pixmap editor insert/delete tools

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.

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

Cutting, copying, and pasting

Pixmap editor cut/copy/paste tools

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.

Note: 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:

PhAB 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/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 Resource 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.

Note: 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


    List Editor.

    
    
  2. Click on the text field near the bottom of the dialog, then type the text you want.
    Note: 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.

Note: 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.

Note: 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 Resource Editor


Number Editor.


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

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


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

Note: 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


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

Note: 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


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:

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:

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.


Note: 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.


Note: 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 session


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:
  4. After you've added or edited any callback, click on the appropriate button:

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.


Note: 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


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):

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.


Note: 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.
Note: 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

Here's some basic information about hotkeys:

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:

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 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.


Note:
  • 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


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.

Processing hotkeys

Here's how a hotkey works:

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:

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

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.


Note: 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


    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.

Note: 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.


[Previous] [Contents] [Index] [Next]