Previous Next Contents Index Doc Set Home


Resources

3

3.1 Introduction

In Motif, the appearance and behavior of a widget is controlled by its resources. Resources include colors, fonts, images and text, titles, positions and sizes of windows or widgets, callbacks, and all other customizable parameters that can affect the behavior of the interface. Resources can have indirect as well as direct effects. For example, changing the label on a PushButton also changes the size of the button to allow space for the new label.

When you add a widget to the design hierarchy, WorkShop Visual sets default values for all of that widget's resources. In most cases, however, you must set some resources explicitly to make the widget useful. To make it easy to set these resources, WorkShop Visual groups resources on dialogs called resource panels.

There are two types of resource panel - "Widget" and "Core". The Widget resource panel contains resources relevant to the class of the selected widget. The Core resource panel groups together resources which apply to all classes of widget because they apply to the base classes - Core, Primitive and Manager. All widget classes are derived from the Core class and most are also derived from either the Primitive or the Manager class. The Core resource panel is described in the Core Resource Panel section on page 81.

When you generate source code for your design, you can also choose to generate an X resource file. This is a separate file containing resource settings which may be altered by the end user. See the Setting up the X Resource File section on page 228 for details on resource files and their generation. As well as allowing you to control which resources should be generated into the resource file, WorkShop Visual also provides loose and tight bindings which give you greater control over the way in which resources are assigned to the widgets in your design. This is described in the Resource Bindings section on page 89.

In this chapter, you will use resource panels to:

In addition to resource panels, WorkShop Visual offers special editors for laying out widgets in a Form, setting fonts and pixmaps, editing XmString (Motif compound string) structures and selecting colors. See Chapter 4, "The Layout Editor" for a full description of the Layout Editor, and Chapter 5, "Other Editors" for descriptions of the font, color, pixmap and compound string editors.

3.2 The Label Resource Panel

To make the tutorial interface meaningful, you must set the text of all labels and buttons to something other than the default. Begin by changing the three labels in the RowColumn widget to the text shown in Figure 3-1.

Figure  3-1 Labels Before and After Setting Text
First, bring up the resource panel for the first label:

1. Double click on the first Label under the RowColumn widget.

When you double click on the Label, WorkShop Visual displays its resource panel, as shown in Figure 3-2.

Figure  3-2 Label Resource Panel
Resource panels usually have several pages. The option menu in the top left corner of the panel is a page selector. If the "Display" page is not already selected:

2. Select the "Display" page.

Now, edit the text of the label.

3. Double-click in the text box opposite "Label".

Editing text in these boxes works in much the same way as assigning widget names. When you double-click, the first word in the box is highlighted. Triple-clicking highlights all the words in the box. Entering new text replaces the highlighted text.

4. Type: Topping 1:

Note - Do not press <Return>. Labels can contain multiple lines and pressing <Return> inserts a newline character into your label. If you unintentionally press <Return>, you can backspace to remove the newline.

5. Click on the "Apply" button at the bottom of the resource panel.

The "Apply" command sets the new resource value. When you click on "Apply", the dynamic display shows the new label text.

Note - If your locale is not the default "C" and you are using international text in your labels, the text will not appear correctly until you have set up the fontlist resource required for your particular language. See the Setting the Application Font Resource section on page 599 for more information. See Chapter 18, "Internationalization" if you are not sure whether this applies to you.

3.2.1 Regions of the Resource Panel

Although different classes of widgets have different resource panels, all resource panels have the same basic structure.

Annotations

As you change resources, a change bar appears at the far right of the resource panel, as shown next to the "Label" resource in Figure 3-3.

Figure  3-3 Annotated Resources
After pressing "Apply", the change bar alters in appearance to that shown next to the "Font" resource in Figure 3-3.

The tick and cross symbols shown in Figure 3-3 will only appear when running in Microsoft Windows mode. The tick indicates that the resource is applicable to Microsoft Windows and the cross indicates that it is not. This is explained more fully in the Widgets and Resources section on page 333.

Resource Names

Resource names are shown on the left of a resource panel. Sometimes these names are simply labels and sometimes they are buttons which, when pressed, display a dialog relevant to the resource type. In Figure 3-2 above, all the resource names are buttons. Any resources that do not apply to the selected widget are grayed out.

Resource Values

Current resource values are shown in the boxes on the right. These boxes are either single-line text fields, multi-line text boxes or menu options. You can edit resource settings by typing into these boxes or selecting from an option menu. Default values are shown in parentheses.

Masking Toggles

The unlabeled toggle to the left of each resource name is the resource masking toggle which can be used at the code generation stage to mask resources in or out of the X resource file. This topic is discussed in the Masking Resources section on page 235. You do not have to set these toggles in order to set resource values.

3.2.2 Page Selector and Toggle Switches

The main section of the resource panel usually has several pages. The option menu at the top of the panel is a page selector which lets you move from one page to another. The Label panel also has a toggle switch which can be used to designate this widget as a gadget. The widget-gadget toggle appears in the resource panels for other widget classes if the widget class has a gadget counterpart. Some widget classes also have other toggle switches appropriate to the class.

3.2.3 General Commands: Apply

The four buttons at the bottom of the panel offer general commands. "Apply" causes your new resource settings to take effect. If you do not click "Apply", your edited settings are lost when you select another widget or close the resource panel.

3.2.4 Undo, Close, Help

