"

 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 Atzkern

        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, and especially not creating autocreated children..."

    ^ children

    "Modified (comment): / 12-02-2019 / 17:41:06 / Claus Gittinger"

!

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 > 10000 ifTrue:[

            self halt:'possibly recursive item hierarchy'.

            ^ self.

        ].

    ].

    ^ level

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

!

nextSibling

    "returns the next child of my parent or nil"

    |siblings myIndex|

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

        siblings := parent getChildren.

        myIndex := siblings identityIndexOf:self.

        myIndex ~~ 0 ifTrue:[

            ^ siblings at:myIndex+1 ifAbsent:nil

        ].

    ].

    ^ nil

    "Created: / 13-02-2019 / 15:17:39 / Claus Gittinger"

!

parent

    "returns the parent or nil"

    |p|

    p := parent.

    ^ (p notNil and:[p isHierarchicalItem]) 

        ifTrue:[p]

        ifFalse:[nil]

    "Modified: / 01-08-2018 / 10:18:37 / Claus Gittinger"

    "Modified: / 01-08-2018 / 16:15:07 / Stefan Vogel"

!

parent:aParent

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

    parent := aParent

!

previousSibling

    "returns the previous child of my parent or nil"

    |siblings myIndex|

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

        siblings := parent getChildren.

        myIndex := siblings identityIndexOf:self.

        myIndex ~~ 0 ifTrue:[

            ^ siblings at:myIndex-1 ifAbsent:nil

        ].

    ].

    ^ nil

    "Created: / 13-02-2019 / 15:17:57 / Claus Gittinger"

!

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 synchronized:[

        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

    "Modified: / 28-07-2018 / 15:51:06 / Claus Gittinger"

!

children:aListOfChildren

    "set a new list of children"

    self synchronized:[

        self removeAll.

        self addAll:aListOfChildren beforeIndex:1.

    ].

    ^ aListOfChildren

    "Modified: / 06-02-2019 / 15:59:15 / Claus Gittinger"

!

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"

    self canCollapse ifTrue:[

        self synchronized:[

            |overAllNrOfVisibleChildren nrOfVisibleChildren index|

            overAllNrOfVisibleChildren := self numberOfVisibleChildren.

            self setExpanded:false.

            (index := self listIndex) notNil ifTrue:[

                "/ do not call self size or self children,

                "/ as this might autocreate children !!!!

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

                    children do:[:el|

                        nrOfVisibleChildren := nrOfVisibleChildren + el numberOfVisibleChildren

                    ].

                    self assert:(nrOfVisibleChildren = overAllNrOfVisibleChildren).

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

                ].

                index ~~ 0 ifTrue:[self hierarchyChanged].

            ]

        ]

    ]

    "Modified: / 12-02-2019 / 18:53:55 / Claus Gittinger"

!

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"

    "/ 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 synchronized:[

        |index list|

        self isExpanded ifFalse:[

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

                list notEmptyOrNil ifTrue:[

                    self setExpanded:true. 

                    list := OrderedCollection new.

                    self addVisibleChildrenTo:list.

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

                ].

                index ~~ 0 ifTrue:[self hierarchyChanged].

            ] ifFalse:[

                self setExpanded:true

            ]

        ].

    ].

    "Modified: / 08-03-2018 / 21:06:13 / stefan"

    "Modified: / 20-02-2019 / 00:23:49 / Claus Gittinger"

!

expandLevels:numLevels

    "expand children numLevels down"

    numLevels == 0 ifTrue:[^ self].

    self children do:[:each |

        each expand.

        each expandLevels:(numLevels - 1).

    ].

!

expandLevels:numLevels max:maxNumExpandedHolder

    "expand children numLevels down"

    |childrenToExpand|

    numLevels == 0 ifTrue:[^ self].

    maxNumExpandedHolder value <= 0 ifTrue:[^ self].

    childrenToExpand := self children.

    childrenToExpand do:[:each |

        each expand.

    ].

    maxNumExpandedHolder value:(maxNumExpandedHolder value - childrenToExpand size).

    childrenToExpand do:[:each |

        each expandLevels:(numLevels - 1) max:maxNumExpandedHolder.

    ].

    "Modified: / 13-02-2019 / 12:33:40 / Claus Gittinger"

!

expandWithoutUpdate

    "in case expand is redefined to do any update 

     (as in guiBrowser's applicationTreeItem),

     this can be used to expand without updating"

    self expand

    "Created: / 02-02-2019 / 19:59:55 / Claus Gittinger"

    "Modified (comment): / 03-02-2019 / 01:28:33 / Claus Gittinger"

!

labelPath

    "return my label-path as an ordered collection of individual labels"

    ^ ({self} , self allParents) reverse collect:#label

    "Created: / 16-10-2017 / 13:09:10 / cg"

    "Modified: / 16-10-2017 / 14:16:46 / cg"

!

makeVisible

    "expand all my parents"

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

        self synchronized:[

            parent makeVisible.

            parent expand.

        ]

    ].

    "Modified: / 28-07-2018 / 15:47:52 / Claus Gittinger"

!

recursiveCollapse

    "collapse item and recursively all sub items"

    self canCollapse ifFalse:[^ self].

    "/ self checkConsistency.    

    self synchronized:[

        |nrOfVisibleChildren index|

        self canCollapse ifTrue:[

            (index := self listIndex) notNil ifTrue:[

                "/ do not call self size or self children here;

                "/ otherwise, lazy children would be autocreated !!!!

                nrOfVisibleChildren := self numberOfVisibleChildren.

                self recursiveSetCollapsedHelper.

                nrOfVisibleChildren ~~ 0 ifTrue:[

                    self model removeFromIndex:(index + 1) toIndex:(index + nrOfVisibleChildren)

                ].

                index ~~ 0 ifTrue:[

                    self hierarchyChanged

                ]

            ] ifFalse:[

                "/ not visible

                self recursiveSetCollapsedHelper

            ]

        ]

    ].

    "/ self checkConsistency.

    "Modified: / 13-02-2019 / 12:59:40 / Claus Gittinger"

!

recursiveExpand

    "expand children and sub-children; 

     WARNING: refetches children.

     Precondition: must be collapsed"

"/ true ifTrue:[ ^ self __recursiveExpand ].

    (self isExpanded not and:[self canRecursiveExpand]) ifFalse:[ ^ self ].

    self synchronized:[  | index |

        index := self listIndex.

                      "/ matilk: why check this again?

        (index notNil and:[self isExpanded not and:[self canRecursiveExpand]]) ifTrue:[ | action mdlist |

            mdlist := OrderedCollection with:self.

            [ mdlist notEmpty ] whileTrue:[ | toExpand |

                toExpand := mdlist removeFirst.

                toExpand setExpanded:true.

                toExpand do:[: eachChild |

                    (eachChild isExpanded or:[eachChild canRecursiveExpand])

                        ifTrue: [ mdlist add:eachChild ]

                        ifFalse:[ eachChild setExpanded:false ].

                ].

            ].

            mdlist := OrderedCollection new: 100.

            action := [: el | mdlist add: el. el isExpanded ifTrue:[ el do: action ]. ].

            action value: self.

            mdlist removeFirst.

            self model itemAddAll:mdlist afterIndex: index.