"

 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:#ListView

	instanceVariableNames:'list firstLineShown leftOffset nFullLinesShown nLinesShown

		fgColor bgColor partialLines leftMargin topMargin textStartLeft

		textStartTop innerWidth tabPositions lineSpacing fontHeight

		fontAscent fontIsFixedWidth fontWidth autoScroll autoScrollBlock

		autoScrollDeltaT searchPattern wordCheck includesNonStrings

		widthOfWidestLine listMsg viewOrigin listChannel'

	classVariableNames:'DefaultForegroundColor DefaultBackgroundColor DefaultTabPositions'

	poolDictionaries:''

	category:'Views-Text'

!

!ListView 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

"

    a View for (string-)lists.

    This class can only passively display collections of strings-

    selections, editing, cursors etc. must be done in subclasses.

    see SelectionInListView, TextView etc.

    This code currently handles only fixed-height fonts correctly -

    should be rewritten in some places ...

    It can only scroll by full lines vertically (i.e. setting firstLineShown to ~~ 1)

    which should be changed to have this behavior optionally for smooth scroll.

    The text is internally kept in the list instance variable, and is supposed to consist

    of a collection (Ordered- or StringCollection) of line entries.

    Typically, individual entries are either strings or nil (for empty lines).

    However, any object which supports the displayOn: and widthIn: protocol can be

    used - see MultipleColumnListEntry as an example.

    Therefore, ListView (and all subclasses) are prepared to handle non-string entries

    (especially: attributed Text).

    The internal version of the text has tabulators expanded to blanks - when text is exchanged

    with an external medium (i.e. reading/writing files), these are expanded/compressed assuming

    a tab-setting of 8. This is done independent of the users tab setting, which is used

    while the text is edited. Thus, even if the tab setting is multiple of 4's, tabs are

    written in multiples of 8 when the text is saved. Since this is the default on all ascii

    terminals and printers, this assures that the text looks correctly indented when finally printed.

    Notice:

    ListView is one of the oldest widget classes in the current system and

    definitely requires some rewrite:

    Due to historic reasons (ListView implemented scrolling before the general

    scrolling code in View was added), this one does scrolling different from all other

    views. The general scrolling code (in View) uses the transformation for transparent scrolling.

    Here, the transformation is not used, instead it is done again, by keeping the firstLineShown

    (i.e. vertical offset) and leftOffset (horizontal offset).

    The most annoying consequence of this is, that scrolling is done by lines here, 

    while its done in pixels in the View class. Thus, be careful, when changing things

    (better: dont touch it ;-)

    Also, all controller functionality is completely performed by the listView

    (and subclasses) itself. It is still possible, to define and set a specialized

    controller, though. I.e. if you like to change the input behavior, define

    a corresponding controller class and intersect the keyXXX/buttonXXX messages

    there.

    This will be totally rewritten ... so dont depend on the internals; especially the scrolling

    code will be totally removed here and the inherited functionality be used in the next version.

    [Instance variables:]

      list            <aCollection>           the text strings

      firstLineShown  <Number>                the index of the 1st visible line (1 ..)

      leftOffset      <Number>                left offset for horizontal scroll

      nFullLinesShown <Number>                the number of unclipped lines in visible area

                                              (internal; updated on size changes)

      nLinesShown     <Number>                the number of lines in visible area, incl. partial

                                              (internal; updated on size changes)

      fgColor         <Color>                 color to draw characters

      bgColor         <Color>                 the background

      partialLines    <Boolean>               allow last line to be partial displayed

      leftMargin      <Number>                margin at left in pixels

      topMargin       <Number>                margin at top in pixels

      textStartLeft   <Number>                margin + leftMargin (internal)

      textStartTop    <Number>                margin + topMargin (internal)

      innerWidth      <Number>                width - margins (internal)

      tabPositions    <aCollection>           tab stops (cols)

      fontHeight      <Number>                font height in pixels (internal)

      fontAscent      <Number>                font ascent in pixels (internal)

      fontIsFixed     <Boolean>               true if its a fixed font (internal)

      fontWidth       <Number>                width of space (internal)

      lineSpacing     <Number>                pixels between lines

      searchPattern   <String>                last pattern for searching

      wordCheck       <Block>                 rule used for check for word boundaries in word select

                                              The default rule is to return true for alphaNumeric characters.

                                              (can be changed to allow for underscore and other

                                               characters to be treated as alphaCharacters)

      autoScrollBlock <Block>                 block installed as timeoutBlock when doing an

                                              autoScroll (internal)

      autoScrollDeltaT                        computed scroll time delta in seconds (internal)

      includesNonStrings                      cached flag if any non-strings are in list

      widthOfWidestLine                       cached width of widest line

      listMsg                                 if view has a model and listMsg is non-nil,

                                              this is sent to the model to aquired a new contents

                                              whenever a change of the aspect  (aspectMsg) occurs.

      viewOrigin                              the current origin 

    [StyleSheet parameters:]

      textForegroundColor                defaults to Black

      textBackgroundColor                defaults to White

      textFont                           defaults to defaultFont

      textTabPositions                   defaults to #(1 9 17 25 ...)

    [author:]

        Claus Gittinger

    [see also:]

        TextView EditTextView