"Undo" makes all edited settings revert to the last applied settings. "Close" makes the resource panel disappear. "Help" displays the appropriate help screen.

Note that in Figure 3-3, the "Apply" button is highlighted. Pressing <Return> when a resource panel has the input focus generally executes the highlighted command. However, <Return> does not work in this way when you type into a multi-line text box, because the text box accepts <Return> as a newline character.

Now set the text of the other two Label widgets. You do not have to close the Label resource panel. However, you may need to move it if it covers the construction area.

1. Select the second Label widget.

Note that the "Label" resource on the panel changes to reflect the current setting of the newly selected widget.

2. Double-click in the "Label" box in the resource panel to highlight the default label.

Additional ways to edit in text boxes include: dragging with the mouse to highlight text, using <Delete> to delete highlighted text, or just typing at the current cursor location.

3. Type: Topping 2:

4. Click on "Apply".

5. Repeat Steps 1 through 4 for the third Label, using the text: Topping 3:

6. Click on "Close".

"Close" makes the resource panel disappear.

3.3 Multiple Selection and Resources

If you have more than one widget selected you can still set resources - in both the core and widget resource panels. In this case you will only be able to set those resources which are relevant to all the selected widgets. WorkShop Visual decides which resources are relevant by finding a widget class which is common to all the selected widgets. In the case of widgets which are very different, for example a Button and a MenuBar, the only class they have in common is the low-level Core widget class. In such a case, you would only be able to change Core resources.

3.4 Resource Panels in Microsoft Windows Mode

When WorkShop Visual is running in Microsoft Windows mode, it makes sure that the design you are creating is Microsoft Windows compliant. Motif resources do not map directly to Microsoft Windows resources. Some resources can be translated into something similar on Microsoft Windows (which may not necessarily be a resource), some cannot.

Resources are marked in the resource panels, according to their relevance to Microsoft Windows, in two ways:

Resources which are not applicable to Microsoft Windows have their fields colored pink in the resource panel. You can still enter values into these fields and they will be generated for Motif, but nothing will be generated for Microsoft Windows. You can change the color of these non-Microsoft Windows resource fields by changing an entry in the WorkShop Visual application resource file. See the Setting the Color of non Microsoft Windows Resource Fields section on page 352 for details on how to do this.

3.5 Button Widget Resources

Use the same procedure as that used for the Label widgets to set the labels of ToggleButtons, CascadeButtons and PushButtons. Set labels for the ToggleButtons in the work area as shown in Figure 3-4.

Figure  3-4 ToggleButtons Before and After Setting Labels

1. Double click on the first ToggleButton to bring up its resource panel.

You can also bring up the selected widget's resource panel by selecting the "Resources" item in the "Widget" Menu, by pressing the Resources toolbar icon or by pressing <Return> when the widget has the input focus in the construction area.

2. Click twice in the "Label" box and type: Vanilla

3. Click on "Apply".

4. Select the second ToggleButton.

5. Click twice in the "Label" box and type: Chocolate

6. Click on "Apply".

7. Select the third ToggleButton.

8. Click twice in the "Label" box and type: Strawberry

9. Click on "Apply".

3.6 Shared Resource Panels

Notice that the resource panel for a ToggleButton looks the same as for a Label. This is because, in Motif, the ToggleButton widget class is derived from the Label class. Another way of saying this is that the ToggleButton is a specialized kind of Label, also called a subclass of Label. The Label is the ToggleButton's superclass.

3.6.1 Widget Class Inheritance

The ToggleButton class inherits most of its characteristics, including most of its resources, from the Label class. By means of inheritance, all Motif widget classes are organized in a hierarchy known as the class hierarchy. The class hierarchy is an abstract hierarchy of available widget classes and should not be confused with the design hierarchy you are building on the screen.

Several types of buttons - ToggleButtons, PushButtons, CascadeButtons and DrawnButtons - are derived from the Label class. You can set the text of all widgets of these classes using the same resource panel without having to close and re-open it.

Set labels for the radio buttons (the ToggleButtons in the RadioBox) as shown in Figure 3-5.

Figure  3-5 Radio Buttons Before and After Setting Labels

1. Double click on the first radio button to bring up its resource panel.

2. Click twice in the "Label" box and type: Large

3. Click on "Apply".

4. Select the second radio button.

5. Click twice in the "Label" box and type: Small

6. Click on "Apply".

If you assign a label to the radio button which is longer than the default label, the Frame widget changes size to accommodate the new width. This represents a chain reaction: the ToggleButtons resize to accommodate longer text strings, then their RadioBox parent and its Frame parent resize to fit in turn. Motif does all this automatically. This behavior is not obvious in the tutorial layout but it is illustrated in Figure 3-6.

Figure  3-6 Radio Buttons With Longer Labels
Use the same Label resource panel to set the label resources of the CascadeButtons as shown in Figure 3-7.

Figure  3-7 Menu Bar Before and After Setting CascadeButton Labels

7. Select the first CascadeButton and assign it the label: Procedures

8. Select the second CascadeButton and assign it the label: Help

Finally, set the labels of the three PushButtons in the button box, as shown in Figure 3-8. PushButtons also resize automatically to accommodate their labels.

Figure  3-8 Button Box Before and After Setting Resources

9. Select the first PushButton and assign it the label: Cone

10. Select the second PushButton and assign it the label: Dish

