















        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.









        May 8, 1992                                              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" may mean
             that the cursor is within the bounds of the element, or
             it may mean that the cursor is on the boundary of the
             element, or the element may 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 may
             limit selection to a single element where the user is



        4-2                                              May 8, 1992








                                                           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



        May 8, 1992                                              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 objects are
             organized in layers, when 3-dimensional selection is
             needed, when objects 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 a null 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                                              May 8, 1992








                                                           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



        May 8, 1992                                              4-5








        OSF/Motif Style Guide


             dragging and selection is described in Section 4.3.

             In the range selection model, when BBSSeelleecctt is pressed,   *
             all elements in the collection must be deselected.  If   *
             BBSSeelleecctt is clicked on a selectable element, it must be   *
             selected.  Pressing BBSSeelleecctt must also set an anchor on   *
             the element, or at the position where BBSSeelleecctt was        *
             pressed.  The aanncchhoorr is one of the endpoints of the
             selected range.  As BBSSeelleecctt is dragged through the       *
             collection, every element between the pointer and the    *
             anchor must be included in the selection.  When BBSSeelleecctt  *
             is released, the anchor must not move, all the elements  *
             between the anchor and the release position must remain  *
             in the selection, and the location cursor must be at     *
             the location where BBSSeelleecctt is released.

             In graphics-like collections, where the location cursor
             and the anchor can be between elements as well as on
             them, there is a special selection mechanism called
             marquee selection.  In marquee selection, as BBSSeelleecctt is
             dragged through the collection a box, or marquee, is
             defined from the anchor to the current mouse position.   *
             All items completely within the marquee must be          *
             included in the selection.  If the marquee selection is
             started within an element, the selection can be
             extended to enclose the entire element.  If the
             collection is arranged as a list or matrix, the marquee
             should be extended to completely enclose the initial
             element in the selection, and the marquee should also
             be extended to enclose the element on which BBSSeelleecctt is
             released.  Marquee selection can be implemented so that
             it is only used when BBSSeelleecctt is pressed in the
             background; other selection models can be used when
             BBSSeelleecctt is pressed on an element.

             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           *
             selection must be extended according to one of the       *
             following extension models:

             RReesseelleecctt       The selection must extend to include all  *
                            elements between the anchor and the       *
                            pointer.  When <<SShhiifftt>> BBSSeelleecctt is         *
                            released, the anchor must not move, all   *
                            the elements between the anchor and the   *
                            release position must remain in the       *
                            selection, and the location cursor must   *
                            be at the position of the release.

             EEnnllaarrggee OOnnllyy   The selection can only be enlarged.  The  *
                            selection must extend to include all      *



        4-6                                              May 8, 1992








                                                           Selection


                            elements completely between the old       *
                            selection and the pointer.  In the        *
                            graphics-like collections, the marquee    *
                            is enlarged to include the old            *
                            selection.  When <<SShhiifftt>> BBSSeelleecctt is       *
                            released, the position of the anchor is   *
                            irrelevant, all the elements selected     *
                            must remain in the selection, and the     *
                            location cursor must be at the position   *
                            of the release                            *

             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 point, 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 point, this model     *
                            must move the anchor point to the other   *
                            side of the selection, and then must      *
                            work exactly like the reselect model.
                            In graphics-like collections, balancing
                            the anchor point is done separately in
                            each dimension.  When <<SShhiifftt>> BBSSeelleecctt is  *
                            released, all elements must remain in     *
                            the selection, the anchor must remain in  *
                            its last position, and the location       *
                            cursor must be at the position of the     *
                            release.

             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.



        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
             behaves very similar to the range selection model.  The
             description of this selection model assumes that drag-
             and-drop is not integrated with selection.  Integrating



        May 8, 1992                                              4-7








        OSF/Motif Style Guide


             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 is exactly the same as in the range selection
             model.  In the discontiguous selection model, when       *
             BBSSeelleecctt is pressed all elements in the collection must   *
             be deselected.  If BBSSeelleecctt is clicked on a selectable    *
             element, it must be selected.  Pressing BBSSeelleecctt must     *
             also set an anchor on the element, or at the position    *
             where BBSSeelleecctt was pressed.  As BBSSeelleecctt is dragged        *
             through the collection, every element between the        *
             pointer and the anchor must be included in the           *
             selection.  When BBSSeelleecctt is released, the anchor must    *
             not move, all the elements between the anchor and the    *
             release position must remain in the selection, and the   *
             location cursor must be on the last element selected.    *
             After the anchor is set 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 mode, <<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 null, <<CCttrrll>> BBSSeelleecctt CClliicckk
             can 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 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.  In any case, the location    *
             cursor must move to the point at which the click         *
             occurs.

             <<CCttrrll>> BBSSeelleecctt MMoottiioonn is used to toggle the selection
             state of a range of elements.  The range itself is
             determined exactly as for BBSSeelleecctt MMoottiioonn.  There are
             two models used for toggling.

             AAnncchhoorr TTooggggllee     The anchor element of the range is
                               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.




        4-8                                              May 8, 1992








                                                           Selection


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

             Once <<CCttrrll>> BBSSeelleecctt has been used to toggle a
             selection, the toggled range may be extended by <<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.  The extended range
             can be determined by any of the extension models
             described in Section 4.1.4; that is, Reselect, Enlarge
             Only, or Balance Beam.  Once the extended range is       *
             determined, the selection state of elements added to     *
             the range must be determined by the toggle model as      *
             previously described.  If <<SShhiifftt>> BBSSeelleecctt removes
             elements from the extended range, they can 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 opposite state of the
             extended range.



        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.  There are two different keyboard selection
             models 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 disjointed 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.

             Add mode is used for making more complex and possibly
             disjointed 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     *



        May 8, 1992                                              4-9








        OSF/Motif Style Guide


             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 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 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 disjointed from the
             selection, <<SSeelleecctt>> or <<SSppaaccee>> selects the cursored
             element and deselects any other element.



        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-10                                             May 8, 1992








                                                           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       *
             nonnull, it must be deselected and the 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 Text) 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    *
             null, the anchor must 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        *
             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.








        May 8, 1992                                             4-11








        OSF/Motif Style Guide


        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 an extension to the model that
             allows the user to select discontiguous elements.

             In normal mode, keyboard-based discontiguous selection
             behaves identically to keyboard-based range selection.   *
             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 it 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 using one of the toggle mechanisms       *
             described in Section 4.1.5.



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




        4-12                                             May 8, 1992








                                                           Selection


             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.9  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.  Typing a      *
             mnemonic while the collection has the keyboard focus     *
             must be equivalent to moving the location cursor to the  *
             element and typing <<SSeelleecctt>> or <<SSppaaccee>>.



        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 a null 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 nonnull selection.  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 null.  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



        May 8, 1992                                             4-13








        OSF/Motif Style Guide


                  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 null.  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 either
             use persistent or non-persistent selections.



        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 a      *
             mouse button or keyboard input.

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












        4-14                                             May 8, 1992








                                                           Selection


        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 describes 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 may
             be used, or a control may be activated, which performs
             the operation.  There may 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
             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 nonnull
                   selection, 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.



        May 8, 1992                                             4-15








        OSF/Motif Style Guide


               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 actions 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
                   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 may 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    *



        4-16                                             May 8, 1992








                                                           Selection


             pending delete is enabled.

             In normal mode, inserting or pasting elements            *
             disjointed 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>> behave as follows:

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

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

                +o If there is no 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 there is a nonnull selection, the cursor is      *
                  disjointed from the selection and in add mode,      *
                  <<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 selection is nonnull and in normal mode, the     *
                  selection must be deleted.

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

                +o If there is no selection, <<DDeelleettee>> must delete the  *
                  region.

                +o If there is a nonnull selection, the cursor is      *
                  disjointed from the selection and in add mode,      *
                  <<DDeelleettee>> 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.





        May 8, 1992                                             4-17








        OSF/Motif Style Guide


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



        4-18                                             May 8, 1992








                                                           Selection


             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.

                +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  operation indicated by the modifiers 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 were transferred to a text
             component, the name of the file (or possibly the
             contents if it were a text file) could 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 can not transfer in the preferred format,



        May 8, 1992                                             4-19








        OSF/Motif Style Guide


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

             Some mouse-based transfer operations place data at the
             pointer position, if possible.  Other transfer
             operations, including keyboard-based transfer
             operations, place the data at the insert position of
             the collection, which is determined in the following
             way:

                +o In text-like collections, the insert position must  *
                  be the insert cursor, and the data must be pasted   *
                  before it.

                +o In list-like collections, the insert position must  *
                  be the element with the insert cursor, and the      *
                  data must be pasted before it.

                +o In graphics-like collections, the insert position
                  should be at the insert cursor, but the exact
                  placement of the data with respect to the insert
                  cursor is unspecified.

             BBTTrraannssffeerr-based primary and drag transfer operations     *
             must place the transferred data at the position at       *
             which BBTTrraannssffeerr is released.  However, 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.                       *








        4-20                                             May 8, 1992








                                                           Selection


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

             <<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, Operation Targets, for determining which
             component in a window is targeted by a cut, copy or
             copy link 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 insert 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 insert position of the target component to the
             selection last marked by a copy or copy link operation.

             See the rules for operations that do not act on
             selections in Section 4.2.2, Operation Targets, for
             determining which collection in a window is targeted by
             a paste or paste link 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>> may be used
             to select it.





        May 8, 1992                                             4-21








        OSF/Motif Style Guide


             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 insert        *
             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 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 disjointed from a            *
             selection, the pasted data must replace the selection    *
             contents if pending delete is enabled.



        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 though standard keyboard bindings.  There are three
             primary transfer operations:

             PPrriimmaarryy CCooppyy
                  BBTTrraannssffeerr CClliicckk or <<CCttrrll>> BBTTrraannssffeerr CClliicckk must      *
                  copy the primary selection to the pointer           *
                  location.  <<AAlltt>> <<CCooppyy>> or <<AAlltt>> <<CCttrrll>> <<IInnsseerrtt>>    *
                  must copy the primary selection to the insert       *
                  cursor of the target component (see Section 4.2.2   *
                  to determine the target component).

             PPrriimmaarryy MMoovvee
                  <<SShhiifftt>> BBTTrraannssffeerr CClliicckk must move the primary       *
                  selection to the pointer location.  <<AAlltt>> <<CCuutt>> or  *
                  <<AAlltt>> <<SShhiifftt>> <<DDeelleettee>> must move the primary        *
                  selection to the insert cursor of the target        *
                  component.

             PPrriimmaarryy LLiinnkk
                  <<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 pointer location.

             Transferring data to the destination by a primary copy   *
             or primary link 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>> may be used to select it.





        4-22                                             May 8, 1992








                                                           Selection


             A primary move 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 insert cursor 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, 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
             insert cursor 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 BBTTrraannssffeerr is pressed outside a primary selection,
             but at a position where a drag can be initiated and
             where data can be pasted, a user-settable timeout or
             motion threshold can be used to distinguish between the
             BBTTrraannssffeerr CClliicckk of a primary transfer and the BBTTrraannssffeerr
             MMoottiioonn initiating a drag transfer.  If BBTTrraannssffeerr iiss
             pprreesssseedd wwiitthhiinn aa pprriimmaarryy sseelleeccttiioonn,, aa ddrraagg ccaann bbee
             aassssuummeedd..



        44..33..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 insert 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.  <<AAlltt>> need not be used in collections that
             do not support drag-and-drop.  There are three quick
             transfer operations.





        May 8, 1992                                             4-23








        OSF/Motif Style Guide


             QQuuiicckk CCooppyy
                  <<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 should temporarily select elements in the
                  specified range, and on release, should copy them
                  to the insertion position of the destination
                  component.

             QQuuiicckk CCuutt
                  <<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 should temporarily
                  select elements in the specified range, and on
                  release, should move them to the insertion
                  position of the destination component.

             QQuuiicckk LLiinnkk
                  <<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 should
                  temporarily select elements in the specified
                  range, and on release, should place a link to them
                  at the insertion position of the destination
                  component.

             The range of the temporary selection must be determined  *
             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 disjointed from the a 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>>
             may 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 than that used for the
             primary selection.  In text, the highlight should be
             underlining.

             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  *



        4-24                                             May 8, 1992








                                                           Selection


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

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




        May 8, 1992                                             4-25








        OSF/Motif Style Guide


             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>> may 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
             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



        4-26                                             May 8, 1992








                                                           Selection


             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.



        May 8, 1992                                             4-27








        OSF/Motif Style Guide


             The source of the dragged elements can also provide
             visual indications of the result of a drop.  For
             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 hot spot 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 a 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



        4-28                                             May 8, 1992








                                                           Selection


             effect is a change in the visual state of the drag
             icon.  This change is usually represented in the drag
             icon's state indicator.  If a drag icon has a state
             indicator, it should be coincident with the pointer's
             hot spot.  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 affects) 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.  Also, 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 hot spot of the drag icon         *
             pointer.  The drop must occur into the highest drop      *
             site in the stacking order.  This also implies that in
             a group of nested drop sites the drop occurs into the
             smallest drop site under the pointer.

             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.










        May 8, 1992                                             4-29








        OSF/Motif Style Guide


        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.  The system should place a
             transfer icon representing the type of data being
             transferred at the drop site while the transfer is in
             progress.

             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.











        4-30                                             May 8, 1992








                                                           Selection


        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 for transfer operations,
             they may 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    *
             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.  This is not  *
             as restrictive as it sounds though:

                +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; otherwise

                +o In 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, it   *
                  can be used to drag the entire collection, or to    *
                  pan it if it 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>>
             forcing the transfer operation as usual.



        May 8, 1992                                             4-31








        OSF/Motif Style Guide
























































        4-32                                             May 8, 1992






 
