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
• Distributing widgets vertically or horizontally
• 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 “Other Generate options” 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.

---

You must press Shift and then Alt for this method to work.

---

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.

---

PhAB uses two colors to show selected items if the Show Selection option is selected in the View menu. The colors can be customized in the Preferences dialog.

Multiple selected widgets.

In the example above, the toggle widget is not selected, it just happens to be in the same area as the selected widgets. The widget highlighted by red is the first widget in the selection. The widgets highlighted by blue are the rest of the widgets in the selection. If you use an align or match command, the first selected widget is the source widget.

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 dialog. Select Edit-->Find to open this dialog.
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 Align from the Widget 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, which is highlighted differently from the other widgets in the selection if the Show Selection option is set in the View menu. To align to another widget:

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.

Distributing widgets

You can quickly and easily distribute widgets horizontally or vertically, to evenly space them out on the GUI. To do this:

1. Select the widgets you want to distribute.
2. From the Widget menu, select Distribute-->Horizontally or Distribute-->Vertically.

In the following example, several buttons have been distributed horizontally and aligned to the top edge:

Distributed widgets.

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.

Another way to drag a widget is to hold down Shift while selecting and draging one of the widget's resize handles. This method may help when you're moving smaller widgets that are harder to select.

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 Move Into 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 and modules between PhAB instances. You can't use this clipboard with other applications. To use the clipboard, open two PhAB instances, copy or cut something into clipboard in one instance, and then paste it into the other instance.

You'll find the clipboard helpful for these reasons:

• It saves you from creating large numbers of widgets or modules from scratch.
• It helps you create applications whose widgets look and behave consistently with each other.
• You can also copy callbacks associated with copied widgets, saving you time. To include callbacks when you copy widgets, you need to set the Save/Restore Callbacks option on the General tab of the Preferences dialog.

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

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

     Or:

   • Click on the Copy icon in the toolbar:

     

---

If you want to move a widget to another container but retain its callbacks, you need to set the Save/Restore Callbacks option on the General tab of the Preferences dialog. 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 Ctrl-V.

     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 ensures that the instance name is unique. Because the clipboard state is saved between PhAB applications, you can cut widgets from one PhAB application and paste them into another.

---

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.

If you want to duplicate many widgets at once:

1. Select the widgets you want to duplicate.
2. Press and hold down Ctrl.
3. Point to one of the widgets in the selection and drag to a new position.
4. Release Ctrl and the mouse button.

---

If you duplicate a container, all its children are duplicated as well.

---

Duplicating is achieved using a copy to clipboard operation and paste from clipboard, that are done internally. Therefore the rules for clipboard operations about instance names and callback are also valid for duplicating widgets.

---

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 or modules

To permanently remove one or more selected widgets, or to delete a module:

1. Select the widgets or module.
2. Choose Delete from the Edit menu or press Delete.

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

Matching widget resources and callbacks

You can copy the resources or callbacks from one widget to one or more other widgets by using the Matching feature. This features lets you quickly and easily create several widgets with similar appearances and behavior.

To use the matching feature:

1. Select the widget that is the source for the resources or callbacks.
2. Select one or more destination widgets.

   ---

   If you enable the Show Selection option in the View menu, the widget selected first highlighted with a different color than other selected widgets.

   ---

3. Select a match command from the Widget menu:
   • Match Height — sets the height of the destination widgets to the height of the source widget.
   • Match Width — sets the width of the destination widgets to the width of the source widget.
   • Match Resources — sets all the resources of the destination widgets to the source widget's. Only the resources that are common between the destination and the source are changed; unique resources are unaffected.

     ---

     Geometry related resources — Pt_ARG_POS, Pt_ARG_DIM, Pt_ARG_AREA — are not copied.

     ---

     
     
   • Match Callbacks — sets all the callbacks of the destination widgets to the source widget's. Only the callbacks that are common between the destination and the source are changed; unique callbacks are unaffected
   • Match Advanced — displays the Match resources and callbacks dialog, which lets you choose exactly the resources and callbacks you want to copy from the source widget to the destination widgets.

Match resources and callbacks dialog.

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 Widget 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 Widget 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 be converted this way, but the list of possible new classes you can choose from is restricted to compatible container classes. For instance a PtPane with a button inside can be changed into a PtBkgd, but not into a PtList or PtTree. An empty PtTree or any other empty container can be changed into anything, including into non-container widgets. A PtTree that has a child (a PtDivider) can be changed into a container widget.

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.

You can build and save your own collection of template widgets. Templates can be customized buttons, labels, sliders, backgrounds, standard dialogs and windows. You can include callbacks in templates.

Customized templates are not any different from the standard templates in the Widgets palette. In fact, when you create a template, you save it as a personal template (visible only to you) or as a global PhAB template (visible in all PhAB instances).

---

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

---

This section includes:

• Creating templates
• Adding a widget class
• 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 Define Template from the Widget menu or from the menu that appears when you right-click on the Module Tree control panel or on the module.
3. The Define 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 Add Folder. The Setup folders dialog appears:

   

   Enter a folder name and select its type: User folder or PhAB folder. A User folder is visible only to you and cannot be shared with other PhAB users. A PhAB folder can be shared by several PhAB users. The predefined Widgets folder is a PhAB folder.

   ---

   You need to have special permissions in order to create or to change a PhAB folder.

   ---

   Each folder pops up as a palette, beside the widget palette. You can view or hide them using Window-->Show Templates; this menu contains a list of all defined templates. When you launch PhAB, all the palettes pop up by default.

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

   ---

   You can create an icon by clicking Icon Edit.

   ---

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. If the widgets you are saving don't have any callbacks attached, the Edit Callbacks button is disabled.

   You can specify whether PhAB prompts you with a list of included callbacks when you instantiate a template widget that contains callbacks. This setting is set on the General tab of the Preferences dialog under the When created widgets contain callbacks option. If you select Automatically add callbacks, all callbacks are added. If you select Ask me, PhAB prompts you with a list of callbacks that you can select from.

Adding a widget class

You can create a new widget template from scratch, without starting from an existing template. If there is no template available for a widget class (for example, if you just created a brand new widget class), then you must instantiate the widget, then create the a template from the widget instance. See the Building Custom Widgets guide for information about building a widget and creating a widget description table.

To instantiate a widget class and then create a template:

1. Select Edit-->Add Widget Class. The following dialog appears:

   

2. Enter the name of the new widget class and click Continue.

   PhAB scans the palette definition files for the widget's description table. Palette definition files (*.pal are listed in palette.def. If you have written a new *.pal file containing your widget's description table, you should add it to palette.def.

   If no widget definition is found, this dialog appears:

   

3. Once the new widget class's description table is found in one of the palette files, the following dialog is displayed:

   

4. Customize the newly created widget, customize it, and use the Save Template to save the template.

Editing templates

You can change a template definition at any time by editing the templates. To edit an existing template:

1. Choose Templates from the Edit menu.
2. The Edit Templates dialog appears.
3. Edit the template as desired and then save the results.

   You can change the template's name, the template's folder name, and the template's icon. Using drag and drop, you can move the templates between folders, and you can reorder the templates inside the same folder. Note that you can only move a template between folders of the same type (e.g. from a User folder to a User folder).

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.