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
• 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
• Clipboard
• Duplicating widgets and containers
• Deleting widgets
• Importing graphic files
• Changing a widget's class
• Templates

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 PtWindow and PtScrollContainer
• 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 Resources or Callbacks 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 doesn'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 Resources and Callbacks control panels display 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; 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 generates @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 Applications chapter)
• duplicate a widget (see "Duplicating widgets and containers").

Creating a widget

To create a widget:

1. Click on widget-palette icon for the type of widget you want to create (see the Widgets at a Glance appendix to identify the widget-palette icons).
2. 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. To close a polygon, place the last point on top of the first.
   • 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.

Widgets snap to the grid if it's enabled. See "Grid preferences" in the chapter on PhAB's environment. To improve your application's performance, avoid overlapping widgets that are frequently updated.

You can also create a widget by dragging its icon from the widget palette to the Module Tree control panel. Where you drop the icon determines the widget's place in the family hierarchy.

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 anywhere outside a module.

  Or:

• Click the right mouse button in a module.

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 anywhere outside a module.

  Or:

• Click the right mouse button in a module.

  Or:

• Click on the selected widget in the widget palette.

A single widget

To select a single widget, you can:

• Point and click

  Or:

• Use the next and previous buttons in the Resources or Callbacks control panel.
• Use the Module Tree control panel.

These methods are described below.

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 appear around the widget.

To select the parent of a widget, hold down Shift -Alt and click on the widget. This is a handy way to select a PtDivider or PtToolbar.

Control-panel methods

The Next and Previous buttons in the Resources and Callbacks control panels let you select any widget in the current module.

The Module Tree control panel 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 panels.

When you select two or more widgets, the Resources control panel displays only the resources that those widgets have in common. Editing any of these resources affects 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 PtBkgd, 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.
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's added to the list. If the widget is already selected, it's 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 panels

To select multiple widgets, using the Resources or Callbacks 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 next and previous buttons in the Resources or Callbacks control panel, or use the Module Tree control panel.

Using the Module Tree panel

To select a single widget within a group, using the Module Tree control panel:

1. Switch to the Module Tree control panel.
2. Find the group in the tree and click on the widget's name.
3. Shift-click to select additional widgets, if you want.
4. To edit the widget, switch to the Resources or Callbacks control panel.

Using the Next and Previous buttons

To select one or more widgets within a group, using the Next and Previous buttons:

1. Click on any widget within the group to select the entire group.
2. Click on the Resources or Callbacks 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 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. Use the Next and Previous buttons in the Resources or Callbacks control panel.
2. Select the widget from the Module Tree control panel.
3. Use the Search control panel.
4. If the widget seems to be outside the current boundaries of its container, bring it back into view by using the X and Y fields in PhAB's toolbars.

For more information on the toolbars and control panels, see the chapter on PhAB's environment.

Aligning widgets

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

For simple alignments, select the Align icon from PhAB's toolbar:

and then choose the alignment from the pop-up menu.

For more complicated alignment options, bring up the Align Widgets dialog by:

• Choosing the Align icon from PhAB's toolbar, and then choosing Alignment Tool from the menu

  Or:

• Choosing Alignment from the Edit menu, and then choosing Alignment Tool from the submenu

  Or:

• Pressing Ctrl -A .

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. For simple alignments, select the Align icon from PhAB's toolbar and make a choice from the menu.
4. For more complicated alignment options, bring up the Align Widgets dialog. Choose one or more alignment options, then click on the Align 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, be sure to click on both Align to Container buttons.

   ---

3. Click on the Align button.

When aligning widgets to a container you may want the widgets to retain their relative positions to each other. To do this:

1. Group the widgets together (see the section "Aligning widgets using groups" in the Geometry Management chapter).
2. Align the widgets.
3. Optionally, break the group apart.

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. The widget can even refuse to relinquish focus (for example, if you type invalid data in a text widget).

PtMultiText and PtText have special versions of these callbacks.

For more information, see the Widget Reference.

Focus-handling functions

The functions listed below deal with focus. They're described in the Photon Library Reference.

These functions don't actually change which widget has focus; they tell you where focus can go:

PtFindFocusChild()

Find the closest focusable child widget

PtFindFocusNextFrom()

Find the next widget that can get focus

PtFindFocusPrevFrom()

Find the previous widget that can get focus

You can use these routines to determine which widget has focus:

PtContainerFindFocus()

Find the currently focused widget in the same family hierarchy as a widget

PtIsFocused()

Determine to what degree a widget is focused

You can use these routines to give focus to a widget:

PtContainerFocusNext()

Give focus to the next Pt_GETS_FOCUS widget

PtContainerFocusPrev()

Give focus to the previous Pt_GETS_FOCUS widget

PtContainerGiveFocus() or PtGiveFocus()

Give focus to a widget -- these routines are identical.

PtContainerNullFocus()

Nullify the focus of a widget

PtGlobalFocusNext()

Give focus to next widget

PtGlobalFocusNextContainer()

Give focus to another container's widget

PtGlobalFocusNextFrom()

Give focus to the next widget behind the specified widget

PtGlobalFocusPrev()

Give focus to the previous widget

PtGlobalFocusPrevContainer()

Give focus to a widget in the previous container

PtGlobalFocusPrevFrom()

Give focus to widget previous to the specified widget

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. The order of the widgets dictates how you can use the CUA keys to move between widgets.

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 Managing Widgets in Application Code chapter.

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

