eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'ListModelView':

Home

Documentation
www.exept.de
Everywhere
for:
[back]

Class: ListModelView


Inheritance:

   Object
   |
   +--GraphicsMedium
      |
      +--DisplaySurface
         |
         +--SimpleView
            |
            +--View
               |
               +--ListModelView
                  |
                  +--SelectionInListModelView

Package:
stx:libwidg2
Category:
Views-Lists
Version:
rev: 1.182 date: 2019/07/20 05:52:58
user: cg
file: ListModelView.st directory: libwidg2
module: stx stc-classLibrary: libwidg2
Author:
Claus Atzkern

Description:


This widget is a new improved revision of the good-old ListView.
In contrast to ListView, this one reacts on changes of the
underlying list and performs optimized redraws.
It requires a List (or alike) as list.

This class can only passively display collections of elements.
The class doesn't keep its own list, it works directly on
the list ( List or HierarchicalList ).

ATTENTION (warning by cg):
    in contrast to its inappropriate name, this class COMPLETELY ignores the model
    instance variable - all is through the list/listHolder.

Each list item is obligated to provide 3 services:
    - heightOn:aGC
    - widthOn:aGC
    - displayOn:aGC x:x y:y

[Instance variables:]
    list                   <List-Model>     List or HierarchicalList ...
    listHolder             <Model>          Model, which keeps a List
    textStartLeft          <Number>         left inset of text
    viewOrigin             <Point>          the current origin
    enabled                <Boolean>        widget is enabled/disabeled
    fgColor                <Color>          color to draw characters
    bgColor                <Color>          the background
    lineSpacing            <Number>         pixels between lines
    widthOfContents        <Number>         cached width of widest line
    computeWidthInRange    <Point>          used for recompute width of contents
    startOfLinesY          <Collection>     keeps all the absolute Y-start positions
                                            for each line in the list. The first
                                            entry into the list is the top Y inset.
    supportsDisplayInRange <Boolean>        set to true if the list elements
                                            supports the service:
                                                #displayOn:x:y:h:

    hasConstantHeight      <Boolean>        true, than each line has the same height

    constantHeight         <SmallInteger>   hasConstantHeight is turned on, this
                                            is the used line height



    SelectionInListModelView
    HierarchicalListView
    List
    HierarchicalList


Related information:



Class protocol:

Signal constants
o  stopRedrawSignal

defaults
o  defaultRenderer

o  updateStyleCache
extract values from the styleSheet and cache them in class variables

usage example(s):

     self updateStyleCache

initialization
o  initialize
setup the signals


Instance protocol:

accessing
o  list
get the list of items

o  list: aList
set the list of items

o  listRenderer
returns the used listrenderer

o  listRenderer: aRendererOrRendererClass
change the used listRenderer

o  renderer

o  renderer: aTableRenderer

o  setupTableRenderer
creates a renderer with columns based on a DataSetColumnSpec
answer the new renderer

accessing-behavior
o  autoScroll
returns true if auto scrolling is enabled

o  autoScroll: aBool
returns true if auto scrolling is enabled

o  enabled
returns the enabled state

o  enabled: aBoolean
set the enabled state

o  hasConstantHeight
user configured; true if each line has the same lineHeight.
Optimizes scroll and redraw operations

o  hasConstantHeight: aBool
user configured; true if each line has the same lineHeight.
Optimizes scrolling and redraw.

