"

 COPYRIGHT (c) 1999/2015 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.

"

"{ Package: 'stx:libwidg2' }"

"{ NameSpace: Smalltalk }"

Object subclass:#AbstractHierarchicalItem

	instanceVariableNames:'parent children'

	classVariableNames:''

	poolDictionaries:''

	category:'Views-Support'

!

!AbstractHierarchicalItem class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 1999/2015 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.

"

!

documentation

"

    Hierarchical Items are mostly like Models, but the list of

    dependencies are kept by its HierarchicalList.

    The class is used to build up hierarchical trees.

    2015 update:

        the original HierarchicalItem has been refactored into this abstract class,

        which provides all the mechanisms, but leaves the concrete representation

        of some slots open.

        These are:

            - if and how the geometry information (width + height) are cached,

            - if and how the expanded-state is remembered.

            - if and how the underlying model is fetched

        The old class used private slots for the first three (width-height-isExpanded),

        but did not keep a reference to the model. This leads to a very poor performance,

        as many algorithms degenerated to O(n log(n)) or even O(n^2) time behavior,

        as the model was fetched by walking along the parent chain - sometimes for every item

        in a long list.

        The old class is still around and may be used for small trees,

        but we recommend rewriting applications to use the new CompactHierarchicalItem

        class, which behaves the same on the outside, but uses clever tricks to be both more

        space efficient (saving 2 slots) and time efficient (caching the model).

        For this, make sure that the subclass does not access the instvars isExpanded, width and height

        directly, but uses the getters isExpanded, width and height and the setters setExpanded:, width: and height:

    [Instance variables:]

        parent      <Item, List or nil>         parent or my HierarchicalList.

        children    <Collection or nil>         list of children

    [author:]

        Claus Gittinger (redesign and refactoring)

    [see also:]

        HierarchicalItem (the old item class)

        HierarchicalList (typical model)

        HierarchicalListView (typical user of me)

"

! !

!AbstractHierarchicalItem class methodsFor:'instance creation'!

new

    ^ (self basicNew) initialize

!

parent:aParent

    |item|

    item := self new.

    item parent:aParent.

  ^ item

! !

!AbstractHierarchicalItem class methodsFor:'protocol'!

doResetExtentOnChange

    "true: the extent of the item is reset if a change

     notification is raised from the item. the default is true

    "

    ^ true

! !

!AbstractHierarchicalItem class methodsFor:'queries'!

isAbstract

    "Return if this class is an abstract class.

     True is returned here for myself only; false for subclasses.

     Abstract subclasses must redefine this again."

    ^ self == AbstractHierarchicalItem.

! !

!AbstractHierarchicalItem methodsFor:'accessing'!

getChildren

    "returns the children as they are present (or not); not going to the model..."

    ^ children

!

level

    "returns the level starting with 0 for the root"

    |item level|

    item := self.

    level := 0.

    [ (item := item parentOrModel) notNil] whileTrue:[

        level := level + 1.

        level > 100000 ifTrue:[

            self halt:'possibly recursive item hierarchy'

        ].

    ].

    ^ level

    "Modified: / 09-07-2010 / 08:56:27 / cg"

!

parent

    "returns the parent or nil"

    ^ (parent notNil and:[parent isHierarchicalItem]) 

        ifTrue:[parent]

        ifFalse:[nil]

!

parent:aParent

    "set the parent (or the model if the item is the root item)"

    parent := aParent

!

rootItem

    "returns the root item"

    parent isHierarchicalItem ifTrue:[

        ^ parent rootItem

    ].

    ^ self

! !

!AbstractHierarchicalItem methodsFor:'accessing-children'!

at:anIndex

    "return the child at anIndex if valid;

     if the index is invalid, nil is returned"

    ^ self at:anIndex ifAbsent:nil

!

at:anIndex ifAbsent:exceptionBlock

    "return the child at anIndex if valid; if the index is

     invalid, the result of evaluating the exceptionBlock is returned."

    |list|

    (list := self children) notNil ifTrue:[

        ^ list at:anIndex ifAbsent:exceptionBlock

    ].

    ^ exceptionBlock value

