emacs / lispref / frames.texi

   1
   2
   3
   4
   5
   6
   7
   8
   9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29
  30
  31
  32
  33
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43
  44
  45
  46
  47
  48
  49
  50
  51
  52
  53
  54
  55
  56
  57
  58
  59
  60
  61
  62
  63
  64
  65
  66
  67
  68
  69
  70
  71
  72
  73
  74
  75
  76
  77
  78
  79
  80
  81
  82
  83
  84
  85
  86
  87
  88
  89
  90
  91
  92
  93
  94
  95
  96
  97
  98
  99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111
 112
 113
 114
 115
 116
 117
 118
 119
 120
 121
 122
 123
 124
 125
 126
 127
 128
 129
 130
 131
 132
 133
 134
 135
 136
 137
 138
 139
 140
 141
 142
 143
 144
 145
 146
 147
 148
 149
 150
 151
 152
 153
 154
 155
 156
 157
 158
 159
 160
 161
 162
 163
 164
 165
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175
 176
 177
 178
 179
 180
 181
 182
 183
 184
 185
 186
 187
 188
 189
 190
 191
 192
 193
 194
 195
 196
 197
 198
 199
 200
 201
 202
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338
 339
 340
 341
 342
 343
 344
 345
 346
 347
 348
 349
 350
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360
 361
 362
 363
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. 
@c See the file elisp.texi for copying conditions.
@setfilename ../info/frames
@node Frames, Positions, Windows, Top
@chapter Frames
@cindex frame

  A @dfn{frame} is a rectangle on the screen that contains one or more
Emacs windows.  A frame initially contains a single main window (plus
perhaps a minibuffer window), which you can subdivide vertically or
horizontally into smaller windows.

@cindex terminal frame
@cindex X window frame
  When Emacs runs on a text-only terminal, it starts with one
@dfn{terminal frame}.  If you create additional ones, Emacs displays
one and only one at any given time---on the terminal screen, of course.

  When Emacs communicates directly with an X server, it does not have a
terminal frame; instead, it starts with a single @dfn{X window frame}.
It can display multiple X window frames at the same time, each in its
own X window.

@defun framep object
This predicate returns @code{t} if @var{object} is a frame, and
@code{nil} otherwise.
@end defun

@menu
* Creating Frames::		Creating additional frames.
* Multiple Displays::           Creating frames on other X displays.
* Frame Parameters::		Controlling frame size, position, font, etc.
* Frame Titles::                Automatic updating of frame titles.
* Deleting Frames::		Frames last until explicitly deleted.
* Finding All Frames::		How to examine all existing frames.
* Frames and Windows::		A frame contains windows;
				  display of text always works through windows.
* Minibuffers and Frames::	How a frame finds the minibuffer to use.
* Input Focus::			Specifying the selected frame.
* Visibility of Frames::	Frames may be visible or invisible, or icons.
* Raising and Lowering::	Raising a frame makes it hide other X windows;
				  lowering it makes the others hide them.
* Frame Configurations::	Saving the state of all frames.
* Mouse Tracking::		Getting events that say when the mouse moves.
* Mouse Position::		Asking where the mouse is, or moving it.
* Pop-Up Menus::		Displaying a menu for the user to select from.
* Dialog Boxes::                Displaying a box to ask yes or no.
* Pointer Shapes::              Specifying the shape of the mouse pointer.
* X Selections::		Transferring text to and from other X clients.
* Color Names::	                Getting the definitions of color names.
* Resources::		        Getting resource values from the server.
* Server Data::		        Getting info about the X server.
@end menu

  @xref{Display}, for related information.

@node Creating Frames
@section Creating Frames

To create a new frame, call the function @code{make-frame}.

@defun make-frame &optional alist
This function creates a new frame.  If you are using X, it makes
an X window frame; otherwise, it makes a terminal frame.

The argument is an alist specifying frame parameters.  Any parameters
not mentioned in @var{alist} default according to the value of the
variable @code{default-frame-alist}; parameters not specified even there
default from the standard X defaults file and X resources.

The set of possible parameters depends in principle on what kind of
window system Emacs uses to display its frames.  @xref{X Frame
Parameters}, for documentation of individual parameters you can specify.
@end defun

@defvar before-make-frame-hook
A normal hook run by @code{make-frame} before it actually creates the
frame.
@end defvar

@defvar after-make-frame-hook
A normal hook run by @code{make-frame} after it creates the frame.
@end defvar

@node Multiple Displays
@section Multiple Displays
@cindex multiple displays
@cindex multiple X terminals
@cindex displays, multiple

  A single Emacs can talk to more than one X Windows display.
Initially, Emacs uses just one display---the one chosen with the
@code{DISPLAY} environment variable or with the @samp{--display} option
(@pxref{Initial Options,,, emacs, The GNU Emacs Manual}).  To connect to
another display, use the command @code{make-frame-on-display} or specify
the @code{display} frame parameter when you create the frame.

  Emacs treats each X server as a separate terminal, giving each one its
own selected frame and its own minibuffer windows.  A few Lisp variables
have values local to the current terminal (that is, the terminal
corresponding to the currently selected frame): these are
@code{default-minibuffer-frame}, @code{defining-kbd-macro},
@code{last-kbd-macro}, and @code{system-key-alist}.  These variables are
always terminal-local and can never be buffer-local.

  A single X server can handle more than one screen.  A display name
@samp{@var{host}.@var{server}.@var{screen}} has three parts; the last
part specifies the screen number for a given server.  When you use two
screens belonging to one server, Emacs knows by the similarity in their
names that they share a single keyboard, and it treats them as a single
terminal.

@deffn Command make-frame-on-display display &optional parameters
This creates a new frame on display @var{display}, taking the other
frame parameters from @var{parameters}.  Aside from the @var{display}
argument, it is like @code{make-frame} (@pxref{Creating Frames}).
@end deffn

