andros/emacs-gpu
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update docs for window dividers and `window-text-pixel-size'.

Browse source 
* xdisp.c (Fwindow_text_pixel_size): Adjust doc-string.
* elisp.texi (Top): Rename section "Width" to "Size of Displayed
Text".
* text.texi (Primitive Indent):
* strings.texi (String Basics):
* sequences.texi (Sequence Functions): Update references
accordingly.
* display.texi (Size of Displayed Text): Rename section from
"Width".  Add description for `window-text-pixel-size'.
(Window Dividers): Reword description of window dividers.
* frames.texi (Layout Parameters): Improve description of window
divider parameters.
* windows.texi (Window Sizes): Add descriptions of
`window-mode-line-height' and `window-header-line-height'.
(Coordinates and Windows): Mention window dividers.
This commit is contained in:
Martin Rudalics 2014-03-09 12:36:51 +01:00
parent e7db54476d
commit 7e940b6546
10 changed files with 184 additions and 52 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

17
doc/lispref/ChangeLog
View file

@ -1,3 +1,20 @@
2014-03-09 Martin Rudalics <rudalics@gmx.at>
* elisp.texi (Top): Rename section "Width" to "Size of Displayed
Text".
* text.texi (Primitive Indent):
* strings.texi (String Basics):
* sequences.texi (Sequence Functions): Update references
accordingly.
* display.texi (Size of Displayed Text): Rename section from
"Width". Add description for `window-text-pixel-size'.
(Window Dividers): Reword description of window dividers.
* frames.texi (Layout Parameters): Improve description of window
divider parameters.
* windows.texi (Window Sizes): Add descriptions of
`window-mode-line-height' and `window-header-line-height'.
(Coordinates and Windows): Mention window dividers.
2014-03-07 Martin Rudalics <rudalics@gmx.at>
* buffers.texi (The Buffer List): Rename node to Buffer List.

105
doc/lispref/display.texi
View file

