xemacs-beta: man/lispref/frames.texi comparison

comparison man/lispref/frames.texi @ 444:576fb035e263 r21-2-37

Import from CVS: tag r21-2-37

author	cvs
date	Mon, 13 Aug 2007 11:36:19 +0200
parents	abe6d1db359e
children	755ae5b97edb

comparison

equal deleted inserted replaced

-:a8296e22da4e
+:576fb035e263
 @c -*-texinfo-*-
 @c This is part of the XEmacs Lisp Reference Manual.
 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
 @c Copyright (C) 1995, 1996 Ben Wing.
 @c See the file lispref.texi for copying conditions.
 @setfilename ../../info/frames.info
 @node Frames, Consoles and Devices, Windows, Top
 @chapter Frames
 @node Creating Frames
 @section Creating Frames
 To create a new frame, call the function @code{make-frame}.
-@defun make-frame &optional props device
+@deffn Command make-frame &optional props device
 This function creates a new frame on @var{device}, if @var{device}
 permits creation of frames.  (An X server does; an ordinary terminal
 does not (yet).)  @var{device} defaults to the selected device if omitted.
 @xref{Consoles and Devices}.
 The set of possible properties depends in principle on what kind of
 window system XEmacs uses to display its frames.  @xref{X Frame
 Properties}, for documentation of individual properties you can specify
 when creating an X window frame.
-@end defun
+@end deffn
 @node Frame Properties
 @section Frame Properties
 A frame has many properties that control its appearance and behavior.
 and their values.
 @end defun
 @defun frame-property frame property &optional default
 This function returns @var{frame}'s value for the property
-@var{property}.
+@var{property}, or @var{default} if there is no such property.
 @end defun
 @defun set-frame-properties frame plist
 This function alters the properties of frame @var{frame} based on the
 elements of property list @var{plist}.  If you don't mention a property
 in @var{plist}, its value doesn't change.
 @end defun
-@defun set-frame-property frame prop val
+@defun set-frame-property frame property value
-This function sets the property @var{prop} of frame @var{frame} to the
+This function sets the property @var{property} of frame @var{frame} to the
-value @var{val}.
+value @var{value}.
 @end defun
 @node Initial Properties
 @subsection Initial Frame Properties
 @end defun
 @defun set-frame-size frame cols rows &optional pretend
 This function sets the size of @var{frame}, measured in characters;
 @var{cols} and @var{rows} specify the new width and height.  (If
-@var{pretend} is non-nil, it means that redisplay should act as if
+@var{pretend} is non-@code{nil}, it means that redisplay should act as if
 the frame's size is @var{cols} by @var{rows}, but the actual size
 of the frame should not be changed.  You should not normally use
 this option.)
 @end defun
 Frames remain potentially visible until you explicitly @dfn{delete}
 them.  A deleted frame cannot appear on the screen, but continues to
 exist as a Lisp object until there are no references to it.
-@deffn Command delete-frame &optional frame
+@deffn Command delete-frame &optional frame force
 This function deletes the frame @var{frame}.  By default, @var{frame} is
 the selected frame.
+A frame may not be deleted if its minibuffer is used by other frames.
+Normally, you cannot delete the last non-minibuffer-only frame (you must
+use @code{save-buffers-kill-emacs} or @code{kill-emacs}).  However, if
+optional second argument @var{force} is non-@code{nil}, you can delete
+the last frame. (This will automatically call
+@code{save-buffers-kill-emacs}.)
 @end deffn
 @defun frame-live-p frame
 The function @code{frame-live-p} returns non-@code{nil} if the frame
 @var{frame} has not been deleted.
 If @var{device} is specified only frames on that device will be returned.
 @xref{Visibility of Frames}.  (TTY frames always count as
 ``visible'', even though only the selected one is actually displayed.)
 @end defun
-@defun next-frame &optional frame minibuf
+@defun next-frame &optional frame which-frames which-devices
 The function @code{next-frame} lets you cycle conveniently through all
 the frames from an arbitrary starting point.  It returns the ``next''