@defun x-display-list
This returns a list that indicates which X displays Emacs has a
connection to.  The elements of the list are strings, and each one is
a display name.
@end defun

@defun x-open-connection display &optional xrm-string
This function opens a connection to the X display @var{display}.  It
does not create a frame on that display, but it permits you to check
that communication can be established with that display.

The optional argument @var{resource-string}, if not @code{nil}, is a
string of resource names and values, in the same format used in the
@file{.Xresources} file.  The values you specify override the resource
values recorded in the X server itself; they apply to all Emacs frames
created on this display.  Here's an example of what this string might
look like:

@example
"*BorderWidth: 3\n*InternalBorder: 2\n"
@end example

@xref{Resources}.
@end defun

@defun x-close-connection display
This function closes the connection to display @var{display}.  Before
you can do this, you must first delete all the frames that were open on
that display (@pxref{Deleting Frames}).
@end defun

@node Frame Parameters
@section Frame Parameters

A frame has many parameters that control its appearance and behavior.
Just what parameters a frame has depends on what display mechanism it
uses.

Frame parameters exist for the sake of window systems.  A terminal frame
has a few parameters, mostly for compatibility's sake; only the height,
width and @code{buffer-predicate} parameters really do something.

@menu
* Parameter Access::       How to change a frame's parameters.
* Initial Parameters::	   Specifying frame parameters when you make a frame.
* X Frame Parameters::     List of frame parameters.
* Size and Position::      Changing the size and position of a frame.
@end menu

@node Parameter Access
@subsection Access to Frame Parameters

These functions let you read and change the parameter values of a
frame.

@defun frame-parameters frame
The function @code{frame-parameters} returns an alist listing all the
parameters of @var{frame} and their values.
@end defun

@defun modify-frame-parameters frame alist
This function alters the parameters of frame @var{frame} based on the
elements of @var{alist}.  Each element of @var{alist} has the form
@code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a
parameter.  If you don't mention a parameter in @var{alist}, its value
doesn't change.
@end defun

@node Initial Parameters
@subsection Initial Frame Parameters

You can specify the parameters for the initial startup frame
by setting @code{initial-frame-alist} in your @file{.emacs} file.

@defvar initial-frame-alist
This variable's value is an alist of parameter values used when creating
the initial X window frame.  Each element has the form:

@example
(@var{parameter} . @var{value})
@end example

Emacs creates the initial frame before it reads your @file{~/.emacs}
file.  After reading that file, Emacs checks @code{initial-frame-alist},
and applies the parameter settings in the altered value to the already
created initial frame.

If these settings affect the frame geometry and appearance, you'll see
the frame appear with the wrong ones and then change to the specified
ones.  If that bothers you, you can specify the same geometry and
appearance with X resources; those do take affect before the frame is
created.  @xref{Resources X,, X Resources, emacs, The GNU Emacs Manual}.

X resource settings typically apply to all frames.  If you want to
specify some X resources solely for the sake of the initial frame, and
you don't want them to apply to subsequent frames, here's how to achieve
this.  Specify parameters in @code{default-frame-alist} to override the
X resources for subsequent frames; then, to prevent these from affecting
the initial frame, specify the same parameters in
@code{initial-frame-alist} with values that match the X resources.
@end defvar

If these parameters specify a separate minibuffer-only frame with
@code{(minibuffer . nil)}, and you have not created one, Emacs creates
one for you.

@defvar minibuffer-frame-alist
This variable's value is an alist of parameter values used when creating
an initial minibuffer-only frame---if such a frame is needed, according
to the parameters for the main initial frame.
@end defvar

@defvar default-frame-alist
This is an alist specifying default values of frame parameters for
subsequent Emacs frames (not the initial ones).
@end defvar

See also @code{special-display-frame-alist}, in @ref{Choosing Window}.

If you use options that specify window appearance when you invoke Emacs,
they take effect by adding elements to @code{default-frame-alist}.  One
exception is @samp{-geometry}, which adds the specified position to
@code{initial-frame-alist} instead.  @xref{Command Arguments,,, emacs,
The GNU Emacs Manual}.

@node X Frame Parameters
@subsection X Window Frame Parameters

Just what parameters a frame has depends on what display mechanism it
uses.  Here is a table of the parameters of an X window frame; of these,
@code{name}, @code{height}, @code{width}, and @code{buffer-predicate}
provide meaningful information in non-X frames.

@table @code
@item name
The name of the frame.  Most window managers display the frame's name in
the frame's border, at the top of the frame.  If you don't specify a
name, and you have more than one frame, Emacs sets the frame name based
on the buffer displayed in the frame's selected window.

If you specify the frame name explicitly when you create the frame, the
name is also used (instead of the name of the Emacs executable) when
looking up X resources for the frame.

@item display
The display on which to open this frame.  It should be a string of the
form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
@code{DISPLAY} environment variable.

@item left
The screen position of the left edge, in pixels, with respect to the
left edge of the screen.  The value may be a positive number @var{pos},
or a list of the form @code{(+ @var{pos})} which permits specifying a
negative @var{pos} value.

A negative number @minus{}@var{pos}, or a list of the form @code{(-
@var{pos})}, actually specifies the position of the right edge of the
window with respect to the right edge of the screen.  A positive value
of @var{pos} counts toward the left.  If the parameter is a negative
integer @minus{}@var{pos} then @var{pos} is positive!

Some window managers ignore program-specified positions.  If you want to
be sure the position you specify is not ignored, specify a
non-@code{nil} value for the @code{user-position} parameter as well.

@item top
The screen position of the top edge, in pixels, with respect to the
top edge of the screen.  The value may be a positive number @var{pos},
or a list of the form @code{(+ @var{pos})} which permits specifying a
negative @var{pos} value.

