size of a frame is available only after the frame has been mapped (made
visible, @pxref{Visibility of Frames}) at least once. For the initial
frame or a frame that has not been created yet, the outer size can be
-estimated only or must be calculated from the window-system's or window
-manager defaults. One workaround is to obtain the differences of the
+only estimated or must be calculated from the window-system's or window
+manager's defaults. One workaround is to obtain the differences of the
outer and native (see below) sizes of a mapped frame and use them for
calculating the outer size of the new frame.
@cindex outer position
-The upper left corner of the outer frame (indicated by @samp{(0)} in the
-drawing above) is the @dfn{outer position} of the frame. The outer
-position of a graphical frame is also referred to as ``the position'' of
-the frame because it usually remains unchanged on its display whenever
-the frame is resized or its layout is changed.
+The position of the upper left corner of the outer frame (indicated by
+@samp{(0)} in the drawing above) is the @dfn{outer position} of the
+frame. The outer position of a graphical frame is also referred to as
+``the position'' of the frame because it usually remains unchanged on
+its display whenever the frame is resized or its layout is changed.
The outer position is specified by and can be set via the @code{left}
and @code{top} frame parameters (@pxref{Position Parameters}). For a
@code{override-redirect} frames (@pxref{Management Parameters}).
Outer borders are never shown on text terminal frames and on frames
-generated by GTK+ routines. On Windows, the outer border is emulated
+generated by GTK+ routines. On MS-Windows, the outer border is emulated
with the help of a one pixel wide external border. Non-toolkit builds
-allow to change the color of the outer border by setting the
+on X allow to change the color of the outer border by setting the
@code{border-color} frame parameter (@pxref{Layout Parameters}).
@item Title Bar
@cindex title bar
-The @dfn{title bar} is also part of the window manager's decorations and
-typically displays the title of the frame (@pxref{Frame Titles}) as well
-as buttons for minimizing, maximizing and deleting the frame. It can be
-also used for dragging the frame with the mouse. The title bar is
-usually not displayed for fullboth (@pxref{Size Parameters}), tooltip
-(@pxref{Tooltips}) and child frames (@pxref{Child Frames}) and doesn't
-exist for terminal frames. Display of the title bar can be suppressed
-by setting the @code{override-redirect} or the @code{undecorated} frame
-parameters (@pxref{Management Parameters}).
+@cindex caption bar
+The @dfn{title bar}, a.k.a.@ @dfn{caption bar}, is also part of the
+window manager's decorations and typically displays the title of the
+frame (@pxref{Frame Titles}) as well as buttons for minimizing,
+maximizing and deleting the frame. It can be also used for dragging
+the frame with the mouse. The title bar is usually not displayed for
+fullboth (@pxref{Size Parameters}), tooltip (@pxref{Tooltips}) and
+child frames (@pxref{Child Frames}) and doesn't exist for terminal
+frames. Display of the title bar can be suppressed by setting the
+@code{override-redirect} or the @code{undecorated} frame parameters
+(@pxref{Management Parameters}).
@item Menu Bar
@cindex internal menu bar
setting the @code{menu-bar-lines} parameter (@pxref{Layout Parameters})
to zero.
-It depends on the toolkit whether to wrap or truncate the menu bar
-whenever it becomes too long to fit on its frame. Usually, only Motif
-and Windows builds can wrap the menu bar. When they (un-)wrap the menu
-bar, they try to keep the outer height of the frame unchanged, so the
-native height of the frame (see below) will change instead.
+Whether the menu bar is wrapped or truncated whenever its width
+becomes too large to fit on its frame depends on the toolkit .
+Usually, only Motif and MS-Windows builds can wrap the menu bar. When
+they (un-)wrap the menu bar, they try to keep the outer height of the
+frame unchanged, so the native height of the frame (see below) will
+change instead.
@item Tool Bar
@cindex internal tool bar
Parameters}) to zero.
If the variable @code{auto-resize-tool-bars} is non-@code{nil}, Emacs
-wraps the internal tool bar when it becomes too long for its frame. If
-and when Emacs (un-)wraps the internal tool bar, it by default keeps the
-outer height of the frame unchanged, so the native height of the frame
-(see below) will change instead. Emacs built with GTK+, on the other
-hand, never wraps the tool bar but may automatically increase the outer
-width of a frame in order to accommodate an overlong tool bar.
+wraps the internal tool bar when its width becomes too large for its
+frame. If and when Emacs (un-)wraps the internal tool bar, it by
+default keeps the outer height of the frame unchanged, so the native
+height of the frame (see below) will change instead. Emacs built with
+GTK+, on the other hand, never wraps the tool bar but may
+automatically increase the outer width of a frame in order to
+accommodate an overlong tool bar.
@item Native Frame
@cindex native frame
mouse.
@cindex native position
-The top left corner of the native frame specifies the @dfn{native
-position} of the frame. (1)--(3) in the drawing above indicate that
-position for the various builds:
+The position of the top left corner of the native frame specifies the
+@dfn{native position} of the frame. (1)--(3) in the drawing above
+indicate that position for the various builds:
@itemize @w{}
@item (1) non-toolkit and terminal frames
-@item (2) Lucid, Motif and Windows frames
+@item (2) Lucid, Motif and MS-Windows frames
@item (3) GTK+ and NS frames
@end itemize
embedded in the native frame. Its position is unspecified. Its width
can be obtained by removing from that of the native width the widths of
the internal border, one vertical scroll bar, and one left and one right
-fringe as specified for this frame, see @ref{Layout Parameters}. Its
-height can be obtained by removing from that of the native height the
-widths of the internal border and the heights of the frame's internal
-menu and tool bars and one horizontal scroll bar as specified for this
-frame.
+fringe if they are specified for this frame, see @ref{Layout
+Parameters}. Its height can be obtained by removing from that of the
+native height the widths of the internal border and the heights of the
+frame's internal menu and tool bars and one horizontal scroll bar if
+specified for this frame.
@end table
@cindex absolute position
the frame's display. Correspondingly, the @dfn{absolute edges} of a
frame are given as pixel offsets from that origin.
- Note that with multiple monitors the origin of the display does not
+ Note that with multiple monitors, the origin of the display does not
necessarily coincide with the top-left corner of the entire usable
display area of the terminal. Hence the absolute position of a frame
can be negative in such an environment even when that frame is
By convention, vertical offsets increase ``downwards''. This means
that the height of a frame is obtained by subtracting the offset of its
top edge from that of its bottom edge. Horizontal offsets increase
-``leftwards'' as expected so a frame's width is calculated by
+``rightwards'', as expected, so a frame's width is calculated by
subtracting the offset of its left edge from that of its right edge.
For a frame on a graphical terminal the following function returns the
This function returns geometric attributes of @var{frame}. The return
value is an association list of the attributes listed below. All
coordinate, height and width values are integers counting pixels. Note
-that if @var{frame} has not been mapped (@pxref{Visibility of Frames})
-yet, some of the return values may only represent approximations of the
-actual values---those that can be seen after the frame has been mapped.
+that if @var{frame} has not been mapped yet, (@pxref{Visibility of
+Frames}) some of the return values may only represent approximations of
+the actual values---those that can be seen after the frame has been
+mapped.
@table @code
@item outer-position
@defun frame-edges &optional frame type
This function returns the absolute edges of the outer, native or inner
frame of @var{frame}. @var{frame} must be a live frame and defaults to
-the selected one. The list returned has the form (@var{left} @var{top}
-@var{right} @var{bottom}) where all values are in pixels relative to the
-origin of @var{frame}'s display. For terminal frames the values
-returned for @var{left} and @var{top} are always zero.
+the selected one. The returned list has the form @w{@code{(@var{left}
+@var{top} @var{right} @var{bottom})}} where all values are in pixels
+relative to the origin of @var{frame}'s display. For terminal frames
+the values returned for @var{left} and @var{top} are always zero.
Optional argument @var{type} specifies the type of the edges to return:
@code{outer-edges} means to return the outer edges of @var{frame},
@code{inner-edges} means to return its inner edges.
By convention, the pixels of the display at the values returned for
-@var{left} and @var{top} are inside (part of) @var{frame}. Hence, if
-@var{left} and @var{top} are both zero, the pixel at the display's
-origin is part of @var{frame}. The pixels at @var{bottom} and
-@var{right}, on the other hand, lie immediately outside @var{frame}.
-This means that if you have, for example, two side-by-side frames
-positioned such that the right outer edge of the frame on the left
-equals the left outer edge of the frame on the right, the pixels at that
-edge show a part of the frame on the right.
+@var{left} and @var{top} are considered to be inside (part of)
+@var{frame}. Hence, if @var{left} and @var{top} are both zero, the
+pixel at the display's origin is part of @var{frame}. The pixels at
+@var{bottom} and @var{right}, on the other hand, are considered to lie
+immediately outside @var{frame}. This means that if you have, for
+example, two side-by-side frames positioned such that the right outer
+edge of the frame on the left equals the left outer edge of the frame on
+the right, the pixels at that edge show a part of the frame on the
+right.
@end defun
specified via pixel offsets of its outer edges relative to the native
position of its parent frame.
- You can read or change the position of a frame using the frame
+ You can access or change the position of a frame using the frame
parameters @code{left} and @code{top} (@pxref{Position Parameters}).
Here are two additional functions for working with the positions of an
existing, visible frame. For both functions, the argument @var{frame}
must denote a live frame and defaults to the selected frame.
@defun frame-position &optional frame
-For a normal, non-child frame this function returns a cons of the (X, Y)
-pixel coordinates of its outer position (@pxref{Frame Layout}) with
-respect to the origin (0, 0) of its display. For a child frame
+For a normal, non-child frame this function returns a cons of the pixel
+coordinates of its outer position (@pxref{Frame Layout}) with respect to
+the origin @code{(0, 0)} of its display. For a child frame
(@pxref{Child Frames}) this function returns the pixel coordinates of
-its outer position with respect to an origin (0, 0) at the native
+its outer position with respect to an origin @code{(0, 0)} at the native
position of @var{frame}'s parent.
-Negative return values never indicate an offset from the right or bottom
+Negative values never indicate an offset from the right or bottom
edge of @var{frame}'s display or parent frame. Rather, they mean that
@var{frame}'s outer position is on the left and/or above the origin of
its display or the native position of its parent frame. This usually
@defun set-frame-position frame x y
This function sets the outer frame position of @var{frame} to (@var{x},
@var{y}). The latter arguments specify pixels and normally count from
-an origin at the position (0, 0) of @var{frame}'s display. For child
+the origin at the position (0, 0) of @var{frame}'s display. For child
frames, they count from the native position of @var{frame}'s parent
frame.
or parent frame. Neither do they allow to specify a position that does
not lie within the edges of the display or parent frame. The frame
parameters @code{left} and @code{top} (@pxref{Position Parameters})
-allow to do that but may still fail to provide good results for the
+allow to do that, but may still fail to provide good results for the
initial or a new frame.
This function has no effect on text terminal frames.
@end defun
@defvar move-frame-functions
-This hook specifies the functions run when an Emacs frame is moved
+@cindex frame position changes, a hook
+This hook specifies the functions that are run when an Emacs frame is moved
(assigned a new position) by the window-system or window manager. The
functions are run with one argument, the frame that moved. For a child
frame (@pxref{Child Frames}), the functions are run only when the
initial size of a frame. As soon as you know the native size of a
visible frame, you can calculate its outer size (@pxref{Frame Layout})
by adding in the remaining components from the return value of
-@code{frame-geometry} . For invisible frames or for frames that have
-yet to be created, however, the outer size can be estimated only. This
+@code{frame-geometry}. For invisible frames or for frames that have
+yet to be created, however, the outer size can only be estimated. This
also means that calculating an exact initial position of a frame
specified via offsets from the right or bottom edge of the screen
(@pxref{Frame Position}) is impossible.
following option may help in that case.
@defopt frame-resize-pixelwise
-If this option is @code{nil}, a frame's text pixel size is usually
-rounded to a multiple of the current values of that frame's
+If this option is @code{nil} (the default), a frame's text pixel size is
+usually rounded to a multiple of the current values of that frame's
@code{frame-char-height} and @code{frame-char-width} whenever the frame
is resized. If this is non-@code{nil}, no rounding occurs, hence frame
sizes can increase/decrease by one pixel.
@node Frame Interaction Parameters
@subsubsection Frame Interaction Parameters
+@cindex frame interaction parameters
+@cindex interaction parameters between frames
These parameters supply forms of interactions between different frames.
@vindex parent-frame, a frame parameter
@item parent-frame
If non-@code{nil}, this means that this frame is a child frame
-(@pxref{Child Frames}) and this parameter specifies its parent frame.
+(@pxref{Child Frames}), and this parameter specifies its parent frame.
If nil, this means that this frame is a normal, top-level frame.
@vindex delete-before, a frame parameter
If non-@code{nil}, this tells the window manager to remove the frame's
icon from the taskbar associated with the frame's display and inhibit
switching to the frame's window via the combination @kbd{Alt-@key{TAB}}.
-On Windows, iconifying such a frame will "roll in" its window-system
+On MS-Windows, iconifying such a frame will "roll in" its window-system
window at the bottom of the desktop. Some window managers may not honor
this parameter.
@vindex no-focus-on-map, a frame parameter
@item no-focus-on-map
-If non-@code{nil}, this means that the frame dos not want to receive
+If non-@code{nil}, this means that the frame does not want to receive
input focus when it is mapped (@pxref{Visibility of Frames}). Some
window managers may not honor this parameter.
@vindex undecorated, a frame parameter
@item undecorated
If non-@code{nil}, this frame's window-system window is drawn without
-decorations like title, minimize/maximize boxes and external borders.
-This usually means that the window cannot be dragged, resized,
+decorations, like the title, minimize/maximize boxes and external
+borders. This usually means that the window cannot be dragged, resized,
iconified, maximized or deleted with the mouse. If nil, the frame's
window is usually drawn with all the elements listed above unless their
display has been suspended via window manager settings.
It first deletes any child frame of @var{frame} (@pxref{Child Frames})
and any frame whose @code{delete-before} frame parameter (@pxref{Frame
Interaction Parameters}) specifies @var{frame}. All such deletions are
-performed recursively; so this step makes sure that there will not exist
-any other frames with @var{frame} as their ancestor. Then, unless
+performed recursively; so this step makes sure that there no other
+frames with @var{frame} as their ancestor will exist. Then, unless
@var{frame} specifies a tooltip, this function runs the hook
@code{delete-frame-functions} (each function getting one argument,
@var{frame}) before actually killing the frame.
the ``active'' window which should insist a bit more on avoiding to
raise @var{frame} above other frames.
-On Windows the @var{noactivate} argument has no effect. However, if
+On MS-Windows the @var{noactivate} argument has no effect. However, if
@var{frame} is a child frame (@pxref{Child Frames}), this function
usualy does focus @var{frame} without raising it above other child
frames.
frame that previously had focus retains focus as long as the mouse
pointer does not move into another window manager window) from
``strict'' focus (where a frame immediately loses focus when it's left
-by the mouse pointer). It neither recognizes whether your window
+by the mouse pointer). Neither does it recognize whether your window
manager supports delayed focusing or auto-raising where you can
explicitly specify the time until a new frame gets focus or is
auto-raised.
Lowering}).
Making a frame visible usually makes all its child frames (and their
-descendants) visible too (@pxref{Child Frames}).
+descendants) visible as well (@pxref{Child Frames}).
@end deffn
@deffn Command make-frame-invisible &optional frame force
@cindex restacking a frame
@cindex frame stacking order
@cindex frame Z-order
+@cindex Z-order
Most window systems use a desktop metaphor. Part of this metaphor is
the idea that system-level windows (representing, e.g., Emacs frames)
are stacked in a notional third dimension perpendicular to the screen
(@pxref{Layout Parameters}) can be used instead of the external borders.
In particular, under X (but not when building with GTK+), the frame's
-outer border can be used. On Windows, specifying a non-zero outer
-border width will show a one pixel wide external border. Under all
+outer border can be used. On MS-Windows, specifying a non-zero outer
+border width will show a one-pixel wide external border. Under all
window-systems, the internal border can be used. In either case, it's
advisable to disable a child frame's window manager decorations with the
@code{undecorated} frame parameter @pxref{Management Parameters}).
help in this regard (@pxref{Mouse Window Auto-selection}).
@item
-Dropping (@pxref{Drag and Drop}) on child frames is not guaranteed too
+Dropping (@pxref{Drag and Drop}) on child frames is not guaranteed to
work on all window-systems. Some will drop the object on the parent
-frame or some ancestor instead.
+frame or on some ancestor instead.
@end itemize
The following two functions may be useful when working with child and
projects / emacs.git / commitdiff