















        Chapter 4.  SSeelleeccttiioonn







             The selection model determines how elements are
             selected from a group of elements.  This chapter
             describes the selection models that are used by the
             various components of an application.  OSF/Motif
             compliant applications use an object-action selection
             model.  In an object-action selection model, the user
             first selects an object and then performs an action on
             it.  The object-action selection model mimics real
             life, so it is a familiar process to the user and
             increases the user's sense of control over
             applications.

             Objects include not only recognizable objects like
             windows, PushButtons, and List elements, but also
             component elements that are not always recognized as
             discrete objects, like individual letters of a text
             file.  Applications can also treat a group of elements
             as a single element, either in a contiguous range or as
             a noncontiguous group.  This chapter describes the
             following topics:

                +o Selection models, which determine how elements in
                  a collection are selected for later action.

                +o Selection actions, which perform actions directly
                  on a selection, such as cut, copy, and paste.










        August 26, 1994                                          4-1







        OSF/Motif Style Guide


        4.1  SSeelleeccttiioonn MMooddeellss


             Selection is used to mark one or more of a group of
             elements simply for highlighting the elements, or so
             they can be moved, copied, or otherwise manipulated by
             the application.

             Groups of elements can be organized into the following
             three types of collections:

                +o List-like collections

                +o Text-like collections

                +o Graphics-like collections

             In list-like collections, when the pointer or location
             cursor is in the collection, the pointer or location
             cursor is considered to be on an element.

             In text-like collections, when the pointer or location
             cursor is in the collection, the pointer or location
             cursor is considered to be between two elements.  The
             name "text-like" refers to Text components in insert
             mode where the insertion cursor is always between two
             letters.  List-like and text-like collections are
             usually ordered as linear collections; that is, the
             collections are treated as if the elements were
             connected as a series of elements in one dimension.

             In graphics-like collections, the pointer and location
             cursor can be either on or between elements.
             Graphics-like collections are usually ordered as 2-
             dimensional collections.  That is, the ordering of
             elements in the collection depends on both the
             horizontal and vertical position of the element within
             each collection.

             The notion of "on" depends on the manipulation model
             presented by the control.  For example, "on" can mean
             that the cursor is within the bounds of the element, or
             it can mean that the cursor is on the boundary of the
             element, or the element can have handles, and "on"
             means that the cursor is on one of the handles.

             OSF/Motif compliant systems must support the five        *
             different selection models.  Each model is used where
             appropriate in applications to limit the type of
             selections the user can make.  For example, a List can
             limit selection to a single element where the user is




        4-2                                          August 26, 1994







                                                           Selection


             only allowed to make one choice.  The five selection
             models are as follows:

             SSiinnggllee SSeelleeccttiioonn
                    Used to select a single element in a collection.
                    Clicking BBSSeelleecctt on an element selects it and
                    deselects the previously selected element in the
                    collection.  Single selection is described in
                    Section 4.1.1.

             BBrroowwssee SSeelleeccttiioonn
                    Used to allow browsing through single selection
                    collections.  Browse selection is also used to
                    select a single element of a collection.  Browse
                    selection allows the user to browse through the
                    elements by dragging BBSSeelleecctt through the
                    elements in the collection.  Browse selection
                    highlights each element as it is traversed, and
                    gives the application an opportunity to provide
                    information about each element as it is
                    highlighted.  Releasing BBSSeelleecctt on an element
                    selects it and deselects the previously selected
                    element.  Browse selection is described in
                    Section 4.1.2.

             MMuullttiippllee SSeelleeccttiioonn
                    Used to select or deselect multiple elements of
                    a collection.  Clicking BBSSeelleecctt on an unselected
                    element adds that element to the current
                    selection.  Clicking BBSSeelleecctt on a selected
                    element removes that element from the current
                    selection.  Multiple selection is described in
                    Section 4.1.3.

             RRaannggee SSeelleeccttiioonn
                    Used to select a contiguous range of elements in
                    a collection.  Clicking BBSSeelleecctt on an element
                    selects the single element and deselects any
                    previous selection.  BBSSeelleecctt MMoottiioonn over a range
                    of elements selects all the elements within the
                    range and deselects any previous selection.
                    Range selection is described in Section 4.1.4.

             DDiissccoonnttiigguuoouuss SSeelleeccttiioonn
                    Used for selecting multiple discontiguous ranges
                    of elements in a collection.  Clicking or
                    dragging BBSSeelleecctt operates just as for range
                    selection.  Discontiguous selection also allows
                    <<CCttrrll>> BBSSeelleecctt to be used to add or remove
                    selection ranges.  Discontiguous selection is
                    described in Section 4.1.5.




        August 26, 1994                                          4-3







        OSF/Motif Style Guide


             The choice of the selection model should be made on a
             collection-by-collection basis.  Some components, like
             Text, enforce a selection model.  Other components,
             like a List, allow the application or the user to
             determine the selection model.

             Variants of these selection models may be needed for
             collections that are especially dense, when elements
             are organized in layers, when 3-dimensional selection
             is needed, when elements are hierarchically organized,
             or in other situations not covered by this guide.
             Selection models for such cases should not deviate
             unnecessarily from the standard selection models.

             In all selection models, the selected element or group
             of elements should be visually highlighted in some way.
             Highlighting the selection can be done in the following
             ways:

                +o Using any one of the location cursor mechanisms

                +o Inverting the colors of the selection

                +o Drawing a solid or dashed box around the elements
                  of the selection

             The selection can also be an empty selection; that is,
             it is possible for no items to be selected in a
             collection.  This commonly occurs in text-like
             collections where the location cursor is between two
             elements, or when the user has deselected all the
             elements.



        4.1.1  MMoouussee--BBaasseedd SSiinnggllee SSeelleeccttiioonn


             The single selection model is the simplest selection
             model.  In the single selection model, when BBSSeelleecctt is   *
             clicked in a deselected element, the location cursor     *
             must move to that element, that element must be          *
             selected, and any other selection in the collection      *
             must be deselected.











        4-4                                          August 26, 1994







                                                           Selection


        4.1.2  MMoouussee--BBaasseedd BBrroowwssee SSeelleeccttiioonn


             The browse selection model is very similar to the
             single selection model.  In browse selection, like
             single selection, only a single element is selected at
             a time.  In the browse selection model, when BBSSeelleecctt is  *
             released in a selectable element, that element must be   *
             selected, and any other selection in the collection      *
             must be deselected.  As BBSSeelleecctt is dragged through       *
             selectable elements, each element under the pointer      *
             must be selected, and the previously selected element    *
             must be deselected.  The selection must remain on the    *
             element where BBSSeelleecctt is released, and the location      *
             cursor must be moved there.  The browse selection model
             gives the application an opportunity to provide
             information about each element as it is highlighted.



        4.1.3  MMoouussee--BBaasseedd MMuullttiippllee SSeelleeccttiioonn


             Multiple selection allows the user to select or
             deselect multiple single elements of a collection.       *
             Clicking BBSSeelleecctt on an unselected element must add that  *
             element to the current selection in the collection.      *
             Clicking BBSSeelleecctt on a selected element must remove that  *
             element from the current selection in the collection.    *
             Clicking BBSSeelleecctt on an element must move the location    *
             cursor to that element.

             With multiple selection, the user can select any group
             of elements in a collection, including discontiguous
             groups, all the elements, or none of the elements.
             Because multiple selection requires one mouse click for
             each element selected, although a simple model, it is
             not well-suited for selecting large groups of elements.
             BBSSeelleecctt MMoottiioonn can optionally toggle a range of
             elements.  (See Section 4.1.5 for a description of
             range toggling.)



        4.1.4  MMoouussee--BBaasseedd RRaannggee SSeelleeccttiioonn


             The range selection model allows the user to select
             multiple contiguous elements of a collection.  The
             description of this selection model assumes that drag
             and drop is not integrated with selection.  Integrating




        August 26, 1994                                          4-5







        OSF/Motif Style Guide


             dragging and selection is described in Section 4.3.

             In the range selection model, pressing BBSSeelleecctt must set  *
             an aanncchhoorr on the element, or at the position where       *
             BBSSeelleecctt was pressed, and must deselect all elements in   *
             the collection.  The anchor and the current position of  *
             the pointer determine the current range.  As BBSSeelleecctt is  *
             dragged through the collection, the current range must   *
             be highlighted.  When BBSSeelleecctt is released, the anchor    *
             must not move, and all the elements within the current   *
             range must be selected.

             In text-like collections, elements are ordered
             linearly, and a tteexxtt ppooiinntteerr is always considered to be
             between elements at a point near the actual pointer
             position.  The anchor point must be the text pointer     *
             position when BBSSeelleecctt is pressed, and the current range  *
             must consist of all elements between the anchor point    *
             and the current text pointer position.

             In graphics-like and list-like collections, a marquee,
             or highlighted rectangle, is typically used to indicate
             the current range of the selection.  The current range   *
             must consist of those elements that fall completely      *
             within the marquee.  If a marquee selection is started
             when the pointer is on an element, that element can be
             used as an anchor element, and should be used as an
             anchor element if the collection is arranged as a list
             or matrix.  If there is an anchor element, the marquee   *
             must always be made large enough to completely enclose   *
             it.  Otherwise, an anchor point is used, which must be   *
             the point at which BBSSeelleecctt was pressed, and must         *
             determine one corner of the marquee.  If the collection
             is arranged as a list or matrix, and the pointer is on
             an element, the marquee should be extended to
             completely enclose the element under the pointer.        *
             Otherwise, the marquee must be extended to the pointer   *
             position.

             Marquee selection can be implemented so that it is used
             only when BBSSeelleecctt is pressed in the background; other
             selection models, not described in this style guide,
             can be used when BBSSeelleecctt is pressed on an element.  If   *
             marquee selection is used, even if only when started in  *
             the background, clicking BBSSeelleecctt on a selectable         *
             element must make it an anchor element, select it, and   *
             deselect all other elements.

             The user can extend the range selection using <<SShhiifftt>>
             BBSSeelleecctt.  When <<SShhiifftt>> BBSSeelleecctt is pressed, the anchor    *
             remains unchanged, and an extended range for the         *




        4-6                                          August 26, 1994







                                                           Selection


             selection is determined, based on one of the following   *
             extension models:

             RReesseelleecctt       The extended range must be determined by  *
                            the anchor and the current pointer        *
                            position, in exactly the same manner as   *
                            when the selection was initially made.    *

             EEnnllaarrggee OOnnllyy   The selection can only be enlarged.  The  *
                            extended range is determined by the       *
                            anchor and the current pointer position,  *
                            but then must be enlarged to include the  *
                            current selection.                        *

             BBaallaannccee BBeeaamm   A balance point is defined at the
                            midpoint of the current selection.  When  *
                            <<SShhiifftt>> BBSSeelleecctt is pressed on the         *
                            opposite side of the balance point from   *
                            the anchor, this model must work exactly  *
                            like the reselect model.  When <<SShhiifftt>>    *
                            BBSSeelleecctt is pressed, or a navigation       *
                            action modified by <<SShhiifftt>> is started on  *
                            the same side of the balance point as     *
                            the anchor, this model must move the      *
                            anchor to the opposite end of the         *
                            selection, and then must work exactly     *
                            like the reselect model.  In graphics-
                            like collections, balancing the anchor
                            is done separately in each dimension.

             As <<SShhiifftt>> BBSSeelleecctt is dragged through the collection,
             the extended range should be highlighted, and selected
             elements outside of it should be dehighlighted.  When    *
             BBSSeelleecctt is released, the anchor must not move, all the   *
             elements within the extended range must be selected,     *
             and all the elements outside of it must be deselected.

             Text-like collections should use the balance beam
             model.  The extension model used by other collections
             depends on the purpose of the collection.

             In the range selection model, clicking <<CCttrrll>> BBSSeelleecctt
             should move the location cursor to the position of the
             pointer without affecting the current selection.











        August 26, 1994                                          4-7







        OSF/Motif Style Guide


        4.1.5  MMoouussee--BBaasseedd DDiissccoonnttiigguuoouuss SSeelleeccttiioonn


             The discontiguous selection mechanism allows the user
             to make multiple simultaneous range selections.  It is
             an extension of the range selection model.  The
             description of this selection model assumes that drag
             and drop is not integrated with selection.  Integrating
             dragging and selection is described in Section 4.3.

             The behavior of BBSSeelleecctt in the discontiguous selection   *
             model must be exactly the same as in the range           *
             selection model, and after setting the anchor with       *
             BBSSeelleecctt, <<SShhiifftt>> BBSSeelleecctt must work exactly as in the     *
             range selection model.

             The primary difference between the range selection
             model and the discontiguous selection model is the use
             of <<CCttrrll>> BBSSeelleecctt.  In the range selection model,
             <<CCttrrll>> BBSSeelleecctt is only used to move the position of the
             location cursor without disrupting the current
             selection.  In the discontiguous model, <<CCttrrll>> BBSSeelleecctt
             is used to toggle the selection state of an element or
             a range of elements.

             If the current selection is empty, <<CCttrrll>> BBSSeelleecctt CClliicckk
             can simply move the location cursor, but leave the
             anchor alone and leave all elements deselected.          *
             Otherwise, if <<CCttrrll>> BBSSeelleecctt is clicked, the anchor and  *
             location cursor must move to that point, and if <<CCttrrll>>   *
             BBSSeelleecctt is clicked on an element, the selection state    *
             of that element must be toggled, and that element must   *
             become the anchor element.

             <<CCttrrll>> BBSSeelleecctt MMoottiioonn must be used to toggle the         *
             selection state of a range of elements.  The range       *
             itself must be determined exactly as for BBSSeelleecctt         *
             MMoottiioonn.  Releasing <<CCttrrll>> BBSSeelleecctt must toggle the        *
             selection state of the elements in the range according   *
             to one of two models:

             AAnncchhoorr TTooggggllee     Toggling is based upon an anchor
                               element.  If the range is anchored by  *
                               a point, and is not empty, the anchor  *
                               element must be set to the element     *
                               within the range that is nearest to    *
                               the anchor point.  Toggling must set   *
                               the selection state of all elements    *
                               in the range to the inverse of the     *
                               initial state of the anchor element.
                               This is the model recommended for




        4-8                                          August 26, 1994







                                                           Selection


                               toggling.

             FFuullll TTooggggllee       The selection state of each element    *
                               in the extended range must be          *
                               toggled.

             As <<CCttrrll>> BBSSeelleecctt is dragged through the collection,
             highlighting should be used to indicate the current
             range and the selection state of each element that
             would result from releasing <<CCttrrll>> BBSSeelleecctt at the
             current position.

             After using <<CCttrrll>> BBSSeelleecctt to toggle a selection,        *
             <<SShhiifftt>> BBSSeelleecctt or <<CCttrrll>> <<SShhiifftt>> BBSSeelleecctt must be able   *
             to be used to extend the range of toggled elements.      *
             The extended range must be determined in exactly the     *
             same way as when <<SShhiifftt>> BBSSeelleecctt is used to extend a     *
             range selection.

             When <<CCttrrll>> <<SShhiifftt>> BBSSeelleecctt is released, the selection   *
             state of elements added to the range must be determined  *
             by the toggle model as previously described.  If         *
             elements are removed from the range, they must either    *
             revert to their state prior to the last use of <<CCttrrll>>    *
             BBSSeelleecctt, or change to the state opposite from the        *
             elements remaining within the extended range.

             As <<SShhiifftt>> BBSSeelleecctt or <<CCttrrll>> <<SShhiifftt>> BBSSeelleecctt is dragged
             through the collection, highlighting should be used to
             indicate the current range and the selection state of
             each element that would result from releasing <<SShhiifftt>>
             BBSSeelleecctt or <<CCttrrll>> <<SShhiifftt>> BBSSeelleecctt at the current
             position.



        4.1.6  KKeeyybbooaarrdd SSeelleeccttiioonn


             Selections can be made by using the keyboard as well as
             the mouse.  Two keyboard selection models are
             available: normal mode and add mode.

             Normal mode is used for making simple contiguous
             selections from the keyboard.  Normal mode is a
             navigation/selection mode where the location cursor is
             never disjoint from the current selection.  In
             collections where the location cursor is on an element,
             the element with the location cursor is ordinarily
             selected; if it is not, pressing <<SSeelleecctt>> or <<SSppaaccee>>
             moves the selection to the cursored element.




        August 26, 1994                                          4-9







        OSF/Motif Style Guide


             Add mode is used for making more complex and possibly
             disjoint selections.  Add mode is a
             navigation/selection mode where the location cursor can
             move independent of the current selection.  Even in
             collections that do not support discontiguous
             selections, add mode allows the selection to be
             unaffected by keyboard navigation.

             Browse selections must only support normal mode.         *
             Single and multiple selections must only support add     *
             mode.  Range selection must support normal mode and can
             also support add mode.  Discontiguous selections must    *
             support both modes.  The default mode for range and      *
             discontiguous selections must be normal mode.  <<SShhiifftt>>   *
             <<FF88>> must switch between add mode and normal mode if     *
             both modes are supported.  When switching from normal
             to add mode, if the cursored element is the only
             element selected in the collection, it should be
             deselected.  Mouse-based selection must not change       *
             based on the keyboard selection mode.

             In editable components, add mode is a temporary mode     *
             that must be exited when an operation is performed on    *
             the selection or when the selection is deselected.



        4.1.6.1  KKeeyybbooaarrdd--BBaasseedd SSiinnggllee SSeelleeccttiioonn


             Collections using the single selection model must use    *
             add mode.  In add mode, the navigation keys for the      *
             collection must move the location cursor independent     *
             from the selected element.  If <<SSeelleecctt>> or <<SSppaaccee>> is    *
             pressed on an unselected element, it must select the     *
             element with the location cursor, and it must deselect   *
             any previous selection in the collection.



        4.1.6.2  KKeeyybbooaarrdd--BBaasseedd BBrroowwssee SSeelleeccttiioonn


             Collections using the browse selection model must use    *
             normal mode.  The navigation keys must move the          *
             location cursor and select the cursored element,         *
             deselecting any other element.  If the application has   *
             deselected all elements or if the cursor is left         *
             disjoint from the selection, <<SSeelleecctt>> or <<SSppaaccee>> must    *
             select the cursored element and deselect any other       *
             element.




        4-10                                         August 26, 1994







                                                           Selection


        4.1.6.3  KKeeyybbooaarrdd--BBaasseedd MMuullttiippllee SSeelleeccttiioonn


             Collections using the multiple selection model must use  *
             add mode.  The navigation keys for the collection must   *
             move the location cursor independent from the current    *
             selection.  <<SSeelleecctt>> or <<SSppaaccee>> on an unselected         *
             element must add the element to the current selection.   *
             <<SSeelleecctt>> or <<SSppaaccee>> on a selected element must remove    *
             the element from the current selection.



        4.1.6.4  KKeeyybbooaarrdd--BBaasseedd RRaannggee SSeelleeccttiioonn


             Collections using the range selection model must         *
             initially use normal mode.  This allows a keyboard-
             based behavior similar to dragging with the mouse.

             In normal mode, navigation keys must move the location   *
             cursor and deselect the current selection.  If the       *
             cursor is on an element, it must be selected.  The       *
             anchor must move with the location cursor.  However, in  *
             text-like collections, a different model can be used in  *
             which the anchor must instead remain at its current      *
             location, except that, if the current selection is not   *
             empty, it must be deselected and the anchor must be      *
             moved to the location of the cursor prior to             *
             navigation.

             <<SSeelleecctt>> or <<SSppaaccee>> (except in a Text component) must    *
             move the anchor to the cursor, deselect the current      *
             selection, and, if the cursor is on an element, select   *
             the element.  Unless the anchor is on a deselected       *
             item, <<SShhiifftt>> <<SSeelleecctt>> or <<SShhiifftt>> <<SSppaaccee>> (except in     *
             Text) must extend the selection from the anchor to the   *
             cursor, based on the extension model used by <<SShhiifftt>>     *
             BBSSeelleecctt.

             Using <<SShhiifftt>> in conjunction with the navigation keys    *
             must extend the selection, based on the extension model  *
             used by <<SShhiifftt>> BBSSeelleecctt.  If the current selection is    *
             empty, the anchor must first be moved to the cursor.     *
             The cursor must then be moved according to the           *
             navigation keys, and the selection must be extended      *
             based on the extension model used by <<SShhiifftt>> BBSSeelleecctt.

             In add mode, <<SSeelleecctt>>, <<SSppaaccee>>, <<SShhiifftt>> <<SSeelleecctt>>, and    *
             <<SShhiifftt>> <<SSppaaccee>> must work exactly as in normal mode.     *
             However, ordinary navigation must simply move the        *




        August 26, 1994                                         4-11







        OSF/Motif Style Guide


             location cursor, but must leave the anchor unchanged.    *
             Shifted navigation must move the location cursor         *
             according to the navigation keys, and the selection      *
             must be extended based on the extension model used by    *
             <<SShhiifftt>> BBSSeelleecctt.                                         *

             In Text, both <<SSppaaccee>> and <<SShhiifftt>> <<SSppaaccee>> must insert a  *
             space character.



        4.1.6.5  KKeeyybbooaarrdd--BBaasseedd DDiissccoonnttiigguuoouuss SSeelleeccttiioonn


             Collections using the discontiguous selection model      *
             must initially use normal mode.  In the discontiguous
             selection model, add mode is not only a separate model
             of interaction but also an extension to the range
             selection model that allows the user to select
             discontiguous elements.

             In normal mode, all keyboard operations must have the    *
             same effect as in the range selection model.  In normal
             mode, discontiguous selections cannot be made using the
             keyboard.

             In add mode, <<SSeelleecctt>> or <<SSppaaccee>> must move the anchor    *
             to the location cursor and initiate toggling.  If the    *
             location cursor is on an element, the selection state    *
             of that element must be toggled, but the selection       *
             state of all other elements must remain unchanged.       *
             <<SShhiifftt>> <<SSeelleecctt>> or <<SShhiifftt>> <<SSppaaccee>> and shifted          *
             navigation operations must extend the selection between  *
             the anchor and the location cursor, based on the toggle  *
             mechanism used by <<CCttrrll>> BBSSeelleecctt.



        4.1.7  CCaanncceelliinngg aa SSeelleeccttiioonn


             <<CCaanncceell>> must cancel or undo any incomplete motion       *
             operation used for selection.  Once <<CCaanncceell>> is pressed  *
             to cancel a motion operation, the application must       *
             ignore subsequent key and button releases until after    *
             all buttons and keys are released.  <<CCaanncceell>> during a
             range selection should leave all elements, except
             possibly for the cursored element, deselected.           *
             <<CCaanncceell>> while extending or toggling must leave the      *
             selection state of all elements as they were prior to    *
             the button press.




        4-12                                         August 26, 1994







                                                           Selection


        4.1.8  AAuuttoossccrroolllliinngg aanndd SSeelleeccttiioonn



             If the user drags the pointer out of a scrollable        *
             collection during a motion-based selection operation,    *
             autoscrolling must be used to scroll the collection in   *
             the direction of the pointer.  If the user presses       *
             <<CCaanncceell>> with BBSSeelleecctt pressed, the selection operation   *
             must be canceled as described in Section 4.1.7.



        4.1.9  SSeelleeccttiinngg aanndd DDeesseelleeccttiinngg AAllll EElleemmeennttss


             There are two special keyboard-based selection
             mechanisms for selecting (via <<CCttrrll>> <<//>> ) and
             deselecting (via <<CCttrrll>> <<\\>> ) all the elements in a
             collection.  <<CCttrrll>> <<//>> in a collection using multiple,  *
             range, or discontiguous selection must select all the    *
             elements in a collection, place the anchor at the        *
             beginning of the collection, and leave the location      *
             cursor at its previous position.

             Deselection differs between add mode and normal mode.    *
             In add mode, <<CCttrrll>> <<\\>> must deselect all the elements   *
             in a collection.  In normal mode, <<CCttrrll>> <<\\>> must        *
             deselect all the elements in a collection, except the    *
             element with the location cursor if the location cursor  *
             is being displayed.  In either case, it must leave the   *
             location cursor at its current location and move the     *
             anchor to the location cursor.  An application can
             deselect all elements in a collection regardless of the
             state of add mode or the selection model.



        4.1.10  UUssiinngg MMnneemmoonniiccss ffoorr EElleemmeennttss


             Collections can also support mnemonics associated with
             its elements if the elements have labels.  Pressing a    *
             mnemonic key while the collection has the keyboard       *
             focus must be equivalent to moving the location cursor   *
             to the element and pressing <<SSeelleecctt>> or <<SSppaaccee>>.









        August 26, 1994                                         4-13







        OSF/Motif Style Guide


        4.2  SSeelleeccttiioonn AAccttiioonnss



             Each collection maintains its own selection.  A
             selection need not contain any elements, in which case
             it is said to be an empty selection.  At any time,
             there is one selection called the primary selection,
             which is the last selection explicitly started by the
             user.

             Clicking BBSSeelleecctt or <<CCttrrll>> BBSSeelleecctt moves the primary
             selection to a collection only when it results in
             making a selection that is not empty.  When <<SShhiifftt>>
             BBSSeelleecctt is clicked, an implementation can move the
             primary selection to the component even if the
             resulting selection is empty.  Dragging BBSSeelleecctt,         *
             <<SShhiifftt>> BBSSeelleecctt, or <<CCttrrll>> BBSSeelleecctt must move the         *
             primary selection to the component if a button release   *
             during the pointer motion could have potentially         *
             selected any element.

             A selection is said to be persistent if it is
             highlighted even when it is not the primary selection.

             PPeerrssiisstteenntt
                  There are two variants of persistent selections:
                  persistent always, in which the current selection
                  is always highlighted, and persistent on focus, in
                  which the current selection is only highlighted
                  when it is the primary selection or when the
                  collection has the keyboard focus.  In either
                  case, stronger highlighting should be used when
                  the current selection is also the primary
                  selection.  When focus is in the collection, <<AAlltt>>
                  <<IInnsseerrtt>> can be used to promote the current
                  selection to the primary selection.

             NNoonnppeerrssiisstteenntt
                  The collection only highlights a primary
                  selection.  When the primary selection is lost to
                  another collection, the current selection is set
                  to empty.  When focus is in the collection, and it
                  does not have the primary selection, <<AAlltt>>
                  <<IInnsseerrtt>> can be used to restore the previous
                  selection and make it the primary selection.

             Collections that are never editable (such as
             noneditable Lists) should always use persistent
             selections.  Collections that are editable can use
             either persistent or non-persistent selections.




        4-14                                         August 26, 1994







                                                           Selection


             When the user makes or changes a selection, the
             application can display information about the
             selection, but it should not perform any other action
             that uses the selected elements.  For example,
             selecting a file from a List of files should not
             automatically open the file.  Such actions should
             require additional user interaction.



        4.2.1  DDeessttiinnaattiioonn CCoommppoonneenntt



             The destination component is used to identify the
             component on which certain operations, primarily data
             transfer operations, act.  There is only one
             destination component at a time.  When using an          *
             explicit focus policy, the destination component must    *
             be the editable component that last had focus.  When     *
             using a pointer focus policy, the destination component  *
             must be the editable component that last received mouse  *
             button or keyboard input.

             Special highlighting should be used to identify the
             destination component.  In Text, a solid insertion
             cursor can be shown.



        4.2.2  OOppeerraattiioonn TTaarrggeettss



             Once a selection is made, the elements of the selection
             can be acted on using selection actions.  Some common
             selection actions are delete, cut, copy, and paste,
             although your application is not limited to these.
             This section and the following one describe the way
             many selection operations work.  Operations that
             transfer data are described in greater detail in
             Section 4.3.

             The user may invoke an operation that can act on a
             selection in some component.  A keyboard operation can
             be used, or a control can be activated, which performs
             the operation.  There can be a number of components in
             a window to which the action could be applied, and it
             may not be clear which component is the target.  This
             could be the case, for example, when selecting CCooppyy
             from the EEddiitt Menu, or when typing <<CCttrrll>> <<IInnsseerrtt>>, the




        August 26, 1994                                         4-15







        OSF/Motif Style Guide


             accelerator for CCooppyy.  For operations that act on
             selections, use the following hierarchy of rules to
             determine which component's selection to act on:

               1.  If the keyboard focus is in a component (or a      *
                   Popup Menu of a component) that supports           *
                   selections, the action must act on that            *
                   component.

               2.  Otherwise, if the keyboard focus is in a window
                   (or a Menu of a window) with a main component
                   that has a persistent selection, it should act on
                   the main component.

               3.  Otherwise, if the keyboard focus is in the window
                   (or a Menu of the window) that has the
                   destination component, and the destination
                   component contains a persistent selection that is
                   not empty, it should act on the destination
                   component.

               4.  Otherwise, if the keyboard focus is in the same
                   window (or a Menu of the window) that has the
                   primary selection, it should act on the component
                   with the primary selection.

               5.  Otherwise, if the keyboard focus is in a window
                   (or a Menu of a window) that has only one
                   editable component with a persistent selection,
                   then it can act on that component.

               6.  Otherwise, invoking the action should have no
                   effect, except to signal an error or post a
                   DialogBox.

             Similarly, the user may invoke an operation that
             transfers data to a component or otherwise uses a
             component in some way, and, again, it may not be clear
             which component should be used.  This could be the
             case, for example, when selecting PPaassttee from the EEddiitt
             Menu, or when typing <<SShhiifftt>> <<IInnsseerrtt>>, the accelerator
             for PPaassttee.  For operations that do not act on
             selections, use the following hierarchy of rules:

               1.  If the keyboard focus is in a component (or a      *
                   Popup Menu of a component) that supports the       *
                   action, the action must be applied to that         *
                   component.

               2.  Otherwise, if the keyboard focus is in a window
                   (or a Menu of a window) with a main component




        4-16                                         August 26, 1994







                                                           Selection


                   that supports the action, it should be applied to
                   the main component.

               3.  Otherwise, if the keyboard focus is in the window
                   (or a Menu of the window) that has the
                   destination component, and the destination
                   component supports the action, it should be
                   applied to the destination component.

               4.  Otherwise, invoking the action should have no
                   effect, except to signal an error or post a
                   DialogBox.



        4.2.3  SSeelleeccttiioonn OOppeerraattiioonnss



             This subsection describes some of the standard
             operations available through the EEddiitt Menu and through
             standard keyboard bindings that operate on selections.

             A collection can either enable or disable pending
             delete, which controls the circumstances under which
             the selection is deleted.  By default, pending delete
             should be enabled.

             Inserting or pasting elements into a selection, except   *
             for a primary transfer operation at the bounds of the    *
             primary selection, must first delete the selection if    *
             pending delete is enabled.

             In normal mode, inserting or pasting elements disjoint   *
             from the selection must also deselect the selection,     *
             except for primary transfer operations whose source and  *
             destination are in the same collection.  In add mode,    *
             the selection must not be deselected.

             In editable list-like and graphics-like collections,     *
             <<DDeelleettee>> must delete the selected elements.  In          *
             editable text-like collections, <<DDeelleettee>> and             *
             <<BBaacckkSSppaaccee>> must behave as follows:

                +o If the selection is not empty and the control is    *
                  in normal mode, the selection must be deleted.

                +o If the selection is not empty, the control is in    *
                  add mode, and the cursor is not disjoint from the   *
                  selection, the selection must be deleted.





        August 26, 1994                                         4-17







        OSF/Motif Style Guide


                +o If the selection is not empty and the control is    *
                  in add mode, but the cursor is disjoint from the    *
                  selection, <<DDeelleettee>> must delete one character       *
                  forward, and <<BBaacckkSSppaaccee>> must delete one character  *
                  backward.

                +o If the selection is empty, <<DDeelleettee>> must delete     *
                  one character forward, and <<BBaacckkSSppaaccee>> must delete  *
                  one character backward.

             More generally, any operation that deletes a region
             (for example, a word or line) behaves as follows:

                +o If the selection is not empty and the control is    *
                  in normal mode, the selection must be deleted.

                +o If selection is not empty, the control is in add    *
                  mode, and the cursor is not disjoint from the       *
                  selection, the selection must be deleted.

                +o If the selection is not empty and the control is    *
                  in add mode, but the cursor is disjoint from the    *
                  selection, the operation must delete the region.

                +o If the selection is empty, the operation must       *
                  delete the region.

             If the region deleted (in add mode) partially overlaps   *
             the selection, then the overlapped part of the           *
             selection must be deleted.

             Generally, whenever an action causes data to be removed
             from a component, what to do with the space left by the
             data is up to the component.  In cases where the
             surrounding data can be reformatted to fill in the
             space left by the removed data (such as in Text
             components), the delete action should cause this
             reformatting.  In this case, a clear action should
             delete the data without reformatting any surrounding
             data.  In Text components, the clear action deletes the
             selected text and replaces it with white space.  In
             cases where the surrounding data cannot be reformatted
             to fill in the space left by the removed data (such as
             in bitmap graphics), the delete action should remove
             the data but not cause any reformatting.  The CCuutt entry
             from the EEddiitt Menu should behave like the delete
             action.

             In cases where an action adds data to a component, the
             effect the new data has on the surrounding data depends
             on the component.  In cases where the surrounding data




        4-18                                         August 26, 1994







                                                           Selection


             can be reformatted to allow the new data to fit in
             (such as in Text components), insert actions should
             cause this reformatting.  The PPaassttee entry from the EEddiitt
             Menu should behave like insert actions.

             <<UUnnddoo>> or <<AAlltt>> <<BBaacckkSSppaaccee>> should undo the last
             operation on a selection.



        4.3  TTrraannssffeerr MMooddeellss



             This section describes the four techniques available
             for transferring data:

             CClliippbbooaarrdd TTrraannssffeerr
                  This technique transfers a selection from a source
                  to the clipboard, and then subsequently from the
                  clipboard to a destination.

             PPrriimmaarryy TTrraannssffeerr
                  This technique transfers the primary selection
                  directly to a destination without using the
                  clipboard for intermediate storage of the data.

             QQuuiicckk TTrraannssffeerr
                  This technique allows the user to indicate a range
                  of elements (called a secondary selection) that
                  are then transferred to the destination component.

             DDrraagg TTrraannssffeerr oorr DDrraagg aanndd DDrroopp
                  This technique allows the user to drag a selection
                  or an unselected element from a source to a
                  destination.

             Clipboard and primary transfer operations can be
             invoked from Pulldown or Popup Menus and have standard
             keyboard bindings as well.  Primary, quick, and drag
             transfer operations can also be invoked using
             BBTTrraannssffeerr.

             There are three transfer operations generally
             available:

                +o Copy, which copies elements from the source to the
                  destination.

                +o Move, which moves elements from the source to the
                  destination.




        August 26, 1994                                         4-19







        OSF/Motif Style Guide


                +o Link, which inserts a link in the destination to
                  elements in the source.

             The default operation for primary and quick transfer
             using BBTTrraannssffeerr is copy.  The default operation for
             drag transfer is generally move, though it depends on
             the characteristics of the source and the destination.
             Modifiers can be used to force an operation different
             from the default:                                        *

                +o <<CCttrrll>> must force a copy.                           *

                +o <<SShhiifftt>> must force a move.                          *

                +o <<CCttrrll>> <<SShhiifftt>> must force a link.                   *

             If the move, copy, or link operation the user requests   *
             is not available, the transfer operation must fail.

             When data is moved or copied, it can change its
             appearance or representation.  The destination can
             determine the representation of the transferred data as
             it chooses.  For example, if a graphic element
             representing a file is transferred to a Text component,
             the name of the file (or possibly the contents, if it
             is a text file) can be inserted.  If possible, the       *
             source must transfer the format that the destination     *
             requests.  Otherwise, the destination can use any
             heuristic to determine the best format to transfer the
             data in.  That heuristic can even be, if the source
             cannot transfer in the preferred format, fail.  If the
             destination decides that a transfer in its chosen
             format could possibly cause a loss of data between the
             source and the destination, the destination should
             notify the user of the possible loss of data and
             confirm the action before proceeding.

             If there is a choice of the exact representation of
             data to be inserted, there should be some visual means
             that clearly indicates to the user which representation
             the application will use.  If there is no such
             indication, then when the user performs the transfer
             operation, the application can post a Popup Menu or a
             DialogBox to allow the user to choose the
             representation.

             A transfer can also cause the destination to take
             related actions.  For example, transferring an element
             to a printer icon can cause the element to be printed.






        4-20                                         August 26, 1994







                                                           Selection


             The insertion position is the position in the
             destination at which transferred data is placed.  The
             insertion position is determined in the following way:

                +o Some collections have a fixed insertion point (as
                  in append-only text) or keep the elements in the
                  collection ordered in a specific way.  In those
                  cases, the collection can determine where to place
                  the data.

                +o If the collection does not have a fixed insertion   *
                  point or keep elements ordered in a specific way,   *
                  the insertion position for BBTTrraannssffeerr-based primary  *
                  and drag transfer operations must be the position   *
                  at which the user releases BBTTrraannssffeerr.

                +o If the collection does not have a fixed insertion
                  point or keep elements ordered in a specific way,
                  the insertion position for other transfer
                  operations, including keyboard-based transfer
                  operations, is determined as follows:

                     - In text-like collections, the insertion        *
                       position must be the location cursor, and the  *
                       data must be pasted before it.

                     - In list-like collections, the insertion        *
                       position must be the element with the          *
                       location cursor, and the data must be pasted   *
                       before it.

                     - In graphics-like collections, the insertion
                       position should be at the location cursor,
                       but the exact placement of the data with
                       respect to the location cursor is
                       unspecified.



        4.3.1  CClliippbbooaarrdd TTrraannssffeerr



             The clipboard transfer operations CCuutt, CCooppyy, and PPaassttee,
             are usually performed using the EEddiitt Menu of an
             application.  They also have standard keyboard bindings  *
             that must be available in every editable collection.     *

             <<CCuutt>> or <<SShhiifftt>> <<DDeelleettee>> and the CCuutt entry of the EEddiitt  *
             Menu must cut selected elements of the target component  *
             to the clipboard.                                        *




        August 26, 1994                                         4-21







        OSF/Motif Style Guide


             <<CCooppyy>> or <<CCttrrll>> <<IInnsseerrtt>> and the CCooppyy entry of the      *
             EEddiitt Menu must copy selected elements of the target      *
             component to the clipboard and can mark the selection    *
             for subsequent use with PPaassttee LLiinnkk.

             A CCooppyy LLiinnkk entry of the EEddiitt Menu can be used to place
             a link in the clipboard to selected elements of the
             target component so that the link can be placed in a
             destination by subsequent use of PPaassttee or PPaassttee LLiinnkk.

             See the rules for operations that act on selections in
             Section 4.2.2 for determining which component in a
             window is targeted by a CCuutt, CCooppyy, or CCooppyy LLiinnkk
             operation.

             <<PPaassttee>> or <<SShhiifftt>> <<IInnsseerrtt>> and the PPaassttee entry of the   *
             EEddiitt Menu must paste the contents of the clipboard at    *
             the insertion position of the target component.

             The PPaassttee LLiinnkk entry of the EEddiitt Menu can place a link
             at the insertion position of the target component to
             the selection last marked by a CCooppyy or CCooppyy LLiinnkk
             operation.

             See the rules for operations that do not act on
             selections in Section 4.2.2 for determining which
             collection in a window is targeted by a PPaassttee or PPaassttee
             LLiinnkk operation.

             If the last data cut was the primary selection, pasting
             it can make it the primary selection if there is no
             current primary selection.  Otherwise, pasting data
             should not select it.  However, if the collection is in
             normal mode, the anchor and the cursor should be placed
             at opposite ends of the pasted data so that subsequent
             use of <<SShhiifftt>> <<SSeelleecctt>> or <<SShhiifftt>> <<SSppaaccee>> can be used
             to select it.

             If PPaassttee or PPaassttee LLiinnkk is invoked using a component's    *
             Popup Menu, the data must be pasted at the insertion     *
             position of the component.  However, if the Popup Menu   *
             is popped up over a selection, the selection must first  *
             be deleted, even if pending delete is disabled, and the  *
             pasted data must replace it, if possible.

             If PPaassttee or PPaassttee LLiinnkk is invoked from the EEddiitt Menu or  *
             by a keyboard operation, and the insertion position in   *
             the target component is not disjoint from a selection,   *
             the pasted data must replace the selection contents if   *
             pending delete is enabled.





        4-22                                         August 26, 1994







                                                           Selection


        4.3.2  PPrriimmaarryy TTrraannssffeerr



             Primary transfer can be invoked by clicking BBTTrraannssffeerr
             or through standard keyboard bindings.  There are three
             primary transfer operations:

             PPrriimmaarryy CCooppyy
                  In an editable collection, BBTTrraannssffeerr CClliicckk, <<CCttrrll>>  *
                  BBTTrraannssffeerr CClliicckk, <<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>> must copy the primary selection to the     *
                  insertion position, as defined in Section 4.3.      *
                  (Note that the insertion position is usually        *
                  different for mouse and keyboard operations.)

             PPrriimmaarryy MMoovvee
                  In an editable collection, <<SShhiifftt>> BBTTrraannssffeerr        *
                  CClliicckk, <<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>>      *
                  must move the primary selection to the insertion    *
                  position, as defined in Section 4.3.  (Note that    *
                  the insertion position is usually different for     *
                  mouse and keyboard operations.)

             PPrriimmaarryy LLiinnkk
                  In an editable collection, <<CCttrrll>> <<SShhiifftt>>           *
                  BBTTrraannssffeerr CClliicckk must place a link to the primary    *
                  selection at the insertion position, as defined in  *
                  Section 4.3.

             Transferring data to the destination by a PPrriimmaarryy CCooppyy   *
             or PPrriimmaarryy LLiinnkk must not select it.  However, if the
             source and the destination components are different,
             and if the collection is in normal mode, the anchor and
             the cursor should be placed at opposite ends of the
             transferred data, so that subsequent use of <<SShhiifftt>>
             <<SSeelleecctt>> or <<SShhiifftt>> <<SSppaaccee>> can be used to select it.

             A PPrriimmaarryy MMoovvee must move the primary selection as well   *
             as the elements selected; that is, the element moved to  *
             the destination must become selected as the primary      *
             selection.

             If a primary transfer operation is invoked using a       *
             component's Popup Menu, the data must be transferred to  *
             the insertion position of the component.  However, if    *
             the Popup Menu is popped up over a persistent            *
             nonprimary selection, the selection must first be        *
             deleted, even if pending delete is disabled, and the     *
             transferred data must replace it.  When a primary        *
             transfer transfers data into a nonprimary selection,     *




        August 26, 1994                                         4-23







        OSF/Motif Style Guide


             the transferred data must replace the selection          *
             contents if pending delete is enabled.

             When a PPrriimmaarryy CCooppyy or PPrriimmaarryy LLiinnkk is invoked by using
             BBTTrraannssffeerr with the pointer at the edge of the primary
             selection, by popping up a Popup Menu at the edge of a
             primary selection, or by a keyboard operation when the
             insertion position is at the edge of the primary
             selection, the data should be transferred, and the
             selection should be left unchanged, even if pending
             delete is enabled.  If a PPrriimmaarryy CCooppyy or PPrriimmaarryy LLiinnkk
             is invoked inside the primary selection, the operation
             should have no effect.

             If BBTTrraannssffeerr is pressed outside a primary selection,
             but at a position both where a drag can be initiated
             and where data can be pasted by a primary transfer, a
             user-settable timeout and motion threshold should be
             used in the following way to distinguish drag
             initiation from primary transfer:

                +o If BBTTrraannssffeerr MMoottiioonn exceeding the motion threshold
                  occurs following the BBTTrraannssffeerr PPrreessss, a drag
                  should be initiated.

                +o Otherwise, if the BBTTrraannssffeerr RReelleeaassee follows the
                  BBTTrraannssffeerr PPrreessss within the timeout period, a
                  primary transfer should be done.

                +o Otherwise, when the timeout period expires, a drag
                  should be initiated.  However, if BBTTrraannssffeerr
                  RReelleeaassee is then done without motion exceeding the
                  threshold, the drag should be canceled.

             If BBTTrraannssffeerr is pressed within a draggable primary
             selection, the drag should be initiated on the
             BBTTrraannssffeerr PPrreessss.



        4.3.3  QQuuiicckk TTrraannssffeerr



             Quick transfer is used to make a temporary (or
             secondary) selection and then immediately copy, move,
             or link that selection to the insertion position of the
             destination component.  Quick transfer is implemented
             using <<AAlltt>> BBTTrraannssffeerr MMoottiioonn, with the standard
             modifiers used to force the various transfer
             operations.




        4-24                                         August 26, 1994







                                                           Selection


             Text components must support quick transfer.             *

             There are three quick transfer operations:

             QQuuiicckk CCooppyy
                  If a component supports quick transfer, <<AAlltt>>       *
                  BBTTrraannssffeerr MMoottiioonn or <<AAlltt>> <<CCttrrll>> BBTTrraannssffeerr MMoottiioonn   *
                  must temporarily select elements in the specified   *
                  range and, on release, must copy them to the        *
                  insertion position of the destination component.

             QQuuiicckk CCuutt
                  If a component supports quick transfer, <<AAlltt>>       *
                  <<SShhiifftt>> BBTTrraannssffeerr MMoottiioonn must temporarily select    *
                  elements in the specified range and, on release,    *
                  must move them to the insertion position of the     *
                  destination component.

             QQuuiicckk LLiinnkk
                  If a component supports quick transfer, <<AAlltt>>       *
                  <<CCttrrll>> <<SShhiifftt>> BBTTrraannssffeerr MMoottiioonn must temporarily    *
                  select elements in the specified range and, on      *
                  release, must place a link to them at the           *
                  insertion position of the destination component.

             The range of the temporary selection must be determined  *
             by using exactly the same model used when BBSSeelleecctt        *
             MMoottiioonn determines the range of a primary selection.

             If the insertion position of the destination component   *
             is not disjoint from the selection, the transferred      *
             data must replace the selection contents if pending      *
             delete is enabled.  Transferring data to the             *
             destination component by a quick transfer must not       *
             select it.  However, if the destination component is in
             normal mode, the anchor and the cursor should be placed
             at opposite ends of the transferred data so that
             subsequent use of <<SShhiifftt>> <<SSeelleecctt>> or <<SShhiifftt>> <<SSppaaccee>>
             can be used to select it.

             Quick transfer can be used to transfer static text or
             graphics that are not ordinarily selectable.  For
             example, a portion of the text label of a PushButton is
             not ordinarily selectable, since BBSSeelleecctt CClliicckk,
             <<SSeelleecctt>> or <<SSppaaccee>> activate the PushButton instead.

             While dragging out the quick selection, the range
             should be highlighted in some way.  The highlighting
             mechanism should be different from that used for the
             primary selection.  In text, the highlight should be
             underlining.




        August 26, 1994                                         4-25







        OSF/Motif Style Guide


             If the pointer is dragged out of a scrollable            *
             collection while making the temporary selection,         *
             autoscrolling must be used to scroll the collection in   *
             the direction of the pointer.  If BBTTrraannssffeerr is released  *
             with the pointer outside of the collection, or if        *
             <<CCaanncceell>> is pressed with BBTTrraannssffeerr pressed, the          *
             highlighting must be removed and a transfer must not be  *
             performed.



        4.3.4  DDrraagg TTrraannssffeerr



             Drag transfer, also known as drag and drop, provides a
             quick and simple model for transferring data within and
             between applications.  Depending on where it is
             initiated, drag transfer can be used to transfer the
             selected elements of a collection, a single unselected
             element, an entire collection, and even unselectable
             static textual and graphics labels.

             A user performs a drag transfer by pressing BBTTrraannssffeerr
             in the source, moving the pointer to the destination
             (called the drop site), and releasing BBTTrraannssffeerr.  This
             transfers the data from the source to the destination.
             The usual modifier keys can be used to force a copy,
             move, or link:

                +o <<CCttrrll>> BBTTrraannssffeerr MMoottiioonn must force a drag copy.     *

                +o <<SShhiifftt>> BBTTrraannssffeerr MMoottiioonn must force a drag move.    *

                +o <<CCttrrll>> <<SShhiifftt>> BBTTrraannssffeerr MMoottiioonn must force a drag   *
                  link.

             If no modifier key is chosen, the default operation
             should be a move, although it depends on the
             characteristics of the source and the destination.  In
             particular, the default should be copy if the source is
             not editable, or if the destination is a copying or
             transformation device; for example, if the drop occurs
             over an icon for a printer or a compiler.

             When a drag move moves the primary selection, the
             primary selection should move to the destination, as
             well as the elements selected; that is, the element
             moved to the destination should become selected as the
             primary selection.





        4-26                                         August 26, 1994







                                                           Selection


             When a drag move moves a selection within the same       *
             component, the selection must move along with the        *
             elements selected.

             In other cases, data transferred by a drag transfer      *
             must not become selected at the destination.  However,
             if the destination is in normal mode, then except when
             drag copy and drag link transfer a selection within the
             same component, the anchor and the cursor should be
             placed at opposite ends of the transferred data so that
             subsequent use of <<SShhiifftt>> <<SSeelleecctt>> or <<SShhiifftt>> <<SSppaaccee>>
             can be used to select it.

             Within a collection, drag transfer can be used to
             either drag a selected set of elements, a single
             unselected element, or the entire collection.  This is
             determined in the following way:

                +o In text-like collections, initiating a drag in a    *
                  selected region must drag the text selection        *
                  (including all pieces if it is discontiguous).

                +o In list-like and graphics-like collections,         *
                  initiating a drag on a selected element must drag   *
                  the entire selection.

                +o In list-like and graphics-like collections,         *
                  initiating a drag on an unselected element must     *
                  drag just that element.  If the collection          *
                  contains a selection, the selection must not be     *
                  affected (except if the drop occurs in the same     *
                  collection).

                +o In graphics-like collections, initiating a drag in
                  the background of a contiguous selected region can
                  drag the selection.  Otherwise, BBTTrraannssffeerr MMoottiioonn
                  beginning in the background of a collection can
                  drag the entire collection or, if the collection
                  is scrollable, can be used to pan the collection.

             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 with nested
             draggable elements, the drag occurs on the smallest
             draggable element under the pointer.

             All collections should support drag transfer and should
             allow elements to be dragged to or from other
             collections, including those in different applications.
             A collection can support only drag (particularly if it




        August 26, 1994                                         4-27







        OSF/Motif Style Guide


             is not editable) or only drop.

             If a collection only allows elements dragged from it to
             be dropped in the same collection, then, during the
             drag, it can prevent the pointer from moving outside of
             the collection.  If so, and if the collection is
             scrollable, holding the pointer at the edge of the
             collection should cause autoscrolling.



        4.3.4.1  DDrraagg IIccoonnss



             When a drag operation is started, the pointer must be    *
             replaced with a drag icon.  A drag icon provides visual
             feedback that a drag is in progress.  It can be
             composed of three parts:

                +o A source indicator

                +o An operation indicator

                +o A state indicator

             Figure 4-1 shows move, copy, and link drag icons for
             graphical and textual information.  The bulk of the
             icon is the source indicator.  When defining new drag
             icons, you should follow the same rules as for defining
             new pointers described in Section 2.2.2.

                            FFiigguurree 44--11..  Drag Icons

             All drag icons must include a source indicator.  A       *
             source indicator should give a visual representation of
             the type of elements being dragged; for example,
             horizontal lines in a rectangle for representing text.
             The source indicator can include a fragment of the
             actual data being dragged, such as the first few
             characters of some text.

             An operation indicator shows whether the drag operation
             will result in a move, copy, or link operation.  Most
             drag icons should include an operation indicator.  An
             operation indicator can be shown either as a separate
             element of the drag icon or as a variation of a graphic
             used for the source indicator.

             The source of the dragged elements can also provide
             visual indications of the result of a drop.  For




        4-28                                         August 26, 1994







                                                           Selection


             example, if the default operation for the dragged
             elements is a move, the source can be hidden or
             deemphasized; or if the default operation of the
             dragged elements is a link, a line can be drawn from
             the source to the pointer.

             A state indicator shows whether the current pointer
             location is over a valid drop site for the dragged
             elements.  All drag icons can include a state
             indicator.  A state indicator should be coincident with
             the hotspot of the pointer.



        4.3.4.2  DDuurriinngg aa DDrraagg



             Systems should provide help operations during drag and
             drop.  If a system provides drag and drop help,
             pressing <<HHeellpp>> (followed by releasing BBTTrraannssffeerr)
             during a drag and drop operation should allow the
             posting of a DialogBox with the help information and
             the possible choices for concluding the drag and drop
             operation.  The DialogBox should allow for canceling
             the drag and drop operation or for dropping the
             elements at the current location as a move, copy, or
             link.

             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.

             It can be difficult during a drag and drop operation to
             make both the drag source and drop site visible to the
             user at the same time.  A system can alleviate this
             problem by making it possible to navigate to drop sites
             that were not visibly available at the start of the
             drag operation.  For example, a system can scroll a
             scrollable region when the pointer rests on the edge of
             that scrollable region.  A system can open an icon view
             when the pointer rests on that icon.  A system can also
             raise a window when the pointer rests in that window.

             During a drag and drop interaction, the system should
             indicate dynamically whether the current pointer
             location is a possible valid drop site for the data
             that the user is dragging.  This is done using drag-
             over effects, and drag-under effects.  A drag-over
             effect is a change in the visual state of the drag
             icon.  This change is usually represented in the drag




        August 26, 1994                                         4-29







        OSF/Motif Style Guide


             icon's state indicator.  If a drag icon has a state
             indicator, it should be coincident with the pointer's
             hotspot.  The state indicator should be emphasized for
             valid drop sites and deemphasized for invalid drops
             sites.  The state indicator can also indicate that
             there is no drop site under the pointer.

             A drag-under effect is a change to the visual state of
             a possible valid drop site when the drag icon pointer
             is over the drop site.  All drop sites should use some
             kind of drag-under effect.  Drop sites can use a solid
             line around the site, or a raised or lowered beveled
             edge around the drop site as a drag-under effect.  Drop
             sites can also change any visual component of the drop
             site, or even animate those changes, as a drag-under
             effect.  For example, an icon representing a folder
             might show an animated image of the folder opening as a
             user drags a file onto it.  Drop sites can also use
             other media (for example, audio effects) to provide
             feedback.



        4.3.4.3  EEnnddiinngg aa DDrraagg



             Releasing BBTTrraannssffeerr (or BBSSeelleecctt when transfer and        *
             selection are integrated) must end a drag and drop       *
             operation.  In addition, as mentioned in the previous    *
             section, pressing <<CCaanncceell>> must also end a drag and      *
             drop operation by canceling the drag in progress.  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.

             However, if a drop occurs within a selection at any      *
             level, the transferred data must replace the contents    *
             of the entire selection if pending delete is enabled.













        4-30                                         August 26, 1994







                                                           Selection


        4.3.4.4  DDrroopp RReessuullttss



             Every drop operation, even when there was a visual
             indication of a valid drop site, can result in either
             success, failure, or partial failure (in the case of
             dragging multiple elements).  While the transfer is in   *
             progress, that is until the drop site determines the     *
             success of the drag and drop operation, the data must    *
             not leave the source.  While the transfer is in
             progress, a transfer icon representing the type of data
             being transferred should appear at the drop site.

             After a successful transfer, the data must be placed in  *
             the drop site and the transfer icon must be removed.
             The removal of the transfer icon can be accompanied by
             an animation that shows the icon transforming into the
             drop site.  For example, the transfer icon can melt
             into the drop site.

             After a failed transfer, the data must remain at the     *
             drag source, the data must not be placed in the drop     *
             site, and the transfer icon must be removed.  The
             removal of the transfer icon should be accompanied by
             an animation that shows the icon returning to the
             source location.  For example, the transfer icon can
             snap back to the location of the drag source.

             When multiple elements are involved in a drag and drop
             operation, the success or failure of the operation can
             be determined for the group as a whole or for each
             individual element in the group.  If the group is
             transferred as a whole, there should only be one
             transfer icon at the drop site while the transfer is in
             progress.  If the elements in the group succeed or fail
             individually, there can either be a transfer icon for
             each element or one transfer icon for the whole group.
             In either case, if partial success or failure is
             allowed, the drop site should post a message for each
             individual failure or otherwise indicate which
             transfers succeeded or failed.













        August 26, 1994                                         4-31







        OSF/Motif Style Guide


        4.3.5  IInntteeggrraattiinngg SSeelleeccttiioonn aanndd TTrraannssffeerr



             Instead of using BBTTrraannssffeerr, transfer operations can be
             integrated with BBSSeelleecctt. When BBSSeelleecctt is used for
             dragging operations, its use partially supersedes 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.  The following rules are designed to
             make the integration of selection and transfer less
             restrictive:

                +o In text-like collections, BBSSeelleecctt MMoottiioonn starting   *
                  in a selected region must drag the text selection;  *
                  starting outside the selected region, it must be    *
                  used for making selections.

                +o In list-like and graphics-like collections,         *
                  BBSSeelleecctt MMoottiioonn starting on a selected element must  *
                  drag the entire selection.

                +o In dense list-like or graphics-like collections,    *
                  in which background space around elements is not    *
                  generally available and in which BBSSeelleecctt MMoottiioonn is  *
                  used for browsing or for selecting or toggling a    *
                  range of elements, BBSSeelleecctt MMoottiioonn starting on an    *
                  unselected element must be used for making          *
                  selections.

                +o In less dense list-like or graphics-like            *
                  collections, BBSSeelleecctt MMoottiioonn in the background must  *
                  be used for making marquee selections; if they are  *
                  not supported, BBSSeelleecctt MMoottiioonn can be used to drag   *
                  the entire collection, or to pan if the collection  *
                  is scrollable.

                +o BBSSeelleecctt CClliicckk must always be used for selection.    *

             When BBSSeelleecctt is used for dragging, the <<CCttrrll>> and        *
             <<SShhiifftt>> modifiers must be used to force the transfer     *
             operation as for BBTTrraannssffeerr.  When BBSSeelleecctt is only used   *
             for selection, the <<CCttrrll>> and <<SShhiifftt>> modifiers have     *
             their usual selection-specific meanings.                 *

             If BBMMeennuu is not available for Popup Menus, <<AAlltt>>         *
             BBSSeelleecctt must be used instead.

             If BBMMeennuu is available, then when transfer is integrated
             with selection, <<AAlltt>> BBSSeelleecctt CClliicckk should be used for
             primary transfer, and <<AAlltt>> BBSSeelleecctt MMoottiioonn should be
             used for quick transfer, with <<CCttrrll>> and <<SShhiifftt>>




        4-32                                         August 26, 1994







                                                           Selection


             forcing the transfer operation as usual.






















































        August 26, 1994                                         4-33





 
