Appearance Manager Docs

;;;----------------------------------------------------------------------

;;;----------------------------------------------------------------------
;;; Last Updated: 8/20/99
;;; from akh some changes for Carbon/OSx are included july 2001

Changes in this version:

1. Include appearance-editable-text and separator-dialog-item modules
   contributed by Terje Norderhaug.
2. Integrate Terje's little-arrows-dialog-item7 with the original
   little-arrows-dialog-item to make it useable with pre-OS8 systems.
3. Include fixes from the pop-up-title-back-patch to the 
   old-draw-pop-up-menu method. - (obsolete comment)
4. Include fix from Terje Norderhaug to menu-select and 
   new-draw-pop-up-menu to make typein pop-up-menus draw properly. (obsolete comment)
5. Include a new translation of the latest Appearance.p header file.
  (obsolete comment- appearance.lisp is now included in "ccl:interfaces;" for MCL 4.4)
6. Moved installation instructions from Appearance-manager.lisp to this
   file. Also include a description of each module in the documentation
   below.

Changes in previous version:

1. Fix serious bug in appearance-manager.lisp that caused an error when
   invalidating a button-dialog-item.
2. Move drawing when appearance manager not present into separate method.
3. Document exported symbols in new-control-dialog-item.lisp
4. Use back-color when drawing controls, especially clock items.

Changes in previous version:

1. Fix typo in update-progress-bar-min-max method.
2. Fix key-handler method on clock-dialog-items to focus the view before
   redrawing.
3. Always create root control before adding any controls to a window,
   and redefine validate-control-dialog-item method on button-dialog-item
   to avoid trashing a window's erase-region.
4. Provide an alternative method for calling #_IdleControls.

   Thanks to Terje Norderhaug for the above.

Changes in previous version:

1. New modules tab-bar-view and multi-pane-view give functionality of
   OS8 tab controls.
2. New module appearance-activity-mixin allows controls to be drawn as
   disabled when their window is inactive.
2. Move globals & constants to file "appearance-globals," and utility
   functions & methods to file "appearance-utils".
3. Export accessor functions for *appearance-available-p* and 
   *appearance-compatability-mode-p* variables, instead of the names
   themselves.
4. Give the color constants more descriptive names.
5. Draw pop-up-menus as disabled in inactive windows when flags are
   set to do so.
6. Re-write example window to show off new tab control.
7. Various cosmetic changes to the code.

Changes in previous version:

1. Change graphic alignment in example bevel button from :left to :center,
   because :left alignment doesn't work for some reason.
2. Include "font-utils.lisp" file required by new-control-dialog-item
3. Update interface file using Digitool's PInterface Translator

Chages in previous version:

1. Add def-load-pointers forms to restore action-proc slots for
   new-control-dialog-items. Kill-lisp-pointers removes these when
   an application is saved. Thanks to David Lamkins for suggesting
   this solution.
2. Make date/time dialog-items aware of daylight savings time.
3. Added collapse-all funciton.
4. Make set-control-data macro more hygenic.
5. Change menu-gray colors to constants instead of variables
6. Miscelaneous formatting changes (mostly cosmetic).
7. Update package to include Appearance 1.0.2 extensions and SDK

;;;----------------------------------------------------------------------
;;; Appearance-activity-mixin.lisp

  New controls are now drawn as disabled when their window is not 
selected. This mixin class makes it easy to add that behavior to existing 
view classes.


APPEARANCE-ACTIVITY-MIXIN                                   [class]
  A mix-in class for views who want to act like OS8 controls (i.e., 
who want to draw differently when their window is inactive).

DRAW-ACTIVE-P view                               [generic-function]
  Called inside the view-draw-contents method by view classes who 
have mixed in the appearance-activity-mixin to ask whether they
should draw normally (non-nil) or as inactive (nil).

This file also defines methods on control-dialog-item, to ensure they
exhibit this behavior. The behavior is governed by the existance and
settings of the Appearance manager, and by the global variable
ccl::*draw-inactive-dialog-items-as-disabled*.

;;;----------------------------------------------------------------------
;;; Appearance-editable-text.lisp

  Adds the new theme focus rectangle around editable-text-dialog-items
when they are selected. Contributed by Terje Norderhaug.

This module is compatable with systems that do not have Appearance 
installed.


No exported symbols.

;;;----------------------------------------------------------------------
;;; Appearance-globals.lisp

  Global variables and constants used internally by appearance-manager
modules.


No exported symbols.

;;;----------------------------------------------------------------------
;;; Appearance-manager.lisp

  Initialization and other miscelaneous methods.


INIT-APPEARANCE-MANAGER                                  [function]
  Should be called during initialization. Tests for presence of the
Appearance Manager and compatibility mode.

WINDOW-COLLAPSABLE-P window                      [generic-function]
  Returns t if window can be collapsed, nil otherwise.

WINDOW-COLLAPSED-P window                        [generic-function]
  Returns t if window is collapsed, nil otherwise.

WINDOW-COLLAPSE window                           [generic-function]
  Collapses window so that only the title bar is visible.

WINDOW-UNCOLLAPSE window                         [generic-function]
  If window is collapsed, restores the window to its original size.

COLLAPSE-ALL &optional collapse-p                        [function]
  Collapses (or uncollapses) all open windows.

;;;----------------------------------------------------------------------
;;; Appearance-utils.lisp

  Utilities used internally by the appearance-manager. Exported because
they may be usefull for other purposes.

This module is compatable with systems that do not have Appearance 
installed.


TRACK-BUTTON-CLICK &optional hilite-function test-function
                                                 [generic-function]
  Tracks a click on the view in the expected way as if it were a 
button. Does nothing if called while the mouse is up.

HILITE-VIEW view hilite-p                        [generic-function]
  Shows or hides a hilite for the given view depending on the 
value of hilite-p.

SYSTEM-FONT-SPEC                                         [function]
  Returns a spec for the current system font. As of OS8, the system
font is no longer hard-wired, so we need a way to get it.
 (actually ccl::sys-font-spec is a better deal cons-wise)

;;;----------------------------------------------------------------------
;;; Bevel-button-dialog-item.lisp

  A new button control-dialog-item that can display text and icons and/or
picts.


BEVEL-BUTTON-DIALOG-ITEM                                    [class]
  A button that can display text and/or a graphic, which may be an
icon-suite, a cicn, or a pict. A bevel button can also have a menu.

BEVEL-BUTTON-MENU button                         [generic-function]
SET-BEVEL-BUTTON-MENU button menu                [generic-function]
  These methods get and set the menu associated with the bevel 
button. The menu should be an instance of type pop-up-menu, or nil.

BEVEL-BUTTON-MENU-ARROW-DIRECTION button         [generic-function]
SET-BEVEL-BUTTON-MENU-ARROW-DIRECTION menu direction 
                                                 [generic-function]
  These methods are for getting and setting the direction of the
menu arrow. If the button has no associated menu, these methods do
nothing. The direction arg should be one of '(:right :down).

SELECTED-ITEM-INDEX button                       [generic-function]
SET-SELECTED-ITEM-INDEX button index             [generic-function]
  These methods are for getting and setting the selected menu item
for the menu associated with the button. If the button has no menu,
these methods do nothing.

BEVEL-BUTTON-ICON-SUITE-ID button                [generic-function]
SET-BEVEL-BUTTON-ICON-SUITE-ID button res-id     [generic-function]
  These methods are for getting and setting the resource id of the
icon suite displayed in the button. If the button has a cicn or 
pict graphic, calling set-bevel-button-icon-suite-id will replace
it.

BEVEL-BUTTON-CICON-ID button                     [generic-function]
SET-BEVEL-BUTTON-CICON-ID button res-id          [generic-function]
  These methods are for getting and setting the resource id of the
cicn displayed in the button. If the button has an icon suite or
pict graphic, calling set-bevel-button-cicon-id will replace it.

BEVEL-BUTTON-PICT-ID button                      [generic-function]
SET-BEVEL-BUTTON-PICT-ID button res-id           [generic-function]
  These methods are for getting and setting the resource id of the
