emacs-diffs
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Emacs-diffs] trunk r118176: Rewrite "Size and Position" section in fram


From: Martin Rudalics
Subject: [Emacs-diffs] trunk r118176: Rewrite "Size and Position" section in frames.texi.
Date: Wed, 22 Oct 2014 09:57:29 +0000
User-agent: Bazaar (2.6b2)

------------------------------------------------------------
revno: 118176
revision-id: address@hidden
parent: address@hidden
committer: martin rudalics <address@hidden>
branch nick: trunk
timestamp: Wed 2014-10-22 11:57:17 +0200
message:
  Rewrite "Size and Position" section in frames.texi.
  
  * frames.texi (Size Parameters): Replace "frame contents" by
  "frame's text area".  Add reference to Size and Position
  section.
  (Size and Position): Major rewrite.  Add explanations for
  frame's default font, text and display areas.  Add descriptions
  for `set-frame-font', `frame-text-height', `frame-text-width'
  and `frame-inhibit-implied-resize'.
modified:
  doc/lispref/ChangeLog          changelog-20091113204419-o5vbwnq5f7feedwu-6155
  doc/lispref/frames.texi        
frames.texi-20091113204419-o5vbwnq5f7feedwu-6180
=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2014-10-20 19:59:41 +0000
+++ b/doc/lispref/ChangeLog     2014-10-22 09:57:17 +0000
@@ -1,3 +1,13 @@
+2014-10-22  Martin Rudalics  <address@hidden>
+
+       * frames.texi (Size Parameters): Replace "frame contents" by
+       "frame's text area".  Add reference to Size and Position
+       section.
+       (Size and Position): Major rewrite.  Add explanations for
+       frame's default font, text and display areas.  Add descriptions
+       for `set-frame-font', `frame-text-height', `frame-text-width'
+       and `frame-inhibit-implied-resize'.
+
 2014-10-20  Glenn Morris  <address@hidden>
 
        * Merge in all changes up to 24.4 release.

=== modified file 'doc/lispref/frames.texi'
--- a/doc/lispref/frames.texi   2014-10-09 04:23:09 +0000
+++ b/doc/lispref/frames.texi   2014-10-22 09:57:17 +0000
@@ -709,13 +709,13 @@
 @table @code
 @vindex height, a frame parameter
 @item height
-The height of the frame contents, in characters.  (To get the height in
-pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.)
+The height of the frame's text area (@pxref{Size and Position}), in
+characters.
 
 @vindex width, a frame parameter
 @item width