!

at:anIndex put:anItem

    "replace a child by a new item. return anItem (sigh)"

    |children oldItem visIndex model expFlag|

    anItem isNil ifTrue:[

        self removeFromIndex:anIndex toIndex:anIndex.

        ^ nil

    ].

    anItem parent:self.

    (model := self model) isNil ifTrue:[

        self children at:anIndex put:anItem.

        ^ anItem

    ].

    model criticalDo:[

        children := self children.

        oldItem  := children at:anIndex.

        oldItem isExpanded ifTrue:[

            oldItem collapse

        ].

        visIndex := model identityIndexOf:oldItem.

        expFlag  := anItem isExpanded.

        anItem setExpanded:false.

        children at:anIndex put:anItem.

        visIndex ~~ 0 ifTrue:[

            model at:visIndex put:anItem.

        ].

        self changed:#redraw.

        expFlag ifTrue:[ anItem expand ].

    ].

    ^ anItem

!

children:aListOfChildren

    "set a new list of children"

    self criticalDo:[

        self removeAll.

        self addAll:aListOfChildren beforeIndex:1

    ].

    ^ aListOfChildren

!

first

    "returns the first child

    "

    ^ self at:1

!

last

    "returns the last child"

    ^ self at:(self size)

!

second

    "returns the second child"

    ^ self at:2

! !

!AbstractHierarchicalItem methodsFor:'accessing-hierarchy'!

collapse

    "hide all my subitems"

    |visChd index|

    self canCollapse ifTrue:[

        self setExpanded:false.

        self criticalDo:[

            (index := self listIndex) notNil ifTrue:[

                "/ do not call :#size: children will be autoloaded !!!!

                (visChd := children size) ~~ 0 ifTrue:[

                    self nonCriticalFrom:1 to:nil do:[:el|

                        visChd := visChd + el numberOfVisibleChildren

                    ].

                    self model itemRemoveFromIndex:(index + 1) toIndex:(index + visChd).

                ].

                index ~~ 0 ifTrue:[self hierarchyChanged].

            ]

        ]

    ]

!

