Previous Next Contents Index Doc Set Home


Widget Reference

22

22.1 Introduction

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 WorkShop Visual using the command small_visu, the widget icons are smaller and slightly different from those shown here.

22.2 ArrowButton



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 22-1.

Figure  22-1 ArrowButton Resource Panel
Unlike other button widgets, ArrowButtons are not derived from the Label and cannot display text or pixmap labels.

22.3 BulletinBoard



Display
 		Settings

Title

Dialog style

Margin height

Resize policy

Margin width

Shadow

Horizontal spacing

Allow overlap

Vertical spacing

Auto unmanage

Fraction base

Default position

Cancel button

No resize

Default button

Rubber positioning



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. 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, 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.

22.4 CascadeButton



Display
 		Margins

Label

Top

Font

Bottom

Pixmap

Left

Insensitive pixmap

Right

Cascade pixmap

Width

Arm color

Height

Arm pixmap

Spacing

Select pixmap

Default shadow

Select insensitive pixmap

Indicator size



Toggles
 		Keyboard

Widget

Accelerator

Gadget

Accelerator text 

     

Mnemonic 

     

Mnemonic charset 

     

Mapping delay



Callbacks
 		Settings

Activate

Alignment

Cascading

Type

Arm

Resize

Disarm

Push button

Expose

Shadow

Resize

Fill on Arm

Value changed

Fill on select 

     

Indicator on 

     

Indicator type 

     

Multi click 

     

Set 

     

Visible when off

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.

22.5 Command



Display
 		Labels

No match string

Apply label

Pattern

OK label

Max history items

Cancel label

Command

Help label

History item count

List label

Text columns

Prompt string

Directory mask

Prompt string

Directory

Directory label



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 22-2. The additional children can include a MenuBar and any number of PushButton widgets.

Figure  22-2 Command Widget Hierarchy

22.6 DialogTemplate



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 22-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.

Figure  22-3 Standard Hierarchy Using the DialogTemplate
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.

22.7 DrawingArea



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 WorkShop Visual window is drawn in a DrawingArea contained in a ScrolledWindow.

Clicking twice on a DrawingArea in the construction area displays the Layout Editor. 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.

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.

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.

22.8 DrawnButton



Display
 		Settings

Label

Alignment

Font

Type

Pixmap

Resize

Insensitive pixmap

Push button

Cascade pixmap

Shadow

Arm color

Fill on Arm

Arm pixmap

Fill on select

Select color

Indicator on

Select pixmap

Indicator type

Select insensitive pixmap

Multi click 

     

Set 

     

Visible when off



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.

22.9 FileSelectionBox



Display
 		Labels

No match string

Apply label

Pattern

OK label

Max history items

Cancel label

Directory spec

Help label

Visible item count

File list label

Text columns

Selection label

Directory mask

Filter label

Directory

Directory label



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

22.10 Form



Display
 		Settings

Title

Dialog style

Margin height

Resize policy

Margin width

Shadow

Horizontal spacing

Allow overlap

Vertical spacing

Auto unmanage

Fraction base

Default position

Cancel button

No resize

Default button

Rubber positioning



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. 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, 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.

22.11 Frame



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 22-4.

Figure  22-4 Hierarchy Showing a Frame Widget as a Border
The Frame sizes itself to match the size of its children.

22.12 Label



Display
 		Settings

Label

Alignment

Font

Type

Pixmap

Resize

Insensitive pixmap

Push button

Cascade pixmap

Shadow in

Arm color

Fill on arm

Arm pixmap

Fill on select

Select color

Indicator on

Select pixmap

Indicator type

Select insensitive pixmap

Multi click 

     

Set 

     

Visible when off



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 the Compound Strings section on page 176.

If you set a pixmap for a Label, the Label does not display it until you also change its "Type" setting to "Pixmap".

22.13 List



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.

22.14 MainWindow



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:

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.

22.15 Menu



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 22-5 shows design hierarchies for the three types of menus.

Figure  22-5 Sample Hierarchy Using Menus
Unlike pulldown and pullright menus, popup menus must be explicitly managed by the generated code. 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, 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. 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.

22.16 MenuBar



Display
 		Settings

Entry border

Orientation

Margin width

Packing

Margin height

Alignment

Columns

Adjust last

Spacing

Adjust margin

Help widget

Aligned

Last selected

Homogeneous 

     

Popup enabled 

     

Radio always one 

     

Radio behavior 

     

Resize height 

     

Resize width 

     

Tear off modal



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 22-5 on page 672.

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.

22.17 MessageBox



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

22.18 OptionMenu



Display
 		Settings

Entry border

Orientation

Margin width

Packing

Margin height

Alignment

Columns

Adjust last

Spacing

Adjust margin

Help widget

Aligned

Last selected

Homogeneous 

     

Popup enabled 

     

Radio always one 

     

Radio behavior 

     

Resize height 

    

Resize width 

    

Tear off modal



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 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 22-6 shows a sample hierarchy. Note that you cannot have a cascading option menu.

Figure  22-6 Sample Hierarchy for the OptionMenu
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.

22.19 PanedWindow



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.

22.20 PushButton



Display
 		Margins

Label

Top

Font

Bottom

Pixmap

Left

Insensitive pixmap

Right

Cascade pixmap

Width

Arm color

Height

Arm pixmap

Spacing

Select color

Default shadow

Select pixmap

Indicator size

Select insensitive pixmap 

    



Settings
 		Callbacks

Alignment

Activate

Type

Cascading

Resize

