"

 COPYRIGHT (c) 1989 by Claus Gittinger

	      All Rights Reserved

 This software is furnished under a license and may be used

 only in accordance with the terms of that license and with the

 inclusion of the above copyright notice.   This software may not

 be provided or otherwise made available to, or used by, any

 other person.  No title to or ownership of the software is

 hereby transferred.

"

"{ Package: 'stx:libwidg' }"

ListView subclass:#SelectionInListView

	instanceVariableNames:'selection actionBlock enabled hilightFgColor hilightBgColor

		halfIntensityFgColor doubleClickActionBlock listAttributes

	classVariableNames:'RightArrowShadowForm RightArrowLightForm RightArrowForm

		SmallRightArrowShadowForm SmallRightArrowLightForm

		DefaultForegroundColor DefaultBackgroundColor

		DefaultHilightForegroundColor DefaultHilightBackgroundColor

		DefaultHilightFrameColor DefaultHilightLevel

		DefaultRightArrowStyle DefaultRightArrowLevel

		DefaultDisabledForegroundColor DefaultShadowColor

		DefaultLightColor DefaultHilightStyle'

	poolDictionaries:''

	category:'Views-Lists'

!

!SelectionInListView class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 1989 by Claus Gittinger

	      All Rights Reserved

 This software is furnished under a license and may be used

 only in accordance with the terms of that license and with the

 inclusion of the above copyright notice.   This software may not

 be provided or otherwise made available to, or used by, any

 other person.  No title to or ownership of the software is

 hereby transferred.

"

!

documentation