A negative number @minus{}@var{pos}, or a list of the form @code{(-
@var{pos})}, actually specifies the position of the bottom edge of the
window with respect to the bottom edge of the screen.  A positive value
of @var{pos} counts toward the top.  If the parameter is a negative
integer @minus{}@var{pos} then @var{pos} is positive!

Some window managers ignore program-specified positions.  If you want to
be sure the position you specify is not ignored, specify a
non-@code{nil} value for the @code{user-position} parameter as well.

@item icon-left
The screen position of the left edge @emph{of the frame's icon}, in
pixels, counting from the left edge of the screen.  This takes effect if
and when the frame is iconified.

@item icon-top
The screen position of the top edge @emph{of the frame's icon}, in
pixels, counting from the top edge of the screen.  This takes effect if
and when the frame is iconified.

@item user-position
Non-@code{nil} if the screen position of the frame was explicitly
requested by the user (for example, with the @samp{-geometry} option).
Nothing automatically makes this parameter non-@code{nil}; it is up to
Lisp programs that call @code{make-frame} to specify this parameter to
indicate that the values of the @code{left} and @code{top} parameters
are user-specified positions.

@item height
The height of the frame contents, in characters.  (To get the height in
pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.)

@item width
The width of the frame contents, in characters.  (To get the height in
pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)

@item window-id
The number of the X window for the frame.

@item minibuffer
Whether this frame has its own minibuffer.  The value @code{t} means
yes, @code{nil} means no, @code{only} means this frame is just a
minibuffer.  If the value is a minibuffer window (in some other frame),
the new frame uses that minibuffer.

@item buffer-predicate
The buffer-predicate function for this frame.  The function
@code{other-buffer} uses this predicate (from the selected frame) to
decide which buffers it should consider, if the predicate is not
@code{nil}.  It calls the predicate with one arg, a buffer, once for
each buffer; if the predicate returns a non-@code{nil} value, it
considers that buffer.

@item font
The name of the font for displaying text in the frame.  This is a
string.

@item auto-raise
Whether selecting the frame raises it (non-@code{nil} means yes).

@item auto-lower
Whether deselecting the frame lowers it (non-@code{nil} means yes).

@item vertical-scroll-bars
Whether the frame has scroll bars for vertical scrolling
(non-@code{nil} means yes).

@item horizontal-scroll-bars
Whether the frame has scroll bars for horizontal scrolling
(non-@code{nil} means yes).  (Horizontal scroll bars are not currently
implemented.)

@item scroll-bar-width
The width of the vertical scroll bar, in pixels.

@item icon-type
The type of icon to use for this frame when it is iconified.  If the
value is a string, that specifies a file containing a bitmap to use.
Any other non-@code{nil} value specifies the default bitmap icon (a
picture of a gnu); @code{nil} specifies a text icon.

@item icon-name
The name to use in the icon for this frame, when and if the icon
appears.  If this is @code{nil}, the frame's title is used.

@item foreground-color
The color to use for the image of a character.  This is a string; the X
server defines the meaningful color names.

@item background-color
The color to use for the background of characters.

@item mouse-color
The color for the mouse pointer.

@item cursor-color
The color for the cursor that shows point.

@item border-color
The color for the border of the frame.

@item cursor-type
The way to display the cursor.  The legitimate values are @code{bar},
@code{box}, and @code{(bar . @var{width})}.  The symbol @code{box}
specifies an ordinary black box overlaying the character after point;
that is the default.  The symbol @code{bar} specifies a vertical bar
between characters as the cursor.  @code{(bar . @var{width})} specifies
a bar @var{width} pixels wide.

@item border-width
The width in pixels of the window border.

@item internal-border-width
The distance in pixels between text and border.

@item unsplittable
If non-@code{nil}, this frame's window is never split automatically.

@item visibility
The state of visibility of the frame.  There are three possibilities:
@code{nil} for invisible, @code{t} for visible, and @code{icon} for
iconified.  @xref{Visibility of Frames}.

@item menu-bar-lines
The number of lines to allocate at the top of the frame for a menu bar.
The default is 1.  @xref{Menu Bar}.  (In Emacs versions that use the X
toolkit, there is only one menu bar line; all that matters about the
number you specify is whether it is greater than zero.)

@item parent-id
@c ??? Not yet working.
The X window number of the window that should be the parent of this one.
Specifying this lets you create an Emacs window inside some other
application's window.  (It is not certain this will be implemented; try
it and see if it works.)
@end table

@node Size and Position
@subsection Frame Size And Position

  You can read or change the size and position of a frame using the
frame parameters @code{left}, @code{top}, @code{height}, and
@code{width}.  Whatever geometry parameters you don't specify are chosen
by the window manager in its usual fashion.

  Here are some special features for working with sizes and positions:

@defun set-frame-position frame left top
This function sets the position of the top left corner of @var{frame} to
@var{left} and @var{top}.  These arguments are measured in pixels, and
count from the top left corner of the screen.  Negative parameter values
count up or rightward from the top left corner of the screen.
@end defun

@defun frame-height &optional frame
@defunx frame-width &optional frame
These functions return the height and width of @var{frame}, measured in
characters.  If you don't supply @var{frame}, they use the selected
frame.
@end defun

@defun frame-pixel-height &optional frame
@defunx frame-pixel-width &optional frame
These functions return the height and width of @var{frame}, measured in
pixels.  If you don't supply @var{frame}, they use the selected frame.
@end defun

@defun frame-char-height &optional frame
@defunx frame-char-width &optional frame
These functions return the height and width of a character in
@var{frame}, measured in pixels.  The values depend on the choice of
font.  If you don't supply @var{frame}, these functions use the selected
frame.
@end defun

@defun set-frame-size frame cols rows
This function sets the size of @var{frame}, measured in characters;
@var{cols} and @var{rows} specify the new width and height.

To set the size based on values measured in pixels, use
@code{frame-char-height} and @code{frame-char-width} to convert
them to units of characters.
@end defun

  The old-fashioned functions @code{set-screen-height} and
@code{set-screen-width}, which were used to specify the height and width
of the screen in Emacs versions that did not support multiple frames,
are still usable.  They apply to the selected frame.  @xref{Screen
Size}.

@defun x-parse-geometry geom
@cindex geometry specification
The function @code{x-parse-geometry} converts a standard X windows
geometry string to an alist that you can use as part of the argument to
@code{make-frame}.

The alist describes which parameters were specified in @var{geom}, and
gives the values specified for them.  Each element looks like
@code{(@var{parameter} . @var{value})}.  The possible @var{parameter}
values are @code{left}, @code{top}, @code{width}, and @code{height}.

For the size parameters, the value must be an integer.  The position
parameter names @code{left} and @code{top} are not totally accurate,
because some values indicate the position of the right or bottom edges
instead.  These are the @var{value} possibilities for the position
parameters:

@table @asis
@item an integer
A positive integer relates the left edge or top edge of the window to
the left or top edge of the screen.  A negative integer relates the
right or bottom edge of the window to the right or bottom edge of the
screen.

@item @code{(+ @var{position})}
This specifies the position of the left or top edge of the window
relative to the left or top edge of the screen.  The integer
@var{position} may be positive or negative; a negative value specifies a
position outside the screen.

@item @code{(- @var{position})}
This specifies the position of the right or bottom edge of the window
relative to the right or bottom edge of the screen.  The integer
@var{position} may be positive or negative; a negative value specifies a
position outside the screen.
@end table

Here is an example:

@example
(x-parse-geometry "35x70+0-0")
     @result{} ((width . 35) (height . 70)
         (left . 0) (top - 0))
@end example
@end defun

@ignore
New functions @code{set-frame-height} and @code{set-frame-width} set the
size of a specified frame.  The frame is the first argument; the size is
the second.
@end ignore

@node Frame Titles
@section Frame Titles

Every frame has a title; most window managers display the frame title at
the top of the frame.  You can specify an explicit title with the
@code{name} frame property.  But normally you don't specify this
explicitly, and Emacs computes the title automatically.

Emacs computes the frame title based on a template stored in the
variable @code{frame-title-format}.

@defvar frame-title-format
This variable specifies how to compute a title for a frame
when you have not explicitly specified one.

The variable's value is actually a mode line construct, just like
@code{mode-line-format}.  @xref{Mode Line Data}.
@end defvar

@defvar icon-title-format
This variable specifies how to compute the title for an iconified frame,
when you have not explicitly specified the frame title.  This title
appears in the icon itself.
@end defvar

@defvar multiple-frames
This variable is set automatically by Emacs.  Its value is @code{t} when
there are two or more frames (not counting minibuffer-only frames or
invisible frames).  The default value of @code{frame-title-format} uses
@code{multiple-frames} so as to put the buffer name in the frame title
only when there is more than one frame.
@end defvar

@node Deleting Frames
@section Deleting Frames
@cindex deletion of frames

Frames remain potentially visible until you explicitly @dfn{delete}
them.  A deleted frame cannot appear on the screen, but continues to
exist as a Lisp object until there are no references to it.  There is no
way to cancel the deletion of a frame aside from restoring a saved frame
configuration (@pxref{Frame Configurations}); this is similar to the
way windows behave.

@deffn Command delete-frame &optional frame
This function deletes the frame @var{frame}.  By default, @var{frame} is
the selected frame.
@end deffn

@defun frame-live-p frame
The function @code{frame-live-p} returns non-@code{nil} if the frame
@var{frame} has not been deleted.
@end defun

  Some window managers provide a command to delete a window.  These work
by sending a special message to the program that operates the window.
When Emacs gets one of these commands, it generates a
@code{delete-frame} event, whose normal definition is a command that
calls the function @code{delete-frame}.  @xref{Misc Events}.

@node Finding All Frames
@section Finding All Frames

@defun frame-list
The function @code{frame-list} returns a list of all the frames that
have not been deleted.  It is analogous to @code{buffer-list} for
buffers.  The list that you get is newly created, so modifying the list
doesn't have any effect on the internals of Emacs.
@end defun

@defun visible-frame-list
This function returns a list of just the currently visible frames.
@xref{Visibility of Frames}.  (Terminal frames always count as
``visible'', even though only the selected one is actually displayed.)
@end defun

@defun next-frame &optional frame minibuf
The function @code{next-frame} lets you cycle conveniently through all
the frames from an arbitrary starting point.  It returns the ``next''
frame after @var{frame} in the cycle.  If @var{frame} is omitted or
@code{nil}, it defaults to the selected frame.

The second argument, @var{minibuf}, says which frames to consider:

@table @asis
@item @code{nil}
Exclude minibuffer-only frames.
@item @code{visible}
Consider all visible frames.
@item 0
Consider all visible or iconified frames.
@item a window
Consider only the frames using that particular window as their
minibuffer.
@item anything else
Consider all frames.
@end table
@end defun

@defun previous-frame &optional frame minibuf
Like @code{next-frame}, but cycles through all frames in the opposite
direction.
@end defun

  See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
Window Ordering}.

