

        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 the 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 or the MenuBar system.  If  *
             the button with the accelerator is within a Popup Menu   *
             system, it must be activatable whenever the focus is in  *
             the Popup Menu system or 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                                          August 26, 1994







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




        August 26, 1994                                          9-5







        OSF/Motif Style Guide
        Activation


                       or a MenuBar), pressing <<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 on 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                                          August 26, 1994







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






















        August 26, 1994                                          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                                          August 26, 1994







                        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 filled square
                              to indicate the on state or an empty
                              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.         *










        August 26, 1994                                          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                                         August 26, 1994







                        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.






        August 26, 1994                                         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 is used to present and edit 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                                         August 26, 1994







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



        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.













        August 26, 1994                                         9-13







        OSF/Motif Style Guide
        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                                         August 26, 1994







                        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 indicator for a CheckButton
             is usually a filled square to indicate the on state or
             an empty square to indicate the off state.  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.           *



        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.




        August 26, 1994                                         9-15







        OSF/Motif Style Guide
        CheckButton


             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:        *

                          +o If the CheckButton was previously unset,  *
                            it must be set.                           *

                          +o If the CheckButton was previously set,    *
                            it must be unset.                         *

                       In all cases the CheckButton must be           *
                       disarmed, and, if the CheckButton is in a      *
                       Menu, the Menu must be unposted.

             BBSSeelleecctt RReelleeaassee 22
                       If the CheckButton was previously unset, it
                       should be set.  If the CheckButton was
                       previously set, it should be unset.  If the
                       CheckButton is in a window, the default
                       action of the window should be activated.

             <<EEnntteerr>> or <<RReettuurrnn>>
                       If the CheckButton is in a window with a       *
                       default action, the default action must be     *
                       activated.  If the CheckButton is in a Menu:   *

                          +o If the CheckButton was previously unset,  *
                            it must be set.                           *

                          +o If the CheckButton was previously set,    *
                            it must be unset.                         *

                          +o 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 is in a Menu, the Menu      *
                       must be unposted.

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









        9-16                                         August 26, 1994







                        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.

















































        August 26, 1994                                         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.  The List must use either    *
             the single or browse selection model.  When a List       *
             element is selected, its contents must be placed in the  *
             Text area.  The default action of the CommandBox must    *
             be to pass the command in the Text area to the           *
             application for execution and to add the command to the  *
             end of the List.  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.

























        9-18                                         August 26, 1994







                        Controls, Groups, and Models Reference Pages
                                                          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
             CommandDialog.











































        August 26, 1994                                         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                                         August 26, 1994







                        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.






















        August 26, 1994                                         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



             Any window can have a default action, although default
             actions are most frequently used in DialogBoxes.  A
             DialogBox should have a default action associated with
             it.  The default action in a window can change
             depending upon which component has the focus.  The
             current default action should correspond to the action
             of some PushButton, called the current default
             PushButton of the window.

             The current default PushButton must be highlighted in    *
             some way, usually by displaying a border around it.      *
             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.

             In a DialogBox, default PushButtons should be in the
             bottom area of PushButtons of the DialogBox.  However,
             if a particular default action is associated with a
             cluster of controls in a window, the corresponding
             default PushButton can be located adjacent to the
             cluster.

             When an explicit focus policy is in use, and the focus
             is outside the window, default highlighting should be
             placed on the PushButton whose action corresponds to
             the default action that would result from moving the
             focus to the window by using keyboard navigation among
             windows.

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

                +o If the focus is in a window, <<EEnntteerr>> and <<CCttrrll>>     *
                  <<RReettuurrnn>> must invoke the default action, and, if    *
                  the focus is in a component in a window other than  *
                  multiline Text, <<RReettuurrnn>> must invoke the default    *
                  action.  These actions must have no other effect    *




        9-22                                         August 26, 1994







                        Controls, Groups, and Models Reference Pages
                                                  Default Activation


                  on the component with the focus, unless the         *
                  default action has some effect.

                +o In list-like and graphics-like collections, when
                  the location cursor is not on an activatable
                  element, BBSSeelleecctt CClliicckk 22 should act like BBSSeelleecctt
                  CClliicckk, followed by invocation of the default
                  action.

                +o When the focus is on a ToggleButton not used for
                  expert activation, BBSSeelleecctt CClliicckk 22 should activate
                  the ToggleButton and then perform the default
                  action.

             Except in the middle of a button motion operation,       *
             <<CCaanncceell>> anywhere in a DialogBox must be equivalent to   *
             activating the CCaanncceell PushButton in the DialogBox.



        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.





























        August 26, 1994                                         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 can 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                                         August 26, 1994







                        Controls, Groups, and Models Reference Pages
                                                           DialogBox


                    by components in the DialogBox.  This action is
                    usually only available in DialogBoxes that
                    provide status information such as a Working
                    DialogBox.  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 Working DialogBox.

             PPaauussee  Must cause the task in progress to be paused.     *
                    This action is commonly found in a Working        *
                    DialogBox 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 Working        *
                    DialogBox 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
             responses to the DialogBox should be presented first,




        August 26, 1994                                         9-25







        OSF/Motif Style Guide
        DialogBox


             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                                         August 26, 1994







                        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:

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

               2.  The user drags elements to the drop location.

               3.  The user drops the elements on the drop location.

               4.  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 it can result in a link.  Transfers from
             writable components can by default result in a copy, a
             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.





        August 26, 1994                                         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
             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 hotspot 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                                         August 26, 1994







                        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.

             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.  This action    *
                    must choose the component to act on by following  *
                    the rules in Section 4.2.2 for operations that    *
                    act on selections.  This action must have the     *
                    mnemonic TT.

             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 without removing the original data      *
                    from the client area.  This action must choose    *
                    the component to act on by following the rules    *
                    in Section 4.2.2 for operations that act on       *
                    selections.  This action must have the mnemonic   *
                    CC.

             CCooppyy LLiinnkk__
                    Must copy a link of the selected portion of data  *
                    to the clipboard without removing the original    *
                    data from the client area.  This action must      *
                    choose the component to act on by following the   *
                    rules in Section 4.2.2 for operations that act    *
                    on selections.  This action must have the         *




        August 26, 1994                                         9-29







        OSF/Motif Style Guide
        Edit Menu


                    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 into a   *
                    client area.  This action must choose the         *
                    component to act on by following the rules in     *
                    Section 4.2.2 for operations that do not act on   *
                    selections.  This action must have the mnemonic   *
                    PP.

             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 into a client area.     *
                    This action must choose the component to act on   *
                    by following the rules in Section 4.2.2 for       *
                    operations that do not act on selections.  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 the clipboard.
                    The remaining data is not compressed to fill the
                    space that was occupied by the cleared data.      *
                    This action must choose the component to act on   *
                    by following the rules in Section 4.2.2 for       *
                    operations that act on selections.  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 the clipboard.  *
                    This action must choose the component to act on   *
                    by following the rules in Section 4.2.2 for       *
                    operations that act on selections.  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 make the primary selection consist of all    *
                    the elements in a component of the client area.   *
                    This action must choose the component to act on   *
                    by following the rules in Section 4.2.2 for       *
                    operations that do not act on selections.  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 from the primary selection all the    *
                    elements in a component of the client area.       *
                    This action must choose the component to act on   *
                    by following the rules in Section 4.2.2 for       *
                    operations that do not act on selections.  If
                    the action uses an accelerator, it should be




        9-30                                         August 26, 1994







                        Controls, Groups, and Models Reference Pages
                                                           Edit Menu


                    <<CCttrrll>> <<\\>>.

             SSeelleecctt PPaasstteedd
                    Must make the primary selection consist of the    *
                    last element or elements pasted into a component  *
                    of the client area.  This action must choose the  *
                    component to act on by following the rules in     *
                    Section 4.2.2 for operations that do not act on   *
                    selections.

             RReesseelleecctt   AAlltt++IInnsseerrtt
                    Must make the primary selection consist of the    *
                    last selected element or elements in a component  *
                    of the client area.  This action must choose the  *
                    component to act on by following the rules in     *
                    Section 4.2.2 for operations that do not act on   *
                    selections.  The action must be available only    *
                    in components that do not support persistent      *
                    selections and only when the current selection    *
                    is empty.  If the action uses an accelerator, it
                    should be <<AAlltt>> <<IInnsseerrtt>>.

             PPrroommoottee   AAlltt++IInnsseerrtt
                    Must promote to the primary selection the         *
                    current selection of a component of the client    *
                    area.  This action must choose the component to   *
                    act on by following the rules in Section 4.2.2    *
                    for operations that act on selections.  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>>.

             You should include Menu items in the order described.
             If you add new Menu items, you should insert them near
             similar elements.

             If you use accelerators for UUnnddoo, CCuutt, CCooppyy, and PPaassttee,  *
             you must use either one or both of the models presented  *
             in the following two tables.

                TTAABBLLEE 99--11..  Edit Menu Accelerators, Model 1

                       EEddiitt MMeennuu IItteemm   AAcccceelleerraattoorr
                       __________________________________
                       UUnnddoo             <<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leettee>>
                       CCooppyy             <<CCttrrll>> <<IInnsseerrtt>>
                       PPaassttee            <<SShhiifftt>> <<IInnsseerrtt>>





        August 26, 1994                                         9-31







        OSF/Motif Style Guide
        Edit Menu


                TTAABBLLEE 99--22..  Edit Menu Accelerators, Model 2

                          EEddiitt MMeennuu IItteemm   AAcccceelleerraattoorr
                          ____________________________
                          UUnnddoo             <<CCttrrll>> <<ZZ>>
                          CCuutt              <<CCttrrll>> <<XX>>
                          CCooppyy             <<CCttrrll>> <<CC>>
                          PPaassttee            <<CCttrrll>> <<VV>>

             In addition, if your keyboard has <<UUnnddoo>>, <<CCuutt>>,
             <<CCooppyy>>, and <<PPaassttee>> keys, these should be supported as
             accelerators for the corresponding Menu items as well.



        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-32                                         August 26, 1994







                        Controls, Groups, and Models Reference Pages
                                                         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.























        August 26, 1994                                         9-33







        OSF/Motif Style Guide
        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.










        9-34                                         August 26, 1994







                        Controls, Groups, and Models Reference Pages
                                                      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
                         allow only 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.



        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.






        August 26, 1994                                         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                                         August 26, 1994







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





        August 26, 1994                                         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                                         August 26, 1994







                        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 at least the        *
             following components:                                    *

                +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.  The List must use either the   *
                  single or browse selection model.                   *

                +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.  The List must use either the single or  *
                  browse selection model.                             *

                +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    *




        August 26, 1994                                         9-39







        OSF/Motif Style Guide
        FileSelectionBox


             directory mask.  Selecting a new directory from the      *
             directory list must not change the search pattern.  A    *
             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 to the contents of    *
             the directory List, and the contents of the filename     *
             Text must correspond to 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 can select a new file as many times as
             desired.  The application must not be notified until     *
             one of the following events occurs:                      *

                +o The user activates the OOKK PushButton.               *

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

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

                +o The user double-clicks BBSSeelleecctt 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.          *






        9-40                                         August 26, 1994







                        Controls, Groups, and Models Reference Pages
                                                    FileSelectionBox


                +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.                                              *



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





































        August 26, 1994                                         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.









































        9-42                                         August 26, 1994







                        Controls, Groups, and Models Reference Pages
                                                 FileSelectionDialog


        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.











































        August 26, 1994                                         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 explicit focus policy requires the user to
             explicitly select which window or component receives
             the keyboard focus.  In explicit focus mode at the
             window level, a user moves the keyboard focus to a
             window by pressing BBSSeelleecctt while the mouse pointer is
             over the window.  Simply moving the mouse pointer over
             a window does not give the window the keyboard focus.
             Because of this, explicit mode is often called click-
             to-type.  In explicit mode within a window, a user
             generally moves the keyboard focus to a specific
             component within a window by pressing BBSSeelleecctt over the
             component.  Pressing BBSSeelleecctt must not move focus to a    *
             component that is not traversable or does not accept     *
             input.  Pressing BBSSeelleecctt in a component that is used
             only to change the visible portion of another
             component, such as a ScrollBar or Sash, should act on
             that component but should not move focus to it.  In      *
             this focus policy, the location of keyboard focus must   *
             be shown by a location cursor.






        9-44                                         August 26, 1994







                        Controls, Groups, and Models Reference Pages
                                                               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.

















































        August 26, 1994                                         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                                         August 26, 1994







                        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.














        August 26, 1994                                         9-47





 o