@ -18,7 +18,7 @@ that Emacs presents to the user.
* Selective Display:: Hiding part of the buffer text (the old way).
* Temporary Displays:: Displays that go away automatically.
* Overlays:: Use overlays to highlight parts of the buffer.
* Width:: How wide a character or string is on the screen.
* Size of Displayed Text:: How large displayed text is.
* Line Height:: Controlling the height of lines.
* Faces:: A face defines a graphics style for text characters:
font, colors, etc.
@ -1765,8 +1765,8 @@ changes.
(point)))
@end smallexample
@node Width
@section Width
@node Size of Displayed Text
@section Size of Displayed Text
Since not all characters have the same width, these functions let you
check the width of a character. @xref{Primitive Indent}, and
@ -1823,6 +1823,54 @@ to or less than the display width of @var{ellipsis}. If
@end example
@end defun
The following function returns the size in pixels of text as if it were
displayed in a given window. This function is used by
@code{fit-window-to-buffer} (@pxref{Resizing Windows}) and
@code{fit-frame-to-buffer} (@pxref{Size and Position}) to make a window
exactly as large as the text it contains.
@defun window-text-pixel-size &optional window from to x-limit y-limit mode-and-header-line
This function returns the size of the text of @var{window}'s buffer in
pixels. @var{window} must be a live window and defaults to the selected
one. The return value is a cons of the maximum pixel-width of any text
line and the maximum pixel-height of all text lines.
The optional argument @var{from}, if non-@code{nil}, specifies the first
text position to consider and defaults to the minimum accessible
position of the buffer. If @var{from} is @code{t}, it uses the minimum
accessible position that is not a newline character. The optional
argument @var{to}, if non-@code{nil}, specifies the last text position
to consider and defaults to the maximum accessible position of the
buffer. If @var{to} is @code{t}, it uses the maximum accessible
position that is not a newline character.
The optional argument @var{x-limit}, if non-@code{nil}, specifies the
maximum pixel-width that can be returned. @var{x-limit} @code{nil} or
omitted, means to use the pixel-width of @var{window}'s body
(@pxref{Window Sizes}); this is useful when the caller does not intend
to change the width of @var{window}. Otherwise, the caller should
specify here the maximum width @var{window}'s body may assume. Text
whose x-coordinate is beyond @var{x-limit} is ignored. Since
calculating the width of long lines can take some time, it's always a
good idea to make this argument as small as needed; in particular, if
the buffer might contain long lines that will be truncated anyway.
The optional argument @var{y-limit}, if non-@code{nil}, specifies the
maximum pixel-height that can be returned. Text lines whose
y-coordinate is beyond @var{y-limit} are ignored. Since calculating the
pixel-height of a large buffer can take some time, it makes sense to
specify this argument; in particular, if the caller does not know the
size of the buffer.
The optional argument @var{mode-and-header-line} @code{nil} or omitted
means to not include the height of the mode- or header-line of
@var{window} in the return value. If it is either the symbol
@code{mode-line} or @code{header-line}, include only the height of that
line, if present, in the return value. If it is @code{t}, include the
height of both, if present, in the return value.
@end defun
@node Line Height
@section Line Height
@cindex line height
@ -3904,28 +3952,28 @@ to use the value specified by the frame.
@cindex bottom dividers
Window dividers are bars drawn between a frame's windows. A ``right''
divider is drawn between a window and its sibling(s) on the right. Its
width is specified by the frame parameter @code{right-divider-width}. A
``bottom'' divider is drawn between a window and its sibling(s) on the
bottom or the echo area. Its width is specified by the frame parameter
@code{bottom-divider-width}. In either case, specifying a width of zero
means to not draw such dividers. @xref{Layout Parameters}.
divider is drawn between a window and any adjacent windows on the right.
Its width (thickness) is specified by the frame parameter
@code{right-divider-width}. A ``bottom'' divider is drawn between a
window and adjacent windows on the bottom or the echo area. Its width
is specified by the frame parameter @code{bottom-divider-width}. In
either case, specifying a width of zero means to not draw such dividers.
@xref{Layout Parameters}.
Technically, a right divider ``belongs'' to the window on its left,
which means that its width is part of the total width of that window. A
bottom divider ``belongs'' to the window above it, which means that its
height is part of the total height of that window. @xref{Window Sizes}.
When a window has both, a right and a bottom divider, the bottom divider
``prevails''. This means that the width of the bottom divider equals
the total width of the window while the height of the right divider
equals the total height of the window minus the height of the bottom
divider.
which means that its width contributes to the total width of that
window. A bottom divider ``belongs'' to the window above it, which
means that its width contributes to the total height of that window.
@xref{Window Sizes}. When a window has both, a right and a bottom
divider, the bottom divider ``prevails''. This means that a bottom
divider is drawn over the full total width of its window while the right
divider ends above the bottom divider.
Dividers can be dragged with the mouse and are therefore useful for
adjusting the sizes of adjacent windows with the mouse. They also serve
to set windows visually apart from their siblings when no scroll bars or
mode lines are present. The following three faces allow to customize
the appearance of dividers:
to visually set apart adjacent windows when no scroll bars or mode lines
are present. The following three faces allow to customize the
appearance of dividers:
@table @code
@item window-divider
@ -3944,6 +3992,23 @@ least three pixels wide. To obtain a solid appearance, set this to the
same value used for the @code{window-divider} face.
@end table
You can get the sizes of the dividers of a specific window with the
following two functions.
@defun window-right-divider-width &optional window
Return the width (thickness) in pixels of @var{window}'s right divider.
@var{window} must be a live window and defaults to the selected one.
The return value is always zero for a rightmost window.
@end defun
@defun window-bottom-divider-width &optional window
Return the width (thickness) in pixels of @var{window}'s bottom divider.
@var{window} must be a live window and defaults to the selected one.
The return value is zero for the minibuffer window or a bottommost
window on a minibuffer-less frame.
@end defun
@node Display Property
@section The @code{display} Property
@cindex display specification

2
doc/lispref/elisp.texi
View file

@ -1338,7 +1338,7 @@ Emacs Display
* Selective Display:: Hiding part of the buffer text (the old way).
* Temporary Displays:: Displays that go away automatically.
* Overlays:: Use overlays to highlight parts of the buffer.
* Width:: How wide a character or string is on the screen.
* Size of Displayed Text:: How large displayed text is.
* Line Height:: Controlling the height of lines.
* Faces:: A face defines a graphics style
for text characters: font, colors, etc.