-frame after @var{frame} in the cycle.  If @var{frame} is omitted or
+frame after @var{frame} in the cycle.  If @var{frame} defaults to the
-@code{nil}, it defaults to the selected frame.
+selected frame.
-The second argument, @var{minibuf}, says which frames to consider:
+The second argument, @var{which-frames}, says which frames to consider:
+@table @asis
+@item @code{visible}
+Consider only frames that are visible.
+@item @code{iconic}
+Consider only frames that are iconic.
+@item @code{invisible}
+Consider only frames that are invisible (this is different from iconic).
+@item @code{visible-iconic}
+Consider frames that are visible or iconic.
+@item @code{invisible-iconic}
+Consider frames that are invisible or iconic.
+@item @code{nomini}
+Consider all frames except minibuffer-only ones.
+@item @code{visible-nomini}
+Like @code{visible} but omits minibuffer-only frames.
+@item @code{iconic-nomini}
+Like @code{iconic} but omits minibuffer-only frames.
+@item @code{invisible-nomini}
+Like @code{invisible} but omits minibuffer-only frames.
+@item @code{visible-iconic-nomini}
+Like @code{visible-iconic} but omits minibuffer-only frames.
+@item @code{invisible-iconic-nomini}
+Like @code{invisible-iconic} but omits minibuffer-only frames.
+@item @code{nil}
+Identical to @code{nomini}.
+@item @var{window}
+Consider only the window @var{window}'s frame and any frame now using
+@var{window} as the minibuffer.
+@item any other value
+Consider all frames.
+@end table
+The optional argument @var{which-devices} further clarifies on which
+devices to search for frames as specified by @var{which-frames}.
 @table @asis
 @item @code{nil}
-Exclude minibuffer-only frames.
+Consider all devices on the selected console.
-@item @code{visible}
-Consider all visible frames.
+@item @var{device}
-@item 0
+Consider only the one device @var{device}.
-Consider all visible or iconified frames.
-@item a window
+@item @var{console}
-Consider only the frames using that particular window as their
+Consider all devices on @var{console}.
-minibuffer.
-@item the symbol @code{visible}
+@item @var{device-type}
-Include all visible frames.
+Consider all devices with device type @var{device-type}.
-@item @code{0}
-Include all visible and iconified frames.
+@item @code{window-system}
+Consider all devices on window system consoles.
 @item anything else
-Consider all frames.
+Consider all devices without restriction.
 @end table
 @end defun
-@defun previous-frame &optional frame minibuf
+@defun previous-frame &optional frame which-frames which-devices
 Like @code{next-frame}, but cycles through all frames in the opposite
 direction.
 @end defun
 See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
 order.  The order runs from the frame's top window, which is at the
 upper left corner, down and to the right, until it reaches the window at
 the lower right corner (always the minibuffer window, if the frame has
 one), and then it moves back to the top.
-@defun frame-top-window frame
+@defun frame-highest-window &optional frame position
-This returns the topmost, leftmost window of frame @var{frame}.
+This function returns the topmost, leftmost window of frame @var{frame}
-@end defun
+at position @var{position}.
+If omitted, @var{frame} defaults to the currently selected frame.
+@var{position} is used to distinguish between multiple windows that abut
+the top of the frame: 0 means the leftmost window abutting the top of
+the frame, 1 the next-leftmost, etc.  @var{position} can also be less
+than zero: -1 means the rightmost window abutting the top of the frame,
+-2 the next-rightmost, etc.  If omitted, @var{position} defaults to 0,
+i.e. the leftmost highest window.  If there is no window at the given
+@var{position}, @code{nil} is returned.
+@end defun
+The following three functions work similarly.
+@defun frame-lowest-window &optional frame position
+This function returns the lowest window on @var{frame} which is at
+@var{position}.
+@end defun
+@defun frame-leftmost-window &optional frame position
+This function returns the leftmost window on @var{frame} which is at
+@var{position}.
+@end defun
+@defun frame-rightmost-window &optional frame position
+This function returns the rightmost window on @var{frame} which is at
+@var{position}.
+@end defun
 At any time, exactly one window on any frame is @dfn{selected within the
 frame}.  The significance of this designation is that selecting the
 frame also selects this window.  You can get the frame's current
 selected window with @code{frame-selected-window}.
 This function selects @var{frame} and gives it the window system focus.
 The operation of @code{focus-frame} is not affected by the value of
 @code{focus-follows-mouse}.
 @end defun