11. Select the third PushButton and assign it the label: Cancel

3.6.2 Tip

Remember to click on "Apply" after setting resources, or your new settings will have no effect. If you do not apply your new settings before selecting another widget, WorkShop Visual displays the warning shown in Figure 3-9.

Figure  3-9 Warning that New Resources Were Not Applied
Click "Cancel" on this display to return to the resource panel.

3.7 Resources for Menu Items

Next, set resources for the buttons in the pulldown menus of the menu bar. So far you have set only the CascadeButton labels and the pulldown menus look like Figure 3-10.

Figure  3-10 Pulldown Menus After Setting CascadeButton Labels

1. Select the first PushButton child of the first Menu widget.

2. Change the "Label" resource to: Wash Dishes...

By convention, the ellipsis (...) is used to indicate that a menu item brings up an additional dialog box before the command is executed.

3. Select the second PushButton and assign it the label: Count Money

4. Select the third PushButton and assign it the label: Exit

5. Select the PushButton child of the second Menu widget.

6. Assign it the label: About This Layout...

The pulldown menus now look like Figure 3-11.

Figure  3-11 Pulldown Menus After Setting PushButton Labels
In the following sections, you will:

3.8 The Keyboard Page

Accelerators and mnemonics are keyboard resources which are found on a separate page of the Label resource panel. Use the following steps to set an "H" mnemonic on the "Help" CascadeButton:

1. Select the "Help" CascadeButton.

2. Select "Keyboard" from the resource panel's page selector.

This brings up the "Keyboard" page, shown in Figure 3-12. The resources that are not grayed out are the ones which apply to the CascadeButton class.

Figure  3-12 Keyboard Resources for the CascadeButton

3.8.1 Mnemonics

WorkShop Visual lets you set keyboard mnemonics which work like those in the WorkShop Visual interface. A mnemonic can be any character, even one which is not in the label. It is easiest for the end user if you use a character which appears in the label, preferably the first character. Mnemonics must be unique within a menu bar or menu.

1. Double-click in the "Mnemonic" box.

2. Type: H

3. Click on "Apply".

4. Select the PushButton child of the "Help" menu.

5. Double-click in the "Mnemonic" box.

6. Type: A

7. Click on "Apply".

Note that the "H" and "A" characters now appear underscored, which is Motif's way of indicating a mnemonic. This lets the user invoke the "About This Layout" command in two ways: with the mouse, or by pressing <Meta-H>, <A>.

3.8.2 Accelerators

Now add the keyboard accelerator for the Exit button. As in WorkShop Visual, an accelerator immediately executes a menu command, whether or not the menu is displayed.

1. Select the "Exit" button (the third PushButton under the first pulldown Menu).

2. Double-click in the "Accelerator" box.

3. Type the text string: Ctrl<Key>E

4. Click on "Apply".

These steps make the accelerator active. When the interface is running, <Ctrl-E> will have the same effect as the "Exit" button. The exact syntax of the accelerator is important. If a syntax error occurs, WorkShop Visual displays the error message shown in Figure 3-13 when you try to apply.

Figure  3-13 Accelerator Syntax Error Message
Accelerator syntax is the same as that used for translation tables. This topic is discussed in the Translations and Actions section on page 208.

3.8.3 Accelerator Text

A related resource is accelerator text. This resource displays extra text to the right of a menu option to remind the user of its accelerator. Since accelerator text is just a display convenience, you do not have to use any particular syntax. "Control+E", "Ctrl-E" and "^E" are some common forms.

1. Double-click in the "Accelerator Text" box.

2. Type the text string: Control+E

3. Click on "Apply".

When you pull down the left menu, you now see the new labels on all the buttons and the designated accelerator text on the Exit button, as shown in Figure 3-14.

Figure  3-14 Pulldown Menus After Setting Resources

4. Click on "Close".

3.9 Designated Help Widget

The Motif Style Guide suggests designating one CascadeButton child of the MenuBar as the Help widget. The Help widget always appears at the right end of the menu bar.

1. Double click on the MenuBar to bring up its resource panel.

The MenuBar is a specially configured RowColumn and shares its resources. The resources that are not grayed out apply to the MenuBar.

2. Select the "Display" page if not already selected.

To designate a Help widget:

3. Click in the "Help widget" field and type: help_cascade

Figure  3-15 Display Resources for the MenuBar

4. Click "Apply".

The Help widget must be one of the CascadeButtons in the menu bar. You must type the CascadeButton's variable name exactly. If you make a mistake, WorkShop Visual does not accept the entry.

The dynamic display does not show this change automatically. To see the effect of designating the Help widget, resize the dynamic display.

Leave the MenuBar resource panel open.

3.10 RowColumn Resources

By default, the RowColumn widget has one vertical column. Its resources can be set to change it from this default state to an arrangement of three horizontal rows, as shown in Figure 3-16.

Figure  3-16 RowColumn Array, Before and After Setting Explicit Resources
To achieve the result shown in Figure 3-16, you must also set the size of the TextFields.

1. Select the three TextField widgets in the hierarchy.

You can do this either by dragging a rectangle around the widgets or by selecting one widget and then holding down the Shift key while selecting the other two.

Note that when you select a TextField widget, the MenuBar resource panel, which is still present on the screen, becomes inactive. Its "Apply" button is grayed out and if you try to type into its text fields, your machine beeps. The panel becomes active again whenever a widget of the same base class (RowColumn) is selected.

