"

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

View subclass:#ListView

	instanceVariableNames:'list firstLineShown nFullLinesShown nLinesShown fgColor bgColor

		partialLines leftMargin topMargin textStartLeft textStartTop

		innerWidth tabPositions lineSpacing fontHeight fontAscent

		fontIsFixedWidth fontWidth autoScroll autoScrollBlock

		autoScrollDeltaT wordCheck includesNonStrings widthOfWidestLine

		listMsg viewOrigin listChannel backgroundAlreadyClearedColor

		scrollWhenUpdating scrollLocked lineEndCRLF highlightAreas

		compareModelOnUpdate expandTabsWhenUpdating

		checkLineEndConventionWhenUpdating

		checkedLinesForWidthOfContentsComputation'

	classVariableNames:'DefaultForegroundColor DefaultBackgroundColor DefaultTabPositions

		UserDefaultTabPositions DefaultLeftMargin DefaultTopMargin'

	poolDictionaries:''

	category:'Views-Text'

!

Object subclass:#HighlightArea

	instanceVariableNames:'startLine startCol endLine endCol fgColor bgColor'

	classVariableNames:''

	poolDictionaries:''

	privateIn:ListView

!

Object subclass:#SearchSpec

	instanceVariableNames:'pattern match ignoreCase variable fullWord forward'

	classVariableNames:''

	poolDictionaries:''

	privateIn:ListView