@node Frames and Windows
@section Frames and Windows

  Each window is part of one and only one frame; you can get the frame
with @code{window-frame}.

@defun window-frame window
This function returns the frame that @var{window} is on.
@end defun

  All the non-minibuffer windows in a frame are arranged in a cyclic
order.  The order runs from the frame's top window, which is at the
upper left corner, down and to the right, until it reaches the window at
the lower right corner (always the minibuffer window, if the frame has
one), and then it moves back to the top.

@defun frame-top-window frame
This returns the topmost, leftmost window of frame @var{frame}.
@end defun

At any time, exactly one window on any frame is @dfn{selected within the
frame}.  The significance of this designation is that selecting the
frame also selects this window.  You can get the frame's current
selected window with @code{frame-selected-window}.

@defun frame-selected-window frame
This function returns the window on @var{frame} that is selected within
@var{frame}.
@end defun

Conversely, selecting a window for Emacs with @code{select-window} also
makes that window selected within its frame.  @xref{Selecting Windows}.

Another function that (usually) returns one of the windows in a frame is
@code{minibuffer-window}.  @xref{Minibuffer Misc}.

@node Minibuffers and Frames
@section Minibuffers and Frames

Normally, each frame has its own minibuffer window at the bottom, which
is used whenever that frame is selected.  If the frame has a minibuffer,
you can get it with @code{minibuffer-window} (@pxref{Minibuffer Misc}).

