X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Flispref.info-36;h=a8f035c097115352ab6756b415c46b036db76510;hb=b5f26301ee1ad7dbc9ad1c22e5b8564b5161d9ad;hp=33061503ae2c15456c4d1ff14129f1e7991846db;hpb=82da33b61c3e2dd2937db17b75b2838188793053;p=chise%2Fxemacs-chise.git diff --git a/info/lispref.info-36 b/info/lispref.info-36 index 3306150..a8f035c 100644 --- a/info/lispref.info-36 +++ b/info/lispref.info-36 @@ -1,5 +1,5 @@ -This is Info file ../info/lispref.info, produced by Makeinfo version -1.68 from the input file lispref/lispref.texi. +This is ../info/lispref.info, produced by makeinfo version 4.0b from +lispref/lispref.texi. INFO-DIR-SECTION XEmacs Editor START-INFO-DIR-ENTRY @@ -50,1072 +50,982 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  -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. It is unlikely that you will ever want - to do this, but this function is provided for completeness and for - experimentation purposes. *Note Specifiers::. - - 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. Not currently implemented.) - -`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 `'] 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.) - -`subwindow' - (An embedded X window; not currently implemented.) - -`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.) - - 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.) - - 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 - This function returns non-`nil' if FORMAT is a valid image - instantiator format. 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). +File: lispref.info, Node: Merging Faces, Next: Basic Face Functions, Up: Faces + +Merging Faces for Display +------------------------- + + Here are all the ways to specify which face to use for display of +text: + + * With defaults. Each frame has a "default face", which is used for + all text that doesn't somehow specify another face. The face named + `default' applies to the text area, while the faces `left-margin' + and `right-margin' apply to the left and right margin areas. + + * With text properties. A character may have a `face' property; if + so, it's displayed with that face. (Text properties are actually + implemented in terms of extents.) *Note Text Properties::. + + * With extents. An extent may have a `face' property, which applies + to all the text covered by the extent; in addition, if the + `highlight' property is set, the `highlight' property applies when + the mouse moves over the extent or if the extent is explicitly + highlighted. *Note Extents::. + + * With annotations. Annotations that are inserted into a buffer can + specify their own face. (Annotations are actually implemented in + terms of extents.) *Note Annotations::. + + If these various sources together specify more than one face for a +particular character, XEmacs merges the properties of the various faces +specified. Extents, text properties, and annotations all use the same +underlying representation (as extents). When multiple extents cover one +character, an extent with higher priority overrides those with lower +priority. *Note Extents::. If no extent covers a particular character, +the `default' face is used. + + If a background pixmap is specified, it determines what will be +displayed in the background of text characters. If the background +pixmap is actually a pixmap, with its colors specified, those colors are +used; if it is a bitmap, the face's foreground and background colors are +used to color it.  -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. +File: lispref.info, Node: Basic Face Functions, Next: Face Properties, Prev: Merging Faces, Up: Faces + +Basic Functions for Working with Faces +-------------------------------------- + + The properties a face can specify include the font, the foreground +color, the background color, the background pixmap, the underlining, +the display table, and (for TTY devices) whether the text is to be +highlighted, dimmed, blinking, or displayed in reverse video. The face +can also leave these unspecified, causing them to assume the value of +the corresponding property of the `default' face. + + Here are the basic primitives for working with faces. + + - Function: make-face name &optional doc-string temporary + This function defines and returns a new face named NAME, initially + with all properties unspecified. It does nothing if there is + already a face named NAME. Optional argument DOC-STRING specifies + an explanatory string used for descriptive purposes. If optional + argument TEMPORARY is non-`nil', the face will automatically + disappear when there are no more references to it anywhere in text + or Lisp code (otherwise, the face will continue to exist + indefinitely even if it is not used). + + - Function: face-list &optional temporary + This function returns a list of the names of all defined faces. If + TEMPORARY is `nil', only the permanent faces are included. If it + is `t', only the temporary faces are included. If it is any other + non-`nil' value both permanent and temporary are included. + + - Function: facep object + This function returns `t' if OBJECT is a face, else `nil'. + + - Function: copy-face old-face new-name &optional locale tag-set + exact-p how-to-add + This function defines a new face named NEW-NAME which is a copy of + the existing face named OLD-FACE. If there is already a face + named NEW-NAME, then it alters the face to have the same + properties as OLD-FACE. + + LOCALE, TAG-SET, EXACT-P and HOW-TO-ADD let you copy just parts of + the old face rather than the whole face, and are as in + `copy-specifier' (*note Specifiers::).  -File: lispref.info, Node: Image Instances, Prev: Image Instantiator Conversion, Up: Images +File: lispref.info, Node: Face Properties, Next: Face Convenience Functions, Prev: Basic Face Functions, Up: Faces -Image Instances +Face Properties --------------- - Image-instance objects encapsulate the way a particular image -(pixmap, etc.) is displayed on a particular device. + You can examine and modify the properties of an existing face with +the following functions. - 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. + The following symbols have predefined meanings: - - Function: image-instance-p OBJECT - This function returns non-`nil' if OBJECT is an image instance. +`foreground' + The foreground color of the face. -* Menu: +`background' + The background color of the face. -* Image Instance Types:: Each image instances has a particular type. -* Image Instance Functions:: Functions for working with image instances. +`font' + The font used to display text covered by this face. + +`display-table' + The display table of the face. + +`background-pixmap' + The pixmap displayed in the background of the face. Only used by + faces on X devices. + +`underline' + Underline all text covered by this face. + +`highlight' + Highlight all text covered by this face. Only used by faces on TTY + devices. + +`dim' + Dim all text covered by this face. Only used by faces on TTY + devices. + +`blinking' + Blink all text covered by this face. Only used by faces on TTY + devices. + +`reverse' + Reverse the foreground and background colors. Only used by faces + on TTY devices. + +`doc-string' + Description of what the face's normal use is. NOTE: This is not a + specifier, unlike all the other built-in properties, and cannot + contain locale-specific values. + + - Function: set-face-property face property value &optional locale + tag-set how-to-add + This function changes a property of a FACE. + + 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 + font or color) 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 + `face-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 `face-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: remove-face-property face property &optional locale + tag-set exact-p + This function removes a property of a FACE. + + For built-in properties, this is analogous to `remove-specifier'. + For more information, *Note Other Specification Functions::. + + When PROPERTY is not a built-in property, this function will just + remove its value if LOCALE is `nil' or `all'. However, if LOCALE + is other than that, this function will attempt to remove VALUE as + the instantiator for the given LOCALE with `remove-specifier'. If + the value of the property is not a specifier, it will be converted + into a `generic' specifier automatically. + + - Function: face-property face property &optional locale tag-set + exact-p + This function returns FACE's value of the given PROPERTY. + + If LOCALE is omitted, the FACE'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 not or not may 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. strings + specifying a font or color name), 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 + `face-property-instance' actually does all this, and is used to + determine how to display the face. + + - Function: face-property-instance face property &optional domain + default no-fallback + This function returns the instance of FACE'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 will typically be a color-instance, + font-instance, or pixmap-instance object, and you can query it + using the appropriate object-specific functions. For example, you + could use `color-instance-rgb-components' to find out the RGB + (red, green, and blue) components of how the `background' property + of the `highlight' face is 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 color for + the frame that window is on; or perhaps the same color was + specified but the window is on a different X server, and that X + server has different RGB values for the color 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 a 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::.  -File: lispref.info, Node: Image Instance Types, Next: Image Instance Functions, Up: Image Instances +File: lispref.info, Node: Face Convenience Functions, Next: Other Face Display Functions, Prev: Face Properties, Up: Faces + +Face Convenience Functions +-------------------------- + + - Command: set-face-foreground face color &optional locale tag-set + how-to-add + - Command: set-face-background face color &optional locale tag-set + how-to-add + These functions set the foreground (respectively, background) + color of face FACE to COLOR. The argument COLOR should be a + string (the name of a color) or a color object as returned by + `make-color' (*note Colors::). + + - Command: set-face-background-pixmap face pixmap &optional locale + tag-set how-to-add + This function sets the background pixmap of face FACE to PIXMAP. + The argument PIXMAP should be a string (the name of a bitmap or + pixmap file; the directories listed in the variable + `x-bitmap-file-path' will be searched) or a glyph object as + returned by `make-glyph' (*note Glyphs::). The argument may also + be a list of the form `(WIDTH HEIGHT DATA)' where WIDTH and HEIGHT + are the size in pixels, and DATA is a string, containing the raw + bits of the bitmap. + + - Command: set-face-font face font &optional locale tag-set how-to-add + This function sets the font of face FACE. The argument FONT + should be a string or a font object as returned by `make-font' + (*note Fonts::). + + - Command: set-face-underline-p face underline-p &optional locale + tag-set how-to-add + This function sets the underline property of face FACE. + + - Function: face-foreground face &optional locale tag-set exact-p + - Function: face-background face &optional locale tag-set exact-p + These functions return the foreground (respectively, background) + color specifier of face FACE. *Note Colors::. + + - Function: face-background-pixmap face &optional locale tag-set + exact-p + This function return the background-pixmap glyph object of face + FACE. + + - Function: face-font face &optional locale tag-set exact-p + This function returns the font specifier of face FACE. (Note: + This is not the same as the function `face-font' in FSF Emacs.) + + *Note Fonts::. + + - Function: face-font-name face &optional domain + This function returns the name of the font of face FACE, or `nil' + if it is unspecified. This is basically equivalent to `(font-name + (face-font FACE) DOMAIN)' except that it does not cause an error + if FACE's font is `nil'. (This function is named `face-font' in + FSF Emacs.) + + - Function: face-underline-p face &optional locale + This function returns the underline property of face FACE. + + - Function: face-foreground-instance face &optional domain + - Function: face-background-instance face &optional domain + These functions return the foreground (respectively, background) + color specifier of face FACE. *Note Colors::. + + - Function: face-background-pixmap-instance face &optional domain + This function return the background-pixmap glyph object of face + FACE. + + - Function: face-font-instance face &optional domain + This function returns the font specifier of face FACE. *Note + Fonts::. -Image Instance Types -.................... + +File: lispref.info, Node: Other Face Display Functions, Prev: Face Convenience Functions, Up: Faces - 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. +Other Face Display Functions +---------------------------- - The valid image instance types are + - Command: invert-face face &optional locale + Swap the foreground and background colors of face FACE. If the + face doesn't specify both foreground and background, then its + foreground and background are set to the default background and + foreground. -`nothing' - Nothing is displayed. + - Function: face-equal face1 face2 &optional domain + This returns `t' if the faces FACE1 and FACE2 will display in the + same way. DOMAIN is as in `face-property-instance'. -`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. + - Function: face-differs-from-default-p face &optional domain + This returns `t' if the face FACE displays differently from the + default face. DOMAIN is as in `face-property-instance'. -`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). + +File: lispref.info, Node: Fonts, Next: Colors, Prev: Faces, Up: Faces and Window-System Objects -`color-pixmap' - Displayed as a color pixmap. +Fonts +===== -`pointer' - Used as the mouse pointer for a window. + This section describes how to work with font specifier and font +instance objects, which encapsulate fonts in the window system. -`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. +* Menu: - - Function: valid-image-instance-type-p TYPE - This function returns non-`nil' if TYPE is a valid image instance - type. +* Font Specifiers:: Specifying how a font will appear. +* Font Instances:: What a font specifier gets instanced as. +* Font Instance Names:: The name of a font instance. +* Font Instance Size:: The size of a font instance. +* Font Instance Characteristics:: Display characteristics of font instances. +* Font Convenience Functions:: Convenience functions that automatically + instance and retrieve the properties + of a font specifier. - - Function: image-instance-type-list - This function returns a list of the valid image instance types. + +File: lispref.info, Node: Font Specifiers, Next: Font Instances, Up: Fonts - - 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'. +Font Specifiers +--------------- - - Function: text-image-instance-p OBJECT - This function returns non-`nil' if OBJECT is an image instance of - type `text'. + - Function: font-specifier-p object + This predicate returns `t' if OBJECT is a font specifier, and + `nil' otherwise. - - Function: mono-pixmap-image-instance-p OBJECT - This function returns non-`nil' if OBJECT is an image instance of - type `mono-pixmap'. + - Function: make-font-specifier spec-list + Return a new `font' specifier object with the given specification + list. SPEC-LIST can be a list of specifications (each of which is + a cons of a locale and a list of instantiators), a single + instantiator, or a list of instantiators. *Note Specifiers::, for + more information about specifiers. - - Function: color-pixmap-image-instance-p OBJECT - This function returns non-`nil' if OBJECT is an image instance of - type `color-pixmap'. + Valid instantiators for font specifiers are: - - Function: pointer-image-instance-p OBJECT - This function returns non-`nil' if OBJECT is an image instance of - type `pointer'. + * A string naming a font (e.g. under X this might be + "-*-courier-medium-r-*-*-*-140-*-*-*-*-iso8859-*" for a + 14-point upright medium-weight Courier font). - - Function: subwindow-image-instance-p OBJECT - This function returns non-`nil' if OBJECT is an image instance of - type `subwindow'. + * A font instance (use that instance directly if the device + matches, or use the string that generated it). - - Function: nothing-image-instance-p OBJECT - This function returns non-`nil' if OBJECT is an image instance of - type `nothing'. + * A vector of no elements (only on TTY's; this means to set no + font at all, thus using the "natural" font of the terminal's + text). - -File: lispref.info, Node: Image Instance Functions, Prev: Image Instance Types, Up: Image Instances - -Image Instance Functions -........................ - - - Function: make-image-instance DATA &optional DEVICE DEST-TYPES - NO-ERROR - 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). 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. - - NO-ERROR 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-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.) + * A vector of one element (a face to inherit from).  -File: lispref.info, Node: Glyph Types, Next: Mouse Pointer, Prev: Images, Up: Glyphs +File: lispref.info, Node: Font Instances, Next: Font Instance Names, Prev: Font Specifiers, Up: Fonts -Glyph Types -=========== +Font Instances +-------------- - 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. - - * `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'. - - * `pointer' glyphs can be used to specify the mouse pointer. Their - image can be instantiated as `pointer'. + - Function: font-instance-p object + This predicate returns `t' if OBJECT is a font instance, and `nil' + otherwise. - * `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'. + - Function: make-font-instance name &optional device noerror + This function creates a new font-instance object of the specified + name. DEVICE specifies the device this object applies to and + defaults to the selected device. An error is signalled if the + font is unknown or cannot be allocated; however, if NOERROR is + non-`nil', `nil' is simply returned in this case. - - 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'. + The returned object is a normal, first-class lisp object. The way + you "deallocate" the font is the way you deallocate any other lisp + object: you drop all pointers to it and allow it to be garbage + collected. When these objects are GCed, the underlying X data is + deallocated as well. - - Function: valid-glyph-type-p GLYPH-TYPE - Given a GLYPH-TYPE, this function returns non-`nil' if it is valid. + +File: lispref.info, Node: Font Instance Names, Next: Font Instance Size, Prev: Font Instances, Up: Fonts - - Function: glyph-type-list - This function returns a list of valid glyph types. +Font Instance Names +------------------- - - Function: buffer-glyph-p OBJECT - This function returns non-`nil' if OBJECT is a glyph of type - `buffer'. + - Function: list-fonts pattern &optional device + This function returns a list of font names matching the given + pattern. DEVICE specifies which device to search for names, and + defaults to the currently selected device. - - Function: icon-glyph-p OBJECT - This function returns non-`nil' if OBJECT is a glyph of type - `icon'. + - Function: font-instance-name font-instance + This function returns the name used to allocate FONT-INSTANCE. - - Function: pointer-glyph-p OBJECT - This function returns non-`nil' if OBJECT is a glyph of type - `pointer'. + - Function: font-instance-truename font-instance + This function returns the canonical name of the given font + instance. Font names are patterns which may match any number of + fonts, of which the first found is used. This returns an + unambiguous name for that font (but not necessarily its only + unambiguous name).  -File: lispref.info, Node: Mouse Pointer, Next: Redisplay Glyphs, Prev: Glyph Types, Up: Glyphs - -Mouse Pointer -============= - - 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.) +File: lispref.info, Node: Font Instance Size, Next: Font Instance Characteristics, Prev: Font Instance Names, Up: Fonts + +Font Instance Size +------------------ + + - Function: x-font-size font + This function returns the nominal size of the given font. This is + done by parsing its name, so it's likely to lose. X fonts can be + specified (by the user) in either pixels or 10ths of points, and + this returns the first one it finds, so you have to decide which + units the returned value is measured in yourself ... + + - Function: x-find-larger-font font &optional device + This function loads a new, slightly larger version of the given + font (or font name). Returns the font if it succeeds, `nil' + otherwise. If scalable fonts are available, this returns a font + which is 1 point larger. Otherwise, it returns the next larger + version of this font that is defined. + + - Function: x-find-smaller-font font &optional device + This function loads a new, slightly smaller version of the given + font (or font name). Returns the font if it succeeds, `nil' + otherwise. If scalable fonts are available, this returns a font + which is 1 point smaller. Otherwise, it returns the next smaller + version of this font that is defined.  -File: lispref.info, Node: Redisplay Glyphs, Next: Subwindows, Prev: Mouse Pointer, Up: Glyphs +File: lispref.info, Node: Font Instance Characteristics, Next: Font Convenience Functions, Prev: Font Instance Size, Up: Fonts -Redisplay Glyphs -================ +Font Instance Characteristics +----------------------------- - - Glyph: truncation-glyph - This variable specifies what is displayed at the end of truncated - lines. + - Function: font-instance-properties font-instance + This function returns the properties (an alist or `nil') of + FONT-INSTANCE. - - Glyph: continuation-glyph - This variable specifies what is displayed at the end of wrapped - lines. + - Function: x-make-font-bold font &optional device + Given an X font specification, this attempts to make a "bold" font. + If it fails, it returns `nil'. - - Glyph: octal-escape-glyph - This variable specifies what to prefix character codes displayed - in octal with. + - Function: x-make-font-unbold font &optional device + Given an X font specification, this attempts to make a non-bold + font. If it fails, it returns `nil'. - - Glyph: hscroll-glyph - This variable specifies what to display at the beginning of - horizontally scrolled lines. + - Function: x-make-font-italic font &optional device + Given an X font specification, this attempts to make an "italic" + font. If it fails, it returns `nil'. - - 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: x-make-font-unitalic font &optional device + Given an X font specification, this attempts to make a non-italic + font. If it fails, it returns `nil'. - - Glyph: control-arrow-glyph - This variable specifies what to use as an arrow for control - characters. + - Function: x-make-font-bold-italic font &optional device + Given an X font specification, this attempts to make a + "bold-italic" font. If it fails, it returns `nil'.  -File: lispref.info, Node: Subwindows, Prev: Redisplay Glyphs, Up: Glyphs - -Subwindows -========== - - Subwindows are not currently implemented. - - - Function: subwindowp OBJECT - This function returns non-`nil' if OBJECT is a subwindow. +File: lispref.info, Node: Font Convenience Functions, Prev: Font Instance Characteristics, Up: Fonts + +Font Convenience Functions +-------------------------- + + - Function: font-name font &optional domain + This function returns the name of the FONT in the specified + DOMAIN, if any. FONT should be a font specifier object and DOMAIN + is normally a window and defaults to the selected window if + omitted. This is equivalent to using `specifier-instance' and + applying `font-instance-name' to the result. + + - Function: font-truename font &optional domain + This function returns the truename of the FONT in the specified + DOMAIN, if any. FONT should be a font specifier object and DOMAIN + is normally a window and defaults to the selected window if + omitted. This is equivalent to using `specifier-instance' and + applying `font-instance-truename' to the result. + + - Function: font-properties font &optional domain + This function returns the properties of the FONT in the specified + DOMAIN, if any. FONT should be a font specifier object and DOMAIN + is normally a window and defaults to the selected window if + omitted. This is equivalent to using `specifier-instance' and + applying `font-instance-properties' to the result.  -File: lispref.info, Node: Annotations, Next: Display, Prev: Glyphs, Up: Top - -Annotations -*********** +File: lispref.info, Node: Colors, Prev: Fonts, Up: Faces and Window-System Objects - 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. +Colors +====== * Menu: -* 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. +* Color Specifiers:: Specifying how a color will appear. +* Color Instances:: What a color specifier gets instanced as. +* Color Instance Properties:: Properties of color instances. +* Color Convenience Functions:: Convenience functions that automatically + instance and retrieve the properties + of a color specifier.  -File: lispref.info, Node: Annotation Basics, Next: Annotation Primitives, Up: Annotations - -Annotation Basics -================= - - Marginal annotations are notes associated with a particular location -in a buffer. They may be displayed in a margin created on the -left-hand or right-hand side of the frame, in any whitespace at the -beginning or end of a line, or inside of the text itself. Every -annotation may have an associated action to be performed when the -annotation is selected. The term "annotation" is used to refer to an -individual note. The term "margin" is generically used to refer to the -whitespace before the first character on a line or after the last -character on a line. - - Each annotation has the following characteristics: -GLYPH - This is a glyph object and is used as the displayed representation - of the annotation. - -DOWN-GLYPH - If given, this glyph is used as the displayed representation of - the annotation when the mouse is pressed down over the annotation. - -FACE - The face with which to display the glyph. - -SIDE - Which side of the text (left or right) the annotation is displayed - at. - -ACTION - If non-`nil', this field must contain a function capable of being - the first argument to `funcall'. This function is normally - evaluated with a single argument, the value of the DATA field, - each time the annotation is selected. However, if the WITH-EVENT - parameter to `make-annotation' is non-`nil', the function is - called with two arguments. The first argument is the same as - before, and the second argument is the event (a button-up event, - usually) that activated the annotation. - -DATA - Not used internally. This field can contain any E-Lisp object. - It is passed as the first argument to ACTION described above. - -MENU - A menu displayed when the right mouse button is pressed over the - annotation. - - The margin is divided into "outside" and "inside". The outside -margin is space on the left or right side of the frame which normal text -cannot be displayed in. The inside margin is that space between the -leftmost or rightmost point at which text can be displayed and where the -first or last character actually is. - - There are four different "layout types" which affect the exact -location an annotation appears. - -`outside-margin' - The annotation is placed in the outside margin area. as close as - possible to the edge of the frame. If the outside margin is not - wide enough for an annotation to fit, it is not displayed. - -`inside-margin' - The annotation is placed in the inside margin area, as close as - possible to the edge of the frame. If the inside margin is not - wide enough for the annotation to fit, it will be displayed using - any available outside margin space if and only if the specifier - `use-left-overflow' or `use-right-overflow' (depending on which - side the annotation appears in) is non-`nil'. - -`whitespace' - The annotation is placed in the inside margin area, as close as - possible to the first or last non-whitespace character on a line. - If the inside margin is not wide enough for the annotation to fit, - it will be displayed if and only if the specifier - `use-left-overflow' or `use-right-overflow' (depending on which - side the annotation appears in) is non-`nil'. - -`text' - The annotation is placed at the position it is inserted. It will - create enough space for itself inside of the text area. It does - not take up a place in the logical buffer, only in the display of - the buffer. - - The current layout policy is that all `whitespace' annotations are -displayed first. Next, all `inside-margin' annotations are displayed -using any remaining space. Finally as many `outside-margin' -annotations are displayed as possible. The `text' annotations will -always display as they create their own space to display in. +File: lispref.info, Node: Color Specifiers, Next: Color Instances, Up: Colors - -File: lispref.info, Node: Annotation Primitives, Next: Annotation Properties, Prev: Annotation Basics, Up: Annotations - -Annotation Primitives -===================== - - - Function: make-annotation GLYPH &optional POSITION LAYOUT BUFFER - WITH-EVENT D-GLYPH RIGHTP - This function creates a marginal annotation at position POS in - BUFFER. The annotation is displayed using GLYPH, which should be - a glyph object or a string, and is positioned using layout policy - LAYOUT. If POS is `nil', point is used. If LAYOUT is `nil', - `whitespace' is used. If BUFFER is `nil', the current buffer is - used. - - If WITH-EVENT is non-`nil', then when an annotation is activated, - the triggering event is passed as the second arg to the annotation - function. If D-GLYPH is non-`nil' then it is used as the glyph - that will be displayed when button1 is down. If RIGHTP is - non-`nil' then the glyph will be displayed on the right side of - the buffer instead of the left. - - The newly created annotation is returned. - - - Function: delete-annotation ANNOTATION - This function removes ANNOTATION from its buffer. This does not - modify the buffer text. - - - Function: annotationp ANNOTATION - This function returns `t' if ANNOTATION is an annotation, `nil' - otherwise. - - -File: lispref.info, Node: Annotation Properties, Next: Margin Primitives, Prev: Annotation Primitives, Up: Annotations - -Annotation Properties -===================== - - - Function: annotation-glyph ANNOTATION - This function returns the glyph object used to display ANNOTATION. +Color Specifiers +---------------- - - Function: set-annotation-glyph ANNOTATION GLYPH &optional LAYOUT SIDE - This function sets the glyph of ANNOTATION to GLYPH, which should - be a glyph object. If LAYOUT is non-`nil', set the layout policy - of ANNOTATION to LAYOUT. If SIDE is `left' or `right', change the - side of the buffer at which the annotation is displayed to the - given side. The new value of `annotation-glyph' is returned. + - Function: color-specifier-p object + This function returns non-`nil' if OBJECT is a color specifier. - - Function: annotation-down-glyph ANNOTATION - This function returns the glyph used to display ANNOTATION when - the left mouse button is depressed on the annotation. + - Function: make-color-specifier spec-list + Return a new `color' specifier object with the given specification + list. SPEC-LIST can be a list of specifications (each of which is + a cons of a locale and a list of instantiators), a single + instantiator, or a list of instantiators. *Note Specifiers::, for + a detailed description of how specifiers work. - - Function: set-annotation-down-glyph ANNOTATION GLYPH - This function returns the glyph used to display ANNOTATION when - the left mouse button is depressed on the annotation to GLYPH, - which should be a glyph object. + Valid instantiators for color specifiers are: - - Function: annotation-face ANNOTATION - This function returns the face associated with ANNOTATION. + * A string naming a color (e.g. under X this might be + "lightseagreen2" or "#F534B2"). - - Function: set-annotation-face ANNOTATION FACE - This function sets the face associated with ANNOTATION to FACE. + * A color instance (use that instance directly if the device + matches, or use the string that generated it). - - Function: annotation-layout ANNOTATION - This function returns the layout policy of ANNOTATION. + * A vector of no elements (only on TTY's; this means to set no + color at all, thus using the "natural" color of the + terminal's text). - - Function: set-annotation-layout ANNOTATION LAYOUT - This function sets the layout policy of ANNOTATION to LAYOUT. + * A vector of one or two elements: a face to inherit from, and + optionally a symbol naming which property of that face to + inherit, either `foreground' or `background' (if omitted, + defaults to the same property that this color specifier is + used for; if this specifier is not part of a face, the + instantiator would not be valid). - - Function: annotation-side ANNOTATION - This function returns the side of the buffer that ANNOTATION is - displayed on. Return value is a symbol, either `left' or `right'. + - Function: make-face-boolean-specifier spec-list + Return a new `face-boolean' specifier object with the given spec + list. SPEC-LIST can be a list of specifications (each of which is + a cons of a locale and a list of instantiators), a single + instantiator, or a list of instantiators. *Note Specifiers::, for + a detailed description of how specifiers work. - - Function: annotation-data ANNOTATION - This function returns the data associated with ANNOTATION. + Valid instantiators for face-boolean specifiers are - - Function: set-annotation-data ANNOTATION DATA - This function sets the data field of ANNOTATION to DATA. DATA is - returned. + * t or nil. - - Function: annotation-action ANNOTATION - This function returns the action associated with ANNOTATION. + * A vector of two or three elements: a face to inherit from, + optionally a symbol naming the property of that face to + inherit from (if omitted, defaults to the same property that + this face-boolean specifier is used for; if this specifier is + not part of a face, the instantiator would not be valid), and + optionally a value which, if non-`nil', means to invert the + sense of the inherited property. - - Function: set-annotation-action ANNOTATION ACTION - This function sets the action field of ANNOTATION to ACTION. - ACTION is returned.. - - Function: annotation-menu ANNOTATION - This function returns the menu associated with ANNOTATION. + +File: lispref.info, Node: Color Instances, Next: Color Instance Properties, Prev: Color Specifiers, Up: Colors - - Function: set-annotation-menu ANNOTATION MENU - This function sets the menu associated with ANNOTATION to MENU. - This menu will be displayed when the right mouse button is pressed - over the annotation. +Color Instances +--------------- - - Function: annotation-visible ANNOTATION - This function returns `t' if there is enough available space to - display ANNOTATION, `nil' otherwise. + A "color-instance object" is an object describing the way a color +specifier is instanced in a particular domain. Functions such as +`face-background-instance' return a color-instance object. For example, - - Function: annotation-width ANNOTATION - This function returns the width of ANNOTATION in pixels. + (face-background-instance 'default (next-window)) + => # - - Function: hide-annotation ANNOTATION - This function removes ANNOTATION's glyph, making it invisible. + The color-instance object returned describes the way the background +color of the `default' face is displayed in the next window after the +selected one. - - Function: reveal-annotation ANNOTATION - This function restores ANNOTATION's glyph, making it visible. + - Function: color-instance-p object + This function returns non-`nil' if OBJECT is a color-instance.  -File: lispref.info, Node: Locating Annotations, Next: Annotation Hooks, Prev: Margin Primitives, Up: Annotations +File: lispref.info, Node: Color Instance Properties, Next: Color Convenience Functions, Prev: Color Instances, Up: Colors -Locating Annotations -==================== +Color Instance Properties +------------------------- - - Function: annotations-in-region START END BUFFER - This function returns a list of all annotations in BUFFER which - are between START and END inclusively. + - Function: color-instance-name color-instance + This function returns the name used to allocate COLOR-INSTANCE. - - Function: annotations-at &optional POSITION BUFFER - This function returns a list of all annotations at POSITION in - BUFFER. If POSITION is `nil' point is used. If BUFFER is `nil' - the current buffer is used. + - Function: color-instance-rgb-components color-instance + This function returns a three element list containing the red, + green, and blue color components of COLOR-INSTANCE. - - Function: annotation-list &optional BUFFER - This function returns a list of all annotations in BUFFER. If - BUFFER is `nil', the current buffer is used. - - - Function: all-annotations - This function returns a list of all annotations in all buffers in - existence. - - -File: lispref.info, Node: Margin Primitives, Next: Locating Annotations, Prev: Annotation Properties, Up: Annotations - -Margin Primitives -================= - - The margin widths are controllable on a buffer-local, window-local, -frame-local, device-local, or device-type-local basis through the use -of specifiers. *Note Specifiers::. - - - Specifier: left-margin-width - This is a specifier variable controlling the width of the left - outside margin, in characters. Use `set-specifier' to change its - value. - - - Specifier: right-margin-width - This is a specifier variable controlling the width of the right - outside margin, in characters. Use `set-specifier' to change its - value. - - - Specifier: use-left-overflow - If non-`nil', use the left outside margin as extra whitespace when - displaying `whitespace' and `inside-margin' annotations. Defaults - to `nil'. This is a specifier variable; use `set-specifier' to - change its value. - - - Specifier: use-right-overflow - If non-`nil', use the right outside margin as extra whitespace when - displaying `whitespace' and `inside-margin' annotations. Defaults - to `nil'. This is a specifier variable; use `set-specifier' to - change its value. - - - Function: window-left-margin-pixel-width &optional WINDOW - This function returns the width in pixels of the left outside - margin of WINDOW. If WINDOW is `nil', the selected window is - assumed. - - - Function: window-right-margin-pixel-width &optional WINDOW - This function returns the width in pixels of the right outside - margin of WINDOW. If WINDOW is `nil', the selected window is - assumed. - - The margin colors are controlled by the faces `left-margin' and -`right-margin'. These can be set using the X resources -`Emacs.left-margin.background' and `Emacs.left-margin.foreground'; -likewise for the right margin. + (color-instance-rgb-components + (face-background-instance 'default (next-window))) + => (65535 58596 46517)  -File: lispref.info, Node: Annotation Hooks, Prev: Locating Annotations, Up: Annotations +File: lispref.info, Node: Color Convenience Functions, Prev: Color Instance Properties, Up: Colors -Annotation Hooks -================ +Color Convenience Functions +--------------------------- - The following three hooks are provided for use with the marginal -annotations: + - Function: color-name color &optional domain + This function returns the name of the COLOR in the specified + DOMAIN, if any. COLOR should be a color specifier object and + DOMAIN is normally a window and defaults to the selected window if + omitted. This is equivalent to using `specifier-instance' and + applying `color-instance-name' to the result. -`before-delete-annotation-hook' - This hook is called immediately before an annotation is destroyed. - It is passed a single argument, the annotation being destroyed. + - Function: color-rgb-components color &optional domain + This function returns the RGB components of the COLOR in the + specified DOMAIN, if any. COLOR should be a color specifier + object and DOMAIN is normally a window and defaults to the + selected window if omitted. This is equivalent to using + `specifier-instance' and applying `color-instance-rgb-components' + to the result. -`after-delete-annotation-hook' - This normal hook is called immediately after an annotation is - destroyed. - -`make-annotation-hook' - This hook is called immediately after an annotation is created. - It is passed a single argument, the newly created annotation. + (color-rgb-components (face-background 'default (next-window))) + => (65535 58596 46517)  -File: lispref.info, Node: Display, Next: Hash Tables, Prev: Annotations, Up: Top - -Emacs Display -************* - - This chapter describes a number of other features related to the -display that XEmacs presents to the user. +File: lispref.info, Node: Glyphs, Next: Annotations, Prev: Faces and Window-System Objects, Up: Top + +Glyphs +****** + + A "glyph" is an object that is used for pixmaps, widgets and images +of all sorts, as well as for things that "act" like pixmaps, such as +non-textual strings ("annotations") displayed in a buffer or in the +margins. It is used in begin-glyphs and end-glyphs attached to +extents, marginal and textual annotations, overlay arrows +(`overlay-arrow-*' variables), toolbar buttons, mouse pointers, frame +icons, truncation and continuation markers, and the like. (Basically, +any place there is an image or something that acts like an image, there +will be a glyph object representing it.) + + The actual image that is displayed (as opposed to its position or +clipping) is defined by an "image specifier" object contained within +the glyph. The separation between an image specifier object and a +glyph object is made because the glyph includes other properties than +just the actual image: e.g. the face it is displayed in (for text +images), the alignment of the image (when it is in a buffer), etc. + + - Function: glyphp object + This function returns `t' if OBJECT is a glyph. * Menu: -* Refresh Screen:: Clearing the screen and redrawing everything on it. -* Truncation:: Folding or wrapping long text lines. -* The Echo Area:: Where messages are displayed. -* Warnings:: Display of Warnings. -* Invisible Text:: Hiding part of the buffer text. -* Selective Display:: Hiding part of the buffer text (the old way). -* Overlay Arrow:: Display of an arrow to indicate position. -* Temporary Displays:: Displays that go away automatically. -* Blinking:: How XEmacs shows the matching open parenthesis. -* Usual Display:: The usual conventions for displaying nonprinting chars. -* Display Tables:: How to specify other conventions. -* Beeping:: Audible signal to the user. +* Glyph Functions:: Functions for working with glyphs. +* Images:: Graphical images displayed in a frame. +* Glyph Types:: Each glyph has a particular type. +* Mouse Pointer:: Controlling the mouse pointer. +* Redisplay Glyphs:: Glyphs controlling various redisplay functions. +* Subwindows:: Inserting an externally-controlled subwindow + into a buffer.  -File: lispref.info, Node: Refresh Screen, Next: Truncation, Up: Display - -Refreshing the Screen -===================== - - The function `redraw-frame' redisplays the entire contents of a -given frame. *Note Frames::. - - - Function: redraw-frame FRAME - This function clears and redisplays frame FRAME. +File: lispref.info, Node: Glyph Functions, Next: Images, Up: Glyphs - Even more powerful is `redraw-display': +Glyph Functions +=============== - - Command: redraw-display &optional DEVICE - This function redraws all frames on DEVICE marked as having their - image garbled. DEVICE defaults to the selected device. If DEVICE - is `t', all devices will have their frames checked. - - Processing user input takes absolute priority over redisplay. If you -call these functions when input is available, they do nothing -immediately, but a full redisplay does happen eventually--after all the -input has been processed. - - Normally, suspending and resuming XEmacs also refreshes the screen. -Some terminal emulators record separate contents for display-oriented -programs such as XEmacs and for ordinary sequential display. If you are -using such a terminal, you might want to inhibit the redisplay on -resumption. *Note Suspending XEmacs::. +* Menu: - - Variable: no-redraw-on-reenter - This variable controls whether XEmacs redraws the entire screen - after it has been suspended and resumed. Non-`nil' means yes, - `nil' means no. +* Creating Glyphs:: Creating new glyphs. +* Glyph Properties:: Accessing and modifying a glyph's properties. +* Glyph Convenience Functions:: + Convenience functions for accessing particular + properties of a glyph. +* Glyph Dimensions:: Determining the height, width, etc. of a glyph. - The above functions do not actually cause the display to be updated; -rather, they clear out the internal display records that XEmacs -maintains, so that the next time the display is updated it will be -redrawn from scratch. Normally this occurs the next time that -`next-event' or `sit-for' is called; however, a display update will not -occur if there is input pending. *Note Command Loop::. + +File: lispref.info, Node: Creating Glyphs, Next: Glyph Properties, Up: Glyph Functions - - Function: force-cursor-redisplay - This function causes an immediate update of the cursor on the - selected frame. (This function does not exist in FSF Emacs.) +Creating Glyphs +--------------- - -File: lispref.info, Node: Truncation, Next: The Echo Area, Prev: Refresh Screen, Up: Display - -Truncation -========== - - When a line of text extends beyond the right edge of a window, the -line can either be truncated or continued on the next line. When a line -is truncated, this is normally shown with a `\' in the rightmost column -of the window on X displays, and with a `$' on TTY devices. When a -line is continued or "wrapped" onto the next line, this is shown with a -curved arrow in the rightmost column of the window (or with a `\' on -TTY devices). The additional screen lines used to display a long text -line are called "continuation" lines. - - Normally, whenever line truncation is in effect for a particular -window, a horizontal scrollbar is displayed in that window if the -device supports scrollbars. *Note Scrollbars::. - - Note that continuation is different from filling; continuation -happens on the screen only, not in the buffer contents, and it breaks a -line precisely at the right margin, not at a word boundary. *Note -Filling::. - - - User Option: truncate-lines - This buffer-local variable controls how XEmacs displays lines that - extend beyond the right edge of the window. If it is non-`nil', - then XEmacs does not display continuation lines; rather each line - of text occupies exactly one screen line, and a backslash appears - at the edge of any line that extends to or beyond the edge of the - window. The default is `nil'. - - If the variable `truncate-partial-width-windows' is non-`nil', - then truncation is always used for side-by-side windows (within one - frame) regardless of the value of `truncate-lines'. - - - User Option: default-truncate-lines - This variable is the default value for `truncate-lines', for - buffers that do not have local values for it. - - - User Option: truncate-partial-width-windows - This variable controls display of lines that extend beyond the - right edge of the window, in side-by-side windows (*note Splitting - Windows::.). If it is non-`nil', these lines are truncated; - otherwise, `truncate-lines' says what to do with them. - - The backslash and curved arrow used to indicate truncated or -continued lines are only defaults, and can be changed. These images -are actually glyphs (*note Glyphs::.). XEmacs provides a great deal of -flexibility in how glyphs can be controlled. (This differs from FSF -Emacs, which uses display tables to control these images.) - - For details, *Note Redisplay Glyphs::. + - Function: make-glyph &optional spec-list type + This function creates a new glyph object of type TYPE. + + SPEC-LIST is used to initialize the glyph's image. It is + typically an image instantiator (a string or a vector; *Note Image + Specifiers::), but can also be a list of such instantiators (each + one in turn is tried until an image is successfully produced), a + cons of a locale (frame, buffer, etc.) and an instantiator, a list + of such conses, or any other form accepted by + `canonicalize-spec-list'. *Note Specifiers::, for more + information about specifiers. + + TYPE specifies the type of the glyph, which specifies in which + contexts the glyph can be used, and controls the allowable image + types into which the glyph's image can be instantiated. TYPE + should be one of `buffer' (used for glyphs in an extent, the + modeline, the toolbar, or elsewhere in a buffer), `pointer' (used + for the mouse-pointer), or `icon' (used for a frame's icon), and + defaults to `buffer'. *Note Glyph Types::. + + A glyph in XEmacs does *NOT* refer to a single unit of textual + display (the XEmacs term for this is "rune"), but rather is an + object encapsulating a graphical element, such as an image or + widget (an element such as a button or text field; "widget" is the + term for this under X Windows, and it's called a "control" under + MS Windows). This graphical element could appear in a buffer, a + margin, a gutter, or a toolbar, or as a mouse pointer or an icon, + for example. + + Creating a glyph using `make-glyph' does not specify _where_ the + glyph will be used, but it does specify _what_ the glyph will look + like. In particular, SPEC-LIST is used to specify this, and it's + used to initialize the glyph's `image' property, which is an image + specifier. (Note that "image" as used in the context of a glyph's + `image' property or in the terms "image specifier", "image + instantiator", or "image instance" does not refer to what people + normally think of as an image (which in XEmacs is called a + "pixmap"), but to any graphical element--a pixmap, a widget, or + even a block of text, when used in the places that call for a + glyph.) The format of the SPEC-LIST is typically an image + instantiator (a string or a vector; *Note Image Specifiers::), but + can also be a list of such instantiators (each one in turn is + tried until an image is successfully produced), a cons of a locale + (frame, buffer, etc.) and an instantiator, a list of such conses, + or any other form accepted by `canonicalize-spec-list'. *Note + Specifiers::, for more information about specifiers. + + If you're not familiar with specifiers, you should be in order to + understand how glyphs work. The clearest introduction to + specifiers is in the Lispref manual, available under Info. (Choose + Help->Info->Info Contents on the menubar or type C-h i.) You can + also see `make-specifier' for a capsule summary. What's important + to keep in mind is that a specifier lets you set a different value + for any particular buffer, window, frame, device, or console. + This allows for a great deal of flexibility; in particular, only + one global glyph needs to exist for a particular purpose (e.g. the + icon used to represent an iconified frame, the mouse pointer used + over particular areas of a frame, etc.), and in these cases you do + not create your own glyph, but rather modify the existing one. + + As well as using SPEC-LIST to initialize the glyph, you can set + specifications using `set-glyph-image'. Note that, due to a + possibly questionable historical design decision, a glyph itself + is not actually a specifier, but rather is an object containing an + image specifier (as well as other, seldom-used properties). + Therefore, you cannot set or access specifications for the glyph's + image by directly using `set-specifier', `specifier-instance' or + the like on the glyph; instead use them on `(glyph-image GLYPH)' + or use the convenience functions `set-glyph-image', + `glyph-image-instance', and `glyph-image'. + + Once you have created a glyph, you specify where it will be used as + follows: + + * To insert a glyph into a buffer, create an extent in the + buffer and then use `set-extent-begin-glyph' or + `set-extent-end-glyph' to set a glyph to be displayed at the + corresponding edge of the extent. (It is common to create + zero-width extents for this purpose.) + + * To insert a glyph into the left or right margin of a buffer, + first make sure the margin is visible by setting a value for + the specifiers `left-margin-width' or `right-margin-width'. + (Not strictly necessary when using margin glyphs with layout + policy `whitespace'.) Then follow the same procedure above + for inserting a glyph in a buffer, and then set a non-default + layout policy for the glyph using + `set-extent-begin-glyph-layout' or + `set-extent-end-glyph-layout'. Alternatively, use the + high-level annotations API (see `make-annotation'). (In point + of fact, you can also use the annotations API for glyphs in a + buffer, by setting a layout policy of `text'.) + + * To insert a glyph into the modeline, just put the glyph + directly as one of the modeline elements. (Unfortunately you + can't currently put a begin glyph or end glyph on one of the + modeline extents--they're ignored.) + + * To insert a glyph into a toolbar, specify it as part of a + toolbar instantiator (typically set on the specifier + `default-toolbar'). See `default-toolbar' for more + information. (Note that it is standard practice to use a + symbol in place of the glyph list in the toolbar + instantiator; the symbol is evalled to get the glyph list. + This facilitates both creating the toolbar instantiator and + modifying individual glyphs in a toolbar later on. For + example, you can change the way that the Mail toolbar button + looks by modifying the value of the variable + `toolbar-mail-icon' (in general, `toolbar-*-icon') and then + calling `(set-specifier-dirty-flag default-toolbar)'. (#### + Unfortunately this doesn't quite work the way it should; the + change will appear in new frames, but not existing ones. + + * To insert a glyph into a gutter, create or modify a gutter + instantiator (typically set on the specifier + `default-gutter'). Gutter instantiators consist of strings + or lists of strings, so to insert a glyph, create an extent + over the string, and use `set-extent-begin-glyph' or + `set-extent-end-glyph' to set a glyph to be displayed at the + corresponding edge of the extent, just like for glyphs in a + buffer. + + * To use a glyph as the icon for a frame, you do not actually + create a new glyph; rather, you change the specifications for + the existing glyph `frame-icon-glyph'. (Remember that, + because of the specifier nature of glyphs, you can set + different values for any particular buffer or frame.) + + * To use a glyph as the mouse pointer, in general you do not + create a new glyph, but rather you change the specifications + of various existing glyphs, such as `text-pointer-glyph' for + the pointer used over text, `modeline-pointer-glyph' for the + pointer used over the modeline, etc. Do an apropos over + `*-pointer-glyph' to find all of them. (Note also that you + can temporarily set the mouse pointer to some specific shape + by using `set-frame-pointer', which takes an image instance, + as obtained from calling `glyph-image-instance' on a glyph of + type `pointer' - either one of the above-mentioned variables + or one you created yourself. (See below for what it means to + create a glyph of type `pointer'.) This pointer will last + only until the next mouse motion event is processed or + certain other things happen, such as creating or deleting a + window. (In fact, the above-mentioned pointer glyph variables + are implemented as part of the default handler for mouse + motion events. If you want to customize this behavior, take a + look at `mode-motion-hook', or `mouse-motion-handler' if you + really want to get low-level.) + + * To use a glyph to control the shape of miscellaneous + redisplay effects such as the truncation and continuation + markers, set the appropriate existing glyph variables, as for + icons and pointers above. See `continuation-glyph', + `control-arrow-glyph', `hscroll-glyph', + `invisible-text-glyph', `octal-escape-glyph', and + `truncation-glyph'. See also `overlay-arrow-string', an odd + redisplay leftover which can be set to a glyph you created, + and will cause the glyph to be displayed on top of the text + position specified in the marker stored in + `overlay-arrow-position'. + + * To use a glyph in a display table (i.e. to control the + appearance of any individual character), create the + appropriate character glyphs and then set a specification for + the specifier `current-display-table', which controls the + appearance of characters. You can also set an overriding + display table for use with text displayed in a particular + face; see `set-face-display-table' and `make-display-table'. + #### Note: Display tables do not currently support general + Mule characters. They will be overhauled at some point to + support this and to provide other features required under + Mule. + + * To use a glyph as the background pixmap of a face: Note that + the background pixmap of a face is actually an image + specifier - probably the only place in XEmacs where an image + specifier occurs outside of a glyph. Similarly to how the + glyph's image specifier works, you don't create your own + image specifier, but rather add specifications to the + existing one (using `set-face-background-pixmap'). Note that + the image instance that is generated in order to actually + display the background pixmap is of type `mono-pixmap', + meaning that it's a two-color image and the foreground and + background of the image get filled in with the corresponding + colors from the face. + + It is extremely rare that you will ever have to specify a value for + TYPE, which should be one of `buffer' (used for glyphs in an + extent, the modeline, the toolbar, or elsewhere in a buffer), + `pointer' (used for the mouse-pointer), or `icon' (used for a + frame's icon), and defaults to `buffer'. The only cases where it + needs to be specified is when creating icon or pointer glyphs, and + in both cases the necessary glyphs have already been created at + startup and are accessed through the appropriate variables, e.g. + `text-pointer-glyph' (or in general, `*-pointer-glyph') and + `frame-icon-glyph'. *Note Glyph Types::. + + - Function: make-glyph-internal &optional type + This function creates a new, uninitialized glyph of type TYPE. + + - Function: make-pointer-glyph &optional spec-list + Return a new `pointer-glyph' object with the specification list + SPEC-LIST. This function is equivalent to calling `make-glyph' + with a TYPE of `pointer'. + + It is extremely unlikely that you will ever need to create a + pointer glyph. Instead, you probably want to be calling + `set-glyph-image' on an existing glyph, e.g. `text-pointer-glyph'. + + - Function: make-icon-glyph &optional spec-list + Return a new `pointer-glyph' object with the specification list + SPEC-LIST. This function is equivalent to calling `make-glyph' + with a TYPE of `icon'. + + It is extremely unlikely that you will ever need to create a + pointer glyph. Instead, you probably want to be calling + `set-glyph-image' on an existing glyph, e.g. `text-pointer-glyph'.