2. Bring up the TextField resource panel and select the "Display" page.

Invoke the resource panel by double-clicking over one of the TextFields, selecting "Resources" from the "Widget" menu or pressing the Resources toolbar icon.

The TextField is a variant of the Text widget and shares many of its resources. The distinction is that Text widgets can contain multiple lines of text, while TextFields are limited to a single line. Because these classes have no gadget counterparts, this resource panel has no widget-gadget toggle. There is, however, a toggle to change the widget from TextField to Text. This toggle lets you change from one variant of the Text widget to the other without disturbing your hierarchy or resource settings.

Figure  3-17 "Display" Page of TextField Resource Panel
We want to make the text field boxes narrower. The size of the text field boxes is determined by two factors: the TextField's "Columns" resource and the rules imposed by its RowColumn parent. Begin by setting the "Columns" resource to a smaller number:

3. Double-click in the "Columns" box.

4. Type: 8

5. Click on "Apply".

The TextFields are now narrower.

The "Columns" resource of a TextField or Text widget only affects the size of the box and not the number of characters the user can enter. If you want to limit input to a specific number of characters, set the "Maximum length" which defaults to a very large number.

3.10.1 The RowColumn Resource Panel

To get the layout of three horizontal rows, you need to set the resources of the RowColumn.

1. Select the RowColumn widget in the construction area.

If you already have the MenuBar resource panel up on your screen, it becomes active again although its title is changed to "RowColumn". If it is not on the screen, display it by double-clicking on the RowColumn again.

2. Select the "Settings" page.

Figure  3-18 "Settings" Page of RowColumn Resource Panel
The "Settings" page, shown in Figure 3-18, lists resources that have a limited number of possible settings. Therefore, it has option menus instead of text fields in its right column.

3. In the "Orientation" option menu, select "Horizontal".

4. In the "Packing" option menu, select "Column".

"Horizontal" orientation lays the RowColumn out in rows rather than columns. "Column" packing is necessary if the RowColumn is to have more than one row or column. To see the effect of these two resources:

5. Click on "Apply".

At this point, the RowColumn appears in a horizontal row, with all the cells the same size. When "Orientation" is "Horizontal", the sense of rows and columns is reversed. Therefore, to make three rows you must set the "Columns" resource.

6. Select the "Display" page.

7. Double-click in the "Columns" box and type: 3

8. Click on "Apply".

The result is shown in Figure 3-19.

Figure  3-19 RowColumn Portion of the Dialog with Horizontal Orientation

3.11 Shell Resources

The Shell widget exists primarily as an interface between your application and the X window system. Its behavior is mainly controlled by the window manager and by the widgets it contains. However, it does have a few interesting resources of its own.

1. Double click on the Shell widget, myFirstShell, to bring up its resource panel.

At the top of this panel is a toggle switch which sets the type of Shell widget.

3.11.1 Shell Types

Although every window starts with a Shell widget, there are different types of windows and different types of Shell widgets. WorkShop Visual provides the following Shell widgets:

Note - The behavior described above applies to mwm. With twm, although Shell behavior is the same, it looks different because twm can turn Dialog Shells into pseudo-icons to reduce their size. The pseudo-icons are just a visual convenience for cleaning up your display. Internally, they are distinguished from true icons and they look different on your screen.
All windows in the design close when the Application Shell is closed.

Examples of Shell Types in the WorkShop Visual Interface

To see some possible uses of different Shell types, look at the WorkShop Visual interface itself. The main screen with the widget palette and construction area is the Application Shell. Dialogs, resource panels and the Layout Editor screen are all Dialog Shells. You cannot iconify these windows separately using the window manager.

To remove them from the display, you must close them, either using the window manager or by clicking on a "Close" button, which closes the window internally via an "Activate" callback. All open Dialog Shells disappear when the main window is iconified and reappear when it is restored.

The "Palette Icons" help panel is an example of a Top Level Shell. While it does not come up automatically when WorkShop Visual starts, it can still be iconified independently once you have displayed it. Its popup subwindows, like all Dialog Shells, are children of the main Application Shell and do not close or iconify with the "Palette Icons" help panel.

Shell Type in the Dynamic Display

The Shell type is not reflected in the dynamic display. All windows created for dynamic display are really Dialog Shells and cannot be iconified independently. You can configure WorkShop Visual to use Top Level shells rather than Dialog Shells - see Appendix A, "Application Defaults" for details. The generated code creates the type of Shell you specify for each window at run time.

Application Shell Requirement

You should designate at least one Shell in each design as the Application Shell. If you have no Application Shell in your design, the application will not display any windows. WorkShop Visual shows you a warning message at code generation time if you do not have an Application Shell.

You can have more than one Application Shell in your design. In this case, the main() program generated by WorkShop Visual creates all the Application Shells but displays only one of them. WorkShop Visual cannot tell which one you want displayed first. If you have more than one Application Shell in your design, you may have to write your own main() program or edit the generated one to start with the correct Application Shell. To get similar results without ambiguity, use only one Application Shell for your first window, use Top Level Shells for other primary windows and use callbacks or links to display all windows but the first. Using more than one Application Shell is not recommended.

Every application must have at least one (and usually only one) Application Shell which serves as the main window and as the interface of the application to the X window system.

