|
428
|
1 @c -*-texinfo-*-
|
|
|
2 @c This is part of the XEmacs Lisp Reference Manual.
|
|
|
3 @c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
|
|
|
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
|
|
|
75 @defun x-store-cutbuffer string
|
|
|
76 This function stores @var{string} into the first cut buffer (cut buffer
|
|
|
77 0), moving the other values down through the series of cut buffers,
|
|
|
78 kill-ring-style. (This function is called @code{x-set-cut-buffer} in FSF
|
|
|
79 Emacs.)
|
|
|
80 @end defun
|
|
|
81
|
|
|
82 @node X Server
|
|
|
83 @section X Server
|
|
|
84
|
|
|
85 This section describes how to access and change the overall status of
|
|
|
86 the X server XEmacs is using.
|
|
|
87
|
|
|
88 @menu
|
|
440
|
89 * Resources:: Getting resource values from the server.
|
|
|
90 * Server Data:: Getting info about the X server.
|
|
|
91 * Grabs:: Restricting access to the server by other apps.
|
|
428
|
92 @end menu
|
|
|
93
|
|
|
94 @node Resources
|
|
|
95 @subsection Resources
|
|
|
96
|
|
|
97 @defun default-x-device
|
|
|
98 This function return the default X device for resourcing. This is the
|
|
|
99 first-created X device that still exists.
|
|
|
100 @end defun
|
|
|
101
|
|
|
102 @defun x-get-resource name class type &optional locale device noerror
|
|
|
103 This function retrieves a resource value from the X resource manager.
|
|
|
104
|
|
|
105 @itemize @bullet
|
|
|
106 @item
|
|
|
107 The first arg is the name of the resource to retrieve, such as
|
|
|
108 @samp{"font"}.
|
|
|
109
|
|
|
110 @item
|
|
|
111 The second arg is the class of the resource to retrieve, like
|
|
|
112 @samp{"Font"}.
|
|
|
113
|
|
|
114 @item
|
|
|
115 The third arg should be one of the symbols @code{string},
|
|
|
116 @code{integer}, @code{natnum}, or @code{boolean}, specifying the type of
|
|
|
117 object that the database is searched for.
|
|
|
118
|
|
|
119 @item
|
|
|
120 The fourth arg is the locale to search for the resources on, and can
|
|
|
121 currently be a a buffer, a frame, a device, or the symbol @code{global}.
|
|
|
122 If omitted, it defaults to @code{global}.
|
|
|
123
|
|
|
124 @item
|
|
|
125 The fifth arg is the device to search for the resources on. (The
|
|
|
126 resource database for a particular device is constructed by combining
|
|
|
127 non-device- specific resources such any command-line resources specified
|
|
|
128 and any app-defaults files found [or the fallback resources supplied by
|
|
|
129 XEmacs, if no app-defaults file is found] with device-specific resources
|
|
|
130 such as those supplied using @samp{xrdb}.) If omitted, it defaults to
|
|
|
131 the device of @var{locale}, if a device can be derived (i.e. if
|
|
|
132 @var{locale} is a frame or device), and otherwise defaults to the value
|
|
|
133 of @code{default-x-device}.
|
|
|
134
|
|
|
135 @item
|
|
|
136 The sixth arg @var{noerror}, if non-@code{nil}, means do not signal an
|
|
|
137 error if a bogus resource specification was retrieved (e.g. if a
|
|
|
138 non-integer was given when an integer was requested). In this case, a
|
|
|
139 warning is issued instead.
|
|
|
140 @end itemize
|
|
|
141
|
|
|
142 The resource names passed to this function are looked up relative to the
|
|
|
143 locale.
|
|
|
144
|
|
|
145 If you want to search for a subresource, you just need to specify the
|
|
|
146 resource levels in @var{name} and @var{class}. For example, @var{name}
|
|
|
147 could be @samp{"modeline.attributeFont"}, and @var{class}
|
|
|
148 @samp{"Face.AttributeFont"}.
|
|
|
149
|
|
|
150 Specifically,
|
|
|
151
|
|
|
152 @enumerate
|
|
|
153 @item
|
|
|
154 If @var{locale} is a buffer, a call
|
|
|
155
|
|
|
156 @example
|
|
|
157 @code{(x-get-resource "foreground" "Foreground" 'string @var{some-buffer})}
|
|
|
158 @end example
|
|
|
159
|
|
|
160 is an interface to a C call something like
|
|
|
161
|
|
|
162 @example
|
|
|
163 @code{XrmGetResource (db, "xemacs.buffer.@var{buffer-name}.foreground",
|
|
440
|
164 "Emacs.EmacsLocaleType.EmacsBuffer.Foreground",
|
|
|
165 "String");}
|
|
428
|
166 @end example
|
|
|
167
|
|
|
168 @item
|
|
|
169 If @var{locale} is a frame, a call
|
|
|
170
|
|
|
171 @example
|
|
|
172 @code{(x-get-resource "foreground" "Foreground" 'string @var{some-frame})}
|
|
|
173 @end example
|
|
|
174
|
|
|
175 is an interface to a C call something like
|
|
|
176 @example
|
|
|
177
|
|
|
178 @code{XrmGetResource (db, "xemacs.frame.@var{frame-name}.foreground",
|
|
440
|
179 "Emacs.EmacsLocaleType.EmacsFrame.Foreground",
|
|
|
180 "String");}
|
|
428
|
181 @end example
|
|
|
182
|
|
|
183 @item
|
|
|
184 If @var{locale} is a device, a call
|
|
|
185
|
|
|
186 @example
|
|
|
187 @code{(x-get-resource "foreground" "Foreground" 'string @var{some-device})}
|
|
|
188 @end example
|
|
|
189
|
|
|
190 is an interface to a C call something like
|
|
|
191
|
|
|
192 @example
|
|
|
193 @code{XrmGetResource (db, "xemacs.device.@var{device-name}.foreground",
|
|
440
|
194 "Emacs.EmacsLocaleType.EmacsDevice.Foreground",
|
|
|
195 "String");}
|
|
428
|
196 @end example
|
|
|
197
|
|
|
198 @item
|
|
|
199 If @var{locale} is the symbol @code{global}, a call
|
|
|
200
|
|
|
201 @example
|
|
|
202 @code{(x-get-resource "foreground" "Foreground" 'string 'global)}
|
|
|
203 @end example
|
|
|
204
|
|
|
205 is an interface to a C call something like
|
|
|
206
|
|
|
207 @example
|
|
|
208 @code{XrmGetResource (db, "xemacs.foreground",
|
|
440
|
209 "Emacs.Foreground",
|
|
|
210 "String");}
|
|
428
|
211 @end example
|
|
|
212 @end enumerate
|
|
|
213
|
|
|
214 Note that for @code{global}, no prefix is added other than that of the
|
|
|
215 application itself; thus, you can use this locale to retrieve arbitrary
|
|
|
216 application resources, if you really want to.
|
|
|
217
|
|
|
218 The returned value of this function is @code{nil} if the queried
|
|
|
219 resource is not found. If @var{type} is @code{string}, a string is
|
|
|
220 returned, and if it is @code{integer}, an integer is returned. If
|
|
|
221 @var{type} is @code{boolean}, then the returned value is the list
|
|
|
222 @code{(t)} for true, @code{(nil)} for false, and is @code{nil} to mean
|
|
|
223 ``unspecified''.
|
|
|
224 @end defun
|
|
|
225
|
|
|
226 @defun x-put-resource resource-line &optional device
|
|
|
227 This function adds a resource to the resource database for @var{device}.
|
|
|
228 @var{resource-line} specifies the resource to add and should be a
|
|
|
229 standard resource specification.
|
|
|
230 @end defun
|
|
|
231
|
|
|
232 @defvar x-emacs-application-class
|
|
|
233 This variable holds The X application class of the XEmacs process. This
|
|
|
234 controls, among other things, the name of the ``app-defaults'' file that
|
|
|
235 XEmacs will use. For changes to this variable to take effect, they must
|
|
|
236 be made before the connection to the X server is initialized, that is,
|
|
|
237 this variable may only be changed before XEmacs is dumped, or by setting
|
|
|
238 it in the file @file{lisp/term/x-win.el}.
|
|
|
239
|
|
|
240 By default, this variable is nil at startup. When the connection
|
|
|
241 to the X server is first initialized, the X resource database will
|
|
|
242 be consulted and the value will be set according to whether any
|
|
|
243 resources are found for the application class ``XEmacs''.
|
|
|
244 @end defvar
|
|
|
245
|
|
|
246 @node Server Data
|
|
|
247 @subsection Data about the X Server
|
|
|
248
|
|
|
249 This section describes functions and a variable that you can use to
|
|
|
250 get information about the capabilities and origin of the X server
|
|
|
251 corresponding to a particular device. The device argument is generally
|
|
|
252 optional and defaults to the selected device.
|
|
|
253
|
|
|
254 @defun x-server-version &optional device
|
|
|
255 This function returns the list of version numbers of the X server
|
|
|
256 @var{device} is on. The returned value is a list of three integers: the
|
|
|
257 major and minor version numbers of the X protocol in use, and the
|
|
|
258 vendor-specific release number.
|
|
|
259 @end defun
|
|
|
260
|
|
|
261 @defun x-server-vendor &optional device
|
|
|
262 This function returns the vendor supporting the X server @var{device} is
|
|
|
263 on.
|
|
|
264 @end defun
|
|
|
265
|
|
|
266 @defun x-display-visual-class &optional device
|
|
|
267 This function returns the visual class of the display @var{device} is
|
|
|
268 on. The value is one of the symbols @code{static-gray},
|
|
|
269 @code{gray-scale}, @code{static-color}, @code{pseudo-color},
|
|
|
270 @code{true-color}, and @code{direct-color}. (Note that this is different
|
|
|
271 from previous versions of XEmacs, which returned @code{StaticGray},
|
|
|
272 @code{GrayScale}, etc.)
|
|
|
273 @end defun
|
|
|
274
|
|
|
275 @node Grabs
|
|
|
276 @subsection Restricting Access to the Server by Other Apps
|
|
|
277
|
|
|
278 @defun x-grab-keyboard &optional device
|
|
|
279 This function grabs the keyboard on the given device (defaulting to the
|
|
|
280 selected one). So long as the keyboard is grabbed, all keyboard events
|
|
440
|
281 will be delivered to XEmacs---it is not possible for other X clients to
|
|
428
|
282 eavesdrop on them. Ungrab the keyboard with @code{x-ungrab-keyboard}
|
|
|
283 (use an @code{unwind-protect}). Returns @code{t} if the grab was
|
|
|
284 successful; @code{nil} otherwise.
|
|
|
285 @end defun
|
|
|
286
|
|
|
287 @defun x-ungrab-keyboard &optional device
|
|
|
288 This function releases a keyboard grab made with @code{x-grab-keyboard}.
|
|
|
289 @end defun
|
|
|
290
|
|
|
291 @defun x-grab-pointer &optional device cursor ignore-keyboard
|
|
|
292 This function grabs the pointer and restricts it to its current window.
|
|
|
293 If optional @var{device} argument is @code{nil}, the selected device
|
|
|
294 will be used. If optional @var{cursor} argument is non-@code{nil},
|
|
|
295 change the pointer shape to that until @code{x-ungrab-pointer} is called
|
|
|
296 (it should be an object returned by the @code{make-cursor} function).
|
|
|
297 If the second optional argument @var{ignore-keyboard} is non-@code{nil},
|
|
|
298 ignore all keyboard events during the grab. Returns @code{t} if the
|
|
|
299 grab is successful, @code{nil} otherwise.
|
|
|
300 @end defun
|
|
|
301
|
|
|
302 @defun x-ungrab-pointer &optional device
|
|
|
303 This function releases a pointer grab made with @code{x-grab-pointer}.
|
|
|
304 If optional first arg @var{device} is @code{nil} the selected device is
|
|
|
305 used. If it is @code{t} the pointer will be released on all X devices.
|
|
|
306 @end defun
|
|
|
307
|
|
|
308 @node X Miscellaneous
|
|
|
309 @section Miscellaneous X Functions and Variables
|
|
|
310
|
|
|
311 @defvar x-bitmap-file-path
|
|
|
312 This variable holds a list of the directories in which X bitmap files
|
|
|
313 may be found. If @code{nil}, this is initialized from the
|
|
|
314 @samp{"*bitmapFilePath"} resource. This is used by the
|
|
|
315 @code{make-image-instance} function (however, note that if the
|
|
|
316 environment variable @samp{XBMLANGPATH} is set, it is consulted first).
|
|
|
317 @end defvar
|
|
|
318
|
|
|
319 @defvar x-library-search-path
|
|
|
320 This variable holds the search path used by @code{read-color} to find
|
|
|
321 @file{rgb.txt}.
|
|
|
322 @end defvar
|
|
|
323
|
|
|
324 @defun x-valid-keysym-name-p keysym
|
|
|
325 This function returns true if @var{keysym} names a keysym that the X
|
|
|
326 library knows about. Valid keysyms are listed in the files
|
|
|
327 @file{/usr/include/X11/keysymdef.h} and in
|
|
|
328 @file{/usr/lib/X11/XKeysymDB}, or whatever the equivalents are on your
|
|
|
329 system.
|
|
|
330 @end defun
|
|
|
331
|
|
|
332 @defun x-window-id &optional frame
|
|
|
333 This function returns the ID of the X11 window. This gives us a chance
|
|
|
334 to manipulate the Emacs window from within a different program. Since
|
|
|
335 the ID is an unsigned long, we return it as a string.
|
|
|
336 @end defun
|
|
|
337
|
|
|
338 @defvar x-allow-sendevents
|
|
|
339 If non-@code{nil}, synthetic events are allowed. @code{nil} means
|
|
|
340 they are ignored. Beware: allowing XEmacs to process SendEvents opens a
|
|
|
341 big security hole.
|
|
|
342 @end defvar
|
|
|
343
|
|
|
344 @defun x-debug-mode arg &optional device
|
|
|
345 With a true arg, make the connection to the X server synchronous. With
|
|
|
346 false, make it asynchronous. Synchronous connections are much slower,
|
|
|
347 but are useful for debugging. (If you get X errors, make the connection
|
|
|
348 synchronous, and use a debugger to set a breakpoint on
|
|
|
349 @code{x_error_handler}. Your backtrace of the C stack will now be
|
|
|
350 useful. In asynchronous mode, the stack above @code{x_error_handler}
|
|
|
351 isn't helpful because of buffering.) If @var{device} is not specified,
|
|
|
352 the selected device is assumed.
|
|
|
353
|
|
|
354 Calling this function is the same as calling the C function
|
|
|
355 @code{XSynchronize}, or starting the program with the @samp{-sync}
|
|
|
356 command line argument.
|
|
|
357 @end defun
|
|
|
358
|
|
|
359 @defvar x-debug-events
|
|
|
360 If non-zero, debug information about events that XEmacs sees is
|
|
|
361 displayed. Information is displayed on stderr. Currently defined
|
|
|
362 values are:
|
|
|
363
|
|
|
364 @itemize @bullet
|
|
|
365 @item
|
|
|
366 1 == non-verbose output
|
|
|
367 @item
|
|
|
368 2 == verbose output
|
|
|
369 @end itemize
|
|
|
370 @end defvar
|
