Mercurial > hg > xemacs-beta
annotate man/lispref/x-windows.texi @ 5880:44ba043ceada
Fix a small typo
| author | Vin Shelton <acs@xemacs.org> |
|---|---|
| date | Sat, 28 Mar 2015 16:03:33 -0400 |
| parents | 9fae6227ede5 |
| children |
| rev | line source |
|---|---|
| 428 | 1 @c -*-texinfo-*- |
| 2 @c This is part of the XEmacs Lisp Reference Manual. | |
| 444 | 3 @c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc. |
| 428 | 4 @c See the file lispref.texi for copying conditions. |
| 5 @setfilename ../../info/x-windows.texinfo | |
| 6 @node X-Windows, ToolTalk Support, System Interface, Top | |
| 7 @chapter Functions Specific to the X Window System | |
| 8 @cindex X | |
| 9 @cindex X-Windows | |
| 10 | |
| 11 @c This section is largely different from the one in FSF Emacs. | |
| 12 | |
| 13 XEmacs provides the concept of @dfn{devices}, which generalizes | |
| 14 connections to an X server, a TTY device, etc. Most information about | |
| 15 an X server that XEmacs is connected to can be determined through | |
| 16 general console and device functions. @xref{Consoles and Devices}. | |
| 17 However, there are some features of the X Window System that do not | |
| 18 generalize well, and they are covered specially here. | |
| 19 | |
| 20 @menu | |
| 440 | 21 * X Selections:: Transferring text to and from other X clients. |
| 22 * X Server:: Information about the X server connected to | |
| 23 a particular device. | |
| 428 | 24 * X Miscellaneous:: Other X-specific functions and variables. |
| 25 @end menu | |
| 26 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
625
diff
changeset
|
27 @node X Selections, X Server, X-Windows, X-Windows |
| 428 | 28 @section X Selections |
| 29 @cindex selection (for X windows) | |
| 30 | |
| 31 The X server records a set of @dfn{selections} which permit transfer of | |
| 32 data between application programs. The various selections are | |
| 33 distinguished by @dfn{selection types}, represented in XEmacs by | |
| 34 symbols. X clients including XEmacs can read or set the selection for | |
| 35 any given type. | |
| 36 | |
| 37 @defun x-own-selection data &optional type | |
| 38 This function sets a ``selection'' in the X server. It takes two | |
| 39 arguments: a value, @var{data}, and the selection type @var{type} to | |
| 40 assign it to. @var{data} may be a string, a cons of two markers, or an | |
| 41 extent. In the latter cases, the selection is considered to be the text | |
| 42 between the markers, or between the extent's endpoints. | |
| 43 | |
| 44 Each possible @var{type} has its own selection value, which changes | |
| 45 independently. The usual values of @var{type} are @code{PRIMARY} and | |
| 46 @code{SECONDARY}; these are symbols with upper-case names, in accord | |
| 47 with X Windows conventions. The default is @code{PRIMARY}. | |
| 48 | |
| 49 (In FSF Emacs, this function is called @code{x-set-selection} and | |
| 50 takes different arguments.) | |
| 51 @end defun | |
| 52 | |
| 53 @defun x-get-selection | |
| 54 This function accesses selections set up by XEmacs or by other X | |
| 55 clients. It returns the value of the current primary selection. | |
| 56 @end defun | |
| 57 | |
| 58 @defun x-disown-selection &optional secondary-p | |
| 59 Assuming we own the selection, this function disowns it. If | |
| 60 @var{secondary-p} is non-@code{nil}, the secondary selection instead of | |
| 61 the primary selection is discarded. | |
| 62 @end defun | |
| 63 | |
| 64 @cindex cut buffer | |
| 65 The X server also has a set of numbered @dfn{cut buffers} which can | |
| 66 store text or other data being moved between applications. Cut buffers | |
| 67 are considered obsolete, but XEmacs supports them for the sake of X | |
| 68 clients that still use them. | |
| 69 | |
| 70 @defun x-get-cutbuffer &optional n | |
| 71 This function returns the contents of cut buffer number @var{n}. (This | |
| 72 function is called @code{x-get-cut-buffer} in FSF Emacs.) | |
| 73 @end defun | |
| 74 | |
| 444 | 75 @defun x-store-cutbuffer string &optional push |
| 428 | 76 This function stores @var{string} into the first cut buffer (cut buffer |
| 444 | 77 0). |
| 78 | |
| 79 Normally, the contents of the first cut buffer are simply replaced by | |
| 80 @var{string}. However, if optional argument @var{push} is | |
| 81 non-@code{nil}, the cut buffers are rotated. This means that the | |
| 82 previous value of the first cut buffer moves to the second cut buffer, | |
| 83 and the second to the third, and so on, moving the other values down | |
| 84 through the series of cut buffers, kill-ring-style. There are 8 cut | |
| 85 buffers altogether. | |
| 86 | |
| 87 Cut buffers are considered obsolete; you should use selections instead. | |
| 88 | |
| 89 This function has no effect if support for cut buffers was not compiled in. | |
| 90 | |
| 91 This function is called @code{x-set-cut-buffer} in FSF Emacs. | |
| 428 | 92 @end defun |
| 93 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
625
diff
changeset
|
94 @node X Server, X Miscellaneous, X Selections, X-Windows |
| 428 | 95 @section X Server |
| 96 | |
| 97 This section describes how to access and change the overall status of | |
| 98 the X server XEmacs is using. | |
| 99 | |
| 100 @menu | |
| 440 | 101 * Resources:: Getting resource values from the server. |
| 102 * Server Data:: Getting info about the X server. | |
| 103 * Grabs:: Restricting access to the server by other apps. | |
| 428 | 104 @end menu |
| 105 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
625
diff
changeset
|
106 @node Resources, Server Data, X Server, X Server |
| 428 | 107 @subsection Resources |
| 108 | |
| 109 @defun default-x-device | |
| 110 This function return the default X device for resourcing. This is the | |
| 111 first-created X device that still exists. | |
| 112 @end defun | |
| 113 | |
| 114 @defun x-get-resource name class type &optional locale device noerror | |
| 115 This function retrieves a resource value from the X resource manager. | |
| 116 | |
| 117 @itemize @bullet | |
| 118 @item | |
| 119 The first arg is the name of the resource to retrieve, such as | |
| 120 @samp{"font"}. | |
| 121 | |
| 122 @item | |
| 123 The second arg is the class of the resource to retrieve, like | |
| 124 @samp{"Font"}. | |
| 125 | |
| 126 @item | |
| 127 The third arg should be one of the symbols @code{string}, | |
| 128 @code{integer}, @code{natnum}, or @code{boolean}, specifying the type of | |
| 129 object that the database is searched for. | |
| 130 | |
| 131 @item | |
| 132 The fourth arg is the locale to search for the resources on, and can | |
| 625 | 133 currently be a buffer, a frame, a device, or the symbol @code{global}. |
| 428 | 134 If omitted, it defaults to @code{global}. |
| 135 | |
| 136 @item | |
| 137 The fifth arg is the device to search for the resources on. (The | |
| 138 resource database for a particular device is constructed by combining | |
| 139 non-device- specific resources such any command-line resources specified | |
| 140 and any app-defaults files found [or the fallback resources supplied by | |
| 141 XEmacs, if no app-defaults file is found] with device-specific resources | |
| 142 such as those supplied using @samp{xrdb}.) If omitted, it defaults to | |
| 143 the device of @var{locale}, if a device can be derived (i.e. if | |
| 144 @var{locale} is a frame or device), and otherwise defaults to the value | |
| 145 of @code{default-x-device}. | |
| 146 | |
| 147 @item | |
| 148 The sixth arg @var{noerror}, if non-@code{nil}, means do not signal an | |
| 149 error if a bogus resource specification was retrieved (e.g. if a | |
| 150 non-integer was given when an integer was requested). In this case, a | |
| 151 warning is issued instead. | |
| 152 @end itemize | |
| 153 | |
| 154 The resource names passed to this function are looked up relative to the | |
| 155 locale. | |
| 156 | |
| 157 If you want to search for a subresource, you just need to specify the | |
| 158 resource levels in @var{name} and @var{class}. For example, @var{name} | |
| 159 could be @samp{"modeline.attributeFont"}, and @var{class} | |
| 160 @samp{"Face.AttributeFont"}. | |
| 161 | |
| 162 Specifically, | |
| 163 | |
| 164 @enumerate | |
| 165 @item | |
| 166 If @var{locale} is a buffer, a call | |
| 167 | |
| 168 @example | |
| 169 @code{(x-get-resource "foreground" "Foreground" 'string @var{some-buffer})} | |
| 170 @end example | |
| 171 | |
| 172 is an interface to a C call something like | |
| 173 | |
| 174 @example | |
| 175 @code{XrmGetResource (db, "xemacs.buffer.@var{buffer-name}.foreground", | |
| 440 | 176 "Emacs.EmacsLocaleType.EmacsBuffer.Foreground", |
| 177 "String");} | |
| 428 | 178 @end example |
| 179 | |
| 180 @item | |
| 181 If @var{locale} is a frame, a call | |
| 182 | |
| 183 @example | |
| 184 @code{(x-get-resource "foreground" "Foreground" 'string @var{some-frame})} | |
| 185 @end example | |
| 186 | |
| 187 is an interface to a C call something like | |
| 188 @example | |
| 189 | |
| 190 @code{XrmGetResource (db, "xemacs.frame.@var{frame-name}.foreground", | |
| 440 | 191 "Emacs.EmacsLocaleType.EmacsFrame.Foreground", |
| 192 "String");} | |
| 428 | 193 @end example |
| 194 | |
| 195 @item | |
| 196 If @var{locale} is a device, a call | |
| 197 | |
| 198 @example | |
| 199 @code{(x-get-resource "foreground" "Foreground" 'string @var{some-device})} | |
| 200 @end example | |
| 201 | |
| 202 is an interface to a C call something like | |
| 203 | |
| 204 @example | |
| 205 @code{XrmGetResource (db, "xemacs.device.@var{device-name}.foreground", | |
| 440 | 206 "Emacs.EmacsLocaleType.EmacsDevice.Foreground", |
| 207 "String");} | |
| 428 | 208 @end example |
| 209 | |
| 210 @item | |
| 211 If @var{locale} is the symbol @code{global}, a call | |
| 212 | |
| 213 @example | |
| 214 @code{(x-get-resource "foreground" "Foreground" 'string 'global)} | |
| 215 @end example | |
| 216 | |
| 217 is an interface to a C call something like | |
| 218 | |
| 219 @example | |
| 220 @code{XrmGetResource (db, "xemacs.foreground", | |
| 440 | 221 "Emacs.Foreground", |
| 222 "String");} | |
| 428 | 223 @end example |
| 224 @end enumerate | |
| 225 | |
| 226 Note that for @code{global}, no prefix is added other than that of the | |
| 227 application itself; thus, you can use this locale to retrieve arbitrary | |
| 228 application resources, if you really want to. | |
| 229 | |
| 230 The returned value of this function is @code{nil} if the queried | |
| 231 resource is not found. If @var{type} is @code{string}, a string is | |
| 232 returned, and if it is @code{integer}, an integer is returned. If | |
| 233 @var{type} is @code{boolean}, then the returned value is the list | |
| 234 @code{(t)} for true, @code{(nil)} for false, and is @code{nil} to mean | |
| 235 ``unspecified''. | |
| 236 @end defun | |
| 237 | |
| 238 @defun x-put-resource resource-line &optional device | |
| 239 This function adds a resource to the resource database for @var{device}. | |
| 240 @var{resource-line} specifies the resource to add and should be a | |
| 241 standard resource specification. | |
| 242 @end defun | |
| 243 | |
| 244 @defvar x-emacs-application-class | |
| 245 This variable holds The X application class of the XEmacs process. This | |
| 246 controls, among other things, the name of the ``app-defaults'' file that | |
| 247 XEmacs will use. For changes to this variable to take effect, they must | |
| 248 be made before the connection to the X server is initialized, that is, | |
| 249 this variable may only be changed before XEmacs is dumped, or by setting | |
| 250 it in the file @file{lisp/term/x-win.el}. | |
| 251 | |
| 444 | 252 By default, this variable is @code{nil} at startup. When the connection |
| 428 | 253 to the X server is first initialized, the X resource database will |
| 254 be consulted and the value will be set according to whether any | |
| 255 resources are found for the application class ``XEmacs''. | |
| 256 @end defvar | |
| 257 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
625
diff
changeset
|
258 @node Server Data, Grabs, Resources, X Server |
| 428 | 259 @subsection Data about the X Server |
| 260 | |
| 261 This section describes functions and a variable that you can use to | |
| 262 get information about the capabilities and origin of the X server | |
| 263 corresponding to a particular device. The device argument is generally | |
| 264 optional and defaults to the selected device. | |
| 265 | |
| 444 | 266 @defun x-server-version &optional device |
| 428 | 267 This function returns the list of version numbers of the X server |
| 268 @var{device} is on. The returned value is a list of three integers: the | |
| 269 major and minor version numbers of the X protocol in use, and the | |
| 270 vendor-specific release number. | |
| 271 @end defun | |
| 272 | |
| 273 @defun x-server-vendor &optional device | |
| 274 This function returns the vendor supporting the X server @var{device} is | |
| 275 on. | |
| 276 @end defun | |
| 277 | |
| 278 @defun x-display-visual-class &optional device | |
| 279 This function returns the visual class of the display @var{device} is | |
| 280 on. The value is one of the symbols @code{static-gray}, | |
| 281 @code{gray-scale}, @code{static-color}, @code{pseudo-color}, | |
| 282 @code{true-color}, and @code{direct-color}. (Note that this is different | |
| 283 from previous versions of XEmacs, which returned @code{StaticGray}, | |
| 284 @code{GrayScale}, etc.) | |
| 285 @end defun | |
| 286 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
625
diff
changeset
|
287 @node Grabs, , Server Data, X Server |
| 428 | 288 @subsection Restricting Access to the Server by Other Apps |
| 289 | |
| 290 @defun x-grab-keyboard &optional device | |
| 291 This function grabs the keyboard on the given device (defaulting to the | |
| 292 selected one). So long as the keyboard is grabbed, all keyboard events | |
| 440 | 293 will be delivered to XEmacs---it is not possible for other X clients to |
| 428 | 294 eavesdrop on them. Ungrab the keyboard with @code{x-ungrab-keyboard} |
| 295 (use an @code{unwind-protect}). Returns @code{t} if the grab was | |
| 296 successful; @code{nil} otherwise. | |
| 297 @end defun | |
| 298 | |
| 299 @defun x-ungrab-keyboard &optional device | |
| 300 This function releases a keyboard grab made with @code{x-grab-keyboard}. | |
| 301 @end defun | |
| 302 | |
| 303 @defun x-grab-pointer &optional device cursor ignore-keyboard | |
| 304 This function grabs the pointer and restricts it to its current window. | |
| 305 If optional @var{device} argument is @code{nil}, the selected device | |
| 306 will be used. If optional @var{cursor} argument is non-@code{nil}, | |
| 307 change the pointer shape to that until @code{x-ungrab-pointer} is called | |
| 308 (it should be an object returned by the @code{make-cursor} function). | |
| 309 If the second optional argument @var{ignore-keyboard} is non-@code{nil}, | |
| 310 ignore all keyboard events during the grab. Returns @code{t} if the | |
| 311 grab is successful, @code{nil} otherwise. | |
| 312 @end defun | |
| 313 | |
| 314 @defun x-ungrab-pointer &optional device | |
| 315 This function releases a pointer grab made with @code{x-grab-pointer}. | |
| 316 If optional first arg @var{device} is @code{nil} the selected device is | |
| 317 used. If it is @code{t} the pointer will be released on all X devices. | |
| 318 @end defun | |
| 319 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
625
diff
changeset
|
320 @node X Miscellaneous, , X Server, X-Windows |
| 428 | 321 @section Miscellaneous X Functions and Variables |
| 322 | |
| 323 @defvar x-bitmap-file-path | |
| 324 This variable holds a list of the directories in which X bitmap files | |
| 325 may be found. If @code{nil}, this is initialized from the | |
| 326 @samp{"*bitmapFilePath"} resource. This is used by the | |
| 327 @code{make-image-instance} function (however, note that if the | |
| 328 environment variable @samp{XBMLANGPATH} is set, it is consulted first). | |
| 329 @end defvar | |
| 330 | |
| 331 @defvar x-library-search-path | |
| 332 This variable holds the search path used by @code{read-color} to find | |
| 333 @file{rgb.txt}. | |
| 334 @end defvar | |
| 335 | |
| 336 @defun x-valid-keysym-name-p keysym | |
| 337 This function returns true if @var{keysym} names a keysym that the X | |
| 338 library knows about. Valid keysyms are listed in the files | |
| 339 @file{/usr/include/X11/keysymdef.h} and in | |
| 340 @file{/usr/lib/X11/XKeysymDB}, or whatever the equivalents are on your | |
| 341 system. | |
| 342 @end defun | |
| 343 | |
| 344 @defun x-window-id &optional frame | |
| 345 This function returns the ID of the X11 window. This gives us a chance | |
| 346 to manipulate the Emacs window from within a different program. Since | |
| 347 the ID is an unsigned long, we return it as a string. | |
| 348 @end defun | |
| 349 | |
| 350 @defvar x-allow-sendevents | |
| 351 If non-@code{nil}, synthetic events are allowed. @code{nil} means | |
| 352 they are ignored. Beware: allowing XEmacs to process SendEvents opens a | |
| 353 big security hole. | |
| 354 @end defvar | |
| 355 | |
| 356 @defun x-debug-mode arg &optional device | |
| 357 With a true arg, make the connection to the X server synchronous. With | |
| 358 false, make it asynchronous. Synchronous connections are much slower, | |
| 359 but are useful for debugging. (If you get X errors, make the connection | |
| 360 synchronous, and use a debugger to set a breakpoint on | |
| 361 @code{x_error_handler}. Your backtrace of the C stack will now be | |
| 362 useful. In asynchronous mode, the stack above @code{x_error_handler} | |
| 363 isn't helpful because of buffering.) If @var{device} is not specified, | |
| 364 the selected device is assumed. | |
| 365 | |
| 366 Calling this function is the same as calling the C function | |
| 367 @code{XSynchronize}, or starting the program with the @samp{-sync} | |
| 368 command line argument. | |
| 369 @end defun | |
| 370 | |
| 371 @defvar x-debug-events | |
| 372 If non-zero, debug information about events that XEmacs sees is | |
| 373 displayed. Information is displayed on stderr. Currently defined | |
| 374 values are: | |
| 375 | |
| 376 @itemize @bullet | |
| 377 @item | |
| 378 1 == non-verbose output | |
| 379 @item | |
| 380 2 == verbose output | |
| 381 @end itemize | |
| 382 @end defvar |