range-on-open

Generic Function

Package: cg

ToC

DocOverview

CGDoc

RelNotes

FAQ

Index

PermutedIndex

Allegro CL version 10.1
Unrevised from 10.0 to 10.1.
10.0 version

range-on-open

Arguments: outline item-value range

Returns the list of child outline-items that an outline-item should display when its state is :open. This generic function is called internally whenever an outline-item is opened, either interactively by the end user or programmatically by calling (setf state) on the outline-item or open-outline-item-value on its value. The returned value is then stored as the new range of the outline-item.

The default method returns the current list of outline-items that is stored as the value of the range property of this outline-item. An application may supply a custom range-on-open method for an outline subclass in order to create most of the outline-items lazily if and when the end user opens each parent item. If all outline-items are instead created when creating the outline itself (or if they are added later with add-outline-item or add-outline-item-value), then there is no need to write a range-on-open method.

outline is the outline control that the outline-item being opened is on. item-value is the current value of this outline-item. range is the list of child items currently stored as the range of the outline-item.

When a custom range-on-open method creates new outline-items, these items typically do not in turn have child items yet, because such items would be created later if and when range-on-open is further called for the items being created now. The outline will not know at this time whether range-on-open would later return further child items, and so by default would draw the new items as leaf nodes. To prevent this from happening, the has-range-on-open property of each new item being created should be set to true if that item is expected to have child items if and when it is opened later.

The user is allowed to open all descendent items of an outline-item either by control-clicking its icon or by selecting the item and pressing control-right-arrow. This could cause many items (or even an infinite number if items loop) to be opened if range-on-open methods are written in a way that allow that. If this recursive-opening operation is taking a long time, the user can press the Escape key to interrupt the operation and display whatever items have been opened so far.

Below is the range-on-open method from the Navigator Dialog's basic outline example.

;; The generic function range-on-open is called whenever an
;; outline-item is opened.  We add this method to lazily open the
;; outline-items in the outline in the right half of the dialog.
(defmethod range-on-open ((outline my-class-outline) item-value range)
  
  ;; If this item has already been opened, then the range we gave
  ;; it last time is passed back in on this call.  Assume that the
  ;; set of subclasses we found previously is still current, and
  ;; just return them again to show the same subclasses this time.
  (or range
      
      ;; If no child items were passed in, then either this
      ;; class has no subclasses or this outline-item has not
      ;; yet been opened.  So find the subclasses for the latter
      ;; case and create new outline-items for them the first
      ;; time the user opens this item.
      (mapcar #'make-subclass-item-lazily
        (mop:class-direct-subclasses item-value))))

;; This function is used by the outline in the right half of the dialog
;; to create outline-items "lazily" for the direct subclasses of a class
;; when that class' outline-item is opened by the user.
(defun make-subclass-item-lazily (class)
  (make-instance 'outline-item
    :value class
    :state :closed
    
    ;; Since this outline is opening items lazily, Common Graphics doesn't yet
    ;; know if the outline-item is REALLY a "leaf" with no sub-items.
    ;; So check ahead for subclasses of this subclass, and if there
    ;; are any then tell the outline to draw this item as an
    ;; openable item rather than as a leaf.
    :has-range-on-open (and (mop:class-direct-subclasses class) t)))