Subsidiary windows can be either Dialog Shells or Top level Shells. This distinction is explained more fully in the Shell Types section on page 75.

3.11.2 Setting Resources for the Main Shell

The main Shell in your design, myFirstShell, must be an Application Shell. Therefore:

1. Bring up the Shell`s resource panel, if it is not already displayed.

2. Click on the "Application shell" toggle.

You can also set the main dialog title on this resource panel. To do this:

3. Select the "Display" page.

4. Double-click in the "Title" box and type: Ice Cream Shop

Figure  3-20 "Display" Page of the Dialog (Shell) Resource Panel

5. Click on "Apply".

6. Click on "Close".

The layout now looks like Figure 3-21.

Figure  3-21 Tutorial Interface So Far

3.11.3 Setting Resources for the Secondary Window

In your application, you have another Shell for the Help window. This Shell should be a Dialog Shell.

To view its resource panel:

1. Double click on the Shell for the Help window.

If the "Dialog shell" toggle at the top of the Resource Panel is not already set:

2. Click on the "Dialog shell" toggle.

You can also change the title on this Resource Panel.

3. Select the "Display" page.

4. Double-click in the "Title" box and type: Help

5. Click on "Apply".

6. Click on "Close".

3.12 Navigating in the Resource Panels

Because Motif has so many resources, WorkShop Visual uses multiple-page resource panels to display them on the screen. You may find it useful to refer to Chapter 22, "Widget Reference", starting on page 653 while you are becoming familiar with the structure of the resource panels. That chapter has a list of resources by widget class and page.

Some resources that are not available on the resource panel of a specific widget class can be found on the Core resource panel, which is discussed in the Core Resource Panel section on page 81.

3.12.1 Settings

In general, any multiple-choice resource - one with a limited number of settings - is found on the "Settings" page, where you can set it with an option menu. All other resources that require you to type in a new value or call an additional dialog to set the new value are divided among the other pages. Except for the "Settings" page, resources are organized loosely by topic.

3.12.2 Display, Margins

Resources that affect the widget's appearance are generally found on the "Display" page. These resources include text, colors, fonts and dimensions. The Core resource panel also includes some resources that affect the dimensions and the location of the widget.

Labels and Label derivatives have enough display resources to require a second page. The Label resource panel divides these resources into a "Display" page, containing color, font, text and pixmap resources, and a "Margins" page, containing size and margin width resources.

3.12.3 Keyboard

The "Keyboard" page lets you set keyboard mnemonics and accelerators for widgets that can have them.

3.13 Core Resource Panel

WorkShop Visual gives you access to resources for these broad superclasses via a single resource panel, the Core resource panel. To bring up the Core resource panel for a specific widget:

1. Select a widget.

2. Pull down the Widget Menu and select "Core resources...".

A page from the Core resource panel is shown in Figure 3-22.

Figure  3-22 "Display" Page of the Core Resource Panel

3.13.1 Display Page of the Core Resource Panel

The "Display" page of the Core resource panel has basic color and pixmap resources. For example, you can set the colors for the widget's foreground, background, highlighting and shadows. You will do this in Chapter 5, "Other Editors".

3.13.2 Dimensions Page of the Core Resource Panel

The "Dimensions" page offers resources that affect the widget's size and location on the screen. Class-specific dimension resources may override the settings on the Core panel. You may want to experiment with the effects of setting "Shadow thickness" on a TextField or "Highlight thickness" on a PushButton.

3.13.3 Settings Page of the Core Resource Panel

The "Settings" page offers miscellaneous multiple-choice settings which apply to most widget classes. This page also allows you to change the "Map when managed" setting, which works in conjunction with the managed toggle, described below.

3.13.4 Code Generation Page of the Core Resource Panel

The "Code Generation" page gives you increased control over the generation of code. For example, you can designate a specific widget as static, local, or global. See the Accessing Widgets in Callbacks section on page 196 for a reason to change a widget`s access. If you are using C++, you can also designate it as private, protected, or public. The Widget Member Access Control section on page 294 discusses C++ access. The "Code Generation" page also allows you to create your own derived C++ classes. This subject is described in detail in the C++ Classes section on page 268.

Managed Toggle

The managed toggle also appears on the "Code Generation" page. By default all widgets are generated as managed, with the exception of the "Apply" button in a SelectionBox that is not a child of a Dialog Shell. This state can be modified using the "Managed" toggle in the "Code generation" page of the Core resource panel. Usually this just means that the code to manage the widget is omitted from the generated code. For widgets or gadgets that are components of composite widgets, the generated code explicitly unmanages the widget if the toggle is off, since the toolkit always creates these widgets as managed. For the "Apply" button of a Selection Box, code to explicitly manage the button is generated if the toggle is on. See the Manipulating Widgets section on page 197 for more information on widget manipulation.

Include in Resource Bindings Toggle

The toggle labelled "Include in Resource Bindings" refers to the generation of resources for the selected widget. This is explained in full in the Tight Bindings section on page 98.

3.13.5 Drop Site Page of the Core Resource Panel

This is where you can specify a drop site. A drop site is a widget that is prepared to receive certain types of data from other widgets by means of the drag and drop mechanism introduced in Motif 1.2. Drag and drop allows you to pass information between widgets by selecting the data and dragging it using the mouse.

The initialization of a drag is a dynamic function that would normally be done from within a callback or action function. WorkShop Visual provides simple support for the reception of a drop but not for the source of a drag.

