Smalltalk/X Webserver

Documentation of class 'HierarchicalListView':

Class: HierarchicalListView

Inheritance
Description
Class protocol
- resources
Instance protocol
Examples

Inheritance:

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

Package:: stx:libwidg2

Category:: Views-Trees

Version:: rev: 1.168 date: 2023/10/26 16:47:10; user: stefan; file: HierarchicalListView.st directory: libwidg2; module: stx stc-classLibrary: libwidg2

Description:

This class implements a hierarchical list view based on a
hierachical list.
It provides functionality similar to SelectionInTreeView, but optimizes
redraws, and operates directly on the model 
(in contrast to SelectionInTreeView, which generates a list internally).

[Instance variables:]
    textStartLeft       <Integer>              inset between icon and text
    imageInset          <Integer>              inset between left side and icon
    imageWidth          <Integer>              width of widest icon
    minLineHeight       <Integer>              minimum required line height
                                               including open/close indication ...
    indicatorWidth      <Integer>              max. width  of indicator
    indicatorHeight     <Integer>              max. height of indicator

    lineMask            <Form>                 line mask
    lineColor           <Color>                line color
    showRoot            <Boolean>              root element is shown or hidden
                                               derives from the hierachical list.
    showLines           <Boolean>              show or hide lines
    showIndicators      <Boolean>              show or hide indicators
    useDefaultIcons     <Boolean>              use the default icons if no icon
                                               for an item is specified
    icons               <IdentityDictionary>   list of registered icons;
                                               identifier := <key> value := <icon>
    showLeftIndicators  <Boolean>              show or hide indicator for most left items
    indicatorAction     <Block>                action evaluated if indicator is pressed (0/1/2 arguments)
    openIndicator       <Icon, Image or Form>  expanded indicator
    closeIndicator      <Icon, Image or Form>  collapsed indicator

    alignTextRight      <Boolean>              enable disable of align the text right
                                               icon            text
                                                    icon       text of child
                                               should be set after creation of the widget!
    alignTextRightX     <Integer>              left x position of aligned right text
    maxWidthOfText      <Integer>              keeps the maximum width of a text label

    levelOfLastItem     <Integer>              keeps the level of the last item;
                                               in case of a delete last items from list
                                               we know were to redraw lines from

    autoScrollHorizontal <Boolean>             true, than automatically scroll horizontal upto
                                               the text label of the current selected line.

    expandOnSelect      <Boolean>              true, than the item selected by a buttonPress
                                               event will be immediately expanded.

