|
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
|
