1@c -*-texinfo-*- 2@c This is part of the GNU Emacs Lisp Reference Manual. 3@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 4@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. 5@c See the file elisp.texi for copying conditions. 6@setfilename ../info/frames 7@node Frames, Positions, Windows, Top 8@chapter Frames 9@cindex frame 10 11 In Emacs editing, A @dfn{frame} is a screen object that contains one 12or more Emacs windows. It's the kind of object that is called a 13``window'' in the terminology of graphical environments; but we can't 14call it a ``window'' here, because Emacs uses that word in a different 15way. 16 17 A frame initially contains a single main window and/or a minibuffer 18window; you can subdivide the main window vertically or horizontally 19into smaller windows. In Emacs Lisp, a @dfn{frame object} is a Lisp 20object that represents a frame on the screen. 21 22@cindex terminal frame 23 When Emacs runs on a text-only terminal, it starts with one 24@dfn{terminal frame}. If you create additional ones, Emacs displays 25one and only one at any given time---on the terminal screen, of course. 26 27@cindex window frame 28 When Emacs communicates directly with a supported window system, such 29as X, it does not have a terminal frame; instead, it starts with 30a single @dfn{window frame}, but you can create more, and Emacs can 31display several such frames at once as is usual for window systems. 32 33@defun framep object 34This predicate returns a non-@code{nil} value if @var{object} is a 35frame, and @code{nil} otherwise. For a frame, the value indicates which 36kind of display the frame uses: 37 38@table @code 39@item x 40The frame is displayed in an X window. 41@item t 42A terminal frame on a character display. 43@item mac 44The frame is displayed on a Macintosh. 45@item w32 46The frame is displayed on MS-Windows 9X/NT. 47@item pc 48The frame is displayed on an MS-DOS terminal. 49@end table 50@end defun 51 52@menu 53* Creating Frames:: Creating additional frames. 54* Multiple Displays:: Creating frames on other displays. 55* Frame Parameters:: Controlling frame size, position, font, etc. 56* Frame Titles:: Automatic updating of frame titles. 57* Deleting Frames:: Frames last until explicitly deleted. 58* Finding All Frames:: How to examine all existing frames. 59* Frames and Windows:: A frame contains windows; 60 display of text always works through windows. 61* Minibuffers and Frames:: How a frame finds the minibuffer to use. 62* Input Focus:: Specifying the selected frame. 63* Visibility of Frames:: Frames may be visible or invisible, or icons. 64* Raising and Lowering:: Raising a frame makes it hide other windows; 65 lowering it makes the others hide it. 66* Frame Configurations:: Saving the state of all frames. 67* Mouse Tracking:: Getting events that say when the mouse moves. 68* Mouse Position:: Asking where the mouse is, or moving it. 69* Pop-Up Menus:: Displaying a menu for the user to select from. 70* Dialog Boxes:: Displaying a box to ask yes or no. 71* Pointer Shape:: Specifying the shape of the mouse pointer. 72* Window System Selections:: Transferring text to and from other X clients. 73* Drag and Drop:: Internals of Drag-and-Drop implementation. 74* Color Names:: Getting the definitions of color names. 75* Text Terminal Colors:: Defining colors for text-only terminals. 76* Resources:: Getting resource values from the server. 77* Display Feature Testing:: Determining the features of a terminal. 78@end menu 79 80 @xref{Display}, for information about the related topic of 81controlling Emacs redisplay. 82 83@node Creating Frames 84@section Creating Frames 85 86To create a new frame, call the function @code{make-frame}. 87 88@defun make-frame &optional alist 89This function creates and returns a new frame, displaying the current 90buffer. If you are using a supported window system, it makes a window 91frame; otherwise, it makes a terminal frame. 92 93The argument is an alist specifying frame parameters. Any parameters 94not mentioned in @var{alist} default according to the value of the 95variable @code{default-frame-alist}; parameters not specified even there 96default from the standard X resources or whatever is used instead on 97your system. 98 99The set of possible parameters depends in principle on what kind of 100window system Emacs uses to display its frames. @xref{Window Frame 101Parameters}, for documentation of individual parameters you can specify. 102 103This function itself does not make the new frame the selected frame. 104@xref{Input Focus}. The previously selected frame remains selected. 105However, the window system may select the new frame for its own reasons, 106for instance if the frame appears under the mouse pointer and your 107setup is for focus to follow the pointer. 108@end defun 109 110@defvar before-make-frame-hook 111A normal hook run by @code{make-frame} before it actually creates the 112frame. 113@end defvar 114 115@defvar after-make-frame-functions 116An abnormal hook run by @code{make-frame} after it creates the frame. 117Each function in @code{after-make-frame-functions} receives one argument, the 118frame just created. 119@end defvar 120 121@node Multiple Displays 122@section Multiple Displays 123@cindex multiple X displays 124@cindex displays, multiple 125 126 A single Emacs can talk to more than one X display. 127Initially, Emacs uses just one display---the one chosen with the 128@code{DISPLAY} environment variable or with the @samp{--display} option 129(@pxref{Initial Options,,, emacs, The GNU Emacs Manual}). To connect to 130another display, use the command @code{make-frame-on-display} or specify 131the @code{display} frame parameter when you create the frame. 132 133 Emacs treats each X server as a separate terminal, giving each one its 134own selected frame and its own minibuffer windows. However, only one of 135those frames is ``@emph{the} selected frame'' at any given moment, see 136@ref{Input Focus}. 137 138 A few Lisp variables are @dfn{terminal-local}; that is, they have a 139separate binding for each terminal. The binding in effect at any time 140is the one for the terminal that the currently selected frame belongs 141to. These variables include @code{default-minibuffer-frame}, 142@code{defining-kbd-macro}, @code{last-kbd-macro}, and 143@code{system-key-alist}. They are always terminal-local, and can never 144be buffer-local (@pxref{Buffer-Local Variables}) or frame-local. 145 146 A single X server can handle more than one screen. A display name 147@samp{@var{host}:@var{server}.@var{screen}} has three parts; the last 148part specifies the screen number for a given server. When you use two 149screens belonging to one server, Emacs knows by the similarity in their 150names that they share a single keyboard, and it treats them as a single 151terminal. 152 153 Note that some graphical terminals can output to more than a one 154monitor (or other output device) at the same time. On these 155``multi-monitor'' setups, a single @var{display} value controls the 156output to all the physical monitors. In this situation, there is 157currently no platform-independent way for Emacs to distinguish between 158the different physical monitors. 159 160@deffn Command make-frame-on-display display &optional parameters 161This creates and returns a new frame on display @var{display}, taking 162the other frame parameters from @var{parameters}. Aside from the 163@var{display} argument, it is like @code{make-frame} (@pxref{Creating 164Frames}). 165@end deffn 166 167@defun x-display-list 168This returns a list that indicates which X displays Emacs has a 169connection to. The elements of the list are strings, and each one is 170a display name. 171@end defun 172 173@defun x-open-connection display &optional xrm-string must-succeed 174This function opens a connection to the X display @var{display}. It 175does not create a frame on that display, but it permits you to check 176that communication can be established with that display. 177 178The optional argument @var{xrm-string}, if not @code{nil}, is a 179string of resource names and values, in the same format used in the 180@file{.Xresources} file. The values you specify override the resource 181values recorded in the X server itself; they apply to all Emacs frames 182created on this display. Here's an example of what this string might 183look like: 184 185@example 186"*BorderWidth: 3\n*InternalBorder: 2\n" 187@end example 188 189@xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}. 190 191If @var{must-succeed} is non-@code{nil}, failure to open the connection 192terminates Emacs. Otherwise, it is an ordinary Lisp error. 193@end defun 194 195@defun x-close-connection display 196This function closes the connection to display @var{display}. Before 197you can do this, you must first delete all the frames that were open on 198that display (@pxref{Deleting Frames}). 199@end defun 200 201@node Frame Parameters 202@section Frame Parameters 203@cindex frame parameters 204 205 A frame has many parameters that control its appearance and behavior. 206Just what parameters a frame has depends on what display mechanism it 207uses. 208 209 Frame parameters exist mostly for the sake of window systems. A 210terminal frame has a few parameters, mostly for compatibility's sake; 211only the @code{height}, @code{width}, @code{name}, @code{title}, 212@code{menu-bar-lines}, @code{buffer-list} and @code{buffer-predicate} 213parameters do something special. If the terminal supports colors, the 214parameters @code{foreground-color}, @code{background-color}, 215@code{background-mode} and @code{display-type} are also meaningful. 216 217@menu 218* Parameter Access:: How to change a frame's parameters. 219* Initial Parameters:: Specifying frame parameters when you make a frame. 220* Window Frame Parameters:: List of frame parameters for window systems. 221* Size and Position:: Changing the size and position of a frame. 222* Geometry:: Parsing geometry specifications. 223@end menu 224 225@node Parameter Access 226@subsection Access to Frame Parameters 227 228These functions let you read and change the parameter values of a 229frame. 230 231@defun frame-parameter frame parameter 232This function returns the value of the parameter @var{parameter} (a 233symbol) of @var{frame}. If @var{frame} is @code{nil}, it returns the 234selected frame's parameter. If @var{frame} has no setting for 235@var{parameter}, this function returns @code{nil}. 236@end defun 237 238@defun frame-parameters &optional frame 239The function @code{frame-parameters} returns an alist listing all the 240parameters of @var{frame} and their values. If @var{frame} is 241@code{nil} or omitted, this returns the selected frame's parameters 242@end defun 243 244@defun modify-frame-parameters frame alist 245This function alters the parameters of frame @var{frame} based on the 246elements of @var{alist}. Each element of @var{alist} has the form 247@code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a 248parameter. If you don't mention a parameter in @var{alist}, its value 249doesn't change. If @var{frame} is @code{nil}, it defaults to the selected 250frame. 251@end defun 252 253@defun modify-all-frames-parameters alist 254This function alters the frame parameters of all existing frames 255according to @var{alist}, then modifies @code{default-frame-alist} 256(and, if necessary, @code{initial-frame-alist}) to apply the same 257parameter values to frames that will be created henceforth. 258@end defun 259 260@node Initial Parameters 261@subsection Initial Frame Parameters 262 263You can specify the parameters for the initial startup frame 264by setting @code{initial-frame-alist} in your init file (@pxref{Init File}). 265 266@defvar initial-frame-alist 267This variable's value is an alist of parameter values used when creating 268the initial window frame. You can set this variable to specify the 269appearance of the initial frame without altering subsequent frames. 270Each element has the form: 271 272@example 273(@var{parameter} . @var{value}) 274@end example 275 276Emacs creates the initial frame before it reads your init 277file. After reading that file, Emacs checks @code{initial-frame-alist}, 278and applies the parameter settings in the altered value to the already 279created initial frame. 280 281If these settings affect the frame geometry and appearance, you'll see 282the frame appear with the wrong ones and then change to the specified 283ones. If that bothers you, you can specify the same geometry and 284appearance with X resources; those do take effect before the frame is 285created. @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}. 286 287X resource settings typically apply to all frames. If you want to 288specify some X resources solely for the sake of the initial frame, and 289you don't want them to apply to subsequent frames, here's how to achieve 290this. Specify parameters in @code{default-frame-alist} to override the 291X resources for subsequent frames; then, to prevent these from affecting 292the initial frame, specify the same parameters in 293@code{initial-frame-alist} with values that match the X resources. 294@end defvar 295 296If these parameters specify a separate minibuffer-only frame with 297@code{(minibuffer . nil)}, and you have not created one, Emacs creates 298one for you. 299 300@defvar minibuffer-frame-alist 301This variable's value is an alist of parameter values used when creating 302an initial minibuffer-only frame---if such a frame is needed, according 303to the parameters for the main initial frame. 304@end defvar 305 306@defvar default-frame-alist 307This is an alist specifying default values of frame parameters for all 308Emacs frames---the first frame, and subsequent frames. When using the X 309Window System, you can get the same results by means of X resources 310in many cases. 311 312Setting this variable does not affect existing frames. 313@end defvar 314 315See also @code{special-display-frame-alist}. @xref{Definition of 316special-display-frame-alist}. 317 318If you use options that specify window appearance when you invoke Emacs, 319they take effect by adding elements to @code{default-frame-alist}. One 320exception is @samp{-geometry}, which adds the specified position to 321@code{initial-frame-alist} instead. @xref{Emacs Invocation,, Command 322Line Arguments for Emacs Invocation, emacs, The GNU Emacs Manual}. 323 324@node Window Frame Parameters 325@subsection Window Frame Parameters 326 327 Just what parameters a frame has depends on what display mechanism 328it uses. This section describes the parameters that have special 329meanings on some or all kinds of terminals. Of these, @code{name}, 330@code{title}, @code{height}, @code{width}, @code{buffer-list} and 331@code{buffer-predicate} provide meaningful information in terminal 332frames, and @code{tty-color-mode} is meaningful @emph{only} in 333terminal frames. 334 335@menu 336* Basic Parameters:: Parameters that are fundamental. 337* Position Parameters:: The position of the frame on the screen. 338* Size Parameters:: Frame's size. 339* Layout Parameters:: Size of parts of the frame, and 340 enabling or disabling some parts. 341* Buffer Parameters:: Which buffers have been or should be shown. 342* Management Parameters:: Communicating with the window manager. 343* Cursor Parameters:: Controlling the cursor appearance. 344* Color Parameters:: Colors of various parts of the frame. 345@end menu 346 347@node Basic Parameters 348@subsubsection Basic Parameters 349 350 These frame parameters give the most basic information about the 351frame. @code{title} and @code{name} are meaningful on all terminals. 352 353@table @code 354@item display 355The display on which to open this frame. It should be a string of the 356form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the 357@code{DISPLAY} environment variable. 358 359@item display-type 360This parameter describes the range of possible colors that can be used 361in this frame. Its value is @code{color}, @code{grayscale} or 362@code{mono}. 363 364@item title 365If a frame has a non-@code{nil} title, it appears in the window system's 366border for the frame, and also in the mode line of windows in that frame 367if @code{mode-line-frame-identification} uses @samp{%F} 368(@pxref{%-Constructs}). This is normally the case when Emacs is not 369using a window system, and can only display one frame at a time. 370@xref{Frame Titles}. 371 372@item name 373The name of the frame. The frame name serves as a default for the frame 374title, if the @code{title} parameter is unspecified or @code{nil}. If 375you don't specify a name, Emacs sets the frame name automatically 376(@pxref{Frame Titles}). 377 378If you specify the frame name explicitly when you create the frame, the 379name is also used (instead of the name of the Emacs executable) when 380looking up X resources for the frame. 381@end table 382 383@node Position Parameters 384@subsubsection Position Parameters 385 386 Position parameters' values are normally measured in pixels, but on 387text-only terminals they count characters or lines instead. 388 389@table @code 390@item left 391The screen position of the left edge, in pixels, with respect to the 392left edge of the screen. The value may be a positive number @var{pos}, 393or a list of the form @code{(+ @var{pos})} which permits specifying a 394negative @var{pos} value. 395 396A negative number @minus{}@var{pos}, or a list of the form @code{(- 397@var{pos})}, actually specifies the position of the right edge of the 398window with respect to the right edge of the screen. A positive value 399of @var{pos} counts toward the left. @strong{Reminder:} if the 400parameter is a negative integer @minus{}@var{pos}, then @var{pos} is 401positive. 402 403Some window managers ignore program-specified positions. If you want to 404be sure the position you specify is not ignored, specify a 405non-@code{nil} value for the @code{user-position} parameter as well. 406 407@item top 408The screen position of the top edge, in pixels, with respect to the 409top edge of the screen. It works just like @code{left}, except vertically 410instead of horizontally. 411 412@item icon-left 413The screen position of the left edge @emph{of the frame's icon}, in 414pixels, counting from the left edge of the screen. This takes effect if 415and when the frame is iconified. 416 417If you specify a value for this parameter, then you must also specify 418a value for @code{icon-top} and vice versa. The window manager may 419ignore these two parameters. 420 421@item icon-top 422The screen position of the top edge @emph{of the frame's icon}, in 423pixels, counting from the top edge of the screen. This takes effect if 424and when the frame is iconified. 425 426@item user-position 427When you create a frame and specify its screen position with the 428@code{left} and @code{top} parameters, use this parameter to say whether 429the specified position was user-specified (explicitly requested in some 430way by a human user) or merely program-specified (chosen by a program). 431A non-@code{nil} value says the position was user-specified. 432 433Window managers generally heed user-specified positions, and some heed 434program-specified positions too. But many ignore program-specified 435positions, placing the window in a default fashion or letting the user 436place it with the mouse. Some window managers, including @code{twm}, 437let the user specify whether to obey program-specified positions or 438ignore them. 439 440When you call @code{make-frame}, you should specify a non-@code{nil} 441value for this parameter if the values of the @code{left} and @code{top} 442parameters represent the user's stated preference; otherwise, use 443@code{nil}. 444@end table 445 446@node Size Parameters 447@subsubsection Size Parameters 448 449 Size parameters' values are normally measured in pixels, but on 450text-only terminals they count characters or lines instead. 451 452@table @code 453@item height 454The height of the frame contents, in characters. (To get the height in 455pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.) 456 457@item width 458The width of the frame contents, in characters. (To get the height in 459pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.) 460 461@item user-size 462This does for the size parameters @code{height} and @code{width} what 463the @code{user-position} parameter (see above) does for the position 464parameters @code{top} and @code{left}. 465 466@item fullscreen 467Specify that width, height or both shall be set to the size of the screen. 468The value @code{fullwidth} specifies that width shall be the size of the 469screen. The value @code{fullheight} specifies that height shall be the 470size of the screen. The value @code{fullboth} specifies that both the 471width and the height shall be set to the size of the screen. 472@end table 473 474@node Layout Parameters 475@subsubsection Layout Parameters 476 477 These frame parameters enable or disable various parts of the 478frame, or control their sizes. 479 480@table @code 481@item border-width 482The width in pixels of the frame's border. 483 484@item internal-border-width 485The distance in pixels between text (or fringe) and the frame's border. 486 487@item vertical-scroll-bars 488Whether the frame has scroll bars for vertical scrolling, and which side 489of the frame they should be on. The possible values are @code{left}, 490@code{right}, and @code{nil} for no scroll bars. 491 492@ignore 493@item horizontal-scroll-bars 494Whether the frame has scroll bars for horizontal scrolling 495(non-@code{nil} means yes). Horizontal scroll bars are not currently 496implemented. 497@end ignore 498 499@item scroll-bar-width 500The width of vertical scroll bars, in pixels, or @code{nil} meaning to 501use the default width. 502 503@item left-fringe 504@itemx right-fringe 505The default width of the left and right fringes of windows in this 506frame (@pxref{Fringes}). If either of these is zero, that effectively 507removes the corresponding fringe. A value of @code{nil} stands for 508the standard fringe width, which is the width needed to display the 509fringe bitmaps. 510 511The combined fringe widths must add up to an integral number of 512columns, so the actual default fringe widths for the frame may be 513larger than the specified values. The extra width needed to reach an 514acceptable total is distributed evenly between the left and right 515fringe. However, you can force one fringe or the other to a precise 516width by specifying that width as a negative integer. If both widths are 517negative, only the left fringe gets the specified width. 518 519@item menu-bar-lines 520The number of lines to allocate at the top of the frame for a menu 521bar. The default is 1. A value of @code{nil} means don't display a 522menu bar. @xref{Menu Bar}. (The X toolkit and GTK allow at most one 523menu bar line; they treat larger values as 1.) 524 525@item tool-bar-lines 526The number of lines to use for the tool bar. A value of @code{nil} 527means don't display a tool bar. (GTK allows at most one tool bar line; 528it treats larger values as 1.) 529 530@item line-spacing 531Additional space to leave below each text line, in pixels (a positive 532integer). @xref{Line Height}, for more information. 533@end table 534 535@node Buffer Parameters 536@subsubsection Buffer Parameters 537 538 These frame parameters, meaningful on all kinds of terminals, deal 539with which buffers have been, or should, be displayed in the frame. 540 541@table @code 542@item minibuffer 543Whether this frame has its own minibuffer. The value @code{t} means 544yes, @code{nil} means no, @code{only} means this frame is just a 545minibuffer. If the value is a minibuffer window (in some other frame), 546the new frame uses that minibuffer. 547 548@item buffer-predicate 549The buffer-predicate function for this frame. The function 550@code{other-buffer} uses this predicate (from the selected frame) to 551decide which buffers it should consider, if the predicate is not 552@code{nil}. It calls the predicate with one argument, a buffer, once for 553each buffer; if the predicate returns a non-@code{nil} value, it 554considers that buffer. 555 556@item buffer-list 557A list of buffers that have been selected in this frame, 558ordered most-recently-selected first. 559 560@item unsplittable 561If non-@code{nil}, this frame's window is never split automatically. 562@end table 563 564@node Management Parameters 565@subsubsection Window Management Parameters 566@cindex window manager, and frame parameters 567 568 These frame parameters, meaningful only on window system displays, 569interact with the window manager. 570 571@table @code 572@item visibility 573The state of visibility of the frame. There are three possibilities: 574@code{nil} for invisible, @code{t} for visible, and @code{icon} for 575iconified. @xref{Visibility of Frames}. 576 577@item auto-raise 578Whether selecting the frame raises it (non-@code{nil} means yes). 579 580@item auto-lower 581Whether deselecting the frame lowers it (non-@code{nil} means yes). 582 583@item icon-type 584The type of icon to use for this frame when it is iconified. If the 585value is a string, that specifies a file containing a bitmap to use. 586Any other non-@code{nil} value specifies the default bitmap icon (a 587picture of a gnu); @code{nil} specifies a text icon. 588 589@item icon-name 590The name to use in the icon for this frame, when and if the icon 591appears. If this is @code{nil}, the frame's title is used. 592 593@item window-id 594The number of the window-system window used by the frame 595to contain the actual Emacs windows. 596 597@item outer-window-id 598The number of the outermost window-system window used for the whole frame. 599 600@item wait-for-wm 601If non-@code{nil}, tell Xt to wait for the window manager to confirm 602geometry changes. Some window managers, including versions of Fvwm2 603and KDE, fail to confirm, so Xt hangs. Set this to @code{nil} to 604prevent hanging with those window managers. 605 606@ignore 607@item parent-id 608@c ??? Not yet working. 609The X window number of the window that should be the parent of this one. 610Specifying this lets you create an Emacs window inside some other 611application's window. (It is not certain this will be implemented; try 612it and see if it works.) 613@end ignore 614@end table 615 616@node Cursor Parameters 617@subsubsection Cursor Parameters 618 619 This frame parameter controls the way the cursor looks. 620 621@table @code 622@item cursor-type 623How to display the cursor. Legitimate values are: 624 625@table @code 626@item box 627Display a filled box. (This is the default.) 628@item hollow 629Display a hollow box. 630@item nil 631Don't display a cursor. 632@item bar 633Display a vertical bar between characters. 634@item (bar . @var{width}) 635Display a vertical bar @var{width} pixels wide between characters. 636@item hbar 637Display a horizontal bar. 638@item (hbar . @var{height}) 639Display a horizontal bar @var{height} pixels high. 640@end table 641@end table 642 643@vindex cursor-type 644The buffer-local variable @code{cursor-type} overrides the value of 645the @code{cursor-type} frame parameter, but if it is @code{t}, that 646means to use the cursor specified for the frame. 647 648@defvar blink-cursor-alist 649This variable specifies how to blink the cursor. Each element has the 650form @code{(@var{on-state} . @var{off-state})}. Whenever the cursor 651type equals @var{on-state} (comparing using @code{equal}), the 652corresponding @var{off-state} specifies what the cursor looks like 653when it blinks ``off.'' Both @var{on-state} and @var{off-state} 654should be suitable values for the @code{cursor-type} frame parameter. 655 656There are various defaults for how to blink each type of cursor, if 657the type is not mentioned as an @var{on-state} here. Changes in this 658variable do not take effect immediately, because the variable is 659examined only when you specify the @code{cursor-type} parameter. 660@end defvar 661 662@node Color Parameters 663@subsubsection Color Parameters 664 665 These frame parameters control the use of colors. 666 667@table @code 668@item background-mode 669This parameter is either @code{dark} or @code{light}, according 670to whether the background color is a light one or a dark one. 671 672@item tty-color-mode 673@cindex standard colors for character terminals 674This parameter overrides the terminal's color support as given by the 675system's terminal capabilities database in that this parameter's value 676specifies the color mode to use in terminal frames. The value can be 677either a symbol or a number. A number specifies the number of colors 678to use (and, indirectly, what commands to issue to produce each 679color). For example, @code{(tty-color-mode . 8)} specifies use of the 680ANSI escape sequences for 8 standard text colors. A value of -1 turns 681off color support. 682 683If the parameter's value is a symbol, it specifies a number through 684the value of @code{tty-color-mode-alist}, and the associated number is 685used instead. 686 687@item screen-gamma 688@cindex gamma correction 689If this is a number, Emacs performs ``gamma correction'' which adjusts 690the brightness of all colors. The value should be the screen gamma of 691your display, a floating point number. 692 693Usual PC monitors have a screen gamma of 2.2, so color values in 694Emacs, and in X windows generally, are calibrated to display properly 695on a monitor with that gamma value. If you specify 2.2 for 696@code{screen-gamma}, that means no correction is needed. Other values 697request correction, designed to make the corrected colors appear on 698your screen the way they would have appeared without correction on an 699ordinary monitor with a gamma value of 2.2. 700 701If your monitor displays colors too light, you should specify a 702@code{screen-gamma} value smaller than 2.2. This requests correction 703that makes colors darker. A screen gamma value of 1.5 may give good 704results for LCD color displays. 705@end table 706 707These frame parameters are semi-obsolete in that they are automatically 708equivalent to particular face attributes of particular faces. 709 710@table @code 711@item font 712The name of the font for displaying text in the frame. This is a 713string, either a valid font name for your system or the name of an Emacs 714fontset (@pxref{Fontsets}). It is equivalent to the @code{font} 715attribute of the @code{default} face. 716 717@item foreground-color 718The color to use for the image of a character. It is equivalent to 719the @code{:foreground} attribute of the @code{default} face. 720 721@item background-color 722The color to use for the background of characters. It is equivalent to 723the @code{:background} attribute of the @code{default} face. 724 725@item mouse-color 726The color for the mouse pointer. It is equivalent to the @code{:background} 727attribute of the @code{mouse} face. 728 729@item cursor-color 730The color for the cursor that shows point. It is equivalent to the 731@code{:background} attribute of the @code{cursor} face. 732 733@item border-color 734The color for the border of the frame. It is equivalent to the 735@code{:background} attribute of the @code{border} face. 736 737@item scroll-bar-foreground 738If non-@code{nil}, the color for the foreground of scroll bars. It is 739equivalent to the @code{:foreground} attribute of the 740@code{scroll-bar} face. 741 742@item scroll-bar-background 743If non-@code{nil}, the color for the background of scroll bars. It is 744equivalent to the @code{:background} attribute of the 745@code{scroll-bar} face. 746@end table 747 748@node Size and Position 749@subsection Frame Size And Position 750@cindex size of frame 751@cindex screen size 752@cindex frame size 753@cindex resize frame 754 755 You can read or change the size and position of a frame using the 756frame parameters @code{left}, @code{top}, @code{height}, and 757@code{width}. Whatever geometry parameters you don't specify are chosen 758by the window manager in its usual fashion. 759 760 Here are some special features for working with sizes and positions. 761(For the precise meaning of ``selected frame'' used by these functions, 762see @ref{Input Focus}.) 763 764@defun set-frame-position frame left top 765This function sets the position of the top left corner of @var{frame} to 766@var{left} and @var{top}. These arguments are measured in pixels, and 767normally count from the top left corner of the screen. 768 769Negative parameter values position the bottom edge of the window up from 770the bottom edge of the screen, or the right window edge to the left of 771the right edge of the screen. It would probably be better if the values 772were always counted from the left and top, so that negative arguments 773would position the frame partly off the top or left edge of the screen, 774but it seems inadvisable to change that now. 775@end defun 776 777@defun frame-height &optional frame 778@defunx frame-width &optional frame 779These functions return the height and width of @var{frame}, measured in 780lines and columns. If you don't supply @var{frame}, they use the 781selected frame. 782@end defun 783 784@defun screen-height 785@defunx screen-width 786These functions are old aliases for @code{frame-height} and 787@code{frame-width}. When you are using a non-window terminal, the size 788of the frame is normally the same as the size of the terminal screen. 789@end defun 790 791@defun frame-pixel-height &optional frame 792@defunx frame-pixel-width &optional frame 793These functions return the height and width of @var{frame}, measured in 794pixels. If you don't supply @var{frame}, they use the selected frame. 795@end defun 796 797@defun frame-char-height &optional frame 798@defunx frame-char-width &optional frame 799These functions return the height and width of a character in 800@var{frame}, measured in pixels. The values depend on the choice of 801font. If you don't supply @var{frame}, these functions use the selected 802frame. 803@end defun 804 805@defun set-frame-size frame cols rows 806This function sets the size of @var{frame}, measured in characters; 807@var{cols} and @var{rows} specify the new width and height. 808 809To set the size based on values measured in pixels, use 810@code{frame-char-height} and @code{frame-char-width} to convert 811them to units of characters. 812@end defun 813 814@defun set-frame-height frame lines &optional pretend 815This function resizes @var{frame} to a height of @var{lines} lines. The 816sizes of existing windows in @var{frame} are altered proportionally to 817fit. 818 819If @var{pretend} is non-@code{nil}, then Emacs displays @var{lines} 820lines of output in @var{frame}, but does not change its value for the 821actual height of the frame. This is only useful for a terminal frame. 822Using a smaller height than the terminal actually implements may be 823useful to reproduce behavior observed on a smaller screen, or if the 824terminal malfunctions when using its whole screen. Setting the frame 825height ``for real'' does not always work, because knowing the correct 826actual size may be necessary for correct cursor positioning on a 827terminal frame. 828@end defun 829 830@defun set-frame-width frame width &optional pretend 831This function sets the width of @var{frame}, measured in characters. 832The argument @var{pretend} has the same meaning as in 833@code{set-frame-height}. 834@end defun 835 836@findex set-screen-height 837@findex set-screen-width 838 The older functions @code{set-screen-height} and 839@code{set-screen-width} were used to specify the height and width of the 840screen, in Emacs versions that did not support multiple frames. They 841are semi-obsolete, but still work; they apply to the selected frame. 842 843@node Geometry 844@subsection Geometry 845 846 Here's how to examine the data in an X-style window geometry 847specification: 848 849@defun x-parse-geometry geom 850@cindex geometry specification 851The function @code{x-parse-geometry} converts a standard X window 852geometry string to an alist that you can use as part of the argument to 853@code{make-frame}. 854 855The alist describes which parameters were specified in @var{geom}, and 856gives the values specified for them. Each element looks like 857@code{(@var{parameter} . @var{value})}. The possible @var{parameter} 858values are @code{left}, @code{top}, @code{width}, and @code{height}. 859 860For the size parameters, the value must be an integer. The position 861parameter names @code{left} and @code{top} are not totally accurate, 862because some values indicate the position of the right or bottom edges 863instead. These are the @var{value} possibilities for the position 864parameters: 865 866@table @asis 867@item an integer 868A positive integer relates the left edge or top edge of the window to 869the left or top edge of the screen. A negative integer relates the 870right or bottom edge of the window to the right or bottom edge of the 871screen. 872 873@item @code{(+ @var{position})} 874This specifies the position of the left or top edge of the window 875relative to the left or top edge of the screen. The integer 876@var{position} may be positive or negative; a negative value specifies a 877position outside the screen. 878 879@item @code{(- @var{position})} 880This specifies the position of the right or bottom edge of the window 881relative to the right or bottom edge of the screen. The integer 882@var{position} may be positive or negative; a negative value specifies a 883position outside the screen. 884@end table 885 886Here is an example: 887 888@example 889(x-parse-geometry "35x70+0-0") 890 @result{} ((height . 70) (width . 35) 891 (top - 0) (left . 0)) 892@end example 893@end defun 894 895@node Frame Titles 896@section Frame Titles 897@cindex frame title 898 899 Every frame has a @code{name} parameter; this serves as the default 900for the frame title which window systems typically display at the top of 901the frame. You can specify a name explicitly by setting the @code{name} 902frame property. 903 904 Normally you don't specify the name explicitly, and Emacs computes the 905frame name automatically based on a template stored in the variable 906@code{frame-title-format}. Emacs recomputes the name each time the 907frame is redisplayed. 908 909@defvar frame-title-format 910This variable specifies how to compute a name for a frame when you have 911not explicitly specified one. The variable's value is actually a mode 912line construct, just like @code{mode-line-format}, except that the 913@samp{%c} and @samp{%l} constructs are ignored. @xref{Mode Line 914Data}. 915@end defvar 916 917@defvar icon-title-format 918This variable specifies how to compute the name for an iconified frame, 919when you have not explicitly specified the frame title. This title 920appears in the icon itself. 921@end defvar 922 923@defvar multiple-frames 924This variable is set automatically by Emacs. Its value is @code{t} when 925there are two or more frames (not counting minibuffer-only frames or 926invisible frames). The default value of @code{frame-title-format} uses 927@code{multiple-frames} so as to put the buffer name in the frame title 928only when there is more than one frame. 929 930The value of this variable is not guaranteed to be accurate except 931while processing @code{frame-title-format} or 932@code{icon-title-format}. 933@end defvar 934 935@node Deleting Frames 936@section Deleting Frames 937@cindex deleting frames 938 939Frames remain potentially visible until you explicitly @dfn{delete} 940them. A deleted frame cannot appear on the screen, but continues to 941exist as a Lisp object until there are no references to it. 942 943@deffn Command delete-frame &optional frame force 944@vindex delete-frame-functions 945This function deletes the frame @var{frame}. Unless @var{frame} is a 946tooltip, it first runs the hook @code{delete-frame-functions} (each 947function gets one argument, @var{frame}). By default, @var{frame} is 948the selected frame. 949 950A frame cannot be deleted if its minibuffer is used by other frames. 951Normally, you cannot delete a frame if all other frames are invisible, 952but if the @var{force} is non-@code{nil}, then you are allowed to do so. 953@end deffn 954 955@defun frame-live-p frame 956The function @code{frame-live-p} returns non-@code{nil} if the frame 957@var{frame} has not been deleted. The possible non-@code{nil} return 958values are like those of @code{framep}. @xref{Frames}. 959@end defun 960 961 Some window managers provide a command to delete a window. These work 962by sending a special message to the program that operates the window. 963When Emacs gets one of these commands, it generates a 964@code{delete-frame} event, whose normal definition is a command that 965calls the function @code{delete-frame}. @xref{Misc Events}. 966 967@node Finding All Frames 968@section Finding All Frames 969@cindex frames, scanning all 970 971@defun frame-list 972The function @code{frame-list} returns a list of all the frames that 973have not been deleted. It is analogous to @code{buffer-list} for 974buffers, and includes frames on all terminals. The list that you get is 975newly created, so modifying the list doesn't have any effect on the 976internals of Emacs. 977@end defun 978 979@defun visible-frame-list 980This function returns a list of just the currently visible frames. 981@xref{Visibility of Frames}. (Terminal frames always count as 982``visible,'' even though only the selected one is actually displayed.) 983@end defun 984 985@defun next-frame &optional frame minibuf 986The function @code{next-frame} lets you cycle conveniently through all 987the frames on the current display from an arbitrary starting point. It 988returns the ``next'' frame after @var{frame} in the cycle. If 989@var{frame} is omitted or @code{nil}, it defaults to the selected frame 990(@pxref{Input Focus}). 991 992The second argument, @var{minibuf}, says which frames to consider: 993 994@table @asis 995@item @code{nil} 996Exclude minibuffer-only frames. 997@item @code{visible} 998Consider all visible frames. 999@item 0 1000Consider all visible or iconified frames. 1001@item a window 1002Consider only the frames using that particular window as their 1003minibuffer. 1004@item anything else 1005Consider all frames. 1006@end table 1007@end defun 1008 1009@defun previous-frame &optional frame minibuf 1010Like @code{next-frame}, but cycles through all frames in the opposite 1011direction. 1012@end defun 1013 1014 See also @code{next-window} and @code{previous-window}, in @ref{Cyclic 1015Window Ordering}. 1016 1017@node Frames and Windows 1018@section Frames and Windows 1019 1020 Each window is part of one and only one frame; you can get the frame 1021with @code{window-frame}. 1022 1023@defun window-frame window 1024This function returns the frame that @var{window} is on. 1025@end defun 1026 1027 All the non-minibuffer windows in a frame are arranged in a cyclic 1028order. The order runs from the frame's top window, which is at the 1029upper left corner, down and to the right, until it reaches the window at 1030the lower right corner (always the minibuffer window, if the frame has 1031one), and then it moves back to the top. @xref{Cyclic Window Ordering}. 1032 1033@defun frame-first-window &optional frame 1034This returns the topmost, leftmost window of frame @var{frame}. 1035If omitted or @code{nil}, @var{frame} defaults to the selected frame. 1036@end defun 1037 1038At any time, exactly one window on any frame is @dfn{selected within the 1039frame}. The significance of this designation is that selecting the 1040frame also selects this window. You can get the frame's current 1041selected window with @code{frame-selected-window}. 1042 1043@defun frame-selected-window &optional frame 1044This function returns the window on @var{frame} that is selected 1045within @var{frame}. If omitted or @code{nil}, @var{frame} defaults to 1046the selected frame. 1047@end defun 1048 1049@defun set-frame-selected-window frame window 1050This sets the selected window of frame @var{frame} to @var{window}. 1051If @var{frame} is @code{nil}, it operates on the selected frame. If 1052@var{frame} is the selected frame, this makes @var{window} the 1053selected window. This function returns @var{window}. 1054@end defun 1055 1056 Conversely, selecting a window for Emacs with @code{select-window} also 1057makes that window selected within its frame. @xref{Selecting Windows}. 1058 1059 Another function that (usually) returns one of the windows in a given 1060frame is @code{minibuffer-window}. @xref{Definition of minibuffer-window}. 1061 1062@node Minibuffers and Frames 1063@section Minibuffers and Frames 1064 1065Normally, each frame has its own minibuffer window at the bottom, which 1066is used whenever that frame is selected. If the frame has a minibuffer, 1067you can get it with @code{minibuffer-window} (@pxref{Definition of 1068minibuffer-window}). 1069 1070However, you can also create a frame with no minibuffer. Such a frame 1071must use the minibuffer window of some other frame. When you create the 1072frame, you can specify explicitly the minibuffer window to use (in some 1073other frame). If you don't, then the minibuffer is found in the frame 1074which is the value of the variable @code{default-minibuffer-frame}. Its 1075value should be a frame that does have a minibuffer. 1076 1077If you use a minibuffer-only frame, you might want that frame to raise 1078when you enter the minibuffer. If so, set the variable 1079@code{minibuffer-auto-raise} to @code{t}. @xref{Raising and Lowering}. 1080 1081@defvar default-minibuffer-frame 1082This variable specifies the frame to use for the minibuffer window, by 1083default. It does not affect existing frames. It is always local to 1084the current terminal and cannot be buffer-local. @xref{Multiple 1085Displays}. 1086@end defvar 1087 1088@node Input Focus 1089@section Input Focus 1090@cindex input focus 1091@c @cindex selected frame Duplicates selected-frame 1092 1093At any time, one frame in Emacs is the @dfn{selected frame}. The selected 1094window always resides on the selected frame. 1095 1096When Emacs displays its frames on several terminals (@pxref{Multiple 1097Displays}), each terminal has its own selected frame. But only one of 1098these is ``@emph{the} selected frame'': it's the frame that belongs to 1099the terminal from which the most recent input came. That is, when Emacs 1100runs a command that came from a certain terminal, the selected frame is 1101the one of that terminal. Since Emacs runs only a single command at any 1102given time, it needs to consider only one selected frame at a time; this 1103frame is what we call @dfn{the selected frame} in this manual. The 1104display on which the selected frame is displayed is the @dfn{selected 1105frame's display}. 1106 1107@defun selected-frame 1108This function returns the selected frame. 1109@end defun 1110 1111Some window systems and window managers direct keyboard input to the 1112window object that the mouse is in; others require explicit clicks or 1113commands to @dfn{shift the focus} to various window objects. Either 1114way, Emacs automatically keeps track of which frame has the focus. To 1115switch to a different frame from a Lisp function, call 1116@code{select-frame-set-input-focus}. 1117 1118Lisp programs can also switch frames ``temporarily'' by calling the 1119function @code{select-frame}. This does not alter the window system's 1120concept of focus; rather, it escapes from the window manager's control 1121until that control is somehow reasserted. 1122 1123When using a text-only terminal, only one frame can be displayed at a 1124time on the terminal, so after a call to @code{select-frame}, the next 1125redisplay actually displays the newly selected frame. This frame 1126remains selected until a subsequent call to @code{select-frame} or 1127@code{select-frame-set-input-focus}. Each terminal frame has a number 1128which appears in the mode line before the buffer name (@pxref{Mode 1129Line Variables}). 1130 1131@defun select-frame-set-input-focus frame 1132This function makes @var{frame} the selected frame, raises it (should 1133it happen to be obscured by other frames) and tries to give it the X 1134server's focus. On a text-only terminal, the next redisplay displays 1135the new frame on the entire terminal screen. The return value of this 1136function is not significant. 1137@end defun 1138 1139@c ??? This is not yet implemented properly. 1140@defun select-frame frame 1141This function selects frame @var{frame}, temporarily disregarding the 1142focus of the X server if any. The selection of @var{frame} lasts until 1143the next time the user does something to select a different frame, or 1144until the next time this function is called. (If you are using a 1145window system, the previously selected frame may be restored as the 1146selected frame after return to the command loop, because it still may 1147have the window system's input focus.) The specified @var{frame} 1148becomes the selected frame, as explained above, and the terminal that 1149@var{frame} is on becomes the selected terminal. This function 1150returns @var{frame}, or @code{nil} if @var{frame} has been deleted. 1151 1152In general, you should never use @code{select-frame} in a way that could 1153switch to a different terminal without switching back when you're done. 1154@end defun 1155 1156Emacs cooperates with the window system by arranging to select frames as 1157the server and window manager request. It does so by generating a 1158special kind of input event, called a @dfn{focus} event, when 1159appropriate. The command loop handles a focus event by calling 1160@code{handle-switch-frame}. @xref{Focus Events}. 1161 1162@deffn Command handle-switch-frame frame 1163This function handles a focus event by selecting frame @var{frame}. 1164 1165Focus events normally do their job by invoking this command. 1166Don't call it for any other reason. 1167@end deffn 1168 1169@defun redirect-frame-focus frame &optional focus-frame 1170This function redirects focus from @var{frame} to @var{focus-frame}. 1171This means that @var{focus-frame} will receive subsequent keystrokes and 1172events intended for @var{frame}. After such an event, the value of 1173@code{last-event-frame} will be @var{focus-frame}. Also, switch-frame 1174events specifying @var{frame} will instead select @var{focus-frame}. 1175 1176If @var{focus-frame} is omitted or @code{nil}, that cancels any existing 1177redirection for @var{frame}, which therefore once again receives its own 1178events. 1179 1180One use of focus redirection is for frames that don't have minibuffers. 1181These frames use minibuffers on other frames. Activating a minibuffer 1182on another frame redirects focus to that frame. This puts the focus on 1183the minibuffer's frame, where it belongs, even though the mouse remains 1184in the frame that activated the minibuffer. 1185 1186Selecting a frame can also change focus redirections. Selecting frame 1187@code{bar}, when @code{foo} had been selected, changes any redirections 1188pointing to @code{foo} so that they point to @code{bar} instead. This 1189allows focus redirection to work properly when the user switches from 1190one frame to another using @code{select-window}. 1191 1192This means that a frame whose focus is redirected to itself is treated 1193differently from a frame whose focus is not redirected. 1194@code{select-frame} affects the former but not the latter. 1195 1196The redirection lasts until @code{redirect-frame-focus} is called to 1197change it. 1198@end defun 1199 1200@defopt focus-follows-mouse 1201This option is how you inform Emacs whether the window manager transfers 1202focus when the user moves the mouse. Non-@code{nil} says that it does. 1203When this is so, the command @code{other-frame} moves the mouse to a 1204position consistent with the new selected frame. (This option has no 1205effect on MS-Windows, where the mouse pointer is always automatically 1206moved by the OS to the selected frame.) 1207@end defopt 1208 1209@node Visibility of Frames 1210@section Visibility of Frames 1211@cindex visible frame 1212@cindex invisible frame 1213@cindex iconified frame 1214@cindex frame visibility 1215 1216A window frame may be @dfn{visible}, @dfn{invisible}, or 1217@dfn{iconified}. If it is visible, you can see its contents, unless 1218other windows cover it. If it is iconified, the frame's contents do 1219not appear on the screen, but an icon does. If the frame is 1220invisible, it doesn't show on the screen, not even as an icon. 1221 1222Visibility is meaningless for terminal frames, since only the selected 1223one is actually displayed in any case. 1224 1225@deffn Command make-frame-visible &optional frame 1226This function makes frame @var{frame} visible. If you omit 1227@var{frame}, it makes the selected frame visible. This does not raise 1228the frame, but you can do that with @code{raise-frame} if you wish 1229(@pxref{Raising and Lowering}). 1230@end deffn 1231 1232@deffn Command make-frame-invisible &optional frame force 1233This function makes frame @var{frame} invisible. If you omit 1234@var{frame}, it makes the selected frame invisible. 1235 1236Unless @var{force} is non-@code{nil}, this function refuses to make 1237@var{frame} invisible if all other frames are invisible.. 1238@end deffn 1239 1240@deffn Command iconify-frame &optional frame 1241This function iconifies frame @var{frame}. If you omit @var{frame}, it 1242iconifies the selected frame. 1243@end deffn 1244 1245@defun frame-visible-p frame 1246This returns the visibility status of frame @var{frame}. The value is 1247@code{t} if @var{frame} is visible, @code{nil} if it is invisible, and 1248@code{icon} if it is iconified. 1249 1250On a text-only terminal, all frames are considered visible, whether 1251they are currently being displayed or not, and this function returns 1252@code{t} for all frames. 1253@end defun 1254 1255 The visibility status of a frame is also available as a frame 1256parameter. You can read or change it as such. @xref{Management 1257Parameters}. 1258 1259 The user can iconify and deiconify frames with the window manager. 1260This happens below the level at which Emacs can exert any control, but 1261Emacs does provide events that you can use to keep track of such 1262changes. @xref{Misc Events}. 1263 1264@node Raising and Lowering 1265@section Raising and Lowering Frames 1266 1267 Most window systems use a desktop metaphor. Part of this metaphor is 1268the idea that windows are stacked in a notional third dimension 1269perpendicular to the screen surface, and thus ordered from ``highest'' 1270to ``lowest.'' Where two windows overlap, the one higher up covers 1271the one underneath. Even a window at the bottom of the stack can be 1272seen if no other window overlaps it. 1273 1274@c @cindex raising a frame redundant with raise-frame 1275@cindex lowering a frame 1276 A window's place in this ordering is not fixed; in fact, users tend 1277to change the order frequently. @dfn{Raising} a window means moving 1278it ``up,'' to the top of the stack. @dfn{Lowering} a window means 1279moving it to the bottom of the stack. This motion is in the notional 1280third dimension only, and does not change the position of the window 1281on the screen. 1282 1283 You can raise and lower Emacs frame Windows with these functions: 1284 1285@deffn Command raise-frame &optional frame 1286This function raises frame @var{frame} (default, the selected frame). 1287If @var{frame} is invisible or iconified, this makes it visible. 1288@end deffn 1289 1290@deffn Command lower-frame &optional frame 1291This function lowers frame @var{frame} (default, the selected frame). 1292@end deffn 1293 1294@defopt minibuffer-auto-raise 1295If this is non-@code{nil}, activation of the minibuffer raises the frame 1296that the minibuffer window is in. 1297@end defopt 1298 1299You can also enable auto-raise (raising automatically when a frame is 1300selected) or auto-lower (lowering automatically when it is deselected) 1301for any frame using frame parameters. @xref{Management Parameters}. 1302 1303@node Frame Configurations 1304@section Frame Configurations 1305@cindex frame configuration 1306 1307 A @dfn{frame configuration} records the current arrangement of frames, 1308all their properties, and the window configuration of each one. 1309(@xref{Window Configurations}.) 1310 1311@defun current-frame-configuration 1312This function returns a frame configuration list that describes 1313the current arrangement of frames and their contents. 1314@end defun 1315 1316@defun set-frame-configuration configuration &optional nodelete 1317This function restores the state of frames described in 1318@var{configuration}. However, this function does not restore deleted 1319frames. 1320 1321Ordinarily, this function deletes all existing frames not listed in 1322@var{configuration}. But if @var{nodelete} is non-@code{nil}, the 1323unwanted frames are iconified instead. 1324@end defun 1325 1326@node Mouse Tracking 1327@section Mouse Tracking 1328@cindex mouse tracking 1329@c @cindex tracking the mouse Duplicates track-mouse 1330 1331 Sometimes it is useful to @dfn{track} the mouse, which means to display 1332something to indicate where the mouse is and move the indicator as the 1333mouse moves. For efficient mouse tracking, you need a way to wait until 1334the mouse actually moves. 1335 1336 The convenient way to track the mouse is to ask for events to represent 1337mouse motion. Then you can wait for motion by waiting for an event. In 1338addition, you can easily handle any other sorts of events that may 1339occur. That is useful, because normally you don't want to track the 1340mouse forever---only until some other event, such as the release of a 1341button. 1342 1343@defspec track-mouse body@dots{} 1344This special form executes @var{body}, with generation of mouse motion 1345events enabled. Typically @var{body} would use @code{read-event} to 1346read the motion events and modify the display accordingly. @xref{Motion 1347Events}, for the format of mouse motion events. 1348 1349The value of @code{track-mouse} is that of the last form in @var{body}. 1350You should design @var{body} to return when it sees the up-event that 1351indicates the release of the button, or whatever kind of event means 1352it is time to stop tracking. 1353@end defspec 1354 1355The usual purpose of tracking mouse motion is to indicate on the screen 1356the consequences of pushing or releasing a button at the current 1357position. 1358 1359In many cases, you can avoid the need to track the mouse by using 1360the @code{mouse-face} text property (@pxref{Special Properties}). 1361That works at a much lower level and runs more smoothly than 1362Lisp-level mouse tracking. 1363 1364@ignore 1365@c These are not implemented yet. 1366 1367These functions change the screen appearance instantaneously. The 1368effect is transient, only until the next ordinary Emacs redisplay. That 1369is OK for mouse tracking, since it doesn't make sense for mouse tracking 1370to change the text, and the body of @code{track-mouse} normally reads 1371the events itself and does not do redisplay. 1372 1373@defun x-contour-region window beg end 1374This function draws lines to make a box around the text from @var{beg} 1375to @var{end}, in window @var{window}. 1376@end defun 1377 1378@defun x-uncontour-region window beg end 1379This function erases the lines that would make a box around the text 1380from @var{beg} to @var{end}, in window @var{window}. Use it to remove 1381a contour that you previously made by calling @code{x-contour-region}. 1382@end defun 1383 1384@defun x-draw-rectangle frame left top right bottom 1385This function draws a hollow rectangle on frame @var{frame} with the 1386specified edge coordinates, all measured in pixels from the inside top 1387left corner. It uses the cursor color, the one used for indicating the 1388location of point. 1389@end defun 1390 1391@defun x-erase-rectangle frame left top right bottom 1392This function erases a hollow rectangle on frame @var{frame} with the 1393specified edge coordinates, all measured in pixels from the inside top 1394left corner. Erasure means redrawing the text and background that 1395normally belong in the specified rectangle. 1396@end defun 1397@end ignore 1398 1399@node Mouse Position 1400@section Mouse Position 1401@cindex mouse position 1402@cindex position of mouse 1403 1404 The functions @code{mouse-position} and @code{set-mouse-position} 1405give access to the current position of the mouse. 1406 1407@defun mouse-position 1408This function returns a description of the position of the mouse. The 1409value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x} 1410and @var{y} are integers giving the position in characters relative to 1411the top left corner of the inside of @var{frame}. 1412@end defun 1413 1414@defvar mouse-position-function 1415If non-@code{nil}, the value of this variable is a function for 1416@code{mouse-position} to call. @code{mouse-position} calls this 1417function just before returning, with its normal return value as the 1418sole argument, and it returns whatever this function returns to it. 1419 1420This abnormal hook exists for the benefit of packages like 1421@file{xt-mouse.el} that need to do mouse handling at the Lisp level. 1422@end defvar 1423 1424@defun set-mouse-position frame x y 1425This function @dfn{warps the mouse} to position @var{x}, @var{y} in 1426frame @var{frame}. The arguments @var{x} and @var{y} are integers, 1427giving the position in characters relative to the top left corner of the 1428inside of @var{frame}. If @var{frame} is not visible, this function 1429does nothing. The return value is not significant. 1430@end defun 1431 1432@defun mouse-pixel-position 1433This function is like @code{mouse-position} except that it returns 1434coordinates in units of pixels rather than units of characters. 1435@end defun 1436 1437@defun set-mouse-pixel-position frame x y 1438This function warps the mouse like @code{set-mouse-position} except that 1439@var{x} and @var{y} are in units of pixels rather than units of 1440characters. These coordinates are not required to be within the frame. 1441 1442If @var{frame} is not visible, this function does nothing. The return 1443value is not significant. 1444@end defun 1445 1446@need 3000 1447 1448@node Pop-Up Menus 1449@section Pop-Up Menus 1450 1451 When using a window system, a Lisp program can pop up a menu so that 1452the user can choose an alternative with the mouse. 1453 1454@defun x-popup-menu position menu 1455This function displays a pop-up menu and returns an indication of 1456what selection the user makes. 1457 1458The argument @var{position} specifies where on the screen to put the 1459top left corner of the menu. It can be either a mouse button event 1460(which says to put the menu where the user actuated the button) or a 1461list of this form: 1462 1463@example 1464((@var{xoffset} @var{yoffset}) @var{window}) 1465@end example 1466 1467@noindent 1468where @var{xoffset} and @var{yoffset} are coordinates, measured in 1469pixels, counting from the top left corner of @var{window}. @var{window} 1470may be a window or a frame. 1471 1472If @var{position} is @code{t}, it means to use the current mouse 1473position. If @var{position} is @code{nil}, it means to precompute the 1474key binding equivalents for the keymaps specified in @var{menu}, 1475without actually displaying or popping up the menu. 1476 1477The argument @var{menu} says what to display in the menu. It can be a 1478keymap or a list of keymaps (@pxref{Menu Keymaps}). In this case, the 1479return value is the list of events corresponding to the user's choice. 1480(This list has more than one element if the choice occurred in a 1481submenu.) Note that @code{x-popup-menu} does not actually execute the 1482command bound to that sequence of events. 1483 1484Alternatively, @var{menu} can have the following form: 1485 1486@example 1487(@var{title} @var{pane1} @var{pane2}...) 1488@end example 1489 1490@noindent 1491where each pane is a list of form 1492 1493@example 1494(@var{title} @var{item1} @var{item2}...) 1495@end example 1496 1497Each item should normally be a cons cell @code{(@var{line} . @var{value})}, 1498where @var{line} is a string, and @var{value} is the value to return if 1499that @var{line} is chosen. An item can also be a string; this makes a 1500non-selectable line in the menu. 1501 1502If the user gets rid of the menu without making a valid choice, for 1503instance by clicking the mouse away from a valid choice or by typing 1504keyboard input, then this normally results in a quit and 1505@code{x-popup-menu} does not return. But if @var{position} is a mouse 1506button event (indicating that the user invoked the menu with the 1507mouse) then no quit occurs and @code{x-popup-menu} returns @code{nil}. 1508@end defun 1509 1510 @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu 1511if you could do the job with a prefix key defined with a menu keymap. 1512If you use a menu keymap to implement a menu, @kbd{C-h c} and @kbd{C-h 1513a} can see the individual items in that menu and provide help for them. 1514If instead you implement the menu by defining a command that calls 1515@code{x-popup-menu}, the help facilities cannot know what happens inside 1516that command, so they cannot give any help for the menu's items. 1517 1518 The menu bar mechanism, which lets you switch between submenus by 1519moving the mouse, cannot look within the definition of a command to see 1520that it calls @code{x-popup-menu}. Therefore, if you try to implement a 1521submenu using @code{x-popup-menu}, it cannot work with the menu bar in 1522an integrated fashion. This is why all menu bar submenus are 1523implemented with menu keymaps within the parent menu, and never with 1524@code{x-popup-menu}. @xref{Menu Bar}. 1525 1526 If you want a menu bar submenu to have contents that vary, you should 1527still use a menu keymap to implement it. To make the contents vary, add 1528a hook function to @code{menu-bar-update-hook} to update the contents of 1529the menu keymap as necessary. 1530 1531@node Dialog Boxes 1532@section Dialog Boxes 1533@cindex dialog boxes 1534 1535 A dialog box is a variant of a pop-up menu---it looks a little 1536different, it always appears in the center of a frame, and it has just 1537one level and one or more buttons. The main use of dialog boxes is 1538for asking questions that the user can answer with ``yes,'' ``no,'' 1539and a few other alternatives. With a single button, they can also 1540force the user to acknowledge important information. The functions 1541@code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the 1542keyboard, when called from commands invoked by mouse clicks. 1543 1544@defun x-popup-dialog position contents &optional header 1545This function displays a pop-up dialog box and returns an indication of 1546what selection the user makes. The argument @var{contents} specifies 1547the alternatives to offer; it has this format: 1548 1549@example 1550(@var{title} (@var{string} . @var{value})@dots{}) 1551@end example 1552 1553@noindent 1554which looks like the list that specifies a single pane for 1555@code{x-popup-menu}. 1556 1557The return value is @var{value} from the chosen alternative. 1558 1559As for @code{x-popup-menu}, an element of the list may be just a 1560string instead of a cons cell @code{(@var{string} . @var{value})}. 1561That makes a box that cannot be selected. 1562 1563If @code{nil} appears in the list, it separates the left-hand items from 1564the right-hand items; items that precede the @code{nil} appear on the 1565left, and items that follow the @code{nil} appear on the right. If you 1566don't include a @code{nil} in the list, then approximately half the 1567items appear on each side. 1568 1569Dialog boxes always appear in the center of a frame; the argument 1570@var{position} specifies which frame. The possible values are as in 1571@code{x-popup-menu}, but the precise coordinates or the individual 1572window don't matter; only the frame matters. 1573 1574If @var{header} is non-@code{nil}, the frame title for the box is 1575@samp{Information}, otherwise it is @samp{Question}. The former is used 1576for @code{message-box} (@pxref{message-box}). 1577 1578In some configurations, Emacs cannot display a real dialog box; so 1579instead it displays the same items in a pop-up menu in the center of the 1580frame. 1581 1582If the user gets rid of the dialog box without making a valid choice, 1583for instance using the window manager, then this produces a quit and 1584@code{x-popup-dialog} does not return. 1585@end defun 1586 1587@node Pointer Shape 1588@section Pointer Shape 1589@cindex pointer shape 1590@cindex mouse pointer shape 1591 1592 You can specify the mouse pointer style for particular text or 1593images using the @code{pointer} text property, and for images with the 1594@code{:pointer} and @code{:map} image properties. The values you can 1595use in these properties are @code{text} (or @code{nil}), @code{arrow}, 1596@code{hand}, @code{vdrag}, @code{hdrag}, @code{modeline}, and 1597@code{hourglass}. @code{text} stands for the usual mouse pointer 1598style used over text. 1599 1600 Over void parts of the window (parts that do not correspond to any 1601of the buffer contents), the mouse pointer usually uses the 1602@code{arrow} style, but you can specify a different style (one of 1603those above) by setting @code{void-text-area-pointer}. 1604 1605@defvar void-text-area-pointer 1606This variable specifies the mouse pointer style for void text areas. 1607These include the areas after the end of a line or below the last line 1608in the buffer. The default is to use the @code{arrow} (non-text) 1609pointer style. 1610@end defvar 1611 1612 You can specify what the @code{text} pointer style really looks like 1613by setting the variable @code{x-pointer-shape}. 1614 1615@defvar x-pointer-shape 1616This variable specifies the pointer shape to use ordinarily in the 1617Emacs frame, for the @code{text} pointer style. 1618@end defvar 1619 1620@defvar x-sensitive-text-pointer-shape 1621This variable specifies the pointer shape to use when the mouse 1622is over mouse-sensitive text. 1623@end defvar 1624 1625 These variables affect newly created frames. They do not normally 1626affect existing frames; however, if you set the mouse color of a 1627frame, that also installs the current value of those two variables. 1628@xref{Color Parameters}. 1629 1630 The values you can use, to specify either of these pointer shapes, are 1631defined in the file @file{lisp/term/x-win.el}. Use @kbd{M-x apropos 1632@key{RET} x-pointer @key{RET}} to see a list of them. 1633 1634@node Window System Selections 1635@section Window System Selections 1636@cindex selection (for window systems) 1637 1638The X server records a set of @dfn{selections} which permit transfer of 1639data between application programs. The various selections are 1640distinguished by @dfn{selection types}, represented in Emacs by 1641symbols. X clients including Emacs can read or set the selection for 1642any given type. 1643 1644@deffn Command x-set-selection type data 1645This function sets a ``selection'' in the X server. It takes two 1646arguments: a selection type @var{type}, and the value to assign to it, 1647@var{data}. If @var{data} is @code{nil}, it means to clear out the 1648selection. Otherwise, @var{data} may be a string, a symbol, an integer 1649(or a cons of two integers or list of two integers), an overlay, or a 1650cons of two markers pointing to the same buffer. An overlay or a pair 1651of markers stands for text in the overlay or between the markers. 1652 1653The argument @var{data} may also be a vector of valid non-vector 1654selection values. 1655 1656Each possible @var{type} has its own selection value, which changes 1657independently. The usual values of @var{type} are @code{PRIMARY}, 1658@code{SECONDARY} and @code{CLIPBOARD}; these are symbols with upper-case 1659names, in accord with X Window System conventions. If @var{type} is 1660@code{nil}, that stands for @code{PRIMARY}. 1661 1662This function returns @var{data}. 1663@end deffn 1664 1665@defun x-get-selection &optional type data-type 1666This function accesses selections set up by Emacs or by other X 1667clients. It takes two optional arguments, @var{type} and 1668@var{data-type}. The default for @var{type}, the selection type, is 1669@code{PRIMARY}. 1670 1671The @var{data-type} argument specifies the form of data conversion to 1672use, to convert the raw data obtained from another X client into Lisp 1673data. Meaningful values include @code{TEXT}, @code{STRING}, 1674@code{UTF8_STRING}, @code{TARGETS}, @code{LENGTH}, @code{DELETE}, 1675@code{FILE_NAME}, @code{CHARACTER_POSITION}, @code{NAME}, 1676@code{LINE_NUMBER}, @code{COLUMN_NUMBER}, @code{OWNER_OS}, 1677@code{HOST_NAME}, @code{USER}, @code{CLASS}, @code{ATOM}, and 1678@code{INTEGER}. (These are symbols with upper-case names in accord 1679with X conventions.) The default for @var{data-type} is 1680@code{STRING}. 1681@end defun 1682 1683@cindex cut buffer 1684The X server also has a set of eight numbered @dfn{cut buffers} which can 1685store text or other data being moved between applications. Cut buffers 1686are considered obsolete, but Emacs supports them for the sake of X 1687clients that still use them. Cut buffers are numbered from 0 to 7. 1688 1689@defun x-get-cut-buffer &optional n 1690This function returns the contents of cut buffer number @var{n}. 1691If omitted @var{n} defaults to 0. 1692@end defun 1693 1694@defun x-set-cut-buffer string &optional push 1695@anchor{Definition of x-set-cut-buffer} 1696This function stores @var{string} into the first cut buffer (cut buffer 16970). If @var{push} is @code{nil}, only the first cut buffer is changed. 1698If @var{push} is non-@code{nil}, that says to move the values down 1699through the series of cut buffers, much like the way successive kills in 1700Emacs move down the kill ring. In other words, the previous value of 1701the first cut buffer moves into the second cut buffer, and the second to 1702the third, and so on through all eight cut buffers. 1703@end defun 1704 1705@defvar selection-coding-system 1706This variable specifies the coding system to use when reading and 1707writing selections or the clipboard. @xref{Coding 1708Systems}. The default is @code{compound-text-with-extensions}, which 1709converts to the text representation that X11 normally uses. 1710@end defvar 1711 1712@cindex clipboard support (for MS-Windows) 1713When Emacs runs on MS-Windows, it does not implement X selections in 1714general, but it does support the clipboard. @code{x-get-selection} 1715and @code{x-set-selection} on MS-Windows support the text data type 1716only; if the clipboard holds other types of data, Emacs treats the 1717clipboard as empty. 1718 1719@cindex scrap support (for Mac OS) 1720On Mac OS, selection-like data transfer between applications is 1721performed through a mechanism called @dfn{scraps}. The clipboard is a 1722particular scrap named @code{com.apple.scrap.clipboard}. Types of scrap 1723data are called @dfn{scrap flavor types}, which are identified by 1724four-char codes such as @code{TEXT}. Emacs associates a selection with 1725a scrap, and a selection type with a scrap flavor type via 1726@code{mac-scrap-name} and @code{mac-ostype} properties, respectively. 1727 1728@example 1729(get 'CLIPBOARD 'mac-scrap-name) 1730 @result{} "com.apple.scrap.clipboard" 1731(get 'com.apple.traditional-mac-plain-text 'mac-ostype) 1732 @result{} "TEXT" 1733@end example 1734 1735Conventionally, selection types for scrap flavor types on Mac OS have 1736the form of @acronym{UTI, Uniform Type Identifier} such as 1737@code{com.apple.traditional-mac-plain-text}, 1738@code{public.utf16-plain-text}, and @code{public.file-url}. 1739 1740@defopt x-select-enable-clipboard 1741If this is non-@code{nil}, the Emacs yank functions consult the 1742clipboard before the primary selection, and the kill functions store in 1743the clipboard as well as the primary selection. Otherwise they do not 1744access the clipboard at all. The default is @code{nil} on most systems, 1745but @code{t} on MS-Windows and Mac. 1746@end defopt 1747 1748@node Drag and Drop 1749@section Drag and Drop 1750 1751@vindex x-dnd-test-function 1752@vindex x-dnd-known-types 1753 When a user drags something from another application over Emacs, that other 1754application expects Emacs to tell it if Emacs can handle the data that is 1755dragged. The variable @code{x-dnd-test-function} is used by Emacs to determine 1756what to reply. The default value is @code{x-dnd-default-test-function} 1757which accepts drops if the type of the data to be dropped is present in 1758@code{x-dnd-known-types}. You can customize @code{x-dnd-test-function} and/or 1759@code{x-dnd-known-types} if you want Emacs to accept or reject drops based 1760on some other criteria. 1761 1762@vindex x-dnd-types-alist 1763 If you want to change the way Emacs handles drop of different types 1764or add a new type, customize @code{x-dnd-types-alist}. This requires 1765detailed knowledge of what types other applications use for drag and 1766drop. 1767 1768@vindex dnd-protocol-alist 1769 When an URL is dropped on Emacs it may be a file, but it may also be 1770another URL type (ftp, http, etc.). Emacs first checks 1771@code{dnd-protocol-alist} to determine what to do with the URL. If 1772there is no match there and if @code{browse-url-browser-function} is 1773an alist, Emacs looks for a match there. If no match is found the 1774text for the URL is inserted. If you want to alter Emacs behavior, 1775you can customize these variables. 1776 1777@node Color Names 1778@section Color Names 1779 1780@cindex color names 1781@cindex specify color 1782@cindex numerical RGB color specification 1783 A color name is text (usually in a string) that specifies a color. 1784Symbolic names such as @samp{black}, @samp{white}, @samp{red}, etc., 1785are allowed; use @kbd{M-x list-colors-display} to see a list of 1786defined names. You can also specify colors numerically in forms such 1787as @samp{#@var{rgb}} and @samp{RGB:@var{r}/@var{g}/@var{b}}, where 1788@var{r} specifies the red level, @var{g} specifies the green level, 1789and @var{b} specifies the blue level. You can use either one, two, 1790three, or four hex digits for @var{r}; then you must use the same 1791number of hex digits for all @var{g} and @var{b} as well, making 1792either 3, 6, 9 or 12 hex digits in all. (See the documentation of the 1793X Window System for more details about numerical RGB specification of 1794colors.) 1795 1796 These functions provide a way to determine which color names are 1797valid, and what they look like. In some cases, the value depends on the 1798@dfn{selected frame}, as described below; see @ref{Input Focus}, for the 1799meaning of the term ``selected frame.'' 1800 1801@defun color-defined-p color &optional frame 1802This function reports whether a color name is meaningful. It returns 1803@code{t} if so; otherwise, @code{nil}. The argument @var{frame} says 1804which frame's display to ask about; if @var{frame} is omitted or 1805@code{nil}, the selected frame is used. 1806 1807Note that this does not tell you whether the display you are using 1808really supports that color. When using X, you can ask for any defined 1809color on any kind of display, and you will get some result---typically, 1810the closest it can do. To determine whether a frame can really display 1811a certain color, use @code{color-supported-p} (see below). 1812 1813@findex x-color-defined-p 1814This function used to be called @code{x-color-defined-p}, 1815and that name is still supported as an alias. 1816@end defun 1817 1818@defun defined-colors &optional frame 1819This function returns a list of the color names that are defined 1820and supported on frame @var{frame} (default, the selected frame). 1821If @var{frame} does not support colors, the value is @code{nil}. 1822 1823@findex x-defined-colors 1824This function used to be called @code{x-defined-colors}, 1825and that name is still supported as an alias. 1826@end defun 1827 1828@defun color-supported-p color &optional frame background-p 1829This returns @code{t} if @var{frame} can really display the color 1830@var{color} (or at least something close to it). If @var{frame} is 1831omitted or @code{nil}, the question applies to the selected frame. 1832 1833Some terminals support a different set of colors for foreground and 1834background. If @var{background-p} is non-@code{nil}, that means you are 1835asking whether @var{color} can be used as a background; otherwise you 1836are asking whether it can be used as a foreground. 1837 1838The argument @var{color} must be a valid color name. 1839@end defun 1840 1841@defun color-gray-p color &optional frame 1842This returns @code{t} if @var{color} is a shade of gray, as defined on 1843@var{frame}'s display. If @var{frame} is omitted or @code{nil}, the 1844question applies to the selected frame. If @var{color} is not a valid 1845color name, this function returns @code{nil}. 1846@end defun 1847 1848@defun color-values color &optional frame 1849@cindex rgb value 1850This function returns a value that describes what @var{color} should 1851ideally look like on @var{frame}. If @var{color} is defined, the 1852value is a list of three integers, which give the amount of red, the 1853amount of green, and the amount of blue. Each integer ranges in 1854principle from 0 to 65535, but some displays may not use the full 1855range. This three-element list is called the @dfn{rgb values} of the 1856color. 1857 1858If @var{color} is not defined, the value is @code{nil}. 1859 1860@example 1861(color-values "black") 1862 @result{} (0 0 0) 1863(color-values "white") 1864 @result{} (65280 65280 65280) 1865(color-values "red") 1866 @result{} (65280 0 0) 1867(color-values "pink") 1868 @result{} (65280 49152 51968) 1869(color-values "hungry") 1870 @result{} nil 1871@end example 1872 1873The color values are returned for @var{frame}'s display. If 1874@var{frame} is omitted or @code{nil}, the information is returned for 1875the selected frame's display. If the frame cannot display colors, the 1876value is @code{nil}. 1877 1878@findex x-color-values 1879This function used to be called @code{x-color-values}, 1880and that name is still supported as an alias. 1881@end defun 1882 1883@node Text Terminal Colors 1884@section Text Terminal Colors 1885@cindex colors on text-only terminals 1886 1887 Text-only terminals usually support only a small number of colors, 1888and the computer uses small integers to select colors on the terminal. 1889This means that the computer cannot reliably tell what the selected 1890color looks like; instead, you have to inform your application which 1891small integers correspond to which colors. However, Emacs does know 1892the standard set of colors and will try to use them automatically. 1893 1894 The functions described in this section control how terminal colors 1895are used by Emacs. 1896 1897 Several of these functions use or return @dfn{rgb values}, described 1898in @ref{Color Names}. 1899 1900 These functions accept a display (either a frame or the name of a 1901terminal) as an optional argument. We hope in the future to make Emacs 1902support more than one text-only terminal at one time; then this argument 1903will specify which terminal to operate on (the default being the 1904selected frame's terminal; @pxref{Input Focus}). At present, though, 1905the @var{frame} argument has no effect. 1906 1907@defun tty-color-define name number &optional rgb frame 1908This function associates the color name @var{name} with 1909color number @var{number} on the terminal. 1910 1911The optional argument @var{rgb}, if specified, is an rgb value, a list 1912of three numbers that specify what the color actually looks like. 1913If you do not specify @var{rgb}, then this color cannot be used by 1914@code{tty-color-approximate} to approximate other colors, because 1915Emacs will not know what it looks like. 1916@end defun 1917 1918@defun tty-color-clear &optional frame 1919This function clears the table of defined colors for a text-only terminal. 1920@end defun 1921 1922@defun tty-color-alist &optional frame 1923This function returns an alist recording the known colors supported by a 1924text-only terminal. 1925 1926Each element has the form @code{(@var{name} @var{number} . @var{rgb})} 1927or @code{(@var{name} @var{number})}. Here, @var{name} is the color 1928name, @var{number} is the number used to specify it to the terminal. 1929If present, @var{rgb} is a list of three color values (for red, green, 1930and blue) that says what the color actually looks like. 1931@end defun 1932 1933@defun tty-color-approximate rgb &optional frame 1934This function finds the closest color, among the known colors 1935supported for @var{display}, to that described by the rgb value 1936@var{rgb} (a list of color values). The return value is an element of 1937@code{tty-color-alist}. 1938@end defun 1939 1940@defun tty-color-translate color &optional frame 1941This function finds the closest color to @var{color} among the known 1942colors supported for @var{display} and returns its index (an integer). 1943If the name @var{color} is not defined, the value is @code{nil}. 1944@end defun 1945 1946@node Resources 1947@section X Resources 1948 1949@defun x-get-resource attribute class &optional component subclass 1950The function @code{x-get-resource} retrieves a resource value from the X 1951Window defaults database. 1952 1953Resources are indexed by a combination of a @dfn{key} and a @dfn{class}. 1954This function searches using a key of the form 1955@samp{@var{instance}.@var{attribute}} (where @var{instance} is the name 1956under which Emacs was invoked), and using @samp{Emacs.@var{class}} as 1957the class. 1958 1959The optional arguments @var{component} and @var{subclass} add to the key 1960and the class, respectively. You must specify both of them or neither. 1961If you specify them, the key is 1962@samp{@var{instance}.@var{component}.@var{attribute}}, and the class is 1963@samp{Emacs.@var{class}.@var{subclass}}. 1964@end defun 1965 1966@defvar x-resource-class 1967This variable specifies the application name that @code{x-get-resource} 1968should look up. The default value is @code{"Emacs"}. You can examine X 1969resources for application names other than ``Emacs'' by binding this 1970variable to some other string, around a call to @code{x-get-resource}. 1971@end defvar 1972 1973@defvar x-resource-name 1974This variable specifies the instance name that @code{x-get-resource} 1975should look up. The default value is the name Emacs was invoked with, 1976or the value specified with the @samp{-name} or @samp{-rn} switches. 1977@end defvar 1978 1979To illustrate some of the above, suppose that you have the line: 1980 1981@example 1982xterm.vt100.background: yellow 1983@end example 1984 1985@noindent 1986in your X resources file (whose name is usually @file{~/.Xdefaults} 1987or @file{~/.Xresources}). Then: 1988 1989@example 1990@group 1991(let ((x-resource-class "XTerm") (x-resource-name "xterm")) 1992 (x-get-resource "vt100.background" "VT100.Background")) 1993 @result{} "yellow" 1994@end group 1995@group 1996(let ((x-resource-class "XTerm") (x-resource-name "xterm")) 1997 (x-get-resource "background" "VT100" "vt100" "Background")) 1998 @result{} "yellow" 1999@end group 2000@end example 2001 2002 @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}. 2003 2004@node Display Feature Testing 2005@section Display Feature Testing 2006@cindex display feature testing 2007 2008 The functions in this section describe the basic capabilities of a 2009particular display. Lisp programs can use them to adapt their behavior 2010to what the display can do. For example, a program that ordinarily uses 2011a popup menu could use the minibuffer if popup menus are not supported. 2012 2013 The optional argument @var{display} in these functions specifies which 2014display to ask the question about. It can be a display name, a frame 2015(which designates the display that frame is on), or @code{nil} (which 2016refers to the selected frame's display, @pxref{Input Focus}). 2017 2018 @xref{Color Names}, @ref{Text Terminal Colors}, for other functions to 2019obtain information about displays. 2020 2021@defun display-popup-menus-p &optional display 2022This function returns @code{t} if popup menus are supported on 2023@var{display}, @code{nil} if not. Support for popup menus requires that 2024the mouse be available, since the user cannot choose menu items without 2025a mouse. 2026@end defun 2027 2028@defun display-graphic-p &optional display 2029This function returns @code{t} if @var{display} is a graphic display 2030capable of displaying several frames and several different fonts at 2031once. This is true for displays that use a window system such as X, and 2032false for text-only terminals. 2033@end defun 2034 2035@defun display-mouse-p &optional display 2036@cindex mouse, availability 2037This function returns @code{t} if @var{display} has a mouse available, 2038@code{nil} if not. 2039@end defun 2040 2041@defun display-color-p &optional display 2042@findex x-display-color-p 2043This function returns @code{t} if the screen is a color screen. 2044It used to be called @code{x-display-color-p}, and that name 2045is still supported as an alias. 2046@end defun 2047 2048@defun display-grayscale-p &optional display 2049This function returns @code{t} if the screen can display shades of gray. 2050(All color displays can do this.) 2051@end defun 2052 2053@defun display-supports-face-attributes-p attributes &optional display 2054@anchor{Display Face Attribute Testing} 2055This function returns non-@code{nil} if all the face attributes in 2056@var{attributes} are supported (@pxref{Face Attributes}). 2057 2058The definition of `supported' is somewhat heuristic, but basically 2059means that a face containing all the attributes in @var{attributes}, 2060when merged with the default face for display, can be represented in a 2061way that's 2062 2063@enumerate 2064@item 2065different in appearance than the default face, and 2066 2067@item 2068`close in spirit' to what the attributes specify, if not exact. 2069@end enumerate 2070 2071Point (2) implies that a @code{:weight black} attribute will be 2072satisfied by any display that can display bold, as will 2073@code{:foreground "yellow"} as long as some yellowish color can be 2074displayed, but @code{:slant italic} will @emph{not} be satisfied by 2075the tty display code's automatic substitution of a `dim' face for 2076italic. 2077@end defun 2078 2079@defun display-selections-p &optional display 2080This function returns @code{t} if @var{display} supports selections. 2081Windowed displays normally support selections, but they may also be 2082supported in some other cases. 2083@end defun 2084 2085@defun display-images-p &optional display 2086This function returns @code{t} if @var{display} can display images. 2087Windowed displays ought in principle to handle images, but some 2088systems lack the support for that. On a display that does not support 2089images, Emacs cannot display a tool bar. 2090@end defun 2091 2092@defun display-screens &optional display 2093This function returns the number of screens associated with the display. 2094@end defun 2095 2096@defun display-pixel-height &optional display 2097This function returns the height of the screen in pixels. 2098On a character terminal, it gives the height in characters. 2099 2100For graphical terminals, note that on ``multi-monitor'' setups this 2101refers to the pixel width for all physical monitors associated with 2102@var{display}. @xref{Multiple Displays}. 2103@end defun 2104 2105@defun display-pixel-width &optional display 2106This function returns the width of the screen in pixels. 2107On a character terminal, it gives the width in characters. 2108 2109For graphical terminals, note that on ``multi-monitor'' setups this 2110refers to the pixel width for all physical monitors associated with 2111@var{display}. @xref{Multiple Displays}. 2112@end defun 2113 2114@defun display-mm-height &optional display 2115This function returns the height of the screen in millimeters, 2116or @code{nil} if Emacs cannot get that information. 2117@end defun 2118 2119@defun display-mm-width &optional display 2120This function returns the width of the screen in millimeters, 2121or @code{nil} if Emacs cannot get that information. 2122@end defun 2123 2124@defvar display-mm-dimensions-alist 2125This variable allows the user to specify the dimensions of graphical 2126displays returned by @code{display-mm-height} and 2127@code{display-mm-width} in case the system provides incorrect values. 2128@end defvar 2129 2130@defun display-backing-store &optional display 2131This function returns the backing store capability of the display. 2132Backing store means recording the pixels of windows (and parts of 2133windows) that are not exposed, so that when exposed they can be 2134displayed very quickly. 2135 2136Values can be the symbols @code{always}, @code{when-mapped}, or 2137@code{not-useful}. The function can also return @code{nil} 2138when the question is inapplicable to a certain kind of display. 2139@end defun 2140 2141@defun display-save-under &optional display 2142This function returns non-@code{nil} if the display supports the 2143SaveUnder feature. That feature is used by pop-up windows 2144to save the pixels they obscure, so that they can pop down 2145quickly. 2146@end defun 2147 2148@defun display-planes &optional display 2149This function returns the number of planes the display supports. 2150This is typically the number of bits per pixel. 2151For a tty display, it is log to base two of the number of colors supported. 2152@end defun 2153 2154@defun display-visual-class &optional display 2155This function returns the visual class for the screen. The value is one 2156of the symbols @code{static-gray}, @code{gray-scale}, 2157@code{static-color}, @code{pseudo-color}, @code{true-color}, and 2158@code{direct-color}. 2159@end defun 2160 2161@defun display-color-cells &optional display 2162This function returns the number of color cells the screen supports. 2163@end defun 2164 2165 These functions obtain additional information specifically 2166about X displays. 2167 2168@defun x-server-version &optional display 2169This function returns the list of version numbers of the X server 2170running the display. The value is a list of three integers: the major 2171and minor version numbers of the X protocol, and the 2172distributor-specific release number of the X server software itself. 2173@end defun 2174 2175@defun x-server-vendor &optional display 2176This function returns the ``vendor'' that provided the X server 2177software (as a string). Really this means whoever distributes the X 2178server. 2179 2180When the developers of X labelled software distributors as 2181``vendors,'' they showed their false assumption that no system could 2182ever be developed and distributed noncommercially. 2183@end defun 2184 2185@ignore 2186@defvar x-no-window-manager 2187This variable's value is @code{t} if no X window manager is in use. 2188@end defvar 2189@end ignore 2190 2191@ignore 2192@item 2193The functions @code{x-pixel-width} and @code{x-pixel-height} return the 2194width and height of an X Window frame, measured in pixels. 2195@end ignore 2196 2197@ignore 2198 arch-tag: 94977df6-3dca-4730-b57b-c6329e9282ba 2199@end ignore 2200