diff options
Diffstat (limited to 'doc/fontconfig-devel/fcpatternformat.html')
| -rw-r--r-- | doc/fontconfig-devel/fcpatternformat.html | 539 |
1 files changed, 539 insertions, 0 deletions
diff --git a/doc/fontconfig-devel/fcpatternformat.html b/doc/fontconfig-devel/fcpatternformat.html new file mode 100644 index 0000000..dde8b7d --- /dev/null +++ b/doc/fontconfig-devel/fcpatternformat.html @@ -0,0 +1,539 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//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="index.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" +>Prev</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 +><PRE +CLASS="FUNCSYNOPSISINFO" +>#include <fontconfig.h> + </PRE +><P +><CODE +><CODE +CLASS="FUNCDEF" +>FcChar8 * FcPatternFormat</CODE +>(FcPattern *pat, const FcChar8 *format);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN943" +></A +><H2 +>Description</H2 +><P +>Converts given pattern <CODE +CLASS="PARAMETER" +>pat</CODE +> into text described by +the format specifier <CODE +CLASS="PARAMETER" +>format</CODE +>. +The return value refers to newly allocated memory which should be freed by the +caller using free(), or NULL if <CODE +CLASS="PARAMETER" +>format</CODE +> is invalid. </P +><P +> The format is loosely modeled 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 tag 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 +<CODE +CLASS="PARAMETER" +>pattern</CODE +> and the resulting list of values returned, +joined together using comma. For example, to print the family name and style of 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 <CODE +CLASS="PARAMETER" +>pattern</CODE +> 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 <CODE +CLASS="PARAMETER" +>pattern</CODE +> 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 <CODE +CLASS="PARAMETER" +>pattern</CODE +> 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 +<CODE +CLASS="PARAMETER" +>pattern</CODE +> 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) to the entire sub-expression output. +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 <CODE +CLASS="PARAMETER" +>pattern</CODE +> 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 +<CODE +CLASS="PARAMETER" +>pattern</CODE +>. </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 <CODE +CLASS="PARAMETER" +>pattern</CODE +> 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 elements, 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 +>fccat</DT +><DD +><P +>Expands to the output of the default output format of the fc-cat +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 <CODE +CLASS="PARAMETER" +>pattern</CODE +>. </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(<CODE +CLASS="PARAMETER" +>chars</CODE +>)</DT +><DD +><P +>Deletes all occurrences of each of the characters in <CODE +CLASS="PARAMETER" +>chars</CODE +> +from the text. +FIXME: This converter is not UTF-8 aware yet.</P +></DD +><DT +>escape(<CODE +CLASS="PARAMETER" +>chars</CODE +>)</DT +><DD +><P +>Escapes all occurrences of each of the characters in <CODE +CLASS="PARAMETER" +>chars</CODE +> +by prepending it by the first character in <CODE +CLASS="PARAMETER" +>chars</CODE +>. +FIXME: This converter is not UTF-8 aware yet.</P +></DD +><DT +>translate(<CODE +CLASS="PARAMETER" +>from</CODE +>,<CODE +CLASS="PARAMETER" +>to</CODE +>)</DT +><DD +><P +>Translates all occurrences of each of the characters in <CODE +CLASS="PARAMETER" +>from</CODE +> +by replacing them with their corresponding character in <CODE +CLASS="PARAMETER" +>to</CODE +>. +If <CODE +CLASS="PARAMETER" +>to</CODE +> has fewer characters than +<CODE +CLASS="PARAMETER" +>from</CODE +>, 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 <CODE +CLASS="PARAMETER" +>pattern</CODE +>, +lower-cased and with spaces removed. + </P +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN1053" +></A +><H2 +>Version</H2 +><P +>Fontconfig version 2.9.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" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="index.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 +>
\ No newline at end of file |