"

!

examples 

"

    ListViews alone are rarely used - its mostly an abstract superclass

    for TextView, EditTextView and SelectionInListView.

    anyway, here are a few examples:

     basic simple setup:

									[exBegin]

	|top l|

	top := StandardSystemView new.

	top extent:100@200.

	l := ListView origin:0.0 @ 0.0 corner:1.0 @ 1.0 in:top.

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

	top open

									[exEnd]

      specifying textMargins (these have NOTHING to do with the viewInset):

									[exBegin]

	|top l|

	top := StandardSystemView new.

	top extent:100@200.

	l := ListView origin:0.0 @ 0.0 corner:1.0 @ 1.0 in:top.

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

	l topMargin:10.

	l leftMargin:20.

	top open

									[exEnd]

      globally set the fg/bg colors:

									[exBegin]

	|top l|

	top := StandardSystemView new.

	top extent:100@200.

	l := ListView origin:0.0 @ 0.0 corner:1.0 @ 1.0 in:top.

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

	l foregroundColor:(Color white).

	l backgroundColor:(Color blue).

	top open

									[exEnd]

      non-string (text) entries:

									[exBegin]

	|top list l|

	top := StandardSystemView new.

	top extent:100@200.

	l := ListView origin:0.0 @ 0.0 corner:1.0 @ 1.0 in:top.

	list := #('all' 'of' 'your' 'preferred' 'colors') 

		with:#(red green blue 'orange' cyan)

		collect:[:s :clr | 

			    Text string:s 

				 emphasis:(Array with:#bold

						 with:(#color->(Color name:clr))) ].

	l list:list.

	top open

									[exEnd]

      generic non-string entries:

      (notice: ColoredListEntry is obsoleted by Text)

									[exBegin]

	|top list l|

	top := StandardSystemView new.

	top extent:100@200.

	l := ListView origin:0.0 @ 0.0 corner:1.0 @ 1.0 in:top.

	list := #('all' 'of' 'your' 'preferred' 'colors') 

		with:#(red green blue 'orange' cyan)

		collect:[:s :clr | ColoredListEntry string:s color:(Color name:clr) ].

	l list:list.

	top open

									[exEnd]

      using a model (default listMessage is aspectMessage):

									[exBegin]

	|top model l theModelsText|

	model := Plug new.

	model respondTo:#modelsAspect

		   with:[ theModelsText ].

	top := StandardSystemView new.

	top extent:100@200.

	l := ListView origin:0.0 @ 0.0 corner:1.0 @ 1.0 in:top.

	l model:model.

	l aspect:#modelsAspect.

	top open.

	Delay waitForSeconds:3.

	theModelsText := #('foo' 'bar' 'baz').

	model changed:#modelsAspect.

									[exEnd]

      using a model with different aspects

      for two listViews:

									[exBegin]

	|top model l1 l2 plainText|

	plainText := #('').

	model := Plug new.

	model respondTo:#modelsUppercaseText

		   with:[ plainText asStringCollection 

			      collect:[:l | l asUppercase]].

	model respondTo:#modelsLowercaseText

		   with:[ plainText asStringCollection 

			      collect:[:l | l asLowercase]].

	top := StandardSystemView extent:200@200.

	l1 := ListView origin:0.0 @ 0.0 corner:1.0 @ 0.5 in:top.

	l1 model:model.

	l1 aspect:#modelsAspect.

	l1 listMessage:#modelsUppercaseText.

	l2 := ListView origin:0.0 @ 0.5 corner:1.0 @ 1.0 in:top.

	l2 model:model.

	l2 aspect:#modelsAspect.

	l2 listMessage:#modelsLowercaseText.

	top open.

	Delay waitForSeconds:3.

	plainText := #('foo' 'bar' 'baz').

	model changed:#modelsAspect.

									[exEnd]

"

! !

!ListView class methodsFor:'defaults'!

defaultTabPositions

    ^ self tab8Positions

!

tab4Positions

    ^ #(1 5 9 13 17 21 25 29 33 37 41 45 49 53 57 61 65 69 73 77 81 

	85 89 93 97 101 105 109 113 114 121 125 129 133 137 141 145)

!

tab8Positions

    ^ #(1 9 17 25 33 41 49 57 65 73 81 89 97 105 113 121 129 137 145)

!

updateStyleCache

    "extract values from the styleSheet and cache them in class variables"

    <resource: #style (#textForegroundColor #textBackgroundColor

		       #textTabPositions

		       #textFont)>

    DefaultForegroundColor := StyleSheet colorAt:'textForegroundColor' default:Black.

    DefaultBackgroundColor := StyleSheet colorAt:'textBackgroundColor' default:White.

    DefaultFont := StyleSheet fontAt:'textFont'.

    DefaultTabPositions := StyleSheet at:'textTabPositions'.

    DefaultTabPositions isNil ifTrue:[DefaultTabPositions := self defaultTabPositions].

    "Modified: 1.3.1996 / 13:45:34 / cg"

! !

!ListView methodsFor:'accessing'!

backgroundColor

    "return the background color"

    ^ bgColor

!

backgroundColor:aColor

    "set the background color of the contents"

    bgColor ~~ aColor ifTrue:[

        bgColor := aColor.

        self viewBackground:bgColor.

        shown ifTrue:[

            self invalidate "/ clear; redraw

        ]

    ]

    "Modified: 3.5.1997 / 10:27:40 / cg"

!

font:aFont

    "set the font for all shown text.

     Redraws everything.

     CAVEAT: with the addition of Text objects,

             this method is going to be obsoleted by a textStyle

             method, which allows specific control over

             normalFont/boldFont/italicFont parameters."

    aFont isNil ifTrue:[

        ^ self error:'nil font'

    ].

    font ~~ aFont ifTrue:[

        super font:(aFont on:device).

        preferredExtent := nil.

        widthOfWidestLine := nil. "/ i.e. unknown

        self getFontParameters.

        realized ifTrue:[

            (font graphicsDevice == device) ifTrue:[

                self getFontParameters.

                self computeNumberOfLinesShown.

                shown ifTrue:[

                    self redrawFromVisibleLine:1 to:nLinesShown

                ]

            ].

            self contentsChanged

        ]

    ]

    "Modified: 5.7.1996 / 17:55:34 / cg"

!

fontHeight:pixels

    "set the lines height - thats the number of pixels,

     by which lines are vertically separated."

    fontHeight ~~ pixels ifTrue:[

        fontHeight := pixels.

    ]

    "Created: 17.4.1997 / 01:41:33 / cg"

!

foregroundColor

    "return the foreground color"

    ^ fgColor

!

foregroundColor:aColor

    "set the foreground color"

    fgColor ~~ aColor ifTrue:[

	fgColor := aColor.

	shown ifTrue:[

	    self invalidate 

	]

    ]

    "Modified: 29.5.1996 / 16:19:02 / cg"

!

foregroundColor:color1 backgroundColor:color2

    "set both foreground and background colors"

    ((fgColor ~~ color1) or:[bgColor ~~ color2]) ifTrue:[

	fgColor := color1.

	bgColor := color2.

	shown ifTrue:[

	    self invalidate 

	]

    ]

    "Modified: 29.5.1996 / 16:19:05 / cg"

!

innerHeight

    "return the number of pixels visible of the contents

     - redefined since ListView adds another margin to start the text

     somewhat to indented from the 3D border."

    ^ height - (2 * margin) - topMargin

!

innerHorizontalMargin

    "return the margin between the left border and the 1st col"

    ^ leftMargin

    "Created: 16.1.1996 / 19:28:23 / cg"

!

innerVerticalMargin

    "return the margin between the top border and the 1st line"

    ^ topMargin

    "Created: 16.1.1996 / 19:28:00 / cg"

!

leftMargin

    "return the margin to left of 1st col"

    ^ leftMargin

!

leftMargin:aNumber

    "set the margin between the left border and the 1st col"

    leftMargin := aNumber.

    textStartLeft := aNumber + margin.

    innerWidth := width - aNumber - margin

    "Modified: 28.2.1996 / 19:32:55 / cg"

!

level:aNumber

     (which avoids many computations later)"

    |newMargin|

    newMargin := aNumber abs.

    textStartLeft := leftMargin + newMargin.

    textStartTop := topMargin + newMargin.

    innerWidth := width - textStartLeft - newMargin.