Foundation instead of in the original English.
\1f
-File: lispref.info, Node: Level 3 Primitives, Next: Dynamic Messaging, Prev: Level 3 Basics, Up: I18N Level 3
+File: lispref.info, Node: Input Modes, Next: Translating Input, Up: Terminal Input
+
+Input Modes
+-----------
+
+ - Function: set-input-mode interrupt flow meta quit-char
+ This function sets the mode for reading keyboard input. If
+ INTERRUPT is non-null, then XEmacs uses input interrupts. If it is
+ `nil', then it uses CBREAK mode. When XEmacs communicates
+ directly with X, it ignores this argument and uses interrupts if
+ that is the way it knows how to communicate.
+
+ If FLOW is non-`nil', then XEmacs uses XON/XOFF (`C-q', `C-s')
+ flow control for output to the terminal. This has no effect except
+ in CBREAK mode. *Note Flow Control::.
+
+ The default setting is system dependent. Some systems always use
+ CBREAK mode regardless of what is specified.
+
+ The argument META controls support for input character codes above
+ 127. If META is `t', XEmacs converts characters with the 8th bit
+ set into Meta characters. If META is `nil', XEmacs disregards the
+ 8th bit; this is necessary when the terminal uses it as a parity
+ bit. If META is neither `t' nor `nil', XEmacs uses all 8 bits of
+ input unchanged. This is good for terminals using European 8-bit
+ character sets.
+
+ If QUIT-CHAR is non-`nil', it specifies the character to use for
+ quitting. Normally this character is `C-g'. *Note Quitting::.
+
+ The `current-input-mode' function returns the input mode settings
+XEmacs is currently using.
+
+ - Function: current-input-mode
+ This function returns current mode for reading keyboard input. It
+ returns a list, corresponding to the arguments of `set-input-mode',
+ of the form `(INTERRUPT FLOW META QUIT)' in which:
+ INTERRUPT
+ is non-`nil' when XEmacs is using interrupt-driven input. If
+ `nil', Emacs is using CBREAK mode.
+
+ FLOW
+ is non-`nil' if XEmacs uses XON/XOFF (`C-q', `C-s') flow
+ control for output to the terminal. This value has no effect
+ unless INTERRUPT is non-`nil'.
+
+ META
+ is `t' if XEmacs treats the eighth bit of input characters as
+ the meta bit; `nil' means XEmacs clears the eighth bit of
+ every input character; any other value means XEmacs uses all
+ eight bits as the basic character code.
+
+ QUIT
+ is the character XEmacs currently uses for quitting, usually
+ `C-g'.
-Level 3 Primitives
-------------------
-
- - Function: gettext string
- This function looks up STRING in the default message domain and
- returns its translation. If `I18N3' was not enabled when XEmacs
- was compiled, it just returns STRING.
-
- - Function: dgettext domain string
- This function looks up STRING in the specified message domain and
- returns its translation. If `I18N3' was not enabled when XEmacs
- was compiled, it just returns STRING.
-
- - Function: bind-text-domain domain pathname
- This function associates a pathname with a message domain. Here's
- how the path to message file is constructed under SunOS 5.x:
-
- `{pathname}/{LANG}/LC_MESSAGES/{domain}.mo'
-
- If `I18N3' was not enabled when XEmacs was compiled, this function
- does nothing.
-
- - Special Form: domain string
- This function specifies the text domain used for translating
- documentation strings and interactive prompts of a function. For
- example, write:
+\1f
+File: lispref.info, Node: Translating Input, Next: Recording Input, Prev: Input Modes, Up: Terminal Input
- (defun foo (arg) "Doc string" (domain "emacs-foo") ...)
+Translating Input Events
+------------------------
- to specify `emacs-foo' as the text domain of the function `foo'.
- The "call" to `domain' is actually a declaration rather than a
- function; when actually called, `domain' just returns `nil'.
+ This section describes features for translating input events into
+other input events before they become part of key sequences.
+
+ - Variable: function-key-map
+ This variable holds a keymap that describes the character sequences
+ sent by function keys on an ordinary character terminal. This
+ keymap uses the same data structure as other keymaps, but is used
+ differently: it specifies translations to make while reading
+ events.
+
+ If `function-key-map' "binds" a key sequence K to a vector V, then
+ when K appears as a subsequence _anywhere_ in a key sequence, it
+ is replaced with the events in V.
+
+ For example, VT100 terminals send `<ESC> O P' when the keypad PF1
+ key is pressed. Therefore, we want XEmacs to translate that
+ sequence of events into the single event `pf1'. We accomplish
+ this by "binding" `<ESC> O P' to `[pf1]' in `function-key-map',
+ when using a VT100.
+
+ Thus, typing `C-c <PF1>' sends the character sequence `C-c <ESC> O
+ P'; later the function `read-key-sequence' translates this back
+ into `C-c <PF1>', which it returns as the vector `[?\C-c pf1]'.
+
+ Entries in `function-key-map' are ignored if they conflict with
+ bindings made in the minor mode, local, or global keymaps. The
+ intent is that the character sequences that function keys send
+ should not have command bindings in their own right.
+
+ The value of `function-key-map' is usually set up automatically
+ according to the terminal's Terminfo or Termcap entry, but
+ sometimes those need help from terminal-specific Lisp files.
+ XEmacs comes with terminal-specific files for many common
+ terminals; their main purpose is to make entries in
+ `function-key-map' beyond those that can be deduced from Termcap
+ and Terminfo. *Note Terminal-Specific::.
+
+ Emacs versions 18 and earlier used totally different means of
+ detecting the character sequences that represent function keys.
+
+ - Variable: key-translation-map
+ This variable is another keymap used just like `function-key-map'
+ to translate input events into other events. It differs from
+ `function-key-map' in two ways:
+
+ * `key-translation-map' goes to work after `function-key-map' is
+ finished; it receives the results of translation by
+ `function-key-map'.
+
+ * `key-translation-map' overrides actual key bindings.
+
+ The intent of `key-translation-map' is for users to map one
+ character set to another, including ordinary characters normally
+ bound to `self-insert-command'.
+
+ You can use `function-key-map' or `key-translation-map' for more
+than simple aliases, by using a function, instead of a key sequence, as
+the "translation" of a key. Then this function is called to compute
+the translation of that key.
+
+ The key translation function receives one argument, which is the
+prompt that was specified in `read-key-sequence'--or `nil' if the key
+sequence is being read by the editor command loop. In most cases you
+can ignore the prompt value.
+
+ If the function reads input itself, it can have the effect of
+altering the event that follows. For example, here's how to define
+`C-c h' to turn the character that follows into a Hyper character:
+
+ (defun hyperify (prompt)
+ (let ((e (read-event)))
+ (vector (if (numberp e)
+ (logior (lsh 1 20) e)
+ (if (memq 'hyper (event-modifiers e))
+ e
+ (add-event-modifier "H-" e))))))
+
+ (defun add-event-modifier (string e)
+ (let ((symbol (if (symbolp e) e (car e))))
+ (setq symbol (intern (concat string
+ (symbol-name symbol))))
+ (if (symbolp e)
+ symbol
+ (cons symbol (cdr e)))))
+
+ (define-key function-key-map "\C-ch" 'hyperify)
- - Function: domain-of function
- This function returns the text domain of FUNCTION; it returns
- `nil' if it is the default domain. If `I18N3' was not enabled
- when XEmacs was compiled, it always returns `nil'.
+ The `iso-transl' library uses this feature to provide a way of
+inputting non-ASCII Latin-1 characters.
\1f
-File: lispref.info, Node: Dynamic Messaging, Next: Domain Specification, Prev: Level 3 Primitives, Up: I18N Level 3
-
-Dynamic Messaging
------------------
+File: lispref.info, Node: Recording Input, Prev: Translating Input, Up: Terminal Input
- The `format' function has been extended to permit you to change the
-order of parameter insertion. For example, the conversion format
-`%1$s' inserts parameter one as a string, while `%2$s' inserts
-parameter two. This is useful when creating translations which require
-you to change the word order.
+Recording Input
+---------------
-\1f
-File: lispref.info, Node: Domain Specification, Next: Documentation String Extraction, Prev: Dynamic Messaging, Up: I18N Level 3
-
-Domain Specification
---------------------
+ - Function: recent-keys &optional number
+ This function returns a vector containing recent input events from
+ the keyboard or mouse. By default, 100 events are recorded, which
+ is how many `recent-keys' returns.
- The default message domain of XEmacs is `emacs'. For add-on
-packages, it is best to use a different domain. For example, let us
-say we want to convert the "gorilla" package to use the domain
-`emacs-gorilla'. To translate the message "What gorilla?", use
-`dgettext' as follows:
+ All input events are included, whether or not they were used as
+ parts of key sequences. Thus, you always get the last 100 inputs,
+ not counting keyboard macros. (Events from keyboard macros are
+ excluded because they are less interesting for debugging; it
+ should be enough to see the events that invoked the macros.)
- (dgettext "emacs-gorilla" "What gorilla?")
+ If NUMBER is specified, not more than NUMBER events will be
+ returned. You may change the number of stored events using
+ `set-recent-keys-ring-size'.
- A function (or macro) which has a documentation string or an
-interactive prompt needs to be associated with the domain in order for
-the documentation or prompt to be translated. This is done with the
-`domain' special form as follows:
+ - Function: recent-keys-ring-size
+ This function returns the number of recent events stored
+ internally. This is also the maximum number of events
+ `recent-keys' can return. By default, 100 events are stored.
- (defun scratch (location)
- "Scratch the specified location."
- (domain "emacs-gorilla")
- (interactive "sScratch: ")
- ... )
+ - Function: set-recent-keys-ring-size size
+ This function changes the number of events stored by XEmacs and
+ returned by `recent-keys'.
- It is most efficient to specify the domain in the first line of the
-function body, before the `interactive' form.
+ For example, `(set-recent-keys-ring-size 250)' will make XEmacs
+ remember last 250 events and will make `recent-keys' return last
+ 250 events by default.
- For variables and constants which have documentation strings,
-specify the domain after the documentation.
+ - Command: open-dribble-file filename
+ This function opens a "dribble file" named FILENAME. When a
+ dribble file is open, each input event from the keyboard or mouse
+ (but not those from keyboard macros) is written in that file. A
+ non-character event is expressed using its printed representation
+ surrounded by `<...>'.
- - Special Form: defvar symbol [value [doc-string [domain]]]
- Example:
- (defvar weight 250 "Weight of gorilla, in pounds." "emacs-gorilla")
+ You close the dribble file by calling this function with an
+ argument of `nil'.
- - Special Form: defconst symbol [value [doc-string [domain]]]
- Example:
- (defconst limbs 4 "Number of limbs" "emacs-gorilla")
+ This function is normally used to record the input necessary to
+ trigger an XEmacs bug, for the sake of a bug report.
- Autoloaded functions which are specified in `loaddefs.el' do not need
-to have a domain specification, because their documentation strings are
-extracted into the main message base. However, for autoloaded functions
-which are specified in a separate package, use following syntax:
+ (open-dribble-file "~/dribble")
+ => nil
- - Function: autoload symbol filename &optional docstring interactive
- macro domain
- Example:
- (autoload 'explore "jungle" "Explore the jungle." nil nil "emacs-gorilla")
+ See also the `open-termscript' function (*note Terminal Output::).
\1f
-File: lispref.info, Node: Documentation String Extraction, Prev: Domain Specification, Up: I18N Level 3
-
-Documentation String Extraction
--------------------------------
+File: lispref.info, Node: Terminal Output, Next: Flow Control, Prev: Terminal Input, Up: System Interface
- The utility `etc/make-po' scans the file `DOC' to extract
-documentation strings and creates a message file `doc.po'. This file
-may then be inserted within `emacs.po'.
-
- Currently, `make-po' is hard-coded to read from `DOC' and write to
-`doc.po'. In order to extract documentation strings from an add-on
-package, first run `make-docfile' on the package to produce the `DOC'
-file. Then run `make-po -p' with the `-p' argument to indicate that we
-are extracting documentation for an add-on package.
+Terminal Output
+===============
- (The `-p' argument is a kludge to make up for a subtle difference
-between pre-loaded documentation and add-on documentation: For add-on
-packages, the final carriage returns in the strings produced by
-`make-docfile' must be ignored.)
+ The terminal output functions send output to the terminal or keep
+track of output sent to the terminal. The function `device-baud-rate'
+tells you what XEmacs thinks is the output speed of the terminal.
+
+ - Function: device-baud-rate &optional device
+ This function's value is the output speed of the terminal
+ associated with DEVICE, as far as XEmacs knows. DEVICE defaults
+ to the selected device (usually the only device) if omitted.
+ Changing this value does not change the speed of actual data
+ transmission, but the value is used for calculations such as
+ padding. This value has no effect for window-system devices.
+ (This is different in FSF Emacs, where the baud rate also affects
+ decisions about whether to scroll part of the screen or repaint,
+ even when using a window system.)
+
+ The value is measured in bits per second.
+
+ XEmacs attempts to automatically initialize the baud rate by querying
+the terminal. If you are running across a network, however, and
+different parts of the network work are at different baud rates, the
+value returned by XEmacs may be different from the value used by your
+local terminal. Some network protocols communicate the local terminal
+speed to the remote machine, so that XEmacs and other programs can get
+the proper value, but others do not. If XEmacs has the wrong value, it
+makes decisions that are less than optimal. To fix the problem, use
+`set-device-baud-rate'.
+
+ - Function: set-device-baud-rate &optional device
+ This function sets the output speed of DEVICE. See
+ `device-baud-rate'. DEVICE defaults to the selected device
+ (usually the only device) if omitted.
+
+ - Function: send-string-to-terminal char-or-string &optional stdout-p
+ device
+ This function sends CHAR-OR-STRING to the terminal without
+ alteration. Control characters in CHAR-OR-STRING have
+ terminal-dependent effects.
+
+ If DEVICE is `nil', this function writes to XEmacs's stderr, or to
+ stdout if STDOUT-P is non-`nil'. Otherwise, DEVICE should be a
+ tty or stream device, and the function writes to the device's
+ normal or error output, according to STDOUT-P.
+
+ One use of this function is to define function keys on terminals
+ that have downloadable function key definitions. For example,
+ this is how on certain terminals to define function key 4 to move
+ forward four characters (by transmitting the characters `C-u C-f'
+ to the computer):
+
+ (send-string-to-terminal "\eF4\^U\^F")
+ => nil
+
+ - Command: open-termscript filename
+ This function is used to open a "termscript file" that will record
+ all the characters sent by XEmacs to the terminal. (If there are
+ multiple tty or stream devices, all characters sent to all such
+ devices are recorded.) The function returns `nil'. Termscript
+ files are useful for investigating problems where XEmacs garbles
+ the screen, problems that are due to incorrect Termcap entries or
+ to undesirable settings of terminal options more often than to
+ actual XEmacs bugs. Once you are certain which characters were
+ actually output, you can determine reliably whether they
+ correspond to the Termcap specifications in use.
+
+ A `nil' value for FILENAME stops recording terminal output.
+
+ See also `open-dribble-file' in *Note Terminal Input::.
+
+ (open-termscript "../junk/termscript")
+ => nil
\1f
-File: lispref.info, Node: I18N Level 4, Prev: I18N Level 3, Up: Internationalization
+File: lispref.info, Node: Flow Control, Next: Batch Mode, Prev: Terminal Output, Up: System Interface
-I18N Level 4
+Flow Control
============
- The Asian-language support in XEmacs is called "MULE". *Note MULE::.
+ This section attempts to answer the question "Why does XEmacs choose
+to use flow-control characters in its command character set?" For a
+second view on this issue, read the comments on flow control in the
+`emacs/INSTALL' file from the distribution; for help with Termcap
+entries and DEC terminal concentrators, see `emacs/etc/TERMS'.
+
+ At one time, most terminals did not need flow control, and none used
+`C-s' and `C-q' for flow control. Therefore, the choice of `C-s' and
+`C-q' as command characters was uncontroversial. XEmacs, for economy
+of keystrokes and portability, used nearly all the ASCII control
+characters, with mnemonic meanings when possible; thus, `C-s' for
+search and `C-q' for quote.
+
+ Later, some terminals were introduced which required these characters
+for flow control. They were not very good terminals for full-screen
+editing, so XEmacs maintainers did not pay attention. In later years,
+flow control with `C-s' and `C-q' became widespread among terminals,
+but by this time it was usually an option. And the majority of users,
+who can turn flow control off, were unwilling to switch to less
+mnemonic key bindings for the sake of flow control.
+
+ So which usage is "right", XEmacs's or that of some terminal and
+concentrator manufacturers? This question has no simple answer.
+
+ One reason why we are reluctant to cater to the problems caused by
+`C-s' and `C-q' is that they are gratuitous. There are other
+techniques (albeit less common in practice) for flow control that
+preserve transparency of the character stream. Note also that their use
+for flow control is not an official standard. Interestingly, on the
+model 33 teletype with a paper tape punch (which is very old), `C-s'
+and `C-q' were sent by the computer to turn the punch on and off!
+
+ As X servers and other window systems replace character-only
+terminals, this problem is gradually being cured. For the mean time,
+XEmacs provides a convenient way of enabling flow control if you want
+it: call the function `enable-flow-control'.
+
+ - Function: enable-flow-control
+ This function enables use of `C-s' and `C-q' for output flow
+ control, and provides the characters `C-\' and `C-^' as aliases
+ for them using `keyboard-translate-table' (*note Translating
+ Input::).
+
+ You can use the function `enable-flow-control-on' in your `.emacs'
+file to enable flow control automatically on certain terminal types.
+
+ - Function: enable-flow-control-on &rest termtypes
+ This function enables flow control, and the aliases `C-\' and
+ `C-^', if the terminal type is one of TERMTYPES. For example:
+
+ (enable-flow-control-on "vt200" "vt300" "vt101" "vt131")
+
+ Here is how `enable-flow-control' does its job:
+
+ 1. It sets CBREAK mode for terminal input, and tells the operating
+ system to handle flow control, with `(set-input-mode nil t)'.
+
+ 2. It sets up `keyboard-translate-table' to translate `C-\' and `C-^'
+ into `C-s' and `C-q'. Except at its very lowest level, XEmacs
+ never knows that the characters typed were anything but `C-s' and
+ `C-q', so you can in effect type them as `C-\' and `C-^' even when
+ they are input for other commands. *Note Translating Input::.
+
+ If the terminal is the source of the flow control characters, then
+once you enable kernel flow control handling, you probably can make do
+with less padding than normal for that terminal. You can reduce the
+amount of padding by customizing the Termcap entry. You can also
+reduce it by setting `baud-rate' to a smaller value so that XEmacs uses
+a smaller speed when calculating the padding needed. *Note Terminal
+Output::.
\1f
-File: lispref.info, Node: MULE, Next: Tips, Prev: Internationalization, Up: Top
-
-MULE
-****
-
- "MULE" is the name originally given to the version of GNU Emacs
-extended for multi-lingual (and in particular Asian-language) support.
-"MULE" is short for "MUlti-Lingual Emacs". It was originally called
-Nemacs ("Nihon Emacs" where "Nihon" is the Japanese word for "Japan"),
-when it only provided support for Japanese. XEmacs refers to its
-multi-lingual support as "MULE support" since it is based on "MULE".
-
-* Menu:
-
-* Internationalization Terminology::
- Definition of various internationalization terms.
-* Charsets:: Sets of related characters.
-* MULE Characters:: Working with characters in XEmacs/MULE.
-* Composite Characters:: Making new characters by overstriking other ones.
-* ISO 2022:: An international standard for charsets and encodings.
-* Coding Systems:: Ways of representing a string of chars using integers.
-* CCL:: A special language for writing fast converters.
-* Category Tables:: Subdividing charsets into groups.
+File: lispref.info, Node: Batch Mode, Prev: Flow Control, Up: System Interface
+
+Batch Mode
+==========
+
+ The command line option `-batch' causes XEmacs to run
+noninteractively. In this mode, XEmacs does not read commands from the
+terminal, it does not alter the terminal modes, and it does not expect
+to be outputting to an erasable screen. The idea is that you specify
+Lisp programs to run; when they are finished, XEmacs should exit. The
+way to specify the programs to run is with `-l FILE', which loads the
+library named FILE, and `-f FUNCTION', which calls FUNCTION with no
+arguments.
+
+ Any Lisp program output that would normally go to the echo area,
+either using `message' or using `prin1', etc., with `t' as the stream,
+goes instead to XEmacs's standard error descriptor when in batch mode.
+Thus, XEmacs behaves much like a noninteractive application program.
+(The echo area output that XEmacs itself normally generates, such as
+command echoing, is suppressed entirely.)
+
+ - Function: noninteractive
+ This function returns non-`nil' when XEmacs is running in batch
+ mode.
+
+ - Variable: noninteractive
+ This variable is non-`nil' when XEmacs is running in batch mode.
+ Setting this variable to `nil', however, will not change whether
+ XEmacs is running in batch mode, and will not change the return
+ value of the `noninteractive' function.
\1f
-File: lispref.info, Node: Internationalization Terminology, Next: Charsets, Up: MULE
-
-Internationalization Terminology
-================================
-
- In internationalization terminology, a string of text is divided up
-into "characters", which are the printable units that make up the text.
-A single character is (for example) a capital `A', the number `2', a
-Katakana character, a Kanji ideograph (an "ideograph" is a "picture"
-character, such as is used in Japanese Kanji, Chinese Hanzi, and Korean
-Hangul; typically there are thousands of such ideographs in each
-language), etc. The basic property of a character is its shape. Note
-that the same character may be drawn by two different people (or in two
-different fonts) in slightly different ways, although the basic shape
-will be the same.
-
- In some cases, the differences will be significant enough that it is
-actually possible to identify two or more distinct shapes that both
-represent the same character. For example, the lowercase letters `a'
-and `g' each have two distinct possible shapes - the `a' can optionally
-have a curved tail projecting off the top, and the `g' can be formed
-either of two loops, or of one loop and a tail hanging off the bottom.
-Such distinct possible shapes of a character are called "glyphs". The
-important characteristic of two glyphs making up the same character is
-that the choice between one or the other is purely stylistic and has no
-linguistic effect on a word (this is the reason why a capital `A' and
-lowercase `a' are different characters rather than different glyphs -
-e.g. `Aspen' is a city while `aspen' is a kind of tree).
-
- Note that "character" and "glyph" are used differently here than
-elsewhere in XEmacs.
-
- A "character set" is simply a set of related characters. ASCII, for
-example, is a set of 94 characters (or 128, if you count non-printing
-characters). Other character sets are ISO8859-1 (ASCII plus various
-accented characters and other international symbols), JISX0201 (ASCII,
-more or less, plus half-width Katakana), JISX0208 (Japanese Kanji),
-JISX0212 (a second set of less-used Japanese Kanji), GB2312 (Mainland
-Chinese Hanzi), etc.
-
- Every character set has one or more "orderings", which can be viewed
-as a way of assigning a number (or set of numbers) to each character in
-the set. For most character sets, there is a standard ordering, and in
-fact all of the character sets mentioned above define a particular
-ordering. ASCII, for example, places letters in their "natural" order,
-puts uppercase letters before lowercase letters, numbers before
-letters, etc. Note that for many of the Asian character sets, there is
-no natural ordering of the characters. The actual orderings are based
-on one or more salient characteristic, of which there are many to
-choose from - e.g. number of strokes, common radicals, phonetic
-ordering, etc.
-
- The set of numbers assigned to any particular character are called
-the character's "position codes". The number of position codes
-required to index a particular character in a character set is called
-the "dimension" of the character set. ASCII, being a relatively small
-character set, is of dimension one, and each character in the set is
-indexed using a single position code, in the range 0 through 127 (if
-non-printing characters are included) or 33 through 126 (if only the
-printing characters are considered). JISX0208, i.e. Japanese Kanji,
-has thousands of characters, and is of dimension two - every character
-is indexed by two position codes, each in the range 33 through 126.
-(Note that the choice of the range here is somewhat arbitrary.
-Although a character set such as JISX0208 defines an _ordering_ of all
-its characters, it does not define the actual mapping between numbers
-and characters. You could just as easily index the characters in
-JISX0208 using numbers in the range 0 through 93, 1 through 94, 2
-through 95, etc. The reason for the actual range chosen is so that the
-position codes match up with the actual values used in the common
-encodings.)
-
- An "encoding" is a way of numerically representing characters from
-one or more character sets into a stream of like-sized numerical values
-called "words"; typically these are 8-bit, 16-bit, or 32-bit
-quantities. If an encoding encompasses only one character set, then the
-position codes for the characters in that character set could be used
-directly. (This is the case with ASCII, and as a result, most people do
-not understand the difference between a character set and an encoding.)
-This is not possible, however, if more than one character set is to be
-used in the encoding. For example, printed Japanese text typically
-requires characters from multiple character sets - ASCII, JISX0208, and
-JISX0212, to be specific. Each of these is indexed using one or more
-position codes in the range 33 through 126, so the position codes could
-not be used directly or there would be no way to tell which character
-was meant. Different Japanese encodings handle this differently - JIS
-uses special escape characters to denote different character sets; EUC
-sets the high bit of the position codes for JISX0208 and JISX0212, and
-puts a special extra byte before each JISX0212 character; etc. (JIS,
-EUC, and most of the other encodings you will encounter are 7-bit or
-8-bit encodings. There is one common 16-bit encoding, which is Unicode;
-this strives to represent all the world's characters in a single large
-character set. 32-bit encodings are generally used internally in
-programs to simplify the code that manipulates them; however, they are
-not much used externally because they are not very space-efficient.)
-
- Encodings are classified as either "modal" or "non-modal". In a
-"modal encoding", there are multiple states that the encoding can be in,
-and the interpretation of the values in the stream depends on the
-current global state of the encoding. Special values in the encoding,
-called "escape sequences", are used to change the global state. JIS,
-for example, is a modal encoding. The bytes `ESC $ B' indicate that,
-from then on, bytes are to be interpreted as position codes for
-JISX0208, rather than as ASCII. This effect is cancelled using the
-bytes `ESC ( B', which mean "switch from whatever the current state is
-to ASCII". To switch to JISX0212, the escape sequence `ESC $ ( D'.
-(Note that here, as is common, the escape sequences do in fact begin
-with `ESC'. This is not necessarily the case, however.)
-
- A "non-modal encoding" has no global state that extends past the
-character currently being interpreted. EUC, for example, is a
-non-modal encoding. Characters in JISX0208 are encoded by setting the
-high bit of the position codes, and characters in JISX0212 are encoded
-by doing the same but also prefixing the character with the byte 0x8F.
-
- The advantage of a modal encoding is that it is generally more
-space-efficient, and is easily extendable because there are essentially
-an arbitrary number of escape sequences that can be created. The
-disadvantage, however, is that it is much more difficult to work with
-if it is not being processed in a sequential manner. In the non-modal
-EUC encoding, for example, the byte 0x41 always refers to the letter
-`A'; whereas in JIS, it could either be the letter `A', or one of the
-two position codes in a JISX0208 character, or one of the two position
-codes in a JISX0212 character. Determining exactly which one is meant
-could be difficult and time-consuming if the previous bytes in the
-string have not already been processed.
-
- Non-modal encodings are further divided into "fixed-width" and
-"variable-width" formats. A fixed-width encoding always uses the same
-number of words per character, whereas a variable-width encoding does
-not. EUC is a good example of a variable-width encoding: one to three
-bytes are used per character, depending on the character set. 16-bit
-and 32-bit encodings are nearly always fixed-width, and this is in fact
-one of the main reasons for using an encoding with a larger word size.
-The advantages of fixed-width encodings should be obvious. The
-advantages of variable-width encodings are that they are generally more
-space-efficient and allow for compatibility with existing 8-bit
-encodings such as ASCII.
-
- Note that the bytes in an 8-bit encoding are often referred to as
-"octets" rather than simply as bytes. This terminology dates back to
-the days before 8-bit bytes were universal, when some computers had
-9-bit bytes, others had 10-bit bytes, etc.
+File: lispref.info, Node: X-Windows, Next: ToolTalk Support, Prev: System Interface, Up: Top
-\1f
-File: lispref.info, Node: Charsets, Next: MULE Characters, Prev: Internationalization Terminology, Up: MULE
+Functions Specific to the X Window System
+*****************************************
-Charsets
-========
-
- A "charset" in MULE is an object that encapsulates a particular
-character set as well as an ordering of those characters. Charsets are
-permanent objects and are named using symbols, like faces.
-
- - Function: charsetp object
- This function returns non-`nil' if OBJECT is a charset.
+ XEmacs provides the concept of "devices", which generalizes
+connections to an X server, a TTY device, etc. Most information about
+an X server that XEmacs is connected to can be determined through
+general console and device functions. *Note Consoles and Devices::.
+However, there are some features of the X Window System that do not
+generalize well, and they are covered specially here.
* Menu:
-* Charset Properties:: Properties of a charset.
-* Basic Charset Functions:: Functions for working with charsets.
-* Charset Property Functions:: Functions for accessing charset properties.
-* Predefined Charsets:: Predefined charset objects.
+* X Selections:: Transferring text to and from other X clients.
+* X Server:: Information about the X server connected to
+ a particular device.
+* X Miscellaneous:: Other X-specific functions and variables.
\1f
-File: lispref.info, Node: Charset Properties, Next: Basic Charset Functions, Up: Charsets
-
-Charset Properties
-------------------
-
- Charsets have the following properties:
-
-`name'
- A symbol naming the charset. Every charset must have a different
- name; this allows a charset to be referred to using its name
- rather than the actual charset object.
-
-`doc-string'
- A documentation string describing the charset.
-
-`registry'
- A regular expression matching the font registry field for this
- character set. For example, both the `ascii' and `latin-iso8859-1'
- charsets use the registry `"ISO8859-1"'. This field is used to
- choose an appropriate font when the user gives a general font
- specification such as `-*-courier-medium-r-*-140-*', i.e. a
- 14-point upright medium-weight Courier font.
-
-`dimension'
- Number of position codes used to index a character in the
- character set. XEmacs/MULE can only handle character sets of
- dimension 1 or 2. This property defaults to 1.
-
-`chars'
- Number of characters in each dimension. In XEmacs/MULE, the only
- allowed values are 94 or 96. (There are a couple of pre-defined
- character sets, such as ASCII, that do not follow this, but you
- cannot define new ones like this.) Defaults to 94. Note that if
- the dimension is 2, the character set thus described is 94x94 or
- 96x96.
-
-`columns'
- Number of columns used to display a character in this charset.
- Only used in TTY mode. (Under X, the actual width of a character
- can be derived from the font used to display the characters.) If
- unspecified, defaults to the dimension. (This is almost always the
- correct value, because character sets with dimension 2 are usually
- ideograph character sets, which need two columns to display the
- intricate ideographs.)
-
-`direction'
- A symbol, either `l2r' (left-to-right) or `r2l' (right-to-left).
- Defaults to `l2r'. This specifies the direction that the text
- should be displayed in, and will be left-to-right for most
- charsets but right-to-left for Hebrew and Arabic. (Right-to-left
- display is not currently implemented.)
-
-`final'
- Final byte of the standard ISO 2022 escape sequence designating
- this charset. Must be supplied. Each combination of (DIMENSION,
- CHARS) defines a separate namespace for final bytes, and each
- charset within a particular namespace must have a different final
- byte. Note that ISO 2022 restricts the final byte to the range
- 0x30 - 0x7E if dimension == 1, and 0x30 - 0x5F if dimension == 2.
- Note also that final bytes in the range 0x30 - 0x3F are reserved
- for user-defined (not official) character sets. For more
- information on ISO 2022, see *Note Coding Systems::.
-
-`graphic'
- 0 (use left half of font on output) or 1 (use right half of font on
- output). Defaults to 0. This specifies how to convert the
- position codes that index a character in a character set into an
- index into the font used to display the character set. With
- `graphic' set to 0, position codes 33 through 126 map to font
- indices 33 through 126; with it set to 1, position codes 33
- through 126 map to font indices 161 through 254 (i.e. the same
- number but with the high bit set). For example, for a font whose
- registry is ISO8859-1, the left half of the font (octets 0x20 -
- 0x7F) is the `ascii' charset, while the right half (octets 0xA0 -
- 0xFF) is the `latin-iso8859-1' charset.
-
-`ccl-program'
- A compiled CCL program used to convert a character in this charset
- into an index into the font. This is in addition to the `graphic'
- property. If a CCL program is defined, the position codes of a
- character will first be processed according to `graphic' and then
- passed through the CCL program, with the resulting values used to
- index the font.
-
- This is used, for example, in the Big5 character set (used in
- Taiwan). This character set is not ISO-2022-compliant, and its
- size (94x157) does not fit within the maximum 96x96 size of
- ISO-2022-compliant character sets. As a result, XEmacs/MULE
- splits it (in a rather complex fashion, so as to group the most
- commonly used characters together) into two charset objects
- (`big5-1' and `big5-2'), each of size 94x94, and each charset
- object uses a CCL program to convert the modified position codes
- back into standard Big5 indices to retrieve a character from a
- Big5 font.
-
- Most of the above properties can only be changed when the charset is
-created. *Note Charset Property Functions::.
+File: lispref.info, Node: X Selections, Next: X Server, Up: X-Windows
-\1f
-File: lispref.info, Node: Basic Charset Functions, Next: Charset Property Functions, Prev: Charset Properties, Up: Charsets
-
-Basic Charset Functions
------------------------
+X Selections
+============
- - Function: find-charset charset-or-name
- This function retrieves the charset of the given name. If
- CHARSET-OR-NAME is a charset object, it is simply returned.
- Otherwise, CHARSET-OR-NAME should be a symbol. If there is no
- such charset, `nil' is returned. Otherwise the associated charset
- object is returned.
-
- - Function: get-charset name
- This function retrieves the charset of the given name. Same as
- `find-charset' except an error is signalled if there is no such
- charset instead of returning `nil'.
-
- - Function: charset-list
- This function returns a list of the names of all defined charsets.
-
- - Function: make-charset name doc-string props
- This function defines a new character set. This function is for
- use with Mule support. NAME is a symbol, the name by which the
- character set is normally referred. DOC-STRING is a string
- describing the character set. PROPS is a property list,
- describing the specific nature of the character set. The
- recognized properties are `registry', `dimension', `columns',
- `chars', `final', `graphic', `direction', and `ccl-program', as
- previously described.
-
- - Function: make-reverse-direction-charset charset new-name
- This function makes a charset equivalent to CHARSET but which goes
- in the opposite direction. NEW-NAME is the name of the new
- charset. The new charset is returned.
-
- - Function: charset-from-attributes dimension chars final &optional
- direction
- This function returns a charset with the given DIMENSION, CHARS,
- FINAL, and DIRECTION. If DIRECTION is omitted, both directions
- will be checked (left-to-right will be returned if character sets
- exist for both directions).
-
- - Function: charset-reverse-direction-charset charset
- This function returns the charset (if any) with the same dimension,
- number of characters, and final byte as CHARSET, but which is
- displayed in the opposite direction.
+ The X server records a set of "selections" which permit transfer of
+data between application programs. The various selections are
+distinguished by "selection types", represented in XEmacs by symbols.
+X clients including XEmacs can read or set the selection for any given
+type.
+
+ - Function: x-own-selection data &optional type
+ This function sets a "selection" in the X server. It takes two
+ arguments: a value, DATA, and the selection type TYPE to assign it
+ to. DATA may be a string, a cons of two markers, or an extent.
+ In the latter cases, the selection is considered to be the text
+ between the markers, or between the extent's endpoints.
+
+ Each possible TYPE has its own selection value, which changes
+ independently. The usual values of TYPE are `PRIMARY' and
+ `SECONDARY'; these are symbols with upper-case names, in accord
+ with X Windows conventions. The default is `PRIMARY'.
+
+ (In FSF Emacs, this function is called `x-set-selection' and takes
+ different arguments.)
+
+ - Function: x-get-selection
+ This function accesses selections set up by XEmacs or by other X
+ clients. It returns the value of the current primary selection.
+
+ - Function: x-disown-selection &optional secondary-p
+ Assuming we own the selection, this function disowns it. If
+ SECONDARY-P is non-`nil', the secondary selection instead of the
+ primary selection is discarded.
+
+ The X server also has a set of numbered "cut buffers" which can
+store text or other data being moved between applications. Cut buffers
+are considered obsolete, but XEmacs supports them for the sake of X
+clients that still use them.
+
+ - Function: x-get-cutbuffer &optional n
+ This function returns the contents of cut buffer number N. (This
+ function is called `x-get-cut-buffer' in FSF Emacs.)
+
+ - Function: x-store-cutbuffer string
+ This function stores STRING into the first cut buffer (cut buffer
+ 0), moving the other values down through the series of cut buffers,
+ kill-ring-style. (This function is called `x-set-cut-buffer' in FSF
+ Emacs.)
\1f
-File: lispref.info, Node: Charset Property Functions, Next: Predefined Charsets, Prev: Basic Charset Functions, Up: Charsets
-
-Charset Property Functions
---------------------------
-
- All of these functions accept either a charset name or charset
-object.
-
- - Function: charset-property charset prop
- This function returns property PROP of CHARSET. *Note Charset
- Properties::.
-
- Convenience functions are also provided for retrieving individual
-properties of a charset.
+File: lispref.info, Node: X Server, Next: X Miscellaneous, Prev: X Selections, Up: X-Windows
- - Function: charset-name charset
- This function returns the name of CHARSET. This will be a symbol.
-
- - Function: charset-doc-string charset
- This function returns the doc string of CHARSET.
-
- - Function: charset-registry charset
- This function returns the registry of CHARSET.
-
- - Function: charset-dimension charset
- This function returns the dimension of CHARSET.
-
- - Function: charset-chars charset
- This function returns the number of characters per dimension of
- CHARSET.
-
- - Function: charset-columns charset
- This function returns the number of display columns per character
- (in TTY mode) of CHARSET.
-
- - Function: charset-direction charset
- This function returns the display direction of CHARSET - either
- `l2r' or `r2l'.
-
- - Function: charset-final charset
- This function returns the final byte of the ISO 2022 escape
- sequence designating CHARSET.
-
- - Function: charset-graphic charset
- This function returns either 0 or 1, depending on whether the
- position codes of characters in CHARSET map to the left or right
- half of their font, respectively.
+X Server
+========
- - Function: charset-ccl-program charset
- This function returns the CCL program, if any, for converting
- position codes of characters in CHARSET into font indices.
+ This section describes how to access and change the overall status of
+the X server XEmacs is using.
- The only property of a charset that can currently be set after the
-charset has been created is the CCL program.
+* Menu:
- - Function: set-charset-ccl-program charset ccl-program
- This function sets the `ccl-program' property of CHARSET to
- CCL-PROGRAM.
+* Resources:: Getting resource values from the server.
+* Server Data:: Getting info about the X server.
+* Grabs:: Restricting access to the server by other apps.
\1f
-File: lispref.info, Node: Predefined Charsets, Prev: Charset Property Functions, Up: Charsets
-
-Predefined Charsets
--------------------
-
- The following charsets are predefined in the C code.
-
- Name Type Fi Gr Dir Registry
- --------------------------------------------------------------
- ascii 94 B 0 l2r ISO8859-1
- control-1 94 0 l2r ---
- latin-iso8859-1 94 A 1 l2r ISO8859-1
- latin-iso8859-2 96 B 1 l2r ISO8859-2
- latin-iso8859-3 96 C 1 l2r ISO8859-3
- latin-iso8859-4 96 D 1 l2r ISO8859-4
- cyrillic-iso8859-5 96 L 1 l2r ISO8859-5
- arabic-iso8859-6 96 G 1 r2l ISO8859-6
- greek-iso8859-7 96 F 1 l2r ISO8859-7
- hebrew-iso8859-8 96 H 1 r2l ISO8859-8
- latin-iso8859-9 96 M 1 l2r ISO8859-9
- thai-tis620 96 T 1 l2r TIS620
- katakana-jisx0201 94 I 1 l2r JISX0201.1976
- latin-jisx0201 94 J 0 l2r JISX0201.1976
- japanese-jisx0208-1978 94x94 @ 0 l2r JISX0208.1978
- japanese-jisx0208 94x94 B 0 l2r JISX0208.19(83|90)
- japanese-jisx0212 94x94 D 0 l2r JISX0212
- chinese-gb2312 94x94 A 0 l2r GB2312
- chinese-cns11643-1 94x94 G 0 l2r CNS11643.1
- chinese-cns11643-2 94x94 H 0 l2r CNS11643.2
- chinese-big5-1 94x94 0 0 l2r Big5
- chinese-big5-2 94x94 1 0 l2r Big5
- korean-ksc5601 94x94 C 0 l2r KSC5601
- composite 96x96 0 l2r ---
-
- The following charsets are predefined in the Lisp code.
-
- Name Type Fi Gr Dir Registry
- --------------------------------------------------------------
- arabic-digit 94 2 0 l2r MuleArabic-0
- arabic-1-column 94 3 0 r2l MuleArabic-1
- arabic-2-column 94 4 0 r2l MuleArabic-2
- sisheng 94 0 0 l2r sisheng_cwnn\|OMRON_UDC_ZH
- chinese-cns11643-3 94x94 I 0 l2r CNS11643.1
- chinese-cns11643-4 94x94 J 0 l2r CNS11643.1
- chinese-cns11643-5 94x94 K 0 l2r CNS11643.1
- chinese-cns11643-6 94x94 L 0 l2r CNS11643.1
- chinese-cns11643-7 94x94 M 0 l2r CNS11643.1
- ethiopic 94x94 2 0 l2r Ethio
- ascii-r2l 94 B 0 r2l ISO8859-1
- ipa 96 0 1 l2r MuleIPA
- vietnamese-lower 96 1 1 l2r VISCII1.1
- vietnamese-upper 96 2 1 l2r VISCII1.1
-
- For all of the above charsets, the dimension and number of columns
-are the same.
-
- Note that ASCII, Control-1, and Composite are handled specially.
-This is why some of the fields are blank; and some of the filled-in
-fields (e.g. the type) are not really accurate.
+File: lispref.info, Node: Resources, Next: Server Data, Up: X Server
-\1f
-File: lispref.info, Node: MULE Characters, Next: Composite Characters, Prev: Charsets, Up: MULE
+Resources
+---------
-MULE Characters
-===============
+ - Function: default-x-device
+ This function return the default X device for resourcing. This is
+ the first-created X device that still exists.
- - Function: make-char charset arg1 &optional arg2
- This function makes a multi-byte character from CHARSET and octets
- ARG1 and ARG2.
+ - Function: x-get-resource name class type &optional locale device
+ noerror
+ This function retrieves a resource value from the X resource
+ manager.
- - Function: char-charset ch
- This function returns the character set of char CH.
+ * The first arg is the name of the resource to retrieve, such as
+ `"font"'.
- - Function: char-octet ch &optional n
- This function returns the octet (i.e. position code) numbered N
- (should be 0 or 1) of char CH. N defaults to 0 if omitted.
+ * The second arg is the class of the resource to retrieve, like
+ `"Font"'.
- - Function: find-charset-region start end &optional buffer
- This function returns a list of the charsets in the region between
- START and END. BUFFER defaults to the current buffer if omitted.
+ * The third arg should be one of the symbols `string',
+ `integer', `natnum', or `boolean', specifying the type of
+ object that the database is searched for.
- - Function: find-charset-string string
- This function returns a list of the charsets in STRING.
+ * The fourth arg is the locale to search for the resources on,
+ and can currently be a a buffer, a frame, a device, or the
+ symbol `global'. If omitted, it defaults to `global'.
-\1f
-File: lispref.info, Node: Composite Characters, Next: ISO 2022, Prev: MULE Characters, Up: MULE
+ * The fifth arg is the device to search for the resources on.
+ (The resource database for a particular device is constructed
+ by combining non-device- specific resources such any
+ command-line resources specified and any app-defaults files
+ found [or the fallback resources supplied by XEmacs, if no
+ app-defaults file is found] with device-specific resources
+ such as those supplied using `xrdb'.) If omitted, it defaults
+ to the device of LOCALE, if a device can be derived (i.e. if
+ LOCALE is a frame or device), and otherwise defaults to the
+ value of `default-x-device'.
-Composite Characters
-====================
+ * The sixth arg NOERROR, if non-`nil', means do not signal an
+ error if a bogus resource specification was retrieved (e.g.
+ if a non-integer was given when an integer was requested).
+ In this case, a warning is issued instead.
- Composite characters are not yet completely implemented.
+ The resource names passed to this function are looked up relative
+ to the locale.
- - Function: make-composite-char string
- This function converts a string into a single composite character.
- The character is the result of overstriking all the characters in
- the string.
+ If you want to search for a subresource, you just need to specify
+ the resource levels in NAME and CLASS. For example, NAME could be
+ `"modeline.attributeFont"', and CLASS `"Face.AttributeFont"'.
- - Function: composite-char-string ch
- This function returns a string of the characters comprising a
- composite character.
+ Specifically,
- - Function: compose-region start end &optional buffer
- This function composes the characters in the region from START to
- END in BUFFER into one composite character. The composite
- character replaces the composed characters. BUFFER defaults to
- the current buffer if omitted.
+ 1. If LOCALE is a buffer, a call
- - Function: decompose-region start end &optional buffer
- This function decomposes any composite characters in the region
- from START to END in BUFFER. This converts each composite
- character into one or more characters, the individual characters
- out of which the composite character was formed. Non-composite
- characters are left as-is. BUFFER defaults to the current buffer
- if omitted.
+ `(x-get-resource "foreground" "Foreground" 'string SOME-BUFFER)'
-\1f
-File: lispref.info, Node: ISO 2022, Next: Coding Systems, Prev: Composite Characters, Up: MULE
+ is an interface to a C call something like
-ISO 2022
-========
+ `XrmGetResource (db, "xemacs.buffer.BUFFER-NAME.foreground",
+ "Emacs.EmacsLocaleType.EmacsBuffer.Foreground",
+ "String");'
- This section briefly describes the ISO 2022 encoding standard. For
-more thorough understanding, please refer to the original document of
-ISO 2022.
+ 2. If LOCALE is a frame, a call
- Character sets ("charsets") are classified into the following four
-categories, according to the number of characters of charset:
-94-charset, 96-charset, 94x94-charset, and 96x96-charset.
+ `(x-get-resource "foreground" "Foreground" 'string SOME-FRAME)'
-94-charset
- ASCII(B), left(J) and right(I) half of JISX0201, ...
+ is an interface to a C call something like
-96-charset
- Latin-1(A), Latin-2(B), Latin-3(C), ...
+ `XrmGetResource (db, "xemacs.frame.FRAME-NAME.foreground",
+ "Emacs.EmacsLocaleType.EmacsFrame.Foreground",
+ "String");'
-94x94-charset
- GB2312(A), JISX0208(B), KSC5601(C), ...
+ 3. If LOCALE is a device, a call
-96x96-charset
- none for the moment
+ `(x-get-resource "foreground" "Foreground" 'string SOME-DEVICE)'
- The character in parentheses after the name of each charset is the
-"final character" F, which can be regarded as the identifier of the
-charset. ECMA allocates F to each charset. F is in the range of
-0x30..0x7F, but 0x30..0x3F are only for private use.
+ is an interface to a C call something like
- Note: "ECMA" = European Computer Manufacturers Association
+ `XrmGetResource (db, "xemacs.device.DEVICE-NAME.foreground",
+ "Emacs.EmacsLocaleType.EmacsDevice.Foreground",
+ "String");'
- There are four "registers of charsets", called G0 thru G3. You can
-designate (or assign) any charset to one of these registers.
+ 4. If LOCALE is the symbol `global', a call
- The code space contained within one octet (of size 256) is divided
-into 4 areas: C0, GL, C1, and GR. GL and GR are the areas into which a
-register of charset can be invoked into.
+ `(x-get-resource "foreground" "Foreground" 'string 'global)'
- C0: 0x00 - 0x1F
- GL: 0x20 - 0x7F
- C1: 0x80 - 0x9F
- GR: 0xA0 - 0xFF
+ is an interface to a C call something like
- Usually, in the initial state, G0 is invoked into GL, and G1 is
-invoked into GR.
+ `XrmGetResource (db, "xemacs.foreground",
+ "Emacs.Foreground",
+ "String");'
- ISO 2022 distinguishes 7-bit environments and 8-bit environments. In
-7-bit environments, only C0 and GL are used.
+ Note that for `global', no prefix is added other than that of the
+ application itself; thus, you can use this locale to retrieve
+ arbitrary application resources, if you really want to.
- Charset designation is done by escape sequences of the form:
+ The returned value of this function is `nil' if the queried
+ resource is not found. If TYPE is `string', a string is returned,
+ and if it is `integer', an integer is returned. If TYPE is
+ `boolean', then the returned value is the list `(t)' for true,
+ `(nil)' for false, and is `nil' to mean "unspecified".
- ESC [I] I F
+ - Function: x-put-resource resource-line &optional device
+ This function adds a resource to the resource database for DEVICE.
+ RESOURCE-LINE specifies the resource to add and should be a
+ standard resource specification.
- where I is an intermediate character in the range 0x20 - 0x2F, and F
-is the final character identifying this charset.
+ - Variable: x-emacs-application-class
+ This variable holds The X application class of the XEmacs process.
+ This controls, among other things, the name of the "app-defaults"
+ file that XEmacs will use. For changes to this variable to take
+ effect, they must be made before the connection to the X server is
+ initialized, that is, this variable may only be changed before
+ XEmacs is dumped, or by setting it in the file
+ `lisp/term/x-win.el'.
- The meaning of intermediate characters are:
+ By default, this variable is nil at startup. When the connection
+ to the X server is first initialized, the X resource database will
+ be consulted and the value will be set according to whether any
+ resources are found for the application class "XEmacs".
- $ [0x24]: indicate charset of dimension 2 (94x94 or 96x96).
- ( [0x28]: designate to G0 a 94-charset whose final byte is F.
- ) [0x29]: designate to G1 a 94-charset whose final byte is F.
- * [0x2A]: designate to G2 a 94-charset whose final byte is F.
- + [0x2B]: designate to G3 a 94-charset whose final byte is F.
- - [0x2D]: designate to G1 a 96-charset whose final byte is F.
- . [0x2E]: designate to G2 a 96-charset whose final byte is F.
- / [0x2F]: designate to G3 a 96-charset whose final byte is F.
+\1f
+File: lispref.info, Node: Server Data, Next: Grabs, Prev: Resources, Up: X Server
- The following rule is not allowed in ISO 2022 but can be used in
-Mule.
+Data about the X Server
+-----------------------
- , [0x2C]: designate to G0 a 96-charset whose final byte is F.
+ This section describes functions and a variable that you can use to
+get information about the capabilities and origin of the X server
+corresponding to a particular device. The device argument is generally
+optional and defaults to the selected device.
- Here are examples of designations:
+ - Function: x-server-version &optional device
+ This function returns the list of version numbers of the X server
+ DEVICE is on. The returned value is a list of three integers: the
+ major and minor version numbers of the X protocol in use, and the
+ vendor-specific release number.
- ESC ( B : designate to G0 ASCII
- ESC - A : designate to G1 Latin-1
- ESC $ ( A or ESC $ A : designate to G0 GB2312
- ESC $ ( B or ESC $ B : designate to G0 JISX0208
- ESC $ ) C : designate to G1 KSC5601
+ - Function: x-server-vendor &optional device
+ This function returns the vendor supporting the X server DEVICE is
+ on.
- To use a charset designated to G2 or G3, and to use a charset
-designated to G1 in a 7-bit environment, you must explicitly invoke G1,
-G2, or G3 into GL. There are two types of invocation, Locking Shift
-(forever) and Single Shift (one character only).
+ - Function: x-display-visual-class &optional device
+ This function returns the visual class of the display DEVICE is
+ on. The value is one of the symbols `static-gray', `gray-scale',
+ `static-color', `pseudo-color', `true-color', and `direct-color'.
+ (Note that this is different from previous versions of XEmacs,
+ which returned `StaticGray', `GrayScale', etc.)
- Locking Shift is done as follows:
+\1f
+File: lispref.info, Node: Grabs, Prev: Server Data, Up: X Server
+
+Restricting Access to the Server by Other Apps
+----------------------------------------------
+
+ - Function: x-grab-keyboard &optional device
+ This function grabs the keyboard on the given device (defaulting
+ to the selected one). So long as the keyboard is grabbed, all
+ keyboard events will be delivered to XEmacs--it is not possible
+ for other X clients to eavesdrop on them. Ungrab the keyboard
+ with `x-ungrab-keyboard' (use an `unwind-protect'). Returns `t'
+ if the grab was successful; `nil' otherwise.
+
+ - Function: x-ungrab-keyboard &optional device
+ This function releases a keyboard grab made with `x-grab-keyboard'.
+
+ - Function: x-grab-pointer &optional device cursor ignore-keyboard
+ This function grabs the pointer and restricts it to its current
+ window. If optional DEVICE argument is `nil', the selected device
+ will be used. If optional CURSOR argument is non-`nil', change
+ the pointer shape to that until `x-ungrab-pointer' is called (it
+ should be an object returned by the `make-cursor' function). If
+ the second optional argument IGNORE-KEYBOARD is non-`nil', ignore
+ all keyboard events during the grab. Returns `t' if the grab is
+ successful, `nil' otherwise.
+
+ - Function: x-ungrab-pointer &optional device
+ This function releases a pointer grab made with `x-grab-pointer'.
+ If optional first arg DEVICE is `nil' the selected device is used.
+ If it is `t' the pointer will be released on all X devices.
- LS0 or SI (0x0F): invoke G0 into GL
- LS1 or SO (0x0E): invoke G1 into GL
- LS2: invoke G2 into GL
- LS3: invoke G3 into GL
- LS1R: invoke G1 into GR
- LS2R: invoke G2 into GR
- LS3R: invoke G3 into GR
+\1f
+File: lispref.info, Node: X Miscellaneous, Prev: X Server, Up: X-Windows
+
+Miscellaneous X Functions and Variables
+=======================================
+
+ - Variable: x-bitmap-file-path
+ This variable holds a list of the directories in which X bitmap
+ files may be found. If `nil', this is initialized from the
+ `"*bitmapFilePath"' resource. This is used by the
+ `make-image-instance' function (however, note that if the
+ environment variable `XBMLANGPATH' is set, it is consulted first).
+
+ - Variable: x-library-search-path
+ This variable holds the search path used by `read-color' to find
+ `rgb.txt'.
+
+ - Function: x-valid-keysym-name-p keysym
+ This function returns true if KEYSYM names a keysym that the X
+ library knows about. Valid keysyms are listed in the files
+ `/usr/include/X11/keysymdef.h' and in `/usr/lib/X11/XKeysymDB', or
+ whatever the equivalents are on your system.
+
+ - Function: x-window-id &optional frame
+ This function returns the ID of the X11 window. This gives us a
+ chance to manipulate the Emacs window from within a different
+ program. Since the ID is an unsigned long, we return it as a
+ string.
+
+ - Variable: x-allow-sendevents
+ If non-`nil', synthetic events are allowed. `nil' means they are
+ ignored. Beware: allowing XEmacs to process SendEvents opens a
+ big security hole.
+
+ - Function: x-debug-mode arg &optional device
+ With a true arg, make the connection to the X server synchronous.
+ With false, make it asynchronous. Synchronous connections are
+ much slower, but are useful for debugging. (If you get X errors,
+ make the connection synchronous, and use a debugger to set a
+ breakpoint on `x_error_handler'. Your backtrace of the C stack
+ will now be useful. In asynchronous mode, the stack above
+ `x_error_handler' isn't helpful because of buffering.) If DEVICE
+ is not specified, the selected device is assumed.
+
+ Calling this function is the same as calling the C function
+ `XSynchronize', or starting the program with the `-sync' command
+ line argument.
+
+ - Variable: x-debug-events
+ If non-zero, debug information about events that XEmacs sees is
+ displayed. Information is displayed on stderr. Currently defined
+ values are:
+
+ * 1 == non-verbose output
+
+ * 2 == verbose output
- Single Shift is done as follows:
+\1f
+File: lispref.info, Node: ToolTalk Support, Next: LDAP Support, Prev: X-Windows, Up: Top
- SS2 or ESC N: invoke G2 into GL
- SS3 or ESC O: invoke G3 into GL
+ToolTalk Support
+****************
- (#### Ben says: I think the above is slightly incorrect. It appears
-that SS2 invokes G2 into GR and SS3 invokes G3 into GR, whereas ESC N
-and ESC O behave as indicated. The above definitions will not parse
-EUC-encoded text correctly, and it looks like the code in mule-coding.c
-has similar problems.)
+* Menu:
- You may realize that there are a lot of ISO-2022-compliant ways of
-encoding multilingual text. Now, in the world, there exist many coding
-systems such as X11's Compound Text, Japanese JUNET code, and so-called
-EUC (Extended UNIX Code); all of these are variants of ISO 2022.
+* XEmacs ToolTalk API Summary::
+* Sending Messages::
+* Receiving Messages::
- In Mule, we characterize ISO 2022 by the following attributes:
+\1f
+File: lispref.info, Node: XEmacs ToolTalk API Summary, Next: Sending Messages, Up: ToolTalk Support
- 1. Initial designation to G0 thru G3.
+XEmacs ToolTalk API Summary
+===========================
- 2. Allow designation of short form for Japanese and Chinese.
+ The XEmacs Lisp interface to ToolTalk is similar, at least in spirit,
+to the standard C ToolTalk API. Only the message and pattern parts of
+the API are supported at present; more of the API could be added if
+needed. The Lisp interface departs from the C API in a few ways:
- 3. Should we designate ASCII to G0 before control characters?
+ * ToolTalk is initialized automatically at XEmacs startup-time.
+ Messages can only be sent other ToolTalk applications connected to
+ the same X11 server that XEmacs is running on.
- 4. Should we designate ASCII to G0 at the end of line?
+ * There are fewer entry points; polymorphic functions with keyword
+ arguments are used instead.
- 5. 7-bit environment or 8-bit environment.
+ * The callback interface is simpler and marginally less functional.
+ A single callback may be associated with a message or a pattern;
+ the callback is specified with a Lisp symbol (the symbol should
+ have a function binding).
- 6. Use Locking Shift or not.
+ * The session attribute for messages and patterns is always
+ initialized to the default session.
- 7. Use ASCII or JIS0201-1976-Roman.
+ * Anywhere a ToolTalk enum constant, e.g. `TT_SESSION', is valid, one
+ can substitute the corresponding symbol, e.g. `'TT_SESSION'. This
+ simplifies building lists that represent messages and patterns.
- 8. Use JISX0208-1983 or JISX0208-1976.
+\1f
+File: lispref.info, Node: Sending Messages, Next: Receiving Messages, Prev: XEmacs ToolTalk API Summary, Up: ToolTalk Support
- (The last two are only for Japanese.)
+Sending Messages
+================
- By specifying these attributes, you can create any variant of ISO
-2022.
+* Menu:
- Here are several examples:
+* Example of Sending Messages::
+* Elisp Interface for Sending Messages::
- junet -- Coding system used in JUNET.
- 1. G0 <- ASCII, G1..3 <- never used
- 2. Yes.
- 3. Yes.
- 4. Yes.
- 5. 7-bit environment
- 6. No.
- 7. Use ASCII
- 8. Use JISX0208-1983
-
- ctext -- Compound Text
- 1. G0 <- ASCII, G1 <- Latin-1, G2,3 <- never used
- 2. No.
- 3. No.
- 4. Yes.
- 5. 8-bit environment
- 6. No.
- 7. Use ASCII
- 8. Use JISX0208-1983
+\1f
+File: lispref.info, Node: Example of Sending Messages, Next: Elisp Interface for Sending Messages, Up: Sending Messages
+
+Example of Sending Messages
+---------------------------
+
+ Here's a simple example that sends a query to another application
+and then displays its reply. Both the query and the reply are stored
+in the first argument of the message.
+
+ (defun tooltalk-random-query-handler (msg)
+ (let ((state (get-tooltalk-message-attribute msg 'state)))
+ (cond
+ ((eq state 'TT_HANDLED)
+ (message (get-tooltalk-message-attribute msg arg_val 0)))
+ ((memq state '(TT_FAILED TT_REJECTED))
+ (message "Random query turns up nothing")))))
- euc-china -- Chinese EUC. Although many people call this
- as "GB encoding", the name may cause misunderstanding.
- 1. G0 <- ASCII, G1 <- GB2312, G2,3 <- never used
- 2. No.
- 3. Yes.
- 4. Yes.
- 5. 8-bit environment
- 6. No.
- 7. Use ASCII
- 8. Use JISX0208-1983
+ (defvar random-query-message
+ '( class TT_REQUEST
+ scope TT_SESSION
+ address TT_PROCEDURE
+ op "random-query"
+ args '((TT_INOUT "?" "string"))
+ callback tooltalk-random-query-handler))
- korean-mail -- Coding system used in Korean network.
- 1. G0 <- ASCII, G1 <- KSC5601, G2,3 <- never used
- 2. No.
- 3. Yes.
- 4. Yes.
- 5. 7-bit environment
- 6. Yes.
- 7. No.
- 8. No.
-
- Mule creates all these coding systems by default.
+ (let ((m (make-tooltalk-message random-query-message)))
+ (send-tooltalk-message m))
\1f
-File: lispref.info, Node: Coding Systems, Next: CCL, Prev: ISO 2022, Up: MULE
+File: lispref.info, Node: Elisp Interface for Sending Messages, Prev: Example of Sending Messages, Up: Sending Messages
+
+Elisp Interface for Sending Messages
+------------------------------------
+
+ - Function: make-tooltalk-message attributes
+ Create a ToolTalk message and initialize its attributes. The
+ value of ATTRIBUTES must be a list of alternating keyword/values,
+ where keywords are symbols that name valid message attributes.
+ For example:
+
+ (make-tooltalk-message
+ '(class TT_NOTICE
+ scope TT_SESSION
+ address TT_PROCEDURE
+ op "do-something"
+ args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
+
+ Values must always be strings, integers, or symbols that represent
+ ToolTalk constants. Attribute names are the same as those
+ supported by `set-tooltalk-message-attribute', plus `args'.
+
+ The value of `args' should be a list of message arguments where
+ each message argument has the following form:
+
+ `(mode [value [type]])' or just `value'
+
+ Where MODE is one of `TT_IN', `TT_OUT', or `TT_INOUT' and TYPE is
+ a string. If TYPE isn't specified then `int' is used if VALUE is
+ a number; otherwise `string' is used. If TYPE is `string' then
+ VALUE is converted to a string (if it isn't a string already) with
+ `prin1-to-string'. If only a value is specified then MODE
+ defaults to `TT_IN'. If MODE is `TT_OUT' then VALUE and TYPE
+ don't need to be specified. You can find out more about the
+ semantics and uses of ToolTalk message arguments in chapter 4 of
+ the `ToolTalk Programmer's Guide'.
+
+
+ - Function: send-tooltalk-message msg
+ Send the message on its way. Once the message has been sent it's
+ almost always a good idea to get rid of it with
+ `destroy-tooltalk-message'.
+
+
+ - Function: return-tooltalk-message msg &optional mode
+ Send a reply to this message. The second argument can be `reply',
+ `reject' or `fail'; the default is `reply'. Before sending a
+ reply, all message arguments whose mode is `TT_INOUT' or `TT_OUT'
+ should have been filled in--see `set-tooltalk-message-attribute'.
+
+
+ - Function: get-tooltalk-message-attribute msg attribute &optional argn
+ Returns the indicated ToolTalk message attribute. Attributes are
+ identified by symbols with the same name (underscores and all) as
+ the suffix of the ToolTalk `tt_message_<attribute>' function that
+ extracts the value. String attribute values are copied and
+ enumerated type values (except disposition) are converted to
+ symbols; e.g. `TT_HANDLER' is `'TT_HANDLER', `uid' and `gid' are
+ represented by fixnums (small integers), `opnum' is converted to a
+ string, and `disposition' is converted to a fixnum. We convert
+ `opnum' (a C int) to a string (e.g. `123' => `"123"') because
+ there's no guarantee that opnums will fit within the range of
+ XEmacs Lisp integers.
+
+ [TBD] Use the `plist' attribute instead of C API `user' attribute
+ for user-defined message data. To retrieve the value of a message
+ property, specify the indicator for ARGN. For example, to get the
+ value of a property called `rflag', use
+
+ (get-tooltalk-message-attribute msg 'plist 'rflag)
+
+ To get the value of a message argument use one of the `arg_val'
+ (strings), `arg_ival' (integers), or `arg_bval' (strings with
+ embedded nulls), attributes. For example, to get the integer
+ value of the third argument:
+
+ (get-tooltalk-message-attribute msg 'arg_ival 2)
+
+ As you can see, argument numbers are zero-based. The type of each
+ arguments can be retrieved with the `arg_type' attribute; however
+ ToolTalk doesn't define any semantics for the string value of
+ `arg_type'. Conventionally `string' is used for strings and `int'
+ for 32 bit integers. Note that XEmacs Lisp stores the lengths of
+ strings explicitly (unlike C) so treating the value returned by
+ `arg_bval' like a string is fine.
+
+
+ - Function: set-tooltalk-message-attribute value msg attribute
+ &optional argn
+ Initialize one ToolTalk message attribute.
+
+ Attribute names and values are the same as for
+ `get-tooltalk-message-attribute'. A property list is provided for
+ user data (instead of the `user' message attribute); see
+ `get-tooltalk-message-attribute'.
+
+ Callbacks are handled slightly differently than in the C ToolTalk
+ API. The value of CALLBACK should be the name of a function of one
+ argument. It will be called each time the state of the message
+ changes. This is usually used to notice when the message's state
+ has changed to `TT_HANDLED' (or `TT_FAILED'), so that reply
+ argument values can be used.
+
+ If one of the argument attributes is specified as `arg_val',
+ `arg_ival', or `arg_bval', then ARGN must be the number of an
+ already created argument. Arguments can be added to a message
+ with `add-tooltalk-message-arg'.
+
+
+ - Function: add-tooltalk-message-arg msg mode type &optional value
+ Append one new argument to the message. MODE must be one of
+ `TT_IN', `TT_INOUT', or `TT_OUT', TYPE must be a string, and VALUE
+ can be a string or an integer. ToolTalk doesn't define any
+ semantics for TYPE, so only the participants in the protocol
+ you're using need to agree what types mean (if anything).
+ Conventionally `string' is used for strings and `int' for 32 bit
+ integers. Arguments can initialized by providing a value or with
+ `set-tooltalk-message-attribute'; the latter is necessary if you
+ want to initialize the argument with a string that can contain
+ embedded nulls (use `arg_bval').
+
+
+ - Function: create-tooltalk-message
+ Create a new ToolTalk message. The message's session attribute is
+ initialized to the default session. Other attributes can be
+ initialized with `set-tooltalk-message-attribute'.
+ `make-tooltalk-message' is the preferred way to create and
+ initialize a message.
+
+
+ - Function: destroy-tooltalk-message msg
+ Apply `tt_message_destroy' to the message. It's not necessary to
+ destroy messages after they've been processed by a message or
+ pattern callback, the Lisp/ToolTalk callback machinery does this
+ for you.
-Coding Systems
-==============
-
- A coding system is an object that defines how text containing
-multiple character sets is encoded into a stream of (typically 8-bit)
-bytes. The coding system is used to decode the stream into a series of
-characters (which may be from multiple charsets) when the text is read
-from a file or process, and is used to encode the text back into the
-same format when it is written out to a file or process.
-
- For example, many ISO-2022-compliant coding systems (such as Compound
-Text, which is used for inter-client data under the X Window System) use
-escape sequences to switch between different charsets - Japanese Kanji,
-for example, is invoked with `ESC $ ( B'; ASCII is invoked with `ESC (
-B'; and Cyrillic is invoked with `ESC - L'. See `make-coding-system'
-for more information.
-
- Coding systems are normally identified using a symbol, and the
-symbol is accepted in place of the actual coding system object whenever
-a coding system is called for. (This is similar to how faces and
-charsets work.)
+\1f
+File: lispref.info, Node: Receiving Messages, Prev: Sending Messages, Up: ToolTalk Support
- - Function: coding-system-p object
- This function returns non-`nil' if OBJECT is a coding system.
+Receiving Messages
+==================
* Menu:
-* Coding System Types:: Classifying coding systems.
-* EOL Conversion:: Dealing with different ways of denoting
- the end of a line.
-* Coding System Properties:: Properties of a coding system.
-* Basic Coding System Functions:: Working with coding systems.
-* Coding System Property Functions:: Retrieving a coding system's properties.
-* Encoding and Decoding Text:: Encoding and decoding text.
-* Detection of Textual Encoding:: Determining how text is encoded.
-* Big5 and Shift-JIS Functions:: Special functions for these non-standard
- encodings.
-
-\1f
-File: lispref.info, Node: Coding System Types, Next: EOL Conversion, Up: Coding Systems
-
-Coding System Types
--------------------
-
-`nil'
-`autodetect'
- Automatic conversion. XEmacs attempts to detect the coding system
- used in the file.
-
-`no-conversion'
- No conversion. Use this for binary files and such. On output,
- graphic characters that are not in ASCII or Latin-1 will be
- replaced by a `?'. (For a no-conversion-encoded buffer, these
- characters will only be present if you explicitly insert them.)
-
-`shift-jis'
- Shift-JIS (a Japanese encoding commonly used in PC operating
- systems).
-
-`iso2022'
- Any ISO-2022-compliant encoding. Among other things, this
- includes JIS (the Japanese encoding commonly used for e-mail),
- national variants of EUC (the standard Unix encoding for Japanese
- and other languages), and Compound Text (an encoding used in X11).
- You can specify more specific information about the conversion
- with the FLAGS argument.
-
-`big5'
- Big5 (the encoding commonly used for Taiwanese).
-
-`ccl'
- The conversion is performed using a user-written pseudo-code
- program. CCL (Code Conversion Language) is the name of this
- pseudo-code.
-
-`internal'
- Write out or read in the raw contents of the memory representing
- the buffer's text. This is primarily useful for debugging
- purposes, and is only enabled when XEmacs has been compiled with
- `DEBUG_XEMACS' set (the `--debug' configure option). *Warning*:
- Reading in a file using `internal' conversion can result in an
- internal inconsistency in the memory representing a buffer's text,
- which will produce unpredictable results and may cause XEmacs to
- crash. Under normal circumstances you should never use `internal'
- conversion.
+* Example of Receiving Messages::
+* Elisp Interface for Receiving Messages::
\1f
-File: lispref.info, Node: EOL Conversion, Next: Coding System Properties, Prev: Coding System Types, Up: Coding Systems
-
-EOL Conversion
---------------
-
-`nil'
- Automatically detect the end-of-line type (LF, CRLF, or CR). Also
- generate subsidiary coding systems named `NAME-unix', `NAME-dos',
- and `NAME-mac', that are identical to this coding system but have
- an EOL-TYPE value of `lf', `crlf', and `cr', respectively.
+File: lispref.info, Node: Example of Receiving Messages, Next: Elisp Interface for Receiving Messages, Up: Receiving Messages
-`lf'
- The end of a line is marked externally using ASCII LF. Since this
- is also the way that XEmacs represents an end-of-line internally,
- specifying this option results in no end-of-line conversion. This
- is the standard format for Unix text files.
-
-`crlf'
- The end of a line is marked externally using ASCII CRLF. This is
- the standard format for MS-DOS text files.
+Example of Receiving Messages
+-----------------------------
-`cr'
- The end of a line is marked externally using ASCII CR. This is the
- standard format for Macintosh text files.
+ Here's a simple example of a handler for a message that tells XEmacs
+to display a string in the mini-buffer area. The message operation is
+called `emacs-display-string'. Its first (0th) argument is the string
+to display.
-`t'
- Automatically detect the end-of-line type but do not generate
- subsidiary coding systems. (This value is converted to `nil' when
- stored internally, and `coding-system-property' will return `nil'.)
+ (defun tooltalk-display-string-handler (msg)
+ (message (get-tooltalk-message-attribute msg 'arg_val 0)))
+
+ (defvar display-string-pattern
+ '(category TT_HANDLE
+ scope TT_SESSION
+ op "emacs-display-string"
+ callback tooltalk-display-string-handler))
+
+ (let ((p (make-tooltalk-pattern display-string-pattern)))
+ (register-tooltalk-pattern p))
\1f
-File: lispref.info, Node: Coding System Properties, Next: Basic Coding System Functions, Prev: EOL Conversion, Up: Coding Systems
-
-Coding System Properties
-------------------------
-
-`mnemonic'
- String to be displayed in the modeline when this coding system is
- active.
-
-`eol-type'
- End-of-line conversion to be used. It should be one of the types
- listed in *Note EOL Conversion::.
-
-`post-read-conversion'
- Function called after a file has been read in, to perform the
- decoding. Called with two arguments, BEG and END, denoting a
- region of the current buffer to be decoded.
-
-`pre-write-conversion'
- Function called before a file is written out, to perform the
- encoding. Called with two arguments, BEG and END, denoting a
- region of the current buffer to be encoded.
-
- The following additional properties are recognized if TYPE is
-`iso2022':
-
-`charset-g0'
-`charset-g1'
-`charset-g2'
-`charset-g3'
- The character set initially designated to the G0 - G3 registers.
- The value should be one of
-
- * A charset object (designate that character set)
-
- * `nil' (do not ever use this register)
-
- * `t' (no character set is initially designated to the
- register, but may be later on; this automatically sets the
- corresponding `force-g*-on-output' property)
-
-`force-g0-on-output'
-`force-g1-on-output'
-`force-g2-on-output'
-`force-g3-on-output'
- If non-`nil', send an explicit designation sequence on output
- before using the specified register.
-
-`short'
- If non-`nil', use the short forms `ESC $ @', `ESC $ A', and `ESC $
- B' on output in place of the full designation sequences `ESC $ (
- @', `ESC $ ( A', and `ESC $ ( B'.
-
-`no-ascii-eol'
- If non-`nil', don't designate ASCII to G0 at each end of line on
- output. Setting this to non-`nil' also suppresses other
- state-resetting that normally happens at the end of a line.
-
-`no-ascii-cntl'
- If non-`nil', don't designate ASCII to G0 before control chars on
- output.
-
-`seven'
- If non-`nil', use 7-bit environment on output. Otherwise, use
- 8-bit environment.
-
-`lock-shift'
- If non-`nil', use locking-shift (SO/SI) instead of single-shift or
- designation by escape sequence.
-
-`no-iso6429'
- If non-`nil', don't use ISO6429's direction specification.
-
-`escape-quoted'
- If non-nil, literal control characters that are the same as the
- beginning of a recognized ISO 2022 or ISO 6429 escape sequence (in
- particular, ESC (0x1B), SO (0x0E), SI (0x0F), SS2 (0x8E), SS3
- (0x8F), and CSI (0x9B)) are "quoted" with an escape character so
- that they can be properly distinguished from an escape sequence.
- (Note that doing this results in a non-portable encoding.) This
- encoding flag is used for byte-compiled files. Note that ESC is a
- good choice for a quoting character because there are no escape
- sequences whose second byte is a character from the Control-0 or
- Control-1 character sets; this is explicitly disallowed by the ISO
- 2022 standard.
-
-`input-charset-conversion'
- A list of conversion specifications, specifying conversion of
- characters in one charset to another when decoding is performed.
- Each specification is a list of two elements: the source charset,
- and the destination charset.
-
-`output-charset-conversion'
- A list of conversion specifications, specifying conversion of
- characters in one charset to another when encoding is performed.
- The form of each specification is the same as for
- `input-charset-conversion'.
-
- The following additional properties are recognized (and required) if
-TYPE is `ccl':
-
-`decode'
- CCL program used for decoding (converting to internal format).
-
-`encode'
- CCL program used for encoding (converting to external format).
+File: lispref.info, Node: Elisp Interface for Receiving Messages, Prev: Example of Receiving Messages, Up: Receiving Messages
+
+Elisp Interface for Receiving Messages
+--------------------------------------
+
+ - Function: make-tooltalk-pattern attributes
+ Create a ToolTalk pattern and initialize its attributes. The
+ value of attributes must be a list of alternating keyword/values,
+ where keywords are symbols that name valid pattern attributes or
+ lists of valid attributes. For example:
+
+ (make-tooltalk-pattern
+ '(category TT_OBSERVE
+ scope TT_SESSION
+ op ("operation1" "operation2")
+ args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
+
+ Attribute names are the same as those supported by
+ `add-tooltalk-pattern-attribute', plus `'args'.
+
+ Values must always be strings, integers, or symbols that represent
+ ToolTalk constants or lists of same. When a list of values is
+ provided all of the list elements are added to the attribute. In
+ the example above, messages whose `op' attribute is `"operation1"'
+ or `"operation2"' would match the pattern.
+
+ The value of ARGS should be a list of pattern arguments where each
+ pattern argument has the following form:
+
+ `(mode [value [type]])' or just `value'
+
+ Where MODE is one of `TT_IN', `TT_OUT', or `TT_INOUT' and TYPE is
+ a string. If TYPE isn't specified then `int' is used if VALUE is
+ a number; otherwise `string' is used. If TYPE is `string' then
+ VALUE is converted to a string (if it isn't a string already) with
+ `prin1-to-string'. If only a value is specified then MODE
+ defaults to `TT_IN'. If MODE is `TT_OUT' then VALUE and TYPE
+ don't need to be specified. You can find out more about the
+ semantics and uses of ToolTalk pattern arguments in chapter 3 of
+ the `ToolTalk Programmer's Guide'.
+
+
+ - Function: register-tooltalk-pattern pat
+ XEmacs will begin receiving messages that match this pattern.
+
+ - Function: unregister-tooltalk-pattern pat
+ XEmacs will stop receiving messages that match this pattern.
+
+ - Function: add-tooltalk-pattern-attribute value pat indicator
+ Add one value to the indicated pattern attribute. The names of
+ attributes are the same as the ToolTalk accessors used to set them
+ less the `tooltalk_pattern_' prefix and the `_add' suffix. For
+ example, the name of the attribute for the
+ `tt_pattern_disposition_add' attribute is `disposition'. The
+ `category' attribute is handled specially, since a pattern can only
+ be a member of one category (`TT_OBSERVE' or `TT_HANDLE').
+
+ Callbacks are handled slightly differently than in the C ToolTalk
+ API. The value of CALLBACK should be the name of a function of one
+ argument. It will be called each time the pattern matches an
+ incoming message.
+
+ - Function: add-tooltalk-pattern-arg pat mode type value
+ Add one fully-specified argument to a ToolTalk pattern. MODE must
+ be one of `TT_IN', `TT_INOUT', or `TT_OUT'. TYPE must be a
+ string. VALUE can be an integer, string or `nil'. If VALUE is an
+ integer then an integer argument (`tt_pattern_iarg_add') is added;
+ otherwise a string argument is added. At present there's no way
+ to add a binary data argument.
+
+
+ - Function: create-tooltalk-pattern
+ Create a new ToolTalk pattern and initialize its session attribute
+ to be the default session.
+
+ - Function: destroy-tooltalk-pattern pat
+ Apply `tt_pattern_destroy' to the pattern. This effectively
+ unregisters the pattern.
+
+ - Function: describe-tooltalk-message msg &optional stream
+ Print the message's attributes and arguments to STREAM. This is
+ often useful for debugging.
\1f
-File: lispref.info, Node: Basic Coding System Functions, Next: Coding System Property Functions, Prev: Coding System Properties, Up: Coding Systems
+File: lispref.info, Node: LDAP Support, Next: PostgreSQL Support, Prev: ToolTalk Support, Up: Top
-Basic Coding System Functions
------------------------------
+LDAP Support
+************
- - Function: find-coding-system coding-system-or-name
- This function retrieves the coding system of the given name.
+ XEmacs can be linked with a LDAP client library to provide Elisp
+primitives to access directory servers using the Lightweight Directory
+Access Protocol.
- If CODING-SYSTEM-OR-NAME is a coding-system object, it is simply
- returned. Otherwise, CODING-SYSTEM-OR-NAME should be a symbol.
- If there is no such coding system, `nil' is returned. Otherwise
- the associated coding system object is returned.
+* Menu:
- - Function: get-coding-system name
- This function retrieves the coding system of the given name. Same
- as `find-coding-system' except an error is signalled if there is no
- such coding system instead of returning `nil'.
+* Building XEmacs with LDAP support:: How to add LDAP support to XEmacs
+* XEmacs LDAP API:: Lisp access to LDAP functions
+* Syntax of Search Filters:: A brief summary of RFC 1558
- - Function: coding-system-list
- This function returns a list of the names of all defined coding
- systems.
+\1f
+File: lispref.info, Node: Building XEmacs with LDAP support, Next: XEmacs LDAP API, Prev: LDAP Support, Up: LDAP Support
- - Function: coding-system-name coding-system
- This function returns the name of the given coding system.
+Building XEmacs with LDAP support
+=================================
- - Function: make-coding-system name type &optional doc-string props
- This function registers symbol NAME as a coding system.
+ LDAP support must be added to XEmacs at build time since it requires
+linking to an external LDAP client library. As of 21.2, XEmacs has been
+successfully built and tested with
- TYPE describes the conversion method used and should be one of the
- types listed in *Note Coding System Types::.
+ * OpenLDAP 1.2 (<http://www.openldap.org/>)
- DOC-STRING is a string describing the coding system.
+ * University of Michigan's LDAP 3.3
+ (<http://www.umich.edu/~dirsvcs/ldap/>)
- PROPS is a property list, describing the specific nature of the
- character set. Recognized properties are as in *Note Coding
- System Properties::.
+ * LDAP SDK 1.0 from Netscape Corp. (<http://developer.netscape.com/>)
- - Function: copy-coding-system old-coding-system new-name
- This function copies OLD-CODING-SYSTEM to NEW-NAME. If NEW-NAME
- does not name an existing coding system, a new one will be created.
+ Other libraries conforming to RFC 1823 will probably work also but
+may require some minor tweaking at C level.
- - Function: subsidiary-coding-system coding-system eol-type
- This function returns the subsidiary coding system of
- CODING-SYSTEM with eol type EOL-TYPE.
+ The standard XEmacs configure script auto-detects an installed LDAP
+library provided the library itself and the corresponding header files
+can be found in the library and include paths. A successful detection
+will be signalled in the final output of the configure script.
\1f
-File: lispref.info, Node: Coding System Property Functions, Next: Encoding and Decoding Text, Prev: Basic Coding System Functions, Up: Coding Systems
-
-Coding System Property Functions
---------------------------------
-
- - Function: coding-system-doc-string coding-system
- This function returns the doc string for CODING-SYSTEM.
-
- - Function: coding-system-type coding-system
- This function returns the type of CODING-SYSTEM.
+File: lispref.info, Node: XEmacs LDAP API, Next: Syntax of Search Filters, Prev: Building XEmacs with LDAP support, Up: LDAP Support
- - Function: coding-system-property coding-system prop
- This function returns the PROP property of CODING-SYSTEM.
+XEmacs LDAP API
+===============
-\1f
-File: lispref.info, Node: Encoding and Decoding Text, Next: Detection of Textual Encoding, Prev: Coding System Property Functions, Up: Coding Systems
-
-Encoding and Decoding Text
---------------------------
-
- - Function: decode-coding-region start end coding-system &optional
- buffer
- This function decodes the text between START and END which is
- encoded in CODING-SYSTEM. This is useful if you've read in
- encoded text from a file without decoding it (e.g. you read in a
- JIS-formatted file but used the `binary' or `no-conversion' coding
- system, so that it shows up as `^[$B!<!+^[(B'). The length of the
- encoded text is returned. BUFFER defaults to the current buffer
- if unspecified.
-
- - Function: encode-coding-region start end coding-system &optional
- buffer
- This function encodes the text between START and END using
- CODING-SYSTEM. This will, for example, convert Japanese
- characters into stuff such as `^[$B!<!+^[(B' if you use the JIS
- encoding. The length of the encoded text is returned. BUFFER
- defaults to the current buffer if unspecified.
+ XEmacs LDAP API consists of two layers: a low-level layer which
+tries to stay as close as possible to the C API (where practical) and a
+higher-level layer which provides more convenient primitives to
+effectively use LDAP.
-\1f
-File: lispref.info, Node: Detection of Textual Encoding, Next: Big5 and Shift-JIS Functions, Prev: Encoding and Decoding Text, Up: Coding Systems
+ The low-level API should be used directly for very specific purposes
+(such as multiple operations on a connection) only. The higher-level
+functions provide a more convenient way to access LDAP directories
+hiding the subtleties of handling the connection, translating arguments
+and ensuring compliance with LDAP internationalization rules and formats
+(currently partly implemented only).
-Detection of Textual Encoding
------------------------------
+* Menu:
- - Function: coding-category-list
- This function returns a list of all recognized coding categories.
-
- - Function: set-coding-priority-list list
- This function changes the priority order of the coding categories.
- LIST should be a list of coding categories, in descending order of
- priority. Unspecified coding categories will be lower in priority
- than all specified ones, in the same relative order they were in
- previously.
-
- - Function: coding-priority-list
- This function returns a list of coding categories in descending
- order of priority.
-
- - Function: set-coding-category-system coding-category coding-system
- This function changes the coding system associated with a coding
- category.
-
- - Function: coding-category-system coding-category
- This function returns the coding system associated with a coding
- category.
-
- - Function: detect-coding-region start end &optional buffer
- This function detects coding system of the text in the region
- between START and END. Returned value is a list of possible coding
- systems ordered by priority. If only ASCII characters are found,
- it returns `autodetect' or one of its subsidiary coding systems
- according to a detected end-of-line type. Optional arg BUFFER
- defaults to the current buffer.
+* LDAP Variables:: Lisp variables related to LDAP
+* The High-Level LDAP API:: High-level LDAP lisp functions
+* The Low-Level LDAP API:: Low-level LDAP lisp primitives
+* LDAP Internationalization:: I18n variables and functions