However, you can also create a frame with no minibuffer.  Such a frame
must use the minibuffer window of some other frame.  When you create the
frame, you can specify explicitly the minibuffer window to use (in some
other frame).  If you don't, then the minibuffer is found in the frame
which is the value of the variable @code{default-minibuffer-frame}.  Its
value should be a frame that does have a minibuffer.

If you use a minibuffer-only frame, you might want that frame to raise
when you enter the minibuffer.  If so, set the variable
@code{minibuffer-auto-raise} to @code{t}.  @xref{Raising and Lowering}.

@defvar default-minibuffer-frame
This variable specifies the frame to use for the minibuffer window, by
default.  It is always local to the current terminal and cannot be
buffer-local.  @xref{Multiple Displays}.
@end defvar

@node Input Focus
@section Input Focus
@cindex input focus
@cindex selected frame

At any time, one frame in Emacs is the @dfn{selected frame}.  The selected
window always resides on the selected frame.

@defun selected-frame
This function returns the selected frame.
@end defun

The X server normally directs keyboard input to the X window that the
mouse is in.  Some window managers use mouse clicks or keyboard events
to @dfn{shift the focus} to various X windows, overriding the normal
behavior of the server.

Lisp programs can switch frames ``temporarily'' by calling
the function @code{select-frame}.  This does not override the window
manager; rather, it escapes from the window manager's control until
that control is somehow reasserted.

When using a text-only terminal, there is no window manager; therefore,
@code{switch-frame} is the only way to switch frames, and the effect
lasts until overridden by a subsequent call to @code{switch-frame}.
Only the selected terminal frame is actually displayed on the terminal.
Each terminal screen except for the initial one has a number, and the
number of the selected frame appears in the mode line after the word
@samp{Emacs} (@pxref{Mode Line Variables}).

@c ??? This is not yet implemented properly.
@defun select-frame frame
This function selects frame @var{frame}, temporarily disregarding the
focus of the X server if any.  The selection of @var{frame} lasts until
the next time the user does something to select a different frame, or
until the next time this function is called.
@end defun

Emacs cooperates with the X server and the window managers by arranging
to select frames according to what the server and window manager ask
for.  It does so by generating a special kind of input event, called a
@dfn{focus} event.  The command loop handles a focus event by calling
@code{handle-switch-frame}.  @xref{Focus Events}.

@deffn Command handle-switch-frame frame
This function handles a focus event by selecting frame @var{frame}.

Focus events normally do their job by invoking this command.
Don't call it for any other reason.
@end deffn

@defun redirect-frame-focus frame focus-frame
This function redirects focus from @var{frame} to @var{focus-frame}.
This means that @var{focus-frame} will receive subsequent keystrokes
intended for @var{frame}.  After such an event, the value of
@code{last-event-frame} will be @var{focus-frame}.  Also, switch-frame
events specifying @var{frame} will instead select @var{focus-frame}.

If @var{focus-frame} is @code{nil}, that cancels any existing
redirection for @var{frame}, which therefore once again receives its own
events.

One use of focus redirection is for frames that don't have minibuffers.
These frames use minibuffers on other frames.  Activating a minibuffer
on another frame redirects focus to that frame.  This puts the focus on
the minibuffer's frame, where it belongs, even though the mouse remains
in the frame that activated the minibuffer.

Selecting a frame can also change focus redirections.  Selecting frame
@code{bar}, when @code{foo} had been selected, changes any redirections
pointing to @code{foo} so that they point to @code{bar} instead.  This
allows focus redirection to work properly when the user switches from
one frame to another using @code{select-window}.

This means that a frame whose focus is redirected to itself is treated
differently from a frame whose focus is not redirected.
@code{select-frame} affects the former but not the latter.

The redirection lasts until @code{redirect-frame-focus} is called to
change it.
@end defun

@node Visibility of Frames
@section Visibility of Frames
@cindex visible frame
@cindex invisible frame
@cindex iconified frame
@cindex frame visibility

An X window frame may be @dfn{visible}, @dfn{invisible}, or
@dfn{iconified}.  If it is visible, you can see its contents.  If it is
iconified, the frame's contents do not appear on the screen, but an icon
does.  If the frame is invisible, it doesn't show on the screen, not
even as an icon.

Visibility is meaningless for terminal frames, since only the selected
one is actually displayed in any case.

@deffn Command make-frame-visible &optional frame
This function makes frame @var{frame} visible.  If you omit @var{frame},
it makes the selected frame visible.
@end deffn

@deffn Command make-frame-invisible &optional frame
This function makes frame @var{frame} invisible.  If you omit
@var{frame}, it makes the selected frame invisible.
@end deffn

@deffn Command iconify-frame &optional frame
This function iconifies frame @var{frame}.  If you omit @var{frame}, it
iconifies the selected frame.
@end deffn

@defun frame-visible-p frame
This returns the visibility status of frame @var{frame}.  The value is
@code{t} if @var{frame} is visible, @code{nil} if it is invisible, and
@code{icon} if it is iconified.
@end defun

  The visibility status of a frame is also available as a frame
