Creating Widgets in PhAB

Once you've created or opened an application, you'll probably want to add, delete, and modify widgets. This chapter describes how to work with widgets.

• Types of widgets
• Instance names
• Creating a widget
• Selecting widgets
• Positioning widgets with a grid
• Aligning widgets
• Common User Access (CUA) and handling focus
• Ordering widgets
• Dragging widgets
• Setting a widget's x and y coordinates
• Transferring widgets between containers
• Resizing widgets and modules
• Moving and resizing widgets with the nudge tool
• Clipboard
• Duplicating widgets and containers
• Deleting widgets
• Importing graphic files

For information on using specific widget classes, see: the Widgets at a Glance appendix in this guide the Photon Widget Reference Since widgets inherit a lot of behavior from their parent classes, you should make yourself familiar with the fundamental classes: PtWidget, PtBasic, PtContainer, and so on.

Types of widgets

There are two major types of widgets:

• container widgets-such as PtPane and PtScrollArea
• noncontainer widgets-such as PtButton and PtText

Container-class widgets can contain other widgets-including other containers. Widgets placed inside a container are known as child widgets; the hierarchy resulting from this nesting is called the widget family. Container widgets can look after sizing and positioning their children, as described in the Geometry Management chapter.

When working with container-class widgets in PhAB, remember the following:

• If you move a container, all the container's child widgets also move.
• If you position the pointer inside a container when creating a new widget, that widget is placed hierarchically within the container.
• If you wish to use the bounding-box method to select widgets in a container, you must:
  • press Alt before you start the bounding box
  • start the bounding box within the container

  For more info, see "Selecting widgets" in this chapter.

Instance names

If your program has to interact with a widget, that widget must have a unique instance name. Using this name, PhAB generates a global variable and a manifest that let you easily access the widget from within your code.

To view or edit a widget's instance name, use the Widget Instance Name field at the top of the Control Panel:

Editing a widget's instance name.

A widget's instance name is used to make several C variables, so it can include only letters, digits and underscores. PhAB won't let you use any other characters. An instance name can be no longer than 64 characters. You should develop a naming convention for all the widgets in your application - it will make large applications more manageable.

You can optionally include the instance name in the widget's memory. See "Including instance names" in the Working with Applications chapter.

Default instance name

When you create a widget, PhAB automatically gives it a default instance name. Typically, this default name is the widget's class name. For example, if you create a PtButton-class widget, the Control Panel displays PtButton as the instance name.

If a widget simply serves as a label or window decoration, it doesn't have to be accessed from within your application code. So you should tell PhAB to ignore the widget's instance name during code generation. To do this:

• Leave the instance name equivalent to the class name (that is, leave the default alone).

  Or

• Provide a blank instance name.

When to assign a unique name

You should give a widget a unique name if:

• the widget needs to have a callback attached
• the application needs to change the widget by setting a resource
• the application needs to extract information from the widget

To keep the number of global variables to a minimum, don't give a widget a unique name unless you really need to access the widget from within your application. If you've given a widget a name and later decide you don't need the name, just change it back to the widget's class name or blank it out.

Instance names and translations

As described in the chapter on International Language Support, you'll need an instance name for every text string in your application's user interface. These instance names aren't needed in your code.

To indicate that an instance name isn't required for code generation, start the name with the @ character. PhAB recognizes such a name when generating the text language database, but skips over it when generating code.

If you don't want to create a unique instance name for a string that's to be translated, specify a single @ character for the instance name, and PhAB appends an internal sequence number to the end.

If you don't want to create unique instance names, but you want to organize the text for translation (say by modules), you can give the strings the same instance name, and PhAB will append a sequence number to it. For example, if you assign an instance name of @label to several strings, PhAB will generate @label, @label0, @label1, ... as instance names.

Duplicate names

PhAB resets the instance name of a widget back to the widget class name if it detects a duplicate name when you:

• copy and paste a widget (see "Clipboard")
• import a widget from another application (see "Importing PhAB modules from other applications" in the Working with Modules chapter)
• duplicate a widget (see "Duplicating widgets and containers")

Creating a widget

To create a widget:

1. If the widget isn't in the widget bar, you'll have to add it. See "Customizing the widget bar" in the PhAB Environment chapter.
2. Click on widget-bar icon for the type of widget you want to create (see the Widgets at a Glance appendix to identify the widget-bar icons).
3. Move the pointer to where you want to create the widget. The pointer changes to show you what to do next:
   • If the pointer is a crosshair and you're creating a PtPolygon or PtBezier widget, hold down the mouse button and drag the pointer until the line goes where you want it to go. To add points, you must start the next point on top of the last.
   • If the pointer is a crosshair and you're creating any other type of widget, click the mouse button.
   • If the pointer is a two-headed arrow, hold down the mouse button and drag the pointer until the widget is the size you want.

Creating several widgets

Once you've created a widget, you're returned to select mode. To stay in create mode so you can create several widgets of the same type:

1. Press and hold down Ctrl.
2. Create as many widgets as you want.
3. Release Ctrl.

Canceling create mode

To cancel create mode without creating a widget:

• Click the right mouse button in a module.

  Or

• Click on the arrow icon at the top of the widget bar.

Selecting widgets

In this section we look at:

• selecting a single widget
• selecting multiple widgets
• selecting widgets within a group
• selecting hidden widgets

When PhAB is in select mode, the pointer appears as an arrow. To put PhAB into select mode:

• Click the right mouse button in a module.

  Or

• Click on the arrow icon at the top of the widget bar:

  

A single widget

To select a single widget, you can:

• Point and click.

  Or

• Use the Control Panel.

Point-and-click method

To select a single widget using point and click:

1. Make sure you're in select mode.
2. Click on the widget, using the left mouse button. Resize handles will appear around the widget.

Control-Panel methods

The Next and Previous buttons in the Control Panel let you select any widget in the current module.

The Control Panel also provides a Module Tree mode that displays a tree of all the widgets in the module. Using this tree, you can:

• select a widget inside a group
• find a widget by name
• select a widget hidden underneath another widget

To select a widget from the tree, click on the widget's name.

Multiple widgets

To select multiple widgets, you can:

• Use a bounding box.

  Or

• Use "Shift and click."

  Or

• Use the Control Panel

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.

Using a bounding box

A bounding box lets you select several widgets all at once:

1. Position the pointer above and to the left of the widgets you want to select.
2. If the widgets belong to a container such as PtPane, make sure the pointer is within the container, then hold down the Alt key.
3. Hold down the left mouse button, then drag the pointer down to the right. You'll see an outline "grow" on the screen. For example:

   

4. When all the widgets are within the outline, release the mouse button. You'll see resize handles appear around the area defined by the selected widgets.

Using "Shift and click"

To add or remove a widget from the current list of selected widgets, hold down Shift and click on the widget. This is also known as the extended selection method.

If the widget isn't already selected, it'll be added to the list. If the widget is already selected, it'll be removed from the list.

The above methods for selecting multiple widgets work only for widgets at the same hierarchical level. For example, let's say you've just selected two buttons inside a window. You can't extend that selection to include a button that's inside a pane.

Using the Control Panel

To select multiple widgets, using the Control Panel's Next and Previous buttons:

1. Hold down Shift.
2. Click on the Next button.

   Every time you click, PhAB adds the next widget in the current module to your selection.

To remove the last widget from the current list of selected widgets:

1. Hold down Shift.
2. Click on the Previous button.

   Every time you click, PhAB removes another widget.

Widgets within a group

To select a widget inside a group, you can use the Control Panel's Module Tree mode or its Next and Previous buttons.

Selecting a single widget

To select a single widget within a group:

1. Switch the Control Panel to Module Tree mode.
2. Find the group in the tree and click on the widget's name.
3. To edit the widget, switch the Control Panel to either Resources mode or Callbacks mode.