-@defmac save-selected-frame forms@dots{}
+@defspec save-selected-frame forms@dots{}
-This macro records the selected frame, executes @var{forms} in sequence,
+This special form records the selected frame, executes @var{forms} in
-then restores the earlier selected frame.  The value returned is the
+sequence, then restores the earlier selected frame.  The value returned
-value of the last form.
+is the value of the last form.
-@end defmac
+@end defspec
-@defmac with-selected-frame frame forms@dots{}
+@defspec with-selected-frame frame forms@dots{}
-This macro records the selected frame, then selects @var{frame} and
+This special form records the selected frame, then selects @var{frame}
-executes @var{forms} in sequence.  After the last form is finished, the
+and executes @var{forms} in sequence.  After the last form is finished,
-earlier selected frame is restored.  The value returned is the value of
+the earlier selected frame is restored.  The value returned is the value
-the last form.
+of the last form.
-@end defmac
+@end defspec
 @ignore (FSF Emacs, continued from defun select-frame)
 XEmacs cooperates with the X server and the window managers by arranging
 to select frames according to what the server and window manager ask
 for.  It does so by generating a special kind of input event, called a
 @cindex visible frame
 @cindex invisible frame
 @cindex iconified frame
 @cindex frame visibility
-An X window frame may be @dfn{visible}, @dfn{invisible}, or
+An frame on a window system may be @dfn{visible}, @dfn{invisible}, or
 @dfn{iconified}.  If it is visible, you can see its contents.  If it is
 iconified, the frame's contents do not appear on the screen, but an icon
 does.  If the frame is invisible, it doesn't show on the screen, not
 even as an icon.
 Visibility is meaningless for TTY frames, since only the selected
 one is actually displayed in any case.
-@deffn Command make-frame-visible &optional frame
+@defun make-frame-visible &optional frame
 This function makes frame @var{frame} visible.  If you omit @var{frame},
 it makes the selected frame visible.
-@end deffn
+@end defun
-@deffn Command make-frame-invisible &optional frame
+@defun make-frame-invisible &optional frame force
 This function makes frame @var{frame} invisible.
-@end deffn
+@end defun
 @deffn Command iconify-frame &optional frame
 This function iconifies frame @var{frame}.
 @end deffn
-@deffn Command deiconify-frame &optional frame
+@defun Command deiconify-frame &optional frame
-This function de-iconifies frame @var{frame}.  Under X, this is
+This function de-iconifies frame @var{frame}.  Under a window system,
-equivalent to @code{make-frame-visible}.
+this is equivalent to @code{make-frame-visible}.
-@end deffn
+@end defun
-@defun frame-visible-p frame
+@defun frame-visible-p &optional frame
 This returns whether @var{frame} is currently ``visible'' (actually in
 use for display).  A frame that is not visible is not updated, and, if
 it works through a window system, may not show at all.
 @end defun
-@defun frame-iconified-p frame
+@defun frame-iconified-p &optional frame
 This returns whether @var{frame} is iconified.  Not all window managers
 use icons; some merely unmap the window, so this function is not the
 inverse of @code{frame-visible-p}.  It is possible for a frame to not
 be visible and not be iconified either.  However, if the frame is
 iconified, it will not be visible.  (Under FSF Emacs, the functionality
 of this function is obtained through @code{frame-visible-p}.)
 @end defun
-@defun frame-totally-visible-p frame
+@defun frame-totally-visible-p &optional frame
 This returns whether @var{frame} is not obscured by any other X
 windows.  On TTY frames, this is the same as @code{frame-visible-p}.
 @end defun
 @ignore  @c Not in XEmacs.
 @defun current-frame-configuration
 This function returns a frame configuration list that describes
 the current arrangement of frames and their contents.
 @end defun
-@defun set-frame-configuration configuration
+@defun set-frame-configuration configuration &optional nodelete
-This function restores the state of frames described in
+This function restores the state of frames described by
+@var{configuration}, which should be the return value from a previous
+call to @code{current-frame-configuration}.
+Each frame listed in @var{configuration} has its position, size, window
+configuration, and other properties set as specified in
 @var{configuration}.
+Ordinarily, this function deletes all existing frames not listed in
+@var{configuration}.  But if optional second argument @var{nodelete} is
+non-@code{nil}, the unwanted frames are iconified instead.
 @end defun
 @node Frame Hooks
 @section Hooks for Customizing Frame Behavior
 @cindex frame hooks

Mercurial > hg > xemacs-beta

comparison man/lispref/frames.texi @ 444:576fb035e263 r21-2-37