12
doc/lispref/frames.texi
View file

@ -747,15 +747,15 @@ widths are negative, only the left fringe gets the specified width.
@vindex right-divider-width, a frame parameter
@item right-divider-width
The width of the right divider (@pxref{Window Dividers}) of any window
on the frame, in pixels. A value of zero means to not draw right
dividers.
The width (thickness) reserved for the right divider (@pxref{Window
Dividers}) of any window on the frame, in pixels. A value of zero means
to not draw right dividers.
@vindex bottom-divider-width, a frame parameter
@item bottom-divider-width
The width of the bottom divider (@pxref{Window Dividers}) of any window
on the frame, in pixels. A value of zero means to not draw bottom
dividers.
The width (thickness) reserved for the bottom divider (@pxref{Window
Dividers}) of any window on the frame, in pixels. A value of zero means
to not draw bottom dividers.
@vindex menu-bar-lines frame parameter
@item menu-bar-lines

6
doc/lispref/sequences.texi
View file

@ -107,9 +107,9 @@ Emacs character code.
@noindent
See also @code{string-bytes}, in @ref{Text Representations}.
If you need to compute the width of a string on display, you should
use @code{string-width} (@pxref{Width}), not @code{length}, since
@code{length} only counts the number of characters, but does not
If you need to compute the width of a string on display, you should use
@code{string-width} (@pxref{Size of Displayed Text}), not @code{length},
since @code{length} only counts the number of characters, but does not
account for the display width of each character.
@defun elt sequence index

14
doc/lispref/strings.texi
View file

@ -48,13 +48,13 @@ Vectors}). Unlike in C, Emacs Lisp strings are @emph{not} terminated
by a distinguished character code.
Since strings are arrays, and therefore sequences as well, you can
operate on them with the general array and sequence functions
documented in @ref{Sequences Arrays Vectors}. For example, you can
access or change individual characters in a string using the functions
@code{aref} and @code{aset} (@pxref{Array Functions}). However, note
that @code{length} should @emph{not} be used for computing the width
of a string on display; use @code{string-width} (@pxref{Width})
instead.
operate on them with the general array and sequence functions documented
in @ref{Sequences Arrays Vectors}. For example, you can access or
change individual characters in a string using the functions @code{aref}
and @code{aset} (@pxref{Array Functions}). However, note that
@code{length} should @emph{not} be used for computing the width of a
string on display; use @code{string-width} (@pxref{Size of Displayed
Text}) instead.
There are two text representations for non-@acronym{ASCII}
characters in Emacs strings (and in buffers): unibyte and multibyte.

2
doc/lispref/text.texi
View file

@ -2202,7 +2202,7 @@ count from zero at the left margin.
This section describes the primitive functions used to count and
insert indentation. The functions in the following sections use these
primitives. @xref{Width}, for related functions.
primitives. @xref{Size of Displayed Text}, for related functions.
@defun current-indentation
@comment !!Type Primitive Function

54
doc/lispref/windows.texi
View file

