[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: |
Fri, 09 Jan 2009 14:18:59 +0000 |
CVSROOT: /sources/emacs
Module name: emacs
Changes by: Chong Yidong <cyd> 09/01/09 14:18:59
Modified files:
doc/lispref : display.texi
Log message:
(Font Lookup): Remove obsolete function
x-font-family-list. x-list-fonts accepts Fontconfig/GTK syntax.
(Low-Level Font): Rename from Fonts, move to end of Faces section.
(Font Selection): Reorder order of variable descriptions. Minor
clarifications.
CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/lispref/display.texi?cvsroot=emacs&r1=1.32&r2=1.33
Patches:
Index: display.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/lispref/display.texi,v
retrieving revision 1.32
retrieving revision 1.33
diff -u -b -r1.32 -r1.33
--- display.texi 8 Jan 2009 20:58:13 -0000 1.32
+++ display.texi 9 Jan 2009 14:18:59 -0000 1.33
@@ -1789,12 +1789,12 @@
* Face Remapping:: Remapping faces to alternative definitions.
* 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
that handle a range of character sets.
+* Low-Level Font:: Lisp representation for character display fonts.
@end menu
@node Defining Faces
@@ -2616,189 +2616,48 @@
usually assign faces to around 400 to 600 characters at each call.
@end defvar
address@hidden Fonts
address@hidden Fonts
address@hidden Font Selection
address@hidden Font Selection
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.
+Mode}).}. Normally, Emacs automatically chooses a font based on the
+faces assigned to that character---specifically, the face attributes
address@hidden:family}, @code{:weight}, @code{:slant}, and @code{:width}
+(@pxref{Face Attributes}). The choice of font also depends on the
+character to be displayed; some fonts can only display a limited set
+of characters. If no available font exactly fits the requirements,
+Emacs looks for the @dfn{closest matching font}. The variables in
+this section control how Emacs makes this selection.
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
address@hidden face-font-family-alternatives
+If a given family is specified but does not exist, this variable
+specifies alternative font families to try. Each element should have
+this form:
address@hidden Font Selection
address@hidden Font Selection
address@hidden
+(@var{family} @address@hidden)
address@hidden example
- 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.
+If @var{family} is specified but not available, Emacs will try the other
+families given in @var{alternate-families}, one by one, until it finds a
+family that does exist.
address@hidden defvar
@defvar face-font-selection-order
-This variable specifies the order of importance of the face attributes
address@hidden:width}, @code{:height}, @code{:weight}, and @code{:slant}. The
-value should be a list containing those four symbols, in order of
-decreasing importance.
+If there is no font that exactly matches all desired face attributes
+(@code{:width}, @code{:height}, @code{:weight}, and @code{:slant}),
+this variable specifies the order in which these attributes should be
+considered when selecting the closest matching font. The value should
+be a list containing those four attribute symbols, in order of
+decreasing importance. The default is @code{(:width :height :weight
+:slant)}.
Font selection first finds the best available matches for the first
-attribute listed; then, among the fonts which are best in that way, it
-searches for the best matches in the second attribute, and so on.
+attribute in the list; then, among the fonts which are best in that
+way, it searches for the best matches in the second attribute, and so
+on.
The attributes @code{:weight} and @code{:width} have symbolic values in
a range centered around @code{normal}. Matches that are more extreme
@@ -2806,11 +2665,6 @@
less extreme (closer to @code{normal}); this is designed to ensure that
non-normal faces contrast with normal ones, whenever possible.
-The default is @code{(:width :height :weight :slant)}, which means first
-find the fonts closest to the specified @code{:width}, then---among the
-fonts with that width---find a best match for the specified font height,
-and so on.
-
One example of a case where this variable makes a difference is when the
default font has no italic equivalent. With the default ordering, the
@code{italic} face will use a non-italic font that is similar to the
@@ -2819,20 +2673,6 @@
quite right.
@end defvar
address@hidden face-font-family-alternatives
-This variable lets you specify alternative font families to try, if a
-given family is specified and doesn't exist. Each element should have
-this form:
-
address@hidden
-(@var{family} @address@hidden)
address@hidden example
-
-If @var{family} is specified but not available, Emacs will try the other
-families given in @var{alternate-families}, one by one, until it finds a
-family that does exist.
address@hidden defvar
-
@defvar face-font-registry-alternatives
This variable lets you specify alternative font registries to try, if a
given registry is specified and doesn't exist. Each element should have
@@ -2848,8 +2688,7 @@
@end defvar
Emacs can make use of scalable fonts, but by default it does not use
-them, since the use of too many or too big scalable fonts can crash
-XFree86 servers.
+them.
@defvar scalable-fonts-allowed
This variable controls which scalable fonts to use. A value of
@@ -2886,25 +2725,25 @@
@node Font Lookup
@subsection Looking Up Fonts
address@hidden x-list-fonts pattern &optional face frame maximum
address@hidden x-list-fonts name &optional reference-face frame maximum
This function returns a list of available font names that match
address@hidden If the optional arguments @var{face} and @var{frame} are
-specified, then the list is limited to fonts that are the same size as
address@hidden currently is on @var{frame}.
-
-The argument @var{pattern} should be a string, perhaps with wildcard
-characters: the @samp{*} character matches any substring, and the
address@hidden character matches any single character. Pattern matching
-of font names ignores case.
-
-If you specify @var{face} and @var{frame}, @var{face} should be a face name
-(a symbol) and @var{frame} should be a frame.
address@hidden @var{name} should be a string containing a font name in
+either the Fontconfig, GTK, or XLFD format (@pxref{Font X,, Font
+Specification Options, emacs, The GNU Emacs Manual}). Within an XLFD
+string, wildcard characters may be used: the @samp{*} character
+matches any substring, and the @samp{?} character matches any single
+character. Case is ignored when matching font names.
+
+If the optional arguments @var{reference-face} and @var{frame} are
+specified, the returned list includes only fonts that are the same
+size as @var{reference-face} (a face name) currently is on the frame
address@hidden
The optional argument @var{maximum} sets a limit on how many fonts to
-return. If this is address@hidden, then the return value is truncated
-after the first @var{maximum} matching fonts. Specifying a small value
-for @var{maximum} can make this function much faster, in cases where
-many fonts match the pattern.
+return. If it is address@hidden, then the return value is truncated
+after the first @var{maximum} matching fonts. Specifying a small
+value for @var{maximum} can make this function much faster, in cases
+where many fonts match the pattern.
@end defun
@defun x-family-fonts &optional family frame
@@ -2918,7 +2757,7 @@
omitted or @code{nil}, it applies to the selected frame's display
(@pxref{Input Focus}).
-The list contains a vector of the following form for each font:
+Each element in the list is a vector of the following form:
@example
address@hidden @var{width} @var{point-size} @var{weight} @var{slant}
@@ -2933,24 +2772,6 @@
@var{full} is the full name of the font, and
@var{registry-and-encoding} is a string giving the registry and
encoding of the font.
-
-The result list is sorted according to the current face font sort order.
address@hidden defun
-
address@hidden x-font-family-list &optional frame
-This function returns a list of the font families available for
address@hidden's display. If @var{frame} is omitted or @code{nil}, it
-describes the selected frame's display (@pxref{Input Focus}).
-
-The value is a list of elements of this form:
-
address@hidden
-(@var{family} . @var{fixed-p})
address@hidden example
-
address@hidden
-Here @var{family} is a font family, and @var{fixed-p} is
address@hidden if fonts of that family are fixed-pitch.
@end defun
@defvar font-list-limit
@@ -3095,6 +2916,156 @@
does that, this function's value may not be accurate.
@end defun
address@hidden Low-Level Font
address@hidden Low-Level Font Representation
+
+ 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
+qobject 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. 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 (a 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 be open. 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, creating a font entity does not
+load the contents of that font into computer memory.
+
address@hidden find-font font-spec &optional frame
+This function returns a font entity that best matches the font spec
address@hidden 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 that specifies the
+maximum length of the returned list. The optional argument
address@hidden, 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 a
+font. For these functions, the @var{font} argument can be a font
+object, a font entity, or a font spec.
+
address@hidden font-get font property
+This function returns the value of the font property @var{property}
+for @var{font}.
+
+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 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. 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 Fringes
@section Fringes
@cindex fringes
- [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, 2009/01/08
- [Emacs-diffs] emacs/doc/lispref display.texi,
Chong Yidong <=
- [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