!

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

    text or display objects which behave line-like (i.e. all have constant height).

    Selections, editing, cursors etc. must be implemented in subclasses.

    (see SelectionInListView, TextView etc.)

    This code currently handles only fixed-height fonts correctly -

    it should be rewritten in some places to not compute the position/height from

    the view's font height, but by accumulating line heights...

    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/text 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 and labelAndIcon-like entities).

    The internal version of the text has tabulators expanded to blanks. ListView is not prepared

    to deal with them. 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 user's tab setting, which is used ONLY for positioning,

    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 system and definitely requires a major 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

    using the viewOrigin (transparent means, that the code does not need to know - it simply draws

    as if all of the text was visible).

    Here in ListView, the transformation is not used, instead it is done again, and different, 

    by keeping the firstLineShown (i.e. vertical offset) and leftOffset (horizontal offset).

    Even worse: the firstLineShown is a line-index, the most annoying consequence of this is that 

    scrolling is done by lines here, whereas it is done in pixels in the View class. 

    Thus, be very careful, when changing things (better: don't touch it ;-). 

    Also, the viewOrigin variable is only valid for the x coordinate. The viewOrigin's y is always 0 !!

    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 may be totally rewritten ... so don't depend on the internals; especially the scrolling

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

    Also Notice:

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

    because ListView was written at a time when most of the graphics was done via remote connections

    (X-window network protocol), it is highly tuned to avoid redraw operations. Thus, it can be used

    happily over a slow WLAN (say: 64kBit connection).

    In that, it performed *much* better than other widgets, especialy Java and Qt, some of which are

    hardly usable via the network.

    It may be questionable whether this is still a requirement these days, where network connections

    are usually pretty fast. However, the author insists on this to remain as it is!!

    Future underlying graphics may well become network dependent in the future, for example, when

    the display connection is implemented as an RPC into a web browser...

    Also Notice:

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

    ListView shall be configurable to avoid accesses to its underlying list if required.

    Currently, it can be customized to disable lineWidth computation, tab expansion and scanning for

    non-string entries. All of which is required when huge texts which are not in memory are to be displayed

    (for example: a virtual array of 10million text lines). Please be careful to not reintroduce such

    code when adding features (as happened in the past).

    [Instance variables:]

      list                <aCollection>           the text strings, a collection of lines.

                                                  Nils may be used for empty lines.

      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

      lastSearchPattern   <String>                last pattern for searching

                                                  (kept to provide a default for next search)

      lastSearchIgnoredCase   <Boolean>           last search ignored case

                                                  (kept to provide a default for next search)

      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

      backgroundAlreadyClearedColor               internal; speedup by avoiding

                                                  multiple fills when drawing

                                                  internal lines

      scrollWhenUpdating

                                <Symbol>        defines how the view is scrolled if the

                                                model changes its value by some outside activity

                                                (i.e. not by user input).

                                                Can be one of:

                                                    #keep / nil     -> stay unchanged

                                                    #endOfText      -> scroll to the end

                                                    #beginOfText    -> scroll to the top

                                                The default is #beginOfText (i.e. scroll to top).

    [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]

      using a big list (100000 lines),

      wrapping in a ScrollableView:

                                                                        [exBegin]

        |bigList top lv|

        bigList := (1 to:100000) collect:[:lineNr | 'List line Nr. ' , lineNr printString].

        bigList at:10 put:('Some Text ' asText , 'with Bold part' allBold).

        bigList at:20 put:('Some Text ' asText , 'with Italic part' allItalic).

        top := StandardSystemView extent:200@200.

        lv := HVScrollableView for:ListView in:top.

        lv origin:0.0 @ 0.0 corner:1.0 @ 1.0.

        lv list:bigList expandTabs:false scanForNonStrings:false includesNonStrings:false.

        top open.

                                                                        [exEnd]

      using a huge virtual list (1 mio simulated lines),

      wrapping in a ScrollableView:

                                                                        [exBegin]

        |virtualList top lv|

        virtualList := Plug new.

        virtualList inheritFrom:SequenceableCollection.

        virtualList respondTo:#size with:[ 1000000 ].

        virtualList respondTo:#at:  with:[:lineNr | 'List line Nr. ' , lineNr printString ].

        top := StandardSystemView extent:200@200.

        lv := ScrollableView for:ListView in:top.

        lv origin:0.0 @ 0.0 corner:1.0 @ 1.0.

        lv list:virtualList expandTabs:false scanForNonStrings:false includesNonStrings:false.

        top open.

                                                                        [exEnd]

      using a huge virtual array (1 mio simulated lines),

      wrapping in a ScrollableView.

      To simulate an expensive computation, a delay is planted into the line generator;

      Startup and display of page full of lines should not take longer than the number of lines shown:

                                                                        [exBegin]

        |virtualList top lv|

        virtualList := VirtualArray new.

        virtualList 

            setSize:1000000; 

            generator:[:index | Transcript showCR:index.

                                Delay waitForSeconds:0.5.

                                '%1 -> %2' bindWith:index with:index squared].

        top := StandardSystemView extent:200@200.

        lv := ScrollableView for:ListView in:top.

        lv origin:0.0 @ 0.0 corner:1.0 @ 1.0.

        lv expandTabsWhenUpdating:false.

        lv checkLineEndConventionWhenUpdating:false.

        lv checkedLinesForWidthOfContentsComputation:-1.

        lv list:virtualList.

        top open.

                                                                        [exEnd]

"

! !

!ListView class methodsFor:'defaults'!

defaultTabPositions

    "return an array containing the styleSheets default tab positions"

    ^ DefaultTabPositions ? self tab4Positions

!

defaultTabPositions:aVector

    "set the array containing the styleSheets tab positions"

    DefaultTabPositions := aVector

    "

     ListView defaultTabPositions:(ListView tab4Positions)

    "

!

tab4Positions

    "return an array containing tab positions for 4-col tabs"

    ^ #(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

    "return an array containing tab positions for 8-col tabs"

    ^ #(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 (#'text.foregroundColor' #'text.backgroundColor'

                       #'text.tabPositions'

                       #'text.font')>

    DefaultForegroundColor := StyleSheet colorAt:'text.foregroundColor' default:Color black.

    DefaultBackgroundColor := StyleSheet colorAt:'text.backgroundColor' default:Color white.

    DefaultFont := StyleSheet fontAt:'text.font'.

    DefaultTabPositions := StyleSheet at:'text.tabPositions'.

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

    DefaultLeftMargin := 0.5.

    DefaultTopMargin := 0.5.

    "Modified: 20.10.1997 / 15:05:30 / cg"

!

userDefaultTabPositions

    "return an array containing the users default tab positions"

    ^ UserDefaultTabPositions

!

userDefaultTabPositions:aVector

    "set the array containing the users tab positions"

    UserDefaultTabPositions := aVector

    "

     self userDefaultTabPositions:(self tab4Positions)

    "

! !

!ListView methodsFor:'accessing'!

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

! !

!ListView methodsFor:'accessing-behavior'!

checkLineEndConventionWhenUpdating

    "return the line-end convention check when updating behavior.

     If true (the default), the first line of the list given is checked for having a

     cr-lf line end (which is a DOS convention), and the lineEndCRLF flag is set dynamically.

     If false, the lineEndCRLF remains as specified by the user.

     You may want to disable this flag if it is very expensive to generate a line

     (although, only the very first line is checked, anyway)"

    ^ checkLineEndConventionWhenUpdating

!