@ -618,6 +618,29 @@ argument @var{pixelwise} is passed to the function called.
@code{window-width} is an alias for @code{window-body-width}. These
aliases are considered obsolete and will be removed in the future.
The pixel heights of a window's mode and header line can be retrieved
with the functions given below. Their return value is usually accurate
unless the window has not been displayed before: In that case, the
return value is based on an estimate of the font used for the window's
frame.
@defun window-mode-line-height &optional window
This function returns the height in pixels of @var{window}'s mode line.
@var{window} must be a live window and defaults to the selected one. If
@var{window} has no mode line, the return value is zero.
@end defun
@defun window-header-line-height &optional window
This function returns the height in pixels of @var{window}'s header
line. @var{window} must be a live window and defaults to the selected
one. If @var{window} has no header line, the return value is zero.
@end defun
Functions for retrieving the height and/or width of window dividers
(@pxref{Window Dividers}), fringes (@pxref{Fringes}), scroll bars
(@pxref{Scroll Bars}), and display margins (@pxref{Display Margins}) are
described in the corresponding sections.
@cindex fixed-size window
@vindex window-min-height
@vindex window-min-width
@ -3476,18 +3499,18 @@ coordinate of the topmost row, the X coordinate one column to the
right of the rightmost column, and the Y coordinate one row down from
the bottommost row.
Note that these are the actual outer edges of the window, including
any header line, mode line, scroll bar, fringes, and display margins.
On a text terminal, if the window has a neighbor on its right, its
right edge includes the separator line between the window and its
Note that these are the actual outer edges of the window, including any
header line, mode line, scroll bar, fringes, window divider and display
margins. On a text terminal, if the window has a neighbor on its right,
its right edge includes the separator line between the window and its
neighbor.
@end defun
@defun window-inside-edges &optional window
This function is similar to @code{window-edges}, but the returned edge
values are for the text area of the window. They exclude any header
line, mode line, scroll bar, fringes, display margins, and vertical
separator.
line, mode line, scroll bar, fringes, window divider, display margins,
and vertical separator.
@end defun
@defun window-top-line &optional window
@ -3536,6 +3559,14 @@ The coordinates are in the mode line of @var{window}.
@item header-line
The coordinates are in the header line of @var{window}.
@item right-divider
The coordinates are in the divider separating @var{window} from a
window on the right.
@item right-divider
The coordinates are in the divider separating @var{window} from a
window beneath.
@item vertical-line
The coordinates are in the vertical line between @var{window} and its
neighbor to the right. This value occurs only if the window doesn't
@ -3597,6 +3628,17 @@ returns the edge pixel coordinates relative to the top left corner of
the display screen. @var{window} must specify a live window.
@end defun
@defun window-pixel-left &optional window
This function returns the left pixel edge of window @var{window}.
@var{window} must be a valid window and defaults to the selected one.
@end defun
@defun window-pixel-top &optional window
This function returns the top pixel edge of window @var{window}.
@var{window} must be a valid window and defaults to the selected one.
@end defun
@node Window Configurations
@section Window Configurations
@cindex window configurations

8
src/ChangeLog
View file

@ -1,9 +1,13 @@
2014-03-09 Martin Rudalics <rudalics@gmx.at>
* xdisp.c (Fwindow_text_pixel_size): Adjust doc-string.
2014-03-08 Jan Djärv <jan.h.d@swipnet.se>
* nsterm.h (MAC_OS_X_VERSION_10_9): Add.
* nsterm.m (constrainFrameRect:toScreen:): Constrain normally when frame
is only on one screen (Bug#14713).
* nsterm.m (constrainFrameRect:toScreen:): Constrain normally
when frame is only on one screen (Bug#14713).
2014-03-08 Eli Zaretskii <eliz@gnu.org>

16
src/xdisp.c
View file

@ -9600,19 +9600,23 @@ character. TO, if non-nil, specifies the last text position and
defaults to the maximum accessible position of the buffer. If TO is t,
use the maximum accessible position that is not a newline character.
The optional argument X_LIMIT, if non-nil, specifies the maximum text
width that can be returned. X_LIMIT nil or omitted, means to use the
The optional argument X-LIMIT, if non-nil, specifies the maximum text
width that can be returned. X-LIMIT nil or omitted, means to use the
pixel-width of WINDOW's body; use this if you do not intend to change
the width of WINDOW. Use the maximum width WINDOW may assume if you
intend to change WINDOW's width.
intend to change WINDOW's width. In any case, text whose x-coordinate
is beyond X-LIMIT is ignored. Since calculating the width of long lines
can take some time, it's always a good idea to make this argument as
small as possible; in particular, if the buffer contains long lines that
shall be truncated anyway.
The optional argument Y_LIMIT, if non-nil, specifies the maximum text
The optional argument Y-LIMIT, if non-nil, specifies the maximum text
height that can be returned. Text lines whose y-coordinate is beyond
Y_LIMIT are ignored. Since calculating the text height of a large
Y-LIMIT are ignored. Since calculating the text height of a large
buffer can take some time, it makes sense to specify this argument if
the size of the buffer is unknown.
Optional argument MODE_AND_HEADER_LINE nil or omitted means do not
Optional argument MODE-AND-HEADER-LINE nil or omitted means do not
include the height of the mode- or header-line of WINDOW in the return
value. If it is either the symbol `mode-line' or `header-line', include
only the height of that line, if present, in the return value. If t,