"

    this one is a ListView with a selected line (which is shown highlighted)

    If multipleSelectionsOk is true, it is also allowed to shift-click multiple 

    entries.

    If toggleSelect is true, clicking toggles (i.e. click on a seleted item

    will deselect).

    Whenever the selection changes, an action-block is evaluated, passing the 

    current selection as argument.

    Currently, the selection can be nil, aNumber or a collection of numbers; 

    this will change to be either nil or a collection, making selection handling 

    easier in the future. (this stupid behavior is due to the multiple

    select feature being added later - the first implementation used to support

    only single selections).

    The actionBlock is called with the current selection (single number or

    collection of numbers) as argument.

    Also, to support ST-80 MVC-style use, the model (if nonNil) is notified

    by the change mechanism (performs changeMsg) and vice versa, the view

    updates if the model changes (with aspect of either #list or #selectionIndex).

    Before actually adding entries to the the selection, a checkBlock (if non-nil) is evaluated 

    passing the number of the entry whch is about to be selected as argument.

    The select change operation is only done if this returns true. This allows

    interception of select, for example to query the user if he/she wants to save

    the old contents before (see uses in SystemBrowser and FileBrowser), or to

    disable individual entries.

    It is also possible to select entries with the keyboard; use the cursor up/

    down keys to select prev/next, Home- and End-keys to select first/last. 

    Use the return key to apply the double-click-action to the current selection.

    Also, alphabetic keys will select the next entry starting with that key.

    The keyboard behavior can be further controlled with the keyActionStyle

    instance variable (see SelectionInListView>>keyActionStyle:).

    Finally, ignoreReselect controls if pressing on an already selected item

    triggers the action or not. For some applications it is useful to allow

    reselects (for example, the SystemBrowsers method-list updates the

    source code in this case).

    Currently, some limited form of line attributes are supported. These

    are kept in the instance variable lineAttributes.

    This may change (using mechanisms similar to MultiColListEntry), so

    be prepared. (dont use the listAttributes instvar directly; if possible,

    use MultiColListEntry or subclasses of it.

    Although currently based on the listAttributes instVar, the implementation of

    text attributes will be changed in the near future (when Text/DisplayText are

    available). 

    However, the protocol will probably be kept for backward compatibility

    (i.e. use #attributeAt: / #attributeAt:put etc. - at least, these are easy to find

    when migrating to the new attributed text handling).

    [Instance variables:]

        selection               <misc>          the current selection. nil, a number or collection of numbers

        actionBlock             <Block>         block to be evaluated on selection changes

                                                (1-arg blocks gets selectionIndex or selectionValue

                                                 as arg - depending upon the useIndex setting)

        useIndex                <Boolean>       if true, the index of a selection is passed to

                                                the actionBlock or stuffed into the selection valueHolder;

                                                if false, the seelction-value is passed.

        enabled                 <Boolean>       true: selection changes allowed; false: ignore clicks

        hilightFgColor

        hilightBgColor          <Color>         how highlighted items are drawn

        halfIntensityColor      <Color>         foreground for disabled items

        selectCondition         <Block>         if non-nil, this block can decide if selection is ok.

                                or              its invoked with the itemNr of the

                                <ValueHolder>   'to-be-selected' item.

                                                If the block returns true, the item is selected

                                                (or added to the selection); if false is returned,

                                                no action is taken.

        selectionChangeCondition

                                <Block>         much like above, but invoked without argument,

                                or              on any change of the selection (i.e. also when items

                                <ValueHolder>   are deselected).

                                                Can return false to suppress change.

        doubleClickActionBlock  <Block>         action to perform on double-click

                                                (1-arg blocks gets selectionIndex or selectionValue

                                                 as arg - depending upon the useIndex setting)

        listAttributes                          dont use - will vanish

        hilightLevel            <Integer>       level to draw selections (i.e. for 3D effect)

        hilightFrameColor       <Color>         rectangle around highlighted items

        multipleSelectOk        <Boolean>       if true, multiple selections (with shift) are ok.

                                                default: false

        ignoreReselect          <Boolean>       if true, selecting same again does not trigger action;

                                                if false, every select triggers it.

                                                default: true

        toggleSelect            <Boolean>       if true, click toggles;

                                                if false, click selects.

                                                default: false

        arrowLevel              <Integer>       level to draw right-arrows (for submenus etc.)

        smallArrow              <Boolean>       if true, uses a small arrow bitmap

        listMsg                                 if non-nil, use ST-80 style (model-access)

        initialSelectionMsg 

        printItems 

        oneItem

        keyActionStyle          <Symbol>        controls how to respond to keyboard selects

        returnKeyActionStyle    <Symbol>        controls how to respond to return key

    written spring/summer 89 by claus

    3D Jan 90 by claus

    multiselect Jun 92 by claus

    keyboard-select jun 94 by claus

    [author:]

        Claus Gittinger

"

!

examples

"

    SelectionInListView can be used both in the ST/X way, using action blocks

    or in the traditional mvc way.

    with actions:

      basic interface:

                                                                        [exBegin]

        |top slv|

        top := StandardSystemView new

                label:'select';

                minExtent:100@100;

                maxExtent:300@400;

                extent:200@200.

        slv := SelectionInListView new.

        slv list:#('one' 'two' 'three').

        slv action:[:index | Transcript showCR:'selected ' , index printString].

        top add:slv in:(0.0@0.0 corner:1.0@1.0).

        top open

                                                                        [exEnd]

      get element instead of index:

                                                                        [exBegin]

        |top slv|

        top := StandardSystemView new

                label:'select';

                minExtent:100@100;

                maxExtent:300@400;

                extent:200@200.

        slv := SelectionInListView new.

        slv list:#('one' 'two' 'three').

        slv action:[:element | Transcript showCR:'selected ' , element printString].

        slv useIndex:false.

        top add:slv in:(0.0@0.0 corner:1.0@1.0).

        top open

                                                                        [exEnd]

      concrete example; show filenames:

      (notice: normally, you would use a FileSelectionList)

                                                                        [exBegin]

        |top slv|

        top := StandardSystemView new

                label:'select';

                minExtent:100@100;

                maxExtent:300@400;

                extent:200@200.

        slv := SelectionInListView new.

        slv list:(Filename currentDirectory directoryContents).

        slv action:[:index | 

            Transcript showCR:'selected ' , index printString.

            Transcript showCR:' the value is: ', slv selectionValue].

        top add:slv in:(0.0@0.0 corner:1.0@1.0).

        top open

                                                                        [exEnd]

      add a scrollbar:

                                                                        [exBegin]

        |top slv|

        top := StandardSystemView new

                label:'select';

                minExtent:100@100;

                maxExtent:300@400;

                extent:200@200.

        slv := SelectionInListView new.

        slv list:(Filename currentDirectory directoryContents).

        slv action:[:index | Transcript showCR:'selected ' , index printString].

        top add:(ScrollableView forView:slv) in:(0.0@0.0 corner:1.0@1.0).

        top open

                                                                        [exEnd]

      allow reselect

      (clicking on already selected entry 

       triggers action/changeNotification again):

                                                                        [exBegin]

        |top slv|

        top := StandardSystemView new

                label:'select';

                minExtent:100@100;

                maxExtent:300@400;

                extent:200@200.

        slv := SelectionInListView new.

        slv list:(Filename currentDirectory directoryContents).

        slv action:[:index | Transcript showCR:'selected ' , index printString].

        slv ignoreReselect:false.

        top add:(ScrollableView forView:slv) in:(0.0@0.0 corner:1.0@1.0).

        top open

                                                                        [exEnd]

      allow multiple selections (shift-select):

                                                                        [exBegin]

        |top slv|

        top := StandardSystemView new

                label:'select';

                minExtent:100@100;

                maxExtent:300@400;

                extent:200@200.

        slv := SelectionInListView new.

        slv list:(Filename currentDirectory directoryContents).

        slv action:[:indexList | Transcript showCR:'selected ' , indexList printString].

        slv multipleSelectOk:true.

        top add:(ScrollableView forView:slv) in:(0.0@0.0 corner:1.0@1.0).

        top open

                                                                        [exEnd]

      same, not using index:

                                                                        [exBegin]

        |top slv|

        top := StandardSystemView new

                label:'select';

                minExtent:100@100;

                maxExtent:300@400;

                extent:200@200.

        slv := SelectionInListView new.

        slv list:(Filename currentDirectory directoryContents).

        slv action:[:indexList | Transcript showCR:'selected ' , indexList printString].

        slv multipleSelectOk:true; useIndex:false.

        top add:(ScrollableView forView:slv) in:(0.0@0.0 corner:1.0@1.0).

        top open

                                                                        [exEnd]

      strikeout mode (single):

                                                                        [exBegin]

        |top slv|

        top := StandardSystemView new

                label:'select';

                minExtent:100@100;

                maxExtent:300@400;

                extent:200@200.

        slv := SelectionInListView new.

        slv list:(Filename currentDirectory directoryContents).

        slv action:[:index | Transcript showCR:'selected ' , index printString].

        slv strikeOut:true.

        top add:(ScrollableView forView:slv) in:(0.0@0.0 corner:1.0@1.0).

        top open

                                                                        [exEnd]

      strikeout mode (multiple):

                                                                        [exBegin]

        |top slv|

        top := StandardSystemView new

                label:'select';

                minExtent:100@100;

                maxExtent:300@400;

                extent:200@200.

        slv := SelectionInListView new.

        slv list:(Filename currentDirectory directoryContents).

        slv action:[:index | Transcript showCR:'selected ' , index printString].

        slv strikeOut:true; multipleSelectOk:true.

        top add:(ScrollableView forView:slv) in:(0.0@0.0 corner:1.0@1.0).

        top open

                                                                        [exEnd]

      toggleSelect mode (clicking on selected entry deselects it):

                                                                        [exBegin]

        |top slv|

        top := StandardSystemView new

                label:'select';

                minExtent:100@100;

                maxExtent:300@400;

                extent:200@200.

        slv := SelectionInListView new.

        slv list:(Filename currentDirectory directoryContents).

        slv action:[:index | Transcript showCR:'selected ' , index printString].

        slv toggleSelect:true.

        top add:(ScrollableView forView:slv) in:(0.0@0.0 corner:1.0@1.0).

        top open

                                                                        [exEnd]

      define what to do on double-click:

                                                                        [exBegin]

        |top slv|

        top := StandardSystemView new

                label:'select';

                minExtent:100@100;

                maxExtent:300@400;

                extent:200@200.

        slv := SelectionInListView new.

        slv list:(Filename currentDirectory directoryContents).

        slv action:[:index | Transcript showCR:'selected ' , index printString].

        slv doubleClickAction:[:index | Transcript showCR:'doubleclick on ' , index printString].

        top add:(ScrollableView forView:slv) in:(0.0@0.0 corner:1.0@1.0).

        top open

                                                                        [exEnd]

      enable / disable:

                                                                        [exBegin]

        |top slv|

        top := StandardSystemView new

                label:'select';

                minExtent:100@100;

                maxExtent:300@400;

                extent:200@200.

        slv := SelectionInListView new.

        slv list:(Filename currentDirectory directoryContents).

        slv action:[:index | Transcript showCR:'selected ' , index printString].

        slv disable.

        top add:(ScrollableView forView:slv) in:(0.0@0.0 corner:1.0@1.0).

        top open.

        Delay waitForSeconds:5. 

        slv enable.

                                                                        [exEnd]

      enable / disable via a channel:

                                                                        [exBegin]

        |top slv enableChannel t|

        enableChannel := true asValue.

        t := Toggle label:'enable'.

        t model:enableChannel.

        t open.

        top := StandardSystemView new

                label:'select';

                minExtent:100@100;

                maxExtent:300@400;

                extent:200@200.

        slv := SelectionInListView new.

        slv list:(Filename currentDirectory directoryContents).

        slv action:[:index | Transcript showCR:'selected ' , index printString].

        slv enableChannel:enableChannel.

        top add:(ScrollableView forView:slv) in:(0.0@0.0 corner:1.0@1.0).

        top open.

                                                                        [exEnd]

    using a Model:

                                                                        [exBegin]

        |top slv model|

        model := Plug new.

        model respondTo:#getList with:[#('foo' 'bar' 'baz' 'hello')].

        model respondTo:#initial with:[1].

        model respondTo:#setSelection: with:[:arg | Transcript showCR:'model selected:', arg printString].

        top := StandardSystemView new

                label:'select';

                minExtent:100@100;

                maxExtent:300@400;

                extent:200@200.

        slv := SelectionInListView 

                   on:model

                   aspect:#someAspect

                   change:#setSelection:

                   list:#getList

                   initialSelection:#initial.

        top add:(ScrollableView forView:slv) in:(0.0@0.0 corner:1.0@1.0).

        top open

                                                                        [exEnd]

      notice, that the ST-80 behavaior on reselect is to send a selection change

      with an index of 0.

    same, with useIndex false:

                                                                        [exBegin]

        |top slv model|

        model := Plug new.

        model respondTo:#getList with:[#('foo' 'bar' 'baz' 'hello')].

        model respondTo:#initial with:['bar'].

        model respondTo:#setSelection: with:[:arg | Transcript showCR:'model selected:', arg printString].

        top := StandardSystemView new