For details on how to set up a widget as a drop site, see the Drag and Drop section on page 205.

Figure  3-23 The Drop Site Page

3.14 Constraints Panel

Motif has two classes of widget, the PanedWindow and the Form, which are called constraint widgets. Widgets of these classes have a special set of resources, called constraint resources, that control the size and position of their children. A constraint widget maintains a separate set of constraints for each of its children. WorkShop Visual lets you set them as if they were resources of the children.

To view constraint resources for any child of a constraint widget:

1. Select a child of a contraint widget.

2. Pull down the Widget Menu and select "Constraints...".

Figure  3-24 Constraints Panel
Figure 3-24 shows the default constraints resource panel for the Frame child of the Form in the tutorial layout. This panel shows that the Frame's top is attached to the top of the Form and its left side is attached to the left side of the Form, with an offset of 0 pixels. This is why it is located at the upper left corner of the Form. The bottom and right side of the Frame are unconstrained.

The constraints resources which the Form imposes on its children interact in complex ways and the preferred way of setting them is by using the interactive Layout Editor, which is discussed in Chapter 4, "The Layout Editor". The constraints resource panel is mainly useful for viewing the constraints which have been set, as an adjunct to the Layout Editor. Advanced users may want to set values on the panel itself. This can be done as with any other resource panel, by typing in the new value and clicking on "Apply".

The constraints resource panel for children of the PanedWindow displays a different set of values. This panel is discussed in the section on the PanedWindow in Chapter 22, "Widget Reference", starting on page 653.

3.15 Default Resource Settings

You may have noticed that WorkShop Visual displays default resource settings in parentheses. Default settings are different from explicit settings, even if the values are the same when you build the interface. The difference is that default settings are not added to the generated code or X resource files. If your interface uses default settings, and is then run on a machine other than the one used to design it, it will use the Motif defaults for the machine on which it is running.

Many resources, such as the label on a PushButton or the number of columns in a RowColumn, are unlikely to cause portability problems. Others, such as dimensions and colors, are machine-specific. To make your interface portable, you must either use default values for such resources or put them into an X resource file at the time of code generation so they can be edited for each machine. This is discussed in the Setting up the X Resource File section on page 228.

Figure 3-25 shows a resource panel with some resources which have been explicitly set either in the current WorkShop Visual session or in a previous one. The explicit settings are those marked with a change bar.

Figure  3-25 Resource Panel with Explicitly Set Resources
To revert to the default setting for a resource for which you have entered an explicit setting:

1. Delete all text in the resource's text field on the resource panel.

2. Click on "Apply".

To select the default value for a resource on the "Settings" page:

3. Select the option displayed in parentheses from that option menu.

4. Click on "Apply".

Note - The default value in this case will be the value currently being used in the dynamic display (i.e. the last value assigned to the resource). When the application is run outside of WorkShop Visual the system default will be used. To see the system default in WorkShop Visual, you will need to reset the widget.

3.16 The Reset Command

When you set any resource, WorkShop Visual tries to apply that value to the selected widget in your dynamic display. Note that what you see in the dynamic display is a collection of widget instances. WorkShop Visual does not draw pictures of widgets but actually creates them, using the same Motif function calls which your interface will use when it is running. When WorkShop Visual sets a resource, it makes the appropriate Motif function call to set that resource's value for that widget.

Usually, the result of setting a value is the same as creating the widget with that value in the first place. However, this is not always the case. WorkShop Visual has a command on the Widget Menu, "Reset" (<Ctrl-T>), which destroys the selected widget and its children and recreates them with the most recently applied resource settings. If your layout does not look or behave as expected, try using the "Reset" command. The following steps demonstrate a case where "Reset" is required:

1. Double click on the "Help" CascadeButton widget in the hierarchy to bring up its resource panel.

2. Select the "Keyboard" page.

3. Remove your previously set mnemonic by deleting all text from the "Mnemonic" text field.

4. Click on "Apply".

Notice at this point that the "Mnemonic" text field reverts to the <Default> setting. However, the "Help" button in the dynamic display still has an underscore under the "H", indicating a mnemonic which is no longer present. To update the display:

5. Select "Reset" from the Widget Menu.

Resetting only affects the selected widget and its children. Resetting a widget that is low in the hierarchy may leave inaccuracies elsewhere in the dynamic display. If you set many resources, it is wise to reset the Shell to guarantee that what you see is what you get.

The "Reset" command is particularly useful when using the Form widget and its attachment resources. This topic is discussed in Chapter 4, "The Layout Editor".

6. Reinstate the mnemonic.

3.17 Rejected Resource Settings

Motif and other widget toolkits have rules which control legal settings of resources and, since WorkShop Visual works with real instances of widgets and not simulations, any new resource setting that does not satisfy these rules is rejected. The rules include valid values for the particular widget, requirements of a parent widget such as a RowColumn and requirements of the machine you are using to build your design.

For example, if you are designing an interface for use on a large-screen workstation, you might want to set a dimension resource to a large number of pixels. If you are designing on a smaller-screen machine, you may find you cannot set the value you want even though the interface will run on the large-screen machine later. (In this situation, you could still set the width you want by using an X resource file.)

When Motif rejects a new resource setting, it does not revert to the previous setting but calculates a new value based on defaults and other resource settings in the hierarchy. This new value is reflected on the resource panel and in your dynamic display.

