"

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

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

            self halt:'possibly recursive item hierarchy'.

            ^ self.

        ].

    ].

    ^ level

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

!

parent

    "returns the parent or nil"

    |p|

        ifTrue:[p]

        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 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: / 28-07-2018 / 15:47:25 / 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"

    |visChd index|

    self canCollapse ifTrue:[

        self setExpanded:false.

        self synchronized:[

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

            ]

        ]

    ]

    "Modified: / 28-07-2018 / 15:47:29 / 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|

        (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: / 28-07-2018 / 15:47:47 / 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"

    numLevels == 0 ifTrue:[^ self].

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

    self children do:[:each |

        each expand.

    ].

    maxNumExpandedHolder value:(maxNumExpandedHolder value - self children size).

    self children do:[:each |

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

    ].

!

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 all item and sub items

     **** must be expanded

    "

    self synchronized:[

        |visChd index|

        self canCollapse ifTrue:[

            (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

            ]

        ]

    ]

    "Modified (format): / 28-07-2018 / 15:48:20 / Claus Gittinger"

!

recursiveExpand

    "expand children and sub-children

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

    self isExpanded ifTrue:[ ^ self ].

    self canExpand ifFalse:[ ^ self ].

    self setExpanded:true.

    self synchronized:[

        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]

            ]

        ]

    ].

    "Modified (format): / 28-07-2018 / 13:56:15 / Claus Gittinger"

!

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

    ]

!

fetchModel

    "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

!

model

    "returns the hierachicalList model or nil.