• Use the Module Tree control panel. The widgets for each container are listed from back to front.

  Or:

• Use Test mode and press Tab repeatedly to check the focus order.

The easiest way to reorder the widgets is to use the Module Tree control panel -- just drag the widgets around until they're in the order you want.

You can also use the Shift-select method to reorder the widgets:

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 places the widgets in the order you selected them.

You can also select one or more widgets and then use the Raise and Lower icons to change the widget 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.

   If you want to drag the widgets horizontally, vertically, or diagonally, hold down the Alt while dragging.

   ---

   To drag a container horizontally, vertically, or diagonally, press Alt after pressing the mouse button. (Pressing Alt before the mouse button selects widgets within the container.)

   ---

3. Release the mouse button. Widgets snap to the grid if it's enabled -- see "Grid preferences" in the chapter on PhAB's environment.

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

To move the parent container of a widget, hold down Shift -Alt and drag the child.

Widgets may "disappear" if you move them beyond the boundaries of their container. If this happens, use the Previous and Next buttons in the Resources or Callbacks control panel to select the widgets, then use the X and Y fields in PhAB's toolbar to bring the widgets back into view.

If you find that you're unintentionally dragging widgets when you're just trying to select them, consider:

• Setting the damping factor, as described in "Dragging preferences," below
• Locking the widgets' coordinates and/or size in PhAB's toolbar:

  

  For more information, see "Toolbars" in the chapter on PhAB's Environment.

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 PhAB's toolbars, then press Enter. For more information, see the chapter on PhAB's environment.

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 Move Into icon in PhAB's toolbar:

     

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 any borders and margins -- displayed in the toolbar's H and W 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 PhAB's toolbars, type in a new value, then press Enter. For more information, see the chapter on PhAB's environment.

  Or:

• Use the nudge tool in the toolbar.

If a module is in Test mode, you can't resize it or its widgets. 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.

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 these 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 deletes 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 PhAB's toolbar:

     

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

     

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

     

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. For more information, see "Importing files" in the Working with Applications 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.

Changing a widget's class

You can change the class of a widget by selecting it and then choosing Change Class from the Edit menu. Choose the new class from the pop-up list, and then click the Change class button.

The resources and callbacks that are compatible with the new widget class are kept, along with their values. For example, if you decide that a PtMultitext better suits your needs than a PtButton, you can select the button, open the Change class dialog by right-clicking on the widget, or right-clicking in the Module tree or by choosing Change Class from the Edit menu. The widget's position, size, Pt_ARG_TEXT_STRING, and all the other resources common to the old and new classes are kept.

When you change a widget's class, some resources and callbacks might be deleted. Before proceeding, a dialog displays the number of resources and callbacks that will be removed. You have a chance to cancel the operation.

A container that has children (such as a PtPanel with some widgets inside it) can't be converted this way; the Change class menu item is disabled.

Templates

A template is a customized widget, group or hierarchy of widgets that you want to use as the basis for other widgets. Templates are useful when you want to create many widgets that look and behave alike. PhAB automatically loads your templates, so you can easily create instances of your widgets in any application.

For an example of creating a template, see "Editing Resources" in the Tutorials chapter.

This section includes:

• Creating templates
• Adding a custom widget
• Editing templates
• Deleting templates

Creating templates

To create a template:

1. Create and edit the widget or widgets as required.
2. With the widget(s) selected, choose Save as template from the Edit menu or from the menu that appears when you right-click on the Module Tree control panel.
3. The Save template dialog appears.

   ---

   

   ---

   The dialog for creating new templates.

4. Select the folder in which to place the new template. To replace an existing template, select the template instead of a folder.

   To create a new folder, click on the Add Folder button and enter a folder name. Each folder pops up as a palette, beside the widget palette. You can close them and later view them using the View menu; at the bottom of this menu is list of all the folders defined. When you launch PhAB, all the palettes pop up by default.

5. You must provide a name and an icon for the template.

   ---

   The Save template dialog doesn't display the icon that you create for the template.

   ---

6. Optionally, set the background color for the icon in the widget palette, and the resizing method (use original dimension or resize by dragging).
7. If the widgets that you're saving as a template have callbacks attached, you can click on the Edit Callbacks button and set the callbacks to be saved in the template. By default, all the callbacks are saved.

   When you click on the newly created template and instantiate the widget, the selected callbacks are created and added automatically. A dialog displaying the list of callbacks is displayed, and you can select the ones that you want to be added.

Adding a custom widget

If you've created a custom widget (see Building Custom Widgets) and you want to create a template for it, select any single widget in your application, open the Save as template dialog, follow the steps listed above, and click on the Create New Widget Class button.

This operation doesn't change the selected widget in any way.

A dialog lets you enter a class name (for instance, MyWidget) to be saved in the template. For the custom widget to be functional, you have to add a MyWidget section in one of the *.pal palette files.

To avoid confusion, don't start the name of a custom widget with Pt -- leave that prefix for the standard Photon widgets.

Editing templates

To edit an existing template:

1. Choose Edit Templates from the Edit menu.
2. A dialog similar to that used to create a template is displayed.
3. Edit the template as desired and then save the results.

Deleting templates

To delete a template:

1. Choose Edit Templates from the Edit menu.
2. A dialog similar to that used to create a template is displayed.
3. Choose the template folder, and click Delete.