Improve documentation of font- and face-related attribute functions
* lisp/faces.el (face-attribute): * src/xfaces.c (Fx_family_fonts): * src/font.c (Ffont_get, Ffont_put): Improve and clarify the doc strings. * doc/lispref/display.texi (Low-Level Font): Document the :type attribute of a font. Improve documentation of 'font-get' and 'font-put'. (Attribute Functions): Add cross-reference to the description of face attributes.
This commit is contained in:
Eli Zaretskii
parent
3723415743
commit
3b6338c8c3
4 changed files with 77 additions and 30 deletions
|
|
@ -2818,7 +2818,8 @@ modifying the attributes of a named face.
|
|||
|
||||
@defun face-attribute face attribute &optional frame inherit
|
||||
This function returns the value of the @var{attribute} attribute for
|
||||
@var{face} on @var{frame}.
|
||||
@var{face} on @var{frame}. @xref{Face Attributes}, for the supported
|
||||
attributes.
|
||||
|
||||
If @var{frame} is omitted or @code{nil}, that means the selected frame
|
||||
(@pxref{Input Focus}). If @var{frame} is @code{t}, this function
|
||||
|
|
@ -2901,7 +2902,8 @@ for all frames. This function is mostly intended for internal usage.
|
|||
@defun set-face-attribute face frame &rest arguments
|
||||
This function sets one or more attributes of @var{face} for
|
||||
@var{frame}. The attributes specified in this way override the face
|
||||
spec(s) belonging to @var{face}.
|
||||
spec(s) belonging to @var{face}. @xref{Face Attributes}, for the
|
||||
supported attributes.
|
||||
|
||||
The extra arguments @var{arguments} specify the attributes to set, and
|
||||
the values for them. They should consist of alternating attribute
|
||||
|
|
@ -3865,12 +3867,22 @@ symbols, or @code{nil} if none is required. If @code{gsub} or
|
|||
@code{gpos} is a list, a @code{nil} element in that list means that
|
||||
the font must not match any of the remaining tag symbols. The
|
||||
@code{gpos} element may be omitted.
|
||||
|
||||
@item :type
|
||||
@cindex font backend
|
||||
The symbol that specifies the @dfn{font backend} used to draw the
|
||||
characters. The possible values depend on the platform and on how
|
||||
Emacs was configured at build time. Typical values include
|
||||
@code{ftcrhb} and @code{xfthb} on X, @code{harfbuzz} on MS-Windows,
|
||||
@code{ns} on GNUstep, etc. It can also be @code{nil} if left
|
||||
unspecified, typically in a font-spec.
|
||||
@end table
|
||||
@end defun
|
||||
|
||||
@defun font-put font-spec property value
|
||||
Set the font property @var{property} in the font-spec @var{font-spec}
|
||||
to @var{value}.
|
||||
to @var{value}. The @var{property} can any of the ones described
|
||||
above.
|
||||
@end defun
|
||||
|
||||
@cindex font entity
|
||||
|
|
@ -3914,12 +3926,28 @@ object, a font entity, or a font spec.
|
|||
|
||||
@defun font-get font property
|
||||
This function returns the value of the font property @var{property}
|
||||
for @var{font}.
|
||||
for @var{font}. The @var{property} can any of the ones that
|
||||
@code{font-spec} supports.
|
||||
|
||||
If @var{font} is a font spec and the font spec does not specify
|
||||
@var{property}, 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.
|
||||
may be a list of scripts supported by the font, and the value of the
|
||||
@code{:otf} property is a cons of the form @w{@code{(@var{gsub}
|
||||
. @var{gpos})}}, where @var{gsub} and @var{gpos} are lists
|
||||
representing OpenType features supported by the font, of the form
|
||||
|
||||
@smallexample
|
||||
((@var{script-tag} (@var{langsys-tag} @var{feature}@dots{}) @dots{}) @dots{})
|
||||
@end smallexample
|
||||
|
||||
@noindent where @var{script-tag}, @var{langsys-tag}, and @var{feature}
|
||||
are symbols representing OpenType layout tags.
|
||||
|
||||
If @var{font} is a font object, the special property
|
||||
@code{:combining-capability} is non-@code{nil} if the font backend of
|
||||
@var{font} supports rendering of combining characters for non-OpenType
|
||||
fonts.
|
||||
@end defun
|
||||
|
||||
@defun font-face-attributes font &optional frame
|
||||
|
|
|
|||
|
|
@ -448,6 +448,10 @@ of FACE on FRAME."
|
|||
|
||||
(defun face-attribute (face attribute &optional frame inherit)
|
||||
"Return the value of FACE's ATTRIBUTE on FRAME.
|
||||
|
||||
See `set-face-attribute' for the list of supported attributes
|
||||
and their meanings and allowed values.
|
||||
|
||||
If the optional argument FRAME is given, report on face FACE in that frame.
|
||||
If FRAME is t, report on the defaults for face FACE (for new frames).
|
||||
If FRAME is omitted or nil, use the selected frame.
|
||||
|
|
|
|||
37
src/font.c
37
src/font.c
|
|
@ -4199,26 +4199,33 @@ merge_font_spec (Lisp_Object from, Lisp_Object to)
|
|||
DEFUN ("font-get", Ffont_get, Sfont_get, 2, 2, 0,
|
||||
doc: /* Return the value of FONT's property KEY.
|
||||
FONT is a font-spec, a font-entity, or a font-object.
|
||||
KEY is any symbol, but these are reserved for specific meanings:
|
||||
:family, :weight, :slant, :width, :foundry, :adstyle, :registry,
|
||||
:size, :name, :script, :otf
|
||||
KEY can be any symbol, but these are reserved for specific meanings:
|
||||
:foundry, :family, :adstyle, :registry, :weight, :slant, :width,
|
||||
:size, :dpi, :spacing, :avgwidth, :script, :lang, :otf
|
||||
See the documentation of `font-spec' for their meanings.
|
||||
In addition, if FONT is a font-entity or a font-object, values of
|
||||
:script and :otf are different from those of a font-spec as below:
|
||||
|
||||
The value of :script may be a list of scripts that are supported by the font.
|
||||
If FONT is a font-entity or a font-object, then values of
|
||||
:script and :otf properties are different from those of a font-spec
|
||||
as below:
|
||||
|
||||
The value of :otf is a cons (GSUB . GPOS) where GSUB and GPOS are lists
|
||||
representing the OpenType features supported by the font by this form:
|
||||
((SCRIPT (LANGSYS FEATURE ...) ...) ...)
|
||||
SCRIPT, LANGSYS, and FEATURE are all symbols representing OpenType
|
||||
Layout tags.
|
||||
The value of :script may be a list of scripts that are supported by
|
||||
the font.
|
||||
|
||||
The value of :otf is a cons (GSUB . GPOS) where GSUB and GPOS are
|
||||
lists representing the OpenType features supported by the font, of
|
||||
this form: ((SCRIPT (LANGSYS FEATURE ...) ...) ...), where
|
||||
SCRIPT, LANGSYS, and FEATURE are all symbols representing OpenType
|
||||
Layout tags. See `otf-script-alist' for the OpenType script tags.
|
||||
|
||||
In addition to the keys listed above, the following keys are reserved
|
||||
for the specific meanings as below:
|
||||
|
||||
The value of :combining-capability is non-nil if the font-backend of
|
||||
FONT supports rendering of combining characters for non-OTF fonts. */)
|
||||
The value of :type is a symbol that identifies the font backend to be
|
||||
used, such as `ftcrhb' or `xfthb' on X , `harfbuzz' or `uniscribe' on
|
||||
MS-Windows, `ns' on Cocoa/GNUstep, etc.
|
||||
|
||||
The value of :combining-capability is non-nil if the font-backend of
|
||||
FONT supports rendering of combining characters for non-OTF fonts. */)
|
||||
(Lisp_Object font, Lisp_Object key)
|
||||
{
|
||||
int idx;
|
||||
|
|
@ -4346,7 +4353,9 @@ accepted by the function `font-spec' (which see), VAL must be what
|
|||
allowed in `font-spec'.
|
||||
|
||||
If FONT is a font-entity or a font-object, KEY must not be the one
|
||||
accepted by `font-spec'. */)
|
||||
accepted by `font-spec'.
|
||||
|
||||
See also `font-get' for KEYs that have special meanings. */)
|
||||
(Lisp_Object font, Lisp_Object prop, Lisp_Object val)
|
||||
{
|
||||
int idx;
|
||||
|
|
|
|||
28
src/xfaces.c
28
src/xfaces.c
|
|
@ -1463,9 +1463,9 @@ enum xlfd_swidth
|
|||
};
|
||||
|
||||
/* Order by which font selection chooses fonts. The default values
|
||||
mean `first, find a best match for the font width, then for the
|
||||
font height, then for weight, then for slant.' This variable can be
|
||||
set via set-face-font-sort-order. */
|
||||
mean "first, find a best match for the font width, then for the
|
||||
font height, then for weight, then for slant." This variable can be
|
||||
set via 'internal-set-font-selection-order'. */
|
||||
|
||||
static int font_sort_order[4];
|
||||
|
||||
|
|
@ -1516,16 +1516,22 @@ If FAMILY is omitted or nil, list all families.
|
|||
Otherwise, FAMILY must be a string, possibly containing wildcards
|
||||
`?' and `*'.
|
||||
If FRAME is omitted or nil, use the selected frame.
|
||||
|
||||
Each element of the result is a vector [FAMILY WIDTH POINT-SIZE WEIGHT
|
||||
SLANT FIXED-P FULL REGISTRY-AND-ENCODING].
|
||||
FAMILY is the font family name. POINT-SIZE is the size of the
|
||||
font in 1/10 pt. WIDTH, WEIGHT, and SLANT are symbols describing the
|
||||
width, weight and slant of the font. These symbols are the same as for
|
||||
face attributes. FIXED-P is non-nil if the font is fixed-pitch.
|
||||
FULL is the full name of the font, and REGISTRY-AND-ENCODING is a string
|
||||
giving the registry and encoding of the font.
|
||||
The result list is sorted according to the current setting of
|
||||
the face font sort order. */)
|
||||
|
||||
FAMILY is the font family name.
|
||||
POINT-SIZE is the size of the font in 1/10 pt.
|
||||
WIDTH, WEIGHT, and SLANT are symbols describing the width, weight
|
||||
and slant of the font. These symbols are the same as for face
|
||||
attributes, see `set-face-attribute'.
|
||||
FIXED-P is non-nil if the font is fixed-pitch.
|
||||
FULL is the full name of the font.
|
||||
REGISTRY-AND-ENCODING is a string giving the registry and encoding of
|
||||
the font.
|
||||
|
||||
The resulting list is sorted according to the current setting of
|
||||
the face font sort order, see `face-font-selection-order'. */)
|
||||
(Lisp_Object family, Lisp_Object frame)
|
||||
{
|
||||
Lisp_Object font_spec, list, *drivers, vec;
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue