state

Generic Function

Package: common-graphics

Arguments: widget

Returns two value. The first is the state of the argument, which should be a window or a visible control of some sort. Possible values for most objects are :normal, :shrunk. Windows can also be :icon, :maximized, and :pop-up. The second returned value is described in the last paragraph below).

:normal: the control or window has its normal size and is visible.
:shrunk: the control or window is shrunken and not visible.
:icon: the window is shrunk to a visible icon.
:maximized: the window is extended to its maximum size.

Change in release 6.0: the associated generic function (setf state) is called whenever the state of a window is changed, either programmatically by calling other exported functions such as shrink-window, expand-window, and zoom-window, or interactively when the user clicks the shrink, maximize, or restore buttons on a window frame. In releases prior to 6.0, (setf state) called the other three functions instead, and was not called for interactive state changes except when a window was iconized.

The value argument to (setf state) can be passed as :expanded to expand the window to :normal or :maximized, whichever it was before being shrunk (if it has never been expanded, it is made :normal). Note that :expanded not a true state, so the resulting state of the window will be either :normal or :maximized.

A (setf state) :around method prevents any other non-:around (setf state) methods from being called if the state would not actually be changed by the call. Therefore any methods added by an application do not need to handle this efficiency consideration. This around method also coerces the special :expanded state to either :normal or :maximized and passes that value to the other (setf state) methods that it calls, so any primary, :before, or :after (setf state) methods added by an application will not receive the :expanded state.

The generic functions state and (setf state) may be called on dialog-items or windows, while the other three functions apply only to windows.

state returns a second value for the "expanded state" of the window. This value is always either :normal or :maximized. If the current state of the window is :shrunk or :icon, then the value is the state into which the window will be placed if expand-window is called on it or if (setf state) is called on it with the :expanded state. This is also the most recent expanded state that the window was in, or :normal if it has never been expanded. If the current state of the window is :normal or :maximized, the value is the state to which the window was most recently expanded from :shrunk or :icon state.

Here is an example of an added (setf state) :around method that looks at both the old and new states of any frame-window whose state may be changing, and reports any change. Typcially several custom methods on shrink-window, expand-window, and so on in 5.0.1 could be collapsed into such a single (setf state) method. A simpler :after method could be used instead if the old state is not of interest.

The without-package-locks is needed here in a source code file that's not in the CG package only because it specializes a CG method on a built-in CG class; normally an application would specialize on its own subclass instead.

The requested-state argument is ignored because it may be :expanded, and we are interested here in the resulting :normal or :maximized state instead. Similarly, some other (setf state) method could coerce the requested state to something else.

Eval-in-listener-thread is used to make sure that the printed output always goes to the selected IDE listener pane (and so this method is suitable only for the IDE and not for a generated application). Otherwise, the message will go to the *terminal-io* of whatever thread changed the window state; for example, clicking the minimize button of an IDE window would iconize the window in the IDE GUI thread, for which *terminal-io* is bound to the console, and so the output would appear there.

The prog1 is used to ensure that this (setf state) method returns whatever the next called method returns, though that would normally be the requested-state.

(without-package-locks
 (defmethod (setf state) :around (requested-state (window frame-window))
   (declare (ignore requested-state))
   (let* ((old-state (state window))
          new-state)
     (prog1 (call-next-method)
       (setq new-state (state window))
       (unless (eq old-state new-state)
         (eval-in-listener-thread
          `(format t "~&State of ~s changed from ~s to ~s.~%"
             (name ,window) ,old-state ,new-state)))))))

Common Graphics and IDE documentation is described in About Common Graphics and IDE documentation in cgide.htm.

The documentation is described in introduction.htm and the index is in index.htm.

Created 2000.10.5.