enforcedExpand

    "expand children - even if there are no children,

     the item is initially expanded (but this might be undone later,

     when we know that no children are there"

    self expand:true

!

expand

    "expand children - but only if there are children 

     (i.e. this cannot be used before the childInfo is valid;

      aka not before the updateTask came along this item)"

    self expand:false

!

expand:enforced

    "expand children"

    |index list|

    "/ test whether the item already is expanded; #canExpand could be redefined

    "/ without checking whether the node is expanded (happens already) !!

    self isExpanded ifTrue:[ ^ self ].

    (enforced not and:[self canExpand not]) ifTrue:[ ^ self ].

    self criticalDo:[

        (index := self listIndex) notNil ifTrue:[

            "/ must set expand-flag to false, otherwise change notifications

            "/ are raised during lazy auto creation (to the list).

            self setExpanded:false.

            list := self children.

            self setExpanded:true.

            list notEmptyOrNil ifTrue:[

                list := OrderedCollection new.

                self addVisibleChildrenTo:list.

                self model itemAddAll:list beforeIndex:(index + 1).

            ].

            index ~~ 0 ifTrue:[self hierarchyChanged].

        ] ifFalse:[

            self setExpanded:true

        ]

    ].

!

makeVisible

    "expand all my parents"

    (parent notNil and:[parent isHierarchicalItem]) ifTrue:[

        self criticalDo:[

            parent makeVisible.

            parent expand.

        ]

    ].

!

recursiveCollapse

    "collapse all item and sub items

     **** must be expanded

    "

    |visChd index|

    self canCollapse ifTrue:[

        self criticalDo:[

            (index := self listIndex) notNil ifTrue:[

                "/ do not call :#size: children will be autoloaded !!!!

                (visChd := children size) ~~ 0 ifTrue:[

                    self nonCriticalFrom:1 to:nil do:[:el|

                        visChd := visChd + el numberOfVisibleChildren

                    ].

                ].

                self recursiveSetCollapsed.

                visChd ~~ 0 ifTrue:[

                    self model itemRemoveFromIndex:(index + 1)

                                           toIndex:(index + visChd)

                ].

                index ~~ 0 ifTrue:[

                    self hierarchyChanged

                ]

            ] ifFalse:[

                self recursiveSetCollapsed

            ]

        ]

    ]

!

recursiveExpand

    "expand children and sub-children

     **** must be collapsed"

    "/ test whether the item already is expanded; #canExpand could be redefined

    "/ without checking whether the node is expanded (happens already) !!

    |index list|

    self isExpanded ifTrue:[ ^ self ].

    self canExpand ifFalse:[ ^ self ].

    self setExpanded:true.

    self criticalDo:[

        self size ~~ 0 ifTrue:[

            index := self listIndex.    "/ get the visible list index

            index isNil ifTrue:[        "/ not visible

                self nonCriticalFrom:1 to:nil do:[:el|

                    el setExpanded:true

                ].

            ] ifFalse:[

                list := OrderedCollection new.

                self recursiveSetExpandedAndAddToList:list.

                self model itemAddAll:list beforeIndex:(index + 1).

                index ~~ 0 ifTrue:[self hierarchyChanged]

            ]

        ]

    ].

!

recursiveToggleExpand

    "if the item is collapsed, the item and all its sub-items

     are expanded otherwise collapsed"

    self isExpanded ifTrue:[

        self recursiveCollapse

    ] ifFalse:[

        self recursiveExpand

    ]

!

toggleExpand

    "if the item is collapsed, the item is expanded otherwise collapsed"

    self isExpanded ifTrue:[

        self collapse

    ] ifFalse:[

        self expand

    ].

! !

!AbstractHierarchicalItem methodsFor:'accessing-mvc'!

application

    "returns the responsible application or nil"

    |model|

    (model := self model) notNil ifTrue:[

        ^ model application

    ].

    ^ nil

!

applicationsDo:aOneArgBlock

    "evaluate the block for each dependent application"

    |model|

    (model := self model) notNil ifTrue:[

        model applicationsDo:aOneArgBlock

    ]

!

model

    "returns the hierachicalList model or nil.

     This is a stupid implementation here, in that the top-item's parent is assumed to

     be the model of the tree, and that is returned.

     This saves a slot in every node, but makes some algorithms O(n*log n) or even O(n^2).

     So be aware of the performance penalty"

    |item next|

    item := self. 

    [ (next := item parentOrModel) notNil ] whileTrue:[

        item := next.

    ].

    item isHierarchicalItem ifFalse:[^ item].

    ^ nil

! !

!AbstractHierarchicalItem methodsFor:'adding & removing'!

add:aChildItem

    "add a child at end"

    ^ self add:aChildItem beforeIndex:(self children size + 1).

!

add:aChildItem after:aChild

    "add an item after an existing item"

    |index|

    index := self identityIndexOf:aChild.

    index == 0 ifTrue:[ self subscriptBoundsError:index ].

    self add:aChildItem beforeIndex:(index + 1).

    ^ aChildItem

!

add:aChildItem afterIndex:anIndex

    "add an item after an index"

    ^ self add:aChildItem beforeIndex:(anIndex + 1).

!

add:aChildItem before:aChild

    "add an item before an existing item"

    |index|

    index := self identityIndexOf:aChild.

    index == 0 ifTrue:[ self subscriptBoundsError:index ].

    self add:aChildItem beforeIndex:index.

    ^ aChild

!

add:aChildItem beforeIndex:anIndex

    "add an item before an index"

    aChildItem notNil ifTrue:[

        self addAll:(Array with:aChildItem) beforeIndex:anIndex

    ].

    ^ aChildItem

!

add:aChild sortBlock:aBlock

    "add a child sorted"

    self criticalDo:[

        self basicAdd:aChild sortBlock:aBlock

    ].

    ^ aChild

!

addAll:aList

    "add children at the end"

    ^ self addAll:aList beforeIndex:(self children size + 1)

!

addAll:aList before:aChild

    "add an item before an existing item"

    |index|