Selecting multiple widgets

To select one or more widgets within a group:

1. Click on any widget within the group to select the entire group.
2. Click on the Control Panel's Next button (or press F10) until the widget you want is selected.
3. To select additional widgets, press Shift, then click again on the next-widget button.
4. You can now edit the widgets' resources or callbacks.

Hidden widgets

If you can't find a widget (it may be hidden behind another widget or is outside the boundaries of its container), do the following:

1. Using the Control Panel's Next and Previous buttons or Module Tree mode, select the widget.
2. If the widget seems to be outside the current boundaries of its container, bring it back into view by using the speedbar's x and y fields.

Positioning widgets with a grid

PhAB lets you use a grid to position and size widgets. You can turn the grid on or off, or change its origin and size. The grid doesn't appear onscreen.

To change the grid:

1. Choose Grid from the Options menu. The following dialog appears:

   ---

   

   ---

   Grid Settings dialog.

2. Type in an origin and a frequency.
3. Enable Snap to Grid - otherwise the grid isn't used.
4. Click on Done.

Grid settings remain for the current session only. They aren't saved.

Aligning widgets

You can align several widgets to another widget or to their parent container.

To another widget

When you use this method to align widgets, the widgets are aligned to the first widget you select:

1. Select the first widget.
2. Using the "Shift and click" selection method, select the remaining widgets. (This method is described in "Selecting widgets.")
3. Bring up the Align Widgets dialog. To do this, you can:
   • choose Alignment from the Edit menu
   • press Ctrl -A
   • click on the Alignment icon in the speedbar:

     

4. Choose one or more alignment options, then click on the Align Widgets button. Don't click on an Align to Container button.

To a parent container

To align widgets to their parent container:

1. Select one or more widgets in any order.
2. Bring up the Align Widgets dialog, choose your alignment options, then click on the appropriate Align to Container button.

   If you choose both vertical and horizontal options, make sure to click on both Align to Container buttons.

3. Click on the Align Widgets button.

When aligning widgets to a container you may want the widgets to retain their relative positions to each other. To do this: Group the widgets together (see the section "Aligning widgets using groups" in the Geometry Management chapter). Align the widgets. Break the group apart (optional).

Common User Access (CUA) and handling focus

Common User Access (CUA) is a standard that defines how a user can change the keyboard focus. A widget is focusable if it can be given focus by pressing CUA keys or by calling a focus function.

Changing focus with the keyboard

The following keys move focus only to focusable widgets:

For information on specifying the order in which the widgets are traversed, see the section "Ordering widgets" in this chapter.

Controlling focus

Use the following Pt_ARG_FLAGS flags to control focus for a widget:

Pt_GETS_FOCUS

Make the widget focusable

Pt_FOCUS_RENDER

Make the widget give a visual indication that it has focus

In addition, use the following Pt_ARG_CONTAINER_FLAGS flags to control focus for a container:

Pt_BLOCK_CUA_FOCUS

Prevent the CUA keys from being used to enter the container. However, if the user clicks inside the container, or a focus function gives it focus, the CUA keys can then be used.

Pt_ENABLE_CUA

Give the parent widget the chance to control whether or not a child container handles the CUA keys:

• If this flag is set, the widget's code handles the CUA keys.
• If it isn't set, the CUA keys are passed up the widget family until an ancestor is found with this flag set. This ancestor (if found) handles the keys.

Pt_ENABLE_CUA_ARROWS

The same as Pt_ENABLE_CUA, but it applies only to the arrow keys.

Focus callbacks

All descendants of the PtBasic widget have the following callback resources:

• Pt_CB_GOT_FOCUS -called when the widget gets focus
• Pt_CB_LOST_FOCUS -called when the widget loses focus

For more information, see the Widget Reference.

Focus-handling functions

For a list of functions that deal with focus-handling, see the Summary of Entries in the Photon Library Reference.