pict displayed in the button. If the button has an icon suite or
cicn graphic, calling set-bevel-button-pict-id will replace it.

BEVEL-BUTTON-TEXT-ALIGNMENT button               [generic-function]
SET-BEVEL-BUTTON-TEXT-ALIGNMENT button alignment [generic-function]
  These methods are for getting and setting the alignment of the 
text in the button. If the button has no text, these methods do
nothing. The alignment arg should be one of '(:default :left :right
:center).

BEVEL-BUTTON-TEXT-OFFSET button                  [generic-function]
SET-BEVEL-BUTTON-TEXT-OFFSET button offset       [generic-function]
  These are for getting and setting the offset (in pixels) of the 
text from its normal alignment. 

BEVEL-BUTTON-TEXT-PLACEMENT button               [generic-function]
SET-BEVEL-BUTTON-TEXT-PLACEMENT button placement [generic-function]
  These are for getting and setting the placement of the text 
relative to the graphic. The placement arg should be one of 
'(:default :normal :right :left :below :above).

BEVEL-BUTTON-GRAPHIC-ALIGNMENT button            [generic-function]
SET-BEVEL-BUTTON-GRAPHIC-ALIGNMENT button alignment 
                                                 [generic-function]
  These methods are for getting and setting the alignment of the
graphic associated with the button. The alignment arg should be one
of '(:default :center :left :right :top :bottom :top-left 
:bottom-left :top-right :bottom-right).

BEVEL-BUTTON-GRAPHIC-OFFSET button               [generic-function]
SET-BEVEL-BUTTON-GRAPHIC-OFFSET button offset    [generic-function]
  These methods are for getting and setting the offset (in pixels)
of the graphic from its normal alignment.

BEVEL-BUTTON-BEVEL-SIZE button                   [generic-function]
SET-BEVEL-BUTTON-BEVEL-SIZE button size          [generic-function]
  These methods are for getting and setting the size of the 3-d
bevels surrounding the button. The size arg should be one of 
'(:small :normal :large).

BEVEL-BUTTON-BEHAVIOR button                     [generic-function]
SET-BEVEL-BUTTON-BEHAVIOR button behavior        [generic-function]
  These methods are for getting and setting the behavior of the
bevel button. The behavior arg should be one of '(:pushbutton
:toggle :sticky). If the behavior is :pushbutton, the bevel button
behaves like a normal button. If the behavior is :toggle, the 
button behaves like a checkbox. If the behavior is :sticky, the
button, once pressed, remains pressed.

;;;----------------------------------------------------------------------
;;; Chasing-arrows-dialog-item.lisp

  A new control-dialog-item for indicating the progress of an 
asynchronous task.

Note: chasing-arrows-dialog-items can ONLY be contained by a window.
Adding them to a subview of a window will cause them to be drawn 
improperly.


CHASING-ARROWS-DIALOG-ITEM                                  [class]
  This item implements the circular chasing arrows that the 8.0
Finder uses in the top left corner of windows as it is updating 
them. Chasing behavior is achieved by calling #_IdleControls on 
the window in a method defined in appearance-manager.lisp.

;;;----------------------------------------------------------------------
;;; Clock-dialog-items.lisp

  A new control-dialog-item for displaying or editing a date or time.

Note: A clock item that is both live and editable will affect your
system clock.

Also note: LIVE clock-dialog-items can ONLY be contained by a window.
Adding them to a subview of a window will cause them to be drawn 
improperly.


TIME-DIALOG-ITEM                                            [class]
  Displays and (possibly) edits the hour and minute.

TIME-SECONDS-DIALOG-ITEM                                    [class]
  Displays and (possibly) edits the hour, minute, and second.

DATE-DIALOG-ITEM                                            [class]
  Displays and (possibly) edits the year, month, and day.

MONTH-YEAR-DIALOG-ITEM                                      [class]
  Displays and (possibly) edits the year and month.

UNIVERSAL-TIME clock-item                        [generic-function]
SET-UNIVERSAL-TIME clock-item universal-time     [generic-function]
  These methods are for getting and setting the time displayed by