-The width of the frame contents, in characters.  (To get the width in
-pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
+The width of the frame's text area (@pxref{Size and Position}), in
+characters.
 
 @vindex user-size, a frame parameter
 @item user-size
@@ -739,9 +739,9 @@
 does not allow resizing by mouse dragging.
 
 With some window managers you may have to customize the variable
address@hidden to a address@hidden value in order to make
-a frame appear ``maximized'' or ``fullscreen''.
-
address@hidden (@pxref{Size and Position}) to a
address@hidden value in order to make a frame appear ``maximized'' or
+``fullscreen''.
 @end table
 
 @node Layout Parameters
@@ -1136,65 +1136,137 @@
 @code{scroll-bar} face.
 @end table
 
+
 @node Size and Position
address@hidden Frame Size And Position
address@hidden Frame Size and Position
 @cindex size of frame
 @cindex screen size
 @cindex frame size
 @cindex resize frame
 
-  You can read or change the size and position of a frame using the
-frame parameters @code{left}, @code{top}, @code{height}, and
address@hidden  Whatever geometry parameters you don't specify are chosen
-by the window manager in its usual fashion.
+You can read or change the size and position of a frame using the frame
+parameters @code{left}, @code{top}, @code{height}, and @code{width}.
+Whatever geometry parameters you don't specify are chosen by the window
+manager in its usual fashion.
 
   Here are some special features for working with sizes and positions.
-(For the precise meaning of ``selected frame'' used by these functions,
-see @ref{Input Focus}.)
+Most of the functions described below use a @var{frame} argument which
+has to specify a live frame.  If omitted or @code{nil}, it specifies the
+selected frame, see @ref{Input Focus}.
 
 @defun set-frame-position frame left top
 This function sets the position of the top left corner of @var{frame} to
 @var{left} and @var{top}.  These arguments are measured in pixels, and
-normally count from the top left corner of the screen.
-
-Negative parameter values position the bottom edge of the window up from
-the bottom edge of the screen, or the right window edge to the left of
-the right edge of the screen.  It would probably be better if the values
-were always counted from the left and top, so that negative arguments
-would position the frame partly off the top or left edge of the screen,
-but it seems inadvisable to change that now.
+normally count from the top left corner of the screen to the top left
+corner of the rectangle allotted to the frame by the window manager.
+
+Negative parameter values position the bottom edge of that rectangle up
+from the bottom edge of the screen, or the right rectangle edge to the
+left of the right edge of the screen.  It would probably be better if
+the values were always counted from the left and top, so that negative
+arguments would position the frame partly off the top or left edge of
+the screen, but it seems inadvisable to change that now.
address@hidden defun
+
address@hidden frame default font
address@hidden default font of a frame
+Each frame has a @dfn{default font} which specifies the canonical height
+and width of a character on that frame.  The default font is used when
+retrieving or changing the size of a frame in terms of columns or lines.
+It is also used when resizing (@pxref{Window Sizes}) or splitting
+(@pxref{Splitting Windows}) windows.
+
address@hidden frame-char-height &optional frame
address@hidden frame-char-width &optional frame
+These functions return the canonical height and width of a character in
address@hidden, measured in pixels.  Together, these values establish the
+size of the default font on @var{frame}.  The values depend on the
+choice of font for @var{frame}, see @ref{Font and Color Parameters}.
address@hidden defun                                                            
          
+
+The default font can be also set directly with the following function:
+
address@hidden Command set-frame-font font &optional keep-size frames
+This sets the default font to @var{font}.  When called interactively, it
+prompts for the name of a font, and uses that font on the selected
+frame.  When called from Lisp, @var{font} should be a font name (a
+string), a font object, font entity, or a font spec.
+
+If the optional argument @var{keep-size} is @code{nil}, this keeps the
+number of frame lines and columns fixed.  (If address@hidden, the option
address@hidden described below will override this.)
+If @var{keep-size} is address@hidden (or with a prefix argument), it
+tries to keep the size of the display area of the current frame fixed by
+adjusting the number of lines and columns.
+
+If the optional argument @var{frames} is @code{nil}, this applies the
+font to the selected frame only.  If @var{frames} is address@hidden, it
+should be a list of frames to act upon, or @code{t} meaning all existing
+graphical frames.
address@hidden deffn
+
address@hidden frame display area
address@hidden display area of a frame
+The @dfn{display area} of a frame is a rectangular area within the area
+allotted to the frame by the window manager.  The display area neither
+includes the title bar (@pxref{Frame Titles}) nor any other decorations
+provided by the window manager (like an external border used for
+resizing frames via mouse dragging).
+
+   The actual height of the display area depends on the window-system
+and toolkit in use.  With GTK+, the display area does not include any
+tool bar or menu bar.  With the Motif or Lucid toolkits and with
+Windows, the display area includes the tool bar but not the menu bar.
+In a graphical version with no toolkit, it includes both the tool bar
+and menu bar.  On a text terminal, the display area includes the menu
+bar.
+
address@hidden frame-pixel-height &optional frame
address@hidden frame-pixel-width &optional frame
+   These functions return the height and width of the display area of
address@hidden, measured in pixels.  For a text terminal, the results are
+in characters rather than pixels.
address@hidden defun
+
address@hidden frame text area
address@hidden text area of a frame
+   The @dfn{text area} of a frame is a concept implicitly used by all
+functions that change a frame's height or width.  It is a rectangle
+located within the display area.  Its size is obtained from that of the
+display area by subtracting the sizes of any tool or menu bars that are
+part of the display area, any internal borders, one vertical and one
+horizontal scroll bar, and one left and one right fringe as specified
+for this frame, see @ref{Layout Parameters}.
+
address@hidden frame-text-height &optional frame
address@hidden frame-text-width &optional frame
+These functions return the height and width of the text area of
address@hidden, measured in pixels.  For a text terminal, the results are
+in characters rather than pixels.
+
+The value returned by @code{frame-text-height} differs from that
+returned by @code{frame-pixel-height} by not including the heights of
+any tool bar or menu bar, the height of one horizontal scroll bar and
+the widths of the internal border.
+
+The value returned by @code{frame-text-width} differs from that returned
+by @code{frame-pixel-width} by not including the width of one vertical
+scroll bar, the widths of one left and one right fringe and the widths
+of the internal border.
 @end defun
 
 @defun frame-height &optional frame
 @defunx frame-width &optional frame
-These functions return the height and width of @var{frame}, measured in
-lines and columns.  If you don't supply @var{frame}, they use the
-selected frame.
address@hidden defun
-
address@hidden frame-pixel-height &optional frame
address@hidden frame-pixel-width &optional frame
-These functions return the height and width of the main display area
-of @var{frame}, measured in pixels.  If you don't supply @var{frame},
-they use the selected frame.  For a text terminal, the results are in
-characters rather than pixels.
-
-These values include the internal borders, and windows' scroll bars
-and fringes (which belong to individual windows, not to the frame
-itself).  The exact value of the heights depends on the window-system
-and toolkit in use.  With GTK+, the height does not include any tool
-bar or menu bar.  With the Motif or Lucid toolkits, it includes the
-tool bar but not the menu bar.  In a graphical version with no
-toolkit, it includes both the tool bar and menu bar.  For a text
-terminal, the result includes the menu bar.
address@hidden defun
-
address@hidden frame-char-height &optional frame
address@hidden frame-char-width &optional frame
-These functions return the height and width of a character in
address@hidden, measured in pixels.  The values depend on the choice of
-font.  If you don't supply @var{frame}, these functions use the selected
-frame.
+These functions return the height and width of the text area of
address@hidden, measured in units of the default font height and width of
address@hidden  These functions are plain shorthands for writing
address@hidden(frame-parameter frame 'height)} and @code{(frame-parameter frame
+'width)}.
+
+If the text area of @var{frame} measured in pixles is not a multiple of
+its default font size, the values returned by this functions are rounded
+down to the number of characters of the default font that fully fit into
+the text area.
 @end defun
 
 @defopt frame-resize-pixelwise
@@ -1220,9 +1292,9 @@
 @end defopt
 
 @defun set-frame-size frame width height pixelwise
-This function sets the size of @var{frame}, measured in characters;
address@hidden and @var{height} specify the new width in columns and the
-new height in lines.
+This function sets the size of the text area of @var{frame}, measured in
+characters; @var{width} and @var{height} specify the new width in
+columns and the new height in lines.
 
 The optional argument @var{pixelwise} address@hidden means to measure
 the new width and height in units of pixels instead.  Note that if
@@ -1232,9 +1304,9 @@
 @end defun
 
 @defun set-frame-height frame height &optional pretend pixelwise
-This function resizes @var{frame} to a height of @var{height} lines.  The
-sizes of existing windows in @var{frame} are altered proportionally to
-fit.
+This function resizes the text area of @var{frame} to a height of
address@hidden lines.  The sizes of existing windows in @var{frame} are
+altered proportionally to fit.
 
 If @var{pretend} is address@hidden, then Emacs displays @var{height}
 lines of output in @var{frame}, but does not change its value for the
@@ -1254,8 +1326,8 @@
 @end defun
 
 @defun set-frame-width frame width &optional pretend pixelwise
-This function sets the width of @var{frame}, measured in characters.
-The argument @var{pretend} has the same meaning as in
+This function sets the width of the text area of @var{frame}, measured
+in characters.  The argument @var{pretend} has the same meaning as in
 @code{set-frame-height}.
 
 The optional fourth argument @var{pixelwise} address@hidden means that
@@ -1265,6 +1337,41 @@
 to a multiple of its character width.
 @end defun
 
+None of these three functions will make a frame smaller than needed to
+display all of its windows together with their scroll bars, fringes,
+margins, dividers, mode and header lines.  This contrasts with requests
+by the window manager triggered, for example, by dragging the external
+border of a frame with the mouse.  Such requests are always honored by
+clipping, if necessary, portions that cannot be displayed at the right,
+bottom corner of the frame.
+
+   By default, Emacs tries to keep the number of lines and columns of a
+frame's text area unaltered when, for example, adding or removing a menu
+bar, changing the default font or setting the width of the frame's
+scroll bars.  This means, however, that in such case Emacs must ask the
+window manager to resize the display area of the frame in order to
+accommodate the size change.  (Note that with the exception of GTK+
+builds, adding, removing or wrapping the tool bar usually do not resize
+the frame's display area, hence these may alter the number of displayed
+lines.)
+
+   Occasionally, such implied resizing of the display area may be
+unwanted, for example, when the frame is maximized or made fullscreen
+where it's turned off by default.  In other cases you can disable
+implied resizing with the following option:
+
address@hidden frame-inhibit-implied-resize
+If this option is @code{nil}, changing default font, menu bar mode,
+fringe width, or scroll bars of a specific frame may resize the frame's
+display area in order to preserve the number of columns or lines the
+frame displays.  If this option is address@hidden, no such resizing is
+done.
+
+When you add a tool bar or scroll bar to a frame that is not large
+enough to accommodate one, Emacs will try to enlarge the frame even if
+this option is address@hidden
address@hidden defopt
+
 @c FIXME?  Belongs more in Emacs manual than here?
 @c But, e.g., fit-window-to-buffer is in this manual.
 If you have a frame that displays only one window, you can fit that


reply via email to

[Prev in Thread] Current Thread [Next in Thread]