forked from emacs-mirror/emacs
-
Notifications
You must be signed in to change notification settings - Fork 0
/
windows.texi
6542 lines (5496 loc) · 279 KB
/
windows.texi
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990--1995, 1998--1999, 2001--2021 Free Software
@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Windows
@chapter Windows
This chapter describes the functions and variables related to Emacs
windows. @xref{Frames}, for how windows are assigned an area of screen
available for Emacs to use. @xref{Display}, for information on how text
is displayed in windows.
@menu
* Basic Windows:: Basic information on using windows.
* Windows and Frames:: Relating windows to the frame they appear on.
* Window Sizes:: Accessing a window's size.
* Resizing Windows:: Changing the sizes of windows.
* Preserving Window Sizes:: Preserving the size of windows.
* Splitting Windows:: Creating a new window.
* Deleting Windows:: Removing a window from its frame.
* Recombining Windows:: Preserving the frame layout when splitting and
deleting windows.
* Selecting Windows:: The selected window is the one that you edit in.
* Cyclic Window Ordering:: Moving around the existing windows.
* Buffers and Windows:: Each window displays the contents of a buffer.
* Switching Buffers:: Higher-level functions for switching to a buffer.
* Displaying Buffers:: Displaying a buffer in a suitable window.
* Window History:: Each window remembers the buffers displayed in it.
* Dedicated Windows:: How to avoid displaying another buffer in
a specific window.
* Quitting Windows:: How to restore the state prior to displaying a
buffer.
* Side Windows:: Special windows on a frame's sides.
* Atomic Windows:: Preserving parts of the window layout.
* Window Point:: Each window has its own location of point.
* Window Start and End:: Buffer positions indicating which text is
on-screen in a window.
* Textual Scrolling:: Moving text up and down through the window.
* Vertical Scrolling:: Moving the contents up and down on the window.
* Horizontal Scrolling:: Moving the contents sideways on the window.
* Coordinates and Windows:: Converting coordinates to windows.
* Mouse Window Auto-selection:: Automatically selecting windows with the mouse.
* Window Configurations:: Saving and restoring the state of the screen.
* Window Parameters:: Associating additional information with windows.
* Window Hooks:: Hooks for scrolling, window size changes,
redisplay going past a certain point,
or window configuration changes.
@end menu
@node Basic Windows
@section Basic Concepts of Emacs Windows
@cindex window
A @dfn{window} is an area of the screen that is used to display a buffer
(@pxref{Buffers}). In Emacs Lisp, windows are represented by a special
Lisp object type.
@cindex multiple windows
Windows are grouped into frames (@pxref{Frames}). Each frame
contains at least one window; the user can subdivide it into multiple,
non-overlapping windows to view several buffers at once. Lisp
programs can use multiple windows for a variety of purposes. In
Rmail, for example, you can view a summary of message titles in one
window, and the contents of the selected message in another window.
@cindex terminal screen
@cindex screen of terminal
Emacs uses the word ``window'' with a different meaning than in
graphical desktop environments and window systems, such as the X
Window System. When Emacs is run on X, each of its graphical X
windows is an Emacs frame (containing one or more Emacs windows).
When Emacs is run on a text terminal, the frame fills the entire
terminal screen.
@cindex tiled windows
Unlike X windows, Emacs windows are @dfn{tiled}; they never overlap
within the area of the frame. When a window is created, resized, or
deleted, the change in window space is taken from or given to the
adjacent windows, so that the total area of the frame is unchanged.
@defun windowp object
This function returns @code{t} if @var{object} is a window (whether or
not it displays a buffer). Otherwise, it returns @code{nil}.
@end defun
@cindex live windows
A @dfn{live window} is one that is actually displaying a buffer in a
frame.
@defun window-live-p object
This function returns @code{t} if @var{object} is a live window and
@code{nil} otherwise. A live window is one that displays a buffer.
@end defun
@cindex internal windows
The windows in each frame are organized into a @dfn{window tree}.
@xref{Windows and Frames}. The leaf nodes of each window tree are live
windows---the ones actually displaying buffers. The internal nodes of
the window tree are @dfn{internal windows}, which are not live.
@cindex valid windows
A @dfn{valid window} is one that is either live or internal. A valid
window can be @dfn{deleted}, i.e., removed from its frame
(@pxref{Deleting Windows}); then it is no longer valid, but the Lisp
object representing it might be still referenced from other Lisp
objects. A deleted window may be made valid again by restoring a saved
window configuration (@pxref{Window Configurations}).
You can distinguish valid windows from deleted windows with
@code{window-valid-p}.
@defun window-valid-p object
This function returns @code{t} if @var{object} is a live window, or an
internal window in a window tree. Otherwise, it returns @code{nil},
including for the case where @var{object} is a deleted window.
@end defun
@cindex selected window
@cindex window selected within a frame
In each frame, at any time, exactly one Emacs window is designated
as @dfn{selected within the frame}. For the selected frame, that
window is called the @dfn{selected window}---the one in which most
editing takes place, and in which the cursor for selected windows
appears (@pxref{Cursor Parameters}). Keyboard input that inserts or
deletes text is also normally directed to this window. The selected
window's buffer is usually also the current buffer, except when
@code{set-buffer} has been used (@pxref{Current Buffer}). As for
non-selected frames, the window selected within the frame becomes the
selected window if the frame is ever selected. @xref{Selecting
Windows}.
@defun selected-window
This function returns the selected window (which is always a live
window).
@end defun
@anchor{Window Group}Sometimes several windows collectively and
cooperatively display a buffer, for example, under the management of
Follow Mode (@pxref{Follow Mode,,, emacs}), where the windows together
display a bigger portion of the buffer than one window could alone.
It is often useful to consider such a @dfn{window group} as a single
entity. Several functions such as @code{window-group-start}
(@pxref{Window Start and End}) allow you to do this by supplying, as
an argument, one of the windows as a stand in for the whole group.
@defun selected-window-group
@vindex selected-window-group-function
When the selected window is a member of a group of windows, this
function returns a list of the windows in the group, ordered such that
the first window in the list is displaying the earliest part of the
buffer, and so on. Otherwise the function returns a list containing
just the selected window.
The selected window is considered part of a group when the buffer
local variable @code{selected-window-group-function} is set to a
function. In this case, @code{selected-window-group} calls it with no
arguments and returns its result (which should be the list of windows
in the group).
@end defun
@node Windows and Frames
@section Windows and Frames
Each window belongs to exactly one frame (@pxref{Frames}).
@defun window-frame &optional window
This function returns the frame that the window @var{window} belongs
to. If @var{window} is @code{nil}, it defaults to the selected
window.
@end defun
@defun window-list &optional frame minibuffer window
This function returns a list of live windows belonging to the frame
@var{frame}. If @var{frame} is omitted or @code{nil}, it defaults to
the selected frame.
The optional argument @var{minibuffer} specifies whether to include
the minibuffer window in the returned list. If @var{minibuffer} is
@code{t}, the minibuffer window is included. If @var{minibuffer} is
@code{nil} or omitted, the minibuffer window is included only if it is
active. If @var{minibuffer} is neither @code{nil} nor @code{t}, the
minibuffer window is never included.
The optional argument @var{window}, if non-@code{nil}, should be a live
window on the specified frame; then @var{window} will be the first
element in the returned list. If @var{window} is omitted or @code{nil},
the window selected within the frame is the first element.
@end defun
@cindex window tree
@cindex root window
Windows in the same frame are organized into a @dfn{window tree},
whose leaf nodes are the live windows. The internal nodes of a window
tree are not live; they exist for the purpose of organizing the
relationships between live windows. The root node of a window tree is
called the @dfn{root window}. It can be either a live window (if the
frame has just one window), or an internal window.
A minibuffer window (@pxref{Minibuffer Windows}) that is not alone
on its frame does not have a parent window, so it strictly speaking is
not part of its frame's window tree. Nonetheless, it is a sibling
window of the frame's root window, and thus can be reached via
@code{window-next-sibling}. Also, the function @code{window-tree}
described at the end of this section lists the minibuffer window
alongside the actual window tree.
@defun frame-root-window &optional frame-or-window
This function returns the root window for @var{frame-or-window}. The
argument @var{frame-or-window} should be either a window or a frame;
if omitted or @code{nil}, it defaults to the selected frame. If
@var{frame-or-window} is a window, the return value is the root window
of that window's frame.
@end defun
@cindex parent window
@cindex child window
@cindex sibling window
When a window is split, there are two live windows where previously
there was one. One of these is represented by the same Lisp window
object as the original window, and the other is represented by a
newly-created Lisp window object. Both of these live windows become
leaf nodes of the window tree, as @dfn{child windows} of a single
internal window. If necessary, Emacs automatically creates this
internal window, which is also called the @dfn{parent window}, and
assigns it to the appropriate position in the window tree. A set of
windows that share the same parent are called @dfn{siblings}.
@cindex parent window
@defun window-parent &optional window
This function returns the parent window of @var{window}. If
@var{window} is omitted or @code{nil}, it defaults to the selected
window. The return value is @code{nil} if @var{window} has no parent
(i.e., it is a minibuffer window or the root window of its frame).
@end defun
Each internal window always has at least two child windows. If this
number falls to one as a result of window deletion, Emacs
automatically deletes the internal window, and its sole remaining
child window takes its place in the window tree.
Each child window can be either a live window, or an internal window
(which in turn would have its own child windows). Therefore, each
internal window can be thought of as occupying a certain rectangular
@dfn{screen area}---the union of the areas occupied by the live
windows that are ultimately descended from it.
@cindex window combination
@cindex vertical combination
@cindex horizontal combination
For each internal window, the screen areas of the immediate children
are arranged either vertically or horizontally (never both). If the
child windows are arranged one above the other, they are said to form
a @dfn{vertical combination}; if they are arranged side by side, they
are said to form a @dfn{horizontal combination}. Consider the
following example:
@smallexample
@group
______________________________________
| ______ ____________________________ |
|| || __________________________ ||
|| ||| |||
|| ||| |||
|| ||| |||
|| |||____________W4____________|||
|| || __________________________ ||
|| ||| |||
|| ||| |||
|| |||____________W5____________|||
||__W2__||_____________W3_____________ |
|__________________W1__________________|
@end group
@end smallexample
@noindent
The root window of this frame is an internal window, @var{W1}. Its
child windows form a horizontal combination, consisting of the live
window @var{W2} and the internal window @var{W3}. The child windows
of @var{W3} form a vertical combination, consisting of the live
windows @var{W4} and @var{W5}. Hence, the live windows in this
window tree are @var{W2}, @var{W4}, and @var{W5}.
The following functions can be used to retrieve a child window of an
internal window, and the siblings of a child window.
@defun window-top-child &optional window
This function returns the topmost child window of @var{window}, if
@var{window} is an internal window whose children form a vertical
combination. For any other type of window, the return value is
@code{nil}.
@end defun
@defun window-left-child &optional window
This function returns the leftmost child window of @var{window}, if
@var{window} is an internal window whose children form a horizontal
combination. For any other type of window, the return value is
@code{nil}.
@end defun
@defun window-child window
This function returns the first child window of the internal window
@var{window}---the topmost child window for a vertical combination, or
the leftmost child window for a horizontal combination. If
@var{window} is a live window, the return value is @code{nil}.
@end defun
@defun window-combined-p &optional window horizontal
This function returns a non-@code{nil} value if and only if
@var{window} is part of a vertical combination. If @var{window} is
omitted or @code{nil}, it defaults to the selected one.
If the optional argument @var{horizontal} is non-@code{nil}, this
means to return non-@code{nil} if and only if @var{window} is part of
a horizontal combination.
@end defun
@defun window-next-sibling &optional window
This function returns the next sibling of the window @var{window}. If
omitted or @code{nil}, @var{window} defaults to the selected window.
The return value is @code{nil} if @var{window} is the last child of
its parent.
@end defun
@defun window-prev-sibling &optional window
This function returns the previous sibling of the window @var{window}.
If omitted or @code{nil}, @var{window} defaults to the selected
window. The return value is @code{nil} if @var{window} is the first
child of its parent.
@end defun
The functions @code{window-next-sibling} and
@code{window-prev-sibling} should not be confused with the functions
@code{next-window} and @code{previous-window}, which return the next
and previous window, respectively, in the cyclic ordering of windows
(@pxref{Cyclic Window Ordering}).
The following functions can be useful to locate a window within its
frame.
@defun frame-first-window &optional frame-or-window
This function returns the live window at the upper left corner of the
frame specified by @var{frame-or-window}. The argument
@var{frame-or-window} must denote a window or a live frame and defaults
to the selected frame. If @var{frame-or-window} specifies a window,
this function returns the first window on that window's frame. Under
the assumption that the frame from our canonical example is selected
@code{(frame-first-window)} returns @var{W2}.
@end defun
@defun window-at-side-p &optional window side
This function returns @code{t} if @var{window} is located at
@var{side} of its containing frame. The argument @var{window} must be
a valid window and defaults to the selected one. The argument
@var{side} can be any of the symbols @code{left}, @code{top},
@code{right} or @code{bottom}. The default value @code{nil} is
handled like @code{bottom}.
Note that this function disregards the minibuffer window
(@pxref{Minibuffer Windows}). Hence, with @var{side} equal to
@code{bottom} it may return @code{t} also when the minibuffer window
appears right below @var{window}.
@end defun
@cindex window in direction
@defun window-in-direction direction &optional window ignore sign wrap minibuf
This function returns the nearest live window in direction
@var{direction} as seen from the position of @code{window-point} in
window @var{window}. The argument @var{direction} must be one of
@code{above}, @code{below}, @code{left} or @code{right}. The optional
argument @var{window} must denote a live window and defaults to the
selected one.
This function does not return a window whose @code{no-other-window}
parameter is non-@code{nil} (@pxref{Window Parameters}). If the nearest
window's @code{no-other-window} parameter is non-@code{nil}, this
function tries to find another window in the indicated direction whose
@code{no-other-window} parameter is @code{nil}. If the optional
argument @var{ignore} is non-@code{nil}, a window may be returned even
if its @code{no-other-window} parameter is non-@code{nil}.
If the optional argument @var{sign} is a negative number, it means to
use the right or bottom edge of @var{window} as reference position
instead of @code{window-point}. If @var{sign} is a positive number, it
means to use the left or top edge of @var{window} as reference position.
If the optional argument @var{wrap} is non-@code{nil}, this means to
wrap @var{direction} around frame borders. For example, if @var{window}
is at the top of the frame and @var{direction} is @code{above}, then
this function usually returns the frame's minibuffer window if it's
active and a window at the bottom of the frame otherwise.
If the optional argument @var{minibuf} is @code{t}, this function may
return the minibuffer window even when it's not active. If the
optional argument @var{minibuf} is @code{nil}, this means to return
the minibuffer window if and only if it is currently active.
If @var{minibuf} is neither @code{nil} nor @code{t}, this function
never returns the minibuffer window. However, if @var{wrap} is
non-@code{nil}, it always acts as if @var{minibuf} were @code{nil}.
If it doesn't find a suitable window, this function returns
@code{nil}.
Don't use this function to check whether there is @emph{no} window in
@var{direction}. Calling @code{window-at-side-p} described above is a
much more efficient way to do that.
@end defun
The following function allows the entire window tree of a frame to be
retrieved:
@defun window-tree &optional frame
This function returns a list representing the window tree for frame
@var{frame}. If @var{frame} is omitted or @code{nil}, it defaults to
the selected frame.
The return value is a list of the form @code{(@var{root} @var{mini})},
where @var{root} represents the window tree of the frame's root
window, and @var{mini} is the frame's minibuffer window.
If the root window is live, @var{root} is that window itself.
Otherwise, @var{root} is a list @code{(@var{dir} @var{edges} @var{w1}
@var{w2} ...)} where @var{dir} is @code{nil} for a horizontal
combination and @code{t} for a vertical combination, @var{edges} gives
the size and position of the combination, and the remaining elements
are the child windows. Each child window may again be a window object
(for a live window) or a list with the same format as above (for an
internal window). The @var{edges} element is a list @code{(@var{left}
@var{top} @var{right} @var{bottom})}, similar to the value returned by
@code{window-edges} (@pxref{Coordinates and Windows}).
@end defun
@node Window Sizes
@section Window Sizes
@cindex window size
@cindex size of window
The following schematic shows the structure of a live window:
@smallexample
@group
____________________________________________
|______________ Header Line ______________|RD| ^
^ |LS|LM|LF| |RF|RM|RS| | |
| | | | | | | | | | |
Window | | | | Text Area | | | | | Window
Body | | | | | (Window Body) | | | | | Total
Height | | | | | | | | | Height
| | | | |<- Window Body Width ->| | | | | |
v |__|__|__|_______________________|__|__|__| | |
|_________ Horizontal Scroll Bar _________| | |
|_______________ Mode Line _______________|__| |
|_____________ Bottom Divider _______________| v
<---------- Window Total Width ------------>
@end group
@end smallexample
@cindex window body
@cindex text area of a window
@cindex body of a window
At the center of the window is the @dfn{text area}, or @dfn{body},
where the buffer text is displayed. The text area can be surrounded by
a series of optional areas. On the left and right, from innermost to
outermost, these are the left and right fringes, denoted by LF and RF
(@pxref{Fringes}); the left and right margins, denoted by LM and RM in
the schematic (@pxref{Display Margins}); the left or right vertical
scroll bar, only one of which is present at any time, denoted by LS and
RS (@pxref{Scroll Bars}); and the right divider, denoted by RD
(@pxref{Window Dividers}). At the top of the window is the header line
(@pxref{Header Lines}). At the bottom of the window are the horizontal
scroll bar (@pxref{Scroll Bars}); the mode line (@pxref{Mode Line
Format}); and the bottom divider (@pxref{Window Dividers}).
Emacs provides miscellaneous functions for finding the height and
width of a window. The return value of many of these functions can be
specified either in units of pixels or in units of lines and columns.
On a graphical display, the latter actually correspond to the height and
width of a default character specified by the frame's default font
as returned by @code{frame-char-height} and @code{frame-char-width}
(@pxref{Frame Font}). Thus, if a window is displaying text with a
different font or size, the reported line height and column width for
that window may differ from the actual number of text lines or columns
displayed within it.
@cindex window height
@cindex height of a window
@cindex total height of a window
The @dfn{total height} of a window is the number of lines comprising
the window's body, the header line, the horizontal scroll bar, the mode
line and the bottom divider (if any).
@defun window-total-height &optional window round
This function returns the total height, in lines, of the window
@var{window}. If @var{window} is omitted or @code{nil}, it defaults to
the selected window. If @var{window} is an internal window, the return
value is the total height occupied by its descendant windows.
If a window's pixel height is not an integral multiple of its frame's
default character height, the number of lines occupied by the window is
rounded internally. This is done in a way such that, if the window is a
parent window, the sum of the total heights of all its child windows
internally equals the total height of their parent. This means that
although two windows have the same pixel height, their internal total
heights may differ by one line. This means also, that if window is
vertically combined and has a next sibling, the topmost row of that
sibling can be calculated as the sum of this window's topmost row and
total height (@pxref{Coordinates and Windows})
If the optional argument @var{round} is @code{ceiling}, this
function returns the smallest integer larger than @var{window}'s pixel
height divided by the character height of its frame; if it is
@code{floor}, it returns the largest integer smaller than said value;
with any other @var{round} it returns the internal value of
@var{windows}'s total height.
@end defun
@cindex window width
@cindex width of a window
@cindex total width of a window
The @dfn{total width} of a window is the number of lines comprising the
window's body, its margins, fringes, scroll bars and a right divider (if
any).
@defun window-total-width &optional window round
This function returns the total width, in columns, of the window
@var{window}. If @var{window} is omitted or @code{nil}, it defaults to
the selected window. If @var{window} is internal, the return value is
the total width occupied by its descendant windows.
If a window's pixel width is not an integral multiple of its frame's
character width, the number of lines occupied by the window is rounded
internally. This is done in a way such that, if the window is a parent
window, the sum of the total widths of all its children internally
equals the total width of their parent. This means that although two
windows have the same pixel width, their internal total widths may
differ by one column. This means also, that if this window is
horizontally combined and has a next sibling, the leftmost column of
that sibling can be calculated as the sum of this window's leftmost
column and total width (@pxref{Coordinates and Windows}). The optional
argument @var{round} behaves as it does for @code{window-total-height}.
@end defun
@defun window-total-size &optional window horizontal round
This function returns either the total height in lines or the total
width in columns of the window @var{window}. If @var{horizontal} is
omitted or @code{nil}, this is equivalent to calling
@code{window-total-height} for @var{window}; otherwise it is equivalent
to calling @code{window-total-width} for @var{window}. The optional
argument @var{round} behaves as it does for @code{window-total-height}.
@end defun
The following two functions can be used to return the total size of a
window in units of pixels.
@cindex window pixel height
@cindex pixel height of a window
@cindex total pixel height of a window
@defun window-pixel-height &optional window
This function returns the total height of window @var{window} in pixels.
@var{window} must be a valid window and defaults to the selected one.
The return value includes mode and header line, a horizontal scroll bar
and a bottom divider, if any. If @var{window} is an internal window,
its pixel height is the pixel height of the screen areas spanned by its
children.
@end defun
@cindex window pixel width
@cindex pixel width of a window
@cindex total pixel width of a window
@defun window-pixel-width &optional window
This function returns the width of window @var{window} in pixels.
@var{window} must be a valid window and defaults to the selected one.
The return value includes the fringes and margins of @var{window} as
well as any vertical dividers or scroll bars belonging to @var{window}.
If @var{window} is an internal window, its pixel width is the width of
the screen areas spanned by its children.
@end defun
@cindex full-width window
@cindex full-height window
The following functions can be used to determine whether a given
window has any adjacent windows.
@defun window-full-height-p &optional window
This function returns non-@code{nil} if @var{window} has no other window
above or below it in its frame. More precisely, this means that the
total height of @var{window} equals the total height of the root window
on that frame. The minibuffer window does not count in this regard. If
@var{window} is omitted or @code{nil}, it defaults to the selected
window.
@end defun
@defun window-full-width-p &optional window
This function returns non-@code{nil} if @var{window} has no other
window to the left or right in its frame, i.e., its total width equals
that of the root window on that frame. If @var{window} is omitted or
@code{nil}, it defaults to the selected window.
@end defun
@cindex window body height
@cindex body height of a window
The @dfn{body height} of a window is the height of its text area, which
does not include a mode or header line, a horizontal scroll bar, or a
bottom divider.
@defun window-body-height &optional window pixelwise
This function returns the height, in lines, of the body of window
@var{window}. If @var{window} is omitted or @code{nil}, it defaults to
the selected window; otherwise it must be a live window.
If the optional argument @var{pixelwise} is non-@code{nil}, this
function returns the body height of @var{window} counted in pixels.
If @var{pixelwise} is @code{nil}, the return value is rounded down to
the nearest integer, if necessary. This means that if a line at the
bottom of the text area is only partially visible, that line is not
counted. It also means that the height of a window's body can never
exceed its total height as returned by @code{window-total-height}.
@end defun
@cindex window body width
@cindex body width of a window
The @dfn{body width} of a window is the width of its text area, which
does not include the scroll bar, fringes, margins or a right divider.
Note that when one or both fringes are removed (by setting their width
to zero), the display engine reserves two character cells, one on each
side of the window, for displaying the continuation and truncation
glyphs, which leaves 2 columns less for text display. (The function
@code{window-max-chars-per-line}, described below, takes this
peculiarity into account.)
@defun window-body-width &optional window pixelwise
This function returns the width, in columns, of the body of window
@var{window}. If @var{window} is omitted or @code{nil}, it defaults to
the selected window; otherwise it must be a live window.
If the optional argument @var{pixelwise} is non-@code{nil}, this
function returns the body width of @var{window} in units of pixels.
If @var{pixelwise} is @code{nil}, the return value is rounded down to
the nearest integer, if necessary. This means that if a column on the
right of the text area is only partially visible, that column is not
counted. It also means that the width of a window's body can never
exceed its total width as returned by @code{window-total-width}.
@end defun
@cindex window body size
@cindex body size of a window
@defun window-body-size &optional window horizontal pixelwise
This function returns the body height or body width of @var{window}. If
@var{horizontal} is omitted or @code{nil}, it is equivalent to calling
@code{window-body-height} for @var{window}; otherwise it is equivalent
to calling @code{window-body-width}. In either case, the optional
argument @var{pixelwise} is passed to the function called.
@end defun
For compatibility with previous versions of Emacs,
@code{window-height} is an alias for @code{window-total-height}, and
@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.
If your Lisp program needs to make layout decisions, you will find the
following function useful:
@defun window-max-chars-per-line &optional window face
This function returns the number of characters displayed in the
specified face @var{face} in the specified window @var{window} (which
must be a live window). If @var{face} was remapped (@pxref{Face
Remapping}), the information is returned for the remapped face. If
omitted or @code{nil}, @var{face} defaults to the default face, and
@var{window} defaults to the selected window.
Unlike @code{window-body-width}, this function accounts for the actual
size of @var{face}'s font, instead of working in units of the canonical
character width of @var{window}'s frame (@pxref{Frame Font}). It also
accounts for space used by the continuation glyph, if @var{window} lacks
one or both of its fringes.
@end defun
@cindex fixed-size window
@vindex window-min-height
@vindex window-min-width
Commands that change the size of windows (@pxref{Resizing Windows}),
or split them (@pxref{Splitting Windows}), obey the variables
@code{window-min-height} and @code{window-min-width}, which specify the
smallest allowable window height and width. They also obey the variable
@code{window-size-fixed}, with which a window can be @dfn{fixed} in
size (@pxref{Preserving Window Sizes}).
@defopt window-min-height
This option specifies the minimum total height, in lines, of any window.
Its value has to accommodate at least one text line as well as a mode
and header line, a horizontal scroll bar and a bottom divider, if
present.
@end defopt
@defopt window-min-width
This option specifies the minimum total width, in columns, of any
window. Its value has to accommodate two text columns as well as
margins, fringes, a scroll bar and a right divider, if present.
@end defopt
The following function tells how small a specific window can get taking
into account the sizes of its areas and the values of
@code{window-min-height}, @code{window-min-width} and
@code{window-size-fixed} (@pxref{Preserving Window Sizes}).
@defun window-min-size &optional window horizontal ignore pixelwise
This function returns the minimum size of @var{window}. @var{window}
must be a valid window and defaults to the selected one. The optional
argument @var{horizontal} non-@code{nil} means to return the minimum
number of columns of @var{window}; otherwise return the minimum number
of @var{window}'s lines.
The return value makes sure that all components of @var{window} remain
fully visible if @var{window}'s size were actually set to it. With
@var{horizontal} @code{nil} it includes the mode and header line, the
horizontal scroll bar and the bottom divider, if present. With
@var{horizontal} non-@code{nil} it includes the margins and fringes, the
vertical scroll bar and the right divider, if present.
The optional argument @var{ignore}, if non-@code{nil}, means ignore
restrictions imposed by fixed size windows, @code{window-min-height} or
@code{window-min-width} settings. If @var{ignore} equals @code{safe},
live windows may get as small as @code{window-safe-min-height} lines and
@code{window-safe-min-width} columns. If @var{ignore} is a window,
ignore restrictions for that window only. Any other non-@code{nil}
value means ignore all of the above restrictions for all windows.
The optional argument @var{pixelwise} non-@code{nil} means to return the
minimum size of @var{window} counted in pixels.
@end defun
@node Resizing Windows
@section Resizing Windows
@cindex window resizing
@cindex resize window
@cindex changing window size
@cindex window size, changing
This section describes functions for resizing a window without
changing the size of its frame. Because live windows do not overlap,
these functions are meaningful only on frames that contain two or more
windows: resizing a window also changes the size of a neighboring
window. If there is just one window on a frame, its size cannot be
changed except by resizing the frame (@pxref{Frame Size}).
Except where noted, these functions also accept internal windows as
arguments. Resizing an internal window causes its child windows to be
resized to fit the same space.
@defun window-resizable window delta &optional horizontal ignore pixelwise
This function returns @var{delta} if the size of @var{window} can be
changed vertically by @var{delta} lines. If the optional argument
@var{horizontal} is non-@code{nil}, it instead returns @var{delta} if
@var{window} can be resized horizontally by @var{delta} columns. It
does not actually change the window size.
If @var{window} is @code{nil}, it defaults to the selected window.
A positive value of @var{delta} means to check whether the window can be
enlarged by that number of lines or columns; a negative value of
@var{delta} means to check whether the window can be shrunk by that many
lines or columns. If @var{delta} is non-zero, a return value of 0 means
that the window cannot be resized.
Normally, the variables @code{window-min-height} and
@code{window-min-width} specify the smallest allowable window size
(@pxref{Window Sizes}). However, if the optional argument @var{ignore}
is non-@code{nil}, this function ignores @code{window-min-height} and
@code{window-min-width}, as well as @code{window-size-fixed}. Instead,
it considers the minimum-height window to be one consisting of a header
and a mode line, a horizontal scrollbar and a bottom divider (if any),
plus a text area one line tall; and a minimum-width window as one
consisting of fringes, margins, a scroll bar and a right divider (if
any), plus a text area two columns wide.
If the optional argument @var{pixelwise} is non-@code{nil},
@var{delta} is interpreted as pixels.
@end defun
@defun window-resize window delta &optional horizontal ignore pixelwise
This function resizes @var{window} by @var{delta} increments. If
@var{horizontal} is @code{nil}, it changes the height by @var{delta}
lines; otherwise, it changes the width by @var{delta} columns. A
positive @var{delta} means to enlarge the window, and a negative
@var{delta} means to shrink it.
If @var{window} is @code{nil}, it defaults to the selected window. If
the window cannot be resized as demanded, an error is signaled.
The optional argument @var{ignore} has the same meaning as for the
function @code{window-resizable} above.
If the optional argument @var{pixelwise} is non-@code{nil},
@var{delta} will be interpreted as pixels.
The choice of which window edges this function alters depends on the
values of the option @code{window-combination-resize} and the
combination limits of the involved windows; in some cases, it may alter
both edges. @xref{Recombining Windows}. To resize by moving only the
bottom or right edge of a window, use the function
@code{adjust-window-trailing-edge}.
@end defun
@c The commands enlarge-window, enlarge-window-horizontally,
@c shrink-window, and shrink-window-horizontally are documented in the
@c Emacs manual. They are not preferred for calling from Lisp.
@defun adjust-window-trailing-edge window delta &optional horizontal pixelwise
This function moves @var{window}'s bottom edge by @var{delta} lines.
If optional argument @var{horizontal} is non-@code{nil}, it instead
moves the right edge by @var{delta} columns. If @var{window} is
@code{nil}, it defaults to the selected window.
If the optional argument @var{pixelwise} is non-@code{nil},
@var{delta} is interpreted as pixels.
A positive @var{delta} moves the edge downwards or to the right; a
negative @var{delta} moves it upwards or to the left. If the edge
cannot be moved as far as specified by @var{delta}, this function
moves it as far as possible but does not signal an error.
This function tries to resize windows adjacent to the edge that is
moved. If this is not possible for some reason (e.g., if that adjacent
window is fixed-size), it may resize other windows.
@end defun
@cindex pixelwise, resizing windows
@defopt window-resize-pixelwise
If the value of this option is non-@code{nil}, Emacs resizes windows in
units of pixels. This currently affects functions like
@code{split-window} (@pxref{Splitting Windows}), @code{maximize-window},
@code{minimize-window}, @code{fit-window-to-buffer},
@code{fit-frame-to-buffer} and
@code{shrink-window-if-larger-than-buffer} (all listed below).
Note that when a frame's pixel size is not a multiple of its character
size, at least one window may get resized pixelwise even if this
option is @code{nil}. The default value is @code{nil}.
@end defopt
The following commands resize windows in more specific ways. When
called interactively, they act on the selected window.
@deffn Command fit-window-to-buffer &optional window max-height min-height max-width min-width preserve-size
This command adjusts the height or width of @var{window} to fit the text
in it. It returns non-@code{nil} if it was able to resize @var{window},
and @code{nil} otherwise. If @var{window} is omitted or @code{nil}, it
defaults to the selected window. Otherwise, it should be a live window.
If @var{window} is part of a vertical combination, this function adjusts
@var{window}'s height. The new height is calculated from the actual
height of the accessible portion of its buffer. The optional argument
@var{max-height}, if non-@code{nil}, specifies the maximum total height
that this function can give @var{window}. The optional argument
@var{min-height}, if non-@code{nil}, specifies the minimum total height
that it can give, which overrides the variable @code{window-min-height}.
Both @var{max-height} and @var{min-height} are specified in lines and
include mode and header line and a bottom divider, if any.
If @var{window} is part of a horizontal combination and the value of the
option @code{fit-window-to-buffer-horizontally} (see below) is
non-@code{nil}, this function adjusts @var{window}'s width. The new
width of @var{window} is calculated from the maximum length of its
buffer's lines that follow the current start position of @var{window}.
The optional argument @var{max-width} specifies a maximum width and
defaults to the width of @var{window}'s frame. The optional argument
@var{min-width} specifies a minimum width and defaults to
@code{window-min-width}. Both @var{max-width} and @var{min-width} are
specified in columns and include fringes, margins and scrollbars, if
any.
The optional argument @var{preserve-size}, if non-@code{nil}, will
install a parameter to preserve the size of @var{window} during future
resize operations (@pxref{Preserving Window Sizes}).
If the option @code{fit-frame-to-buffer} (see below) is non-@code{nil},
this function will try to resize the frame of @var{window} to fit its
contents by calling @code{fit-frame-to-buffer} (see below).
@end deffn
@defopt fit-window-to-buffer-horizontally
If this is non-@code{nil}, @code{fit-window-to-buffer} can resize
windows horizontally. If this is @code{nil} (the default)
@code{fit-window-to-buffer} never resizes windows horizontally. If this
is @code{only}, it can resize windows horizontally only. Any other
value means @code{fit-window-to-buffer} can resize windows in both
dimensions.
@end defopt
@defopt fit-frame-to-buffer
If this option is non-@code{nil}, @code{fit-window-to-buffer} can fit a
frame to its buffer. A frame is fit if and only if its root window is a
live window and this option is non-@code{nil}. If this is
@code{horizontally}, frames are fit horizontally only. If this is
@code{vertically}, frames are fit vertically only. Any other
non-@code{nil} value means frames can be resized in both dimensions.
@end defopt
If you have a frame that displays only one window, you can fit that
frame to its buffer using the command @code{fit-frame-to-buffer}.
@deffn Command fit-frame-to-buffer &optional frame max-height min-height max-width min-width only
This command adjusts the size of @var{frame} to display the contents of
its buffer exactly. @var{frame} can be any live frame and defaults to
the selected one. Fitting is done only if @var{frame}'s root window is
live. The arguments @var{max-height}, @var{min-height}, @var{max-width}
and @var{min-width} specify bounds on the new total size of
@var{frame}'s root window. @var{min-height} and @var{min-width} default
to the values of @code{window-min-height} and @code{window-min-width}
respectively.
If the optional argument @var{only} is @code{vertically}, this function
may resize the frame vertically only. If @var{only} is
@code{horizontally}, it may resize the frame horizontally only.
@end deffn
The behavior of @code{fit-frame-to-buffer} can be controlled with the
help of the two options listed next.
@defopt fit-frame-to-buffer-margins
This option can be used to specify margins around frames to be fit by
@code{fit-frame-to-buffer}. Such margins can be useful to avoid, for
example, that the resized frame overlaps the taskbar or parts of its
parent frame.
It specifies the numbers of pixels to be left free on the left, above,
the right, and below a frame that shall be fit. The default specifies
@code{nil} for each which means to use no margins. The value specified
here can be overridden for a specific frame by that frame's
@code{fit-frame-to-buffer-margins} parameter, if present.
@end defopt
@defopt fit-frame-to-buffer-sizes
This option specifies size boundaries for @code{fit-frame-to-buffer}.
It specifies the total maximum and minimum lines and maximum and minimum
columns of the root window of any frame that shall be fit to its buffer.
If any of these values is non-@code{nil}, it overrides the corresponding
argument of @code{fit-frame-to-buffer}.
@end defopt
@deffn Command shrink-window-if-larger-than-buffer &optional window
This command attempts to reduce @var{window}'s height as much as
possible while still showing its full buffer, but no less than
@code{window-min-height} lines. The return value is non-@code{nil} if
the window was resized, and @code{nil} otherwise. If @var{window} is
omitted or @code{nil}, it defaults to the selected window. Otherwise,
it should be a live window.
This command does nothing if the window is already too short to
display all of its buffer, or if any of the buffer is scrolled
off-screen, or if the window is the only live window in its frame.
This command calls @code{fit-window-to-buffer} (see above) to do its
work.
@end deffn
@cindex balancing window sizes
@deffn Command balance-windows &optional window-or-frame
This function balances windows in a way that gives more space to
full-width and/or full-height windows. If @var{window-or-frame}
specifies a frame, it balances all windows on that frame. If
@var{window-or-frame} specifies a window, it balances only that window
and its siblings (@pxref{Windows and Frames}).
@end deffn