"

 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' }"

"{ NameSpace: Smalltalk }"

Label subclass:#Button

	instanceVariableNames:'activeLogo passiveLogo disabledLogo focusLogo onLevel offLevel

		disabledFgColor disabledEtchedFgColor activeFgColor activeBgColor

		enteredFgColor enteredBgColor isReturnButton shadowForm lightForm

		formColor formShadowColor formLightColor edgeStyle

		halfShadowColor halfLightColor defaultable enterLevel leaveLevel

		enteredLogo'

	classVariableNames:'ReturnForm ReturnLightForm ReturnShadowForm DefaultActiveLevel

		DefaultPassiveLevel DefaultEdgeStyle DefaultBorderWidth

		DefaultForegroundColor DefaultBackgroundColor

		DefaultDisabledForegroundColor DefaultDisabledBackgroundColor

		DefaultDisabledEtchedForegroundColor

		DefaultEnteredForegroundColor DefaultEnteredBackgroundColor

		DefaultActiveForegroundColor DefaultActiveBackgroundColor

		DefaultReturnButtonHasImage DefaultReturnButtonHasBorder

		DefaultShadowColor DefaultLightColor DefaultHalfShadowColor

		DefaultHalfLightColor DefaultFocusHighlightStyle'

	poolDictionaries:''

	category:'Views-Interactors'

!

!Button class methodsFor:'documentation'!

actionBlocksVersusModelChanges 

"

    You may ask yourself, why ST/X supports two different ways

    to trigger a buttons action (also true for sliders, selectionInListViews,

    toggles etc.) and when to use which mechanism.

    There are two reasons:

	1) history - historically, ST/X used only actionBlocks

	   Basically, these provide the most general functionality

	   (you can of course send change-messages from those blocks)

	   Change-message notification was added later, to make porting

	   of existing applications easier.

	2) for many (simple) applications, it is often easier, to simply

	   define an action block. This is especially true, if the button

	   triggers some action (such as ok-/abort-buttons) and does NOT

	   change some models internal value.

	   (other smalltalks provide extra adapter-models for this,

	    in which you can set actionBlocks in much the same way).

    In general:

	use model-change-messages, iff multiple views are possibly open

	on the same domain model, and changes can occur from multiple

	places. Or if a change has to be forwarded to multiple other objects

	(possible not foreseen).

	For simplicity, better use actionBlocks for trigger-like actions

	(such as closing a view, ok/abort etc.) iff there is only a single

	entity which is interested in that button press.

"

!

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

