

        OSF/Motif Style Guide
        Accelerators


        AAcccceelleerraattoorrss





        DDeessccrriippttiioonn


             An accelerator is a key or key combination that invokes
             the action of some component without the location
             cursor being on the component when the accelerator is
             pressed.  Accelerators are most commonly used to
             activate Menu items without first posting the Menu.
             You should provide accelerators primarily as a matter
             of utility, not for design conformity.

             If the button with an accelerator is within a primary    *
             or secondary window, or within a PullDown Menu system    *
             from its MenuBar, it must be activatable whenever the    *
             input focus is in the window.  If the button with an     *
             accelerator is within a Popup Menu system, it must be    *
             activatable whenever the focus is in the component with  *
             the Popup Menu.

             Applications can provide accelerators for any button
             component.  Implementations must support accelerators    *
             in PushButtons and ToggleButtons that are in Menus.  If  *
             a button has an accelerator, the accelerator must be     *
             shown following the label of the button.























        9-4                                              May 8, 1992








                        Controls, Groups, and Models Reference Pages
                                                          Activation


        AAccttiivvaattiioonn





        DDeessccrriippttiioonn


             This reference page only provides a short description
             of the various types of activation.  Chapter 5
             describes each type in detail.

             BBaassiicc AAccttiivvaattiioonn
                       The basic activation model mimics real life
                       button activation in that pressing on a
                       button activates it.  Clicking BBSSeelleecctt on the  *
                       button must activate the button.  <<SSeelleecctt>> or  *
                       <<SSppaaccee>> on a button with the focus must        *
                       activate the button.  <<EEnntteerr>> or <<RReettuurrnn>> on   *
                       an activatable Menu entry with the focus must  *
                       activate the entry.  In explicit mode,
                       clicking <<CCttrrll>> BBSSeelleecctt on a traversable
                       component should move the focus to it.  In
                       activatable components, it should have no
                       other effect.  In collections it can change
                       the cursored element or the selection as
                       described in Section 4.1.

             AAcccceelleerraattoorrss
                       An accelerator is a key or key combination
                       that invokes the action of some component
                       without the location cursor on the component
                       when the accelerator is pressed.
                       Accelerators are most commonly used to
                       activate Menu items without first posting the
                       Menu.

             MMnneemmoonniiccss
                       A mnemonic is a single character that can be
                       associated with any component that contains a
                       text label.  When the location cursor is on a  *
                       component within a Menu, a MenuBar or the      *
                       same field as a component with a mnemonic,     *
                       typing the mnemonic character must move the    *
                       location cursor to the component and activate  *
                       it.  If a mnemonic is used for an              *
                       OptionButton, for a CascadeButton in a         *
                       MenuBar, or a PushButton that is not in a      *
                       basic group (that is, not in a Panel, a Menu,  *



        May 8, 1992                                              9-5








        OSF/Motif Style Guide
        Activation


                       or a MenuBar), typing <<AAlltt>> and the mnemonic   *
                       anywhere in the window or its Menus must move  *
                       the cursor to the component with that          *
                       mnemonic and must activate it.

             TTeeaarrooffff AAccttiivvaattiioonn

                       Some Menus have TearoffButtons as their first
                       elements.  A TearoffButton is like a
                       PushButton with the special interaction of
                       converting a Menu into a DialogBox, that is,
                       tearing off the Menu from its CascadeButton.   *
                       TearoffButtons must follow the basic           *
                       activation model.  TearoffButtons have a
                       second activation mechanism.  Once a Menu      *
                       with a TearoffButton is posted, pressing       *
                       BBTTrraannssffeerr in the TearoffButton must start a    *
                       tear-off action.  As long as BBTTrraannssffeerr is      *
                       held, a representation of the Menu must        *
                       follow the movements of the pointer.           *
                       Releasing BBTTrraannssffeerr must end the tear-off      *
                       action by unposting the Menu system, creating  *
                       a new window at the current pointer location   *
                       with the contents of the Menu, and in          *
                       explicit pointer mode give focus to the new    *
                       window.

             HHeellpp AAccttiivvaattiioonn
                       Pressing <<HHeellpp>> on a component must invoke     *
                       any context-sensitive help for the component   *
                       or its nearest ancestor with context-          *
                       sensitive help available.  Within
                       DialogBoxes, context-sensitive help should
                       provide help information or the DialogBox as
                       a whole.  <<SShhiifftt>> <<HHeellpp>> should invoke the
                       context-sensitive help mode if it is
                       available.

             PPooppuupp MMeennuu AAccttiivvaattiioonn
                       If the pointer is in an element with an        *
                       inactive Popup Menu and the context of the     *
                       element allows a Popup Menu to be displayed,   *
                       BBMMeennuu PPrreessss must post (activate) the Menu in   *
                       a spring-loaded manner, and clicking BBMMeennuu     *
                       must post (activate) the Menu.

             DDeeffaauulltt AAccttiivvaattiioonn
                       In a DialogBox, pressing <<EEnntteerr>> or <<RReettuurrnn>>   *
                       (except in Text), or double-clicking BBSSeelleecctt   *
                       must activate the default PushButton in the    *



        9-6                                              May 8, 1992








                        Controls, Groups, and Models Reference Pages
                                                          Activation


                       DialogBox.  If the double click is in a
                       component used for making selections or
                       choices, such as List or RadioBox, the
                       element under the pointer must be selected or
                       should be chosen before the default
                       PushButton is activated.

             EExxppeerrtt AAccttiivvaattiioonn
                       Some elements, usually PushButtons and
                       ToggleButtons, can have expert actions
                       associated with them.  BBSSeelleecctt CClliicckk 22 must    *
                       activate any expert action for the element.
                       Expert action should only be available in a
                       Panel, and the expert action of all the
                       buttons should be similar.  The expert action
                       should include the regular action of the
                       component in a more global manner.

             CCaanncceell AAccttiivvaattiioonn
                       <<CCaanncceell>> is available in most context to stop
                       the current interaction, including canceling
                       drag-and-drop operations, unposting
                       TearoffMenus, canceling DialogBoxes,
                       unposting Menu systems, and canceling
                       scrolling operations.



        RReellaatteedd IInnffoorrmmaattiioonn


             See Chapter 5 for more information about the activation
             model.




















        May 8, 1992                                              9-7








        OSF/Motif Style Guide
        Basic Controls


        BBaassiicc CCoonnttrroollss





        DDeessccrriippttiioonn


             Basic controls are components that only take simple
             input.  They are distinct from field controls in that
             they are usually elements of navigation fields rather
             than fields themselves.  Basic controls must have no     *
             internal navigation.  The following text describes the
             basic controls:

             SSeeppaarraattoorr        Draws a separating line within
                              windows, between Menu items, and
                              between Panes of a PanedWindow.  A
                              Separator allows no application
                              interaction.

             LLaabbeell            Displays static text and images.  A
                              Label presents application information
                              to users.

             PPuusshhBBuuttttoonn       A button used to activate an
                              operation.  A PushButton contains a
                              Label that indicates the operation of
                              the button.  The Label can contain
                              text or an image.

             CCaassccaaddeeBBuuttttoonn    A button used to display a PullDown
                              Menu.  A CascadeButton contains a
                              Label that indicates the Menu
                              displayed.  CascadeButtons can also
                              contain an arrow graphic after the
                              Label to distinguish it from
                              PushButtons and to indicate the
                              direction of the cascading Menu.

             OOppttiioonnBBuuttttoonn     A button used to display an Option
                              Menu.  An Option Menu allows for a one
                              of many selection.  An OptionButton
                              contains a Label that indicates the
                              current state of the Option Menu, and
                              a bar graphic to distinguish it from a
                              PushButton.





        9-8                                              May 8, 1992








                        Controls, Groups, and Models Reference Pages
                                                      Basic Controls


             TToogggglleeBBuuttttoonn     A button with two states: on and off.
                              A ToggleButton contains a Label that
                              indicates the state of the
                              ToggleButton when it is set.
                              Normally, preceding the Label is a
                              graphic indicator of the state of the
                              ToggleButton.

             CChheecckkBBuuttttoonn      A ToggleButton in a group of
                              ToggleButtons where any number of the
                              ToggleButtons can be on at a time.
                              The graphic indicator for a
                              CheckButton is usually a raised square
                              to indicate the on state or a pressed
                              square to indicate the off state.

             RRaaddiiooBBuuttttoonn      A ToggleButton in a group of
                              ToggleButtons where only one of the
                              ToggleButtons can be on at a time.
                              The graphic indicator for a
                              RadioButton is usually a filled
                              diamond or circle to indicate the on
                              state or an empty diamond or circle to
                              indicate the off state.

             TTeeaarrooffffBBuuttttoonn    A button used for tearing off a Menu
                              to create a dialog representation of
                              the Menu contents.  A TearoffButton
                              tears off a Menu in place when
                              activated, or is dragged to tear off
                              and move in one action.  A
                              TearoffButton usually contains a
                              dashed line graphic representing
                              perforations.

             A single line Text control can be configured to act
             like a basic control.



        NNaavviiggaattiioonn


             Basic controls must have no internal navigation.         *









        May 8, 1992                                              9-9








        OSF/Motif Style Guide
        Basic Controls


        OOtthheerr OOppeerraattiioonnss


             Activatable basic controls follow the basic activation
             model described in Section 5.1.



        RReellaatteedd IInnffoorrmmaattiioonn


             For more information, see the reference pages for each
             basic control.








































        9-10                                             May 8, 1992








                        Controls, Groups, and Models Reference Pages
                                                        Basic Groups


        BBaassiicc GGrroouuppss





        DDeessccrriippttiioonn


             Basic groups of controls are used to organize groups of
             basic controls.  The following text describes the basic
             groups:

             PPaanneell            Organizes a collection of basic
                              controls in a horizontal, vertical, or
                              2-dimensional layout.  A Panel is
                              usually composed of just one type of
                              control.

             MMeennuu             Organizes a collection of buttons,
                              labels, and separators in a
                              horizontal, vertical, or 2-dimensional
                              layout within a separate Menu window.
                              There are three types of Menus:
                              PullDown, Popup, and Option.  A Menu
                              is only available while it is popped
                              up or pulled down.

             MMeennuuBBaarr          Organizes a collection of
                              CascadeButtons in a horizontal layout
                              at the top of a MainWindow.



        NNaavviiggaattiioonn


             The <<||vv>>, <<<<-->>, <<-->>>>, and <<||^^>> direction keys must         *
             navigate within a basic group according to the           *
             navigation model described in Chapter 3.



        RReellaatteedd IInnffoorrmmaattiioonn


             For more information, see the reference pages for each
             basic group.





        May 8, 1992                                             9-11








        OSF/Motif Style Guide
        Canvas


        CCaannvvaass





        DDeessccrriippttiioonn


             A Canvas should be used to present and edit graphics.    *
             This component must be composed of an area for           *
             presenting and editing graphics.



        NNaavviiggaattiioonn


             Canvas navigation is unspecified.



        OOtthheerr OOppeerraattiioonnss


             Most Canvas operations are unspecified.  A description
             of the specified Canvas operations follows:

             <<HHeellpp>>    Must provide any available help for the        *
                       Canvas.























        9-12                                             May 8, 1992








                        Controls, Groups, and Models Reference Pages
                                                       CascadeButton


        CCaassccaaddeeBBuuttttoonn





        DDeessccrriippttiioonn


             A CascadeButton should be used to post a PullDown Menu.  *
             This component must be composed of a button, with        *
             either a text or graphics Label.  Following the Label,
             this component should also include an arrow graphic,
             pointing in the direction that the Menu will be posted
             to distinguish it from a PushButton.  The graphic is
             usually not shown in a MenuBar.



        IIlllluussttrraattiioonn


















        NNaavviiggaattiioonn


             A CascadeButton must have no internal navigation.        *











        May 8, 1992                                             9-13








        OSF/Motif Style Guide
        CascadeButton


        OOtthheerr OOppeerraattiioonnss


             CascadeButtons follow the Menu activation model
             described in Section 3.3.  The following text describes
             the other operations of this component:

             <<HHeellpp>>    Must provide any available help for the        *
                       CascadeButton.



        RReellaatteedd IInnffoorrmmaattiioonn


             For more information, see the reference pages for
             Menus.




































        9-14                                             May 8, 1992








                        Controls, Groups, and Models Reference Pages
                                                         CheckButton


        CChheecckkBBuuttttoonn





        DDeessccrriippttiioonn


             A CheckButton should be used to set options in the
             application.  A CheckButton is a special case of a
             ToggleButton.  Any number of CheckButtons can be set at
             the same time.

             This component must be composed of a text or graphic     *
             Label, and a graphic that indicates the state of the     *
             CheckButton.  The graphic should be a square preceding
             the Label, and should have two distinctive states
             indicating the set and unset states of the CheckButton.
             On color systems, the on state color can be distinct
             from general application colors to visually distinguish
             the on state.



        IIlllluussttrraattiioonn











        NNaavviiggaattiioonn


             CheckButtons must have no internal navigation.           *












        May 8, 1992                                             9-15








        OSF/Motif Style Guide
        CheckButton


        OOtthheerr OOppeerraattiioonnss


             The following text describes the CheckButton
             operations:

             BBSSeelleecctt PPrreessss
                       Must arm the CheckButton.  If the CheckButton  *
                       was previously unset, it must show the         *
                       CheckButton in the set state.  If the          *
                       CheckButton was previously set, it must show   *
                       the CheckButton in the unset state.

             BBSSeelleecctt RReelleeaassee
                       If the release happens in the same             *
                       CheckButton that the press occurred in, then   *
                       if the CheckButton was previously unset, it    *
                       must be set, or if the CheckButton was         *
                       previously set, it must be unset.  In all      *
                       cases the CheckButton must be disarmed, and    *
                       if the CheckButton was in a Menu, the Menu     *
                       must be unposted.

             BBSSeelleecctt RReelleeaassee
                       If the CheckButton is in a window, it should   *
                       toggle the state of the CheckButton and        *
                       activate the default action of the window.     *
                       If the CheckButton is in a Menu, it should     *
                       toggle the state of the CheckButton            *

             <<EEnntteerr>> or <<RReettuurrnn>>                                      *
                       If the CheckButton is in a window, the         *
                       default action of the window is activated.     *
                       Otherwise, if the CheckButton is in a Menu     *
                       and was previously unset, it must be set.  If  *
                       the CheckButton is in a Menu and was           *
                       previously set, it must be unset.  In both     *
                       cases the CheckButton must be disarmed, and    *
                       the Menu must be unposted.

             <<SSeelleecctt>> or <<SSppaaccee>>
                       If the CheckButton was previously unset, it    *
                       must be set.  If the CheckButton was           *
                       previously set, it must be unset.  In both     *
                       cases the CheckButton must be disarmed, and    *
                       if the CheckButton was in a Menu, the Menu     *
                       must be unposted.

             <<HHeellpp>>    Must provide any available help for the        *
                       CheckButton.



        9-16                                             May 8, 1992








                        Controls, Groups, and Models Reference Pages
                                                         CheckButton


        RReellaatteedd IInnffoorrmmaattiioonn


             For more information, see the reference pages for
             RadioButton and ToggleButton.
















































        May 8, 1992                                             9-17








        OSF/Motif Style Guide
        CommandBox


        CCoommmmaannddBBooxx





        DDeessccrriippttiioonn


             A CommandBox is a special-purpose composite component
             for command entry that provides a built-in command
             history mechanism.  The CommandBox must be composed of   *
             a Text component with a command line prompt for command  *
             input, and a List component above the Text component     *
             for a command history area.  When a command is entered   *
             in the Text component, it must be added to the end of    *
             the List component and made visible.  This must not      *
             change the state of the selection in the List if one     *
             exists.  The List component can be scrollable.  The      *
             List navigation actions <<||^^>>, <<||vv>>, <<CCttrrll>> <<BBeeggiinn>>, and    *
             <<CCttrrll>> <<EEnndd>> must be available from the Text component   *
             for moving the cursored element within the List and      *
             thus changing the contents of the Text.  The List
             navigation actions <<PPaaggeeUUpp>> and <<PPaaggeeDDoowwnn>> should also
             be available from the Text component for moving the
             cursored element within the List.



        IIlllluussttrraattiioonn























        9-18                                             May 8, 1992








                        Controls, Groups, and Models Reference Pages
                                                          CommandBox


        RReellaatteedd IInnffoorrmmaattiioonn


             For more information, see the reference page for
             CommandDialog.
















































        May 8, 1992                                             9-19








        OSF/Motif Style Guide
        CommandDialog


        CCoommmmaannddDDiiaalloogg





        DDeessccrriippttiioonn


             A CommandDialog should be used to enter commands for
             processing.  It should not interrupt the user's
             interaction with the application.  It should include a
             CommandBox.



        IIlllluussttrraattiioonn


















        RReellaatteedd IInnffoorrmmaattiioonn


             For more information, see the reference page for
             DialogBox.













        9-20                                             May 8, 1992








                        Controls, Groups, and Models Reference Pages
                                                         Composition


        CCoommppoossiittiioonn





        DDeessccrriippttiioonn


             The Composition group should be used to organize
             components in an arbitrary layout.  The layout style
             can be either arbitrary, in even rows and columns, or
             so that the position of components is relative to the
             Composition component and the components it contains.
             This component is composed of an area for organizing
             components.



        NNaavviiggaattiioonn


             This group must follow the navigation model as           *
             described in Chapter 3.



        RReellaatteedd IInnffoorrmmaattiioonn


             For more information, see the reference pages for each
             layout group.





















        May 8, 1992                                             9-21








        OSF/Motif Style Guide
        Default Activation


        DDeeffaauulltt AAccttiivvaattiioonn





        DDeessccrriippttiioonn


             The default action of a DialogBox is activated
             according to the following rules:

                +o When the input focus is on a PushButton other than  *
                  the default, and if the component accepts input,    *
                  pressing <<EEnntteerr>> or <<RReettuurrnn>> must activate the      *
                  PushButton.  The highlighting must be removed from  *
                  the default PushButton.  The highlighting can be
                  moved to the new PushButton.  When the focus
                  policy is implicit, the changes in highlighting
                  should have a delay to prevent flicker when moving
                  the pointer through the components.

                +o When the focus is on a component used for entry     *
                  selections, and if the control accepts input,       *
                  pressing BBSSeelleecctt CClliicckk 22 must select the current    *
                  entry and should activate the default action of     *
                  the DialogBox.  Pressing <<EEnntteerr>> or <<RReettuurrnn>> must   *
                  activate the default action of the DialogBox, but   *
                  not the action of the component.

                +o When the input focus is on any other component,     *
                  and if the component accepts input, pressing        *
                  <<EEnntteerr>> or <<RReettuurrnn>> must activate the default       *
                  action of the DialogBox.

                +o When the focus is not on any component, pressing    *
                  <<EEnntteerr>> or <<RReettuurrnn>> must activate the default       *
                  action of the DialogBox.

             The default action in a window may change depending
             upon which component has the focus.  When the focus is
             on a PushButton, its action must be the default action,
             and the PushButton must show default highlighting.  If
             the default action in a window varies, some PushButton
             must always have default highlighting, except when
             there is no current default action.







        9-22                                             May 8, 1992








                        Controls, Groups, and Models Reference Pages
                                                  Default Activation


        RReellaatteedd IInnffoorrmmaattiioonn


             See Chapter 5 for general information about the
             activation model and default activation.
















































        May 8, 1992                                             9-23








        OSF/Motif Style Guide
        DialogBox


        DDiiaallooggBBooxx





        DDeessccrriippttiioonn


             A DialogBox should be used to group components in a
             window secondary to the main tasks of the application.
             Although a DialogBox may contain any components, a
             simple DialogBox is composed of a Label and PushButtons
             for supplying a response to the DialogBox.  The
             OSF/Motif toolkit provides a number of ready-designed
             DialogBoxes for common uses: CommandDialog,
             FileSelectionDialog, MessageDialog, PromptDialog, and
             SelectionDialog.  There are also a number of different
             types of MessageDialogs:  ErrorDialog,
             InformationDialog, QuestionDialog, WorkingDialog, and
             WarningDialog.  The illustration on this reference page
             shows a typical DialogBox.

             DialogBox PushButtons should use the following common
             labels and actions.  The actions are in the approximate
             sequence in which they should appear in DialogBoxes.

             YYeess    Must indicate an affirmative response to a        *
                    question posed in the DialogBox, and then close   *
                    the window.  While YYeess is not an active-voice
                    label, it implies a positive response to a
                    question in a QuestionDialog or a WarningDialog.
                    Only use YYeess if it is a clear answer to the
                    question.

             NNoo     Must indicate a negative response to a question   *
                    posed in the DialogBox, and then close the        *
                    window.  While NNoo is not an active-voice label,
                    it implies a negative response to a question in
                    a QuestionDialog.  Only use NNoo if it is a clear
                    answer to the question.

             OOKK     Must cause the application to apply any changes   *
                    and perform related actions specified by          *
                    components in the DialogBox, and then dismiss     *
                    the DialogBox.  While OOKK is not an active-voice
                    label, its usage is too common to change.

             CClloossee  Should cause the current DialogBox to be closed
                    without performing any of the actions specified



        9-24                                             May 8, 1992








                        Controls, Groups, and Models Reference Pages
                                                           DialogBox


                    by components in the DialogBox.  This action is
                    usually only available in a DialogBoxes that
                    provide status information such as a
                    WorkingDialogBox.  This label can also be used
                    if the actions in the DialogBox cannot be
                    reversed, in which case this label replaces
                    CCaanncceell after the first irreversible action is
                    performed.

             AAppppllyy  Must apply any changes and perform the related    *
                    actions specified by the components in the        *
                    DialogBox.

             RReettrryy  Must cause the task in progress to be attempted   *
                    again.  This action is commonly found in message
                    boxes that report an error.

             SSttoopp   Must end the task in progress at the next         *
                    possible breaking point.  This action is
                    commonly found in a WorkingDialogBox.

             PPaauussee  Must cause the task in progress to be paused.     *
                    This action is commonly found in a                *
                    WorkingDialogBox, and should be used in           *
                    combination with RReessuummee.

             RReessuummee Must cause a previously paused task to resume.    *
                    This action is commonly found in a                *
                    WorkingDialogBox, and should be used in           *
                    combination with PPaauussee.

             RReesseett  Must cancel any user changes that have not been   *
                    applied to the application.  It must also reset   *
                    the status of the DialogBox to the state since    *
                    the last time the DialogBox action was applied    *
                    or to the initial state of the DialogBox.

             CCaanncceell Must close the DialogBox without performing any   *
                    DialogBox actions not yet applied to the          *
                    application.  Pressing <<CCaanncceell>> anywhere in the   *
                    DialogBox, except during a cancelable drag        *
                    operation, must perform the action of this        *
                    button.

             HHeellpp   Must provide any help for the DialogBox.          *

             You should arrange PushButton actions in DialogBoxes
             like other PushButtons, according to order and
             frequency of use.  The common action PushButtons should
             be ordered as presented in the previous list.  Positive



        May 8, 1992                                             9-25








        OSF/Motif Style Guide
        DialogBox


             responses to the DialogBox should be presented first,
             followed by negative responses and canceling responses.
             HHeellpp should always be the last action on the right.



        IIlllluussttrraattiioonn



























        NNaavviiggaattiioonn


             A DialogBox must follow the navigation model described   *
             in Chapter 3.



        RReellaatteedd IInnffoorrmmaattiioonn


             For more information, see the reference pages for
             CommandDialog, ErrorDialog, FileSelectionDialog,
             InformationDialog, MessageDialog, PromptDialog,
             QuestionDialog, SelectionDialog, WarningDialog, and
             WorkingDialog.



        9-26                                             May 8, 1992








                        Controls, Groups, and Models Reference Pages
                                                       Drag-and-Drop


        DDrraagg--aanndd--DDrroopp





        DDeessccrriippttiioonn



             Drag-and-drop provides a quick and simple model for
             transferring data within and between applications.  A
             drag-and-drop interaction is accomplished in four
             steps:

                +o The user selects elements to drag and grabs them
                  with the pointer, or grabs an unselected element.

                +o The user drags elements to the drop location.

                +o The user drops the elements on the drop location.

                +o The component dropped on processes the drop
                  action.

             Pressing TTrraannssffeerr in a draggable element and moving the  *
             pointer must start a drag-and-drop interaction.  If a    *
             drag is initiated in an unselected region and the        *
             pointer is over two possible draggable elements, the     *
             drag must occur on the highest draggable element in the  *
             stacking order.  This also implies that in nested
             draggable elements the drag occurs from the smallest
             draggable element under the pointer.

             When BBSSeelleecctt is used for dragging operations, its use    *
             must supersede the use of BBSSeelleecctt MMoottiioonn in the          *
             selection models described in Section 4.1.

             Any successful drag-and-drop transfer from a read-only   *
             component should by default result in a copy of the      *
             data, but can result in a link.  Transfers from
             writable components can by default result in either a
             copy, link or a move.  <<SShhiifftt>> BBTTrraannssffeerr RReelleeaassee must    *
             force a move operation if possible; otherwise, the       *
             operation must fail.  <<CCttrrll>> BBTTrraannssffeerr RReelleeaassee must      *
             force a copy operation if possible; otherwise, the       *
             operation must fail.  <<CCttrrll>> <<SShhiifftt>> BBTTrraannssffeerr RReelleeaassee   *
             must force a link operation if possible; otherwise, the  *
             operation must fail.




        May 8, 1992                                             9-27








        OSF/Motif Style Guide
        Drag-and-Drop


             If a system provides drag-and-drop help, pressing
             <<HHeellpp>> during a drag-and-drop operation should allow a
             the posting of a DialogBox with the help information
             and the possible choices for continuing the drag-and-
             drop operation.  Pressing <<CCaanncceell>> during a drag
             operation must cancel the current drag operation and
             return the system to the state prior to the start of
             the drag operation.

             Releasing BBTTrraannssffeerr must end a drag-and-drop operation.  *
             When a user releases BBTTrraannssffeerr, the drop operation must  *
             occur at the location of the hot spot of the drag icon   *
             pointer.  The drop must occur into the highest drop      *
             site in the stacking order.  This also implies that in
             a group of nested drop sites the drop occurs into the
             smallest drop site under the pointer.



        RReellaatteedd IInnffoorrmmaattiioonn


             See Section 4.3 for more information on the drag-and-
             drop model, and for information on quick transfer and
             the selection models.




























        9-28                                             May 8, 1992








                        Controls, Groups, and Models Reference Pages
                                                           Edit Menu


        EEddiitt MMeennuu





        DDeessccrriippttiioonn


             The common EEddiitt Menu contents are described as follows.
             Note that you should only include those functions
             actually supported by your application.  The EEddiitt Menu
             can contain a TearoffButton.  The illustration on this
             reference page shows an EEddiitt Menu.

             UU__nnddoo   AAlltt++BBaacckkssppaaccee
                    Must reverse the most recently executed action.   *
                    To provide a visual cue to the user, the UUnnddoo
                    selection title should be dynamically modified
                    to indicate what is being undone.  For example,
                    if the most recently executed action was a
                    paste, the action name would be UUnnddoo ppaassttee.
                    Your application should be able to undo all of
                    the actions in the EEddiitt Menu.  This action must   *
                    have the mnemonic UU.  If this action has an       *
                    accelerator, it must be <<AAlltt>> <<BBaacckkSSppaaccee>>.

             CCuutt__   SShhiifftt++DDeell
                    Must remove the selected portion of data from     *
                    the client area to the clipboard buffer           *
                    according to the rules in Chapter 4.  This        *
                    action must have the mnemonic TT.  If this action
                    has an accelerator, <<SShhiifftt>> <<DDeelleettee>>, <<AAlltt>>
                    <<CCuutt>>, and <<AAlltt>> <<SShhiifftt>> <<DDeelleettee>> should be
                    supported.

             CC__ooppyy   CCttrrll++IInnss
                    Must copy the selected portion of data to the     *
                    clipboard buffer without removing the original    *
                    data from the client area according to the rules  *
                    in Chapter 4.  This action must have the          *
                    mnemonic CC.  If this action has an accelerator,
                    <<CCttrrll>> <<IInnsseerrtt>>, <<AAlltt>> <<CCooppyy>>, and <<AAlltt>> <<CCttrrll>>
                    <<IInnsseerrtt>> should be supported.

             CCooppyy LLiinnkk__
                    Must copy a link of the selected portion of data  *
                    to the clipboard buffer without removing the      *
                    original data from the client area according to   *
                    the rules in Chapter 4.  This action must have    *



        May 8, 1992                                             9-29








        OSF/Motif Style Guide
        Edit Menu


                    the mnemonic KK.

             PP__aassttee   SShhiifftt++IInnss
                    Must paste the contents of the clipboard buffer   *
                    into a client area according to the rules in      *
                    Chapter 4.  This action must have the mnemonic    *
                    PP.  If this action has an accelerator, <<SShhiifftt>>
                    <<IInnsseerrtt>> should be supported.

             PPaassttee LL__iinnkk
                    Must paste a link of the data represented by the  *
                    contents of the clipboard buffer into a client    *
                    area according to the rules in Chapter 4.  This   *
                    action must have the mnemonic LL.

             CCllee__aarr  Must remove a selected portion of data from the   *
                    client area without copying it to a clipboard     *
                    buffer.  The remaining data is not compressed to
                    fill the space that was occupied by the cleared
                    data.  This action must have the mnemonic EE.      *

             DD__eelleettee Must remove a selected portion of data from the   *
                    client area without copying it to a clipboard     *
                    buffer.  This action must have the mnemonic DD.

             SSeelleecctt AAllll   CCttrrll++//
                    Must add all the elements in the collection with  *
                    the location cursor to the primary selection.
                    If the action uses an accelerator, it should be
                    <<CCttrrll>> <<//>>.

             DDeesseelleecctt AAllll   CCttrrll++\\
                    Must remove all the elements in the collection    *
                    with the location cursor from the primary         *
                    selection.  If the action uses an accelerator,
                    it should be <<CCttrrll>> <<\\>>.

             SSeelleecctt PPaasstteedd
                    Must make the last element or elements pasted     *
                    into the collection with the location cursor      *
                    into the primary selection.

             RReesseelleecctt   AAlltt++IInnsseerrtt
                    Must reselect the last selected element or        *
                    elements in the component with the location       *
                    cursor to the primary selection.  The action      *
                    must only be available for components that do     *
                    not support persistent selections.  If the
                    action uses an accelerator, it should be <<AAlltt>>
                    <<IInnsseerrtt>>.



        9-30                                             May 8, 1992








                        Controls, Groups, and Models Reference Pages
                                                           Edit Menu


             PPrroommoottee   AAlltt++IInnsseerrtt Must promote the current selection  *
                    of the collection with the location cursor to     *
                    the primary selection.  This action must only be  *
                    available for components that support persistent  *
                    selections.  If the action uses an accelerator,
                    it should be <<AAlltt>> <<IInnsseerrtt>>.



        IIlllluussttrraattiioonn


























        RReellaatteedd IInnffoorrmmaattiioonn


             See Chapter 4 for more information on the MenuBar
             system, and for general information about Menu design.












        May 8, 1992                                             9-31








        OSF/Motif Style Guide
        ErrorDialog


        EErrrroorrDDiiaalloogg





        DDeessccrriippttiioonn


             An ErrorDialog should be used to convey a message about
             a user error.  It should stop user interaction with the
             application until it is dismissed.  It should include
             an error symbol, a message, and one of the following
             button arrangements.

             OOKK CCaanncceell
             OOKK CCaanncceell HHeellpp



        IIlllluussttrraattiioonn
















        RReellaatteedd IInnffoorrmmaattiioonn


             For more information, see the reference page for
             DialogBox.











        9-32                                             May 8, 1992








                        Controls, Groups, and Models Reference Pages
                                                      Field Controls


        FFiieelldd CCoonnttrroollss





        DDeessccrriippttiioonn


             Field controls are components that use internal
             navigation controls.  Field controls should be
             navigation fields.  The following text describes the
             field controls:

             SSaasshh             Used to set the boundary between two
                              components.  A Sash is usually a small
                              square on the boundary between two
                              components.  The separated components
                              are called Panes, and a group of
                              Panes, Separators, and Sashes is
                              called a PanedWindow.

             SSccaallee            Used to set or display a value in a
                              range.  A Scale is usually composed of
                              a slider, moving within an element
                              that indicates the size of the range,
                              and a Label that indicates the current
                              value.  The position of the slider
                              indicates the value relative to the
                              range.  The slider is moved directly
                              by using the mouse pointer, or by
                              using the arrow keys.  A Scale can
                              also have buttons with arrow graphics
                              for moving the slider with the mouse.

             SSccrroollllBBaarr        Used to scroll the visible area of a
                              component.  A ScrollBar is usually
                              composed of a slider, moving within an
                              element that indicates the full size
                              of the component, and buttons with
                              arrow graphics for moving the slider
                              with the mouse.  The slider indicates
                              the relative position and size of the
                              visible area of the component.  The
                              slider is moved directly by using the
                              mouse pointer, or by using the arrow
                              keys.






        May 8, 1992                                             9-33








        OSF/Motif Style Guide
        Field Controls


             LLiisstt             Used for selecting elements from a
                              list of elements.  A List can allow
                              multiple items to be selected or can
                              be constrained to only allow one item
                              to be selected at a time.  A List is
                              usually composed of a vertical list of
                              items.  A List can also have both
                              horizontal and vertical ScrollBars for
                              scrolling the visible portion of the
                              list of items.

             TTeexxtt             Used for displaying, entering, and
                              modifying text.  There are single line
                              and multiple line variants.  Multiline
                              Text can have both horizontal and
                              vertical ScrollBars for scrolling the
                              visible portion of the text area.

             CCaannvvaass           Used for displaying, entering, and
                              modifying graphics.  A Canvas can have
                              both horizontal and vertical
                              ScrollBars for scrolling the visible
                              portion of the drawing area.



        NNaavviiggaattiioonn


             Field controls have navigation that is specific to the
             component.  See the reference pages for each field
             control for information about its navigation.



        OOtthheerr OOppeerraattiioonnss


             Field controls have operations that are specific to the
             component.  See the reference pages for each field
             control for information about its operations.












        9-34                                             May 8, 1992








                        Controls, Groups, and Models Reference Pages
                                                      Field Controls


        RReellaatteedd IInnffoorrmmaattiioonn


             For more information, see the reference pages for each
             field control.
















































        May 8, 1992                                             9-35








        OSF/Motif Style Guide
        File Menu


        FFiillee MMeennuu





        DDeessccrriippttiioonn


             The common FFiillee Menu contents are described as follows.
             Note that you should only include those functions
             actually supported by your application.  If the label
             FFiillee is not appropriate to the context of your
             application, you can choose a different, more
             appropriate label.  The FFiillee Menu can contain a
             TearoffButton.  The illustration on this reference page
             shows a FFiillee Menu.

             NN__eeww       Must create a new file.  The NNeeww operation     *
                       must clear existing data from the client       *
                       area.  If completion of the operation will     *
                       obliterate current changes to the file, you    *
                       must display a DialogBox, asking the user      *
                       about saving changes.  This action must have   *
                       the mnemonic NN.

             OO__ppeenn .. .. .. Must open an existing file.  The OOppeenn         *
                       operation must prompt the user for the name    *
                       of the file with a DialogBox.  The title bar
                       should be updated with the name of the newly
                       opened file.  If completion of the operation   *
                       will obliterate current changes to the file,   *
                       you must display a DialogBox, asking the user  *
                       about saving changes.  This DialogBox should
                       be displayed after the user selects a new
                       file.  This action must have the mnemonic OO.   *

             SS__aavvee      Must save the currently opened file without    *
                       removing the existing contents of the client   *
                       area.  If the currently opened file has no     *
                       name, SSaavvee must prompt for a filename with a   *
                       DialogBox.  This action must have the          *
                       mnemonic SS.

             SSaavvee AA__ss .. .. .. Must save the currently opened file under  *
                       a new name without removing the existing       *
                       contents of the client area.  The SSaavvee AAss      *
                       operation must prompt for the name of the      *
                       file with a DialogBox.  If the user tries to   *
                       save the new file under an existing name,      *



        9-36                                             May 8, 1992








                        Controls, Groups, and Models Reference Pages
                                                           File Menu


                       SSaavvee AAss must alert the user with a DialogBox   *
                       of a possible loss of data.  This action must  *
                       have the mnemonic AA.

             PP__rriinntt     Must schedule a file for printing.  If your    *
                       application requires specific printing         *
                       information before printing, the operation     *
                       must first request that information with a     *
                       DialogBox, and the entry title must be         *
                       followed by an ellipses.  Printing
                       information can also be specified for the
                       application in the OOppttiioonnss Menu.  This action  *
                       must have the mnemonic PP.

             CC__lloossee     Can be supplied in applications that have
                       multiple independent primary windows.  This    *
                       action must not be supplied in applications    *
                       with a single primary window, or multiple      *
                       dependent primary windows.  This action must   *
                       only close the current primary window and its  *
                       associated secondary windows; that is, the     *
                       window family.  This action must have the      *
                       mnemonic CC.  You can include this action even
                       though it is similar to the CClloossee action in
                       the window Menu.  This ensures that users
                       have a way to close the primary window even
                       if they are not running a compliant window
                       manager.  Applications should prompt the user
                       to save any unsaved changes if the action
                       would cause loss of data.

             EExx__iitt      Must end the current application and all       *
                       windows associated with it.  This action is
                       equivalent to closing all primary windows of
                       the application.  If completion of the         *
                       operation will obliterate current changes to   *
                       the file, you must display a DialogBox,        *
                       asking the user about saving changes.  This    *
                       action must have the mnemonic XX.  You should
                       include this action even though it is similar
                       to the CClloossee action in the window Menu.  This
                       ensures that users have a way to end the
                       application even if they are not running a
                       compliant window manager.  Applications
                       should prompt the user to save any unsaved
                       changes if the action would cause loss of
                       data.  If your application does not have a
                       FFiillee Menu, put EExxiitt at the end of the first
                       PullDown Menu.




        May 8, 1992                                             9-37








        OSF/Motif Style Guide
        File Menu


        IIlllluussttrraattiioonn


























        RReellaatteedd IInnffoorrmmaattiioonn


             See Chapter 6 for more information on the MenuBar
             system, and for general information about Menu design.





















        9-38                                             May 8, 1992








                        Controls, Groups, and Models Reference Pages
                                                    FileSelectionBox


        FFiilleeSSeelleeccttiioonnBBooxx





        DDeessccrriippttiioonn


             A FileSelectionBox is a special-purpose composite
             component for file selection.  It can be used to
             traverse through directories, view the files and
             subdirectories in them, and then select files.  The      *
             FileSelectionBox must be composed of the following       *
             elements:                                                *

                +o A Text component for displaying and editing a       *
                  directory mask used to select the files to be       *
                  displayed.  The directory mask must be a string     *
                  specifying the base directory to be examined and a  *
                  search pattern.                                     *

                +o A List component for displaying filenames.  The     *
                  file list should display all files and              *
                  subdirectories in the base directory that match     *
                  the search pattern.                                 *

                +o A List component for displaying subdirectories.     *
                  The directory list should display the               *
                  subdirectories of the base directory, as well as    *
                  the base directory itself and its parent            *
                  directory.                                          *

                +o A Text component for displaying and editing a       *
                  filename.                                           *

                +o A group of PushButtons, labeled OOKK, FFiilltteerr,         *
                  CCaanncceell, and HHeellpp.  If the FileSelectionBox is used  *
                  to perform a specific action to the selected        *
                  files, OOKK can be replaced by a label describing     *
                  the action to be done.

                +o Additional elements can be added by an
                  application.

             The user must be able to select a new directory to       *
             examine by scrolling through the list of directories     *
             and selecting the desired directory or by editing the    *
             directory mask.  Selecting a new directory from the      *
             directory list must not change the search pattern.  A    *



        May 8, 1992                                             9-39








        OSF/Motif Style Guide
        FileSelectionBox


             user must be able to select a new search pattern by      *
             editing the directory mask.

             The List navigation actions <<||^^>>, <<||vv>>, <<CCttrrll>> <<BBeeggiinn>>,    *
             and <<CCttrrll>> <<EEnndd>> must be available from the Text         *
             components for moving the cursored element within each   *
             List and thus changing the contents of the Text.  The
             List navigation actions <<PPaaggeeUUpp>> and <<PPaaggeeDDoowwnn>> should
             also be available from the Text components for moving
             the cursored element within each List.  The contents of  *
             the directory Text must correspond with the contents of  *
             the directory List, and the contents of the filename     *
             Text must correspond with the contents of the filename   *
             List.

             The user must be able to select a file by scrolling      *
             through the list of filenames and selecting the desired  *
             file or by entering the filename directly into the Text  *
             component.  Selecting a file from the list causes that
             filename to appear in the file selection Text
             component.

             The user may select a new file as many times as
             desired.  The application must not be notified until     *
             one of the following events occurs:                      *

                +o The OOKK PushButton is activated.                     *

                +o <<EEnntteerr>> or <<RReettuurrnn>> is pressed while the Text       *
                  component has the keyboard focus.                   *

                +o <<EEnntteerr>> or <<RReettuurrnn>> is pressed while the location   *
                  cursor is on an item in the file list.              *

                +o BBSSeelleecctt is double-clicked on an item in the file    *
                  list.                                               *

             The FileSelectionBox must initiate a directory and file  *
             search when any of the following occurs:                 *

                +o The FileSelectionBox is initialized.                *

                +o The user activates the FFiilltteerr PushButton.           *

                +o The user double-clicks or presses <<EEnntteerr>> or        *
                  <<RReettuurrnn>> on an item in the directory list.          *

                +o The user presses <<EEnntteerr>> or <<RReettuurrnn>> while the      *
                  directory mask text edit area has the keyboard      *
                  focus.                                              *



        9-40                                             May 8, 1992








                        Controls, Groups, and Models Reference Pages
                                                    FileSelectionBox


        IIlllluussttrraattiioonn





































        RReellaatteedd IInnffoorrmmaattiioonn


             For more information, see the reference page for
             FileSelection DialogBox.










        May 8, 1992                                             9-41








        OSF/Motif Style Guide
        FileSelectionDialog


        FFiilleeSSeelleeccttiioonnDDiiaalloogg





        DDeessccrriippttiioonn


             A FileSelectionDialog should be used to enter the name
             of a file for processing.  It should not interrupt the
             user's interaction with the application.  It should
             include a FileSelectionBox.



        IIlllluussttrraattiioonn




































        9-42                                             May 8, 1992








                        Controls, Groups, and Models Reference Pages
                                                 FileSelectionDialog


        RReellaatteedd IInnffoorrmmaattiioonn


             For more information, see the reference page for
             DialogBox.
















































        May 8, 1992                                             9-43








        OSF/Motif Style Guide
        Focus


        FFooccuuss





        DDeessccrriippttiioonn


             The keyboard focus model is defined by a focus policy.
             A focus policy is a specific mechanism for moving the
             focus among windows and components.  The implicit and    *
             explicit focus policies must be supported.

             In the implicit focus policy, also called the pointer,
             real-estate driven, or point-to-type policy, the
             keyboard focus moves to the window or component into
             which a user moves the mouse pointer.  No explicit
             action is performed to set the keyboard focus in the
             implicit focus model.  Keyboard events are sent to the
             window or component that the mouse pointer is in, more
             specifically to the component that the mouse pointer is
             in.  In implicit mode, the keyboard focus tracks the
             mouse pointer.  Because of this, there is no way to
             move the keyboard focus from the keyboard using
             implicit mode.  In this focus policy, the location
             cursor for keyboard events does not need to be shown;
             however, the application can show it.

             The mouse pointer always behaves as if the focus policy
             is implicit; that is, mouse events always go to the
             window and the component that the mouse pointer is in.

             The explicit focus policy requires the user to
             explicitly select which window or component receives
             the keyboard focus.  Mouse events are sent to the        *
             component that the pointer is over, so the mouse         *
             pointer must always behave as if the focus policy is     *
             implicit, even when the focus policy is explicit.  In
             explicit focus mode, a user moves the keyboard focus to
             a window or component by pressing BBSSeelleecctt or <<CCttrrll>>
             BBSSeelleecctt while the mouse pointer is over a window or
             component.  Simply moving the mouse pointer over a
             window or component does not give the window or
             component the keyboard focus.  In this focus policy,     *
             the location of keyboard focus must be shown by a        *
             location cursor.

             In explicit mode, keyboard focus moves explicitly among
             the components in a window, as well as among the



        9-44                                             May 8, 1992








                        Controls, Groups, and Models Reference Pages
                                                               Focus


             windows.  Moving the keyboard focus among components in
             a window is called window navigation.  Keyboard events
             go to the component in the window with the keyboard
             focus.



        RReellaatteedd IInnffoorrmmaattiioonn


             See Chapter 2 for more information about the focus
             model.









































        May 8, 1992                                             9-45








        OSF/Motif Style Guide
        Frame


        FFrraammee





        DDeessccrriippttiioonn


             A Frame should be used to frame other components.  It
             simply provides a decorative border.



        OOtthheerr OOppeerraattiioonnss


             This component can indicate the input focus.



































        9-46                                             May 8, 1992








                        Controls, Groups, and Models Reference Pages
                                                      Framing Groups


        FFrraammiinngg GGrroouuppss





        DDeessccrriippttiioonn


             Framing groups are used to frame groups of components
             as the following text describes:

             FFrraammee            Draws framing decorations around a
                              component.

             SSccrroolllleeddWWiinnddooww   Frames a component and adds ScrollBars
                              for scrolling the visible area of the
                              component.

             MMaaiinnWWiinnddooww       Organizes the contents of a primary
                              window.  A MainWindow frames the
                              client area and can optionally include
                              ScrollBars, a MenuBar, a command area,
                              and a message area.



        NNaavviiggaattiioonn


             These groups must follow the navigation model as         *
             described in Chapter 3.



        RReellaatteedd IInnffoorrmmaattiioonn


             For more information, see the reference pages for each
             framing group.













        May 8, 1992                                             9-47






 u