Ordering widgets

In PhAB, each widget exists in front of or behind other widgets. This is known as the widget order, and you can see it when you overlap several widgets.

Here's how to ensure that widgets are in the order you want (so that, for example, using CUA keys to move between widgets works in the correct order):

1. Using the extended ("Shift and click") selection method, select the widgets in the order you want. (This selection method is described in "Selecting widgets.")
2. Do one of the following:
   • choose To Front or To Back from the Edit menu
   • press Ctrl -F or Ctrl -B
   • click on one of these icons:

     

     PhAB will place the widgets in the order you selected them.

If you're not using PhAB, the widget order is the order in which the widgets are created. To change the order, see "Ordering widgets" in the Creating Widgets in Application Code chapter.

To view the widget order, do one of the following:

• use the Control Panel's Module Tree mode
• use the module's Test mode to check the focus order

Dragging widgets

Dragging a widget is the easiest way to move a widget in most situations since it's quick and fairly accurate:

1. Select the widgets.
2. Point to one of the selected widgets, press down the mouse button, then drag the widgets to the new position.
3. Release the mouse button.

To cancel a drag operation, press Esc before releasing the mouse button.

Widgets will snap to the grid if the grid is enabled. See the "Positioning with a grid" section in this chapter. Widgets may "disappear" if you move them beyond the boundaries of their container. If this happens, use the previous/next buttons in the Control Panel to select the widgets, then use the x and y fields in the speedbar to bring the widgets back into view.

Dragging preferences

There are several preferences that you can set for dragging (see the "Customizing your PhAB environment" section in the chapter on PhAB's environment):

• Dragging has a damping factor that determines how far you must drag before the widget moves. The default is 4 pixels.
• You can drag widgets either as an outline or as full widgets.
• You can drag modules either as an outline or as full modules.

Setting a widget's x and y coordinates

To place one or more widgets at specific coordinates:

1. Select the widgets.
2. Type the coordinates in the x and y fields in the speedbar, then press Enter.

Transferring widgets between containers

To move one or more widgets directly from one container or module to another:

1. Select the widgets.
2. Do one of the following:
   • Choose Transfer from the Edit menu.

     Or

   • Press Ctrl -T .

     Or

   • Click on the Transfer icon in the speedbar:

     

3. Move the pointer into the other container and click the mouse button.

Resizing widgets and modules

When you select a widget or module, you'll see its height and width-including margins-displayed in the speedbar's height and width fields. (These values are maintained by the Pt_ARG_DIM resource; see the description of PtWidget in the Widget Reference.)

To resize a selected widget, do one of the following:

• Drag one of the widget's resize handles.

  Or

• Click on the height or width field in the speedbar, type in a new value, then press Enter.

  Or

• Use the nudge tool.

If a module is in Test mode, its resize handles won't function. To resize the module using the handles, click on the module-type tab to switch the module to build mode. If you have trouble seeing a widget's resize handles because of the background color you've chosen, you can change the resize-handle color. For more info, see "Customizing your PhAB environment" in the PhAB Environment chapter.

Moving and resizing widgets with the nudge tool

The nudge tool has three modes of operation. To switch between these modes, click on the small box in the center of the arrows. The box changes to indicate which function is active.

Each arrow has a different effect. Experiment to see exactly how this tool works. One thing you should note: If the box is a "-", clicking on an arrow shrinks the widget in the opposite direction of the arrow.

Every click on the nudge tool will nudge, stretch, or shrink the selected widget by one pixel. To nudge by multiple pixels, hold down the mouse button.

You can also use the Ctrl key and the numeric keypad to nudge, stretch, or shrink a widget. Each key corresponds to one of the nudge buttons. For example, Ctrl -5 switches between modes, and Ctrl -/\ works like the tool's /\ button.

Clipboard

PhAB's clipboard lets you cut, copy, and paste widgets. You can't use this clipboard with other applications but you can use it to copy or move widgets from one PhAB application to another.

You'll find the clipboard helpful for two reasons:

• it saves you from creating large numbers of widgets from scratch
• it helps you create applications whose widgets look and behave consistently with each other

Cutting and copying

A cut operation removes the currently selected widgets from their module and places them in the clipboard. A copy operation copies the currently selected widgets to the clipboard without removing them from their module.

Whenever you cut or copy, PhAB removes any widgets already in the clipboard.

To cut or copy one or more widgets:

1. Select the widgets.
2. To cut, do one of the following:
   • Choose Cut from the Edit menu.

     Or

   • Press Del.

     Or

   • Click on the Cut icon in the speedbar:

     

3. To copy, do one of the following:
   • Choose Copy from the Edit menu.

     Or

   • Press Shift -Del .

     Or

   • Click on the Copy icon in the speedbar:

     

PhAB deletes a widget's callbacks when you cut or copy the widget to the clipboard. If you want to move a widget to another container but retain its callbacks, see "Transferring widgets between containers" in this chapter. The Edit menu also contains a Delete command. This command permanently removes widgets without copying them to the clipboard.

Pasting

A paste operation copies widgets from the clipboard into a module.

To paste the contents of the clipboard:

1. Make sure you're in Select mode.
2. Do one of the following:
   • Choose Paste from the Edit menu.

     Or

   • Press Insert.

     Or

   • Click on the Paste icon in the speedbar:

     

3. Point to where you'd like the clipboard objects to appear, then click the mouse.

Instance names are normally maintained when you paste. But if PhAB detects a duplicate name, it changes that name back to the class name. Because the clipboard state is saved between PhAB applications, you can cut widgets from one PhAB application and paste them into another.

Viewing the clipboard

To view the contents of the clipboard, choose Clipboard from the View menu.

Editing the clipboard

To add new widgets to the clipboard, or to edit or delete specific widgets already in the clipboard, use the same methods that you would use to edit widgets in a window or dialog module.

For a quicker way to duplicate widgets, see "Duplicating widgets and containers."

For a quicker way to move widgets from one container to another, see "Transferring widgets between containers" in this chapter.

Duplicating widgets and containers

Here's a quick and easy way to duplicate a widget or container (it's much simpler than using the clipboard):