the clock item. Only those elements of the time which are displayed 
by the clock are valid in the time returned. For instance, don't
count on the year having a reasonable value in the time returned
by a time-dialog-item.

LIVE-P clock-item                                [generic-function]
(SETF LIVE-P) live-p clock-item                  [generic-function]
  These methods are for getting and setting the "live" property of
a clock item. If a clock is live, it will follow the system clock.

EDITABLE-P clock-item                            [generic-function]
(SETF EDITABLE-P) editable-p clock-item          [generic-function]
  These methods are for getting and setting the "editable" property
of a clock item. If a clock is editable, it is a key handler and
clicking on it or tabbing into it will allow you to edit the 
displayed time. 

;;;----------------------------------------------------------------------
;;; Little-arrows-dialog-item.lisp

  A new control-dialog-item with up & down arrows for adjusting a value.

  This module is compatable with systems that do not have Appearance 
installed, thanks to Terje Norderhaug.


LITTLE-ARROWS-DIALOG-ITEM                                   [class]
  A subset of scroll bars.

LITTLE-ARROWS-MIN arrows                         [generic-function]
SET-LITTLE-ARROWS-MIN arrows minimum             [generic-function]
  See scroll-bar-min and set-scroll-bar-min.

LITTLE-ARROWS-MAX arrows                         [generic-function]
SET-LITTLE-ARROWS-MAX arrows maximum             [generic-function]
  See scroll-bar-max and set-scroll-bar-max.

LITTLE-ARROWS-SETTING arrows                     [generic-function]
SET-LITTLE-ARROWS-SETTING arrows setting         [generic-function]
  See scroll-bar-setting and set-scroll-bar-setting.

LITTLE-ARROWS-INCREMENT arrows                   [generic-function]
SET-LITTLE-ARROWS-INCREMENT arrows increment     [generic-function]
  See scroll-bar-scroll-size and (setf scroll-bar-scroll-size).

LITTLE-ARROWS-ADJUSTEE arrows                    [generic-function]
SET-LITTLE-ARROWS-ADJUSTEE arrows view           [generic-function]
  See scroll-bar-scrollee and set-scroll-bar-scrollee.

LITTLE-ARROWS-CHANGED view arrows                [generic-function]
  See scroll-bar-changed.

;;;----------------------------------------------------------------------
;;; Multi-pane-view.lisp

  A view that displays multiple panes, one at a time, each identified 
by a title, and allows the user to switch among those panes by means 
of a tab bar.

  This module is compatable with systems that do not have Appearance 
installed.


MULTI-PANE-VIEW                                             [class]
  A view that displays multiple panes, one at a time, each identified 
by a title, and allows the user to switch among those panes by means 
of a tab bar.

ADD-PANE view pane title                         [generic-function]
  Adds a pane to the multi-pane-view.

REMOVE-PANE view &key pane title                 [generic-function]
  Removes the given pane or the pane with the given title (if any)
from the multi-pane-view.

GET-PANE view title                              [generic-function]
  Returns the pane with the given title (if any) displayed by
the multi-pane-view.

VIEW-SELECT-PANE view pane                       [generic-function]
  Called internally when a pane is selected. You shouldn't call this
method, but it's provided in case you want to specialize it. If you
want to select a pane programmatically, use SET-SELECTED-PANE.

SIZE-PANE view pane                              [generic-function]
  Sets the size and position of the pane to the proper values for
the multi-pane-view.

GET-SELECTED-PANE view                           [generic-function]
  Returns the title of the pane currently being displayed by the
multi-pane-view.

SET-SELECTED-PANE view title                     [generic-function]
  If there is a pane displayed by the multi-pane-view with the given
title, it is selected (brought to the front).

;;;----------------------------------------------------------------------
;;; New-control-dialog-item.lisp

  A subclass of control-dialog-item that implements new control behaviors
provided by the Appearance Manager.


VIEW-DRAW-NO-APPEARANCE-CONTENTS                 [generic-function]
  Called on a new-control-dialog-item (or subclass thereof) to draw the
