# HG changeset patch # User Chong Yidong # Date 1224445933 0 # Node ID 4ce02f730f6132f2dc6bc6a88391a6bcf82887d2 # Parent eec595ae4d7024813d78d8bd49bfda2b35cd1900 Use @key throughout for mouse clicks. (Creating Frames): Add xref to Init File. (Frame Commands): Add xref to Exiting. (Scroll Bars): Document GTK vs toolkit behavior. diff -r eec595ae4d70 -r 4ce02f730f61 doc/emacs/frames.texi --- a/doc/emacs/frames.texi Sun Oct 19 19:52:05 2008 +0000 +++ b/doc/emacs/frames.texi Sun Oct 19 19:52:13 2008 +0000 @@ -202,7 +202,7 @@ time. Emacs activates the region around the selected text, which is also copied to the kill ring. -@table @kbd +@table @key @item Double-Mouse-1 Select the text around the word which you click on. @@ -299,10 +299,10 @@ Nowadays, few X applications make use of the secondary selection, but you can access it using the following Emacs commands: -@table @kbd +@table @key @findex mouse-set-secondary @kindex M-Drag-Mouse-1 -@item M-@key{Drag-Mouse-1} +@item M-Drag-Mouse-1 Set the secondary selection, with one end at the place where you press down the button, and the other end at the place where you release it (@code{mouse-set-secondary}). The selected text is highlighted, using @@ -314,13 +314,13 @@ @findex mouse-start-secondary @kindex M-Mouse-1 -@item M-@key{Mouse-1} +@item M-Mouse-1 Set one endpoint for the @dfn{secondary selection} (@code{mouse-start-secondary}). @findex mouse-secondary-save-then-kill @kindex M-Mouse-3 -@item M-@key{Mouse-3} +@item M-Mouse-3 Set the secondary selection, with one end at the position clicked and the other at the position specified with @kbd{M-Mouse-1} (@code{mouse-secondary-save-then-kill}). This also puts the selected @@ -329,18 +329,17 @@ @findex mouse-yank-secondary @kindex M-Mouse-2 -@item M-@key{Mouse-2} +@item M-Mouse-2 Insert the secondary selection where you click, placing point at the end of the yanked text (@code{mouse-yank-secondary}). @end table -Double or triple clicking of @kbd{M-@key{Mouse-1}} operates on words -and lines, much like @key{Mouse-1}. +Double or triple clicking of @key{M-Mouse-1} operates on words and +lines, much like @key{Mouse-1}. -If @code{mouse-yank-at-point} is non-@code{nil}, @kbd{M-@key{Mouse-2}} -yanks at point. Then it does not matter precisely where you click, or -even which of the frame's windows you click on. @xref{Mouse -Commands}. +If @code{mouse-yank-at-point} is non-@code{nil}, @key{M-Mouse-2} yanks +at point. Then it does not matter precisely where you click, or even +which of the frame's windows you click on. @xref{Mouse Commands}. @node Clipboard @subsection Using the Clipboard @@ -381,50 +380,46 @@ @kindex Mouse-1 @r{(selection)} @kindex Mouse-2 @r{(selection)} - Some Emacs buffers include references you can follow, or commands -you can activate. These include names of files, of buffers, of -possible completions, of matches for a pattern, as well as the buttons -in Help buffers and customization buffers. You can follow the -reference or activate the command by moving point to it and typing -@key{RET}. You can also do this with the mouse, using either -@kbd{Mouse-1} or @kbd{Mouse-2}. +@vindex mouse-highlight + Some Emacs buffers include @dfn{buttons} which perform some action, +such as following a reference. A button is a stretch of text that +usually stands out in some way; it may be underlined, or a box may be +drawn around it. If you move the mouse over a button, the shape of +the mouse cursor changes and the button lights up (if you change the +variable @code{mouse-highlight} to @code{nil}, Emacs disables this +highlighting). - Since yanking text into a read-only buffer is not allowed, these -buffers generally define @kbd{Mouse-2} to follow a reference or -activate a command. For example, if you click @kbd{Mouse-2} on a file -name in a Dired buffer, you visit that file. If you click -@kbd{Mouse-2} on an error message in the @samp{*Compilation*} buffer, -you go to the source code for that error message. If you click -@kbd{Mouse-2} on a completion in the @samp{*Completions*} buffer, you -choose that completion. + You can activate a button by moving point to it and typing +@key{RET}, or by clicking either @kbd{Mouse-1} or @kbd{Mouse-2} on the +button. For example, typing @key{RET} or clicking on a file name in a +Dired buffer visits that file (@pxref{Dired}). Doing it on an error +message in the @samp{*Compilation*} buffer goes to the source code for +that error message (@pxref{Compilation}). Doing it on a completion in +the @samp{*Completions*} buffer chooses that completion +(@pxref{Completion}). - However, most applications use @kbd{Mouse-1} to do this sort of -thing, so Emacs implements this too. If you click @kbd{Mouse-1} -quickly on a reference or button, it follows or activates. If you -click slowly, it moves point as usual. Dragging, meaning moving the -mouse while it is held down, also has its usual behavior of setting -the region. + Although clicking @key{Mouse-1} on a button usually activates that +button, if you hold the mouse button down for a short period of time +before releasing it (specifically, for more than 450 milliseconds), +then Emacs moves point where you clicked instead. This behavior +allows you to use the mouse to move point over a button without +following it. Dragging, meaning moving the mouse while it is held +down, has its usual behavior of setting the region. @vindex mouse-1-click-in-non-selected-windows - Normally, the @kbd{Mouse-1} click behavior is performed on links in -any window. The variable @code{mouse-1-click-in-non-selected-windows} -controls whether @kbd{Mouse-1} has this behavior even in non-selected -windows, or only in the selected window. - -@vindex mouse-highlight - You can usually tell when @kbd{Mouse-1} and @kbd{Mouse-2} have this -special sort of meaning because the sensitive text highlights when you -move the mouse over it. The variable @code{mouse-highlight} controls -whether to do this highlighting always (even when such text appears -where the mouse already is), never, or only immediately after you move -the mouse. + Normally, clicking @key{Mouse-1} on a button activates the button +even if it is in an un-selected window. If you change the variable +@code{mouse-1-click-in-non-selected-windows} to @code{nil}, clicking +@key{Mouse-1} on a button in an un-selected window moves point to the +clicked position and selects that window, without activating the +button. @vindex mouse-1-click-follows-link - In Emacs versions before 22, only @kbd{Mouse-2} follows links and -@kbd{Mouse-1} always sets point. If you prefer this older behavior, -set the variable @code{mouse-1-click-follows-link} to @code{nil}. -This variable also lets you choose various other alternatives for -following links with the mouse. Type @kbd{C-h v + In Emacs versions before 22, only @kbd{Mouse-2} activates buttons +and @kbd{Mouse-1} always sets point. If you prefer this older +behavior, set the variable @code{mouse-1-click-follows-link} to +@code{nil}. This variable also lets you choose various other +alternatives for following links with the mouse. Type @kbd{C-h v mouse-1-click-follows-link @key{RET}} for more details. @node Menu Mouse Clicks @@ -433,7 +428,7 @@ Several mouse clicks with the @key{CTRL} and @key{SHIFT} modifiers bring up menus. -@table @kbd +@table @key @item C-Mouse-1 @kindex C-Mouse-1 This menu is for selecting a buffer. @@ -461,7 +456,8 @@ you can access them without having to display the menu bar. @item S-Mouse-1 -This menu is for specifying the frame's default font. +This menu is for changing the default face within the window's buffer. +@xref{Temporary Face Changes}. @end table @node Mode Line Mouse @@ -557,8 +553,8 @@ @cindex default-frame-alist @cindex initial-frame-alist -@cindex face customization, in @file{~/.emacs} -@cindex color customization, in @file{~/.emacs} +@cindex face customization, in init file +@cindex color customization, in init file You can control the appearance of new frames you create by setting the frame parameters in @code{default-frame-alist}. You can use the variable @code{initial-frame-alist} to specify parameters that affect @@ -566,10 +562,9 @@ Lisp Reference Manual}, for more information. @cindex font (default) - The easiest way to specify the principal font for all your Emacs -frames is with an X resource (@pxref{Font X}), but you can also do it by -modifying @code{default-frame-alist} to specify the @code{font} -parameter, as shown here: + For instance, one way to specify the principal font for all your +Emacs frames is to modify @code{default-frame-alist} to specify the +@code{font} parameter (@pxref{Font X}): @example (add-to-list 'default-frame-alist '(font . "10x20")) @@ -583,9 +578,9 @@ @end example @noindent -By putting such customizations in your @file{~/.emacs} init file, you -can control the appearance of all the frames Emacs creates, including -the initial one. +By putting such customizations in your init file, you can control the +appearance of all the frames Emacs creates, including the initial one. +@xref{Init File}. @node Frame Commands @section Frame Commands @@ -598,24 +593,20 @@ @findex iconify-or-deiconify-frame Iconify the selected Emacs frame (@code{iconify-or-deiconify-frame}). When typed on an Emacs frame's icon, deiconify instead. - -The normal meaning of @kbd{C-z}, to suspend Emacs, is not useful under -a graphical display that allows multiple applications to operate -simultaneously in their own windows, so Emacs gives @kbd{C-z} a -different binding in that case. +@xref{Exiting}. @item C-x 5 0 @kindex C-x 5 0 @findex delete-frame -Delete the selected frame (@code{delete-frame}). This is not allowed if -there is only one frame. +Delete the selected frame (@code{delete-frame}). This is not allowed +if there is only one frame. @item C-x 5 o @kindex C-x 5 o @findex other-frame -Select another frame, raise it, and warp the mouse to it so that it -stays selected. If you repeat this command, it cycles through all the -frames on your terminal. +Select another frame, raise it, and warp the mouse to it. If you +repeat this command, it cycles through all the frames on your +terminal. @item C-x 5 1 @kindex C-x 5 1 @@ -624,21 +615,20 @@ @end table @vindex focus-follows-mouse - To make the command @kbd{C-x 5 o} work properly, you must tell Emacs -how the system (or the window manager) generally handles -focus-switching between windows. There are two possibilities: either -simply moving the mouse onto a window selects it (gives it focus), or -you have to click on it in a suitable way to do so. On X, this focus -policy also affects whether the focus is given to a frame that Emacs -raises. Unfortunately there is no way Emacs can find out -automatically which way the system handles this, so you have to -explicitly say, by setting the variable @code{focus-follows-mouse}. -If just moving the mouse onto a window selects it, that variable -should be @code{t}; if a click is necessary, the variable should be -@code{nil}. + To make the command @kbd{C-x 5 o} work properly, you should tell +Emacs how the system (or the window manager) handles focus-switching +between windows. There are two possibilities: either simply moving +the mouse onto a window selects it (gives it focus), or you have to +click on it to do so. On X, this focus policy also affects whether +the focus is given to a frame that Emacs raises. Unfortunately there +is no way Emacs can find out automatically which way the system +handles this, so you have to explicitly say, by setting the variable +@code{focus-follows-mouse}. If just moving the mouse onto a window +selects it, that variable should be @code{t}; if a click is necessary, +the variable should be @code{nil}. The default is @code{t}. -The window manager that is part of MS-Windows always gives focus to a -frame that raises, so this variable has no effect in the native + The window manager that is part of MS-Windows always gives focus to +a frame that raises, so this variable has no effect in the native MS-Windows build of Emacs. @node Speedbar @@ -721,15 +711,14 @@ screens as a single stream of input. When you open frames on different X servers, Emacs makes a separate -input stream for each server. This way, two users can type -simultaneously on the two displays, and Emacs will not garble their -input. Each server also has its own selected frame. The commands you -enter with a particular X server apply to that server's selected frame. +input stream for each server. Each server also has its own selected +frame. The commands you enter with a particular X server apply to +that server's selected frame. - Despite these features, people using the same Emacs job from different -displays can still interfere with each other if they are not careful. -For example, if any one types @kbd{C-x C-c}, that exits the Emacs job -for all of them! + It is even possible to use this feature to let two or more users +type simultaneously on the two displays, within the same Emacs job. +In practice, however, the different users can easily interfere with +each others' edits if they are not careful. @node Special Buffer Frames @section Special Buffer Frames @@ -804,16 +793,8 @@ @cindex Auto-Raise mode @cindex Auto-Lower mode -@kindex S-Mouse-1 - You can specify the font and colors used for text display, and the -colors for the frame borders, the cursor, and the mouse cursor, by -customizing the faces @code{default}, @code{border}, @code{cursor} and -@code{mouse}. @xref{Face Customization}. You can also set a frame's -default font through a pop-up menu. Press @kbd{S-Mouse-1} to activate -this menu. - These commands are available for controlling the window management -behavior of the selected frame. +behavior of the selected frame: @table @kbd @findex auto-raise-mode @@ -857,43 +838,45 @@ @cindex mode, Scroll Bar On graphical displays, Emacs normally makes a @dfn{scroll bar} at -the left of each Emacs window.@footnote{Placing it at the left is -usually more useful with overlapping frames with text starting at the -left margin.} The scroll bar runs the height of the window, and shows -a moving rectangular inner box which represents the portion of the -buffer currently displayed. The entire height of the scroll bar -represents the entire length of the buffer. +the left of each Emacs window, and running the height of the +window.@footnote{Placing it at the left is usually more useful with +overlapping frames with text starting at the left margin.} - You can use @kbd{Mouse-2} (normally, the middle button) in the scroll -bar to move or drag the inner box up and down. If you move it to the -top of the scroll bar, you see the top of the buffer. If you move it to -the bottom of the scroll bar, you see the bottom of the buffer. + When Emacs is compiled with GTK support on the X window system, or +in operating systems such as Microsoft Windows or Mac OS, you can use +the scroll bar as you do in other graphical applications. If you +click @key{Mouse-1} on the scroll bar's up and down buttons, that +scrolls the window by one line at a time. Clicking @key{Mouse-1} +above or below the scroll bar's inner box scrolls the window by nearly +the entire height of the window, like @kbd{M-v} and @kbd{C-v} +respectively (@pxref{Moving Point}). Dragging the inner box with +@key{Mouse-1} scrolls the window continuously. - The left and right buttons in the scroll bar scroll by controlled -increments. @kbd{Mouse-1} (normally, the left button) moves the line at -the level where you click up to the top of the window. @kbd{Mouse-3} -(normally, the right button) moves the line at the top of the window -down to the level where you click. By clicking repeatedly in the same -place, you can scroll by the same distance over and over. + If Emacs is compiled without GTK support on the X window system, the +scroll bar behaves differently. The scroll bar's inner box is drawn +to represent the portion of the buffer currently displayed, with the +entire height of the scroll bar representing the entire length of the +buffer. @key{Mouse-1} anywhere on the scroll bar scrolls forward like +@kbd{C-v}, and @key{Mouse-3} scrolls backward like @kbd{M-v}. +Clicking @key{Mouse-2} in the scroll bar lets you move or drag the +inner box up and down. You can also click @kbd{C-Mouse-2} in the scroll bar to split a window vertically. The split occurs on the line where you click. @findex scroll-bar-mode @vindex scroll-bar-mode - You can enable or disable Scroll Bar mode with the command @kbd{M-x -scroll-bar-mode}. With no argument, it toggles the use of scroll -bars. With an argument, it turns use of scroll bars on if and only if -the argument is positive. This command applies to all frames, -including frames yet to be created. Customize the variable -@code{scroll-bar-mode} to control the use of scroll bars at startup. -You can use it to specify that they are placed at the right of windows -if you prefer that. You have to set this variable through the -@samp{Customize} interface (@pxref{Easy Customization}), or it will -not work properly. - - You can also use the X resource @samp{verticalScrollBars} to control -the initial setting of Scroll Bar mode. @xref{Resources}. + You can toggle the use of the scroll bar with the command @kbd{M-x +scroll-bar-mode}. With a prefix argument, this command turns use of +scroll bars on if and only if the argument is positive. This command +applies to all frames, including frames yet to be created. Customize +the variable @code{scroll-bar-mode} to control the use of scroll bars +at startup. You can use it to specify that they are placed at the +right of windows if you prefer that. You have to set this variable +through the @samp{Customize} interface (@pxref{Easy Customization}), +or it will not work properly. You can also use the X resource +@samp{verticalScrollBars} to control the initial setting of Scroll Bar +mode. @xref{Resources}. @findex toggle-scroll-bar To enable or disable scroll bars for just the selected frame, use the