1. Press and hold down Ctrl.
2. Point to the widget or container, hold down the left mouse button, then drag the pointer to where you'd like the new widget to appear.
3. Release Ctrl and the mouse button.

You can duplicate only one container or widget at a time. If you duplicate a container, all its children are duplicated as well. The instance names of the new widgets are reset to be the widget class name. Callbacks aren't duplicated.

Deleting widgets

To permanently remove one or more selected widgets without copying them to the clipboard:

1. Select the widgets.
2. Choose Delete from the Edit menu or press Ctrl -D .

If you want put the widgets somewhere else, you should cut the widgets, not delete them. For more information, see the section on the clipboard in this chapter.

Importing graphic files

PhAB lets you import several kinds of graphic files into your application. To import a graphic file:

1. Select the module in which you want to place the graphic.
2. Choose Import Files from the File menu. You'll see the Import submenu. If this menu is dimmed, you haven't selected a module.
3. Choose Graphics Image File from the Import submenu. You'll see a file selector.
4. To choose a file, do one of the following:
   • double-click on the file
   • click on the file, then press Enter or click on Open
   • type the file's name, then press Enter or click on Open

   PhAB will read the file, convert it into a PtLabel widget, and set the widget's Pt_ARG_LABEL_TYPE resource to Pt_IMAGE.

5. If you wish to edit the imported file, use the pixmap editor, described in the Editing Resources and Callbacks in PhAB chapter.

PhAB doesn't export graphic files directly. That's because any imported file is saved with the module in a PhAB-specific format.

The Pixmap editor (described in the Editing Resources and Callbacks in PhAB chapter) also lets you import graphics: select the widget you want to add the image to, edit its image, and choose the pixmap editor's Import button.