forked from AuroraMiddleware/gtk
372 lines
9.0 KiB
Plaintext
372 lines
9.0 KiB
Plaintext
<!-- ##### SECTION Title ##### -->
|
|
Fonts
|
|
|
|
<!-- ##### SECTION Short_Description ##### -->
|
|
Loading and manipulating fonts
|
|
|
|
<!-- ##### SECTION Long_Description ##### -->
|
|
<para>
|
|
The #GdkFont data type represents a font for drawing on
|
|
the screen. These functions provide support for
|
|
loading fonts, and also for determining the dimensions
|
|
of characters and strings when drawn with a particular
|
|
font.
|
|
</para>
|
|
|
|
<para>
|
|
Fonts in X are specified by a
|
|
<firstterm>X Logical Font Description</firstterm>.
|
|
The following description is considerably simplified.
|
|
For definitive information about XLFD's see the
|
|
X reference documentation. A X Logical Font Description (XLFD)
|
|
consists of a sequence of fields separated (and surrounded by) '-'
|
|
characters. For example, Adobe Helvetica Bold 12 pt, has the
|
|
full description:
|
|
<informalexample><programlisting>
|
|
"-adobe-helvetica-bold-r-normal--12-120-75-75-p-70-iso8859-1"
|
|
</programlisting></informalexample>
|
|
</para>
|
|
|
|
<para>
|
|
The fields in the XLFD are:
|
|
|
|
<informaltable pgwide="1" frame="none">
|
|
<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
|
|
<tbody>
|
|
|
|
<row>
|
|
<entry>Foundry</entry>
|
|
<entry>the company or organization where the font originated.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>Family</entry>
|
|
<entry>the font family (a group of related font designs).</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>Weight</entry>
|
|
<entry>A name for the font's typographic weight
|
|
For example, 'bold' or 'medium').</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>Slant</entry>
|
|
<entry>The slant of the font. Common values are 'R' for Roman,
|
|
'I' for italoc, and 'O' for oblique.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>Set Width</entry>
|
|
<entry>A name for the width of the font. For example,
|
|
'normal' or 'condensed'.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>Add Style</entry>
|
|
<entry>Additional information to distinguish a font from
|
|
other fonts of the same family.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>Pixel Size</entry>
|
|
<entry>The body size of the font in pixels.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>Point Size</entry>
|
|
<entry>The body size of the font in 10ths of a point.
|
|
(A <firstterm>point</firstterm> is 1/72.27 inch) </entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>Resolution X</entry>
|
|
<entry>The horizontal resolution that the font was designed for.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>Resolution Y</entry>
|
|
<entry>The vertical resolution that the font was designed for .</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>Spacing</entry>
|
|
<entry>The type of spacing for the font - can be 'p' for proportional,
|
|
'm' for monospaced or 'c' for charcell.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>Average Width</entry>
|
|
<entry>The average width of a glyph in the font. For monospaced
|
|
and charcell fonts, all glyphs in the font have this width</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>Charset Registry</entry>
|
|
<entry>The registration authority that owns the encoding for
|
|
the font. Together with the Charset Encoding field, this
|
|
defines the character set for the font.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>Charset Encoding</entry>
|
|
<entry>An identifier for the particular character set encoding.</entry>
|
|
</row>
|
|
|
|
</tbody></tgroup></informaltable>
|
|
</para>
|
|
|
|
<para>
|
|
When specifying a font via a X logical Font Description,
|
|
'*' can be used as a wildcard to match any portion of
|
|
the XLFD. For instance, the above example could
|
|
also be specified as
|
|
<informalexample><programlisting>
|
|
"-*-helvetica-bold-r-normal--*-120-*-*-*-*-iso8859-1"
|
|
</programlisting></informalexample>
|
|
|
|
It is generally a good idea to use wildcards for any
|
|
portion of the XLFD that your program does not care
|
|
about specifically, since that will improve the
|
|
chances of finding a matching font.
|
|
</para>
|
|
|
|
<para>
|
|
A <firstterm>fontset</firstterm> is a list of fonts
|
|
that is used for drawing international text that may
|
|
contain characters from a number of different character
|
|
sets. It is represented by a list of XLFD's.
|
|
</para>
|
|
|
|
<para>
|
|
The font for a given character set is determined by going
|
|
through the list of XLFD's in order. For each one, if
|
|
the registry and and encoding fields match the desired
|
|
character set, then that font is used, otherwise if
|
|
the XLFD contains wild-cards for the registry and encoding
|
|
fields, the registry and encoding for the desired character
|
|
set are substituted in and a lookup is done. If a match is found
|
|
that font is used. Otherwise, processing continues
|
|
on to the next font in the list.
|
|
</para>
|
|
|
|
<para>
|
|
The functions for determining the metrics of a string
|
|
come in several varieties that can take a number
|
|
of forms of string input:
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>8-bit string</term>
|
|
<listitem><para>
|
|
When using functions like gdk_string_width() that
|
|
take a <type>gchar *</type>, if the font is of type
|
|
%GDK_FONT_FONT and is an 8-bit font, then each
|
|
<type>gchar</type> indexes the glyphs in the font directly.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>16-bit string</term>
|
|
<listitem><para>
|
|
For functions taking a <type>gchar *</type>, if the
|
|
font is of type %GDK_FONT_FONT, and is a 16-bit
|
|
font, then the <type>gchar *</type> argument is
|
|
interpreted as a <type>guint16 *</type> cast to
|
|
a <type>gchar *</type> and each <type>guint16</type>
|
|
indexes the glyphs in the font directly.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Multibyte string</term>
|
|
<listitem><para>
|
|
For functions taking a <type>gchar *</type>, if the
|
|
font is of type %GDK_FONT_FONTSET, then the input
|
|
string is interpreted as a <firstterm>multibyte</firstterm>
|
|
encoded according to the current locale. (A multibyte
|
|
string is one in which each character may consist
|
|
of one or more bytes, with different lengths for different
|
|
characters in the string). The string will
|
|
be rendered using one or more different fonts from
|
|
the fontset.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
|
|
<para>
|
|
GDK provides functions to determine a number of different
|
|
measurements (metrics) for a given string. (Need diagram
|
|
here).
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>ascent</term>
|
|
<listitem><para>
|
|
The vertical distance from the origin of the drawing
|
|
opereration to the top of the drawn character.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>descent</term>
|
|
<listitem><para>
|
|
The vertical distance from the origin of the drawing
|
|
opereration to the bottom of the drawn character.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>left bearing</term>
|
|
<listitem><para>
|
|
The horizontal distance from the origin of the drawing
|
|
operation to the left-most part of the drawn character.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>right bearing</term>
|
|
<listitem><para>
|
|
The horizontal distance from the origin of the drawing
|
|
operation to the right-most part of the drawn character.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>width bearing</term>
|
|
<listitem><para>
|
|
The horizontal distance from the origin of the drawing
|
|
operation to the correct origin for drawing another
|
|
string to follow the current one. Depending on the
|
|
font, this could be greater than or less than the
|
|
right bearing.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
|
|
<!-- ##### SECTION See_Also ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### SECTION Stability_Level ##### -->
|
|
|
|
|
|
<!-- ##### SECTION Image ##### -->
|
|
|
|
|
|
<!-- ##### STRUCT GdkFont ##### -->
|
|
<para>
|
|
The <structname>GdkFont</structname> structure represents a font or fontset. It
|
|
contains the following public fields. A new <structname>GdkFont</structname>
|
|
structure is returned by gdk_font_load() or gdk_fontset_load(),
|
|
and is reference counted with gdk_font_ref() and gdk_font_unref()
|
|
</para>
|
|
|
|
@type: a value of type #GdkFontType which indicates
|
|
whether this font is a single font or a fontset.
|
|
@ascent: the maximum distance that the font, when drawn,
|
|
ascends above the baseline.
|
|
@descent: the maximum distance that the font, when drawn,
|
|
descends below the baseline.
|
|
|
|
<!-- ##### ENUM GdkFontType ##### -->
|
|
<para>
|
|
Indicates the type of a font. The possible values
|
|
are currently:
|
|
</para>
|
|
|
|
@GDK_FONT_FONT: the font is a single font.
|
|
@GDK_FONT_FONTSET: the font is a fontset.
|
|
|
|
<!-- ##### FUNCTION gdk_font_load ##### -->
|
|
<para>
|
|
</para>
|
|
|
|
@font_name:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_font_load_for_display ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@display:
|
|
@font_name:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_fontset_load ##### -->
|
|
<para>
|
|
</para>
|
|
|
|
@fontset_name:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_fontset_load_for_display ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@display:
|
|
@fontset_name:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_font_from_description ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@font_desc:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_font_from_description_for_display ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@display:
|
|
@font_desc:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_font_get_display ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@font:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_font_ref ##### -->
|
|
<para>
|
|
</para>
|
|
|
|
@font:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_font_unref ##### -->
|
|
<para>
|
|
</para>
|
|
|
|
@font:
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_font_id ##### -->
|
|
<para>
|
|
</para>
|
|
|
|
@font:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_font_equal ##### -->
|
|
<para>
|
|
</para>
|
|
|
|
@fonta:
|
|
@fontb:
|
|
@Returns:
|