"

 COPYRIGHT (c) 1994 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' }"

Button subclass:#PopUpList

	instanceVariableNames:'menu menuAction values useIndex listMsg defaultLabel listHolder

		showHandle'

	classVariableNames:''

	poolDictionaries:''

	category:'Views-Interactors'

!

!PopUpList class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 1994 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

"

    a PopUpList is basically a button with a popup menu.

    The PopUpLists label is showing the current selection from the

    list.

    When an entry is selected, an actionBlock (if nonNil) is evaluated

    and (if nonNil), the model is notified via the changeMessage.

    If no model is set, the list is assumed to be a static list, which

    is defined via #list:, and the popUpList evaluates the action block,

    as defined via #action:.

    If a model is provided, it should return the current selected items index via the 

    aspectMessage (default is #selection or: #selectionIndex, depending on the setting 

    of useIndex) and the list via the listMessage (default is #list).

    If the listMessage was set to nil, the list is not aquired from the model

    and can be set explicitely via #list:.

    The defaults are set to allow a PopUpList to be used with a SelectionInList 

    as model without further setup.

    A simple valueHolder may also be used without further setup.

    (if used with some other model, either use an adaptor, or set the

     change/aspect and/or listMessage to something else ..)

    If a listHolder is set, this one is always asked for the list instead of the

    model, via the #value message. 

    This allows the popUpListView to aquire the list and value from different places.

    Notice: PopUpList and ComboListView provide a similar protocol and functionality.

    [Instance variables:]

        menu                            helpers for the popup menu

        menuAction 

        values 

        useIndex             <Boolean>  if true, the index of the selected entry

                                        is passed to the action block and the

                                        model in a change-message.

                                        If false (the default), the value is passed.

                                        Notice that the default changeMessage is

                                        #selection:, which is not ok to be used

                                        with useIndex:true and a selectionInList model.

                                        (set the changeMessage to #selectionIndex: then)

        listMsg              <Symbol>   message to aquire a new list from the

                                        model. Default is #list.

        listHolder           <Object>   if non-nil, this object is assumed to return the

                                        list via the listMsg (instead of the model).

                                        Default is nil.

    [see also:]

        SelectionInList ValueHolder

        SelectionInListView

        ComboListView

    [author:]

        Claus Gittinger

"

!

examples

"

  non-MVC use:

                                                                        [exBegin]

     |p|

     p := PopUpList label:'healthy fruit'.

     p list:#('apples' 'bananas' 'grape' 'lemon' 'margaritas').

     p open

                                                                        [exEnd]

    with an initial selection:

                                                                        [exBegin]

     |p|

     p := PopUpList label:'dummy'.

     p list:#('apples' 'bananas' 'grape' 'lemon' 'margaritas').

     p selection:'apples'.

     p open

                                                                        [exEnd]

    with separating lines:

                                                                        [exBegin]

     |p|

     p := PopUpList label:'fruit'.

     p list:#('apples' 'bananas' 'grape' 'lemon' '-' 'margaritas').

     p selection:'apples'.

     p open

                                                                        [exEnd]

    draw without menu-handle:

                                                                        [exBegin]

     |p|

     p := PopUpList label:'fruit'.

     p list:#('apples' 'bananas' 'grape' 'lemon' '-' 'margaritas').

     p showHandle:false.

     p open

                                                                        [exEnd]

    with an action:

                                                                        [exBegin]

     |p|

     p := PopUpList label:'dummy'.

     p list:#('apples' 'bananas' 'grape' 'lemon' '-' 'margaritas').

     p selection:'apples'.

     p action:[:what | Transcript showCR:'you selected: ' , what].

     p open

                                                                        [exEnd]

    sometimes, you may like the index instead of the value:

    (notice, that the separating line counts, so you have to take care ...)

                                                                        [exBegin]

     |p|

     p := PopUpList label:'dummy'.

     p list:#('apples' 'bananas' 'grape' 'lemon' '-' 'margaritas').

     p selection:'apples'.

     p action:[:what | Transcript show:'you selected: '; showCR:what].

     p useIndex:true.

     p open

                                                                        [exEnd]

    since the list is actually a popupMenu, you can add double-separators:

    also, here values are different from the labels

                                                                        [exBegin]

     |p|

     p := PopUpList label:'dummy'.

     p list:#('apples' 'bananas' 'grape' 'lemon' 

              '=' 

              'margaritas' 'pina colada'

              '=' 

              'smalltalk' 'c++' 'eiffel' 'java').

     p values:#(apples bananas grape lemon 

                nil 

                'mhmh - so good' 'makes headache'

                nil

                'great' 'another headache' 'not bad' 'neat').

     p selection:'apples'.

     p action:[:what | Transcript show:'you selected: '; showCR:what].

     p open

                                                                        [exEnd]

    since the list is actually represented by a menuView,

    which itself is inheriting from listView, which itself can display

    things different from strings, arbitrary lists can be constructed:

    (see ListEntry, LabelAndIcon and Text classes)

                                                                        [exBegin]

     |p l|

     p := PopUpList label:'dummy'.

     l := OrderedCollection new.

     l add:(Text string:'apples' color:Color red).

     l add:(Text string:'bananas' color:Color red).

     l add:(Text string:'grape' color:Color red).

     l add:(Text string:'lemon' color:Color red).

     l add:'='.

     l add:(Text string:'margaritas' color:Color green darkened darkened).

     l add:(Text string:'pina colada' color:Color green darkened darkened).

     l add:'='.

     l add:(Text string:'smalltalk' color:Color blue).

     l add:(Text string:'c++' color:Color blue).

     l add:(Text string:'eiffel' color:Color blue).

     l add:(Text string:'java' color:Color blue).

     p list:l.

     p values:#(apples bananas grape lemon 

                nil 

                'mhmh - so good' 'makes headache'

                nil

                'great' 'another headache' 'not bad' 'neat').

     p selection:'apples'.

     p action:[:what | Transcript show:'you selected: '; showCR:what].

     p open

                                                                        [exEnd]

    with values different from the label strings:

                                                                        [exBegin]

     |p|

     p := PopUpList label:'dummy'.

     p list:#('apples' 'bananas' 'grape' 'lemon' '-' 'margaritas').

     p selection:'apples'.

     p values:#(10 20 30 40 nil 50).

     p action:[:what | Transcript show:'you selected: '; showCR:what].

     p open

                                                                        [exEnd]

    with values different from the label strings:

                                                                        [exBegin]

     |p|

     p := PopUpList label:'language selection'.

     p list:( #(

                'usa'

                'uk'

                'france'

                'germany'       

                'italy'

               ) collect:[:country |

                            LabelAndIcon 

                                icon:(Image fromFile:'bitmaps/xpmBitmaps/countries/' , country , '.xpm')

                                string:country

                         ]

            ).

     p values:#(us england france germany italy).

     p action:[:what | Transcript show:'you selected: '; showCR:what].

     p open

                                                                        [exEnd]

  with a model (see in the inspector, how the index-holders value changes)

  the defaults are setup to allow a SelectionInList directly as model:

                                                                        [exBegin]

     |p model|

     model := SelectionInList with:#('apples' 'bananas' 'grape' 'lemon' 'margaritas').

     p := PopUpList label:'healthy fruit'.

     p model:model.

     p open.

     model inspect

                                                                        [exEnd]

  model provides selection; list is explicit:

  must change the aspect, since the default setup is for a SelectionInList

                                                                [exBegin]

     |model top b|

     model := 'foo' asValue.

     top := StandardSystemView new.

     top extent:(300 @ 200).

     b := PopUpList in:top.

     b origin:(0.0 @ 0.0) corner:(1.0 @ 0.0).

     b bottomInset:(b preferredExtent y negated).

     b list:#('hello' 'world' 'this' 'is' 'st/x').

     b model:model; aspect:#value; change:#value:.

     top openModal.

     Transcript showCR:('comboBox''s value: ' , model value).

                                                                [exEnd]

    a popupList and a SelectionInListView on the same model:

                                                                        [exBegin]

     |p slv model|

     model := SelectionInList with:#('apples' 'bananas' 'grape' 'lemon' 'margaritas').

     model selection:'apples'.

     p := PopUpList on:model.

     p open.

     slv := SelectionInListView on:model.

     slv open.

                                                                        [exEnd]

    dynamically changing the list (click button(s) to change):

                                                                        [exBegin]

     |p slv model b|

     model := SelectionInList with:#('apples' 'bananas' 'grape' 'lemon' 'margaritas').

     model selection:'apples'.

     p := PopUpList on:model.

     p open.

     slv := SelectionInListView on:model.

     slv open.

     b := Button label:'long list' action:[model list:#('1' '2' '3' '4' '5' '6')].

     b open.

     b := Button label:'short list' action:[model list:#('1' '2' '3')].

     b open.

                                                                        [exEnd]

    two PopUpLists on the same model, different aspects:

                                                                        [exBegin]

     |top panel p model|

     model := Plug new.

     model respondTo:#eat: with:[:val | Transcript showCR:'eat: ' , val].

     model respondTo:#drink: with:[:val | Transcript showCR:'drink: ' , val].

     model respondTo:#meals with:[#(taco burrito enchilada)].

     model respondTo:#drinks with:[#(margarita water corona)].

     top := StandardSystemView new.

     top extent:(100@100).

     panel := VerticalPanelView origin:0.0@0.0 corner:1.0@1.0 in:top.

     panel horizontalLayout:#fitSpace.

     p := PopUpList label:'meals'.

     p model:model; listMessage:#meals; aspect:nil; change:#eat:.

     panel add:p.

     p := PopUpList label:'drinks'.

     p model:model; listMessage:#drinks; aspect:nil; change:#drink:.

     panel add:p.

     top open

                                                                        [exEnd]

    with separate list- and indexHolders:

                                                                        [exBegin]

     |p selectionHolder listHolder|

     listHolder := #('apples' 'bananas' 'grape' 'lemon' 'margaritas') asValue.

     selectionHolder := 'apples' asValue.

     p := PopUpList label:'healthy fruit'.

     p listHolder:listHolder.

     p model:selectionHolder; aspect:#value; change:#value:.

     p open.

     selectionHolder inspect

                                                                        [exEnd]

    same, using index:

                                                                        [exBegin]

     |p selectionIndexHolder listHolder|

     listHolder := #('apples' 'bananas' 'grape' 'lemon' 'margaritas') asValue.

     selectionIndexHolder := 3 asValue.

     p := PopUpList new.

     p listHolder:listHolder.

     p model:selectionIndexHolder; aspect:#value; change:#value:.

     p useIndex:true.

     p open.

     selectionIndexHolder inspect

                                                                        [exEnd]

    using different values:

                                                                        [exBegin]

     |p selectionHolder listHolder values|

     listHolder := #('apples' 'bananas' 'grape' 'lemon' 'margaritas') asValue.

     values := #(apples bananas grape lemon alcohol).

     selectionHolder := #alcohol asValue.

     p := PopUpList label:'healthy fruit'.

     p listHolder:listHolder.

     p model:selectionHolder; aspect:#value; change:#value:.

     p values:values.

     p open.

     selectionHolder inspect

                                                                        [exEnd]

    provide your own menu (spec could come from a specMethod):

                                                                        [exBegin]

     |p myMenu selectionHolder|

     selectionHolder := nil asValue.

     myMenu :=

       #(#Menu

           #(

            #(#MenuItem

                #label: 'Oranges'

                #translateLabel: true

                #value: #oranges

            )

            #(#MenuItem

                #label: 'Lemons'

                #translateLabel: true

                #value: #lemons

            )

            #(#MenuItem

                #label: 'grape'

                #translateLabel: true

                #value: #grape

            )

            #(#MenuItem

                #label: '-'

            )

            #(#MenuItem

               #label: 'other'

               #translateLabel: true

               #value: #other

               #submenu: 

                  #(#Menu

                     #(

                      #(#MenuItem

                         #label: 'margarita'

                         #translateLabel: true

                         #value: #margarita

                       )

                      #(#MenuItem

                         #label: 'vine'

                         #translateLabel: true

                         #value: #vine

                       )

                      )

                   )

            )

          )

       ) decodeAsLiteralArray.

     p := PopUpList label:'healthy fruit'.

     p menu:myMenu.

     p model:selectionHolder; aspect:#value; change:#value:.

     selectionHolder inspect.

     p open.

                                                                        [exEnd]

"

! !

!PopUpList class methodsFor:'defaults'!

defaultAspectMessage

    ^ #selection

!

defaultChangeMessage

    ^ #selection:

!

defaultListMessage

    ^ #list 

! !

!PopUpList methodsFor:'accessing'!

contents

    "return the current contents"

    ^ self label

!

contents:con

    "change the contents"