copyrightCOPYRIGHT (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.

example2|top sel list item|

list := HierarchicalList new.
item := HierarchicalItem::Example label:'Root Item'.

item expand.
list showRoot:false.
list root:item.

top := StandardSystemView extent:300@300.
sel := ScrollableView for:HierarchicalListView miniScrollerH:true
                   origin:0.0@0.0 corner:1.0@1.0 in:top.

sel useDefaultIcons:false.
sel list:list.
sel multipleSelectOk:true.
sel showLines:false.

sel doubleClickAction:[:i| (list at:i) toggleExpand ].
sel   indicatorAction:[:i| (list at:i) toggleExpand ].

top open.

Class protocol:

resources

closeIndicator
collapsedIcon
emptyIcon
expandedIcon
openIndicator

Instance protocol:

accessing

font: aFont: set a new font; if the font changed, all my items
have to clear their cached width and height.
list: aList
newDefaultList: creates and returns a new default list; by default, an instance of HierarchicalList
root: return the anchor of the list or nil

accessing-behavior

autoScrollHorizontal: returns true if automatic horizontal scrolling
(upto the text label of the selected line)
is allowed (the default is as specified in the styleSheet).
autoScrollHorizontal: aBoolean: true, than automatically scroll horizontal upto the text label
of the current selected line.
expandOnSelect: true, than the item selected by a buttonPress event will
be immediately expanded.
expandOnSelect: aBoolean: true, than the item selected by a buttonPress event will
be immediately expanded.

accessing-color & font

lineColor: get the color of the horizontal and vertical lines
lineColor: aColor: set the color of the horizontal and vertical lines

accessing-look

alignTextRight: align the text right
alignTextRight: aBool: align the text right
alignTextRightX: returns the minimum used text inset, if text is aligned right.
alignTextRightX: aNumber: set the minimum used text inset, if text is aligned right.
closeIndicator: anIconOrNil
iconAlignment: aSymbol: alignment of the icons
#left align icons left
#right align icons right
#center align icons center between left and right
iconAt: aKey ifAbsentPut: aBlock: return the icon stored under a key; if not present,the
result of the block if not nil is stored under the key
and returned.
openIndicator
openIndicator: anIconOrNil
registerKeysAndIcons: aDictionary: register icons by key and value derived from a directory
selectedVisualBlock: To be polymorph with SelectionInListView
selectedVisualBlock: aBlockOrNil: To be polymorph with SelectionInListView
showIndicators: returns true if indicators are shown
showIndicators: aBoolean: true if indicators are shown
showLeftIndicators: show or hide the indicators for the most left items
showLeftIndicators: aBoolean: show or hide the indicators for the most left items
showLines: returns true if lines are shown
showLines: aBoolean: show or hide lines
showRoot: return true if the root is shown
showRoot: aBoolean: controls if the root is to be shown
useDefaultIcons: use the default icons if no icon for an item is specified;
** default: true
useDefaultIcons: aBoolean: use the default icons if no icon for an item is specified;
** default: true
visualBlock: To be polymorph with SelectionInListView
visualBlock: aBlockOrNil: To be polymorph with SelectionInListView

actions

indicatorAction: the action evaluated if an indicator is pressed; otherwise
if indicators are shown a default action is performed (toggle expand item).

The arguments to the block are:
- no argument
- 1 argument index
- 2 argument index, self
indicatorAction: anAction: the action evaluated if an indicator is pressed; otherwise
if indicators are shown a default action is performed (toggle expand item).

The arguments to the block are:
- no argument
- 1 argument index
- 2 argument index, self

change & update

indicatorIconChanged: must recompute all
indicatorPressedAt: aLnNr: handle indicator pressed action;
if the item changed expanded, we try to show all
new visible children
lineChangedAt: aLnNr with: arg: line changed at position; check whether line height changed
listChangedInsert: firstAddedIndex nItems: nLines: may have to draw vertical lines above the added items
listChangedRemove: aStart toIndex: aStop: test whether last items are deleted;
than we have to redraw lines because of different levels
updateFromList: what with: aPara: get the status of <showRoot> from the list

drawing basics

drawElementsFrom: start to: stop x: xLeft y: yT w: w: draw the items between start to stop without clearing the background
drawLinesFrom: start to: stop x: xL y: yT toX: xR: draw the lines between start to stop without clearing the background
drawVericalLineForElement: item minX: xL maxX: xR: draw the vertical line my children are connected to

** This is an obsolete interface - do not use it (it may vanish in future versions) **
drawVerticalLineForElement: item minX: xL maxX: xR: draw the vertical line my children are connected to
validateDrawableIconFor: anItem: returns the icon to be drawn for an item or nil
test the extent of the icon; on error an exception is raised

event handling

buttonPress: button x: x y: y: handle a button press event
buttonPressOrReleaseAtLine: aLnNr x: x y: y: handle a button press or release at a line
keyPress: aKey x: x y: y: a key was pressed - handle page-keys here

fetch resources

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

initialization & release

initStyle: setup viewStyle specifics
initialize: (comment from inherited method)
setup default attributes/behavior

private

iconFor: anItem: returns an icon or image for the item or nil if the item
provides no image and useDefaultIcons is switched off,
or if anItem returns #none from the icon query.
lineHeightFor: anItem: returns the computed line height for an item
smallestLevelBetween: start and: stop: returns the smallest level of all items in a range
widthOfWidestLineBetween: firstLine and: lastLine: returns the width of the longest line in pixels in a range
- used to optimize scrolling, by limiting the scrolled area;
not for scrollbar or other width related stuff which should be exact.
xVisibleOfIconAtLevel: aLevel: returns the visible origin x of the icon at a level.
xVisibleOfIndicatorAtLevel: aLevel: returns the visible origin x of the vertical line at a level.
xVisibleOfItem: anItem: returns the visible origin x of the item's label.
xVisibleOfTextAtLevel: aLevel: returns the visible origin x of the text label at a level.
xVisibleOfVerticalLineAt: aLevel: returns the visible origin x of the vertical line assigned to a level.
yVisibleOfIndicatorForItem: anItem: return the y of the vertical center of anItem
yVisibleOfIndicatorForItemBottom: anItem: return the y of the vertical bottom of anItem
yVisibleOfIndicatorForItemTop: anItem: return the y of the vertical top of anItem

queries

hasToSkipButtonMultiPress: button x: x y: y: do not process doubleClick actions on indicator

scrolling

computeViewOriginXat: aLnrNr: returns the viewOrigin x to make the item at a line visisble
makeItemVisible: anItem withMinimumLines: aNumber: handle indicator pressed action;
if the item changed expanded, we try to show all
new visible children
makeLineVisible: aLineNumber: make the line horizontally and vertically visible

Examples:

show a hierarchical list

|top sel list item|

list := HierarchicalList new.
item := HierarchicalItem::Example labeled:'Root Item'.

item expand.
list showRoot:false.
list root:item.

top := StandardSystemView new; extent:300@300.
sel := ScrollableView for:HierarchicalListView miniScrollerH:true
                   origin:0.0@0.0 corner:1.0@1.0 in:top.

sel list:list.
sel multipleSelectOk:true.

sel doubleClickAction:[:i| (list at:i) toggleExpand ].
sel   indicatorAction:[:i| (list at:i) toggleExpand ].

top open.

show a hierarchical list; open an editor on reselect a line with label is a string.

|top sel list item|

list := HierarchicalList new.
item := HierarchicalItem::Example labeled:'Root Item'.

item expand.
list showRoot:false.
list root:item.

top := StandardSystemView new; extent:300@300.
sel := ScrollableView for:HierarchicalListView miniScrollerH:true
                   origin:0.0@0.0 corner:1.0@1.0 in:top.

sel list:list.

sel openEditorAction:[:ln :aGC| |field item|
    item  := list at:ln.

    item label isString ifFalse:[
        field := nil
    ] ifTrue:[
        field := EditField new.
        field level:0.
        field acceptOnLostFocus:true.
        field acceptAction:[:x| item label:(field contents) ].
        field font:(aGC font).
        field contents:(item label).
    ].
    field
].

sel multipleSelectOk:true.

sel doubleClickAction:[:i| (list at:i) toggleExpand ].
sel   indicatorAction:[:i| (list at:i) toggleExpand ].

top open.

|top sel list item|

list := HierarchicalList new.
item := HierarchicalItem::Example labeled:'Root Item'.

item expand.
list showRoot:false.
list root:item.

top := StandardSystemView new; extent:300@300.
sel := ScrollableView for:HierarchicalListView miniScrollerH:true
                   origin:0.0@0.0 corner:1.0@1.0 in:top.

sel openIndicator:(ToolbarIconLibrary down22x22Icon).
sel closeIndicator:(ToolbarIconLibrary downRight22x22Icon).
sel showLines:false.

sel list:list.
sel multipleSelectOk:true.
sel alignTextRight:true.
sel doubleClickAction:[:i| (list at:i) toggleExpand ].
sel   indicatorAction:[:i| (list at:i) toggleExpand ].

top open.

ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Sat, 27 Jul 2024 06:45:12 GMT