602 lines
13 KiB
HTML
602 lines
13 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<HTML
|
|
><HEAD
|
|
><TITLE
|
|
>FcPatternFormat</TITLE
|
|
><META
|
|
NAME="GENERATOR"
|
|
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
|
|
REL="HOME"
|
|
HREF="t1.html"><LINK
|
|
REL="UP"
|
|
TITLE="FcPattern"
|
|
HREF="x102.html#AEN255"><LINK
|
|
REL="PREVIOUS"
|
|
TITLE="FcNameUnparse"
|
|
HREF="fcnameunparse.html"></HEAD
|
|
><BODY
|
|
CLASS="REFENTRY"
|
|
BGCOLOR="#FFFFFF"
|
|
TEXT="#000000"
|
|
LINK="#0000FF"
|
|
VLINK="#840084"
|
|
ALINK="#0000FF"
|
|
><DIV
|
|
CLASS="NAVHEADER"
|
|
><TABLE
|
|
SUMMARY="Header navigation table"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
CELLPADDING="0"
|
|
CELLSPACING="0"
|
|
><TR
|
|
><TH
|
|
COLSPAN="3"
|
|
ALIGN="center"
|
|
></TH
|
|
></TR
|
|
><TR
|
|
><TD
|
|
WIDTH="10%"
|
|
ALIGN="left"
|
|
VALIGN="bottom"
|
|
><A
|
|
HREF="fcnameunparse.html"
|
|
ACCESSKEY="P"
|
|
><<< Previous</A
|
|
></TD
|
|
><TD
|
|
WIDTH="80%"
|
|
ALIGN="center"
|
|
VALIGN="bottom"
|
|
></TD
|
|
><TD
|
|
WIDTH="10%"
|
|
ALIGN="right"
|
|
VALIGN="bottom"
|
|
> </TD
|
|
></TR
|
|
></TABLE
|
|
><HR
|
|
ALIGN="LEFT"
|
|
WIDTH="100%"></DIV
|
|
><H1
|
|
><A
|
|
NAME="FCPATTERNFORMAT"
|
|
></A
|
|
>FcPatternFormat</H1
|
|
><DIV
|
|
CLASS="REFNAMEDIV"
|
|
><A
|
|
NAME="AEN930"
|
|
></A
|
|
><H2
|
|
>Name</H2
|
|
>FcPatternFormat -- Format a pattern into a string according to a format specifier</DIV
|
|
><DIV
|
|
CLASS="REFSYNOPSISDIV"
|
|
><A
|
|
NAME="AEN933"
|
|
></A
|
|
><H2
|
|
>Synopsis</H2
|
|
><DIV
|
|
CLASS="FUNCSYNOPSIS"
|
|
><P
|
|
></P
|
|
><A
|
|
NAME="AEN934"
|
|
></A
|
|
><TABLE
|
|
BORDER="0"
|
|
BGCOLOR="#E0E0E0"
|
|
WIDTH="100%"
|
|
><TR
|
|
><TD
|
|
><PRE
|
|
CLASS="FUNCSYNOPSISINFO"
|
|
>#include <fontconfig.h>
|
|
</PRE
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><P
|
|
><CODE
|
|
><CODE
|
|
CLASS="FUNCDEF"
|
|
>FcChar8 * <TT
|
|
CLASS="FUNCTION"
|
|
>FcPatternFormat</TT
|
|
></CODE
|
|
>(FcPattern *<TT
|
|
CLASS="PARAMETER"
|
|
><I
|
|
>pat</I
|
|
></TT
|
|
>, const FcChar8 *<TT
|
|
CLASS="PARAMETER"
|
|
><I
|
|
>format</I
|
|
></TT
|
|
>);</CODE
|
|
></P
|
|
><P
|
|
></P
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="REFSECT1"
|
|
><A
|
|
NAME="AEN943"
|
|
></A
|
|
><H2
|
|
>Description</H2
|
|
><P
|
|
>Converts given pattern <TT
|
|
CLASS="PARAMETER"
|
|
><I
|
|
>pat</I
|
|
></TT
|
|
> into text described by
|
|
the format specifier <TT
|
|
CLASS="PARAMETER"
|
|
><I
|
|
>format</I
|
|
></TT
|
|
>.
|
|
The return value refers to newly allocated memory which should be freed by the
|
|
caller using free(), or NULL if <TT
|
|
CLASS="PARAMETER"
|
|
><I
|
|
>format</I
|
|
></TT
|
|
> is invalid. </P
|
|
><P
|
|
> The format is loosely modelled after printf-style format string.
|
|
The format string is composed of zero or more directives: ordinary
|
|
characters (not "%"), which are copied unchanged to the output stream;
|
|
and tags which are interpreted to construct text from the pattern in a
|
|
variety of ways (explained below).
|
|
Special characters can be escaped
|
|
using backslash. C-string style special characters like \n and \r are
|
|
also supported (this is useful when the format string is not a C string
|
|
literal).
|
|
It is advisable to always escape curly braces that
|
|
are meant to be copied to the output as ordinary characters. </P
|
|
><P
|
|
> Each tags is introduced by the character "%",
|
|
followed by an optional minimum field width,
|
|
followed by tag contents in curly braces ({}).
|
|
If the minimum field width value is provided the tag
|
|
will be expanded and the result padded to achieve the minimum width.
|
|
If the minimum field width is positive, the padding will right-align
|
|
the text. Negative field width will left-align.
|
|
The rest of this section describes various supported tag contents
|
|
and their expansion. </P
|
|
><P
|
|
> A <I
|
|
CLASS="FIRSTTERM"
|
|
>simple</I
|
|
> tag
|
|
is one where the content is an identifier. When simple
|
|
tags are expanded, the named identifier will be looked up in
|
|
<TT
|
|
CLASS="PARAMETER"
|
|
><I
|
|
>pattern</I
|
|
></TT
|
|
> and the resulting list of values returned,
|
|
joined together using comma. For example, to print the family name and style the
|
|
pattern, use the format "%{family} %{style}\n". To extend the family column
|
|
to forty characters use "%-40{family}%{style}\n". </P
|
|
><P
|
|
> Simple tags expand to list of all values for an element. To only choose
|
|
one of the values, one can index using the syntax "%{elt[idx]}". For example,
|
|
to get the first family name only, use "%{family[0]}". </P
|
|
><P
|
|
> If a simple tag ends with "=" and the element is found in the pattern, the
|
|
name of the element followed by "=" will be output before the list of values.
|
|
For example, "%{weight=}" may expand to the string "weight=80". Or to the empty
|
|
string if <TT
|
|
CLASS="PARAMETER"
|
|
><I
|
|
>pattern</I
|
|
></TT
|
|
> does not have weight set. </P
|
|
><P
|
|
> If a simple tag starts with ":" and the element is found in the pattern, ":"
|
|
will be printed first. For example, combining this with the =, the format
|
|
"%{:weight=}" may expand to ":weight=80" or to the empty string
|
|
if <TT
|
|
CLASS="PARAMETER"
|
|
><I
|
|
>pattern</I
|
|
></TT
|
|
> does not have weight set. </P
|
|
><P
|
|
> If a simple tag contains the string ":-", the rest of the the tag contents
|
|
will be used as a default string. The default string is output if the element
|
|
is not found in the pattern. For example, the format
|
|
"%{:weight=:-123}" may expand to ":weight=80" or to the string
|
|
":weight=123" if <TT
|
|
CLASS="PARAMETER"
|
|
><I
|
|
>pattern</I
|
|
></TT
|
|
> does not have weight set. </P
|
|
><P
|
|
> A <I
|
|
CLASS="FIRSTTERM"
|
|
>count</I
|
|
> tag
|
|
is one that starts with the character "#" followed by an element
|
|
name, and expands to the number of values for the element in the pattern.
|
|
For example, "%{#family}" expands to the number of family names
|
|
<TT
|
|
CLASS="PARAMETER"
|
|
><I
|
|
>pattern</I
|
|
></TT
|
|
> has set, which may be zero. </P
|
|
><P
|
|
> A <I
|
|
CLASS="FIRSTTERM"
|
|
>sub-expression</I
|
|
> tag
|
|
is one that expands a sub-expression. The tag contents
|
|
are the sub-expression to expand placed inside another set of curly braces.
|
|
Sub-expression tags are useful for aligning an entire sub-expression, or to
|
|
apply converters (explained later) on an entire sub-expression.
|
|
For example, the format "%40{{%{family} %{style}}}" expands the sub-expression
|
|
to construct the family name followed by the style, then takes the entire
|
|
string and pads it on the left to be at least forty characters. </P
|
|
><P
|
|
> A <I
|
|
CLASS="FIRSTTERM"
|
|
>filter-out</I
|
|
> tag
|
|
is one starting with the character "-" followed by a
|
|
comma-separated list of element names, followed by a sub-expression enclosed
|
|
in curly braces. The sub-expression will be expanded but with a pattern that
|
|
has the listed elements removed from it.
|
|
For example, the format "%{-size,pixelsize{sub-expr}}" will expand "sub-expr"
|
|
with <TT
|
|
CLASS="PARAMETER"
|
|
><I
|
|
>pattern</I
|
|
></TT
|
|
> sans the size and pixelsize elements. </P
|
|
><P
|
|
> A <I
|
|
CLASS="FIRSTTERM"
|
|
>filter-in</I
|
|
> tag
|
|
is one starting with the character "+" followed by a
|
|
comma-separated list of element names, followed by a sub-expression enclosed
|
|
in curly braces. The sub-expression will be expanded but with a pattern that
|
|
only has the listed elements from the surrounding pattern.
|
|
For example, the format "%{+family,familylang{sub-expr}}" will expand "sub-expr"
|
|
with a sub-pattern consisting only the family and family lang elements of
|
|
<TT
|
|
CLASS="PARAMETER"
|
|
><I
|
|
>pattern</I
|
|
></TT
|
|
>. </P
|
|
><P
|
|
> A <I
|
|
CLASS="FIRSTTERM"
|
|
>conditional</I
|
|
> tag
|
|
is one starting with the character "?" followed by a
|
|
comma-separated list of element conditions, followed by two sub-expression
|
|
enclosed in curly braces. An element condition can be an element name,
|
|
in which case it tests whether the element is defined in pattern, or
|
|
the character "!" followed by an element name, in which case the test
|
|
is negated. The conditional passes if all the element conditions pass.
|
|
The tag expands the first sub-expression if the conditional passes, and
|
|
expands the second sub-expression otherwise.
|
|
For example, the format "%{?size,dpi,!pixelsize{pass}{fail}}" will expand
|
|
to "pass" if <TT
|
|
CLASS="PARAMETER"
|
|
><I
|
|
>pattern</I
|
|
></TT
|
|
> has size and dpi elements but
|
|
no pixelsize element, and to "fail" otherwise. </P
|
|
><P
|
|
> An <I
|
|
CLASS="FIRSTTERM"
|
|
>enumerate</I
|
|
> tag
|
|
is one starting with the string "[]" followed by a
|
|
comma-separated list of element names, followed by a sub-expression enclosed
|
|
in curly braces. The list of values for the named elements are walked in
|
|
parallel and the sub-expression expanded each time with a pattern just having
|
|
a single value for those elements, starting from the first value and
|
|
continuing as long as any of those elements has a value.
|
|
For example, the format "%{[]family,familylang{%{family} (%{familylang})\n}}"
|
|
will expand the pattern "%{family} (%{familylang})\n" with a pattern
|
|
having only the first value of the family and familylang elemtns, then expands
|
|
it with the second values, then the third, etc. </P
|
|
><P
|
|
> As a special case, if an enumerate tag has only one element, and that element
|
|
has only one value in the pattern, and that value is of type FcLangSet, the
|
|
individual languages in the language set are enumerated. </P
|
|
><P
|
|
> A <I
|
|
CLASS="FIRSTTERM"
|
|
>builtin</I
|
|
> tag
|
|
is one starting with the character "=" followed by a builtin
|
|
name. The following builtins are defined:
|
|
|
|
<P
|
|
></P
|
|
><DIV
|
|
CLASS="VARIABLELIST"
|
|
><DL
|
|
><DT
|
|
>unparse</DT
|
|
><DD
|
|
><P
|
|
>Expands to the result of calling FcNameUnparse() on the pattern.</P
|
|
></DD
|
|
><DT
|
|
>fcmatch</DT
|
|
><DD
|
|
><P
|
|
>Expands to the output of the default output format of the fc-match
|
|
command on the pattern, without the final newline.</P
|
|
></DD
|
|
><DT
|
|
>fclist</DT
|
|
><DD
|
|
><P
|
|
>Expands to the output of the default output format of the fc-list
|
|
command on the pattern, without the final newline.</P
|
|
></DD
|
|
><DT
|
|
>pkgkit</DT
|
|
><DD
|
|
><P
|
|
>Expands to the list of PackageKit font() tags for the pattern.
|
|
Currently this includes tags for each family name, and each language
|
|
from the pattern, enumerated and sanitized into a set of tags terminated
|
|
by newline. Package management systems can use these tags to tag their
|
|
packages accordingly.</P
|
|
></DD
|
|
></DL
|
|
></DIV
|
|
>
|
|
|
|
For example, the format "%{+family,style{%{=unparse}}}\n" will expand
|
|
to an unparsed name containing only the family and style element values
|
|
from <TT
|
|
CLASS="PARAMETER"
|
|
><I
|
|
>pattern</I
|
|
></TT
|
|
>. </P
|
|
><P
|
|
> The contents of any tag can be followed by a set of zero or more
|
|
<I
|
|
CLASS="FIRSTTERM"
|
|
>converter</I
|
|
>s. A converter is specified by the
|
|
character "|" followed by the converter name and arguments. The
|
|
following converters are defined:
|
|
|
|
<P
|
|
></P
|
|
><DIV
|
|
CLASS="VARIABLELIST"
|
|
><DL
|
|
><DT
|
|
>basename</DT
|
|
><DD
|
|
><P
|
|
>Replaces text with the results of calling FcStrBasename() on it.</P
|
|
></DD
|
|
><DT
|
|
>dirname</DT
|
|
><DD
|
|
><P
|
|
>Replaces text with the results of calling FcStrDirname() on it.</P
|
|
></DD
|
|
><DT
|
|
>downcase</DT
|
|
><DD
|
|
><P
|
|
>Replaces text with the results of calling FcStrDowncase() on it.</P
|
|
></DD
|
|
><DT
|
|
>shescape</DT
|
|
><DD
|
|
><P
|
|
>Escapes text for one level of shell expansion.
|
|
(Escapes single-quotes, also encloses text in single-quotes.)</P
|
|
></DD
|
|
><DT
|
|
>cescape</DT
|
|
><DD
|
|
><P
|
|
>Escapes text such that it can be used as part of a C string literal.
|
|
(Escapes backslash and double-quotes.)</P
|
|
></DD
|
|
><DT
|
|
>xmlescape</DT
|
|
><DD
|
|
><P
|
|
>Escapes text such that it can be used in XML and HTML.
|
|
(Escapes less-than, greater-than, and ampersand.)</P
|
|
></DD
|
|
><DT
|
|
>delete(<TT
|
|
CLASS="PARAMETER"
|
|
><I
|
|
>chars</I
|
|
></TT
|
|
>)</DT
|
|
><DD
|
|
><P
|
|
>Deletes all occurrences of each of the characters in <TT
|
|
CLASS="PARAMETER"
|
|
><I
|
|
>chars</I
|
|
></TT
|
|
>
|
|
from the text.
|
|
FIXME: This converter is not UTF-8 aware yet.</P
|
|
></DD
|
|
><DT
|
|
>escape(<TT
|
|
CLASS="PARAMETER"
|
|
><I
|
|
>chars</I
|
|
></TT
|
|
>)</DT
|
|
><DD
|
|
><P
|
|
>Escapes all occurrences of each of the characters in <TT
|
|
CLASS="PARAMETER"
|
|
><I
|
|
>chars</I
|
|
></TT
|
|
>
|
|
by prepending it by the first character in <TT
|
|
CLASS="PARAMETER"
|
|
><I
|
|
>chars</I
|
|
></TT
|
|
>.
|
|
FIXME: This converter is not UTF-8 aware yet.</P
|
|
></DD
|
|
><DT
|
|
>translate(<TT
|
|
CLASS="PARAMETER"
|
|
><I
|
|
>from</I
|
|
></TT
|
|
>,<TT
|
|
CLASS="PARAMETER"
|
|
><I
|
|
>to</I
|
|
></TT
|
|
>)</DT
|
|
><DD
|
|
><P
|
|
>Translates all occurrences of each of the characters in <TT
|
|
CLASS="PARAMETER"
|
|
><I
|
|
>from</I
|
|
></TT
|
|
>
|
|
by replacing them with their corresponding character in <TT
|
|
CLASS="PARAMETER"
|
|
><I
|
|
>to</I
|
|
></TT
|
|
>.
|
|
If <TT
|
|
CLASS="PARAMETER"
|
|
><I
|
|
>to</I
|
|
></TT
|
|
> has fewer characters than
|
|
<TT
|
|
CLASS="PARAMETER"
|
|
><I
|
|
>from</I
|
|
></TT
|
|
>, it will be extended by repeating its last
|
|
character.
|
|
FIXME: This converter is not UTF-8 aware yet.</P
|
|
></DD
|
|
></DL
|
|
></DIV
|
|
>
|
|
|
|
For example, the format "%{family|downcase|delete( )}\n" will expand
|
|
to the values of the family element in <TT
|
|
CLASS="PARAMETER"
|
|
><I
|
|
>pattern</I
|
|
></TT
|
|
>,
|
|
lower-cased and with spaces removed.
|
|
</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="REFSECT1"
|
|
><A
|
|
NAME="AEN1049"
|
|
></A
|
|
><H2
|
|
>Version</H2
|
|
><P
|
|
>Fontconfig version 2.8.0
|
|
|
|
</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="NAVFOOTER"
|
|
><HR
|
|
ALIGN="LEFT"
|
|
WIDTH="100%"><TABLE
|
|
SUMMARY="Footer navigation table"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
CELLPADDING="0"
|
|
CELLSPACING="0"
|
|
><TR
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="left"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="fcnameunparse.html"
|
|
ACCESSKEY="P"
|
|
><<< Previous</A
|
|
></TD
|
|
><TD
|
|
WIDTH="34%"
|
|
ALIGN="center"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="t1.html"
|
|
ACCESSKEY="H"
|
|
>Home</A
|
|
></TD
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="right"
|
|
VALIGN="top"
|
|
> </TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="left"
|
|
VALIGN="top"
|
|
>FcNameUnparse</TD
|
|
><TD
|
|
WIDTH="34%"
|
|
ALIGN="center"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="x102.html#AEN255"
|
|
ACCESSKEY="U"
|
|
>Up</A
|
|
></TD
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="right"
|
|
VALIGN="top"
|
|
> </TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
></BODY
|
|
></HTML
|
|
> |