3.18 Resource Bindings

Previously in this chapter you have seen how to set resources for individual widgets. The Setting up the X Resource File section on page 228 describes how WorkShop Visual can generate a resource file which contains all the resources you have set in the design.

The way resources and widgets are tied together is often referred to as a binding. One line is generated for each resource which has been explicitly set and which you have asked to be generated into a resource file. See the Resource File Syntax section on page 249 for a description of the format of resource files. The Code Generation Options section on page 232 shows how you can tell WorkShop Visual which resources to generate into the resource file.

There are two methods of setting resources in WorkShop Visual:

1. Setting resources on individual widgets in the resource panel

2. Using loose bindings

Which method you choose depends on the number of widgets you wish to use a resource. In large designs you may want all widgets of a particular class to look the same (all buttons to be green, for example). Loose bindings provide the means of doing this. Resources which apply to individual resources should be set using the resource panel.

Tight bindings are a way of avoiding conflicts in an application's resource file. This is explained in more detail in the Tight Bindings section on page 98.

3.19 Loose Bindings

Setting a loose binding lets you specify a default resource that will be used if no explicit resource has been set. The loose bindings dialog allows a lot of flexibility because widgets can be referred to by their widget name, their class name or even by a wildcard indicating that any widget fitting the description is applicable. You can also specify how general to make the binding. This is explained in more detail in the example below. Loose bindings are useful if, for example:

You can achieve this by setting up loose bindings. This can be explained with a simple example.

3.19.1 Example Loose Binding

1. Create a widget hierarchy containing a Shell, a Form, another Form and three PushButtons, as shown in Figure 3-26.

Figure  3-26 Hierarchy for Loose Bindings

2. Name the Shell "MyShell" and one of the Forms "MyForm", as shown.

For resources, the widget name is the name that will be used. Setting the variable name, however, automatically sets the widget name using the same name.

3. Select the Shell, the Form named MyForm and the first Button.

Select one and then hold the Shift key down while selecting the others.

4. Select "Loose bindings" from the "Widget" menu.

The Loose Bindings dialog appears.

Figure  3-27 Loose Bindings Dialog

3.19.2 Loose Bindings Dialog

The Loose Bindings Dialog, shown in Figure 3-27, consists of the following areas:

Menubar

This contains three menus: "File", "Edit" and "Options". The "File" menu contains commands to Load, Merge and Inherit bindings from external resource files. These operations are described in more detail in the Resources from External Resource Files section on page 95. The "Edit" menu allows you to delete bindings as well as cut, copy and paste them. The cut and paste mechanism is important because the order of the bindings in the list is the order they are generated. The order of resources in the resource file is significant because the file is read in order by the X toolkit. If there are any conflicting resources, the later resources override previous ones. The "Options" menu contains one option "Use Inherited Bindings" which allows you to decide whether or not to use any inherited bindings which appear in your loose bindings list. This toggle is set by default.

Currently Defined Bindings

At the top of the window is the list of currently defined loose bindings. Beneath the list there is an up and a down arrow button. Use these to change the order of the bindings in the list. The order in which the bindings appear in this list is the order they are generated into the resource file.

Binding Under Construction

Underneath the list of existing bindings there is a scrolling window of option menus representing a binding for the selected widgets in the widget hierarchy.

Resource Name and Value

Beneath the representation of the binding there are two text boxes - one for the name of the resource and one for its value.

Resource Panels

At the bottom of the dialog there are buttons to bring up the core and widget resource panels. The resource panels relate to the bottommost widget that you have selected in the widget hierarchy (also known as the leaf widget). There is also a button to "Add" the binding to the list of those currently defined.

3.19.3 Creating the Binding

To continue with our example:

1. Change the option menus in the Loose Bindings dialog so that they appear as in Figure 3-28.

This shows a binding which refers to the Shell and one of the Forms by name but to the button by its Motif class name. This means that the binding refers to all the buttons below the named Form. In between each widget, we have selected the asterisk (*), to indicate that there can be other widgets between the named ones. The other Form is included in this way.

Figure  3-28 Widget Options for Loose Bindings

2. Press "Widget Resources".

The Button widget resource panel is displayed.

3. Set the Label resource to: Bound. Press "Apply" and close the resource panel.

The "Resource Name" text box now contains the text "labelString" which is the name for the Label resource recognized by X Windows. The "Resource value" text box contains the text "Bound" which is the value you typed into the resource panel.

4. Press "Apply".

The following line is added to the loose bindings list:

XApplication*MyShell*MyForm.XmPushButton.labelString: Bound
When you next generate a resource file this will appear in it. In plain English this means:

All Push Button widgets which are children of Forms named "MyForm" which are descendants of Shells named "MyShell" (with any number of widgets in between) which are in an application of class "XApplication" will have their Label set to "Bound".

3.19.4 Resources from External Resource Files

The Loose Bindings dialog "File" menu contains three items:

Selecting either "Load" or "Merge" produces a File Selection Box prompting you for the name of a resource file. Selecting "Inherit Bindings" from the "File" menu displays the "Inherit Bindings" dialog.

Inherit Bindings Dialog

The Inherit Bindings dialog contains two areas: a text box and button allowing you to specify the name of the resource file from which to inherit bindings and a list of bindings from the last specified file. This is a read-only list. Pressing the button labelled "Resource Binding" displays a File Selection Box where you can locate a resource file.

