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.

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)))

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.