"

    Buttons are Labels which do something when pressed/released.

    Since they inherit from Label, read the documentation on Labels to 

    see how color, layout, font, image or labelString are changed.

    Buttons (and also instances of subclasses, such as toggles, checkToggles

    and radioButtons) perform some action when pressed, and optionally when

    released. Due to historic reasons, ST/X buttons support two mechanisms:

    Actionblock operation:

      the button has an actionBlock (actually, it has two: a pressAction and

      a releaseAction) which is evaluated, when the button is pressed.

      The user of a button can set these action blocks via the #action:,

      #pressAction: or #releaseAction: messages.

    Model-View interaction:

      buttons with a model will send change-messages to the model and also react 

      to changes in the model.

      You have to define the buttons labelMessage and an aspectSymbol.

      When changed, the model should send 'self changed:<aspect>' if it wants the

      label to change and return a string from the labelSymbol-message.

      By default, the labelMsg is nil, therefore no update of the label is done.

      (this behavior is inherited from label, see documentation there)

      When pressed, the button sends a changeMessage to the model.

      If the changeMsg is for a one-argument message, the current

      press-state is passed as argument (i.e. true if pressed, false if released).

      By default, the change-Message is #value: (for ST-80 compatibility).

        button model:aModel.

        button aspect:aspectSymbol.

        button change:changeSymbol.

        button labelMessage:labelSymbol.

        model sends #changed:aspectSymbol

        ---> button will redraw its label from value returned by model>>labelSymbol

        button changes state:

        ---> button sends changeSymbol / changeSymbol:state to the model

      By default (as inherited), the labelMsg is nil; therefore, buttons

      do not try to aquire a new labelString from the model.

      If you want this behavior, you must set labelMsg and aspectMsg

      as appropriate.

    labels

      Originally, labels only had a label- and disabledLabel attributes (both

      had to be explicitly set via setter methods).

      Later the model- and labelChannel interfaces were added; model interface

      for compatbility with other smalltalks, where a single multi-aspect model

      might be used, the channels were added to support visualWorks style of multiple

      single-aspect holders. This final version is also what the UIBuilder is working

      against. The other mechanisms are still present, but disabled if a newer mechanism

      is used (i.e. if a labelChannel has been given, the label and disabledLabel instvars

      are ignored).

      All of this is here to provide backward compatibility for existing customers

      and st/x programs (which is a good thing to have, b.t.w).

    See examples.

    [Instance variables:]

      activeLogo              <StringOrImage> logo to show when active (pressed)

      passiveLogo             <StringOrImage> logo to show when passive (released)

                                              default is nil for both, so the normal logo is used

                                              (see superclass: Label)

      onLevel                 <Integer>       level when pressed (3D only) (default: depends on style)

      offLevel                <Integer>       level when released (3D only) (default: depends on style)

      disabledFgColor         <Color>         color used to draw logo when disabled (default: depends on style)

      activeFgColor           <Color>         color to draw logo when pressed (default: depends on style)

      activeBgColor           <Color>         bg color when pressed (default: depends on style)

      enteredFgColor          <Color>         fg color to draw logo when cursor entered (default: depends on style)

      enteredBgColor          <Color>         bg color when cursor entered (default: depends on style)

      isReturnButton          <Boolean>       true if this button is also activated by the

                                              return key - if true, it will draw a return-bitmap 

                                              in addition to the logo (default: false)

      defaultable             <Boolean>       true, if this button can become a returnButton.

                                              (computes its default extent differently)

      shadowForm              <Form>          form to display in addition to buttons label (returnbutton only)

      lightForm               <Form>          light part of shadowForm (returnbutton only)

      formColor               <Color>         color to draw form with (returnbutton only)

      formShadowColor         <Color>         color for shadowing the form (3D only & return)

      formLightColor          <Color>         color for lighting the form (3D only)

    [styleSheet parameters:]

      buttonActiveLevel       <Integer>       level when on (ignored in 2D styles)

      buttonPassiveLevel      <Integer>       level when off (ignored in 2D styles)

      buttonBorderWidth       <Integer>       default borderwidth

      buttonEdgeStyle         <Symbol>        style of edges (currently #soft or nil)

      buttonFont              <Font>          font to use for textual labels

      buttonForegroundColor   <Color>         color to draw foreground pixels (i.e. the string)

      buttonBackgroundColor   <Color>         color to draw background pixels

      buttonDisabledForegroundColor <Color>   same when disabled

      buttonDisabledBackgroundColor <Color>   same when disabled

      buttonEnteredForegroundColor  <Color>   same when mouse pointer is in

      buttonEnteredBackgroundColor  <Color>   same when mouse pointer is in

      buttonActiveForegroundColor   <Color>   same when button is active

      buttonActiveBackgroundColor   <Color>   same when button is active

      buttonShadowColor             <Color>   shadow color for edgaes (ignored in 2D styles)

      buttonLightColor              <Color>   light color for edgaes (ignored in 2D styles)

      buttonHalfShadowColor         <Color>   half shadow color; for soft edges only

      buttonHalfLightColor          <Color>   half light color; for soft edges only

      buttonReturnButtonHasImage    <Boolean> if true, return-buttons draw a return-key image

      buttonReturnButtonHasBorder   <Boolean> if true, return-buttons show a border

    [author:]

        Claus Gittinger

    [see also:]

        Toggle CheckToggle CheckBox

        Dialog

        ValueHolder TriggerValue

        Block

"

!

examples 

"

    You don't have to normally care for all the internals 

    (they allow many variations though). 

    For buttons with a stringLabel, the typical use is:

        b := Button label:'some logo' in:aView.

        b action:[ .. things to do, when pressed ... ]

    and for bitmap/image buttons its:

        b := Button label:someImage in:aView.

        b action:[ .. things to do, when pressed ... ]

    Of course, you can also setup things the ST-80 way, in first

    creating the button and later add it to some superview:

        b := Button new.

        b label:someImage.

        b action:[ .. things to do, when pressed ... ]

        ...

        aSuperView add:b in:<frameRectangle>.

    Although you can specify most of the look of a button,

    you should use the defaults in most applications.

    As you specify more things in your program, 

    the styleSheet settings are more and more ignored.

    Also, even though it might look fancy, colorful

    button panels are usually not a good GUI design;

    they will attract the users attention - possibly to things

    which are not worth it.

    Finally, if you use fancy colors, always think of those poor users

    without color displays - the styleSheet allows those people to adjust things,

    while hard-coded colors cannot be fixed without changing the code.

    a simple button with default settings and no action:

    (you may want to try it with different viewStyle settings in effect):

                                                                        [exBegin]

          |top b|

          top := StandardSystemView new.

          top extent:100@100.

          b := Button in:top.

          b label:'hello'.

          top open.

                                                                        [exEnd]

    give it some action (watch the transcript):

                                                                        [exBegin]

          |top b|

          top := StandardSystemView new.

          top extent:100@100.

          b := Button in:top.

          b label:'hello'.

          b action:[Transcript flash].

          top open.

                                                                        [exEnd]

    there is also a combined instance creation message:

                                                                        [exBegin]

          |top b|

          top := StandardSystemView new.

          top extent:100@100.

          b := Button label:'hello' action:[Transcript flash] in:top.

          top open.

                                                                        [exEnd]

    a return button

    (in dialogs, you should setup things to have the return-key perform

     the ok action, and mark the corresponding button as being a returnButton):

                                                                        [exBegin]

          |top b|

          top := StandardSystemView new.

          top extent:100@100.

          b := Button label:'hello' action:[Transcript flash] in:top.

          b beReturnButton.

          top open.

                                                                        [exEnd]

    multiple buttons in a panel:

                                                                        [exBegin]

          |top panel b1 b2 b3|

          top := StandardSystemView new.

          top extent:300@100.

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

          b1 := Button label:'one'   in:panel.

          b2 := Button label:'two'   in:panel.

          b3 := Button label:'three' action:[Transcript flash] in:panel.

          top open.

                                                                        [exEnd]

    enabling/disabling buttons via explicit messages:

                                                                        [exBegin]

          |top panel b1 b2 b3|

          top := StandardSystemView new.

          top extent:300@100.

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

          b1 := Button label:'enable'  action:[b3 enable] in:panel.

          b2 := Button label:'disable' action:[b3 disable] in:panel.

          b3 := Button label:'flash'   action:[Transcript flash] in:panel.

          top open.

                                                                        [exEnd]

    enabling/disabling buttons via implicit value change of a valueHolder:

    The two views are only indirectly coupled (via the valueHolder);

    not knowing about each other.

                                                                        [exBegin]

          |top panel ena t b1 b2 b3 check|

          top := StandardSystemView new.

          top extent:300@100.

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

          ena := false asValue.

          t := Toggle label:'enable' in:panel.

          t model:ena.

          b1 := Button label:'button1' in:panel.

          b1 controller enableChannel:ena.

          b2 := Button label:'button2' in:panel.

          b2 controller enableChannel:ena.

          b3 := Button label:'button3' in:panel.

          b3 controller enableChannel:ena.

          top open.

          check := CheckBox model:ena.

          check label:'also enable'.

          check extent:(check preferredExtent + (5@5)).

          check open

                                                                        [exEnd]

    changing colors:

                                                                        [exBegin]

          |top b|

          top := StandardSystemView new.

          top extent:100@100.

          b := Button label:'hello' in:top.

          b action:[Transcript flash].

          b activeForegroundColor:(Color white).

          b activeBackgroundColor:(Color red).

          top open.

                                                                        [exEnd]

    changing more colors:

                                                                        [exBegin]

          |top b|

          top := StandardSystemView new.

          top extent:100@100.

          b := Button label:'hello' in:top.

          b action:[Transcript flash].

          b enteredForegroundColor:(Color red).

          b enteredBackgroundColor:(b backgroundColor).

          b activeForegroundColor:(Color white).

          b activeBackgroundColor:(Color red).

          top open.

                                                                        [exEnd]

    button with an image and different colors:

                                                                        [exBegin]

          |top b|

          top := StandardSystemView new.

          top extent:100@100.

          b := Button in:top.

          b label:(Image fromFile:'bitmaps/SBrowser.xbm').

          b action:[Transcript flash].

          b enteredForegroundColor:(Color green darkened).

          b enteredBackgroundColor:(b backgroundColor).

          b activeForegroundColor:(Color white).

          b activeBackgroundColor:(Color red).

          top open.

                                                                        [exEnd]

    changing the image when pressed:

                                                                        [exBegin]

          |top b|

          top := StandardSystemView new.

          top extent:100@100.

          b := Button in:top.

          b passiveLogo:(Image fromFile:'bitmaps/SBrowser.xbm').

          b activeLogo:(Image fromFile:'bitmaps/CBrowser.xbm').

          b action:[Transcript flash].

          b enteredForegroundColor:(Color red).

          b enteredBackgroundColor:(b backgroundColor).

          b activeForegroundColor:(Color white).

          b activeBackgroundColor:(Color red).

          top open.

                                                                        [exEnd]

    well, even that is possible (but you should NEVER do it):

                                                                        [exBegin]

          |top b|

          top := StandardSystemView new.

          top extent:100@100.

          b := Button in:top.

          b passiveLogo:(Image fromFile:'../../goodies/bitmaps/xpmBitmaps/misc_tools/email.xpm').

          b activeLogo:'start'.

          b action:[Transcript flash].

          b enteredForegroundColor:(Color red).

          b enteredBackgroundColor:(b backgroundColor).

          b activeForegroundColor:(Color white).

          b activeBackgroundColor:(Color red).

          top open.

                                                                        [exEnd]

    more playing with colors:

                                                                        [exBegin]

          |top b|

          top := StandardSystemView new.

          top extent:100@100.

          b := Button in:top.

          b logo:(Image fromFile:'../../goodies/bitmaps/xbmBitmaps/TicTacToe.xbm').

          b action:[Transcript flash].

          b foregroundColor:(Color red:0 green:80 blue:20) darkened.

          b backgroundColor:(Color grey:10).

          b enteredForegroundColor:(Color red).

          b activeForegroundColor:(Color red).

          b activeBackgroundColor:(Color grey:50).