parameter.  You can read or change it as such.  @xref{X Frame
Parameters}.

  The user can iconify and deiconify frames with the window manager.
This happens below the level at which Emacs can exert any control, but
Emacs does provide events that you can use to keep track of such
changes.  @xref{Misc Events}.

@node Raising and Lowering
@section Raising and Lowering Frames

The X Window System uses a desktop metaphor.  Part of this metaphor is
the idea that windows are stacked in a notional third dimension
perpendicular to the screen surface, and thus ordered from ``highest''
to ``lowest''.  Where two windows overlap, the one higher up covers the
one underneath.  Even a window at the bottom of the stack can be seen if
no other window overlaps it.

@cindex raising a frame
@cindex lowering a frame
A window's place in this ordering is not fixed; in fact, users tend to
change the order frequently.  @dfn{Raising} a window means moving it
``up'', to the top of the stack.  @dfn{Lowering} a window means moving
it to the bottom of the stack.  This motion is in the notional third
dimension only, and does not change the position of the window on the
screen.

You can raise and lower Emacs's X windows with these functions:

@deffn Command raise-frame frame
This function raises frame @var{frame}.
@end deffn

@deffn Command lower-frame frame
This function lowers frame @var{frame}.
@end deffn

@defopt minibuffer-auto-raise
If this is non-@code{nil}, activation of the minibuffer raises the frame
that the minibuffer window is in.
@end defopt

You can also enable auto-raise (raising automatically when a frame is
selected) or auto-lower (lowering automatically when it is deselected)
for any frame using frame parameters.  @xref{X Frame Parameters}.

@node Frame Configurations
@section Frame Configurations
@cindex frame configuration

  A @dfn{frame configuration} records the current arrangement of frames,
all their properties, and the window configuration of each one.

@defun current-frame-configuration
This function returns a frame configuration list that describes
the current arrangement of frames and their contents.
@end defun

@defun set-frame-configuration configuration
This function restores the state of frames described in
@var{configuration}.
@end defun

@node Mouse Tracking
@section Mouse Tracking
@cindex mouse tracking
@cindex tracking the mouse

Sometimes it is useful to @dfn{track} the mouse, which means to display
something to indicate where the mouse is and move the indicator as the
mouse moves.  For efficient mouse tracking, you need a way to wait until
the mouse actually moves.

The convenient way to track the mouse is to ask for events to represent
mouse motion.  Then you can wait for motion by waiting for an event.  In
addition, you can easily handle any other sorts of events that may
occur.  That is useful, because normally you don't want to track the
mouse forever---only until some other event, such as the release of a
button.

@defspec track-mouse body@dots{}
Execute @var{body}, meanwhile generating input events for mouse motion.
The code in @var{body} can read these events with @code{read-event} or
@code{read-key-sequence}.  @xref{Motion Events}, for the format of mouse
motion events.

The value of @code{track-mouse} is that of the last form in @var{body}.
@end defspec

The usual purpose of tracking mouse motion is to indicate on the screen
the consequences of pushing or releasing a button at the current
position.

In many cases, you can avoid the need to track the mouse by using
the @code{mouse-face} text property (@pxref{Special Properties}).
That works at a much lower level and runs more smoothly than
Lisp-level mouse tracking.

@ignore
@c These are not implemented yet.

These functions change the screen appearance instantaneously.  The
effect is transient, only until the next ordinary Emacs redisplay.  That
is ok for mouse tracking, since it doesn't make sense for mouse tracking
to change the text, and the body of @code{track-mouse} normally reads
the events itself and does not do redisplay.

@defun x-contour-region window beg end
This function draws lines to make a box around the text from @var{beg}
to @var{end}, in window @var{window}.
@end defun

@defun x-uncontour-region window beg end
This function erases the lines that would make a box around the text
from @var{beg} to @var{end}, in window @var{window}.  Use it to remove
a contour that you previously made by calling @code{x-contour-region}.
@end defun

@defun x-draw-rectangle frame left top right bottom
This function draws a hollow rectangle on frame @var{frame} with the
specified edge coordinates, all measured in pixels from the inside top
left corner.  It uses the cursor color, the one used for indicating the
location of point.
@end defun

@defun x-erase-rectangle frame left top right bottom
This function erases a hollow rectangle on frame @var{frame} with the
specified edge coordinates, all measured in pixels from the inside top
left corner.  Erasure means redrawing the text and background that
normally belong in the specified rectangle.
@end defun
@end ignore

@node Mouse Position
@section Mouse Position
@cindex mouse position
@cindex position of mouse

  The functions @code{mouse-position} and @code{set-mouse-position}
give access to the current position of the mouse.

@defun mouse-position
This function returns a description of the position of the mouse.  The
value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x}
and @var{y} are integers giving the position in characters relative to
the top left corner of the inside of @var{frame}.
@end defun

@defun set-mouse-position frame x y
This function @dfn{warps the mouse} to position @var{x}, @var{y} in
frame @var{frame}.  The arguments @var{x} and @var{y} are integers,
giving the position in characters relative to the top left corner of the
inside of @var{frame}.
@end defun

@defun mouse-pixel-position
This function is like @code{mouse-position} except that it returns
coordinates in units of pixels rather than units of characters.
@end defun

@defun set-mouse-pixel-position frame x y
This function warps the mouse like @code{set-mouse-position} except that
@var{x} and @var{y} are in units of pixels rather than units of
characters.  These coordinates are not required to be within the frame.
@end defun

@need 3000

@node Pop-Up Menus
@section Pop-Up Menus

  When using X windows, a Lisp program can pop up a menu which the
user can choose from with the mouse.

@defun x-popup-menu position menu
This function displays a pop-up menu and returns an indication of
what selection the user makes.

The argument @var{position} specifies where on the screen to put the
menu.  It can be either a mouse button event (which says to put the menu
where the user actuated the button) or a list of this form:

@example
((@var{xoffset} @var{yoffset}) @var{window})
@end example

@noindent
where @var{xoffset} and @var{yoffset} are coordinates, measured in
pixels, counting from the top left corner of @var{window}'s frame.

If @var{position} is @code{t}, it means to use the current mouse
position.  If @var{position} is @code{nil}, it means to precompute the
key binding equivalents for the keymaps specified in @var{menu},
without actually displaying or popping up the menu.

The argument @var{menu} says what to display in the menu.  It can be a
keymap or a list of keymaps (@pxref{Menu Keymaps}).  Alternatively, it
can have the following form:

@example
(@var{title} @var{pane1} @var{pane2}...)
@end example

@noindent
where each pane is a list of form

@example
(@var{title} (@var{line} . @var{item})...)
@end example

Each @var{line} should be a string, and each @var{item} should be the
value to return if that @var{line} is chosen.
@end defun

  @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu if
a prefix key with a menu keymap would do the job.  If you use a menu
keymap to implement a menu, @kbd{C-h c} and @kbd{C-h a} can see the
individual items in that menu and provide help for them.  If instead you
implement the menu by defining a command that calls @code{x-popup-menu},
the help facilities cannot know what happens inside that command, so
they cannot give any help for the menu's items.

  The menu bar mechanism, which lets you switch between submenus by
moving the mouse, cannot look within the definition of a command to see
that it calls @code{x-popup-menu}.  Therefore, if you try to implement a
submenu using @code{x-popup-menu}, it cannot work with the menu bar in
an integrated fashion.  This is why all menu bar submenus are
implemented with menu keymaps within the parent menu, and never with
@code{x-popup-menu}.  @xref{Menu Bar},

  If you want a menu bar submenu to have contents that vary, you should
still use a menu keymap to implement it.  To make the contents vary, add
a hook function to @code{menu-bar-update-hook} to update the contents of
the menu keymap as necessary.

@node Dialog Boxes
@section Dialog Boxes
@cindex dialog boxes

  A dialog box is a variant of a pop-up menu.  It looks a little
different (if Emacs uses an X toolkit), it always appears in the center
of a frame, and it has just one level and one pane.  The main use of
dialog boxes is for asking questions that the user can answer with
``yes'', ``no'', and a few other alternatives.  The functions
@code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the
keyboard, when called from commands invoked by mouse clicks.

@defun x-popup-dialog position contents
This function displays a pop-up dialog box and returns an indication of
what selection the user makes.  The argument @var{contents} specifies
the alternatives to offer; it has this format:

@example
(@var{title} (@var{string} . @var{value})@dots{})
@end example

@noindent
which looks like the list that specifies a single pane for
@code{x-popup-menu}.

The return value is @var{value} from the chosen alternative.

An element of the list may be just a string instead of a cons cell
@code{(@var{string} . @var{value})}.  That makes a box that cannot
be selected.

If @code{nil} appears in the list, it separates the left-hand items from
the right-hand items; items that precede the @code{nil} appear on the
left, and items that follow the @code{nil} appear on the right.  If you
don't include a @code{nil} in the list, then approximately half the
items appear on each side.

Dialog boxes always appear in the center of a frame; the argument
@var{position} specifies which frame.  The possible values are as in
@code{x-popup-menu}, but the precise coordinates don't matter; only the
frame matters.

If your Emacs executable does not use an X toolkit, then it cannot
display a real dialog box; so instead it displays the same items in a
pop-up menu in the center of the frame.
@end defun

@node Pointer Shapes
@section Pointer Shapes
@cindex pointer shape
@cindex mouse pointer shape

  These variables specify which shape to use for the mouse pointer in
various situations:

@table @code
@item x-pointer-shape
@vindex x-pointer-shape
This variable specifies the pointer shape to use ordinarily in the Emacs
frame.

@item x-sensitive-text-pointer-shape
@vindex x-sensitive-text-pointer-shape
This variable specifies the pointer shape to use when the mouse
is over mouse-sensitive text.
@end table

  These variables affect newly created frames.  They do not normally
affect existing frames; however, if you set the mouse color of a frame,
that also updates its pointer shapes based on the current values of
these variables.  @xref{X Frame Parameters}.

  The values you can use, to specify either of these pointer shapes, are
defined in the file @file{lisp/x-win.el}.  Use @kbd{M-x apropos
@key{RET} x-pointer @key{RET}} to see a list of them.

@node X Selections
@section X Selections
@cindex selection (for X windows)

The X server records a set of @dfn{selections} which permit transfer of
data between application programs.  The various selections are
distinguished by @dfn{selection types}, represented in Emacs by
symbols.  X clients including Emacs can read or set the selection for
any given type.

@defun x-set-selection type data
This function sets a ``selection'' in the X server.  It takes two
arguments: a selection type @var{type}, and the value to assign to it,
@var{data}.  If @var{data} is @code{nil}, it means to clear out the
selection.  Otherwise, @var{data} may be a string, a symbol, an integer
(or a cons of two integers or list of two integers), an overlay, or a
cons of two markers pointing to the same buffer.  An overlay or a pair
of markers stands for text in the overlay or between the markers.

The data may also be a vector of valid non-vector selection values.

Each possible @var{type} has its own selection value, which changes
independently.  The usual values of @var{type} are @code{PRIMARY} and
@code{SECONDARY}; these are symbols with upper-case names, in accord
with X Window System conventions.  The default is @code{PRIMARY}.
@end defun

@defun x-get-selection &optional type data-type
This function accesses selections set up by Emacs or by other X
clients.  It takes two optional arguments, @var{type} and
@var{data-type}.  The default for @var{type}, the selection type, is
@code{PRIMARY}.

