[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] emacs/doc/lispref display.texi
From: |
Chong Yidong |
Subject: |
[Emacs-diffs] emacs/doc/lispref display.texi |
Date: |
Thu, 08 Jan 2009 20:58:13 +0000 |
CVSROOT: /sources/emacs
Module name: emacs
Changes by: Chong Yidong <cyd> 09/01/08 20:58:13
Modified files:
doc/lispref : display.texi
Log message:
(Faces): Put Font Selection node after Auto Faces.
(Face Attributes): Don't link to Font Lookup. Document
font-family-list.
(Fonts): New node.
CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/lispref/display.texi?cvsroot=emacs&r1=1.31&r2=1.32
Patches:
Index: display.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/lispref/display.texi,v
retrieving revision 1.31
retrieving revision 1.32
diff -u -b -r1.31 -r1.32
--- display.texi 8 Jan 2009 11:46:04 -0000 1.31
+++ display.texi 8 Jan 2009 20:58:13 -0000 1.32
@@ -1787,9 +1787,10 @@
* Attribute Functions:: Functions to examine and set face attributes.
* Displaying Faces:: How Emacs combines the faces specified for a
character.
* Face Remapping:: Remapping faces to alternative definitions.
-* Font Selection:: Finding the best available font for a face.
* Face Functions:: How to define and examine faces.
* Auto Faces:: Hook for automatic face assignment.
+* Fonts:: Lisp representation for character display fonts.
+* Font Selection:: Finding the best available font for a face.
* Font Lookup:: Looking up the names of available fonts
and information about them.
* Fontsets:: A fontset is a collection of fonts
@@ -1961,14 +1962,16 @@
@table @code
@item :family
-Font family name (@pxref{Font Lookup}), or fontset name
-(@pxref{Fontsets}). If you specify a font family name, the wild-card
-characters @samp{*} and @samp{?} are allowed. @xref{Font Lookup}.
+Font family name or fontset name (a string). If you specify a font
+family name, the wild-card characters @samp{*} and @samp{?} are
+allowed. The function @code{font-family-list}, described below,
+returns a list of available family names. @xref{Fontsets}, for
+information about fontsets.
@item :foundry
-The @dfn{font foundry} in which the font family specified by the
address@hidden:family} attribute is located. The wild-card characters
address@hidden and @samp{?} are allowed. @xref{Font Lookup}.
+The name of the @dfn{font foundry} in which the font family specified
+by the @code{:family} attribute is located (a string). The wild-card
+characters @samp{*} and @samp{?} are allowed.
@item :width
Relative proportionate character width, also known as the character
@@ -2082,19 +2085,20 @@
used automatically to handle certain shades of gray.
@item :font
-The font used to display the face. Its value should be a font object
-(@pxref{Font Lookup}).
+The font used to display the face. Its value should be a font object.
address@hidden Selection}, for information about font objects.
When specifying this attribute using @code{set-face-attribute}
-(@pxref{Attribute Functions}), you may supply a font spec, a font
+(@pxref{Attribute Functions}), you may also supply a font spec, a font
entity, or a string. Emacs converts such values to an appropriate
-font object, and stores that font object internally. If you specify a
-string, the contents of the string should be an XLFD font name
-(@pxref{Font X,, Font Specification Options, emacs, The GNU Emacs
-Manual}); if the XLFD contains wildcards, Emacs chooses the first font
-matching those wildcards. Specifying this attribute also changes the
-values of the @code{:family}, @code{:foundry}, @code{:width},
address@hidden:height}, @code{:weight}, and @code{:slant} attributes.
+font object, and stores that font object as the actual attribute
+value. If you specify a string, the contents of the string should be
+a font name (@pxref{Font X,, Font Specification Options, emacs, The
+GNU Emacs Manual}); if the font name is an XLFD containing wildcards,
+Emacs chooses the first font matching those wildcards. Specifying
+this attribute also changes the values of the @code{:family},
address@hidden:foundry}, @code{:width}, @code{:height}, @code{:weight}, and
address@hidden:slant} attributes.
@item :inherit
The name of a face from which to inherit attributes, or a list of face
@@ -2114,6 +2118,12 @@
setting the @code{:slant} attribute to @code{italic}, and setting it
to @code{nil} is equivalent to setting @code{:slant} to @code{normal}.
address@hidden font-family-list &optional frame
+This function returns a list of available font family names. The
+optional argument @var{frame} specifies the frame on which the text is
+to be displayed; if it is @code{nil}, the selected frame is used.
address@hidden defun
+
@defvar x-bitmap-file-path
This variable specifies a list of directories for searching
for bitmap files, for the @code{:stipple} attribute.
@@ -2512,27 +2522,273 @@
value, which inherits from @var{face}'s global definition.
@end defun
address@hidden Face Functions
address@hidden Functions for Working with Faces
+
+ Here are additional functions for creating and working with faces.
+
address@hidden make-face name
+This function defines a new face named @var{name}, initially with all
+attributes @code{nil}. It does nothing if there is already a face named
address@hidden
address@hidden defun
+
address@hidden face-list
+This function returns a list of all defined face names.
address@hidden defun
+
address@hidden copy-face old-face new-name &optional frame new-frame
+This function defines a face named @var{new-name} as a copy of the existing
+face named @var{old-face}. It creates the face @var{new-name} if that
+doesn't already exist.
+
+If the optional argument @var{frame} is given, this function applies
+only to that frame. Otherwise it applies to each frame individually,
+copying attributes from @var{old-face} in each frame to @var{new-face}
+in the same frame.
+
+If the optional argument @var{new-frame} is given, then @code{copy-face}
+copies the attributes of @var{old-face} in @var{frame} to @var{new-name}
+in @var{new-frame}.
address@hidden defun
+
address@hidden face-id face
+This function returns the @dfn{face number} of face @var{face}. This
+is a number that uniquely identifies a face at low levels within
+Emacs. It is seldom necessary to refer to a face by its face number.
address@hidden defun
+
address@hidden face-documentation face
+This function returns the documentation string of face @var{face}, or
address@hidden if none was specified for it.
address@hidden defun
+
address@hidden face-equal face1 face2 &optional frame
+This returns @code{t} if the faces @var{face1} and @var{face2} have the
+same attributes for display.
address@hidden defun
+
address@hidden face-differs-from-default-p face &optional frame
+This returns address@hidden if the face @var{face} displays
+differently from the default face.
address@hidden defun
+
address@hidden face alias
+A @dfn{face alias} provides an equivalent name for a face. You can
+define a face alias by giving the alias symbol the @code{face-alias}
+property, with a value of the target face name. The following example
+makes @code{modeline} an alias for the @code{mode-line} face.
+
address@hidden
+(put 'modeline 'face-alias 'mode-line)
address@hidden example
+
address@hidden Auto Faces
address@hidden Automatic Face Assignment
address@hidden automatic face assignment
address@hidden faces, automatic choice
+
+ This hook is used for automatically assigning faces to text in the
+buffer. It is part of the implementation of Jit-Lock mode, used by
+Font-Lock.
+
address@hidden fontification-functions
+This variable holds a list of functions that are called by Emacs
+redisplay as needed to assign faces automatically to text in the buffer.
+
+The functions are called in the order listed, with one argument, a
+buffer position @var{pos}. Each function should attempt to assign faces
+to the text in the current buffer starting at @var{pos}.
+
+Each function should record the faces they assign by setting the
address@hidden property. It should also add a address@hidden
address@hidden property for all the text it has assigned faces to.
+That property tells redisplay that faces have been assigned to that text
+already.
+
+It is probably a good idea for each function to do nothing if the
+character after @var{pos} already has a address@hidden @code{fontified}
+property, but this is not required. If one function overrides the
+assignments made by a previous one, the properties as they are
+after the last function finishes are the ones that really matter.
+
+For efficiency, we recommend writing these functions so that they
+usually assign faces to around 400 to 600 characters at each call.
address@hidden defvar
+
address@hidden Fonts
address@hidden Fonts
+
+ Before Emacs can draw a character on a particular display, it must
+select a @dfn{font} for that address@hidden this context, the
+term @dfn{font} has nothing to do with Font Lock (@pxref{Font Lock
+Mode}).}. Normally, Emacs automatically chooses a font for displaying
+a character based on the faces assigned to that
+character---specifically, the face attributes @code{:family},
address@hidden:weight}, @code{:slant}, and @code{:width}. The choice of font
+also depends on the character to be displayed; some fonts can only
+display a limited set of characters. Normally, it is not necessary to
+manipulate fonts directly. In case you need to do so, this section
+explains how.
+
+ In Emacs Lisp, fonts are represented using three different Lisp
+object types: @dfn{font objects}, @dfn{font specs}, and @dfn{font
+entities}.
+
address@hidden fontp object &optional type
+Return @code{t} if @var{object} is a font object, font spec, or font
+entity. Otherwise, return @code{nil}.
+
+The optional argument @var{type}, if address@hidden, determines the
+exact type of Lisp object to check for. In that case, @var{type}
+should be one of @code{font-object}, @code{font-spec}, or
address@hidden
address@hidden defun
+
+ A font object is a Lisp object that represents a font that Emacs has
address@hidden Font objects cannot be modified in Lisp, but they can
+be inspected. For instance, if you call @code{set-face-attribute} and
+pass a font spec, font entity, or font name string as the value of the
address@hidden:font} attribute, Emacs opens the best ``matching'' font that is
+available for display. It then stores the corresponding font object
+as the actual value of the @code{:font} attribute for that face.
+
address@hidden font-at position &optional window string
+Return the font object that is being used to display the character at
+position @var{position} in the window @var{window}. If @var{window}
+is @code{nil}, it defaults to the selected window. If @var{string} is
address@hidden, @var{position} specifies a position in the current buffer;
+otherwise, @var{string} should be a string, and @var{position}
+specifies a position in that string.
address@hidden defun
+
+ A font spec is a Lisp object that contains a set of specifications
+that can be used to find a font. More than one font may match the
+specifications in a font spec.
+
address@hidden font-spec &rest arguments
+Return a new font spec using the specifications in @var{arguments},
+which should come in @address@hidden pairs. The possible
+specifications are as follows:
+
address@hidden @code
address@hidden :name
+The font name string, in either XLFD, Fontconfig, or GTK format.
address@hidden X,, Font Specification Options, emacs, The GNU Emacs
+Manual}.
+
address@hidden :family
address@hidden :foundry
address@hidden :weight
address@hidden :slant
address@hidden :width
+These have the same meanings as the face attributes of the same name.
address@hidden Attributes}.
+
address@hidden :size
+The font size---either a non-negative integer that specifies the pixel
+size, or a floating point number that specifies the point size.
+
address@hidden :adstyle
+Additional typographic style information for the font, such as
address@hidden The value should be a string or a symbol.
+
address@hidden :registry
+The charset registry and encoding of the font, such as
address@hidden The value should be a string or a symbol.
+
address@hidden :script
+The script that the font must support (a symbol).
address@hidden table
address@hidden defun
+
address@hidden font-put font-spec property value
+Set the font property @var{property} in the font-spec @var{font-spec}
+to @var{value}.
address@hidden defun
+
+ A font entity is a reference to a font that need not have been
+opened. Its properties are intermediate between a font object and a
+font spec: like a font object, and unlike a font spec, it refers to a
+single, specific font. Unlike a font object, it can be modified in
+Lisp, and creating a font entity does not load the contents of that
+font into computer memory.
+
address@hidden find-font font-spec &optional frame
+Return a font entity that best matches the font spec @var{font-spec}
+on frame @var{frame}. If @var{frame} is @code{nil}, it defaults to
+the selected frame.
address@hidden defun
+
address@hidden list-fonts font-spec &optional frame num prefer
+This function returns a list of all font entities that match the font
+spec @var{font-spec}.
+
+The optional argument @var{frame}, if address@hidden, specifies the
+frame on which the fonts are to be displayed. The optional argument
address@hidden, if address@hidden, should be an integer; in that case, the
+function returns a list of at most @var{num} font entities. The
+optional argument @var{prefer}, if address@hidden, should be another
+font spec, which is used to control the order of the returned list;
+the returned font entities are sorted in order of decreasing
+``closeness'' to that font spec.
address@hidden defun
+
+ The following functions can be used to obtain information about font
+objects, font entities, and font specs alike:
+
address@hidden font-get font property
+This function returns the value of the font property @var{property}
+for @var{font}, which should be either a font object, font spec, or
+font entity.
+
+If @var{font} is a font spec and the font spec does not specify
address@hidden, the return value is @code{nil}. If @var{font} is a
+font object or font entity, the value for the @var{:script} property
+may be a list of scripts supported by the font.
address@hidden defun
+
address@hidden font-face-attributes font &optional frame
+This function returns a list of face attributes corresponding to
address@hidden , which should be either a font name, a font object, a font
+spec, or a font entity. The optional argument @var{frame} specifies
+the frame on which the font is to be displayed. If it is @code{nil},
+the selected frame is used. The return value has the form
+
address@hidden
+(:family @var{family} :height @var{height} :weight @var{weight}
+ :slant @var{slant} :width @var{width})
address@hidden smallexample
+
+where the values of @var{family}, @var{height}, @var{weight},
address@hidden, and @var{width} are face attribute values. Some of these
+key-attribute pairs may be omitted from the list if they are not
+specified by @var{font}.
address@hidden defun
+
address@hidden font-xlfd-name font &optional fold-wildcards
+This function returns the XLFD (X Logical Font Descriptor), a string,
+matching @var{font}. @xref{Font X,, Font Specification Options,
+emacs, The GNU Emacs Manual}, for information about XLFDs. @var{font}
+should be a font spec, font entity, or font object. If the name is
+too long for an XLFD (which can contain at most 255 characters), the
+function returns @code{nil}.
+
+If the optional argument @var{fold-wildcards} is address@hidden,
+consecutive wildcards in the XLFD are folded into one.
address@hidden defun
+
@node Font Selection
@subsection Font Selection
- @dfn{Selecting a font} means mapping the specified face attributes for
-a character to a font that is available on a particular display. The
-face attributes, as determined by face merging, specify most of the
-font choice, but not all. Part of the choice depends on what character
-it is.
-
- If the face specifies a fontset name, that fontset determines a
-pattern for fonts of the given charset. If the face specifies a font
-family, a font pattern is constructed.
-
- Emacs tries to find an available font for the given face attributes
-and character's registry and encoding. If there is a font that matches
-exactly, it is used, of course. The hard case is when no available font
-exactly fits the specification. Then Emacs looks for one that is
-``close''---one attribute at a time. You can specify the order to
-consider the attributes. In the case where a specified font family is
-not available, you can specify a set of mappings for alternatives to
-try.
+ Emacs tries to find an available font to display each character
+based on the face attributes and the character's registry and
+encoding. If there is a font that matches exactly, it is used, of
+course. The hard case is when no available font exactly fits the
+specification. Then Emacs looks for one that is ``close''---one
+attribute at a time. You can specify the order to consider the
+attributes. In the case where a specified font family is not
+available, you can specify a set of mappings for alternatives to try.
@defvar face-font-selection-order
This variable specifies the order of importance of the face attributes
@@ -2627,101 +2883,6 @@
nominal heights and widths would suggest.
@end defvar
address@hidden Face Functions
address@hidden Functions for Working with Faces
-
- Here are additional functions for creating and working with faces.
-
address@hidden make-face name
-This function defines a new face named @var{name}, initially with all
-attributes @code{nil}. It does nothing if there is already a face named
address@hidden
address@hidden defun
-
address@hidden face-list
-This function returns a list of all defined face names.
address@hidden defun
-
address@hidden copy-face old-face new-name &optional frame new-frame
-This function defines a face named @var{new-name} as a copy of the existing
-face named @var{old-face}. It creates the face @var{new-name} if that
-doesn't already exist.
-
-If the optional argument @var{frame} is given, this function applies
-only to that frame. Otherwise it applies to each frame individually,
-copying attributes from @var{old-face} in each frame to @var{new-face}
-in the same frame.
-
-If the optional argument @var{new-frame} is given, then @code{copy-face}
-copies the attributes of @var{old-face} in @var{frame} to @var{new-name}
-in @var{new-frame}.
address@hidden defun
-
address@hidden face-id face
-This function returns the @dfn{face number} of face @var{face}. This
-is a number that uniquely identifies a face at low levels within
-Emacs. It is seldom necessary to refer to a face by its face number.
address@hidden defun
-
address@hidden face-documentation face
-This function returns the documentation string of face @var{face}, or
address@hidden if none was specified for it.
address@hidden defun
-
address@hidden face-equal face1 face2 &optional frame
-This returns @code{t} if the faces @var{face1} and @var{face2} have the
-same attributes for display.
address@hidden defun
-
address@hidden face-differs-from-default-p face &optional frame
-This returns address@hidden if the face @var{face} displays
-differently from the default face.
address@hidden defun
-
address@hidden face alias
-A @dfn{face alias} provides an equivalent name for a face. You can
-define a face alias by giving the alias symbol the @code{face-alias}
-property, with a value of the target face name. The following example
-makes @code{modeline} an alias for the @code{mode-line} face.
-
address@hidden
-(put 'modeline 'face-alias 'mode-line)
address@hidden example
-
-
address@hidden Auto Faces
address@hidden Automatic Face Assignment
address@hidden automatic face assignment
address@hidden faces, automatic choice
-
- This hook is used for automatically assigning faces to text in the
-buffer. It is part of the implementation of Jit-Lock mode, used by
-Font-Lock.
-
address@hidden fontification-functions
-This variable holds a list of functions that are called by Emacs
-redisplay as needed to assign faces automatically to text in the buffer.
-
-The functions are called in the order listed, with one argument, a
-buffer position @var{pos}. Each function should attempt to assign faces
-to the text in the current buffer starting at @var{pos}.
-
-Each function should record the faces they assign by setting the
address@hidden property. It should also add a address@hidden
address@hidden property for all the text it has assigned faces to.
-That property tells redisplay that faces have been assigned to that text
-already.
-
-It is probably a good idea for each function to do nothing if the
-character after @var{pos} already has a address@hidden @code{fontified}
-property, but this is not required. If one function overrides the
-assignments made by a previous one, the properties as they are
-after the last function finishes are the ones that really matter.
-
-For efficiency, we recommend writing these functions so that they
-usually assign faces to around 400 to 600 characters at each call.
address@hidden defvar
-
@node Font Lookup
@subsection Looking Up Fonts
- [Emacs-diffs] emacs/doc/lispref display.texi, Chong Yidong, 2009/01/07
- [Emacs-diffs] emacs/doc/lispref display.texi, Chong Yidong, 2009/01/08
- [Emacs-diffs] emacs/doc/lispref display.texi,
Chong Yidong <=
- [Emacs-diffs] emacs/doc/lispref display.texi, Chong Yidong, 2009/01/09
- [Emacs-diffs] emacs/doc/lispref display.texi, Chong Yidong, 2009/01/10
- [Emacs-diffs] emacs/doc/lispref display.texi, Chong Yidong, 2009/01/10
- [Emacs-diffs] emacs/doc/lispref display.texi, Chong Yidong, 2009/01/19
- [Emacs-diffs] emacs/doc/lispref display.texi, Eli Zaretskii, 2009/01/24