Arm

Push button

Disarm

Shadow

Expose

Fill on Arm

Resize

Fill on select

Value changed

Indicator as 

    

Indicator type 

    

Multi click 

    

Set 

     

Visible when off 

     



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.

22.21 RadioBox



Display
 		Settings

Entry border

Orientation

Margin width

Packing

Margin height

Alignment

Columns

Adjust last

Spacing

Adjust margin

Help widget

Aligned

Last selected

Homogeneous 

    

Popup enabled 

    

Radio always one 

    

Radio behavior 

    

Resize height 

    

Resize width 

    

Tear off modal



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.

22.22 RowColumn



Display
 		Settings

Entry border

Orientation

Margin width

Packing

Margin height

Alignment

Columns

Adjust last

Spacing

Adjust margin

Help widget

Aligned

Last selected

Homogeneous 

     

Popup enabled 

   

Radio always one 

   

Radio behavior 

   

Resize height 

   

Resize width 

   

Tear off modal



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 22-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.

Figure  22-7 Resizing Widgets in a RowColumn
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".

22.23 Scale



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.

22.24 ScrollBar



Display
 		Settings
 		Callbacks

Slider size

Orientation

Decrement

Minimum

Direction

Drag

Maximum

Show arrows

Increment

Value 

    

Page decrement

Increment 

    

Page increment

Page increment 

    

To bottom

Initial delay 

    

To top

Repeat delay 

    

Value changed

Trough color 

    

    

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.

22.25 ScrolledList



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 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 22-8:

Figure  22-8 Effective ScrolledList Placement
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.

22.26 ScrolledText



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.

22.27 ScrolledWindow



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, 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.

22.28 SelectionBox



Display
 		Labels

No match string

Apply label

Pattern

Ok label

Max history items

Cancel label

Text String

Help label

Visible item count

List label

Text columns

Selection label

Directory mask

Filter label

Directory

Directory label



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.

22.29 SelectionPrompt



Display
 		Labels

No match string

Apply label

Pattern

OK label

Max history items

Cancel label

Text String

Help label

Visible item count

List label

Text columns

Selection label

Directory mask

Filter label

Directory

Directory label



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.

22.30 Separator



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 22-9.

Figure  22-9 Use of Separator Inside a Menu
You can use Separators inside a RowColumn. Figure 22-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  22-10 Use of Separators in a RowColumn (Horizontal Orientation, 4 Rows)

22.31 Shell



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 WorkShop Visual design hierarchy must have a Shell as its root widget.

Motif has various kinds of Shells but WorkShop Visual groups them into a single widget. The WorkShop Visual Shell can be configured as an Application, Top level, or Dialog Shell using its 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.

22.32 Text



Display
 		Settings

Value

Edit mode

Cursor position

Auto show cursor

Margin width

Editable

Margin height

Pending delete

Maximum length

Cursor visible

Top position

Resize height

Selection threshold

Resize width

Blink rate

Word wrap

Columns

Verify bell

Rows

Scroll horizontal

Font

Scroll vertical 

    

Scroll left side 

    

Scroll top side



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.

22.33 TextField



Display
 		Settings

Value

Edit mode

Cursor position

Auto show cursor

Margin width

Editable

Margin height

Pending delete

Maximum length

Cursor visible

Top position

Resize height

Selection threshold

Resize width

Blink rate

Word wrap

Columns

Verify bell

Rows

Scroll horizontal

Font

Scroll vertical 

    

Scroll left side 

    

Scroll top side



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. The Books on X and Motif section on page 782 provides some suggestions for further reading on this subject.

22.34 ToggleButton



Display
 		Settings
 		Callbacks

Label

Alignment

Activate

Font

Type

Cascading

Pixmap

Resize

Arm

Insensitive pixmap

Push button

Disarm

Cascade pixmap

Shadow

Expose

Arm color

Fill on arm

Resize

Arm pixmap

Fill on select

Value changed

Select color

Indicator on 

    

Select pixmap

Indicator type 

    

Select insensitive pixmap

Multi click 

    

    

Set 

    

    

Visible when off 

    



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 22-11.

Figure  22-11 Radio Buttons and Normal Toggle Buttons
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.

22.35 Mapping Motif Widgets to Microsoft Windows

Following is a list of the Motif widgets which can be selected from within WorkShop Visual in Microsoft Windows mode along with the way in which they are mapped to a Microsoft Windows class.

ApplicationShell
Maps to CFrameWnd.

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.

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.

22.36 Mapping Motif Resources to Microsoft Windows

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.

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.

22.37 Window Styles

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

22.37.1 Shells

All Shells have:

22.37.2 ApplicationShell

In addition to Shell styles, has:

22.37.3 TopLevelShell

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.

22.37.4 DialogShell

In addition to Shell styles, has:

22.37.5 MainWindow and ScrolledWindow

22.37.6 Frame

22.37.7 BulletinBoard, Form, RowColumn, DrawingArea and DialogTemplate

22.37.8 RadioBox

22.37.9 MenuBar, PopupMenu and CascadeButton

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:

The following apply to calls to AppendMenu from a PopupMenu or CascadeButton only:

22.37.10 OptionMenu

22.37.11 FileSelectionBox

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:

If XmNpattern is not set this parameter is NULL

22.37.12 PanedWindow

22.37.13 Label

22.37.14 PushButton

22.37.15 ToggleButton

22.37.16 Scale and Scrollbar

22.37.17 TextField and Text

22.37.18 List


Previous Next Contents Index Doc Set Home