outline

Class

The class of an outline control.

Control

Instance of the outline class. This control acts as a multiple-item list, with added functionality to display its items in a hierarchy and to display only selected subtrees of the hierarchy. The items displayed are instances of the outline-item class.

The outline can be navigated via the arrow keys and the PAGE UP/PAGE DOWN keys. Scrollbars appear along the length of the control when the list exceeds the size of the frame.

Adding an outline control to your form

Click the outline tool on the Component toolbar. Move the mouse cursor to the part of the form where you want to place the control, and click again. The control will appear with colored resizing handles.

Resizing and moving the control

Controls can only be resized and moved on forms during the design stage; the size and location of everything is fixed on a running form.

Resize the control by clicking the mouse cursor and dragging one of the handles to the new size-point. Release the mouse key when you are satisfied with the new size. Note: resizing the outline won't mean proportional changes in the size of the characters inside the list. Change the font property if you want to change the size of the actual characters displayed.

Move the control by clicking anywhere on it except a resizing handle and dragging it to a new location on the form. Release the mouse key when you are ready to place the control.

Creating an outline widget programmatically

Here is an example of writing code from scratch to create an outline widget, rather than building one interactively on a form. The keyword arguments here such as :range correspond to properties such as the range property that would be displayed in the inspector for an outline on a form, and which you can modify by calling (setf range).

The nested tree of :range arguments shown here demonstrates how to specify the whole tree of outline-items at once; an alternative is to write range-on-open methods that create each item's child items lazily when the item is opened by the user. Another alternative would be to call (setf range) on individual outline-item objects. For more complete examples, see the "Outline Widget" examples in the Navigator Dialog.

There are many functions for manipulating outline widgets. A good way to find documentation links to all of them is by searching for "outline" in the Allegro Tree of Knowledge dialog displayed by the Help | Tree of Knowledge menu command. One generic function for outline widgets is handle-home-key-shortcuts, which allows keys in the middle of the keyboard (J, K, D, F, T, and B) to have the same effect as keys often on the right, like the arrow keys, Home, and End.

(in-package :cg-user)
(make-window 'outline-dialog
  :class 'dialog
  :interior (make-box-relative 100 200 240 140)
  :dialog-items
  (list (make-instance 'outline
          :font (make-font-ex nil "MS Sans Serif" 11 nil)
          :left 20 :top 20 :width 200 :height 100
          :name :my-outline
          :value :top-1
          :range
          (list (make-instance 'outline-item
                  :value :top-1
                  :state :open
                  :selected t
                  :range
                  (list (make-instance 'outline-item 
                          :value :middle-1
                          :state :open
                          :range
                          (list
                           (make-instance 'outline-item 
                             :value :bottom-11
                             :state :closed)
                           (make-instance 'outline-item
                             :value :bottom-12
                             :available nil
                             :state :closed)
                           (make-instance 'outline-item
                             :value :bottom-13
                             :state :closed
                             :font
                             (make-font-ex
                              nil "Courier" 15 '(:bold :italic)))))
                        (make-instance 'outline-item
                          :value :middle-2
                          :state :open
                          :range
                          (list
                           (make-instance 'outline-item
                             :value :bottom-21
                             :state :closed
                             :foreground-color red)
                           (make-instance 'outline-item
                             :value :bottom-22
                             :state :closed)
                           (make-instance 'outline-item
                             :value :bottom-23
                             :state :closed
                             :background-color yellow)))))
                (make-instance 'outline-item
                  :value :top-2
                  :state :open
                  :range
                  (list (make-instance 'outline-item
                          :value :biff
                          :state :closed
                          :background-color cyan)
                        (make-instance 'outline-item
                          :value :boff
                          :state :closed
                          :range nil)))))))

See also About how to get sample code for creating controls in cgide.htm, which explains how to use the IDE to create such code.

A diagram of window and widget classes is shown in Widget and window classes in cgide.htm.

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page has had moderate revisions compared to the 9.0 page.
Created 2019.8.20.