state

Arguments: widget

State for windows and miscellaneous controls

state works differently on outline-items, as described below under the heading State on outline-items.

This generic function returns two values. 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 and :shrunk. Windows can also be :icon, and :maximized. The second returned value is described under the heading Second returned value 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.

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.

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 is 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.

Second returned value

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.

Example

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 common-graphics package only because it specializes a common-graphics method on a built-in common-graphics 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)
         (ide:eval-in-listener-thread
          `(format t "~&State of ~s changed from ~s to ~s.~%"
             (name ,window) ,old-state ,new-state)))))))

State on outline-items

The state property also applies to outline-items, though the valid values are :closed, :open, and :partially-open, rather than the values listed above.

:closed indicates that the item's subitems are not currently shown, while :open indicates that they are. :partially-open indicates that some but perhaps not all of the subitems are currently shown, and so the next user gesture to toggle the state will show all subitems, rather than hiding them as is normally done when subitems are already showing.

:partially-open is probably useful only when a range-on-open method has been supplied for the outline, since a range-on-open method can be written to return different sets of subitems at different times depending on some arbitrary current context.

(setf state) may be called on an outline-item to hide or show its subitems, as an alternative to calling close-outline-item-value or open-outline-item-value; passing :partially-open will show the subitems, but leave the outline-item in a state where the next user gesture to toggle the state will again show subitems. The state of an outline-item may also be established by passing the :state initarg when calling make-instance to create the outline-item.

The (setf state) method for an outline-item does not do certain additional things (that were done is earlier releases) that an interactive toggling of the item state might do, such as moving the keyboard focus to the item and scrolling the item into view. This was especially inefficient when programmatically setting the state of a number of outline-items, and could leave the focus on an arbitrary item. An application can control the extra behavior with calls to the setf's of functions such as focus-index, selected-outline-item, and a call to set-first-visible-line.

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