"

 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.

"

View subclass:#Label

	instanceVariableNames:'logo labelWidth labelHeight labelOriginX labelOriginY adjust

		hSpace vSpace bgColor fgColor fixSize labelMsg converter

		labelChannel foregroundChannel backgroundChannel'

	poolDictionaries:''

	category:'Views-Layout'

!

!Label 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 class implements labels, which are views to display a string or image.

    The Label will try to do its best to make its contents fit into the

    view. The contents can be a String, a collection of Strings (i.e.

    a StringCollection) or a Form/Image. 

    The contents is drawn in fgColor/bgColor, which can be changed using:

	aLabel foregroundColor:aColor

	aLabel backgroundColor:aColor

    When a label is assigned a contents, it will resize itself to fit

    the required size. This resizing can be suppressed by setting the

    fixsize attribute to true using:

	aLabel sizeFixed:true

    This can be used, if resizing of the label is not wanted.

    However, in this case you have to make certain that the size is big enough

    to hold any changed logos later. (usually, you create the label first with

    the longest string first to have it compute its size, then set the fixSize 

    attribute to avoid resizing later).

    Be careful when placing self-resizing labels into panels - by default,

    panels do not react on the size change - leading to ugly looking geometry.

    (but you can tell the panel to watch for changes with #elementsCHangeSize:)

    The placement of the contents within the label is controlled by

    the adjust attribute, it can be set with:

	aLabel adjust:how

    where how is one of the symbols left, #right, #center, #centerLeft,

    #centerRight, #leftRight or #rightLeft (see the comment in Label>>adjust:). 

    The default is #center.

    model-less operation (ok for static labels):

      if no model is set, the labels contents is set with:

	aLabel label:aStringOrImage

      and stays constant unless changed by new calls to #label:.

    model operation (ST-80 style):

      labels with a model, aspectMsg and labelMsg react to 

      changes of the aspect, and send a labelMsg-message 

      to the model in order to aquire a new labelString or image.

      The model should send 'self changed:aspectMsg' if it thinks the label 

      should change and return a string or image from the labelMsg-message.

	label model:aModel.

	label aspect:aspectSymbol.

	label labelMessage:labelSymbol.

	model sends #changed:aspectSymbol

	---> label will redraw its label from value of model perform:labelSymbol

      Having a labelSymbol different from the aspectSymbol allows for two labels

      to react on the same aspect-change, but use different messages when asking

      the model for a new label contents. By default, the labelMsg is nil,

      so the label does NOT update its shown contents.

      The aspectMsg defaults to #value.

    channel operation (new ST/X style):

      the label will react on changes of the token found in the

      channels: foregroundChannel, backgroundChannel and labelChannel.

      These are valueHolders and can be shared between labels.

    Instance variables:

	logo                <Object>        the logo, can be a Form, String or Text

	labelWidth          <Integer>       the width of the logo in device units

	labelHeight         <Integer>       the height of the logo in device units

	labelOriginX        <Integer>       the x-position of the logo withing the Label

	labelOriginY        <Integer>       the y-position of the logo withing the Label

	adjust              <Symbol>        controls how the logo is positioned within the

					    label. Can be one of:#left,#right,#center,

					    #centerLeft or #centerRight (see comment in adjust:)

	hSpace              <Integer>       number of horizontal pixels around logo

	vSpace              <Integer>       number of vertical pixels around logo

	bgColor             <Color>         background color

	fgColor             <Color>         foreground color

	fixSize             <Boolean>       if true, a change of the logo change will not

					    resize the label; otherwise, its size is adjusted.

					    default:false.

	labelMsg            <Symbol>        if non-nil, this is sent to the model to

					    aquire the labelString or labelImage.

					    If nil, the label stays as is

    styleSheet parameters:

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

      labelBackgroundColor    <Color>         color to draw background pixels

      labelFont               <Font>          font to use for textual labels

"

!

examples

"

    Notice, that Buttons and others inherit from Label; 

    therefore, the following geometry examples apply to all subclasses too.

    simple (default position is 0@0):

	|top l|

	top := StandardSystemView new.

	top extent:(200 @ 200).

	l := Label in:top.

	l label:'hello world'.

	top open

    there is also a creation message which sets the label:

	|top l|

	top := StandardSystemView new.

	top extent:(200 @ 200).

	l := Label label:'hello world' in:top.

	top open

    placement:

	|top l|

	top := StandardSystemView new.

	top extent:(200 @ 200).

	l := Label in:top.

	l label:'hello world'.

	l origin:50@100.

	top open

    level:

	|top l|

	top := StandardSystemView new.

	top extent:(200 @ 200).

	l := Label in:top.

	l level:5.

	l label:'hello world'.

	l origin:50@100.

	top open

    another level:    

	|top l|

	top := StandardSystemView new.

	top extent:(200 @ 200).

	l := Label in:top.

	l level:-1.

	l label:'hello world'.

	l origin:50@100.

	top open

    colors & font:    

	|top l|

	top := StandardSystemView new.

	top extent:(200 @ 200).

	l := Label in:top.

	l level:-1.

	l font:(Font family:'Times' size:18).

	l foregroundColor:Color yellow.

	l backgroundColor:Color red.

	l label:'hello world'.

	l origin:50@100.

	top open

    border & colors:    

	|top l|

	top := StandardSystemView new.

	top extent:(200 @ 200).

	l := Label in:top.

	l level:0.

	l borderWidth:1.

	l borderColor:Color red.

	l foregroundColor:Color green darkened.

	l backgroundColor:Color green lightened.

	l label:'hello world'.

	l origin:50@100.

	top open

    different adjusts (resize to see):    

	|top l|

	top := StandardSystemView new.

	top extent:(300 @ 250).

	top label:'make me smaller'.

	l := Label in:top.

	l borderWidth:1.

	l label:'default - #centered'.

	l origin:0.1@40.

	l width:0.8.

	l := Label in:top.

	l borderWidth:1.

	l adjust:#left.

	l label:'#left adjust'.

	l origin:0.1@70.

	l width:0.8.

	l := Label in:top.

	l borderWidth:1.

	l adjust:#right.

	l label:'#right adjust'.

	l origin:0.1@100.

	l width:0.8.

	l := Label in:top.

	l borderWidth:1.

	l adjust:#centerLeft.

	l label:'#centerLeft adjust with a long text'.

	l origin:0.1@130.

	l width:0.8.

	l := Label in:top.

	l borderWidth:1.

	l adjust:#centerRight.

	l label:'#centerRight adjust with a long text'.

	l origin:0.1@160.

	l width:0.8.

	l := Label in:top.

	l borderWidth:1.

	l adjust:#leftRight.

	l label:'#leftRight adjust with a long text'.

	l origin:0.1@190.

	l width:0.8.

	l := Label in:top.

	l borderWidth:1.

	l adjust:#rightLeft.

	l label:'#rightLeft adjust with a long text'.

	l origin:0.1@220.

	l width:0.8.

	top open

    fitting-adjust (resize to see):

    Warning: #fit is experimental and should not be used.

	|top l|

	top := StandardSystemView new.

	top extent:(200 @ 200).

	l := Label origin:0.25 @ 0.25 corner:0.75@0.75 in:top.

	l label:'stretch'.

	l level:-1.

	l adjust:#fit.

	top open

    or:

    Warning: #fit is experimental and should not be used.

	|top l|

	top := StandardSystemView new.

	top extent:(200 @ 200).

	l := Label origin:0.25 @ 0.25 corner:0.75@0.75 in:top.

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

	l level:-1.

	l adjust:#fit.

	top open

    just a reminder, that instead of doing placement manually

    as in ...:    

	|top l|

	top := StandardSystemView new.

	top extent:(200 @ 200).

	l := Label in:top.

	l borderWidth:1.

	l label:'default - centered'.

	l origin:0.1@70.

	l width:0.8.

	l := Label in:top.

	l borderWidth:1.

	l adjust:#left.

	l label:'left adjust'.

	l origin:0.1@100.

	l width:0.8.

	l := Label in:top.

	l borderWidth:1.

	l adjust:#right.

	l label:'right adjust'.

	l origin:0.1@130.

	l width:0.8.

	top open

    ... it is much easier, to use a geometry handler, such as

    a VerticalPanel. Try:

	|top panel l|

	top := StandardSystemView new.

	top extent:(200 @ 200).

	panel := VerticalPanelView 

			origin:0.1 @ 0.0 

			corner:0.9 @ 1.0 

			    in:top.

	panel horizontalLayout:#fit.

	panel verticalLayout:#center.

	l := Label in:panel.

	l borderWidth:1.

	l label:'default - centered'.

	l := Label in:panel.

	l borderWidth:1.

	l adjust:#left.

	l label:'left adjust'.

	l := Label in:panel.

	l borderWidth:1.

	l adjust:#right.

	l label:'right adjust'.

	top open

    labels with bitmaps or images:

	|top l|

	top := StandardSystemView new.

	top extent:(200 @ 200).

	l := Label in:top.

	l level:-1.

	l label:((Image fromFile:'bitmaps/garfield.gif') magnifyBy:0.2 @ 0.2).

	l origin:50@100.

	top open

     that even works with #fit:

	|top l|

	top := StandardSystemView new.

	top extent:(200 @ 200).

	l := Label in:top.

	l adjust:#fit.

	l level:-1.

	l label:(Image fromFile:'bitmaps/garfield.gif').

	l origin:0.2@0.2 corner:0.8@0.8.

	top open

     notice, that Buttons inherit from Label; thus:

	|top b|

	top := StandardSystemView new.

	top extent:(200 @ 200).

	b := Button in:top.

	b adjust:#fit.

	b label:(Image fromFile:'bitmaps/garfield.gif').

	b origin:0.2@0.2 corner:0.8@0.8.

	b action:[Transcript showCr:'wow'].

	top open

     Channel operation (controlling gf, bg and labelText via ValueHolders)

     -----------------

	|top panel logoChannel fgChannel bgChannel l b|

	top := StandardSystemView new.

	top extent:(450 @ 200).

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

	l := Label in:panel.

	l level:-1.

	l label:'change my colors'.

	l origin:50@100.

	l sizeFixed:true.

	fgChannel := Color blue asValue.

	bgChannel := Color grey asValue.

	logoChannel := 'change me' asValue.

	b := Toggle label:'change fg' in:panel. b showLamp:false; onLevel:-2.

	b pressAction:[fgChannel value:Color red].

	b releaseAction:[fgChannel value:Color blue].

	b := Toggle label:'change bg' in:panel.

	b pressAction:[bgChannel value:Color yellow].

	b releaseAction:[bgChannel value:Color grey].

	b := Toggle label:'change text' in:panel.

	b pressAction:[logoChannel value:'wow'].

	b releaseAction:[logoChannel value:'not bad' ].

	l labelChannel:logoChannel.

	l foregroundChannel:fgChannel.

	l backgroundChannel:bgChannel.