control when the appearance manager is not present.

TEXT-JUSTIFICATION                               [generic-function]
SET-TEXT-JUSTIFICATION                           [generic-function]
  Methods to get and set the justification of a control's text.
Valid values are (:cetner :default :left :right).

BACK-COLOR                                       [generic-function]
SET-BACK-COLOR                                   [generic-function]
  Methods to get and set the text and/or (depending on the class) graphic
background color of a control.

;;;----------------------------------------------------------------------
;;; Platinum-pop-up-menus.lisp

  Re-defines the view-draw-contents method for pop-up-menus and 
pull-down-menus to draw them with the new, 3-d look when the 
Appearance Manager is present and is not in compatibility mode.

This module is compatable with systems that do not have Appearance 
installed.

;;;----------------------------------------------------------------------
;;; Progress-bar-dialog-item.lisp

  A bar for graphically displaying the progress of a task.

Note: INDETERMINATE progress-bar-dialog-items can ONLY be contained by a 
window. Adding them to a subview of a window will cause them to be drawn 
improperly.


PROGRESS-BAR-DIALOG-ITEM                                    [class]
  A progress bar like the one used by the OS8 Finder. If the 
"determinate" property is non-nil, the display is determined by the
progress-bar-setting. If the bar is indeterminate, it is 
automatically updated to draw as a "barber pole."

PROGRESS-BAR-MIN progress-bar                    [generic-function]
SET-PROGRESS-BAR-MIN progress-bar value          [generic-function]
  Methods to get and set the minimum value of the progress bar.

PROGRESS-BAR-MAX progress-bar                    [generic-function]
SET-PROGRESS-BAR-MAX progress-bar value          [generic-function]
  Methods to get and set the maximum value of the progress bar.

PROGRESS-BAR-SETTING progress-bar                [generic-function]
SET-PROGRESS-BAR-SETTING progress-bar setting    [generic-function]
  Methods to get and set the setting of the progress bar. If the
progress bar is indeterminate, these methods do nothing.

PROGRESS-BAR-DETERMINATE-P progress-bar          [generic-function]
SET-PROGRESS-BAR-DETERMINATE-P progress-bar determinate-p 
                                                 [generic-function]
  Methods to get and set the "determinate" property of the progress
bar.

;;;----------------------------------------------------------------------
;;; Separator-dialog-item.lisp

  A 3-d separator line class.

This module is compatable with systems that do not have Appearance 
installed.


SEPARATOR-DIALOG-ITEM                                       [class]
  A separator dialog item a la MacOS 8 with backward compatability 
for  older versions of MacOS. Contributed by Terje Norderhaug.

;;;----------------------------------------------------------------------
;;; Slider-dialog-item.lisp

  A new control-dialog-item for adjusting a scalar value.


SLIDER-DIALOG-ITEM                                          [class]
  Another subset of scroll-bar-dialog-item.

SLIDER-MIN slider                                [generic-function]
SET-SLIDER-MIN slider new-value                  [generic-function]
  See scroll-bar-min and set-scroll-bar-min.

SLIDER-MAX slider                                [generic-function]
SET-SLIDER-MAX slider new-value                  [generic-function]
  See scroll-bar-max and set-scroll-bar-max.

SLIDER-SETTING slider                            [generic-function]
SET-SLIDER-SETTING slider                        [generic-function]
  See scroll-bar-setting and set-scroll-bar-setting.

SLIDER-CHANGED view slider                       [generic-function]
  See scroll-bar-changed.

;;;----------------------------------------------------------------------
;;; Tab-bar-view.lisp

  A view of file-folder-style tabs for changing the contents of another
view.

This module is compatable with systems that do not have Appearance 
installed.


TAB-BAR-VIEW                                                [class]
  A view containing file-folder-style tabs.

ADD-TAB view title action &optional font         [generic-function]
  Adds a tab with the given title and font to the end of the tab-bar.
The tab will call action (with itself as an argument) when selected.

REMOVE-TAB view title                            [generic-function]
  Removes the tab with the given title (if any) from the tab bar.

;;;----------------------------------------------------------------------