CHAPTER 27 |
Widget Reference |
This chapter provides a brief description of each of the Motif widgets in the widget palette and gives hints for their effective use. It also describes some of the quirks of each widget. Only basic information is given here. For a full description of each widget, including all its resources, see the Motif Programmer's Reference Manual.Each widget description starts with a list of resources grouped by page in the resource panel. Also listed are the callbacks applicable to the widget. Although, strictly speaking, the callbacks for a widget are resources, they are added, edited and viewed in a separate callbacks dialog.
Core resources are not listed to avoid repetition. Resources in bold typeface are frequently set and so are of interest to users regardless of their level of expertise. Resources in normal typeface are less commonly used and you may require more knowledge to use them effectively. Resources that are in italics are not applicable to that widget and are insensitive on the resource panel.
Note - If you invoke Sun WorkShop Visual using the command small_visu, the widget icons are smaller and slightly different from those shown here.
Settings |
Callbacks |
Toggles |
Arrow direction |
Activate |
Widget |
|
Arm |
Gadget |
|
Disarm |
|
The ArrowButton widget provides a button with an arrow on it instead of a text label. The arrow can point up, down, left, or right. Choose one of the four directions by selecting the appropriate direction from the option menu on the ArrowButton resource panel which is shown in Figure 27-1.
Unlike other button widgets, ArrowButtons are not derived from the Label and cannot display text or pixmap labels.
Fonts |
Callbacks |
Text font |
Focus |
Button font |
Map |
Label font |
Unmap |
The BulletinBoard widget is the most basic container widget. It is most commonly used internally by Motif to implement other container or composite widgets such as the Form, SelectionBox and MessageBox. These derived widgets are often more useful than the BulletinBoard itself.As a container widget, the BulletinBoard does not impose any particular layout on its children. It provides absolute positioning, margin constraints and lets you specify whether the widgets inside are allowed to overlap or not. Resizing the BulletinBoard does not move or resize the widgets in it.
The BulletinBoard is most useful for transient dialogs that are not meant to be resized. For resizable dialogs, use a Form or DialogTemplate. You can also use a BulletinBoard for cases where complicated positioning is required and code is to be written for this purpose.
Only the Move and Resize options of the Layout Editor can be used with a BulletinBoard. Attachments between widgets and position attachments are not available. For more flexible layout options, use a Form widget.
If a BulletinBoard is the child of a Shell, the BulletinBoard's "Title" resource is used as the title of the Shell's window.
Note that the "Title", "Dialog style", "Default position" and "No resize" resources are disabled if the BulletinBoard is a child of the Form.
The "Auto unmanage" resource, when set to "Yes", makes the dialog disappear whenever you click on a button child of a BulletinBoard. This behavior, which is the default behavior in Motif, is useful for transient dialogs but can be confusing in main windows. Sun WorkShop Visual explicitly sets this resource to "No" for the BulletinBoard and two of its derivatives, the DialogTemplate and the Form. With other BulletinBoard derivatives, Sun WorkShop Visual does not override the default "Yes" setting and so the dialog does disappear if you click any button. To restore your dynamic display, reset the Shell or select the Shell icon in the window holding area.
The "Default position" resource controls how the position of the window on the screen is determined. If you set this resource to "No" on a BulletinBoard (or derivative) that is a child of a Shell, the window is displayed in the position determined by the x and y resources of the BulletinBoard, not those of the Shell. As this behavior is dependent on the window manager, it may not be consistent.
Toggles |
Keyboard |
Widget |
Accelerator |
Gadget |
Accelerator text |
|
Mnemonic |
|
Mnemonic charset |
|
Mapping delay |
The CascadeButton widget is used to display a menu. A CascadeButton can only be used as the child of a MenuBar or Menu. When it is the child of a MenuBar, a pulldown menu is displayed and when it is the child of a Menu, a pullright menu is displayed. Sample hierarchies showing these specific uses of the CascadeButton are located in the Menu widget description.The only permissible child of a CascadeButton is a Menu. When a user clicks on a CascadeButton, a menu is displayed.
In Motif, a Menu is not technically a child of a CascadeButton but of the button's parent. To indicate this, the connection between a CascadeButton and its menu is drawn with a dotted line instead of the normal solid line.
You can set keyboard mnemonics for CascadeButtons to let the user navigate through the menus without using the mouse.
Note that the Mapping delay resource can be used only when the Button is used to instigate a pullright menu.
Settings |
Callbacks |
Dialog type |
Apply |
Minimize buttons |
Cancel |
Must match |
OK |
File type |
No match |
Work area placement |
Command changed |
|
Command entered |
The Command widget is a composite widget used to select a command from a scrollable history list of commands. Commands can be typed into a text area at the bottom of the widget. When a command is entered, it is added to the end of the history list. A Command inherits some BulletinBoard resources. To display the BulletinBoard resource panel, click on "Bulletin Board Resources" in the resource panel.A Command contains a ScrolledList widget for the command history region, a Label widget for the command line prompt and a Text widget for the command entry region. These components are contained in a BulletinBoard widget that is not visible in the design hierarchy. You can change the default resource settings for the component widgets but you cannot delete them. To change the prompt, change the "Prompt string" resource in the resource panel of the Command, not in the resource panel of its Label child.
A Command is usually used in a Shell or MainWindow.
You can add multiple children to a Command. The first child becomes the work area. This can be a container widget containing additional widgets. The "Work area placement" resource controls where the work area appears in the dialog, even though it appears at the end of the Command widget's hierarchy as shown in Figure 27-2. The additional children can include a MenuBar and any number of PushButton widgets.
Display |
Settings |
Message text |
Default button |
OK label |
Dialog type |
Cancel label |
Alignment |
Help label |
Minimize buttons |
Symbol pixmap |
|
Callbacks |
Cancel |
Ok |
The DialogTemplate widget is usually used as the child of a Shell for a broad range of dialogs. It provides a standard layout that includes, from top to bottom, a menu bar, a work area, a Separator, and a button box.The DialogTemplate is a specially configured MessageBox and shares its resource panel. It also inherits some BulletinBoard resources. To display the BulletinBoard resource panel, click on "Bulletin Board Resources" in the resource panel.
The Separator is a component part of the DialogTemplate. You must add the other elements of the standard layout if you want them: for example, a MenuBar, any type of widget for the work area and buttons of any type for the button box, as shown in Figure 27-3. The work area can be a container widget, such as a Form, with children. The DialogTemplate always arranges its children in the standard order from bottom to top, regardless of the order in which you add them to the hierarchy.
The areas of the standard layout are constrained to be the same width, with the buttons in the button box evenly spaced in one or more rows. The buttons are automatically rearranged as needed when the window resizes.
Margins |
Callbacks |
Width |
Expose |
Height |
Input |
|
Resize |
Resize policy |
|
The DrawingArea widget provides an area in which an application can display output graphics. For example, the design hierarchy in the main Sun WorkShop Visual window is drawn in a DrawingArea contained in a ScrolledWindow.
To display the Layout Editor, select "Layout..." from the Widget menu or press the Layout button on the toolbar. Only the Move and Resize options of the Layout Editor can be used with a DrawingArea. Attachments between widgets and position attachments are not available.
To display the resource panel, select "Resources..." from the Widget pulldown menu or double-click over the widget.
Although a DrawingArea can have any number and types of children, it is not very useful for managing the geometry of other widgets. Other container widgets such as the Form should be used for this purpose instead.
Sun WorkShop Visual cannot help you with drawing in the drawing area. To do this, you must write code containing X Graphics calls. This code is normally put in the "Expose" callback.
Margins |
Callbacks |
Top |
Activate |
Bottom |
Cascading |
Left |
Arm |
Right |
Disarm |
Width |
Expose |
Height |
Resize |
Spacing |
Value changed |
Default shadow |
|
Indicator size |
|
Keyboard |
Toggles |
Accelerator |
Widget |
Accelerator text |
Gadget |
Mnemonic |
|
Mnemonic charset |
|
Mapping delay |
|
The DrawnButton widget is similar to a PushButton except that its face must be drawn by the application instead of being drawn automatically. It can be used to provide a button that has a context-sensitive appearance.To display a picture on a button, it is usually easier to use a PushButton with a pixmap for the image. Drawing the picture on a DrawnButton requires writing code containing X graphics calls, which is normally put in the "Expose" callback.
Settings |
Callbacks |
Dialog type |
Apply |
Minimize buttons |
Cancel |
Must match |
OK |
File type |
No match |
Work area placement |
Command changed |
|
Command entered |
The FileSelectionBox widget is a composite widget that lets users browse through the file system and select a file. The file browser in Sun WorkShop Visual is an example of a FileSelectionBox. The Generate Dialog is a FileSelectionBox with a work area child. The FileSelectionBox is derived from the SelectionBox and shares its resource panel.The FileSelectionBox combination includes two ScrolledLists, two TextFields, four Labels, a Separator and four PushButtons, which are gadgets. These components are contained in a BulletinBoard widget that is not visible in the design hierarchy. To display the resources inherited from the BulletinBoard, click on "Bulletin Board Resources" in the resource panel.
While a FileSelectionBox can be used anywhere that a BulletinBoard can, it is usually placed in a Dialog Shell that is popped up for file selection.
To change the labels of button or label widgets from the defaults, change the resources in the resource panel of the FileSelectionBox, not in the resource panels of the individual widgets.
You can add multiple children to a FileSelectionBox. The first child becomes the work area. This can be a container widget containing additional widgets. The "Work area placement" resource controls where the work area appears in the dialog, even though it appears at the end of the FileSelectionBox widget's hierarchy. The additional children can include a MenuBar and any number of PushButton widgets.
Fonts |
Callbacks |
Text font |
Focus |
Button font |
Map |
Label font |
Unmap |
The Form widget is a container widget that provides both absolute and relative positioning of its children widgets. It is commonly used to lay out widgets in a dialog, either as a child of a Shell or as the work area in a DialogTemplate or similar widget.The layout of widgets in a Form is specified by using attachments on children of the Form. Different types of attachments let you specify different types of spatial relationships such as a fixed location within the Form, a relative location within the Form, or a fixed distance between widgets. These capabilities allow considerable flexibility and reliable behavior when widgets or windows are resized. Sun WorkShop Visual lets you specify these attachments interactively in the Layout Editor. For more information, see the Layout Editor chapter.
You can view the attachments set on any child of a Form by using the Constraints panel. Select any child of the Form, pull down the Widget Menu and select "Constraints...". Use of this panel is described in the Using the Resource Panels chapter. It is particular useful if you have to superimpose one widget over another.
The "Auto unmanage" resource, if set to "Yes", makes the dialog erase whenever you click on a button child of a Form. This behavior, the default behavior in Motif, is useful for transient dialogs. However, because a Form is often used for main windows, Sun WorkShop Visual explicitly sets this resource to "No" in the case of the Form. Set it to "Yes" if you want a Form to auto unmanage.
For more details, see BulletinBoard.
Display |
|
Margin width |
|
Margin height |
|
Title widget |
|
Title spacing |
|
Shadow type |
|
Title alignment (horizontal) |
|
Title alignment (vertical) |
|
The Frame widget is used to provide a border, possibly with a title, around a widget that otherwise has none, to enhance the border of a widget that already has one, or to create a border around a group of widgets. A Frame can be used to provide three-dimensional effects, like indenting a DrawingArea.A Frame can have two children. The first is placed inside the Frame and the second (which is optional) is used as a title. The second child is usually a Label.
To create a border around a group of widgets, they must be placed in a container widget such as a RowColumn or a Form, that is the child of a Frame, as shown in Figure 27-4.
The Frame sizes itself to match the size of its children.
Margins |
Callbacks |
Top |
Activate |
Bottom |
Cascading |
Left |
Arm |
Right |
Disarm |
Width |
Expose |
Height |
Resize |
Spacing |
Value changed |
Default shadow |
|
Indicator size |
|
Keyboard |
Toggles |
Accelerator |
Widget |
Accelerator text |
Gadget |
Mnemonic |
|
Mnemonic charset |
|
Mapping delay |
|
The Label widget provides a static display area for text or pixmap images. Labels are commonly used to display descriptive text strings or icons or logos. Labels can be placed in menus to provide unselectable titles for groups of menu items.A string in a Label can extend over multiple lines and have multiple fonts. Multiple fonts are supported using the Compound String Editor, which is discussed in "Compound Strings" on page 167.
If you set a pixmap for a Label, the Label does not display it until you also change its "Type" setting to "Pixmap".
Display |
Callbacks |
Margin width |
Browse |
Margin height |
Default |
Spacing |
Extended |
Visible items |
Multiple |
Top item |
Single |
Double click interval |
|
Font |
|
Settings |
Items |
Automatic selection |
Item |
Selection policy |
|
Size policy |
|
Scroll bar display |
|
The List widget is used to display a list of text items, one or more of which can be selected, depending on the setting of the "Selection policy" resource.For a scrolling list of text items, use a ScrolledList widget, a composite widget that contains a List widget.
The Items page of the List resource panel lets you add items to the list so you can see what the list looks like. To add an item, enter its text into the "Item" resource box and select "Add". To remove an item from the list, enter its text into the "Item" resource box and select "Remove". While items must be added in the order in which you want them to appear, they can be deleted in any order.
To see additional items, change the "Visible items" resource.
The Motif toolkit provides a large number of functions for manipulating Lists such as adding, removing and replacing items. For further details, see the Motif documentation.
Note that each item in a List is a compound string (XmString). It is therefore theoretically possible to use different fonts for different items, or for different parts of a single item. In practice, limitations of the Motif toolkit make this inadvisable.
Scrolled window margins |
Main window margins |
Width |
Width |
Height |
Height |
Spacing |
|
Callbacks |
Settings |
Traverse obscured |
Scroll bar display |
|
Scroll bar placement |
|
Scrolling policy |
|
Visual policy |
|
Show separators |
|
Command location |
|
Message window |
The MainWindow provides a standard layout for an application's primary window. This standard layout includes, from top to bottom:
A menu bar |
A command area with history, a prompt and an input area |
A work area |
A message area |
The MainWindow is a composite widget with three Separators and two ScrollBars. You must add the widgets for each element in the standard layout. Use a MenuBar for the menu bar and a Command for the command area. A Text or TextField is usually used for the message area. You must give the message area widget a variable name and specify that name as the "Message window" resource of the MainWindow.The work area can be almost any other kind of widget. It can be a container widget with other widgets as children. A MainWindow ordinarily displays a scrolled window onto a work area whose size is fixed. If your work area is a Form, you may want to change the "Scrolling policy" resource to "Application defined". This removes the scroll bars and lets the Form resize with the window so that you can use the features of the Layout Editor to control resize behavior.
Note - "Scrolling policy" does not take effect in the dynamic display but works correctly in the generated code.
If you do not add a work area to a MainWindow, the generated code produces warning messages when you run it.Careful use of resources can make a Form emulate the behavior of a MainWindow. Experience has shown that it is often more convenient to use.
Display |
Settings |
Entry border |
Orientation |
Margin width |
Packing |
Margin height |
Alignment |
Columns |
Adjust last |
Spacing |
Adjust margin |
Help widget |
Aligned |
Last selected |
Homogeneous |
|
Popup enabled1 |
|
Radio always one |
|
Radio behavior |
|
Resize height |
|
Resize width |
|
Tear-off modal |
1 Only if used as a PopupMenu. It is insensitive in all other cases. |
Keyboard |
Callbacks |
Accelerator 1 |
Map |
Menu post1 |
Unmap |
Mnemonic |
Entry |
Mnemonic charset |
|
1 Only if used as a PopupMenu. It is insensitive in all other cases. |
The Menu widget provides pulldown, pullright and popup menus and is a specially configured RowColumn widget.The active items in a menu can be PushButtons, ToggleButtons, or CascadeButtons. Menus can also contain Separators and Labels for display purposes.
To create a pulldown menu, add a Menu as a child of a CascadeButton that is a child of a MenuBar or OptionMenu. When a user clicks on the CascadeButton, the menu appears.
To create a pullright menu, add a Menu as a child of a CascadeButton that is a child of a Menu. When a user clicks on the CascadeButton, the menu appears. Pullright menus are only permitted in menus that are pulled down from a MenuBar, not in OptionMenus.
To create a popup menu, add a Menu as a child of a DrawingArea. When a user clicks on the DrawingArea with the right mouse button, the menu appears. A DrawingArea can have more than one popup menu as a child. In this case, the menu that pops up in the dynamic display depends on which menu is selected in the design hierarchy.
To create a Tear-off menu, set the Tear-off modal resource to enabled. Note that some Motif versions have a bug where, if this resource is not hard-coded and is part of the applications resource file, a call to XmRepTypeInstallTearOffModalConverter() must be made from either the main program or the Menu's pre-create prelude for the resource to take effect.
Figure 27-5 shows design hierarchies for the three types of menus.
Unlike pulldown and pullright menus, popup menus must be explicitly managed by the generated code. Sun WorkShop Visual does not do this automatically because popup menus are context-sensitive in most applications. You can do this by using the input callback of the DrawingArea to position and manage the menu, or with an action routine using the translations mechanism. Normally, the menu is positioned using XmMenuPosition() and managed using XtManageChild().To create a Menu with mutually exclusive toggle buttons, set the "Radio behavior" resource to "Yes".
In Motif, Menus are technically siblings, not children, of the DrawingAreas or CascadeButtons from which they appear. However, Sun WorkShop Visual displays its hierarchy as if the Menus were children of these widgets because the DrawingArea or CascadeButton affects the Menu's behavior just as a parent widget does. Sun WorkShop Visual uses a dotted rather than a solid line to connect the Menu to its CascadeButton or DrawingArea. The dotted line indicates that the connection is not a true Motif parent-child relationship.
Keyboard |
Callbacks |
Accelerator |
Map |
Menu post |
Unmap |
Mnemonic |
Entry |
Mnemonic charset |
|
The MenuBar widget displays a set of CascadeButtons from which you can pull down menus.MainWindow, DialogTemplate and SelectionBox provide standard layouts that can include a MenuBar. If you do not use one of these to contain the MenuBar, you must use a Form and attach the MenuBar to its top, left and right sides. For further information about the differences, see the descriptions of the MainWindow, DialogTemplate, SelectionBox and Form. For a design hierarchy that includes a MenuBar with a typical configuration of children, see Figure 27-5 on page 763.
The default resource settings provide a standard menu bar as defined in the Motif Style Guide. You can change the "Packing" resource setting from "Tight" to "Column". "Tight" makes all buttons the minimum size to accommodate their text "Column" makes all buttons the same size
If you use "Column" packing, the "Alignment" resource can be set to center the labels on the buttons. Changing other resources is not recommended.
A MenuBar positions all its CascadeButtons close together starting at the left. If your menu bar has a "Help" button, the Motif Style Guide recommends placing it at the right end of the menu bar. To designate a CascadeButton as the "Help" button, enter its variable name as the "Help widget" resource of the MenuBar.
ox
Display |
Settings |
Callbacks |
Message text |
Default button |
Cancel |
Ok label |
Dialog type |
Ok |
Cancel label |
Alignment |
|
Help label |
Minimize buttons |
|
Symbol pixmap |
|
|
The MessageBox widget displays a message to the user. Sun WorkShop Visual's error messages are examples of MessageBoxes. The MessageBox is a composite widget that consists of three PushButton gadgets, two Labels and a Separator. These components are contained in a BulletinBoard that is not visible in the design hierarchy. To view the inherited BulletinBoard resources, click on "Bulletin Board Resources" in the resource panel.Although a MessageBox can be used anywhere that a BulletinBoard can be used, it is usually placed in a Dialog Shell that is popped up to alert the user.
To display a message or pixmap in the message area, or to change the labels of buttons, change the resources in the resource panel of the MessageBox, not in the resource panels of the component widgets.
You can add a MenuBar and any number of button widgets as children of a MessageBox, as well as a single widget of another type, which becomes the work area. The work area can be a container widget, such as a Form, with children.
u
Keyboard |
Callbacks |
Accelerator |
Map |
Menu post |
Unmap |
Mnemonic |
Entry |
Mnemonic charset |
|
The OptionMenu widget is used to display a one-of-many choice without using the screen space required by a set of radio buttons. The page selectors in Sun WorkShop Visual's resource panels are examples of OptionMenus.An OptionMenu is a composite widget that includes a Label and a CascadeButton. You should add a Menu child to the CascadeButton, with a PushButton for each choice. You can use Separators to divide groups of options. Figure 27-6 shows a sample hierarchy. Note that you cannot have a cascading option menu.
Set the label identifying the OptionMenu by changing the "Label" resource in the resource panel of the Label. Do not change the label of the CascadeButton as this displays the current setting of the OptionMenu.
dWindow
Margins |
|
Margin width |
Margin height |
Sash width |
Sash height |
Sash indent |
Sash shadow |
Spacing |
|
Settings |
|
Refigure |
Separator |
The PanedWindow widget is used to lay out a set of widgets in a vertical column of uniform width. Each child widget is laid out in a vertical partition that is separated from adjacent children by a movable separator like a window sash. The user can move the sash to determine how much vertical space is allotted to each child. Since the height of a PanedWindow is less than the aggregate height of its children, a PanedWindow saves vertical space without sacrificing functionality. The children of a PanedWindow can be container widgets that control the layout of other widgets.The PanedWindow is a constraint widget. The Constraints panel applies to any child of the PanedWindow, not to the PanedWindow itself. You can display the Constraints panel by selecting "Constraints" from the Widget menu when one of the PanedWindow's children is selected. The Resource Panels chapter discusses how to use this panel.
The Constraints panel lets you set the "Minimum" and "Maximum" height resources for the child. These provide limits on the height of the widget's partition and positioning of the sashes.
The children in a PanedWindow are constrained to be the same width as the widest child.
You may need to reset a PanedWindow whenever you rearrange or resize its children.
Button
Toggles |
Keyboard |
Widget |
Accelerator1 |
Gadget |
Accelerator text 1 |
|
Mnemonic 1 |
|
Mnemonic charset1 |
|
Mapping delay |
1 Sensitive when PushButton is child of Menu |
The PushButton widget displays a button that can be "pressed" by clicking a mouse button over it. Like the Label, it can display either text or a pixmap.There are different kinds of buttons for different needs, such as the ArrowButton and DrawnButton. For a button that pops up a menu, use a CascadeButton.
Setting the "Show as default" resource is not recommended since a BulletinBoard parent often changes this setting. The BulletinBoard decides which button to make the default.
Keyboard |
Callbacks |
Accelerator |
Map |
Menu post |
Unmap |
Mnemonic |
Entry |
Mnemonic charset |
|
A RadioBox widget is used to contain a group of ToggleButtons that act as radio buttons, meaning that they are mutually exclusive. Selecting one toggle in the group deselects the previously selected one. You can set the "Packing", "Columns", and "Orientation" resources to create multiple columns as for RowColumn.The ToggleButtons in the RadioBox are gadgets.
You can make a RowColumn act like a RadioBox by setting its "Radio behavior" resource to "Yes". This configuration of the RowColumn provides more flexibility than the RadioBox does, e.g. to have Labels, Separators, or other widgets inside the box with the ToggleButtons, or to use the widget version of the ToggleButton instead of the gadget.
Keyboard |
Callbacks |
Accelerator |
Map |
Menu post |
Unmap |
Mnemonic |
Entry |
Mnemonic charset |
|
The RowColumn widget is used to arrange child widgets in a grid. It is often used for arranging items such as groups of buttons or toggles. For example, a Menu is a specially configured RowColumn widget. Other widgets that are based on RowColumn are OptionMenu, MenuBar, Menu and RadioBox.A RowColumn can have any number of children. The default arrangement of RowColumn items is one vertical column. To create multiple columns, set the "Packing" resource to "Column", then set the "Columns" resource.
Items are read in order starting down the first column when the "Orientation" resource setting is "Vertical" and across the first row when the "Orientation" resource setting is "Horizontal". When the "Orientation" resource setting is "Horizontal", the "Columns" setting refers to the number of horizontal rows.
Because a RowColumn widget is not designed to have its layout changed dynamically, it may not display the changes you expect. If its children seem to be the wrong size on the dynamic display, try resetting the RowColumn.
Note - When you use multiple columns, a RowColumn forces all items to be the same width. Sometimes this results in wasted space, as in the "Before" view of Figure 27-7, where the left column has short Labels and the right column has long TextFields. You can resize the TextFields to match the width of the Labels. However, although the new value is accepted in the resource panel, the difference in width is not apparent in the dynamic display until you have changed the value for all of the TextFields, as shown in the "After" view.
To create columns of unequal width, use a Form instead of a RowColumn. You can also nest RowColumns to create layouts that are more complex than rows and columns.To create a group of radio buttons inside a RowColumn, use ToggleButtons and set the "Radio behavior" resource of the RowColumn to "Yes".
Display |
Settings |
Callbacks |
Decimal points |
Orientation |
Drag |
Minimum |
Direction |
Value changed |
Maximum |
Show value |
|
Value |
|
|
Title |
|
|
Scale width |
|
|
Scale height |
|
|
Scale multiple |
|
|
Font |
|
|
The Scale widget offers a range of values to choose from and displays a slider that can be moved to change the current value. You can drag the slider to move it continuously, click in the trough with the left mouse button to move the slider incrementally, or click in the trough with the middle mouse button to move the slider to the cursor location.A Scale can have children of almost any type. These are usually Labels, which the Scale lays out evenly along its length.
Changing the orientation of a Scale can have strange effects. If problems occur, try resetting the Scale or its parent.
The ScrollBar widget lets users view data that requires more space than the display area provides. ScrollBars are rarely used alone. It is easiest to use them as part of a composite widget such as a ScrolledWindow, ScrolledList, or ScrolledText.Each ScrollBar is represented as a rectangle with an arrow pointing outward at each end and a slider inside it. The display area is scrolled either by moving the slider or by clicking on an arrow. You can drag the slider to move it continuously, click in the trough or on the arrows with the left mouse button to move the slider incrementally, or click in the trough with the middle mouse button to move the slider to the cursor location. You can edit the resources to control the amount by which the display area scrolls on each scrolling action.
A ScrollBar cannot have children.
Margins |
Settings |
Width |
Scroll bar display |
Height |
Scroll bar placement |
Spacing |
Scrolling policy |
|
Visual policy |
Callbacks |
Show separators |
Traverse obscured |
|
|
|
The ScrolledList widget is a composite widget that displays a scrollable list of items. A ScrolledList is a specially configured ScrolledWindow that contains a List widget. The resources of a List widget child can be set in the normal way.A ScrolledList resizes itself whenever you add or delete items from the List so that its width always matches that of the widest item in the list. In some versions of the Motif toolkit, the ScrolledList may become confused about its correct width.
To prevent unwanted resizing, you must constrain a ScrolledList in some way. You can constrain it in a Form by using attachments and positions. However, if the Form also contains other widgets, this can produce strange results. To avoid this, use a ScrolledList in a Form containing nothing except a ScrolledList, as shown in Figure 27-8:
You can then place this Form in another Form with other widgets. Attach the ScrolledList to its parent Form on all four sides and set the "Resize policy" of the Form to either "Grow" or "None". You can set the width and height of the Form to define a reasonable size for the ScrolledList, or fix the initial size of the Form, and therefore the ScrolledList it contains, by using attachments.Constraints set in the Form supersede the ScrolledList's "Visible items" resource setting and the width of individual items in the list.
Margins |
Settings |
Width |
Scroll bar display |
Height |
Scroll bar placement |
Spacing |
Scrolling policy |
|
Visual policy |
Callbacks |
Show separators |
Traverse obscured |
Command window |
|
Message window |
The ScrolledText widget is a composite widget that provides a scrollable text area. A ScrolledText is a specially configured ScrolledWindow that contains a Text widget. The resources of the Text widget child can be set in the usual way.
Margins |
Settings |
Width |
Scroll bar display |
Height |
Scroll bar placement |
Spacing |
Scrolling policy |
|
Visual policy |
Callbacks |
Show separators |
Traverse obscured |
Command window |
|
Message window |
The ScrolledWindow widget is used to display data that requires more space than is available. It is a composite widget consisting of two scroll bars and a viewing area onto a visible object that can be larger than the ScrolledWindow. A ScrolledWindow can have one child of almost any type.Although the visible object can be any kind of widget, it is commonly a DrawingArea or a composite widget containing other widgets. For example, a ScrolledWindow can be used to scroll through a form or table of widgets by placing a Form or RowColumn in it. For a scrollable list or text display, use the ScrolledList or ScrolledText widget.
If you do not add a child to a ScrolledWindow, the generated code produces warning messages when you run it.
If the "Scrolling policy" resource is set to "Automatic", the toolkit handles scrolling for you and the scroll bars are created automatically.
If the "Scrolling policy" resource is set to "Application defined", you must respond to movements of the scroll bars by changing the information displayed in the ScrolledWindow's child. In this case, Sun WorkShop Visual generates code to create the scroll bars for you if any resource, callback, or name is set.
The effect of the resources that control scroll bar behavior - "Scrolling policy" and "Scroll bar display" - is not reflected in the dynamic display but they work correctly in the generated code.
Settings |
Callbacks |
Dialog type |
Apply |
Minimize buttons |
Cancel |
Must match |
Ok |
File type |
No match |
Work area placement |
Command changed |
|
Command entered |
The SelectionBox widget is a composite widget used to select one or more items from a scrollable list. The SelectionBox combination includes a ScrolledList for the item list, two Labels, a Separator and four PushButtons, which are gadgets. These components are contained in a BulletinBoard widget that is not visible in the design hierarchy. To view resources inherited from the BulletinBoard, click on "Bulletin Board Resources" in the resource panel.While a SelectionBox can be used anywhere that a BulletinBoard can be used, it is usually placed in a Dialog Shell that is popped up to get a selection from the user.
To change the labels of button or label widgets, change the resources in the resource panel of the SelectionBox, not in the resource panels of the individual widgets.
You can add multiple children to a SelectionBox. The first child becomes the work area. This can be a container widget containing additional widgets. The "Work area placement" resource controls where the work area appears in the dialog, even though it appears at the end of the SelectionBox widget's hierarchy. The additional children can include a MenuBar and any number of PushButton widgets.
The four PushButtons provided are labeled "OK", "Apply", "Cancel", and "Help". The "Apply" PushButton can be displayed by setting the "Managed" toggle in the PushButton's Core resource panel.
mpt
Settings |
Callbacks |
Dialog type |
Apply |
Minimize buttons |
Cancel |
Must match |
OK |
File type |
No match |
Work area placement |
Command changed |
|
Command entered |
The SelectionPrompt widget is used to prompt the user for text input. It is a composite widget consisting of a Label used for a question or prompt, a Text box into which the answer is typed and three PushButtons ("OK", "Cancel", and "Help"). An "Apply" PushButton is also provided. It is displayed by setting the "Managed" toggle in that PushButton's Core resource panel. These components are contained in a BulletinBoard that is not visible in the design hierarchy. To view the resources inherited from the BulletinBoard, click on "Bulletin Board Resources" in the resource panel.Most of the information about the SelectionBox applies to the SelectionPrompt, except that the SelectionPrompt does not include a List. While a SelectionPrompt can be used anywhere that a BulletinBoard can be used, it is usually placed in a Dialog Shell that is popped up to query the user for input. To change the prompt or the labels of the buttons, change the resources in resource panel of the SelectionPrompt, not in the resource panels of the individual widgets. The SelectionPrompt can have multiple lines.
The PushButtons in a SelectionPrompt are gadgets. You can add multiple children to a Prompt. The first child becomes the work area. This can be a container widget. The "Work area placement" resource controls where the work area appears in the dialog, even though it appears at the end of the Prompt widget's hierarchy. The additional children can include a MenuBar and any number of PushButtons.
Margins |
Toggles |
Type |
Widget |
Orientation |
Gadget |
The Separator widget is a line used to separate objects visually. A Separator cannot have children. Set the "Orientation" resource to specify a vertical or horizontal line. Set the "Type" resource to specify a different line type such as a double line or a dashed line.
Separators can be used to separate items in a Menu or RowColumn or to separate widgets in a dialog box. To separate widgets in a Form, make a Separator a child of the Form along with the other widgets. The Separator is very small until it is constrained in some way. To stretch it the length or width of the Form, attach it to both sides of the Form, or to other widgets on each side. Setting the size of a Separator explicitly is not recommended. A Separator with a "Type" of "No line" can be used as an invisible widget.
Separators are often used inside Menus to divide items into groups. The Separator appears between its adjacent siblings, as shown in Figure 27-9.
You can use Separators inside a RowColumn. Figure 27-10 shows a sample hierarchy and the resulting dynamic display. When you use Separators in a RowColumn, set the orientation of the Separators explicitly to "Vertical" or "Horizontal". Separators in a RowColumn span a cell the size of every other element in the array. This can produce more white space around the Separator than is pleasing. If you want different proportions, use a Form for your column layout.Set the RowColumn's "Spacing" resource to 0 to eliminate a gap between adjacent separators.
FIGURE 27-10 Use of Separators in a RowColumn (Horizontal Orientation, 4 Rows)
Display |
Settings |
Dimensions |
Title |
Delete response |
Base width |
Mwm menu |
Keyboard focus |
Base height |
Icon mask |
Input |
Width inc |
Icon pixmap |
Transient |
Height inc |
Icon name1 |
Allow resize |
Min width |
Label font |
Override redirect: No |
Min height |
Button font |
Iconic1 |
Max width |
Text font |
Unit type |
Max height |
Input method |
Window gravity |
Min aspect X |
Pre-edit type |
Initial state |
Min aspect Y |
|
Save under |
Max aspect X |
|
Audible warning |
Max aspect Y |
|
|
Timeout |
1 Sensitive if Shell is set to Dialog Shell |
Callbacks |
Toggles |
Pop down |
Application shell |
Pop up |
Top level shell |
|
Dialog shell |
The Shell widget forms the interface between your design and the Motif window manager. Every Sun WorkShop Visual design hierarchy must have a Shell as its root widget.The Sun WorkShop Visual palette contains three types of Shell widget - the Dialog shell, Top Level Shell and Application Shell. These Shells can be switched to any of the others by setting the appropriate toggle in the Shell resource panel.
The Application Shell is used as the main application window. Your application must have at least one (and usually only one) Application Shell. Top level Shells look and act like Application Shells. Typically, they are used for all primary windows in the application except the first. Dialog Shells are used for secondary windows such as pop-up dialogs. If an Application or Top level Shell is closed or iconified, all associated Dialog windows also disappear.
An Application or Top level Shell appears as a Dialog Shell in the dynamic display but the generated code produces the correct type of Shell. To check the icon pixmap, set the "Transient" resource to "No", then reset the Shell. This produces the full set of decorations, allowing you to iconify the dynamic display window.
A Shell can only have one child, which can be of any type. However, much of the Shell's behavior is based on the assumption that its child is a BulletinBoard, Form, or similar container widget, since the Shell exercises no geometry management over its descendants. A Shell is not visible until it has a child.
Setting a Shell's width and height on its Core resource panel does not control the window size. To control initial window size, set the minimum width and height resources of the Shell, or set the width and height of the Shell's child.
To control the initial position of a window, set the "Default position" resource of the Shell's child to "No", and set the x and y resources of the child, not the Shell.
Callbacks |
Toggles |
Activate |
Text |
Focus |
Text Field |
Losing focus |
|
Gain primary |
|
Lose primary |
|
Modify verify |
|
Motion verify |
|
Value changed |
|
The Text widget provides an area for entering multi-line text. A wide range of callbacks is provided to deal with input verification and validation.To use multi-line text, you must set the "Edit mode" resource to "Multi line". To change the height of the Text widget to display multiple lines of text, you can change the "Rows" resource setting to a number greater than 1. Changing the number of Rows may or may not be effective, depending on the type of widget used as the Text widget's parent.
To create a scrollable text editing area, use a ScrolledText, a composite widget that includes a Text widget. Although the Text widget can be the child of a ScrolledWindow, this configuration does not work well. If you use this configuration, change the "Edit Mode" resource to "Multi line" and increase the number of Rows and Columns to exceed the size of the ScrolledWindow viewing area.
The Motif toolkit provides functions for accessing and modifying the text in the widget. For details, see the Motif documentation.
Callbacks |
Toggles |
Activate |
Text |
Focus |
Text Field |
Losing focus |
|
Gain primary |
|
Lose primary |
|
Modify verify |
|
Motion verify |
|
Value changed |
|
The TextField widget is a variant of the Text widget that provides an area for entering only a single line of text. It has all the Text's editing features except multi-line capability.You can change from TextField to Text by using the toggle. However, to get multi-line capability, you must also set the "Edit mode" resource to "Multi line".
The Motif toolkit provides functions for accessing and modifying the text in the widget. For details, see your Motif documentation. "Books on X and Motif" on page 890 provides some suggestions for further reading on this subject.
Margins |
Keyboard |
Toggles |
Top |
Accelerator1 |
Widget |
Bottom |
Accelerator text1 |
Gadget |
Left |
Mnemonic1 |
|
Right |
Mnemonic charset1 |
|
Width |
Mapping delay |
|
Height |
|
|
Spacing |
|
|
Default shadow |
|
|
Indicator size |
|
|
1 Sensitive when ToggleButton is child of Menu |
The ToggleButton widget provides a simple on/off toggle for indicating "yes/no" choices.ToggleButtons can be made into mutually exclusive radio buttons by placing them inside a RadioBox, or inside a Menu or RowColumn whose "Radio behavior" resource is set to "Yes". Radio buttons have a different shape from normal toggles, as shown in Figure 27-11.
You can configure the ToggleButton to resemble a PushButton that appears to push in and out to represent on and off settings. To do this:
1. | Set the "Shadow Thickness" Core resource to 2. This draws a border around the button. |
2. | Set the "Indicator on" resource to "No". This suppresses the small square indicator. |
3. | Set the left margin to 0. This removes the space which was occupied by the indicator. |
Following is a list of the Motif widgets which can be selected from within Sun WorkShop Visual in Microsoft Windows mode along with the way in which they are mapped to a Microsoft Windows class.
ApplicationShell
Maps to CFrameWnd or to CDialog is "Generate as Resources" is requested in the Generate Options dialog.
TopLevelShell
Maps to CDialog.
DialogShell
Maps to CDialog.
MainWindow and ScrolledWindow
Map to CWnd unless they are the child of a Shell, in which case they are ignored for Microsoft Windows.
Frame, RadioBox and ToggleButton
Map to CButton.
BulletinBoard, Form, RowColumn and DialogTemplate
Map to CWnd if they are structured as a C++ class.
DrawingArea
Maps to CWnd unless its parent is a ScrolledWindow, MainWindow or Shell in which case it is ignored for Microsoft Windows. Otherwise it is forced to be structured as a C++ class.
MenuBar, PopupMenu and CascadeButton
Map to a CMenu and cannot be structured as a C++ class.
OptionMenu
Maps to a CComboBox and cannot be structured as a C++ class.
FileSelectionBox
Maps to a CFileDialog class.
Paned Window
Maps to CSplitterWnd.
Label
Maps to a CStatic.
PushButton
Maps to a CButton if XmNlabelType is XmLABEL or to a CBitmapButton if XmNlabelType is XmPIXMAP.
Separator
This is not mapped to an object on Microsoft Windows - instead it is added as a Menu attribute, if part of a menu. If not in a menu, it is ignored.
Scale and Scrollbar
Map to CScrollbar unless they are part of a ScrolledWindow in which case the appropriate style is added to the enclosing class and they are ignored as widgets. Note that the Scale is mapped correctly is "Generate as Resources" is selected in the Generate Options dialog.
TextField and Text
Maps to CEdit.
List
Maps to CListBox.
ScrolledText
This maps to CEdit with appropriate scrolling styles and the ScrolledWindow part is ignored.
ScrolledList
This maps to CListBox with appropriate scrolling styles and the ScrolledWindow part is ignored.
Although Microsoft Windows uses resources, the way in which they are used is different from X/Motif. Resources used by Microsoft Windows are compiled into the application. There is also a far more restricted set than on Motif.Sun WorkShop Visual only generates bitmaps, icons and accelerators as Microsoft Windows resources. Other Motif resources are mapped to visual window attributes or written into the source code.
When a Microsoft Windows object is created, window styles can be specified. These are bit flags which are or'd together. The following example shows how a toggle button would be created:Create ( "Classical", WS_CHILD | WS_VISIBLE | WS_TABSTOP | BS_AUTORADIOBUTTON, rect, this, IDC_shell_classical);The second parameter to this method, which is a method inherited from a basic MFC class, is the window style. When you set resources in Sun WorkShop Visual, suitable window styles are chosen. Below is a list of the window styles available for each widget which can be mapped to a Microsoft Windows object. The list also shows when they are used and the corresponding Motif resource.
All Shells have:
WS_POPUP |
WS_CAPTION |
WS_SYSMENU |
WS_MINIMIZE - if XmNinitialState is set to Iconic |
WS_VSCROLL and WS_HSCROLL - if child is MainWindow or ScrolledWindow and the appropriate scrollbar is named, has a resource set or has a callback or method set |
In addition to Shell styles, has:
WS_THICKFRAME |
WS_MINIMIZEBOX |
WS_MAXIMIZEBOX |
Exactly the same styles as ApplicationShell.
Note - This does not mean that ApplicationShell and TopLevelShell are exactly the same on Microsoft Windows - they are different classes.
In addition to Shell styles, has:
WS_THICKFRAME - unless XmNoResize is set to True on the BulletinBoard derived child |
Only supported if XmNscrollingPolicy is set to XmAPPLICATION-DEFINED |
WS_CHILD |
WS_VISIBLE - if the widget is managed |
WS_DISABLED - if XmNsensitive is False |
WS_TABSTOP - if XmNtraversalOn is True |
WS_VSCROLL and WS_HSCROLL - if the appropriate scrollbar is named, has a resource set or has a callback or method set |
WS_CHILD |
WS_VISIBLE - if the widget is managed |
WS_DISABLED - if XmNsensitive is False |
WS_TABSTOP - if XmNtraversalOn is True |
WS_GROUP |
BS_GROUPBOX |
WS_CHILD |
WS_VISIBLE - if the widget is managed |
WS_DISABLED - if XmNsensitive is False |
WS_TABSTOP - if is XmNtraversalOn is True |
WS_CHILD |
WS_VISIBLE - if the widget is managed |
WS_DISABLED - if XmNsensitive is False |
WS_TABSTOP - if XmNtraversalOn is True |
WS_GROUP |
BS_GROUPBOX - if parent is not a Frame |
These widgets are not windows on Microsoft Windows, as all other objects are - they are CMenu objects. CMenu is not derived from CWnd. This means that they have no window styles associated with them. Their children (or the children of the PulldownMenu in the case of the CascadeButton) are generated by a call to AppendMenu for each child. The following flags are passed to AppendMenu depending on the type of child:
MF_POPUP - for a CascadeButton which has a PulldownMenu |
MF_STRING - for CascadeButtons without a PulldownMenu, PushButtons, Labels and ToggleButtons which do not have a valid pixmap object for XmNlabelPixmap |
MF_GRAYED - if XmNsensitive is False (for the CascadeButton in the case of a MenuBar) |
MF_MENUBREAK - if the item (or the CascadeButton in the case of a MenuBar) starts a new column |
The following apply to calls to AppendMenu from a PopupMenu or CascadeButton only:
MF_DISABLED - for Labels if XmNsensitive is True |
MF_SEPARATOR - for separators |
MF_CHECKED - for ToggleButtons which have XmNset True |
WS_CHILD |
CBS_DROPDOWNLIST |
WS_VISIBLE - if the widget is managed |
WS_DISABLED - if XmNsensitive is False |
WS_TABSTOP - if XmNtraversalOn is True |
WS_GROUP - if XmNnavigationType is not XmNONE |
The SetFont method is called if the widget has a font object resource set for the XmNbuttonfontList resource or if it inherits a font object set for an enclosing BulletinBoard or Shell |
This maps to a CFileDialog class. Since the Create method is not called explicitly for a CFileDialog (instead InitDialog and DoModal are called) there are no styles. Instead, resources are mapped to parameters passed to the New method:
OpenFileDialog - always TRUE |
lpszDefExt - always NULL |
lpszFileName - set to the value of XmNdirSpec if specified, otherwise NULL |
dwFlags - always OFN_HIDEREADONLY|OFN_OVERWRITEPROMPT |
lpszFilter - if XmNpattern is specified this value is set as follows: |
If XmNpattern is not set this parameter is NULL
pParentWnd - the main window |
WS_CHILD |
WS_VISIBLE - if the widget is managed |
WS_DISABLED - if XmNsensitive is False |
WS_TABSTOP - if XmNtraversalOn is True |
The CreateView method is called to create each of the child panes. This requires that the child pane classes can support dynamic creation (i.e. have the IMPLEMENT_DYNCREATE macro). Sun WorkShop Visual will generate the appropriate macro invocations to support dynamic creation of child pane classes. |
WS_CHILD |
WS_VISIBLE - if the widget is managed |
WS_DISABLED - if XmNsensitive is False |
WS_TABSTOP - if XmNtraversalOn is True |
An alignment (SS_LEFT, SS_CENTER, SS_RIGHT) depending on the alignment of the label (determined either from XmNalignment or from parent's XmNentryAlignment if parent is a RowColumn) |
SS_ICON - if XmNlabelType is set to XmPIXMAP and XmNlabelPixmap is set to a Pixmap object |
The caption parameter to the Create method is the value of XmNlabelString if set, otherwise the widget name. |
The SetFont method is called if the widget has a font object resource set for the XmNfontList resource. If the widget is being created (i.e. is not a component) then SetFont will be called if an ancestor BulletinBoard or Shell has XmNlabelFontList set. |
The SetIcon method is called if the widget has a valid Pixmap object set for XmNlabelPixmap. |
WS_CHILD |
WS_VISIBLE - if the widget is managed |
WS_DISABLED - if XmNsensitive is False |
WS_TABSTOP - if XmNtraversalOn is True |
BS_OWNERDRAW - if XmNlabelType is set to XmPIXMAP |
BS_DEFPUSHBUTTON - if the widget is set as the default button for an ancestor BulletinBoard which is itself a descendant of a DialogShell or a TopLevelShell and there are no CWnd objects intervening between the button and the CDialog |
The caption parameter to the Create method is the value of XmNlabelString if set, otherwise the widget name |
The SetFont method is called if the widget has a font object resource set for the XmNfontList resource. If the widget is being created (i.e. is not a component) then SetFont will be called if an ancestor BulletinBoard or Shell has XmNlabelFontList set. |
WS_CHILD |
WS_VISIBLE - if the widget is managed |
WS_DISABLED - if XmNsensitive is False |
WS_TABSTOP - if XmNtraversalOn is True |
BS_AUTORADIOBUTTON - if XmNindicatorType is set to XmONE_OF_MANY, otherwise BS_AUTOCHECKBOX |
The SetCheck method is called if XmNset is set. |
The caption parameter to the Create method is the value of XmNlabelString if set, otherwise the widget name. |
The SetFont method is called if the widget has a font object resource set for the XmNfontList resource. |
WS_CHILD |
WS_VISIBLE - if the widget is managed |
WS_DISABLED - if XmNsensitive is False |
WS_TABSTOP - if XmNtraversalOn is True |
SBS_HORIZ or SBS_VERT - depending on the setting of XmNorientation |
SetScrollRange is called if the widget is a ScrolledWindow component or if either XmNmaximum or XmNminimum are set. |
SetScrollPos is called if XmNvalue is set. |
WS_CHILD |
WS_VISIBLE - if the widget is managed |
WS_DISABLED - if XmNsensitive is False |
WS_TABSTOP - if XmNtraversalOn is True |
WS_BORDER - if XmNshadowThickness is greater than zero |
WS_GROUP if XmNnavigationType is not XmNONE |
ES_MULTILINE and ES_WANTRETURN if XmNeditMode is set to XmMULTI_LINE_EDIT |
ES_READONLY if XmNeditable is set to false |
WS_VSCROLL - if the parent is a ScrolledText and XmNscrollVertical is the default or set to true |
WS_HSCROLL - if the parent is a ScrolledText and XmNscrollHorizontal is the default or set to true |
The SetWindowText method is called if the XmNvalue resource is set. |
The SetFont method is called if the widget has a font object resource set for the XmNfontList resource or if it inherits a font object set for an enclosing BulletinBoard or Shell. |
The LimitText method is called if the XmNmaxLength resource is set. |
WS_CHILD |
WS_VISIBLE - if the widget is managed |
WS_GROUP if XmNnavigationType is not XmNONE |
WS_TABSTOP - if XmNtraversalOn is True |
WS_BORDER - if XmNshadowThickness is greater than zero |
WS_VSCROLL and WS_HSCROLL - if the parent is a ScrolledList |
LBS_EXTENDEDSEL - if XmNselectionPolicy is XmEXTENDED_SELECT |
LBS_MULTIPLESEL - if XmNselectionPolicy is XmMULTIPLESELECT |
LBS_DISABLENOSCROLL - if parent is ScrolledList and XmNscrollbarDisplayPolicy is not XmAS_NEEDED |
The SetFont method is called if the widget has a font object resource set for the XmNfontList resource or if it inherits a font object set for an enclosing BulletinBoard or Shell. |