In order to inherit the bindings displayed in this dialog, set the "Use Inherited Bindings" toggle in the "Options" dialog.

When you next generate a resource file, if the toggle button in the "Options" menu is set, a reference to the named resource file is generated. This, in effect, inherits all the resources listed in the Inherit Bindings dialog. You can unset the "Inherited Loose Bindings" toggle if you no longer wish to inherit resources. If you unset the toggle button, no resource bindings are inherited.

3.19.5 Refining the Binding

The example illustrated in the Example Loose Binding section on page 91 is a simple one. You have more ways of altering the resource binding in the Loose Bindings Dialog. Each element in the binding currently being defined can be altered by means of the corresponding option menu, as shown in Figure 3-29.

Figure  3-29 Current Binding with Corresponding Buttons
You can refine the binding using these option menus. There are three types of refinement that can be made:

These are described below.

Wildcard

In between each widget name there is a wildcard character. This can be either a period (.) or an asterisk (*). Period means that the widget on the right is a direct descendant of the widget on the left. Asterisk means that there can be any number of other, unnamed widgets in between the widget on the left and the right.

Widget Reference

There are three ways of referring to widgets. You can select the Motif class name (e.g. XmPushButton for buttons, XmForm for Forms etc.), the widget name you have specified or a question mark character (?). The question mark is a wildcard meaning that there must be a widget at this point in the description but that it can be any widget.

Resource

The last item in the binding currently being defined is the resource and its value. If you have set more than one resource for this binding they are listed in the corresponding option menu. You can set a loose binding for any number of resources.

Note - If the name of a widget is changed loose bindings will not be re-applied to that widget until a reset is performed.

3.20 Tight Bindings

The default resource bindings that WorkShop Visual generates could lead to ambiguities if more than one widget has the same widget name within the same application class. Tight bindings are a means of naming extra widgets in a resource binding in order to lessen the possibility of ambiguity. The Resource File Syntax section on page 249 describes the structure of resource bindings as present in the resource file. The default resource binding generated by WorkShop Visual for the hierarchy shown in Figure 3-30 is:

Figure  3-30 First Hierarchy
This example mentions only one widget explicitly, the leaf widget, whose widget name is "OkButton".

Note - The variable name for this widget has not been set. In resource files it is the widget name which is important.
In an application you may find that you have more than one leaf widget with the same widget name. If, however, the widgets need different resources the default resource syntax described above would not be useful since it refers to all of them. Some resource settings would then be lost. The more widgets that are named in the resource binding, the less possibility of there being a conflict over widget names in the resource file.

3.20.1 Example Tight Binding

Using the example above, the following shows how you can still have more than one leaf widget (in this case a PushButton) with the same name but with different labels.

1. Create the hierarchy shown in Figure 3-30, making sure that you have used the names shown for the widget names.

2. Select another Shell from the palette and create a second hierarchy as shown in Figure 3-31. Give the button the widget name "OkButton", the same widget name as the button in the first hierarchy.

Figure  3-31 Second Hierarchy

3. Specify the label: Ok for the button in the first hierarchy

4. Specify the label: Apply for the button in the second hierarchy

5. Select the widget FirstShell in the first hierarchy and bring up its core resource panel

6. Select the "Code Generation" page

7. Set the toggle labelled "Include in Resource Bindings"

This is the toggle which makes a widget's resource bindings "tight".

8. Press "Apply"

When the resource file is next generated, the widget with the tight resource binding will appear as follows:

XApplication*FirstShell*OkButton.labelString: Ok

9. Now do the same for the second hierarchy, including the widget SecondShell in the resource binding.

The binding for the second hierarchy looks like this:

XApplication*SecondShell*OkButton.labelString: Apply
Resources for the two buttons with the same widget name are now easily distinguished. You can add any number of widgets into the resource binding (in this example we could have added the Form as well). This would make the binding tighter and less open to ambiguity.

3.20.2 Tight Resource Binding Recommendation

It is recommended that you set the "Include in Resource Bindings" toggle on all Shells in your design. This will not cause any unwanted effects and will prevent most ambiguities.

3.21 Comparison of Resource Generation

If you explicitly set the Label resource of the first button in the loose bindings example shown in Figure 3-26, but you do not set a loose binding, the following line is generated into the resource file:

XApplication*button1.labelString:Bound
If you have used tight bindings, which are described in the Tight Bindings section on page 98, to set a tight binding for the Shell, MyShell, without specifying any loose bindings, the following line is generated into the resource file:

XApplication*MyShell*button1.labelString:Bound
If you have set a loose binding to encompass all the buttons, as described in the Example Loose Binding section on page 91, the following line is generated into the resource file:

XApplication*MyShell*MyForm*XmPushButton.labelString:Bound

3.22 Where to Look for More Information on Resources

For more information on widget resources see Chapter 22, "Widget Reference", starting on page 653. This chapter contains a summary of the most commonly used resources for each of the Motif widget classes. While this summary is necessarily brief, it will help you get started.

There are many books available that provide a more complete discussion of Motif widget resources. The Motif Programming Manual includes a summary which is both thorough and readable. Several other useful books are listed in Appendix D, "Further Reading".

If you are using WorkShop Visual with additional widgets, you should also consult the documentation provided by your widget developer.


Previous Next Contents Index Doc Set Home