Next: Glyph Convenience Functions, Previous: Manipulating Glyphs, Up: Manipulating Glyphs [Contents][Index]
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).
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. The glyph face is an exception; it is a face name (a symbol) or a face object, not a specifier. (The face properties themselves are typically specifiers.) 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:
global
if omitted).
nil
(it does not make sense to explicitly specify a locale in
this case), and specifications will be added as given.
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). In 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.
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.
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
. See Specifiers.
This function removes a property from a glyph. For built-in properties,
this is analogous to remove-specifier
. See remove-specifier-p, for the meaning of the locale, tag-set,
and exact-p arguments.
Next: Glyph Convenience Functions, Previous: Manipulating Glyphs, Up: Manipulating Glyphs [Contents][Index]