-This is ../info/lispref.info, produced by makeinfo version 3.12s from
+This is ../info/lispref.info, produced by makeinfo version 4.0b from
lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
Foundation instead of in the original English.
\1f
-File: lispref.info, Node: The Echo Area, Next: Warnings, Prev: Truncation, Up: Display
-
-The Echo Area
-=============
-
- The "echo area" is used for displaying messages made with the
-`message' primitive, and for echoing keystrokes. It is not the same as
-the minibuffer, despite the fact that the minibuffer appears (when
-active) in the same place on the screen as the echo area. The `XEmacs
-Reference Manual' specifies the rules for resolving conflicts between
-the echo area and the minibuffer for use of that screen space (*note
-The Minibuffer: (emacs)Minibuffer.). Error messages appear in the echo
-area; see *Note Errors::.
-
- You can write output in the echo area by using the Lisp printing
-functions with `t' as the stream (*note Output Functions::), or as
-follows:
-
- - Function: message string &rest arguments
- This function displays a one-line message in the echo area. The
- argument STRING is similar to a C language `printf' control
- string. See `format' in *Note String Conversion::, for the details
- on the conversion specifications. `message' returns the
- constructed string.
-
- In batch mode, `message' prints the message text on the standard
- error stream, followed by a newline.
-
- If STRING is `nil', `message' clears the echo area. If the
- minibuffer is active, this brings the minibuffer contents back onto
- the screen immediately.
-
- (message "Minibuffer depth is %d."
- (minibuffer-depth))
- -| Minibuffer depth is 0.
- => "Minibuffer depth is 0."
-
- ---------- Echo Area ----------
- Minibuffer depth is 0.
- ---------- Echo Area ----------
-
- In addition to only displaying a message, XEmacs allows you to
-"label" your messages, giving you fine-grained control of their
-display. Message label is a symbol denoting the message type. Some
-standard labels are:
-
- * `message'--default label used by the `message' function;
-
- * `error'--default label used for reporting errors;
-
- * `progress'--progress indicators like `Converting... 45%' (not
- logged by default);
-
- * `prompt'--prompt-like messages like `Isearch: foo' (not logged by
- default);
-
- * `command'--helper command messages like `Mark set' (not logged by
- default);
-
- * `no-log'--messages that should never be logged
-
- Several messages may be stacked in the echo area at once. Lisp
-programs may access these messages, or remove them as appropriate, via
-the message stack.
-
- - Function: display-message label message &optional frame stdout-p
- This function displays MESSAGE (a string) labeled as LABEL, as
- described above.
-
- The FRAME argument specifies the frame to whose minibuffer the
- message should be printed. This is currently unimplemented. The
- STDOUT-P argument is used internally.
-
- (display-message 'command "Mark set")
-
- - Function: lmessage label string &rest arguments
- This function displays a message STRING with label LABEL. It is
- similar to `message' in that it accepts a `printf'-like strings
- and any number of arguments.
-
- ;; Display a command message.
- (lmessage 'command "Comment column set to %d" comment-column)
-
- ;; Display a progress message.
- (lmessage 'progress "Fontifying %s... (%d)" buffer percentage)
-
- ;; Display a message that should not be logged.
- (lmessage 'no-log "Done")
-
- - Function: clear-message &optional label frame stdout-p no-restore
- This function remove any message with the given LABEL from the
- message-stack, erasing it from the echo area if it's currently
- displayed there.
-
- If a message remains at the head of the message-stack and
- NO-RESTORE is `nil', it will be displayed. The string which
- remains in the echo area will be returned, or `nil' if the
- message-stack is now empty. If LABEL is nil, the entire
- message-stack is cleared.
-
- ;; Show a message, wait for 2 seconds, and restore old minibuffer
- ;; contents.
- (message "A message")
- -| A message
- => "A Message"
- (lmessage 'my-label "Newsflash! Newsflash!")
- -| Newsflash! Newsflash!
- => "Newsflash! Newsflash!"
- (sit-for 2)
- (clear-message 'my-label)
- -| A message
- => "A message"
-
- Unless you need the return value or you need to specify a label,
- you should just use `(message nil)'.
-
- - Function: current-message &optional frame
- This function returns the current message in the echo area, or
- `nil'. The FRAME argument is currently unused.
-
- Some of the messages displayed in the echo area are also recorded in
-the ` *Message-Log*' buffer. Exactly which messages will be recorded
-can be tuned using the following variables.
-
- - User Option: log-message-max-size
- This variable specifies the maximum size of the ` *Message-log*'
- buffer.
-
- - Variable: log-message-ignore-labels
- This variable specifies the labels whose messages will not be
- logged. It should be a list of symbols.
-
- - Variable: log-message-ignore-regexps
- This variable specifies the regular expressions matching messages
- that will not be logged. It should be a list of regular
- expressions.
-
- Normally, packages that generate messages that might need to be
- ignored should label them with `progress', `prompt', or `no-log',
- so they can be filtered by `log-message-ignore-labels'.
-
- - Variable: echo-keystrokes
- This variable determines how much time should elapse before command
- characters echo. Its value must be a number, which specifies the
- number of seconds to wait before echoing. If the user types a
- prefix key (such as `C-x') and then delays this many seconds
- before continuing, the prefix key is echoed in the echo area. Any
- subsequent characters in the same command will be echoed as well.
-
- If the value is zero, then command input is not echoed.
-
- - Variable: cursor-in-echo-area
- This variable controls where the cursor appears when a message is
- displayed in the echo area. If it is non-`nil', then the cursor
- appears at the end of the message. Otherwise, the cursor appears
- at point--not in the echo area at all.
-
- The value is normally `nil'; Lisp programs bind it to `t' for
- brief periods of time.
-
-\1f
-File: lispref.info, Node: Warnings, Next: Invisible Text, Prev: The Echo Area, Up: Display
-
-Warnings
-========
-
- XEmacs contains a facility for unified display of various warnings.
-Unlike errors, warnings are displayed in the situations when XEmacs
-encounters a problem that is recoverable, but which should be fixed for
-safe future operation.
-
- For example, warnings are printed by the startup code when it
-encounters problems with X keysyms, when there is an error in `.emacs',
-and in other problematic situations. Unlike messages, warnings are
-displayed in a separate buffer, and include an explanatory message that
-may span across several lines. Here is an example of how a warning is
-displayed:
-
- (1) (initialization/error) An error has occurred while loading ~/.emacs:
-
- Symbol's value as variable is void: bogus-variable
-
- To ensure normal operation, you should investigate the cause of the error
- in your initialization file and remove it. Use the `-debug-init' option
- to XEmacs to view a complete error backtrace.
-
- Each warning has a "class" and a "priority level". The class is a
-symbol describing what sort of warning this is, such as
-`initialization', `resource' or `key-mapping'.
-
- The warning priority level specifies how important the warning is.
-The recognized warning levels, in increased order of priority, are:
-`debug', `info', `notice', `warning', `error', `critical', `alert' and
-`emergency'.
-
- - Function: display-warning class message &optional level
- This function displays a warning message MESSAGE (a string).
- CLASS should be a warning class symbol, as described above, or a
- list of such symbols. LEVEL describes the warning priority level.
- If unspecified, it default to `warning'.
-
- (display-warning 'resource
- "Bad resource specification encountered:
- something like
-
- Emacs*foo: bar
-
- You should replace the * with a . in order to get proper behavior when
- you use the specifier and/or `set-face-*' functions.")
-
- ---------- Warning buffer ----------
- (1) (resource/warning) Bad resource specification encountered:
- something like
-
- Emacs*foo: bar
-
- You should replace the * with a . in order to get proper behavior when
- you use the specifier and/or `set-face-*' functions.
- ---------- Warning buffer ----------
-
- - Function: lwarn class level message &rest args
- This function displays a formatted labeled warning message. As
- above, CLASS should be the warning class symbol, or a list of such
- symbols, and LEVEL should specify the warning priority level
- (`warning' by default).
-
- Unlike in `display-warning', MESSAGE may be a formatted message,
- which will be, together with the rest of the arguments, passed to
- `format'.
-
- (lwarn 'message-log 'warning
- "Error caught in `remove-message-hook': %s"
- (error-message-string e))
-
- - Variable: log-warning-minimum-level
- This variable specifies the minimum level of warnings that should
- be generated. Warnings with level lower than defined by this
- variable are completely ignored, as if they never happened.
-
- - Variable: display-warning-minimum-level
- This variable specifies the minimum level of warnings that should
- be displayed. Unlike `log-warning-minimum-level', setting this
- function does not suppress warnings entirely--they are still
- generated in the `*Warnings*' buffer, only they are not displayed
- by default.
-
- - Variable: log-warning-suppressed-classes
- This variable specifies a list of classes that should not be
- logged or displayed. If any of the class symbols associated with
- a warning is the same as any of the symbols listed here, the
- warning will be completely ignored, as it they never happened.
-
- - Variable: display-warning-suppressed-classes
- This variable specifies a list of classes that should not be
- logged or displayed. If any of the class symbols associated with
- a warning is the same as any of the symbols listed here, the
- warning will not be displayed. The warning will still logged in
- the *Warnings* buffer (unless also contained in
- `log-warning-suppressed-classes'), but the buffer will not be
- automatically popped up.
-
-\1f
-File: lispref.info, Node: Invisible Text, Next: Selective Display, Prev: Warnings, Up: Display
-
-Invisible Text
-==============
-
- You can make characters "invisible", so that they do not appear on
-the screen, with the `invisible' property. This can be either a text
-property or a property of an overlay.
-
- In the simplest case, any non-`nil' `invisible' property makes a
-character invisible. This is the default case--if you don't alter the
-default value of `buffer-invisibility-spec', this is how the
-`invisibility' property works. This feature is much like selective
-display (*note Selective Display::), but more general and cleaner.
-
- More generally, you can use the variable `buffer-invisibility-spec'
-to control which values of the `invisible' property make text
-invisible. This permits you to classify the text into different subsets
-in advance, by giving them different `invisible' values, and
-subsequently make various subsets visible or invisible by changing the
-value of `buffer-invisibility-spec'.
-
- Controlling visibility with `buffer-invisibility-spec' is especially
-useful in a program to display the list of entries in a data base. It
-permits the implementation of convenient filtering commands to view
-just a part of the entries in the data base. Setting this variable is
-very fast, much faster than scanning all the text in the buffer looking
-for properties to change.
-
- - Variable: buffer-invisibility-spec
- This variable specifies which kinds of `invisible' properties
- actually make a character invisible.
-
- `t'
- A character is invisible if its `invisible' property is
- non-`nil'. This is the default.
-
- a list
- Each element of the list makes certain characters invisible.
- Ultimately, a character is invisible if any of the elements
- of this list applies to it. The list can have two kinds of
- elements:
-
- `ATOM'
- A character is invisible if its `invisible' property
- value is ATOM or if it is a list with ATOM as a member.
-
- `(ATOM . t)'
- A character is invisible if its `invisible' property
- value is ATOM or if it is a list with ATOM as a member.
- Moreover, if this character is at the end of a line and
- is followed by a visible newline, it displays an
- ellipsis.
-
- Ordinarily, commands that operate on text or move point do not care
-whether the text is invisible. However, the user-level line motion
-commands explicitly ignore invisible newlines.
-
-\1f
-File: lispref.info, Node: Selective Display, Next: Overlay Arrow, Prev: Invisible Text, Up: Display
-
-Selective Display
-=================
-
- "Selective display" is a pair of features that hide certain lines on
-the screen.
-
- The first variant, explicit selective display, is designed for use in
-a Lisp program. The program controls which lines are hidden by altering
-the text. Outline mode has traditionally used this variant. It has
-been partially replaced by the invisible text feature (*note Invisible
-Text::); there is a new version of Outline mode which uses that instead.
-
- In the second variant, the choice of lines to hide is made
-automatically based on indentation. This variant is designed to be a
-user-level feature.
-
- The way you control explicit selective display is by replacing a
-newline (control-j) with a carriage return (control-m). The text that
-was formerly a line following that newline is now invisible. Strictly
-speaking, it is temporarily no longer a line at all, since only newlines
-can separate lines; it is now part of the previous line.
-
- Selective display does not directly affect editing commands. For
-example, `C-f' (`forward-char') moves point unhesitatingly into
-invisible text. However, the replacement of newline characters with
-carriage return characters affects some editing commands. For example,
-`next-line' skips invisible lines, since it searches only for newlines.
-Modes that use selective display can also define commands that take
-account of the newlines, or that make parts of the text visible or
-invisible.
-
- When you write a selectively displayed buffer into a file, all the
-control-m's are output as newlines. This means that when you next read
-in the file, it looks OK, with nothing invisible. The selective display
-effect is seen only within XEmacs.
-
- - Variable: selective-display
- This buffer-local variable enables selective display. This means
- that lines, or portions of lines, may be made invisible.
-
- * If the value of `selective-display' is `t', then any portion
- of a line that follows a control-m is not displayed.
-
- * If the value of `selective-display' is a positive integer,
- then lines that start with more than that many columns of
- indentation are not displayed.
-
- When some portion of a buffer is invisible, the vertical movement
- commands operate as if that portion did not exist, allowing a
- single `next-line' command to skip any number of invisible lines.
- However, character movement commands (such as `forward-char') do
- not skip the invisible portion, and it is possible (if tricky) to
- insert or delete text in an invisible portion.
-
- In the examples below, we show the _display appearance_ of the
- buffer `foo', which changes with the value of `selective-display'.
- The _contents_ of the buffer do not change.
-
- (setq selective-display nil)
- => nil
-
- ---------- Buffer: foo ----------
- 1 on this column
- 2on this column
- 3n this column
- 3n this column
- 2on this column
- 1 on this column
- ---------- Buffer: foo ----------
-
- (setq selective-display 2)
- => 2
-
- ---------- Buffer: foo ----------
- 1 on this column
- 2on this column
- 2on this column
- 1 on this column
- ---------- Buffer: foo ----------
-
- - Variable: selective-display-ellipses
- If this buffer-local variable is non-`nil', then XEmacs displays
- `...' at the end of a line that is followed by invisible text.
- This example is a continuation of the previous one.
-
- (setq selective-display-ellipses t)
- => t
-
- ---------- Buffer: foo ----------
- 1 on this column
- 2on this column ...
- 2on this column
- 1 on this column
- ---------- Buffer: foo ----------
-
- You can use a display table to substitute other text for the
- ellipsis (`...'). *Note Display Tables::.
-
-\1f
-File: lispref.info, Node: Overlay Arrow, Next: Temporary Displays, Prev: Selective Display, Up: Display
-
-The Overlay Arrow
-=================
-
- The "overlay arrow" is useful for directing the user's attention to
-a particular line in a buffer. For example, in the modes used for
-interface to debuggers, the overlay arrow indicates the line of code
-about to be executed.
-
- - Variable: overlay-arrow-string
- This variable holds the string to display to call attention to a
- particular line, or `nil' if the arrow feature is not in use.
- Despite its name, the value of this variable can be either a string
- or a glyph (*note Glyphs::).
-
- - Variable: overlay-arrow-position
- This variable holds a marker that indicates where to display the
- overlay arrow. It should point at the beginning of a line. The
- arrow text appears at the beginning of that line, overlaying any
- text that would otherwise appear. Since the arrow is usually
- short, and the line usually begins with indentation, normally
- nothing significant is overwritten.
-
- The overlay string is displayed only in the buffer that this marker
- points into. Thus, only one buffer can have an overlay arrow at
- any given time.
-
- You can do the same job by creating an extent with a `begin-glyph'
-property. *Note Extent Properties::.
+File: lispref.info, Node: Glyph Properties, Next: Glyph Convenience Functions, Prev: Creating Glyphs, Up: Glyph Functions
+
+Glyph Properties
+----------------
+
+ Each glyph has a list of properties, which control all of the
+aspects of the glyph's appearance. The following symbols have
+predefined meanings:
+
+`image'
+ The image used to display the glyph.
+
+`baseline'
+ Percent above baseline that glyph is to be displayed. Only for
+ glyphs displayed inside of a buffer.
+
+`contrib-p'
+ Whether the glyph contributes to the height of the line it's on.
+ Only for glyphs displayed inside of a buffer.
+
+`face'
+ Face of this glyph (_not_ a specifier).
+
+ - Function: set-glyph-property glyph property value &optional locale
+ tag-set how-to-add
+ This function changes a property of a GLYPH.
+
+ For built-in properties, the actual value of the property is a
+ specifier and you cannot change this; but you can change the
+ specifications within the specifier, and that is what this
+ function will do. For user-defined properties, you can use this
+ function to either change the actual value of the property or, if
+ this value is a specifier, change the specifications within it.
+
+ If PROPERTY is a built-in property, the specifications to be added
+ to this property can be supplied in many different ways:
+
+ * If VALUE is a simple instantiator (e.g. a string naming a
+ pixmap filename) or a list of instantiators, then the
+ instantiator(s) will be added as a specification of the
+ property for the given LOCALE (which defaults to `global' if
+ omitted).
+
+ * If VALUE is a list of specifications (each of which is a cons
+ of a locale and a list of instantiators), then LOCALE must be
+ `nil' (it does not make sense to explicitly specify a locale
+ in this case), and specifications will be added as given.
+
+ * If VALUE is a specifier (as would be returned by
+ `glyph-property' if no LOCALE argument is given), then some
+ or all of the specifications in the specifier will be added
+ to the property. In this case, the function is really
+ equivalent to `copy-specifier' and LOCALE has the same
+ semantics (if it is a particular locale, the specification
+ for the locale will be copied; if a locale type,
+ specifications for all locales of that type will be copied;
+ if `nil' or `all', then all specifications will be copied).
+
+ HOW-TO-ADD should be either `nil' or one of the symbols `prepend',
+ `append', `remove-tag-set-prepend', `remove-tag-set-append',
+ `remove-locale', `remove-locale-type', or `remove-all'. See
+ `copy-specifier' and `add-spec-to-specifier' for a description of
+ what each of these means. Most of the time, you do not need to
+ worry about this argument; the default behavior usually is fine.
+
+ In general, it is OK to pass an instance object (e.g. as returned
+ by `glyph-property-instance') as an instantiator in place of an
+ actual instantiator. In such a case, the instantiator used to
+ create that instance object will be used (for example, if you set
+ a font-instance object as the value of the `font' property, then
+ the font name used to create that object will be used instead).
+ If some cases, however, doing this conversion does not make sense,
+ and this will be noted in the documentation for particular types
+ of instance objects.
+
+ If PROPERTY is not a built-in property, then this function will
+ simply set its value if LOCALE is `nil'. However, if LOCALE is
+ given, then this function will attempt to add VALUE as the
+ instantiator for the given LOCALE, using `add-spec-to-specifier'.
+ If the value of the property is not a specifier, it will
+ automatically be converted into a `generic' specifier.
+
+ - Function: glyph-property glyph property &optional locale
+ This function returns GLYPH's value of the given PROPERTY.
+
+ If LOCALE is omitted, the GLYPH's actual value for PROPERTY will
+ be returned. For built-in properties, this will be a specifier
+ object of a type appropriate to the property (e.g. a font or color
+ specifier). For other properties, this could be anything.
+
+ If LOCALE is supplied, then instead of returning the actual value,
+ the specification(s) for the given locale or locale type will be
+ returned. This will only work if the actual value of PROPERTY is
+ a specifier (this will always be the case for built-in properties,
+ but may or may not apply to user-defined properties). If the
+ actual value of PROPERTY is not a specifier, this value will
+ simply be returned regardless of LOCALE.
+
+ The return value will be a list of instantiators (e.g. vectors
+ specifying pixmap data), or a list of specifications, each of
+ which is a cons of a locale and a list of instantiators.
+ Specifically, if LOCALE is a particular locale (a buffer, window,
+ frame, device, or `global'), a list of instantiators for that
+ locale will be returned. Otherwise, if LOCALE is a locale type
+ (one of the symbols `buffer', `window', `frame', or `device'), the
+ specifications for all locales of that type will be returned.
+ Finally, if LOCALE is `all', the specifications for all locales of
+ all types will be returned.
+
+ The specifications in a specifier determine what the value of
+ PROPERTY will be in a particular "domain" or set of circumstances,
+ which is typically a particular Emacs window along with the buffer
+ it contains and the frame and device it lies within. The value is
+ derived from the instantiator associated with the most specific
+ locale (in the order buffer, window, frame, device, and `global')
+ that matches the domain in question. In other words, given a
+ domain (i.e. an Emacs window, usually), the specifier for PROPERTY
+ will first be searched for a specification whose locale is the
+ buffer contained within that window; then for a specification
+ whose locale is the window itself; then for a specification whose
+ locale is the frame that the window is contained within; etc. The
+ first instantiator that is valid for the domain (usually this
+ means that the instantiator is recognized by the device [i.e. the
+ X server or TTY device] that the domain is on). The function
+ `glyph-property-instance' actually does all this, and is used to
+ determine how to display the glyph.
+
+ - Function: glyph-property-instance glyph property &optional domain
+ default no-fallback
+ This function returns the instance of GLYPH's PROPERTY in the
+ specified DOMAIN.
+
+ Under most circumstances, DOMAIN will be a particular window, and
+ the returned instance describes how the specified property
+ actually is displayed for that window and the particular buffer in
+ it. Note that this may not be the same as how the property
+ appears when the buffer is displayed in a different window or
+ frame, or how the property appears in the same window if you
+ switch to another buffer in that window; and in those cases, the
+ returned instance would be different.
+
+ The returned instance is an image-instance object, and you can
+ query it using the appropriate image instance functions. For
+ example, you could use `image-instance-depth' to find out the
+ depth (number of color planes) of a pixmap displayed in a
+ particular window. The results might be different from the
+ results you would get for another window (perhaps the user
+ specified a different image for the frame that window is on; or
+ perhaps the same image was specified but the window is on a
+ different X server, and that X server has different color
+ capabilities from this one).
+
+ DOMAIN defaults to the selected window if omitted.
+
+ DOMAIN can be a frame or device, instead of a window. The value
+ returned for such a domain is used in special circumstances when a
+ more specific domain does not apply; for example, a frame value
+ might be used for coloring a toolbar, which is conceptually
+ attached to a frame rather than a particular window. The value is
+ also useful in determining what the value would be for a
+ particular window within the frame or device, if it is not
+ overridden by a more specific specification.
+
+ If PROPERTY does not name a built-in property, its value will
+ simply be returned unless it is a specifier object, in which case
+ it will be instanced using `specifier-instance'.
+
+ Optional arguments DEFAULT and NO-FALLBACK are the same as in
+ `specifier-instance'. *Note Specifiers::.
+
+ - Function: remove-glyph-property glyph property &optional locale
+ tag-set exact-p
+ This function removes a property from a glyph. For built-in
+ properties, this is analogous to `remove-specifier'. *Note
+ remove-specifier-p: Specifiers, for the meaning of the LOCALE,
+ TAG-SET, and EXACT-P arguments.
\1f
-File: lispref.info, Node: Temporary Displays, Next: Blinking, Prev: Overlay Arrow, Up: Display
-
-Temporary Displays
-==================
-
- Temporary displays are used by commands to put output into a buffer
-and then present it to the user for perusal rather than for editing.
-Many of the help commands use this feature.
-
- - Special Form: with-output-to-temp-buffer buffer-name forms...
- This function executes FORMS while arranging to insert any output
- they print into the buffer named BUFFER-NAME. The buffer is then
- shown in some window for viewing, displayed but not selected.
-
- The string BUFFER-NAME specifies the temporary buffer, which need
- not already exist. The argument must be a string, not a buffer.
- The buffer is erased initially (with no questions asked), and it is
- marked as unmodified after `with-output-to-temp-buffer' exits.
-
- `with-output-to-temp-buffer' binds `standard-output' to the
- temporary buffer, then it evaluates the forms in FORMS. Output
- using the Lisp output functions within FORMS goes by default to
- that buffer (but screen display and messages in the echo area,
- although they are "output" in the general sense of the word, are
- not affected). *Note Output Functions::.
-
- The value of the last form in FORMS is returned.
-
- ---------- Buffer: foo ----------
- This is the contents of foo.
- ---------- Buffer: foo ----------
-
- (with-output-to-temp-buffer "foo"
- (print 20)
- (print standard-output))
- => #<buffer foo>
-
- ---------- Buffer: foo ----------
- 20
-
- #<buffer foo>
-
- ---------- Buffer: foo ----------
-
- - Variable: temp-buffer-show-function
- If this variable is non-`nil', `with-output-to-temp-buffer' calls
- it as a function to do the job of displaying a help buffer. The
- function gets one argument, which is the buffer it should display.
-
- In Emacs versions 18 and earlier, this variable was called
- `temp-buffer-show-hook'.
-
- - Function: momentary-string-display string position &optional char
- message
- This function momentarily displays STRING in the current buffer at
- POSITION. It has no effect on the undo list or on the buffer's
- modification status.
-
- The momentary display remains until the next input event. If the
- next input event is CHAR, `momentary-string-display' ignores it
- and returns. Otherwise, that event remains buffered for
- subsequent use as input. Thus, typing CHAR will simply remove the
- string from the display, while typing (say) `C-f' will remove the
- string from the display and later (presumably) move point forward.
- The argument CHAR is a space by default.
-
- The return value of `momentary-string-display' is not meaningful.
-
- You can do the same job in a more general way by creating an extent
- with a begin-glyph property. *Note Extent Properties::.
-
- If MESSAGE is non-`nil', it is displayed in the echo area while
- STRING is displayed in the buffer. If it is `nil', a default
- message says to type CHAR to continue.
-
- In this example, point is initially located at the beginning of the
- second line:
-
- ---------- Buffer: foo ----------
- This is the contents of foo.
- -!-Second line.
- ---------- Buffer: foo ----------
-
- (momentary-string-display
- "**** Important Message! ****"
- (point) ?\r
- "Type RET when done reading")
- => t
-
- ---------- Buffer: foo ----------
- This is the contents of foo.
- **** Important Message! ****Second line.
- ---------- Buffer: foo ----------
-
- ---------- Echo Area ----------
- Type RET when done reading
- ---------- Echo Area ----------
-
- This function works by actually changing the text in the buffer.
- As a result, if you later undo in this buffer, you will see the
- message come and go.
+File: lispref.info, Node: Glyph Convenience Functions, Next: Glyph Dimensions, Prev: Glyph Properties, Up: Glyph Functions
+
+Glyph Convenience Functions
+---------------------------
+
+ The following functions are provided for working with specific
+properties of a glyph. Note that these are exactly like calling the
+general functions described above and passing in the appropriate value
+for PROPERTY.
+
+ Remember that if you want to determine the "value" of a specific
+glyph property, you probably want to use the `*-instance' functions.
+For example, to determine whether a glyph contributes to its line
+height, use `glyph-contrib-p-instance', not `glyph-contrib-p'. (The
+latter will return a boolean specifier or a list of specifications, and
+you probably aren't concerned with these.)
+
+ - Function: glyph-image glyph &optional locale
+ This function is equivalent to calling `glyph-property' with a
+ property of `image'. The return value will be an image specifier
+ if LOCALE is `nil' or omitted; otherwise, it will be a
+ specification or list of specifications.
+
+ - Function: set-glyph-image glyph spec &optional locale tag-set
+ how-to-add
+ This function is equivalent to calling `set-glyph-property' with a
+ property of `image'.
+
+ - Function: glyph-image-instance glyph &optional domain default
+ no-fallback
+ This function returns the instance of GLYPH's image in the given
+ DOMAIN, and is equivalent to calling `glyph-property-instance'
+ with a property of `image'. The return value will be an image
+ instance.
+
+ Normally DOMAIN will be a window or `nil' (meaning the selected
+ window), and an instance object describing how the image appears
+ in that particular window and buffer will be returned.
+
+ - Function: glyph-contrib-p glyph &optional locale
+ This function is equivalent to calling `glyph-property' with a
+ property of `contrib-p'. The return value will be a boolean
+ specifier if LOCALE is `nil' or omitted; otherwise, it will be a
+ specification or list of specifications.
+
+ - Function: set-glyph-contrib-p glyph spec &optional locale tag-set
+ how-to-add
+ This function is equivalent to calling `set-glyph-property' with a
+ property of `contrib-p'.
+
+ - Function: glyph-contrib-p-instance glyph &optional domain default
+ no-fallback
+ This function returns whether the glyph contributes to its line
+ height in the given DOMAIN, and is equivalent to calling
+ `glyph-property-instance' with a property of `contrib-p'. The
+ return value will be either `nil' or `t'. (Normally DOMAIN will be
+ a window or `nil', meaning the selected window.)
+
+ - Function: glyph-baseline glyph &optional locale
+ This function is equivalent to calling `glyph-property' with a
+ property of `baseline'. The return value will be a specifier if
+ LOCALE is `nil' or omitted; otherwise, it will be a specification
+ or list of specifications.
+
+ - Function: set-glyph-baseline glyph spec &optional locale tag-set
+ how-to-add
+ This function is equivalent to calling `set-glyph-property' with a
+ property of `baseline'.
+
+ - Function: glyph-baseline-instance glyph &optional domain default
+ no-fallback
+ This function returns the instance of GLYPH's baseline value in
+ the given DOMAIN, and is equivalent to calling
+ `glyph-property-instance' with a property of `baseline'. The
+ return value will be an integer or `nil'.
+
+ Normally DOMAIN will be a window or `nil' (meaning the selected
+ window), and an instance object describing the baseline value
+ appears in that particular window and buffer will be returned.
+
+ - Function: glyph-face glyph
+ This function returns the face of GLYPH. (Remember, this is not a
+ specifier, but a simple property.)
+
+ - Function: set-glyph-face glyph face
+ This function changes the face of GLYPH to FACE.
\1f
-File: lispref.info, Node: Blinking, Next: Usual Display, Prev: Temporary Displays, Up: Display
-
-Blinking Parentheses
-====================
-
- This section describes the mechanism by which XEmacs shows a matching
-open parenthesis when the user inserts a close parenthesis.
-
- - Variable: blink-paren-function
- The value of this variable should be a function (of no arguments)
- to be called whenever a character with close parenthesis syntax is
- inserted. The value of `blink-paren-function' may be `nil', in
- which case nothing is done.
-
- *Please note:* This variable was named `blink-paren-hook' in
- older Emacs versions, but since it is not called with the
- standard convention for hooks, it was renamed to
- `blink-paren-function' in version 19.
-
- - Variable: blink-matching-paren
- If this variable is `nil', then `blink-matching-open' does nothing.
-
- - Variable: blink-matching-paren-distance
- This variable specifies the maximum distance to scan for a matching
- parenthesis before giving up.
-
- - Variable: blink-matching-paren-delay
- This variable specifies the number of seconds for the cursor to
- remain at the matching parenthesis. A fraction of a second often
- gives good results, but the default is 1, which works on all
- systems.
-
- - Function: blink-matching-open
- This function is the default value of `blink-paren-function'. It
- assumes that point follows a character with close parenthesis
- syntax and moves the cursor momentarily to the matching opening
- character. If that character is not already on the screen, it
- displays the character's context in the echo area. To avoid long
- delays, this function does not search farther than
- `blink-matching-paren-distance' characters.
-
- Here is an example of calling this function explicitly.
-
- (defun interactive-blink-matching-open ()
- "Indicate momentarily the start of sexp before point."
- (interactive)
- (let ((blink-matching-paren-distance
- (buffer-size))
- (blink-matching-paren t))
- (blink-matching-open)))
-
-\1f
-File: lispref.info, Node: Usual Display, Next: Display Tables, Prev: Blinking, Up: Display
-
-Usual Display Conventions
-=========================
+File: lispref.info, Node: Glyph Dimensions, Prev: Glyph Convenience Functions, Up: Glyph Functions
- The usual display conventions define how to display each character
-code. You can override these conventions by setting up a display table
-(*note Display Tables::). Here are the usual display conventions:
+Glyph Dimensions
+----------------
- * Character codes 32 through 126 map to glyph codes 32 through 126.
- Normally this means they display as themselves.
+ - Function: glyph-width glyph &optional window
+ This function returns the width of GLYPH on WINDOW. This may not
+ be exact as it does not take into account all of the context that
+ redisplay will.
- * Character code 9 is a horizontal tab. It displays as whitespace
- up to a position determined by `tab-width'.
+ - Function: glyph-ascent glyph &optional window
+ This function returns the ascent value of GLYPH on WINDOW. This
+ may not be exact as it does not take into account all of the
+ context that redisplay will.
- * Character code 10 is a newline.
+ - Function: glyph-descent glyph &optional window
+ This function returns the descent value of GLYPH on WINDOW. This
+ may not be exact as it does not take into account all of the
+ context that redisplay will.
- * All other codes in the range 0 through 31, and code 127, display
- in one of two ways according to the value of `ctl-arrow'. If it is
- non-`nil', these codes map to sequences of two glyphs, where the
- first glyph is the ASCII code for `^'. (A display table can
- specify a glyph to use instead of `^'.) Otherwise, these codes map
- just like the codes in the range 128 to 255.
-
- * Character codes 128 through 255 map to sequences of four glyphs,
- where the first glyph is the ASCII code for `\', and the others are
- digit characters representing the code in octal. (A display table
- can specify a glyph to use instead of `\'.)
-
- The usual display conventions apply even when there is a display
-table, for any character whose entry in the active display table is
-`nil'. Thus, when you set up a display table, you need only specify
-the characters for which you want unusual behavior.
-
- These variables affect the way certain characters are displayed on
-the screen. Since they change the number of columns the characters
-occupy, they also affect the indentation functions.
-
- - User Option: ctl-arrow
- This buffer-local variable controls how control characters are
- displayed. If it is non-`nil', they are displayed as a caret
- followed by the character: `^A'. If it is `nil', they are
- displayed as a backslash followed by three octal digits: `\001'.
-
- - Variable: default-ctl-arrow
- The value of this variable is the default value for `ctl-arrow' in
- buffers that do not override it. *Note Default Value::.
-
- - User Option: tab-width
- The value of this variable is the spacing between tab stops used
- for displaying tab characters in Emacs buffers. The default is 8.
- Note that this feature is completely independent from the
- user-settable tab stops used by the command `tab-to-tab-stop'.
- *Note Indent Tabs::.
+ - Function: glyph-height glyph &optional window
+ This function returns the height of GLYPH on WINDOW. (This is
+ equivalent to the sum of the ascent and descent values.) This may
+ not be exact as it does not take into account all of the context
+ that redisplay will.
\1f
-File: lispref.info, Node: Display Tables, Next: Beeping, Prev: Usual Display, Up: Display
-
-Display Tables
-==============
-
- You can use the "display table" feature to control how all 256
-possible character codes display on the screen. This is useful for
-displaying European languages that have letters not in the ASCII
-character set.
+File: lispref.info, Node: Images, Next: Glyph Types, Prev: Glyph Functions, Up: Glyphs
- The display table maps each character code into a sequence of
-"runes", each rune being an image that takes up one character position
-on the screen. You can also define how to display each rune on your
-terminal, using the "rune table".
+Images
+======
* Menu:
-* Display Table Format:: What a display table consists of.
-* Active Display Table:: How XEmacs selects a display table to use.
-* Character Descriptors:: Format of an individual element of a
- display table.
+* Image Specifiers:: Specifying how an image will appear.
+* Image Instantiator Conversion::
+ Conversion is applied to image instantiators
+ at the time they are added to an
+ image specifier or at the time they
+ are passed to `make-image-instance'.
+* Image Instances:: What an image specifier gets instanced as.
\1f
-File: lispref.info, Node: Display Table Format, Next: Active Display Table, Up: Display Tables
-
-Display Table Format
---------------------
-
- A display table is an array of 256 elements. (In FSF Emacs, a display
-table is 262 elements. The six extra elements specify the truncation
-and continuation glyphs, etc. This method is very kludgey, and in
-XEmacs the variables `truncation-glyph', `continuation-glyph', etc. are
-used. *Note Truncation::.)
-
- - Function: make-display-table
- This creates and returns a display table. The table initially has
- `nil' in all elements.
-
- The 256 elements correspond to character codes; the Nth element says
-how to display the character code N. The value should be `nil', a
-string, a glyph, or a vector of strings and glyphs (*note Character
-Descriptors::). If an element is `nil', it says to display that
-character according to the usual display conventions (*note Usual
-Display::).
-
- If you use the display table to change the display of newline
-characters, the whole buffer will be displayed as one long "line."
-
- For example, here is how to construct a display table that mimics the
-effect of setting `ctl-arrow' to a non-`nil' value:
-
- (setq disptab (make-display-table))
- (let ((i 0))
- (while (< i 32)
- (or (= i ?\t) (= i ?\n)
- (aset disptab i (concat "^" (char-to-string (+ i 64)))))
- (setq i (1+ i)))
- (aset disptab 127 "^?"))
+File: lispref.info, Node: Image Specifiers, Next: Image Instantiator Conversion, Up: Images
+
+Image Specifiers
+----------------
+
+ An image specifier is used to describe the actual image of a glyph.
+It works like other specifiers (*note Specifiers::), in that it contains
+a number of specifications describing how the image should appear in a
+variety of circumstances. These specifications are called "image
+instantiators". When XEmacs wants to display the image, it instantiates
+the image into an "image instance". Image instances are their own
+primitive object type (similar to font instances and color instances),
+describing how the image appears in a particular domain. (On the other
+hand, image instantiators, which are just descriptions of how the image
+should appear, are represented using strings or vectors.)
+
+ - Function: image-specifier-p object
+ This function returns non-`nil' if OBJECT is an image specifier.
+ Usually, an image specifier results from calling `glyph-image' on
+ a glyph.
+
+ - Function: make-image-specifier spec-list
+ This function creates a new image specifier object and initializes
+ it according to SPEC-LIST. *Note Specifiers::.
+
+ Note that, in practice, you rarely, if ever, need to actually
+ create an image specifier! (This function exists mainly for
+ completeness.) Pretty much the only use for image specifiers is to
+ control how glyphs are displayed, and the image specifier
+ associated with a glyph (the `image' property of a glyph) is
+ created automatically when a glyph is created and need not (and
+ cannot, for that matter) ever be changed (*note Glyphs::). In
+ fact, the design decision to create a separate image specifier
+ type, rather than make glyphs themselves be specifiers, is
+ debatable--the other properties of glyphs are rarely used and could
+ conceivably have been incorporated into the glyph's instantiator.
+ The rarely used glyph types (buffer, pointer, icon) could also
+ have been incorporated into the instantiator.
+
+ Image instantiators come in many formats: `xbm', `xpm', `gif',
+`jpeg', etc. This describes the format of the data describing the
+image. The resulting image instances also come in many
+types--`mono-pixmap', `color-pixmap', `text', `pointer', etc. This
+refers to the behavior of the image and the sorts of places it can
+appear. (For example, a color-pixmap image has fixed colors specified
+for it, while a mono-pixmap image comes in two unspecified shades
+"foreground" and "background" that are determined from the face of the
+glyph or surrounding text; a text image appears as a string of text and
+has an unspecified foreground, background, and font; a pointer image
+behaves like a mono-pixmap image but can only be used as a mouse
+pointer [mono-pixmap images cannot be used as mouse pointers]; etc.) It
+is important to keep the distinction between image instantiator format
+and image instance type in mind. Typically, a given image instantiator
+format can result in many different image instance types (for example,
+`xpm' can be instanced as `color-pixmap', `mono-pixmap', or `pointer';
+whereas `cursor-font' can be instanced only as `pointer'), and a
+particular image instance type can be generated by many different image
+instantiator formats (e.g. `color-pixmap' can be generated by `xpm',
+`gif', `jpeg', etc.).
+
+ *Note Image Instances::, for a more detailed discussion of image
+instance types.
+
+ An image instantiator should be a string or a vector of the form
+
+ `[FORMAT :KEYWORD VALUE ...]'
+
+ i.e. a format symbol followed by zero or more alternating
+keyword-value pairs. The "format" field should be a symbol, one of
+
+`nothing'
+ Don't display anything; no keywords are valid for this. Can only
+ be instanced as `nothing'.
+
+`string'
+ Display this image as a text string. Can only be instanced as
+ `text', although support for instancing as `mono-pixmap' should be
+ added.
+
+`formatted-string'
+ Display this image as a text string with replaceable fields,
+ similar to a modeline format string; not currently implemented.
+
+`xbm'
+ An X bitmap; only if X support was compiled into this XEmacs. Can
+ be instanced as `mono-pixmap', `color-pixmap', or `pointer'.
+
+`xpm'
+ An XPM pixmap; only if XPM support was compiled into this XEmacs.
+ Can be instanced as `color-pixmap', `mono-pixmap', or `pointer'.
+ XPM is an add-on library for X that was designed to rectify the
+ shortcomings of the XBM format. Most implementations of X include
+ the XPM library as a standard part. If your vendor does not, it
+ is highly recommended that you download it and install it. You
+ can get it from the standard XEmacs FTP site, among other places.
+
+`xface'
+ An X-Face bitmap, used to encode people's faces in e-mail messages;
+ only if X-Face support was compiled into this XEmacs. Can be
+ instanced as `mono-pixmap', `color-pixmap', or `pointer'.
+
+`gif'
+ A GIF87 or GIF89 image; only if GIF support was compiled into this
+ XEmacs. Can be instanced as `color-pixmap'. Note that XEmacs
+ includes GIF decoding functions as a standard part of it, so if
+ you have X support, you will normally have GIF support, unless you
+ explicitly disable it at configure time.
+
+`jpeg'
+ A JPEG-format image; only if JPEG support was compiled into this
+ XEmacs. Can be instanced as `color-pixmap'. If you have the JPEG
+ libraries present on your system when XEmacs is built, XEmacs will
+ automatically detect this and use them, unless you explicitly
+ disable it at configure time.
+
+`png'
+ A PNG/GIF24 image; only if PNG support was compiled into this
+ XEmacs. Can be instanced as `color-pixmap'.
+
+`tiff'
+ A TIFF-format image; only if TIFF support was compiled into this
+ XEmacs.
+
+`cursor-font'
+ One of the standard cursor-font names, such as `watch' or
+ `right_ptr' under X. Under X, this is, more specifically, any of
+ the standard cursor names from appendix B of the Xlib manual [also
+ known as the file `<X11/cursorfont.h>'] minus the `XC_' prefix. On
+ other window systems, the valid names will be specific to the type
+ of window system. Can only be instanced as `pointer'.
+
+`font'
+ A glyph from a font; i.e. the name of a font, and glyph index into
+ it of the form `FONT fontname index [[mask-font] mask-index]'.
+ Only if X support was compiled into this XEmacs. Currently can
+ only be instanced as `pointer', although this should probably be
+ fixed.
+
+`mswindows-resource'
+ An MS Windows pointer resource. Specifies a resource to retrieve
+ directly from the system (an OEM resource) or from a file,
+ particularly an executable file. If the resource is to be
+ retrieved from a file, use :file and optionally :resource-id.
+ Otherwise use :resource-id. Always specify :resource-type to
+ specify the type (cursor, bitmap or icon) of the resource.
+ Possible values for :resource-id are listed below. Can be
+ instanced as `pointer' or `color-pixmap'.
+
+`subwindow'
+ An embedded windowing system window. Can only be instanced as
+ `subwindow'.
+
+`button'
+ A button widget; either a push button, radio button or toggle
+ button. Can only be instanced as `widget'.
+
+`combo-box'
+ A drop list of selectable items in a widget, for editing text.
+ Can only be instanced as `widget'.
+
+`edit-field'
+ A text editing widget. Can only be instanced as `widget'.
+
+`label'
+ A static, text-only, widget; for displaying text. Can only be
+ instanced as `widget'.
+
+`layout'
+ A widget for controlling the positioning of children underneath it.
+ Through the use of nested layouts, a widget hierarchy can be
+ created which can have the appearance of any standard dialog box
+ or similar arrangement; all of this is counted as one "glyph" and
+ could appear in many of the places that expect a single glyph.
+ Can only be instanced as `widget'.
+
+`native-layout'
+ The native version of a layout widget. Can only be instanced as
+ `widget'.
+
+`progress-gauge'
+ A sliding widget, for showing progress. Can only be instanced as
+ `widget'.
+
+`tab-control'
+ A tab widget; a series of user selectable tabs. Can only be
+ instanced as `widget'.
+
+`tree-view'
+ A folding widget. Can only be instanced as `widget'.
+
+`scrollbar'
+ A scrollbar widget. Can only be instanced as `widget'.
+
+`autodetect'
+ XEmacs tries to guess what format the data is in. If X support
+ exists, the data string will be checked to see if it names a
+ filename. If so, and this filename contains XBM or XPM data, the
+ appropriate sort of pixmap or pointer will be created. [This
+ includes picking up any specified hotspot or associated mask
+ file.] Otherwise, if `pointer' is one of the allowable
+ image-instance types and the string names a valid cursor-font
+ name, the image will be created as a pointer. Otherwise, the
+ image will be displayed as text. If no X support exists, the
+ image will always be displayed as text.
+
+`inherit'
+ Inherit from the background-pixmap property of a face. Can only be
+ instanced as `mono-pixmap'.
+
+ The valid keywords are:
+
+`:data'
+ Inline data. For most formats above, this should be a string. For
+ XBM images, this should be a list of three elements: width,
+ height, and a string of bit data. This keyword is not valid for
+ instantiator format `nothing'.
+
+`:file'
+ Data is contained in a file. The value is the name of this file.
+ If both `:data' and `:file' are specified, the image is created
+ from what is specified in `:data' and the string in `:file'
+ becomes the value of the `image-instance-file-name' function when
+ applied to the resulting image-instance. This keyword is not
+ valid for instantiator formats `nothing', `string',
+ `formatted-string', `cursor-font', `font', and `autodetect'.
+
+`:foreground'
+`:background'
+ For `xbm', `xface', `cursor-font', and `font'. These keywords
+ allow you to explicitly specify foreground and background colors.
+ The argument should be anything acceptable to
+ `make-color-instance'. This will cause what would be a
+ `mono-pixmap' to instead be colorized as a two-color color-pixmap,
+ and specifies the foreground and/or background colors for a pointer
+ instead of black and white.
+
+`:mask-data'
+ For `xbm' and `xface'. This specifies a mask to be used with the
+ bitmap. The format is a list of width, height, and bits, like for
+ `:data'.
+
+`:mask-file'
+ For `xbm' and `xface'. This specifies a file containing the mask
+ data. If neither a mask file nor inline mask data is given for an
+ XBM image, and the XBM image comes from a file, XEmacs will look
+ for a mask file with the same name as the image file but with
+ `Mask' or `msk' appended. For example, if you specify the XBM file
+ `left_ptr' [usually located in `/usr/include/X11/bitmaps'], the
+ associated mask file `left_ptrmsk' will automatically be picked up.
+
+`:hotspot-x'
+`:hotspot-y'
+ For `xbm' and `xface'. These keywords specify a hotspot if the
+ image is instantiated as a `pointer'. Note that if the XBM image
+ file specifies a hotspot, it will automatically be picked up if no
+ explicit hotspot is given.
+
+`:color-symbols'
+ Only for `xpm'. This specifies an alist that maps strings that
+ specify symbolic color names to the actual color to be used for
+ that symbolic color (in the form of a string or a color-specifier
+ object). If this is not specified, the contents of
+ `xpm-color-symbols' are used to generate the alist.
+
+`:resource-id'
+ Only for `mswindows-resource'. This must be either an integer
+ (which directly specifies a resource number) or a string. Valid
+ strings are
+
+ For bitmaps:
+
+ "close", "uparrow", "dnarrow", "rgarrow", "lfarrow", "reduce",
+ "zoom", "restore", "reduced", "zoomd", "restored", "uparrowd",
+ "dnarrowd", "rgarrowd", "lfarrowd", "mnarrow", "combo",
+ "uparrowi", "dnarrowi", "rgarrowi", "lfarrowi", "size", "btsize",
+ "check", "checkboxes", and "btncorners".
+
+ For cursors:
+
+ "normal", "ibeam", "wait", "cross", "up", "sizenwse", "sizenesw",
+ "sizewe", "sizens", "sizeall", and "no".
+
+ For icons:
+
+ "sample", "hand", "ques", "bang", "note", and "winlogo".
+
+`:resource-type'
+ Only for `mswindows-resource'. This must be a symbol, either
+ `cursor', `icon', or `bitmap', specifying the type of resource to
+ be retrieved.
+
+`:face'
+ Only for `inherit'. This specifies the face to inherit from. For
+ widgets this also specifies the face to use for display. It
+ defaults to gui-element-face.
+
+ Keywords accepted as menu item specs are also accepted by widgets.
+These are `:selected', `:active', `:suffix', `:keys', `:style',
+`:filter', `:config', `:included', `:key-sequence', `:accelerator',
+`:label' and `:callback'.
+
+ If instead of a vector, the instantiator is a string, it will be
+converted into a vector by looking it up according to the specs in the
+`console-type-image-conversion-list' for the console type of the domain
+(usually a window; sometimes a frame or device) over which the image is
+being instantiated.
+
+ If the instantiator specifies data from a file, the data will be
+read in at the time that the instantiator is added to the image
+specifier (which may be well before the image is actually displayed),
+and the instantiator will be converted into one of the inline-data
+forms, with the filename retained using a `:file' keyword. This
+implies that the file must exist when the instantiator is added to the
+image, but does not need to exist at any other time (e.g. it may safely
+be a temporary file).
+
+ - Function: valid-image-instantiator-format-p format &optional locale
+ This function returns non-`nil' if FORMAT is a valid image
+ instantiator format.
+
+ If LOCALE is non-`nil' then the format is checked in that locale.
+ If LOCALE is `nil' the current console is used.
+
+ Note that the return value for many formats listed above depends on
+ whether XEmacs was compiled with support for that format.
+
+ - Function: image-instantiator-format-list
+ This function return a list of valid image-instantiator formats.
+
+ - Variable: xpm-color-symbols
+ This variable holds definitions of logical color-names used when
+ reading XPM files. Elements of this list should be of the form
+ `(COLOR-NAME FORM-TO-EVALUATE)'. The COLOR-NAME should be a
+ string, which is the name of the color to define; the
+ FORM-TO-EVALUATE should evaluate to a color specifier object, or a
+ string to be passed to `make-color-instance' (*note Colors::). If
+ a loaded XPM file references a symbolic color called COLOR-NAME,
+ it will display as the computed color instead.
+
+ The default value of this variable defines the logical color names
+ `"foreground"' and `"background"' to be the colors of the
+ `default' face.
+
+ - Variable: x-bitmap-file-path
+ 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).
\1f
-File: lispref.info, Node: Active Display Table, Next: Character Descriptors, Prev: Display Table Format, Up: Display Tables
-
-Active Display Table
---------------------
-
- The active display table is controlled by the variable
-`current-display-table'. This is a specifier, which means that you can
-specify separate values for it in individual buffers, windows, frames,
-and devices, as well as a global value. It also means that you cannot
-set this variable using `setq'; use `set-specifier' instead. *Note
-Specifiers::. (FSF Emacs uses `window-display-table',
-`buffer-display-table', `standard-display-table', etc. to control the
-display table. However, specifiers are a cleaner and more powerful way
-of doing the same thing. FSF Emacs also uses a different format for
-the contents of a display table, using additional indirection to a
-"glyph table" and such. Note that "glyph" has a different meaning in
-XEmacs.)
-
- Individual faces can also specify an overriding display table; this
-is set using `set-face-display-table'. *Note Faces::.
-
- If no display table can be determined for a particular window, then
-XEmacs uses the usual display conventions. *Note Usual Display::.
+File: lispref.info, Node: Image Instantiator Conversion, Next: Image Instances, Prev: Image Specifiers, Up: Images
+
+Image Instantiator Conversion
+-----------------------------
+
+ - Function: set-console-type-image-conversion-list console-type list
+ This function sets the image-conversion-list for consoles of the
+ given CONSOLE-TYPE. The image-conversion-list specifies how image
+ instantiators that are strings should be interpreted. Each
+ element of the list should be a list of two elements (a regular
+ expression string and a vector) or a list of three elements (the
+ preceding two plus an integer index into the vector). The string
+ is converted to the vector associated with the first matching
+ regular expression. If a vector index is specified, the string
+ itself is substituted into that position in the vector.
+
+ Note: The conversion above is applied when the image instantiator
+ is added to an image specifier, not when the specifier is actually
+ instantiated. Therefore, changing the image-conversion-list only
+ affects newly-added instantiators. Existing instantiators in
+ glyphs and image specifiers will not be affected.
+
+ - Function: console-type-image-conversion-list console-type
+ This function returns the image-conversion-list for consoles of
+ the given CONSOLE-TYPE.
\1f
-File: lispref.info, Node: Character Descriptors, Prev: Active Display Table, Up: Display Tables
+File: lispref.info, Node: Image Instances, Prev: Image Instantiator Conversion, Up: Images
-Character Descriptors
----------------------
+Image Instances
+---------------
- Each element of the display-table vector describes how to display a
-particular character and is called a "character descriptor". A
-character descriptor can be:
+ Image-instance objects encapsulate the way a particular image
+(pixmap, etc.) is displayed on a particular device.
-a string
- Display this particular string wherever the character is to be
- displayed.
+ In most circumstances, you do not need to directly create image
+instances; use a glyph instead. However, it may occasionally be useful
+to explicitly create image instances, if you want more control over the
+instantiation process.
-a glyph
- Display this particular glyph wherever the character is to be
- displayed.
+ - Function: image-instance-p object
+ This function returns non-`nil' if OBJECT is an image instance.
-a vector
- The vector may contain strings and/or glyphs. Display the
- elements of the vector one after another wherever the character is
- to be displayed.
+* Menu:
-`nil'
- Display according to the standard interpretation (*note Usual
- Display::).
+* Image Instance Types:: Each image instances has a particular type.
+* Image Instance Functions:: Functions for working with image instances.
\1f
-File: lispref.info, Node: Beeping, Prev: Display Tables, Up: Display
-
-Beeping
-=======
-
- You can make XEmacs ring a bell, play a sound, or blink the screen to
-attract the user's attention. Be conservative about how often you do
-this; frequent bells can become irritating. Also be careful not to use
-beeping alone when signaling an error is appropriate. (*Note Errors::.)
-
- - Function: ding &optional dont-terminate sound device
- This function beeps, or flashes the screen (see `visible-bell'
- below). It also terminates any keyboard macro currently executing
- unless DONT-TERMINATE is non-`nil'. If SOUND is specified, it
- should be a symbol specifying which sound to make. This sound
- will be played if `visible-bell' is `nil'. (This only works if
- sound support was compiled into the executable and you are running
- on the console of a Sun SparcStation, SGI, HP9000s700, or Linux
- PC. Otherwise you just get a beep.) The optional third argument
- specifies what device to make the sound on, and defaults to the
- selected device.
-
- - Function: beep &optional dont-terminate sound device
- This is a synonym for `ding'.
-
- - User Option: visible-bell
- This variable determines whether XEmacs should flash the screen to
- represent a bell. Non-`nil' means yes, `nil' means no. On TTY
- devices, this is effective only if the Termcap entry for the
- terminal type has the visible bell flag (`vb') set.
-
- - Variable: sound-alist
- This variable holds an alist associating names with sounds. When
- `beep' or `ding' is called with one of the name symbols, the
- associated sound will be generated instead of the standard beep.
-
- Each element of `sound-alist' is a list describing a sound. The
- first element of the list is the name of the sound being defined.
- Subsequent elements of the list are alternating keyword/value
- pairs:
-
- `sound'
- A string of raw sound data, or the name of another sound to
- play. The symbol `t' here means use the default X beep.
-
- `volume'
- An integer from 0-100, defaulting to `bell-volume'.
-
- `pitch'
- If using the default X beep, the pitch (Hz) to generate.
-
- `duration'
- If using the default X beep, the duration (milliseconds).
+File: lispref.info, Node: Image Instance Types, Next: Image Instance Functions, Up: Image Instances
- For compatibility, elements of `sound-alist' may also be:
+Image Instance Types
+....................
- * `( sound-name . <sound> )'
+ Image instances come in a number of different types. The type of an
+image instance specifies the nature of the image: Whether it is a text
+string, a mono pixmap, a color pixmap, etc.
- * `( sound-name <volume> <sound> )'
+ The valid image instance types are
- You should probably add things to this list by calling the function
- `load-sound-file'.
+`nothing'
+ Nothing is displayed.
- Caveats:
+`text'
+ Displayed as text. The foreground and background colors and the
+ font of the text are specified independent of the pixmap.
+ Typically these attributes will come from the face of the
+ surrounding text, unless a face is specified for the glyph in
+ which the image appears.
- - You can only play audio data if running on the console screen
- of a Sun SparcStation, SGI, or HP9000s700.
+`mono-pixmap'
+ Displayed as a mono pixmap (a pixmap with only two colors where the
+ foreground and background can be specified independent of the
+ pixmap; typically the pixmap assumes the foreground and background
+ colors of the text around it, unless a face is specified for the
+ glyph in which the image appears).
- - The pitch, duration, and volume options are available
- everywhere, but many X servers ignore the `pitch' option.
+`color-pixmap'
+ Displayed as a color pixmap.
- The following beep-types are used by XEmacs itself:
+`pointer'
+ Used as the mouse pointer for a window.
- `auto-save-error'
- when an auto-save does not succeed
+`subwindow'
+ A child window that is treated as an image. This allows (e.g.)
+ another program to be responsible for drawing into the window.
+ Not currently implemented.
- `command-error'
- when the XEmacs command loop catches an error
+ - Function: valid-image-instance-type-p type
+ This function returns non-`nil' if TYPE is a valid image instance
+ type.
- `undefined-key'
- when you type a key that is undefined
+ - Function: image-instance-type-list
+ This function returns a list of the valid image instance types.
- `undefined-click'
- when you use an undefined mouse-click combination
+ - Function: image-instance-type image-instance
+ This function returns the type of the given image instance. The
+ return value will be one of `nothing', `text', `mono-pixmap',
+ `color-pixmap', `pointer', or `subwindow'.
- `no-completion'
- during completing-read
+ - Function: text-image-instance-p object
+ This function returns non-`nil' if OBJECT is an image instance of
+ type `text'.
- `y-or-n-p'
- when you type something other than 'y' or 'n'
+ - Function: mono-pixmap-image-instance-p object
+ This function returns non-`nil' if OBJECT is an image instance of
+ type `mono-pixmap'.
- `yes-or-no-p'
- when you type something other than 'yes' or 'no'
+ - Function: color-pixmap-image-instance-p object
+ This function returns non-`nil' if OBJECT is an image instance of
+ type `color-pixmap'.
- `default'
- used when nothing else is appropriate.
+ - Function: pointer-image-instance-p object
+ This function returns non-`nil' if OBJECT is an image instance of
+ type `pointer'.
- Other lisp packages may use other beep types, but these are the
- ones that the C kernel of XEmacs uses.
+ - Function: subwindow-image-instance-p object
+ This function returns non-`nil' if OBJECT is an image instance of
+ type `subwindow'.
- - User Option: bell-volume
- This variable specifies the default volume for sounds, from 0 to
- 100.
+ - Function: nothing-image-instance-p object
+ This function returns non-`nil' if OBJECT is an image instance of
+ type `nothing'.
- - Command: load-default-sounds
- This function loads and installs some sound files as beep-types.
-
- - Command: load-sound-file filename sound-name &optional volume
- This function reads in an audio file and adds it to `sound-alist'.
- The sound file must be in the Sun/NeXT U-LAW format. SOUND-NAME
- should be a symbol, specifying the name of the sound. If VOLUME
- is specified, the sound will be played at that volume; otherwise,
- the value of BELL-VOLUME will be used.
-
- - Function: play-sound sound &optional volume device
- This function plays sound SOUND, which should be a symbol
- mentioned in `sound-alist'. If VOLUME is specified, it overrides
- the value (if any) specified in `sound-alist'. DEVICE specifies
- the device to play the sound on, and defaults to the selected
- device.
-
- - Command: play-sound-file file &optional volume device
- This function plays the named sound file at volume VOLUME, which
- defaults to `bell-volume'. DEVICE specifies the device to play
- the sound on, and defaults to the selected device.
-
-\1f
-File: lispref.info, Node: Hash Tables, Next: Range Tables, Prev: Display, Up: Top
-
-Hash Tables
-***********
-
- - Function: hash-table-p object
- This function returns `t' if OBJECT is a hash table, else `nil'.
-
-* Menu:
-
-* Introduction to Hash Tables:: Hash tables are fast data structures for
- implementing simple tables (i.e. finite
- mappings from keys to values).
-* Working With Hash Tables:: Hash table functions.
-* Weak Hash Tables:: Hash tables with special garbage-collection
- behavior.
+ - Function: widget-image-instance-p object
+ Return `t' if OBJECT is an image instance of type `widget'.
\1f
-File: lispref.info, Node: Introduction to Hash Tables, Next: Working With Hash Tables, Up: Hash Tables
-
-Introduction to Hash Tables
-===========================
-
- A "hash table" is a data structure that provides mappings from
-arbitrary Lisp objects called "keys" to other arbitrary Lisp objects
-called "values". A key/value pair is sometimes called an "entry" in
-the hash table. There are many ways other than hash tables of
-implementing the same sort of mapping, e.g. association lists (*note
-Association Lists::) and property lists (*note Property Lists::), but
-hash tables provide much faster lookup when there are many entries in
-the mapping. Hash tables are an implementation of the abstract data
-type "dictionary", also known as "associative array".
-
- Internally, hash tables are hashed using the "linear probing" hash
-table implementation method. This method hashes each key to a
-particular spot in the hash table, and then scans forward sequentially
-until a blank entry is found. To look up a key, hash to the appropriate
-spot, then search forward for the key until either a key is found or a
-blank entry stops the search. This method is used in preference to
-double hashing because of changes in recent hardware. The penalty for
-non-sequential access to memory has been increasing, and this
-compensates for the problem of clustering that linear probing entails.
-
- When hash tables are created, the user may (but is not required to)
-specify initial properties that influence performance.
-
- Use the `:size' parameter to specify the number of entries that are
-likely to be stored in the hash table, to avoid the overhead of resizing
-the table. But if the pre-allocated space for the entries is never
-used, it is simply wasted and makes XEmacs slower. Excess unused hash
-table entries exact a small continuous performance penalty, since they
-must be scanned at every garbage collection. If the number of entries
-in the hash table is unknown, simply avoid using the `:size' keyword.
-
- Use the `:rehash-size' and `:rehash-threshold' keywords to adjust
-the algorithm for deciding when to rehash the hash table. For
-temporary hash tables that are going to be very heavily used, use a
-small rehash threshold, for example, 0.4 and a large rehash size, for
-example 2.0. For permanent hash tables that will be infrequently used,
-specify a large rehash threshold, for example 0.8.
-
- Hash tables can also be created by the lisp reader using structure
-syntax, for example:
- #s(hash-table size 20 data (foo 1 bar 2))
-
- The structure syntax accepts the same keywords as `make-hash-table'
-(without the `:' character), as well as the additional keyword `data',
-which specifies the initial hash table contents.
-
- - Function: make-hash-table &key `test' `size' `rehash-size'
- `rehash-threshold' `weakness'
- This function returns a new empty hash table object.
-
- Keyword `:test' can be `eq', `eql' (default) or `equal'.
- Comparison between keys is done using this function. If speed is
- important, consider using `eq'. When storing strings in the hash
- table, you will likely need to use `equal'.
-
- Keyword `:size' specifies the number of keys likely to be inserted.
- This number of entries can be inserted without enlarging the hash
- table.
-
- Keyword `:rehash-size' must be a float greater than 1.0, and
- specifies the factor by which to increase the size of the hash
- table when enlarging.
-
- Keyword `:rehash-threshold' must be a float between 0.0 and 1.0,
- and specifies the load factor of the hash table which triggers
- enlarging.
-
- Keyword `:weakness' can be `nil' (default), `t', `key' or `value'.
-
- A weak hash table is one whose pointers do not count as GC
- referents: for any key-value pair in the hash table, if the only
- remaining pointer to either the key or the value is in a weak hash
- table, then the pair will be removed from the hash table, and the
- key and value collected. A non-weak hash table (or any other
- pointer) would prevent the object from being collected.
-
- A key-weak hash table is similar to a fully-weak hash table except
- that a key-value pair will be removed only if the key remains
- unmarked outside of weak hash tables. The pair will remain in the
- hash table if the key is pointed to by something other than a weak
- hash table, even if the value is not.
-
- A value-weak hash table is similar to a fully-weak hash table
- except that a key-value pair will be removed only if the value
- remains unmarked outside of weak hash tables. The pair will
- remain in the hash table if the value is pointed to by something
- other than a weak hash table, even if the key is not.
-
- - Function: copy-hash-table hash-table
- This function returns a new hash table which contains the same
- keys and values as HASH-TABLE. The keys and values will not
- themselves be copied.
-
- - Function: hash-table-count hash-table
- This function returns the number of entries in HASH-TABLE.
-
- - Function: hash-table-test hash-table
- This function returns the test function of HASH-TABLE. This can
- be one of `eq', `eql' or `equal'.
-
- - Function: hash-table-size hash-table
- This function returns the current number of slots in HASH-TABLE,
- whether occupied or not.
-
- - Function: hash-table-rehash-size hash-table
- This function returns the current rehash size of HASH-TABLE. This
- is a float greater than 1.0; the factor by which HASH-TABLE is
- enlarged when the rehash threshold is exceeded.
-
- - Function: hash-table-rehash-threshold hash-table
- This function returns the current rehash threshold of HASH-TABLE.
- This is a float between 0.0 and 1.0; the maximum "load factor" of
- HASH-TABLE, beyond which the HASH-TABLE is enlarged by rehashing.
-
- - Function: hash-table-weakness hash-table
- This function returns the weakness of HASH-TABLE. This can be one
- of `nil', `t', `key' or `value'.
+File: lispref.info, Node: Image Instance Functions, Prev: Image Instance Types, Up: Image Instances
+
+Image Instance Functions
+........................
+
+ - Function: make-image-instance data &optional domain dest-types
+ noerror
+ This function creates a new image-instance object.
+
+ DATA is an image instantiator, which describes the image (*note
+ Image Specifiers::).
+
+ DEST-TYPES should be a list of allowed image instance types that
+ can be generated. The DEST-TYPES list is unordered. If multiple
+ destination types are possible for a given instantiator, the "most
+ natural" type for the instantiator's format is chosen. (For XBM,
+ the most natural types are `mono-pixmap', followed by
+ `color-pixmap', followed by `pointer'. For the other normal image
+ formats, the most natural types are `color-pixmap', followed by
+ `mono-pixmap', followed by `pointer'. For the string and
+ formatted-string formats, the most natural types are `text',
+ followed by `mono-pixmap' (not currently implemented), followed by
+ `color-pixmap' (not currently implemented). For MS Windows
+ resources, the most natural type for pointer resources is
+ `pointer', and for the others it's `color-pixmap'. The other
+ formats can only be instantiated as one type. (If you want to
+ control more specifically the order of the types into which an
+ image is instantiated, just call `make-image-instance' repeatedly
+ until it succeeds, passing less and less preferred destination
+ types each time.
+
+ If DEST-TYPES is omitted, all possible types are allowed.
+
+ DOMAIN specifies the domain to which the image instance will be
+ attached. This domain is termed the "governing domain". The type
+ of the governing domain depends on the image instantiator format.
+ (Although, more correctly, it should probably depend on the image
+ instance type.) For example, pixmap image instances are specific
+ to a device, but widget image instances are specific to a
+ particular XEmacs window because in order to display such a widget
+ when two windows onto the same buffer want to display the widget,
+ two separate underlying widgets must be created. (That's because a
+ widget is actually a child window-system window, and all
+ window-system windows have a unique existence on the screen.) This
+ means that the governing domain for a pixmap image instance will
+ be some device (most likely, the only existing device), whereas
+ the governing domain for a widget image instance will be some
+ XEmacs window.
+
+ If you specify an overly general DOMAIN (e.g. a frame when a
+ window was wanted), an error is signaled. If you specify an overly
+ specific DOMAIN (e.g. a window when a device was wanted), the
+ corresponding general domain is fetched and used instead. For
+ `make-image-instance', it makes no difference whether you specify
+ an overly specific domain or the properly general domain derived
+ from it. However, it does matter when creating an image instance
+ by instantiating a specifier or glyph (e.g. with
+ `glyph-image-instance'), because the more specific domain causes
+ spec lookup to start there and proceed to more general domains. (It
+ would also matter when creating an image instance with an
+ instantiator format of `inherit', but we currently disallow this.
+ #### We should fix this.) n If omitted, DOMAIN defaults to the
+ selected window.
+
+ NOERROR controls what happens when the image cannot be generated.
+ If `nil', an error message is generated. If `t', no messages are
+ generated and this function returns `nil'. If anything else, a
+ warning message is generated and this function returns `nil'.
+
+ - Function: colorize-image-instance image-instance foreground
+ background
+ This function makes the image instance be displayed in the given
+ colors. Image instances come in two varieties: bitmaps, which are
+ 1 bit deep which are rendered in the prevailing foreground and
+ background colors; and pixmaps, which are of arbitrary depth
+ (including 1) and which have the colors explicitly specified.
+ This function converts a bitmap to a pixmap. If the image
+ instance was a pixmap already, nothing is done (and `nil' is
+ returned). Otherwise `t' is returned.
+
+ - Function: image-instance-name image-instance
+ This function returns the name of the given image instance.
+
+ - Function: image-instance-domain image-instance
+ Return the governing domain of the given IMAGE-INSTANCE. The
+ governing domain of an image instance is the domain that the image
+ instance is specific to. It is _NOT_ necessarily the domain that
+ was given to the call to `specifier-instance' that resulted in the
+ creation of this image instance. See `make-image-instance' for
+ more information on governing domains.
+
+ - Function: image-instance-string image-instance
+ This function returns the string of the given image instance.
+ This will only be non-`nil' for text image instances.
+
+ - Function: image-instance-file-name image-instance
+ This function returns the file name from which IMAGE-INSTANCE was
+ read, if known.
+
+ - Function: image-instance-mask-file-name image-instance
+ This function returns the file name from which IMAGE-INSTANCE's
+ mask was read, if known.
+
+ - Function: image-instance-depth image-instance
+ This function returns the depth of the image instance. This is 0
+ for a mono pixmap, or a positive integer for a color pixmap.
+
+ - Function: image-instance-height image-instance
+ This function returns the height of the image instance, in pixels.
+
+ - Function: image-instance-width image-instance
+ This function returns the width of the image instance, in pixels.
+
+ - Function: image-instance-hotspot-x image-instance
+ This function returns the X coordinate of the image instance's
+ hotspot, if known. This is a point relative to the origin of the
+ pixmap. When an image is used as a mouse pointer, the hotspot is
+ the point on the image that sits over the location that the
+ pointer points to. This is, for example, the tip of the arrow or
+ the center of the crosshairs.
+
+ This will always be `nil' for a non-pointer image instance.
+
+ - Function: image-instance-hotspot-y image-instance
+ This function returns the Y coordinate of the image instance's
+ hotspot, if known.
+
+ - Function: image-instance-foreground image-instance
+ This function returns the foreground color of IMAGE-INSTANCE, if
+ applicable. This will be a color instance or `nil'. (It will only
+ be non-`nil' for colorized mono pixmaps and for pointers.)
+
+ - Function: image-instance-background image-instance
+ This function returns the background color of IMAGE-INSTANCE, if
+ applicable. This will be a color instance or `nil'. (It will only
+ be non-`nil' for colorized mono pixmaps and for pointers.)
\1f
-File: lispref.info, Node: Working With Hash Tables, Next: Weak Hash Tables, Prev: Introduction to Hash Tables, Up: Hash Tables
-
-Working With Hash Tables
-========================
-
- - Function: puthash key value hash-table
- This function hashes KEY to VALUE in HASH-TABLE.
-
- - Function: gethash key hash-table &optional default
- This function finds the hash value for KEY in HASH-TABLE. If
- there is no entry for KEY in HASH-TABLE, DEFAULT is returned
- (which in turn defaults to `nil').
-
- - Function: remhash key hash-table
- This function removes the entry for KEY from HASH-TABLE. Does
- nothing if there is no entry for KEY in HASH-TABLE.
+File: lispref.info, Node: Glyph Types, Next: Mouse Pointer, Prev: Images, Up: Glyphs
- - Function: clrhash hash-table
- This function removes all entries from HASH-TABLE, leaving it
- empty.
+Glyph Types
+===========
- - Function: maphash function hash-table
- This function maps FUNCTION over entries in HASH-TABLE, calling it
- with two args, each key and value in the hash table.
+ Each glyph has a particular type, which controls how the glyph's
+image is generated. Each glyph type has a corresponding list of
+allowable image instance types that can be generated. When you call
+`glyph-image-instance' to retrieve the image instance of a glyph,
+XEmacs does the equivalent of calling `make-image-instance' and passing
+in DEST-TYPES the list of allowable image instance types for the
+glyph's type.
- FUNCTION may not modify HASH-TABLE, with the one exception that
- FUNCTION may remhash or puthash the entry currently being
- processed by FUNCTION.
+ * `buffer' glyphs can be used as the begin-glyph or end-glyph of an
+ extent, in the modeline, and in the toolbar. Their image can be
+ instantiated as `nothing', `mono-pixmap', `color-pixmap', `text',
+ and `subwindow'.
-\1f
-File: lispref.info, Node: Weak Hash Tables, Prev: Working With Hash Tables, Up: Hash Tables
-
-Weak Hash Tables
-================
+ * `pointer' glyphs can be used to specify the mouse pointer. Their
+ image can be instantiated as `pointer'.
- A "weak hash table" is a special variety of hash table whose
-elements do not count as GC referents. For any key-value pair in such a
-hash table, if either the key or value (or in some cases, if one
-particular one of the two) has no references to it outside of weak hash
-tables (and similar structures such as weak lists), the pair will be
-removed from the table, and the key and value collected. A non-weak
-hash table (or any other pointer) would prevent the objects from being
-collected.
+ * `icon' glyphs can be used to specify the icon used when a frame is
+ iconified. Their image can be instantiated as `mono-pixmap' and
+ `color-pixmap'.
- Weak hash tables are useful for keeping track of information in a
-non-obtrusive way, for example to implement caching. If the cache
-contains objects such as buffers, markers, image instances, etc. that
-will eventually disappear and get garbage-collected, using a weak hash
-table ensures that these objects are collected normally rather than
-remaining around forever, long past their actual period of use.
-(Otherwise, you'd have to explicitly map over the hash table every so
-often and remove unnecessary elements.)
+ - Function: glyph-type glyph
+ This function returns the type of the given glyph. The return
+ value will be a symbol, one of `buffer', `pointer', or `icon'.
- There are three types of weak hash tables:
+ - Function: valid-glyph-type-p glyph-type
+ Given a GLYPH-TYPE, this function returns non-`nil' if it is valid.
-fully weak hash tables
- In these hash tables, a pair disappears if either the key or the
- value is unreferenced outside of the table.
+ - Function: glyph-type-list
+ This function returns a list of valid glyph types.
-key-weak hash tables
- In these hash tables, a pair disappears if the key is unreferenced
- outside of the table, regardless of how the value is referenced.
+ - Function: buffer-glyph-p object
+ This function returns non-`nil' if OBJECT is a glyph of type
+ `buffer'.
-value-weak hash tables
- In these hash tables, a pair disappears if the value is
- unreferenced outside of the table, regardless of how the key is
- referenced.
+ - Function: icon-glyph-p object
+ This function returns non-`nil' if OBJECT is a glyph of type
+ `icon'.
- Also see *Note Weak Lists::.
-
- Weak hash tables are created by specifying the `:weakness' keyword to
-`make-hash-table'.
+ - Function: pointer-glyph-p object
+ This function returns non-`nil' if OBJECT is a glyph of type
+ `pointer'.
\1f
-File: lispref.info, Node: Range Tables, Next: Databases, Prev: Hash Tables, Up: Top
-
-Range Tables
-************
+File: lispref.info, Node: Mouse Pointer, Next: Redisplay Glyphs, Prev: Glyph Types, Up: Glyphs
- A range table is a table that efficiently associated values with
-ranges of integers.
-
- Note that range tables have a read syntax, like this:
-
- #s(range-table data ((-3 2) foo (5 20) bar))
-
- This maps integers in the range (-3, 2) to `foo' and integers in the
-range (5, 20) to `bar'.
-
- - Function: range-table-p object
- Return non-`nil' if OBJECT is a range table.
-
-* Menu:
+Mouse Pointer
+=============
-* Introduction to Range Tables:: Range tables efficiently map ranges of
- integers to values.
-* Working With Range Tables:: Range table functions.
+ The shape of the mouse pointer when over a particular section of a
+frame is controlled using various glyph variables. Since the image of
+a glyph is a specifier, it can be controlled on a per-buffer,
+per-frame, per-window, or per-device basis.
+
+ You should use `set-glyph-image' to set the following variables,
+_not_ `setq'.
+
+ - Glyph: text-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over
+ text.
+
+ - Glyph: nontext-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over a
+ buffer, but not over text. If unspecified in a particular domain,
+ `text-pointer-glyph' is used.
+
+ - Glyph: modeline-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over
+ the modeline. If unspecified in a particular domain,
+ `nontext-pointer-glyph' is used.
+
+ - Glyph: selection-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over a
+ selectable text region. If unspecified in a particular domain,
+ `text-pointer-glyph' is used.
+
+ - Glyph: gc-pointer-glyph
+ This variable specifies the shape of the mouse pointer when a
+ garbage collection is in progress. If the selected window is on a
+ window system and this glyph specifies a value (i.e. a pointer
+ image instance) in the domain of the selected window, the pointer
+ will be changed as specified during garbage collection.
+ Otherwise, a message will be printed in the echo area, as
+ controlled by `gc-message'.
+
+ - Glyph: busy-pointer-glyph
+ This variable specifies the shape of the mouse pointer when XEmacs
+ is busy. If unspecified in a particular domain, the pointer is
+ not changed when XEmacs is busy.
+
+ - Glyph: menubar-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over
+ the menubar. If unspecified in a particular domain, the
+ window-system-provided default pointer is used.
+
+ - Glyph: scrollbar-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over a
+ scrollbar. If unspecified in a particular domain, the
+ window-system-provided default pointer is used.
+
+ - Glyph: toolbar-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over a
+ toolbar. If unspecified in a particular domain,
+ `nontext-pointer-glyph' is used.
+
+ Internally, these variables are implemented in
+`default-mouse-motion-handler', and thus only take effect when the
+mouse moves. That function calls `set-frame-pointer', which sets the
+current mouse pointer for a frame.
+
+ - Function: set-frame-pointer frame image-instance
+ This function sets the mouse pointer of FRAME to the given pointer
+ image instance. You should not call this function directly. (If
+ you do, the pointer will change again the next time the mouse
+ moves.)
\1f
-File: lispref.info, Node: Introduction to Range Tables, Next: Working With Range Tables, Up: Range Tables
-
-Introduction to Range Tables
-============================
-
- - Function: make-range-table
- Make a new, empty range table.
-
- - Function: copy-range-table old-table
- Make a new range table which contains the same values for the same
- ranges as the given table. The values will not themselves be
- copied.
+File: lispref.info, Node: Redisplay Glyphs, Next: Subwindows, Prev: Mouse Pointer, Up: Glyphs
-\1f
-File: lispref.info, Node: Working With Range Tables, Prev: Introduction to Range Tables, Up: Range Tables
+Redisplay Glyphs
+================
-Working With Range Tables
-=========================
+ - Glyph: truncation-glyph
+ This variable specifies what is displayed at the end of truncated
+ lines.
- - Function: get-range-table pos table &optional default
- This function finds value for position POS in TABLE. If there is
- no corresponding value, return DEFAULT (defaults to `nil').
+ - Glyph: continuation-glyph
+ This variable specifies what is displayed at the end of wrapped
+ lines.
- - Function: put-range-table start end val table
- This function sets the value for range (START, END) to be VAL in
- TABLE.
+ - Glyph: octal-escape-glyph
+ This variable specifies what to prefix character codes displayed
+ in octal with.
- - Function: remove-range-table start end table
- This function removes the value for range (START, END) in TABLE.
+ - Glyph: hscroll-glyph
+ This variable specifies what to display at the beginning of
+ horizontally scrolled lines.
- - Function: clear-range-table table
- This function flushes TABLE.
+ - Glyph: invisible-text-glyph
+ This variable specifies what to use to indicate the presence of
+ invisible text. This is the glyph that is displayed when an
+ ellipsis is called for, according to `selective-display-ellipses'
+ or `buffer-invisibility-spec'). Normally this is three dots
+ ("...").
- - Function: map-range-table function table
- This function maps FUNCTION over entries in TABLE, calling it with
- three args, the beginning and end of the range and the
- corresponding value.
+ - Glyph: control-arrow-glyph
+ This variable specifies what to use as an arrow for control
+ characters.
\1f
-File: lispref.info, Node: Databases, Next: Processes, Prev: Range Tables, Up: Top
+File: lispref.info, Node: Subwindows, Prev: Redisplay Glyphs, Up: Glyphs
-Databases
-*********
+Subwindows
+==========
- - Function: databasep object
- This function returns non-`nil' if OBJECT is a database.
+ Subwindows are not currently implemented.
-* Menu:
-
-* Connecting to a Database::
-* Working With a Database::
-* Other Database Functions::
+ - Function: subwindowp object
+ This function returns non-`nil' if OBJECT is a subwindow.
\1f
-File: lispref.info, Node: Connecting to a Database, Next: Working With a Database, Up: Databases
-
-Connecting to a Database
-========================
+File: lispref.info, Node: Annotations, Next: Display, Prev: Glyphs, Up: Top
- - Function: open-database file &optional type subtype access mode
- This function opens database FILE, using database method TYPE and
- SUBTYPE, with access rights ACCESS and permissions MODE. ACCESS
- can be any combination of `r' `w' and `+', for read, write, and
- creation flags.
-
- TYPE can have the value `'dbm' or `'berkeley_db' to select the
- type of database file to use. (Note: XEmacs may not support both
- of these types.)
-
- For a TYPE of `'dbm', there are no subtypes, so SUBTYPE should by
- `nil'.
+Annotations
+***********
- For a TYPE of `'berkeley_db', the following subtypes are
- available: `'hash', `'btree', and `'recno'. See the manpages for
- the Berkeley DB functions to more information about these types.
+ An "annotation" is a pixmap or string that is not part of a buffer's
+text but is displayed next to a particular location in a buffer.
+Annotations can be displayed intermixed with text, in any whitespace at
+the beginning or end of a line, or in a special area at the left or
+right side of the frame called a "margin", whose size is controllable.
+Annotations are implemented using extents (*note Extents::); but you
+can work with annotations without knowing how extents work.
- - Function: close-database obj
- This function closes database OBJ.
+* Menu:
- - Function: database-live-p obj
- This function returns `t' iff OBJ is an active database, else
- `nil'.
+* Annotation Basics:: Introduction to annotations.
+* Annotation Primitives:: Creating and deleting annotations.
+* Annotation Properties:: Retrieving and changing the characteristics
+ of an annotation.
+* Margin Primitives:: Controlling the size of the margins.
+* Locating Annotations:: Looking for annotations in a buffer.
+* Annotation Hooks:: Hooks called at certain times during an
+ annotation's lifetime.
projects / chise / xemacs-chise.git / blobdiff