34.4 Describing Characters for Help Messages

These functions convert events, key sequences or characters to textual descriptions. These descriptions are useful for including arbitrary text characters or key sequences in messages, because they convert non-printing and whitespace characters to sequences of printing characters. The description of a non-whitespace printing character is the character itself.

Function: key-description sequence

This function returns a string containing the SXEmacs standard notation for the input events in sequence. The argument sequence may be a string, vector or list. See Events, for more information about valid events. See also the examples for single-key-description, below.

Function: single-key-description key

This function returns a string describing key in the standard SXEmacs notation for keyboard input. A normal printing character appears as itself, but a control character turns into a string starting with ‘C-’, a meta character turns into a string starting with ‘M-’, and space, linefeed, etc. appear as ‘SPC’, ‘LFD’, etc. A symbol appears as the name of the symbol. An event that is a list appears as the name of the symbol in the CAR of the list.

(single-key-description ?\C-x)
     ⇒ "C-x"

(key-description "\C-x \M-y \n \t \r \f123")
     ⇒ "C-x SPC M-y SPC LFD SPC TAB SPC RET SPC C-l 1 2 3"

(single-key-description 'kp-next)
     ⇒ "kp-next"

(single-key-description '(shift button1))
     ⇒ "Sh-button1"

Function: text-char-description character

This function returns a string describing character in the standard SXEmacs notation for characters that appear in text—like single-key-description, except that control characters are represented with a leading caret (which is how control characters in SXEmacs buffers are usually displayed).

(text-char-description ?\C-c)
     ⇒ "^C"

(text-char-description ?\M-m)
     ⇒ "M-m"

(text-char-description ?\C-\M-m)
     ⇒ "M-^M"