1 @node Frame, Keystrokes, Concept Index, Top
2 @comment node-name, next, previous, up
3 @chapter The XEmacs Frame
10 In many environments, such as a tty terminal, an XEmacs frame
11 literally takes up the whole screen. If you are
12 running XEmacs in a multi-window system like the X Window System, the
13 XEmacs frame takes up one X window. @xref{XEmacs under X}, for more
17 No matter what environment you are running in, XEmacs allows you to look
18 at several buffers at the same time by having several windows be part of
19 the frame. Often, the whole frame is taken up by just one window, but
20 you can split the frame into two or more subwindows. If you are
21 running XEmacs under the X window system, that means you can have several
22 @dfn{XEmacs windows} inside the X window that contains the XEmacs frame.
23 You can even have multiple frames in different X windows, each with
24 their own set of subwindows.
28 Each XEmacs frame displays a variety of information:
31 The biggest area usually displays the text you are editing. It may
32 consist of one window or of two or more windows if you need to look at two
33 buffers a the same time.
35 Below each text window's last line is a @dfn{mode line} (@pxref{Mode
36 Line}), which describes what is going on in that window. The mode line
37 is in inverse video if the terminal supports that. If there are several
38 XEmacs windows in one frame, each window has its own mode line.
40 At the bottom of each XEmacs frame is the @dfn{echo area} or @dfn{minibuffer
41 window}(@pxref{Echo Area}). It is used by XEmacs to exchange information
42 with the user. There is only one echo area per XEmacs frame.
44 If you are running XEmacs under a graphical windowing system, a
45 menu bar at the top of the frame makes shortcuts to several of the
46 commands available (@pxref{Pull-down Menus}).
48 Under a graphical windowing system, a
49 toolbar at the top of the frame, just under the menu bar if it exists,
50 provides ``one-touch'' shortcuts to several commands. (Not yet
53 Under a graphical windowing system, a
54 gutter at the top (under the toolbar) and/or bottom of the frame
55 provides advanced GUI facilities like tab controls for rapid switching
56 among related windows and progress bars for time-consuming operations
57 like downloads across the Internet. Gutters are an experimental feature
58 introduced in XEmacs version 21.2. (Not yet documented.)
61 You can subdivide the XEmacs frame into multiple text windows, and use
62 each window for a different file (@pxref{Windows}). Multiple XEmacs
63 windows are tiled vertically on the XEmacs frame. The upper XEmacs window
64 is separated from the lower window by its mode line.
66 When there are multiple, tiled XEmacs windows on a single XEmacs frame,
67 the XEmacs window receiving input from the keyboard has the @dfn{keyboard
68 focus} and is called the @dfn{selected window}. The selected window
69 contains the cursor, which indicates the insertion point. If you are
70 working in an environment that permits multiple XEmacs frames, and you
71 move the focus from one XEmacs frame into another, the
72 selected window is the one that was last selected in that frame.
74 The same text can be displayed simultaneously in several XEmacs
75 windows, which can be in different XEmacs frames. If you alter the text
76 in an XEmacs buffer by editing it in one XEmacs window, the changes are
77 visible in all XEmacs windows containing that buffer.
81 * Point:: The place in the text where editing commands operate.
82 * Echo Area:: Short messages appear at the bottom of the frame.
83 * Mode Line:: Interpreting the mode line.
84 * GUI Components:: Menubar, toolbars, gutters.
85 * XEmacs under X:: Some information on using XEmacs under the X
87 * XEmacs under MS Windows:: Some information on using XEmacs under
91 @node Point, Echo Area, Frame, Frame
92 @comment node-name, next, previous, up
97 When XEmacs is running, the cursor shows the location at which editing
98 commands will take effect. This location is called @dfn{point}. You
99 can use keystrokes or the mouse cursor to move point through the text
100 and edit the text at different places.
102 While the cursor appears to point @var{at} a character, you should
103 think of point as @var{between} two characters: it points @var{before}
104 the character on which the cursor appears. The exception is at the
105 end of the line, where the cursor appears after the last character of
106 the line. Where the display is capable, the cursor at the end of the
107 line will appear differently from a cursor over whitespace at the end
108 of the line. (In an X Windows frame, the end-of-line cursor is half
109 the width of a within-line cursor.) Sometimes people speak of ``the
110 cursor'' when they mean ``point,'' or speak of commands that move
111 point as ``cursor motion'' commands.
113 Each XEmacs frame has only one cursor. When output is in progress, the cursor
114 must appear where the typing is being done. This does not mean that
115 point is moving. It is only that XEmacs has no way to show you the
116 location of point except when the terminal is idle.
118 If you are editing several files in XEmacs, each file has its own point
119 location. A file that is not being displayed remembers where point is.
120 Point becomes visible at the correct location when you look at the file again.
122 When there are multiple text windows, each window has its own point
123 location. The cursor shows the location of point in the selected
124 window. The visible cursor also shows you which window is selected. If
125 the same buffer appears in more than one window, point can be moved in
126 each window independently.
128 The term `point' comes from the character @samp{.}, which was the
129 command in TECO (the language in which the original Emacs was written)
130 for accessing the value now called `point'.
132 @node Echo Area, Mode Line, Point, Frame
133 @section The Echo Area
136 The line at the bottom of the frame (below the mode line) is the
137 @dfn{echo area}. XEmacs uses this area to communicate with the user:
141 @dfn{Echoing} means printing out the characters that the user types. XEmacs
142 never echoes single-character commands. Multi-character commands are
143 echoed only if you pause while typing them: As soon as you pause for more
144 than one second in the middle of a command, all the characters of the command
145 so far are echoed. This is intended to @dfn{prompt} you for the rest of
146 the command. Once echoing has started, the rest of the command is echoed
147 immediately as you type it. This behavior is designed to give confident
148 users fast response, while giving hesitant users maximum feedback. You
149 can change this behavior by setting a variable (@pxref{Display Vars}).
151 If you issue a command that cannot be executed, XEmacs may print an
152 @dfn{error message} in the echo area. Error messages are accompanied by
153 a beep or by flashing the frame. Any input you have typed ahead is
154 thrown away when an error happens.
156 Some commands print informative messages in the echo area. These
157 messages look similar to error messages, but are not announced with a
158 beep and do not throw away input. Sometimes a message tells you what the
159 command has done, when this is not obvious from looking at the text being
160 edited. Sometimes the sole purpose of a command is to print a message
161 giving you specific information. For example, the command @kbd{C-x =} is
162 used to print a message describing the character position of point in the
163 text and its current column in the window. Commands that take a long time
164 often display messages ending in @samp{...} while they are working, and
165 add @samp{done} at the end when they are finished.
167 The echo area is also used to display the @dfn{minibuffer}, a window
168 that is used for reading arguments to commands, such as the name of a
169 file to be edited. When the minibuffer is in use, the echo area displays
170 with a prompt string that usually ends with a colon. The cursor
171 appears after the prompt. You can always get out of the minibuffer by
172 typing @kbd{C-g}. @xref{Minibuffer}.
175 @node Mode Line, GUI Components, Echo Area, Frame
176 @comment node-name, next, previous, up
177 @section The Mode Line
181 Each text window's last line is a @dfn{mode line} which describes what is
182 going on in that window. When there is only one text window, the mode line
183 appears right above the echo area. The mode line is in inverse video if
184 the terminal supports that, starts and ends with dashes, and contains text
185 like @samp{XEmacs:@: @var{something}}.
187 If a mode line has something else in place of @samp{XEmacs:@:
188 @var{something}}, the window above it is in a special subsystem
189 such as Dired. The mode line then indicates the status of the
192 Normally, the mode line has the following appearance:
195 --@var{ch}-XEmacs: @var{buf} (@var{major} @var{minor})----@var{pos}------
199 This gives information about the buffer being displayed in the window: the
200 buffer's name, what major and minor modes are in use, whether the buffer's
201 text has been changed, and how far down the buffer you are currently
204 @var{ch} contains two stars (@samp{**}) if the text in the buffer has been
205 edited (the buffer is ``modified''), or two dashes (@samp{--}) if the
206 buffer has not been edited. Exception: for a read-only buffer, it is
209 @var{buf} is the name of the window's chosen @dfn{buffer}. The chosen
210 buffer in the selected window (the window that the cursor is in) is also
211 XEmacs's selected buffer, the buffer in which editing takes place. When
212 we speak of what some command does to ``the buffer'', we mean the
213 currently selected buffer. @xref{Buffers}.
215 @var{pos} tells you whether there is additional text above the top of
216 the screen or below the bottom. If your file is small and it is
217 completely visible on the screen, @var{pos} is @samp{All}. Otherwise,
218 @var{pos} is @samp{Top} if you are looking at the beginning of the file,
219 @samp{Bot} if you are looking at the end of the file, or
220 @samp{@var{nn}%}, where @var{nn} is the percentage of the file above the
221 top of the screen.@refill
223 @var{major} is the name of the @dfn{major mode} in effect in the buffer. At
224 any time, each buffer is in one and only one major mode.
225 The available major modes include Fundamental mode (the least specialized),
226 Text mode, Lisp mode, and C mode. @xref{Major Modes}, for details
227 on how the modes differ and how you select one.@refill
229 @var{minor} is a list of some of the @dfn{minor modes} that are turned on
230 in the window's chosen buffer. For example, @samp{Fill} means that Auto
231 Fill mode is on. @code{Abbrev} means that Word Abbrev mode is on.
232 @code{Ovwrt} means that Overwrite mode is on. @xref{Minor Modes}, for more
233 information. @samp{Narrow} means that the buffer being displayed has
234 editing restricted to only a portion of its text. This is not really a
235 minor mode, but is like one. @xref{Narrowing}. @code{Def} means that a
236 keyboard macro is being defined. @xref{Keyboard Macros}.
238 Some buffers display additional information after the minor modes. For
239 example, Rmail buffers display the current message number and the total
240 number of messages. Compilation buffers and Shell mode display the status
243 If XEmacs is currently inside a recursive editing level, square
244 brackets (@samp{[@dots{}]}) appear around the parentheses that surround
245 the modes. If XEmacs is in one recursive editing level within another,
246 double square brackets appear, and so on. Since information on
247 recursive editing applies to XEmacs in general and not to any one buffer,
248 the square brackets appear in every mode line on the screen or not in
249 any of them. @xref{Recursive Edit}.@refill
252 XEmacs can optionally display the time and system load in all mode lines.
253 To enable this feature, type @kbd{M-x display-time}. The information added
254 to the mode line usually appears after the file name, before the mode names
255 and their parentheses. It looks like this:
258 @var{hh}:@var{mm}pm @var{l.ll} [@var{d}]
262 (Some fields may be missing if your operating system cannot support them.)
263 @var{hh} and @var{mm} are the hour and minute, followed always by @samp{am}
264 or @samp{pm}. @var{l.ll} is the average number of running processes in the
265 whole system recently. @var{d} is an approximate index of the ratio of
266 disk activity to CPU activity for all users.
268 The word @samp{Mail} appears after the load level if there is mail for
269 you that you have not read yet.
271 @vindex mode-line-inverse-video
272 Customization note: the variable @code{mode-line-inverse-video}
273 controls whether the mode line is displayed in inverse video (assuming
274 the terminal supports it); @code{nil} means no inverse video. The
275 default is @code{t}. For X frames, simply set the foreground and
276 background colors appropriately.
278 @node GUI Components, XEmacs under X, Mode Line, Frame
279 @comment node-name, next, previous, up
280 @section GUI Components
282 When executed in a graphical windowing environment such as the X Window
283 System or Microsoft Windows, XEmacs displays several graphical user
284 interface components such as scrollbars, menubars, toolbars, and
285 gutters. By default there is a vertical scrollbar at the right of each
286 frame, and at the top of the frame there is a menubar, a toolbar, and a
287 gutter, in that order. Gutters can contain any of several widgets, but
288 the default configuration puts a set of "notebook tabs" which you can
289 use as a shortcut for selecting any of several related buffers in a
290 given frame. Operating the GUI components is "obvious": click on the
291 menubar to pull down a menu, on a button in the toolbar to invoke a
292 function, and on a tab in the gutter to switch buffers.
295 * Menubar Basics:: How XEmacs uses the menubar.
296 * Scrollbar Basics:: How XEmacs uses scrollbars.
297 * Mode Line Basics:: How XEmacs uses modelines.
298 * Toolbar Basics:: How XEmacs uses toolbars.
299 * Gutter Basics:: How XEmacs uses gutters.
300 * Inhibiting:: What if you don't like GUI?
301 * Customizing:: Position, orientation, and appearance of GUI objects.
304 @node Menubar Basics, Scrollbar Basics, , GUI Components
305 @comment node-name, next, previous, up
306 @section The XEmacs Menubar
308 The XEmacs menubar is intended to be conformant to the usual conventions
309 for menubars, although conformance is not yet perfect. The menu at the
310 extreme right is the @samp{Help} menu, which should always be
311 available. It provides access to all the XEmacs help facilities
312 available through @kbd{C-h}, as well as samples of various configuration
313 files like @samp{~/.Xdefaults} and @samp{~/.emacs}. At the extreme left
314 is the @samp{Files} menu, which provides the usual file reading,
315 writing, and printing operations, as well as operations like revert
316 buffer from most recent save. The next menu from the left is the
317 @samp{Edit} menu, which provides the @samp{Undo} operation as well as
318 cutting and pasting, searching, and keyboard macro definition and
321 @c #### w3.el and VM should get cross-references here.
322 XEmacs provides a very dynamic environment, and the Lisp language makes
323 for highly flexible applications. The menubar reflects this: many menus
324 (eg, the @samp{Buffers} menu, @pxref{Buffers Menu}) contain items
325 determined by the current state of XEmacs, and most major modes and many
326 minor modes add items to menus and even whole menus to the menubar. In
327 fact, some applications like w3.el and VM provide so many menus that
328 they define a whole new menubar and add a button that allows convenient
329 switching between the ``XEmacs menubar'' and the ``application
330 menubar''. Such applications normally bind themselves to a particular
331 frame, and this switching only takes place on frames where such an
332 application is active (ie, the current window of the frame is displaying
333 a buffer in the appropriate major mode).
335 Other menus which are typically available are the @samp{Options},
336 @samp{Tools}, @samp{Buffers}, @samp{Apps}, and @samp{Mule} menus. For
337 detailed descriptions of these menus, @ref{Pull-down Menus}. (In 21.2
338 XEmacsen, the @samp{Mule} menu will be moved under @samp{Options}.)
340 @node Scrollbar Basics, Mode Line Basics, Menubar Basics, GUI Components
341 @comment node-name, next, previous, up
342 @section XEmacs Scrollbars
344 XEmacs scrollbars provide the usual interface. Arrow buttons at either
345 end allow for line by line scrolling, including autorepeat. Clicking in
346 the scrollbar itself provides scrolling by windowsfull, depending on
347 which side of the slider is clicked. The slider itself may be dragged
348 for smooth scrolling.
350 The position of the slider corresponds to the position of the window in
351 the buffer. In particular, the length of the slider is proportional to
352 the fraction of the buffer which appears in the window.
354 The presence of the scrollbars is under control of the application or
355 may be customized by the user. By default a vertical scrollbar is
356 present in all windows (except the minibuffer), and there is no
357 horizontal scrollbar.
359 @node Mode Line Basics, Toolbar Basics, Scrollbar Basics, GUI Components
360 @comment node-name, next, previous, up
361 @section XEmacs Mode Lines
363 When used in a windowing system, the XEmacs modelines can be dragged
364 vertically. The effect is to resize the windows above and below the
365 modeline (this includes the minibuffer window).
367 Additionally, a modeline can be dragged horizontally, in which case it
368 scrolls its own text. This behavior is not enabled by default because it
369 could be considered as disturbing when dragging vertically. When this
370 behavior is enabled, the modeline's text can be dragged either in the
371 same direction as the mouse, or in the opposite sense, making the
372 modeline act as a scrollbar for its own text.
374 You can select the behavior you want from the @samp{Display} submenu of
375 the @samp{Options} menu.
377 @node Toolbar Basics, Gutter Basics, Mode Line Basics, GUI Components
378 @comment node-name, next, previous, up
379 @section XEmacs Toolbars
381 XEmacs has a default toolbar which provides shortcuts for some of the
382 commonly used operations (such as opening files) and applications (such
383 as the Info manual reader). Operations which require arguments will pop
384 up dialogs to get them.
386 The position of the default toolbar can be customized. Also, several
387 toolbars may be present simultaneously (in different positions). VM,
388 for example, provides an application toolbar which shortcuts for
389 mail-specific operations like sending, saving, and deleting messages.
391 @node Gutter Basics, Inhibiting, Toolbar Basics, GUI Components
392 @comment node-name, next, previous, up
393 @section XEmacs Gutters
395 Gutters are the most flexible of the GUI components described in this
396 section. In theory, the other GUI components could be implemented by
397 customizing a gutter, but in practice the other components were
398 introduced earlier and have their own special implementations. Gutters
399 tend to be more transient than the other components. Buffer tabs, for
400 example, change every time the selected buffer in the frame changes.
401 And for progress gauges a gutter to contain the gauge is typically
402 created on the fly when needed, then destroyed when the operation whose
403 staus is being displayed is completed.
405 Buffer tabs, having somewhat complex behavior, deserve a closer look.
406 By default, a row of buffer tabs is displayed at the top of every frame.
407 (The tabs could be placed in the bottom gutter, but would be oriented
408 the same way and look rather odd. The horizontal orientation makes
409 putting them in a side gutter utterly impractical.) The buffer
410 displayed in the current window of a frame can be changed to a specific
411 buffer by clicking [mouse-1] on the corresponding tab in the gutter.
413 Each tab contains the name of its buffer. The tab for the current
414 buffer in each frame is displayed in raised relief. The list of buffers
415 chosen for display in the buffer tab row is derived by filtering the
416 buffer list (like the @code{Buffers} menu). The list starts out with
417 all existing buffers, with more recently selected buffers coming earlier
420 Then "uninteresting" buffers, like internal XEmacs buffers, the
421 @code{*Message Log*} buffer, and so on are deleted from the list. Next,
422 the frame's selected buffer is determined. Buffers with a different
423 major mode from the selected buffer are removed from the list. Finally,
424 if the list is too long, the least recently used buffers are deleted
425 from the list. By default up to 6 most recently used buffers with the
426 same mode are displayed on tabs in the gutter.
428 @node Inhibiting, Customizing, Gutter Basics, GUI Components
429 @comment node-name, next, previous, up
430 @section Inhibiting Display of GUI Components
432 Use of GUI facilities is a personal thing. Almost everyone agrees that
433 drawing via keyboard-based "turtle graphics" is acceptable to hardly
434 anyone if a mouse is available, but conversely emulating a keyboard with
435 a screenful of buttons is a painful experience. But between those
436 extremes the complete novice will require a fair amount of time before
437 toolbars and menus become dispensable, but many an "Ancien Haquer" sees
438 them as a complete waste of precious frame space that could be filled
441 Display of all of the GUI components created by XEmacs can be inhibited
442 through the use of Customize. Customize can be accessed through
443 @samp{Options | Customize} in the menu bar, or via @kbd{M-x customize}.
444 Then navigate through the Customize tree to @samp{Emacs | Environment}.
445 Scrollbar and toolbar visibility is controlled via the @samp{Display}
446 group, options @samp{Scrollbars visible} and @samp{Toolbar visible}
447 respectively. Gutter visibility is controlled by group @samp{Gutter},
448 option @samp{Visible}.
450 Or they can be controlled directly by @kbd{M-x customize-variable}, by
451 changing the values of the variables @code{menubar-visible-p},
452 @code{scrollbars-visible-p}, @code{toolbar-visible-p}, or
453 @code{gutter-buffers-tab-visible-p} respectively. (The strange form of
454 the last variable is due to the fact that gutters are often used to
455 display transient widgets like progress gauges, which you probably don't
456 want to inhibit. It is more likely that you want to inhibit the default
457 display of the buffers tab widget, which is what that variable controls.
458 This interface is subject to change depending on developer experience
461 Control of frame configuration can controlled automatically according to
462 various parameters such as buffer or frame because these are
463 @dfn{specifiers} @ref{Specifiers, , , lispref}. Using these features
464 requires programming in Lisp; Customize is not yet that sophisticated.
465 Also, components that appear in various positions and orientations can
466 have display suppressed according to position. @kbd{C-h a visible-p}
467 gives a list of variables which can be customized. E.g., to control the
468 visibility of specifically the left-side toolbar only, customize
469 @code{left-toolbar-visible-p}.
471 @node Customizing, , Inhibiting, GUI Components
472 @comment node-name, next, previous, up
473 @section Changing the Position, Orientation, and Appearance of GUI Components
475 #### Not documented yet.
477 @node XEmacs under X, XEmacs under MS Windows, GUI Components, Frame
478 @section Using XEmacs Under the X Window System
479 @comment node-name, next, previous, up
481 XEmacs can be used with the X Window System and a window manager like
482 MWM or TWM. In that case, the X window manager opens, closes, and
483 resizes XEmacs frames. You use the window manager's mouse gestures to
484 perform the operations. Consult your window manager guide or reference
485 manual for information on manipulating X windows.
487 When you are working under X, each X window (that is, each XEmacs frame)
488 has a menu bar for mouse-controlled operations (@pxref{Pull-down Menus}).
490 @cindex multi-frame XEmacs
492 XEmacs under X is also a multi-frame XEmacs. You can use the @b{New
493 Frame} menu item from the @b{File} menu to create a new XEmacs frame in a
494 new X window from the same process. The different frames will share the
495 same buffer list, but you can look at different buffers in the different
498 @findex find-file-other-frame
499 The function @code{find-file-other-frame} is just like @code{find-file},
500 but creates a new frame to display the buffer in first. This is
501 normally bound to @kbd{C-x 5 C-f}, and is what the @b{Open File, New
502 Frame} menu item does.
504 @findex switch-to-buffer-other-frame
505 The function @code{switch-to-buffer-other-frame} is just like
506 @code{switch-to-buffer}, but creates a new frame to display the buffer
507 in first. This is normally bound to @kbd{C-x 5 b}.
509 @vindex default-frame-alist
510 @vindex default-frame-plist
511 You can specify a different default frame size other than the one provided.
512 Use the variable @code{default-frame-plist}, which is a plist of default
513 values for frame creation other than the first one. These may be set in
514 your init file, like this:
517 (setq default-frame-plist '(width 80 height 55))
520 This variable has replaced @code{default-frame-alist}, which is
523 @vindex x-frame-defaults
524 For values specific to the first XEmacs frame, you must use X resources.
525 The variable @code{x-frame-defaults} takes an alist of default frame
526 creation parameters for X window frames. These override what is
527 specified in @file{~/.Xdefaults} but are overridden by the arguments to
528 the particular call to @code{x-create-frame}.
530 @vindex create-frame-hook
531 When you create a new frame, the variable @code{create-frame-hook}
532 is called with one argument, the frame just created.
534 If you want to close one or more of the X windows you created using
535 @b{New Frame}, use the @b{Delete Frame} menu item from the @b{File} menu.
537 @vindex frame-title-format
538 @vindex frame-icon-title-format
539 If you are working with multiple frames, some special information
543 Two variables, @code{frame-title-format} and
544 @code{frame-icon-title-format} determine the title of the frame and
545 the title of the icon that results if you shrink the frame.
547 @vindex auto-lower-frame
548 @vindex auto-raise-frame
550 The variables @code{auto-lower-frame} and @code{auto-raise-frame}
551 position a frame. If true, @code{auto-lower-frame} lowers a frame to
552 the bottom when it is no longer selected. If true,
553 @code{auto-raise-frame} raises a frame to the top when it is
554 selected. Under X, most ICCCM-compliant window managers will have
555 options to do this for you, but these variables are provided in case you
556 are using a broken window manager.
559 There is a new frame/modeline format directive, %S, which expands to
560 the name of the current frame (a frame's name is distinct from its
561 title; the name is used for resource lookup, among other things, and the
562 title is simply what appears above the window.)
565 @node XEmacs under MS Windows, , XEmacs under X, Frame
566 @section Using XEmacs Under Microsoft Windows
567 @comment node-name, next, previous, up
569 Use of XEmacs under MS Windows is not separately documented here, but
570 most operations available under the X Window System are also available
573 Where possible, native MS Windows GUI components and capabilities are