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.216 date: 2024/03/01 11:45:21
user: stefan
file: ListModelView.st directory: libwidg2
module: stx stc-classLibrary: libwidg2

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


copyright
COPYRIGHT (c) 1999 by eXept Software AG
             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.


bug1
shown contents is not updated, until scrolled slightly
     or resized


bug2
shown contents is not updated, until scrolled slightly
     or resized

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
(comment from inherited method)
warning: this is experimental and not yet implemented

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

o  renderer: aTableRenderer
(comment from inherited method)
warning: this is experimental and not yet implemented

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

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
return how to scroll, when I get a new text
(via the model or the #contents/#list)
Possible return values 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)

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 were removed from indices aStart to aStop

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

Usage example(s): 

super keyPress:aKey x:x y:y

o  keyboardZoom: largerBoolean
ALT+/- (was: CTRL+/-) zoom action

o  mouseWheelZoom: amount
(comment from inherited method)
CTRL-wheel action.
ignored here - redefined in views which can zoom

o  sizeChanged: how from: oldExtentOrNil
my view has changed the size (not the contents)

event simulation
o  syncronizeEvents

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

o  syncronizeEvents: aBoolean

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

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
this returns the coordinate in absolute coordinates.
(i.e. subtract the scrollOffset in viewOrigin to get the position within the window,
and subtract the scrollOffset and add the view's screenorigin, to get the position on the screen)

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 within 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; by default, an instance of 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

queries-contents
o  heightOfContents
return the height of the contents in pixels

o  widthOfContents
return the width of the contents in pixels

recomputation
o  computePreferredExtent
returns the preferred extent

o  recomputeHeightOfContents
recompute all the (cached) y positions

scroller interface
o  getWidthOfContents

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

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  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  scrollToEndOfText

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  openAndWaitUntilVisible.
    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.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Thu, 21 Nov 2024 17:28:54 GMT