1 This is ../info/lispref.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Time of Day, Next: Time Conversion, Prev: User Identification, Up: System Interface
58 This section explains how to determine the current time and the time
61 - Function: current-time-string &optional time-value
62 This function returns the current time and date as a
63 humanly-readable string. The format of the string is unvarying;
64 the number of characters used for each part is always the same, so
65 you can reliably use `substring' to extract pieces of it. It is
66 wise to count the characters from the beginning of the string
67 rather than from the end, as additional information may be added
70 The argument TIME-VALUE, if given, specifies a time to format
71 instead of the current time. The argument should be a list whose
72 first two elements are integers. Thus, you can use times obtained
73 from `current-time' (see below) and from `file-attributes' (*note
77 => "Wed Oct 14 22:21:05 1987"
79 - Function: current-time
80 This function returns the system's time value as a list of three
81 integers: `(HIGH LOW MICROSEC)'. The integers HIGH and LOW
82 combine to give the number of seconds since 0:00 January 1, 1970,
83 which is HIGH * 2**16 + LOW.
85 The third element, MICROSEC, gives the microseconds since the
86 start of the current second (or 0 for systems that return time
87 only on the resolution of a second).
89 The first two elements can be compared with file time values such
90 as you get with the function `file-attributes'. *Note File
93 - Function: current-time-zone &optional time-value
94 This function returns a list describing the time zone that the
97 The value has the form `(OFFSET NAME)'. Here OFFSET is an integer
98 giving the number of seconds ahead of UTC (east of Greenwich). A
99 negative value means west of Greenwich. The second element, NAME
100 is a string giving the name of the time zone. Both elements
101 change when daylight savings time begins or ends; if the user has
102 specified a time zone that does not use a seasonal time
103 adjustment, then the value is constant through time.
105 If the operating system doesn't supply all the information
106 necessary to compute the value, both elements of the list are
109 The argument TIME-VALUE, if given, specifies a time to analyze
110 instead of the current time. The argument should be a cons cell
111 containing two integers, or a list whose first two elements are
112 integers. Thus, you can use times obtained from `current-time'
113 (see above) and from `file-attributes' (*note File Attributes::).
116 File: lispref.info, Node: Time Conversion, Next: Timers, Prev: Time of Day, Up: System Interface
121 These functions convert time values (lists of two or three integers)
122 to strings or to calendrical information. There is also a function to
123 convert calendrical information to a time value. You can get time
124 values from the functions `current-time' (*note Time of Day::) and
125 `file-attributes' (*note File Attributes::).
127 - Function: format-time-string format-string &optional time
128 This function converts TIME to a string according to
129 FORMAT-STRING. If TIME is omitted, it defaults to the current
130 time. The argument FORMAT-STRING may contain `%'-sequences which
131 say to substitute parts of the time. Here is a table of what the
135 This stands for the abbreviated name of the day of week.
138 This stands for the full name of the day of week.
141 This stands for the abbreviated name of the month.
144 This stands for the full name of the month.
147 This is a synonym for `%x %X'.
150 This has a locale-specific meaning. In the default locale
151 (named C), it is equivalent to `%A, %B %e, %Y'.
154 This stands for the day of month, zero-padded.
157 This is a synonym for `%m/%d/%y'.
160 This stands for the day of month, blank-padded.
163 This is a synonym for `%b'.
166 This stands for the hour (00-23).
169 This stands for the hour (00-12).
172 This stands for the day of the year (001-366).
175 This stands for the hour (0-23), blank padded.
178 This stands for the hour (1-12), blank padded.
181 This stands for the month (01-12).
184 This stands for the minute (00-59).
187 This stands for a newline.
190 This stands for `AM' or `PM', as appropriate.
193 This is a synonym for `%I:%M:%S %p'.
196 This is a synonym for `%H:%M'.
199 This stands for the seconds (00-60).
202 This stands for a tab character.
205 This is a synonym for `%H:%M:%S'.
208 This stands for the week of the year (01-52), assuming that
209 weeks start on Sunday.
212 This stands for the numeric day of week (0-6). Sunday is day
216 This stands for the week of the year (01-52), assuming that
217 weeks start on Monday.
220 This has a locale-specific meaning. In the default locale
221 (named C), it is equivalent to `%D'.
224 This has a locale-specific meaning. In the default locale
225 (named C), it is equivalent to `%T'.
228 This stands for the year without century (00-99).
231 This stands for the year with century.
234 This stands for the time zone abbreviation.
236 - Function: decode-time time
237 This function converts a time value into calendrical information.
238 The return value is a list of nine elements, as follows:
240 (SECONDS MINUTES HOUR DAY MONTH YEAR DOW DST ZONE)
242 Here is what the elements mean:
245 The number of seconds past the minute, as an integer between
249 The number of minutes past the hour, as an integer between 0
253 The hour of the day, as an integer between 0 and 23.
256 The day of the month, as an integer between 1 and 31.
259 The month of the year, as an integer between 1 and 12.
262 The year, an integer typically greater than 1900.
265 The day of week, as an integer between 0 and 6, where 0
269 `t' if daylight savings time is effect, otherwise `nil'.
272 An integer indicating the time zone, as the number of seconds
275 Note that Common Lisp has different meanings for DOW and ZONE.
277 - Function: encode-time seconds minutes hour day month year &optional
279 This function is the inverse of `decode-time'. It converts seven
280 items of calendrical data into a time value. For the meanings of
281 the arguments, see the table above under `decode-time'.
283 Year numbers less than 100 are treated just like other year
284 numbers. If you want them to stand for years above 1900, you must
285 alter them yourself before you call `encode-time'.
287 The optional argument ZONE defaults to the current time zone and
288 its daylight savings time rules. If specified, it can be either a
289 list (as you would get from `current-time-zone') or an integer (as
290 you would get from `decode-time'). The specified zone is used
291 without any further alteration for daylight savings time.
294 File: lispref.info, Node: Timers, Next: Terminal Input, Prev: Time Conversion, Up: System Interface
296 Timers for Delayed Execution
297 ============================
299 You can set up a timer to call a function at a specified future time.
301 - Function: add-timeout secs function object &optional resignal
302 This function adds a timeout, to be signaled after the timeout
303 period has elapsed. SECS is a number of seconds, expressed as an
304 integer or a float. FUNCTION will be called after that many
305 seconds have elapsed, with one argument, the given OBJECT. If the
306 optional RESIGNAL argument is provided, then after this timeout
307 expires, `add-timeout' will automatically be called again with
308 RESIGNAL as the first argument.
310 This function returns an object which is the "id" of this
311 particular timeout. You can pass that object to `disable-timeout'
312 to turn off the timeout before it has been signalled.
314 The number of seconds may be expressed as a floating-point number,
315 in which case some fractional part of a second will be used.
316 Caveat: the usable timeout granularity will vary from system to
319 Adding a timeout causes a timeout event to be returned by
320 `next-event', and the function will be invoked by
321 `dispatch-event', so if XEmacs is in a tight loop, the function
322 will not be invoked until the next call to sit-for or until the
323 return to top-level (the same is true of process filters).
325 WARNING: if you are thinking of calling add-timeout from inside of
326 a callback function as a way of resignalling a timeout, think
327 again. There is a race condition. That's why the RESIGNAL
330 (NOTE: In FSF Emacs, this function is called `run-at-time' and has
331 different semantics.)
333 - Function: disable-timeout id
334 Cancel the requested action for ID, which should be a value
335 previously returned by `add-timeout'. This cancels the effect of
336 that call to `add-timeout'; the arrival of the specified time will
337 not cause anything special to happen. (NOTE: In FSF Emacs, this
338 function is called `cancel-timer'.)
341 File: lispref.info, Node: Terminal Input, Next: Terminal Output, Prev: Timers, Up: System Interface
346 This section describes functions and variables for recording or
347 manipulating terminal input. See *Note Display::, for related
352 * Input Modes:: Options for how input is processed.
353 * Translating Input:: Low level conversion of some characters or events
355 * Recording Input:: Saving histories of recent or all input events.
358 File: lispref.info, Node: Input Modes, Next: Translating Input, Up: Terminal Input
363 - Function: set-input-mode interrupt flow meta quit-char
364 This function sets the mode for reading keyboard input. If
365 INTERRUPT is non-null, then XEmacs uses input interrupts. If it is
366 `nil', then it uses CBREAK mode. When XEmacs communicates
367 directly with X, it ignores this argument and uses interrupts if
368 that is the way it knows how to communicate.
370 If FLOW is non-`nil', then XEmacs uses XON/XOFF (`C-q', `C-s')
371 flow control for output to the terminal. This has no effect except
372 in CBREAK mode. *Note Flow Control::.
374 The default setting is system dependent. Some systems always use
375 CBREAK mode regardless of what is specified.
377 The argument META controls support for input character codes above
378 127. If META is `t', XEmacs converts characters with the 8th bit
379 set into Meta characters. If META is `nil', XEmacs disregards the
380 8th bit; this is necessary when the terminal uses it as a parity
381 bit. If META is neither `t' nor `nil', XEmacs uses all 8 bits of
382 input unchanged. This is good for terminals using European 8-bit
385 If QUIT-CHAR is non-`nil', it specifies the character to use for
386 quitting. Normally this character is `C-g'. *Note Quitting::.
388 The `current-input-mode' function returns the input mode settings
389 XEmacs is currently using.
391 - Function: current-input-mode
392 This function returns current mode for reading keyboard input. It
393 returns a list, corresponding to the arguments of `set-input-mode',
394 of the form `(INTERRUPT FLOW META QUIT)' in which:
396 is non-`nil' when XEmacs is using interrupt-driven input. If
397 `nil', Emacs is using CBREAK mode.
400 is non-`nil' if XEmacs uses XON/XOFF (`C-q', `C-s') flow
401 control for output to the terminal. This value has no effect
402 unless INTERRUPT is non-`nil'.
405 is `t' if XEmacs treats the eighth bit of input characters as
406 the meta bit; `nil' means XEmacs clears the eighth bit of
407 every input character; any other value means XEmacs uses all
408 eight bits as the basic character code.
411 is the character XEmacs currently uses for quitting, usually
415 File: lispref.info, Node: Translating Input, Next: Recording Input, Prev: Input Modes, Up: Terminal Input
417 Translating Input Events
418 ------------------------
420 This section describes features for translating input events into
421 other input events before they become part of key sequences.
423 - Variable: function-key-map
424 This variable holds a keymap that describes the character sequences
425 sent by function keys on an ordinary character terminal. This
426 keymap uses the same data structure as other keymaps, but is used
427 differently: it specifies translations to make while reading
430 If `function-key-map' "binds" a key sequence K to a vector V, then
431 when K appears as a subsequence _anywhere_ in a key sequence, it
432 is replaced with the events in V.
434 For example, VT100 terminals send `<ESC> O P' when the keypad PF1
435 key is pressed. Therefore, we want XEmacs to translate that
436 sequence of events into the single event `pf1'. We accomplish
437 this by "binding" `<ESC> O P' to `[pf1]' in `function-key-map',
440 Thus, typing `C-c <PF1>' sends the character sequence `C-c <ESC> O
441 P'; later the function `read-key-sequence' translates this back
442 into `C-c <PF1>', which it returns as the vector `[?\C-c pf1]'.
444 Entries in `function-key-map' are ignored if they conflict with
445 bindings made in the minor mode, local, or global keymaps. The
446 intent is that the character sequences that function keys send
447 should not have command bindings in their own right.
449 The value of `function-key-map' is usually set up automatically
450 according to the terminal's Terminfo or Termcap entry, but
451 sometimes those need help from terminal-specific Lisp files.
452 XEmacs comes with terminal-specific files for many common
453 terminals; their main purpose is to make entries in
454 `function-key-map' beyond those that can be deduced from Termcap
455 and Terminfo. *Note Terminal-Specific::.
457 Emacs versions 18 and earlier used totally different means of
458 detecting the character sequences that represent function keys.
460 - Variable: key-translation-map
461 This variable is another keymap used just like `function-key-map'
462 to translate input events into other events. It differs from
463 `function-key-map' in two ways:
465 * `key-translation-map' goes to work after `function-key-map' is
466 finished; it receives the results of translation by
469 * `key-translation-map' overrides actual key bindings.
471 The intent of `key-translation-map' is for users to map one
472 character set to another, including ordinary characters normally
473 bound to `self-insert-command'.
475 You can use `function-key-map' or `key-translation-map' for more
476 than simple aliases, by using a function, instead of a key sequence, as
477 the "translation" of a key. Then this function is called to compute
478 the translation of that key.
480 The key translation function receives one argument, which is the
481 prompt that was specified in `read-key-sequence'--or `nil' if the key
482 sequence is being read by the editor command loop. In most cases you
483 can ignore the prompt value.
485 If the function reads input itself, it can have the effect of
486 altering the event that follows. For example, here's how to define
487 `C-c h' to turn the character that follows into a Hyper character:
489 (defun hyperify (prompt)
490 (let ((e (read-event)))
491 (vector (if (numberp e)
492 (logior (lsh 1 20) e)
493 (if (memq 'hyper (event-modifiers e))
495 (add-event-modifier "H-" e))))))
497 (defun add-event-modifier (string e)
498 (let ((symbol (if (symbolp e) e (car e))))
499 (setq symbol (intern (concat string
500 (symbol-name symbol))))
503 (cons symbol (cdr e)))))
505 (define-key function-key-map "\C-ch" 'hyperify)
507 The `iso-transl' library uses this feature to provide a way of
508 inputting non-ASCII Latin-1 characters.
511 File: lispref.info, Node: Recording Input, Prev: Translating Input, Up: Terminal Input
516 - Function: recent-keys &optional number
517 This function returns a vector containing recent input events from
518 the keyboard or mouse. By default, 100 events are recorded, which
519 is how many `recent-keys' returns.
521 All input events are included, whether or not they were used as
522 parts of key sequences. Thus, you always get the last 100 inputs,
523 not counting keyboard macros. (Events from keyboard macros are
524 excluded because they are less interesting for debugging; it
525 should be enough to see the events that invoked the macros.)
527 If NUMBER is specified, not more than NUMBER events will be
528 returned. You may change the number of stored events using
529 `set-recent-keys-ring-size'.
531 - Function: recent-keys-ring-size
532 This function returns the number of recent events stored
533 internally. This is also the maximum number of events
534 `recent-keys' can return. By default, 100 events are stored.
536 - Function: set-recent-keys-ring-size size
537 This function changes the number of events stored by XEmacs and
538 returned by `recent-keys'.
540 For example, `(set-recent-keys-ring-size 250)' will make XEmacs
541 remember last 250 events and will make `recent-keys' return last
542 250 events by default.
544 - Command: open-dribble-file filename
545 This function opens a "dribble file" named FILENAME. When a
546 dribble file is open, each input event from the keyboard or mouse
547 (but not those from keyboard macros) is written in that file. A
548 non-character event is expressed using its printed representation
549 surrounded by `<...>'.
551 You close the dribble file by calling this function with an
554 This function is normally used to record the input necessary to
555 trigger an XEmacs bug, for the sake of a bug report.
557 (open-dribble-file "~/dribble")
560 See also the `open-termscript' function (*note Terminal Output::).
563 File: lispref.info, Node: Terminal Output, Next: Flow Control, Prev: Terminal Input, Up: System Interface
568 The terminal output functions send output to the terminal or keep
569 track of output sent to the terminal. The function `device-baud-rate'
570 tells you what XEmacs thinks is the output speed of the terminal.
572 - Function: device-baud-rate &optional device
573 This function's value is the output speed of the terminal
574 associated with DEVICE, as far as XEmacs knows. DEVICE defaults
575 to the selected device (usually the only device) if omitted.
576 Changing this value does not change the speed of actual data
577 transmission, but the value is used for calculations such as
578 padding. This value has no effect for window-system devices.
579 (This is different in FSF Emacs, where the baud rate also affects
580 decisions about whether to scroll part of the screen or repaint,
581 even when using a window system.)
583 The value is measured in bits per second.
585 XEmacs attempts to automatically initialize the baud rate by querying
586 the terminal. If you are running across a network, however, and
587 different parts of the network work are at different baud rates, the
588 value returned by XEmacs may be different from the value used by your
589 local terminal. Some network protocols communicate the local terminal
590 speed to the remote machine, so that XEmacs and other programs can get
591 the proper value, but others do not. If XEmacs has the wrong value, it
592 makes decisions that are less than optimal. To fix the problem, use
593 `set-device-baud-rate'.
595 - Function: set-device-baud-rate &optional device
596 This function sets the output speed of DEVICE. See
597 `device-baud-rate'. DEVICE defaults to the selected device
598 (usually the only device) if omitted.
600 - Function: send-string-to-terminal char-or-string &optional stdout-p
602 This function sends CHAR-OR-STRING to the terminal without
603 alteration. Control characters in CHAR-OR-STRING have
604 terminal-dependent effects.
606 If DEVICE is `nil', this function writes to XEmacs's stderr, or to
607 stdout if STDOUT-P is non-`nil'. Otherwise, DEVICE should be a
608 tty or stream device, and the function writes to the device's
609 normal or error output, according to STDOUT-P.
611 One use of this function is to define function keys on terminals
612 that have downloadable function key definitions. For example,
613 this is how on certain terminals to define function key 4 to move
614 forward four characters (by transmitting the characters `C-u C-f'
617 (send-string-to-terminal "\eF4\^U\^F")
620 - Command: open-termscript filename
621 This function is used to open a "termscript file" that will record
622 all the characters sent by XEmacs to the terminal. (If there are
623 multiple tty or stream devices, all characters sent to all such
624 devices are recorded.) The function returns `nil'. Termscript
625 files are useful for investigating problems where XEmacs garbles
626 the screen, problems that are due to incorrect Termcap entries or
627 to undesirable settings of terminal options more often than to
628 actual XEmacs bugs. Once you are certain which characters were
629 actually output, you can determine reliably whether they
630 correspond to the Termcap specifications in use.
632 A `nil' value for FILENAME stops recording terminal output.
634 See also `open-dribble-file' in *Note Terminal Input::.
636 (open-termscript "../junk/termscript")
640 File: lispref.info, Node: Flow Control, Next: Batch Mode, Prev: Terminal Output, Up: System Interface
645 This section attempts to answer the question "Why does XEmacs choose
646 to use flow-control characters in its command character set?" For a
647 second view on this issue, read the comments on flow control in the
648 `emacs/INSTALL' file from the distribution; for help with Termcap
649 entries and DEC terminal concentrators, see `emacs/etc/TERMS'.
651 At one time, most terminals did not need flow control, and none used
652 `C-s' and `C-q' for flow control. Therefore, the choice of `C-s' and
653 `C-q' as command characters was uncontroversial. XEmacs, for economy
654 of keystrokes and portability, used nearly all the ASCII control
655 characters, with mnemonic meanings when possible; thus, `C-s' for
656 search and `C-q' for quote.
658 Later, some terminals were introduced which required these characters
659 for flow control. They were not very good terminals for full-screen
660 editing, so XEmacs maintainers did not pay attention. In later years,
661 flow control with `C-s' and `C-q' became widespread among terminals,
662 but by this time it was usually an option. And the majority of users,
663 who can turn flow control off, were unwilling to switch to less
664 mnemonic key bindings for the sake of flow control.
666 So which usage is "right", XEmacs's or that of some terminal and
667 concentrator manufacturers? This question has no simple answer.
669 One reason why we are reluctant to cater to the problems caused by
670 `C-s' and `C-q' is that they are gratuitous. There are other
671 techniques (albeit less common in practice) for flow control that
672 preserve transparency of the character stream. Note also that their use
673 for flow control is not an official standard. Interestingly, on the
674 model 33 teletype with a paper tape punch (which is very old), `C-s'
675 and `C-q' were sent by the computer to turn the punch on and off!
677 As X servers and other window systems replace character-only
678 terminals, this problem is gradually being cured. For the mean time,
679 XEmacs provides a convenient way of enabling flow control if you want
680 it: call the function `enable-flow-control'.
682 - Function: enable-flow-control
683 This function enables use of `C-s' and `C-q' for output flow
684 control, and provides the characters `C-\' and `C-^' as aliases
685 for them using `keyboard-translate-table' (*note Translating
688 You can use the function `enable-flow-control-on' in your `.emacs'
689 file to enable flow control automatically on certain terminal types.
691 - Function: enable-flow-control-on &rest termtypes
692 This function enables flow control, and the aliases `C-\' and
693 `C-^', if the terminal type is one of TERMTYPES. For example:
695 (enable-flow-control-on "vt200" "vt300" "vt101" "vt131")
697 Here is how `enable-flow-control' does its job:
699 1. It sets CBREAK mode for terminal input, and tells the operating
700 system to handle flow control, with `(set-input-mode nil t)'.
702 2. It sets up `keyboard-translate-table' to translate `C-\' and `C-^'
703 into `C-s' and `C-q'. Except at its very lowest level, XEmacs
704 never knows that the characters typed were anything but `C-s' and
705 `C-q', so you can in effect type them as `C-\' and `C-^' even when
706 they are input for other commands. *Note Translating Input::.
708 If the terminal is the source of the flow control characters, then
709 once you enable kernel flow control handling, you probably can make do
710 with less padding than normal for that terminal. You can reduce the
711 amount of padding by customizing the Termcap entry. You can also
712 reduce it by setting `baud-rate' to a smaller value so that XEmacs uses
713 a smaller speed when calculating the padding needed. *Note Terminal
717 File: lispref.info, Node: Batch Mode, Prev: Flow Control, Up: System Interface
722 The command line option `-batch' causes XEmacs to run
723 noninteractively. In this mode, XEmacs does not read commands from the
724 terminal, it does not alter the terminal modes, and it does not expect
725 to be outputting to an erasable screen. The idea is that you specify
726 Lisp programs to run; when they are finished, XEmacs should exit. The
727 way to specify the programs to run is with `-l FILE', which loads the
728 library named FILE, and `-f FUNCTION', which calls FUNCTION with no
731 Any Lisp program output that would normally go to the echo area,
732 either using `message' or using `prin1', etc., with `t' as the stream,
733 goes instead to XEmacs's standard error descriptor when in batch mode.
734 Thus, XEmacs behaves much like a noninteractive application program.
735 (The echo area output that XEmacs itself normally generates, such as
736 command echoing, is suppressed entirely.)
738 - Function: noninteractive
739 This function returns non-`nil' when XEmacs is running in batch
742 - Variable: noninteractive
743 This variable is non-`nil' when XEmacs is running in batch mode.
744 Setting this variable to `nil', however, will not change whether
745 XEmacs is running in batch mode, and will not change the return
746 value of the `noninteractive' function.
749 File: lispref.info, Node: X-Windows, Next: ToolTalk Support, Prev: System Interface, Up: Top
751 Functions Specific to the X Window System
752 *****************************************
754 XEmacs provides the concept of "devices", which generalizes
755 connections to an X server, a TTY device, etc. Most information about
756 an X server that XEmacs is connected to can be determined through
757 general console and device functions. *Note Consoles and Devices::.
758 However, there are some features of the X Window System that do not
759 generalize well, and they are covered specially here.
763 * X Selections:: Transferring text to and from other X clients.
764 * X Server:: Information about the X server connected to
766 * X Miscellaneous:: Other X-specific functions and variables.
769 File: lispref.info, Node: X Selections, Next: X Server, Up: X-Windows
774 The X server records a set of "selections" which permit transfer of
775 data between application programs. The various selections are
776 distinguished by "selection types", represented in XEmacs by symbols.
777 X clients including XEmacs can read or set the selection for any given
780 - Function: x-own-selection data &optional type
781 This function sets a "selection" in the X server. It takes two
782 arguments: a value, DATA, and the selection type TYPE to assign it
783 to. DATA may be a string, a cons of two markers, or an extent.
784 In the latter cases, the selection is considered to be the text
785 between the markers, or between the extent's endpoints.
787 Each possible TYPE has its own selection value, which changes
788 independently. The usual values of TYPE are `PRIMARY' and
789 `SECONDARY'; these are symbols with upper-case names, in accord
790 with X Windows conventions. The default is `PRIMARY'.
792 (In FSF Emacs, this function is called `x-set-selection' and takes
793 different arguments.)
795 - Function: x-get-selection
796 This function accesses selections set up by XEmacs or by other X
797 clients. It returns the value of the current primary selection.
799 - Function: x-disown-selection &optional secondary-p
800 Assuming we own the selection, this function disowns it. If
801 SECONDARY-P is non-`nil', the secondary selection instead of the
802 primary selection is discarded.
804 The X server also has a set of numbered "cut buffers" which can
805 store text or other data being moved between applications. Cut buffers
806 are considered obsolete, but XEmacs supports them for the sake of X
807 clients that still use them.
809 - Function: x-get-cutbuffer &optional n
810 This function returns the contents of cut buffer number N. (This
811 function is called `x-get-cut-buffer' in FSF Emacs.)
813 - Function: x-store-cutbuffer string
814 This function stores STRING into the first cut buffer (cut buffer
815 0), moving the other values down through the series of cut buffers,
816 kill-ring-style. (This function is called `x-set-cut-buffer' in FSF
820 File: lispref.info, Node: X Server, Next: X Miscellaneous, Prev: X Selections, Up: X-Windows
825 This section describes how to access and change the overall status of
826 the X server XEmacs is using.
830 * Resources:: Getting resource values from the server.
831 * Server Data:: Getting info about the X server.
832 * Grabs:: Restricting access to the server by other apps.
835 File: lispref.info, Node: Resources, Next: Server Data, Up: X Server
840 - Function: default-x-device
841 This function return the default X device for resourcing. This is
842 the first-created X device that still exists.
844 - Function: x-get-resource name class type &optional locale device
846 This function retrieves a resource value from the X resource
849 * The first arg is the name of the resource to retrieve, such as
852 * The second arg is the class of the resource to retrieve, like
855 * The third arg should be one of the symbols `string',
856 `integer', `natnum', or `boolean', specifying the type of
857 object that the database is searched for.
859 * The fourth arg is the locale to search for the resources on,
860 and can currently be a a buffer, a frame, a device, or the
861 symbol `global'. If omitted, it defaults to `global'.
863 * The fifth arg is the device to search for the resources on.
864 (The resource database for a particular device is constructed
865 by combining non-device- specific resources such any
866 command-line resources specified and any app-defaults files
867 found [or the fallback resources supplied by XEmacs, if no
868 app-defaults file is found] with device-specific resources
869 such as those supplied using `xrdb'.) If omitted, it defaults
870 to the device of LOCALE, if a device can be derived (i.e. if
871 LOCALE is a frame or device), and otherwise defaults to the
872 value of `default-x-device'.
874 * The sixth arg NOERROR, if non-`nil', means do not signal an
875 error if a bogus resource specification was retrieved (e.g.
876 if a non-integer was given when an integer was requested).
877 In this case, a warning is issued instead.
879 The resource names passed to this function are looked up relative
882 If you want to search for a subresource, you just need to specify
883 the resource levels in NAME and CLASS. For example, NAME could be
884 `"modeline.attributeFont"', and CLASS `"Face.AttributeFont"'.
888 1. If LOCALE is a buffer, a call
890 `(x-get-resource "foreground" "Foreground" 'string SOME-BUFFER)'
892 is an interface to a C call something like
894 `XrmGetResource (db, "xemacs.buffer.BUFFER-NAME.foreground",
895 "Emacs.EmacsLocaleType.EmacsBuffer.Foreground",
898 2. If LOCALE is a frame, a call
900 `(x-get-resource "foreground" "Foreground" 'string SOME-FRAME)'
902 is an interface to a C call something like
904 `XrmGetResource (db, "xemacs.frame.FRAME-NAME.foreground",
905 "Emacs.EmacsLocaleType.EmacsFrame.Foreground",
908 3. If LOCALE is a device, a call
910 `(x-get-resource "foreground" "Foreground" 'string SOME-DEVICE)'
912 is an interface to a C call something like
914 `XrmGetResource (db, "xemacs.device.DEVICE-NAME.foreground",
915 "Emacs.EmacsLocaleType.EmacsDevice.Foreground",
918 4. If LOCALE is the symbol `global', a call
920 `(x-get-resource "foreground" "Foreground" 'string 'global)'
922 is an interface to a C call something like
924 `XrmGetResource (db, "xemacs.foreground",
928 Note that for `global', no prefix is added other than that of the
929 application itself; thus, you can use this locale to retrieve
930 arbitrary application resources, if you really want to.
932 The returned value of this function is `nil' if the queried
933 resource is not found. If TYPE is `string', a string is returned,
934 and if it is `integer', an integer is returned. If TYPE is
935 `boolean', then the returned value is the list `(t)' for true,
936 `(nil)' for false, and is `nil' to mean "unspecified".
938 - Function: x-put-resource resource-line &optional device
939 This function adds a resource to the resource database for DEVICE.
940 RESOURCE-LINE specifies the resource to add and should be a
941 standard resource specification.
943 - Variable: x-emacs-application-class
944 This variable holds The X application class of the XEmacs process.
945 This controls, among other things, the name of the "app-defaults"
946 file that XEmacs will use. For changes to this variable to take
947 effect, they must be made before the connection to the X server is
948 initialized, that is, this variable may only be changed before
949 XEmacs is dumped, or by setting it in the file
950 `lisp/term/x-win.el'.
952 By default, this variable is nil at startup. When the connection
953 to the X server is first initialized, the X resource database will
954 be consulted and the value will be set according to whether any
955 resources are found for the application class "XEmacs".
958 File: lispref.info, Node: Server Data, Next: Grabs, Prev: Resources, Up: X Server
960 Data about the X Server
961 -----------------------
963 This section describes functions and a variable that you can use to
964 get information about the capabilities and origin of the X server
965 corresponding to a particular device. The device argument is generally
966 optional and defaults to the selected device.
968 - Function: x-server-version &optional device
969 This function returns the list of version numbers of the X server
970 DEVICE is on. The returned value is a list of three integers: the
971 major and minor version numbers of the X protocol in use, and the
972 vendor-specific release number.
974 - Function: x-server-vendor &optional device
975 This function returns the vendor supporting the X server DEVICE is
978 - Function: x-display-visual-class &optional device
979 This function returns the visual class of the display DEVICE is
980 on. The value is one of the symbols `static-gray', `gray-scale',
981 `static-color', `pseudo-color', `true-color', and `direct-color'.
982 (Note that this is different from previous versions of XEmacs,
983 which returned `StaticGray', `GrayScale', etc.)
986 File: lispref.info, Node: Grabs, Prev: Server Data, Up: X Server
988 Restricting Access to the Server by Other Apps
989 ----------------------------------------------
991 - Function: x-grab-keyboard &optional device
992 This function grabs the keyboard on the given device (defaulting
993 to the selected one). So long as the keyboard is grabbed, all
994 keyboard events will be delivered to XEmacs--it is not possible
995 for other X clients to eavesdrop on them. Ungrab the keyboard
996 with `x-ungrab-keyboard' (use an `unwind-protect'). Returns `t'
997 if the grab was successful; `nil' otherwise.
999 - Function: x-ungrab-keyboard &optional device
1000 This function releases a keyboard grab made with `x-grab-keyboard'.
1002 - Function: x-grab-pointer &optional device cursor ignore-keyboard
1003 This function grabs the pointer and restricts it to its current
1004 window. If optional DEVICE argument is `nil', the selected device
1005 will be used. If optional CURSOR argument is non-`nil', change
1006 the pointer shape to that until `x-ungrab-pointer' is called (it
1007 should be an object returned by the `make-cursor' function). If
1008 the second optional argument IGNORE-KEYBOARD is non-`nil', ignore
1009 all keyboard events during the grab. Returns `t' if the grab is
1010 successful, `nil' otherwise.
1012 - Function: x-ungrab-pointer &optional device
1013 This function releases a pointer grab made with `x-grab-pointer'.
1014 If optional first arg DEVICE is `nil' the selected device is used.
1015 If it is `t' the pointer will be released on all X devices.
1018 File: lispref.info, Node: X Miscellaneous, Prev: X Server, Up: X-Windows
1020 Miscellaneous X Functions and Variables
1021 =======================================
1023 - Variable: x-bitmap-file-path
1024 This variable holds a list of the directories in which X bitmap
1025 files may be found. If `nil', this is initialized from the
1026 `"*bitmapFilePath"' resource. This is used by the
1027 `make-image-instance' function (however, note that if the
1028 environment variable `XBMLANGPATH' is set, it is consulted first).
1030 - Variable: x-library-search-path
1031 This variable holds the search path used by `read-color' to find
1034 - Function: x-valid-keysym-name-p keysym
1035 This function returns true if KEYSYM names a keysym that the X
1036 library knows about. Valid keysyms are listed in the files
1037 `/usr/include/X11/keysymdef.h' and in `/usr/lib/X11/XKeysymDB', or
1038 whatever the equivalents are on your system.
1040 - Function: x-window-id &optional frame
1041 This function returns the ID of the X11 window. This gives us a
1042 chance to manipulate the Emacs window from within a different
1043 program. Since the ID is an unsigned long, we return it as a
1046 - Variable: x-allow-sendevents
1047 If non-`nil', synthetic events are allowed. `nil' means they are
1048 ignored. Beware: allowing XEmacs to process SendEvents opens a
1051 - Function: x-debug-mode arg &optional device
1052 With a true arg, make the connection to the X server synchronous.
1053 With false, make it asynchronous. Synchronous connections are
1054 much slower, but are useful for debugging. (If you get X errors,
1055 make the connection synchronous, and use a debugger to set a
1056 breakpoint on `x_error_handler'. Your backtrace of the C stack
1057 will now be useful. In asynchronous mode, the stack above
1058 `x_error_handler' isn't helpful because of buffering.) If DEVICE
1059 is not specified, the selected device is assumed.
1061 Calling this function is the same as calling the C function
1062 `XSynchronize', or starting the program with the `-sync' command
1065 - Variable: x-debug-events
1066 If non-zero, debug information about events that XEmacs sees is
1067 displayed. Information is displayed on stderr. Currently defined
1070 * 1 == non-verbose output
1072 * 2 == verbose output
1075 File: lispref.info, Node: ToolTalk Support, Next: LDAP Support, Prev: X-Windows, Up: Top
1082 * XEmacs ToolTalk API Summary::
1083 * Sending Messages::
1084 * Receiving Messages::
1087 File: lispref.info, Node: XEmacs ToolTalk API Summary, Next: Sending Messages, Up: ToolTalk Support
1089 XEmacs ToolTalk API Summary
1090 ===========================
1092 The XEmacs Lisp interface to ToolTalk is similar, at least in spirit,
1093 to the standard C ToolTalk API. Only the message and pattern parts of
1094 the API are supported at present; more of the API could be added if
1095 needed. The Lisp interface departs from the C API in a few ways:
1097 * ToolTalk is initialized automatically at XEmacs startup-time.
1098 Messages can only be sent other ToolTalk applications connected to
1099 the same X11 server that XEmacs is running on.
1101 * There are fewer entry points; polymorphic functions with keyword
1102 arguments are used instead.
1104 * The callback interface is simpler and marginally less functional.
1105 A single callback may be associated with a message or a pattern;
1106 the callback is specified with a Lisp symbol (the symbol should
1107 have a function binding).
1109 * The session attribute for messages and patterns is always
1110 initialized to the default session.
1112 * Anywhere a ToolTalk enum constant, e.g. `TT_SESSION', is valid, one
1113 can substitute the corresponding symbol, e.g. `'TT_SESSION'. This
1114 simplifies building lists that represent messages and patterns.
1117 File: lispref.info, Node: Sending Messages, Next: Receiving Messages, Prev: XEmacs ToolTalk API Summary, Up: ToolTalk Support
1124 * Example of Sending Messages::
1125 * Elisp Interface for Sending Messages::
1128 File: lispref.info, Node: Example of Sending Messages, Next: Elisp Interface for Sending Messages, Up: Sending Messages
1130 Example of Sending Messages
1131 ---------------------------
1133 Here's a simple example that sends a query to another application
1134 and then displays its reply. Both the query and the reply are stored
1135 in the first argument of the message.
1137 (defun tooltalk-random-query-handler (msg)
1138 (let ((state (get-tooltalk-message-attribute msg 'state)))
1140 ((eq state 'TT_HANDLED)
1141 (message (get-tooltalk-message-attribute msg arg_val 0)))
1142 ((memq state '(TT_FAILED TT_REJECTED))
1143 (message "Random query turns up nothing")))))
1145 (defvar random-query-message
1148 address TT_PROCEDURE
1150 args '((TT_INOUT "?" "string"))
1151 callback tooltalk-random-query-handler))
1153 (let ((m (make-tooltalk-message random-query-message)))
1154 (send-tooltalk-message m))
projects / chise / xemacs-chise.git- / blob