o  scrollWhenUpdating: aSymbolOrNil
define how to scroll, when I get a new text
(via the model or the #contents/#list)
Allowed arguments are:
#keep / nil -> no change
#endOfText -> scroll to the end
#beginOfText -> scroll to the top
The default is #beginOfText.
This may be useful for fields which get new values assigned from
the program (i.e. not from the user)

accessing-items
o  at: anIndex
return the list element at an index

o  at: anIndex ifAbsent: exceptionBlock
return the list element at an index if valid.
If the index is invalid, return the result of evaluating
the exceptionblock.

o  findLast: aOneArgBlock
find the last list entry, for which evaluation of the argument, aOneArgBlock
returns true; return its index or 0 if none detected.

o  identityIndexOf: anElement
returns the index of an element or nil

o  last
returns the last list entry

o  listAt: anIndex
for protocol compatibility with SelectionInListView

accessing-look
o  backgroundColor
get the background color

o  font: aFont
set a new font

o  foregroundColor
get the foreground color

o  foregroundColor: aColor
set the foreground color

o  lineSpacing
get the lineSpacing - that's an additional number of pixels,
by which lines are vertically separated.

o  lineSpacing: aNumber
set the lineSpacing - that's an additional number of pixels,
by which lines are vertically separated.

o  viewBackground: aColor
set the background color

accessing-mvc
o  listHolder
returns the listHolder or nil

o  listHolder: aListHolder
set a new listHolder

change & update
o  lineChangedAt: aLnNr with: arg
line changed at position; check whether line height changed

o  listChangedInsert: start nItems: nLines
list changed; items are added

o  listChangedRemove: aStart toIndex: aStop
list changed; items are removed

o  update: what with: aPara from: chgObj
catch and handle any notification raised from the list model
or list holder

o  updateFromList: what with: aParameter
called if the list changed

drawing
o  drawElementsFrom: start to: stop x: x y: y w: w
draw lines from start to stop.
clipping and clearing the background is already done

o  drawFrom: start to: stop x: xLft y: yTop w: aWidth
draw lines from start to stop. Test whether a new clip
must be setup.

o  drawSelectionFrameFrom: start to: stop x: x y: y w: w
What to do here?

o  invalidateLineAt: aLineNr
add a damage to redraw a line specified by its line number to the
input event queue.

o  invalidateLineAt: aLineNr fromX: x
add a damage to redraw a line specified by its line number to the
input event queue.

o  redraw
redraw complete view

o  redrawX: x y: y width: w height: h
redraw part of myself immediately, given logical coordinates

enumerating
o  visibleLinesAndItemsDo: aTwoArgBlock
enumerate over each visible item

event handling
o  keyPress: aKey x: x y: y
a key was pressed - handle page-keys here

o  keyboardZoom: largerBoolean
CTRL+/- zoom action

o  sizeChanged: how
(comment from inherited method)
tell subviews that I changed size.
How is either #smaller, #larger or nil, and is used to control the order,
in which subviews are notified (possibly reducing redraw activity)

event simulation
o  syncronizeEvents

o  syncronizeEvents: aBoolean

fetch resources
o  colorOnDevice: aColor
fetch a device colors

o  imageOnMyDevice: anImage
associate image to device and returns the new image.

focus handling
o  wantsFocusWithButtonPress
catch the keyboard focus on button click

o  wantsFocusWithPointerEnter
views which like to take the keyboard focus
when the pointer enters can do so by redefining this
to return true

initialization & release
o  create
fetch device dependent resources

o  initStyle
setup viewStyle specifics

o  initialize
setup default attributes

o  mapped
recompute list

o  recreate
sent after a snapin or a migration, reinit for new device

o  reinitialize
reinit after snapIn (font geometry might be different)

o  release
remove dependencies

private
o  hasDamage
return true, if any damage events (i.e. expose or resize) are pending

o  startOfLinesY
returns a collection of absolute Y-positions per line.
The first entry is the top Y inset.
The size of the list is one more than the lists size,
providing the Y-position of the line below the contents as its last entry.

o  xAbsoluteOfItem: anItem
returns the absolute x of the labeled text

o  xVisibleOfItem: anItem
returns the visible x of the labeled text

o  yAbsoluteOfLine: aLineNr
given a lineNr, return its y-coordinate

o  yAbsoluteToLineNr: yAbsolute
returns the line number for a given physical y coordinate
or nil if beyond of list.

o  yAbsoluteToRowNr: yVisible
for protocol compatibility with DSVColumnView

o  yVisibleOfLine: aLineNr
given a lineNr, return the y-coordinate in the view

o  yVisibleToLineNr: yVisible
returns the line number for a given physical y coordinate
or nil if beyond of list.

o  yVisibleToRowNr: yVisible
for protocol compatibility with DSVColumnView

protocol
o  fetchResources
fetch device colors and ..., to avoid reallocation at redraw time;
*** called after a create or snapin to fetch all device resources

o  heightForLines: numberOfLines

o  lineHeightFor: anItem
returns the computed line height for an item

o  listSizeChanged: anIndex nLines: noLines
list size changed; information is stored to recompute the
width if required( preferredExtent, horizontal scroller ... ).
see: widthOfContents
*** if nLines is negative, lines are removed otherwise added.

o  lostSynchronisation
called when the changes derived from the model are faster than the handling

o  newDefaultList
creates and returns a new default list class, on default a List

o  widthOfWidestLineBetween: firstLine and: lastLine
return the width in pixels of the widest line in a range
- used to optimize scrolling, by limiting the scrolled area;
not for scrollbar or other width related stuff which should be exact.

queries
o  isLineFullyVisible: aLineNr
returns true if the line is fully visible

o  isLineVisible: aLineNr
returns true if the line is visible

o  isLineVisible: aLineNr in: anExtentPoint
returns true if the line is visible inside the top margin and the y given by the point

o  lineIsFullyVisible: aLineNr
returns true if the line is fully visible

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  numberOfLines
return the number of lines the text has
(protocol compat. with SelectionInListView)

o  size
returns the number of list entries

recomputation
o  computePreferredExtent
returns the preferred extent

o  recomputeHeightOfContents
recompute all the y positions

scroller interface
o  getWidthOfContents

o  heightOfAnyNonNilItem
returns the height of a line at an index (including lineSpacing...)

o  heightOfContents
return the height of the contents in pixels

o  heightOfLineAt: aLineNr
returns the height of a line at an index (including lineSpacing...)

o  innerHeight
returns the inner height of the contents shown

o  innerWidth
returns the inner width of the contents shown

o  maxViewOriginY
returns the maximum possible y of the view origin

o  realHeightOfLineAt: aLineNr
returns the real (uncached) height of a line at an index

o  setWidthOfContents: aWidth

o  verticalScrollStep
return the amount to scroll when stepping up/down (also used for mouseWheel).

o  viewOrigin
return the viewOrigin; that's the coordinate of the contents
which is shown topLeft in the view.

o  widthOfContents
return the width of the contents in pixels

o  xOriginOfContents
return the horizontal origin of the contents in pixels

o  yOriginOfContents
return the vertical origin of the contents in pixels

scrolling
o  basicScrollTo: anOrigin redraw: doRedraw
change origin to have newOrigin be visible at the top-left.

o  halfPageDown
scroll down half a page

o  halfPageUp
scroll up half a page

o  makeLineVisible: aLnNr
make the line visible

o  scrollTo: anOrigin redraw: doRedraw
change origin to have newOrigin be visible at the top-left.

o  scrollToLine: aLineNumber
make line visible

scrolling auto
o  startAutoScroll: aSelectorOrBlock distance: aDistance
setup for auto-scroll (when button-press-moving below/above view);
- timeDelta for scroll is computed from distance

o  stopAutoScroll
stop any autoScroll

selection
o  hasSelection
by default, false is returned here (redefined in SelectionInListModelView)


Private classes:

    Renderer
    TableRenderer

Examples:


    |top list view up index|

    list := List new.

    top  := StandardSystemView new; extent:300@300.
    view := ScrollableView for:ListModelView miniScroller:true
                        origin:0.0@0.0 corner:1.0@1.0 in:top.

    view list:list.
    top  openAndWait.
    up := true.

    [top shown] whileTrue:[
        Delay waitForSeconds:0.2.

        up ifTrue:[
            index := 1 + (list size).
            list add:('element: ', index printString).
            up := index < 20
        ] ifFalse:[
            list removeIndex:1.
            up := list isEmpty.
        ]
    ].


ST/X 7.2.0.0; WebServer 1.670 at bd0aa1f87cdd.unknown:8081; Tue, 19 Mar 2024 04:53:28 GMT