| Allegro CL version 8.2 Moderately revised from 8.1. 8.1 version |
Arguments: widget
state works
differently on outline-item
s, 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.
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 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)))))))
The state
property also applies to outline-item
s, 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.
| Allegro CL version 8.2 Moderately revised from 8.1. 8.1 version |