The @var{data-type} argument specifies the form of data conversion to
use, to convert the raw data obtained from another X client into Lisp
data.  Meaningful values include @code{TEXT}, @code{STRING},
@code{TARGETS}, @code{LENGTH}, @code{DELETE}, @code{FILE_NAME},
@code{CHARACTER_POSITION}, @code{LINE_NUMBER}, @code{COLUMN_NUMBER},
@code{OWNER_OS}, @code{HOST_NAME}, @code{USER}, @code{CLASS},
@code{NAME}, @code{ATOM}, and @code{INTEGER}.  (These are symbols with
upper-case names in accord with X conventions.)  The default for
@var{data-type} is @code{STRING}.
@end defun

@cindex cut buffer
The X server also has a set of numbered @dfn{cut buffers} which can
store text or other data being moved between applications.  Cut buffers
are considered obsolete, but Emacs supports them for the sake of X
clients that still use them.

@defun x-get-cut-buffer n
This function returns the contents of cut buffer number @var{n}.
@end defun

@defun x-set-cut-buffer string
This function stores @var{string} into the first cut buffer (cut buffer
0), moving the other values down through the series of cut buffers, much
like the way successive kills in Emacs move down the kill ring.
@end defun

@node Color Names
@section Color Names

@defun x-color-defined-p color &optional frame
This function reports whether a color name is meaningful.  It returns
@code{t} if so; otherwise, @code{nil}.  The argument @var{frame} says
which frame's display to ask about; if @var{frame} is omitted or
@code{nil}, the selected frame is used.

Note that this does not tell you whether the display you are using
really supports that color.  You can ask for any defined color on any
kind of display, and you will get some result---that is how the X server
works.  Here's an approximate way to test whether your display supports
the color @var{color}:

@example
(defun x-color-supported-p (color &optional frame)
  (and (x-color-defined-p color frame)
       (or (x-display-color-p frame)
           (member color '("black" "white"))
           (and (> (x-display-planes frame) 1)
                (equal color "gray")))))
@end example
@end defun

@defun x-color-values color &optional frame
This function returns a value that describes what @var{color} should
ideally look like.  If @var{color} is defined, the value is a list of
three integers, which give the amount of red, the amount of green, and
the amount of blue.  Each integer ranges in principle from 0 to 65535,
but in practice no value seems to be above 65280.  If @var{color} is not
defined, the value is @code{nil}.

@example
(x-color-values "black")
     @result{} (0 0 0)
(x-color-values "white")
     @result{} (65280 65280 65280)
(x-color-values "red")
     @result{} (65280 0 0)
(x-color-values "pink")
     @result{} (65280 49152 51968)
(x-color-values "hungry")
     @result{} nil
@end example

The color values are returned for @var{frame}'s display.  If @var{frame}
is omitted or @code{nil}, the information is return for the selected
frame's display.
@end defun

@node Resources
@section X Resources

@defun x-get-resource attribute class &optional component subclass
The function @code{x-get-resource} retrieves a resource value from the X
Windows defaults database.

Resources are indexed by a combination of a @dfn{key} and a @dfn{class}.
This function searches using a key of the form
@samp{@var{instance}.@var{attribute}} (where @var{instance} is the name
under which Emacs was invoked), and using @samp{Emacs.@var{class}} as
the class.

The optional arguments @var{component} and @var{subclass} add to the key
and the class, respectively.  You must specify both of them or neither.
If you specify them, the key is
@samp{@var{instance}.@var{component}.@var{attribute}}, and the class is
@samp{Emacs.@var{class}.@var{subclass}}.
@end defun

  @xref{Resources X,, X Resources, emacs, The GNU Emacs Manual}.

@node Server Data
@section Data about the X Server

  This section describes functions you can use to get information about
the capabilities and origin of an X display that Emacs is using.  Each
of these functions lets you specify the display you are interested in:
the @var{display} argument can be either a display name, or a frame
(meaning use the display that frame is on).  If you omit the
@var{display} argument, or specify @code{nil}, that means to use the
selected frame's display.

@defun x-display-screens &optional display
This function returns the number of screens associated with the display.
@end defun

@defun x-server-version &optional display
This function returns the list of version numbers of the X server
running the display.
@end defun

@defun x-server-vendor &optional display
This function returns the vendor that provided the X server software.
@end defun

@defun x-display-pixel-height &optional display
This function returns the height of the screen in pixels.
@end defun

@defun x-display-mm-height &optional display
This function returns the height of the screen in millimeters.
@end defun

@defun x-display-pixel-width &optional display
This function returns the width of the screen in pixels.
@end defun

@defun x-display-mm-width &optional display
This function returns the width of the screen in millimeters.
@end defun

@defun x-display-backing-store &optional display
This function returns the backing store capability of the screen.
Values can be the symbols @code{always}, @code{when-mapped}, or
@code{not-useful}.
@end defun

@defun x-display-save-under &optional display
This function returns non-@code{nil} if the display supports the
SaveUnder feature.
@end defun

@defun x-display-planes &optional display
This function returns the number of planes the display supports.
@end defun

@defun x-display-visual-class &optional display
This function returns the visual class for the screen.  The value is one
of the symbols @code{static-gray}, @code{gray-scale},
@code{static-color}, @code{pseudo-color}, @code{true-color}, and
@code{direct-color}.
@end defun

@defun x-display-grayscale-p &optional display
This function returns @code{t} if the screen can display shades of gray.
@end defun

@defun x-display-color-p &optional display
This function returns @code{t} if the screen is a color screen.
@end defun

@defun x-display-color-cells &optional display
This function returns the number of color cells the screen supports.
@end defun

@ignore
@defvar x-no-window-manager
This variable's value is is @code{t} if no X window manager is in use.
@end defvar
@end ignore

@ignore
@item
The functions @code{x-pixel-width} and @code{x-pixel-height} return the
width and height of an X Window frame, measured in pixels.
@end ignore
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.