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
+ − 27 @node X Selections
+ − 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
+ − 94 @node X Server
+ − 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
+ − 106 @node Resources
+ − 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
+ − 258 @node Server Data
+ − 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
+ − 287 @node Grabs
+ − 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
+ − 320 @node X Miscellaneous
+ − 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