docs/xml/pangofc-font.xml

   1 <refentry id="PangoFcFont">
   2 <refmeta>
   3 <refentrytitle role="top_of_page" id="PangoFcFont.top_of_page">PangoFcFont</refentrytitle>
   4 <manvolnum>3</manvolnum>
   5 <refmiscinfo>PANGO Library</refmiscinfo>
   6 </refmeta>
   7
   8 <refnamediv>
   9 <refname>PangoFcFont</refname>
  10 <refpurpose>Base font class for Fontconfig-based backends</refpurpose>
  11 </refnamediv>
  12
  13 <refsynopsisdiv id="PangoFcFont.synopsis" role="synopsis">
  14 <title role="synopsis.title">Synopsis</title>
  15
  16 <synopsis>
  17                     <link linkend="PangoFcFont-struct">PangoFcFont</link>;
  18                     <link linkend="PangoFcFontClass">PangoFcFontClass</link>;
  19 #define             <link linkend="PANGO-RENDER-TYPE-FC--CAPS">PANGO_RENDER_TYPE_FC</link>
  20 <link linkend="FT-Face">FT_Face</link>             <link linkend="pango-fc-font-lock-face">pango_fc_font_lock_face</link>             (<link linkend="PangoFcFont">PangoFcFont</link> *font);
  21 <link linkend="void">void</link>                <link linkend="pango-fc-font-unlock-face">pango_fc_font_unlock_face</link>           (<link linkend="PangoFcFont">PangoFcFont</link> *font);
  22 <link linkend="gboolean">gboolean</link>            <link linkend="pango-fc-font-has-char">pango_fc_font_has_char</link>              (<link linkend="PangoFcFont">PangoFcFont</link> *font,
  23                                                          <link linkend="gunichar">gunichar</link> wc);
  24 <link linkend="guint">guint</link>               <link linkend="pango-fc-font-get-glyph">pango_fc_font_get_glyph</link>             (<link linkend="PangoFcFont">PangoFcFont</link> *font,
  25                                                          <link linkend="gunichar">gunichar</link> wc);
  26 <link linkend="PangoGlyph">PangoGlyph</link>          <link linkend="pango-fc-font-get-unknown-glyph">pango_fc_font_get_unknown_glyph</link>     (<link linkend="PangoFcFont">PangoFcFont</link> *font,
  27                                                          <link linkend="gunichar">gunichar</link> wc);
  28 <link linkend="void">void</link>                <link linkend="pango-fc-font-kern-glyphs">pango_fc_font_kern_glyphs</link>           (<link linkend="PangoFcFont">PangoFcFont</link> *font,
  29                                                          <link linkend="PangoGlyphString">PangoGlyphString</link> *glyphs);
  30 </synopsis>
  31 </refsynopsisdiv>
  32
  33 <refsect1 id="PangoFcFont.object-hierarchy" role="object_hierarchy">
  34 <title role="object_hierarchy.title">Object Hierarchy</title>
  35 <synopsis>
  36   <link linkend="GObject">GObject</link>
  37    +----<link linkend="PangoFont">PangoFont</link>
  38          +----PangoFcFont
  39                +----<link linkend="PangoXftFont">PangoXftFont</link>
  40 </synopsis>
  41 </refsect1>
  42
  43
  44
  45
  46
  47 <refsect1 id="PangoFcFont.properties" role="properties">
  48 <title role="properties.title">Properties</title>
  49 <synopsis>
  50   &quot;<link linkend="PangoFcFont--fontmap">fontmap</link>&quot;                  <link linkend="PangoFcFontMap">PangoFcFontMap</link>*       : Read / Write
  51   &quot;<link linkend="PangoFcFont--pattern">pattern</link>&quot;                  <link linkend="gpointer">gpointer</link>              : Read / Write / Construct Only
  52 </synopsis>
  53 </refsect1>
  54
  55
  56
  57 <refsect1 id="PangoFcFont.description" role="desc">
  58 <title role="desc.title">Description</title>
  59 <para>
  60 <link linkend="PangoFcFont"><type>PangoFcFont</type></link> is a base class for font implementation using the
  61 Fontconfig and FreeType libraries. It is used in the
  62 <link linkend="pango-Xft-Fonts-and-Rendering">Xft</link> and
  63 <link linkend="pango-FreeType-Fonts-and-Rendering">FreeType</link>
  64 backends shipped with Pango, but can also be used when creating
  65 new backends. Any backend deriving from this base class will
  66 take advantage of the wide range of shapers implemented using
  67 FreeType that come with Pango.
  68 </para>
  69 </refsect1>
  70
  71 <refsect1 id="PangoFcFont.details" role="details">
  72 <title role="details.title">Details</title>
  73 <refsect2 id="PangoFcFont-struct" role="struct">
  74 <title>PangoFcFont</title>
  75 <indexterm zone="PangoFcFont-struct"><primary sortas="PangoFcFont">PangoFcFont</primary></indexterm><programlisting>typedef struct _PangoFcFont PangoFcFont;</programlisting>
  76 <para>
  77 <link linkend="PangoFcFont"><type>PangoFcFont</type></link> is a base class for font implementations
  78 using the Fontconfig and FreeType libraries and is used in
  79 conjunction with <link linkend="PangoFcFontMap"><type>PangoFcFontMap</type></link>. When deriving from this
  80 class, you need to implement all of its virtual functions
  81 other than <link linkend="shutdown"><function>shutdown()</function></link> along with the <link linkend="get-glyph-extents"><function>get_glyph_extents()</function></link>
  82 virtual function from <link linkend="PangoFont"><type>PangoFont</type></link>.</para>
  83 <para>
  84 </para></refsect2>
  85 <refsect2 id="PangoFcFontClass" role="struct">
  86 <title>PangoFcFontClass</title>
  87 <indexterm zone="PangoFcFontClass"><primary sortas="PangoFcFontClass">PangoFcFontClass</primary></indexterm><programlisting>typedef struct {
  88   FT_Face    (*lock_face)         (PangoFcFont      *font);
  89   void       (*unlock_face)       (PangoFcFont      *font);
  90   gboolean   (*has_char)          (PangoFcFont      *font,
  91                                    gunichar          wc);
  92   guint      (*get_glyph)         (PangoFcFont      *font,
  93                                    gunichar          wc);
  94   PangoGlyph (*get_unknown_glyph) (PangoFcFont      *font,
  95                                    gunichar          wc);
  96   void       (*shutdown)          (PangoFcFont      *font);
  97 } PangoFcFontClass;
  98 </programlisting>
  99 <para>
 100 Class structure for <link linkend="PangoFcFont"><type>PangoFcFont</type></link>.</para>
 101 <para>
 102 </para><variablelist role="struct">
 103 <varlistentry>
 104 <term><structfield>lock_face</structfield>&#160;()</term>
 105 <listitem><simpara> Returns the FT_Face of the font and increases
 106  the reference count for the face by one.
 107 </simpara></listitem>
 108 </varlistentry>
 109 <varlistentry>
 110 <term><structfield>unlock_face</structfield>&#160;()</term>
 111 <listitem><simpara> Decreases the reference count for the
 112  FT_Face of the font by one. When the count is zero,
 113  the <link linkend="PangoFcFont"><type>PangoFcFont</type></link> subclass is allowed to free the
 114  FT_Face.
 115 </simpara></listitem>
 116 </varlistentry>
 117 <varlistentry>
 118 <term><structfield>has_char</structfield>&#160;()</term>
 119 <listitem><simpara> Return <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the the font contains a glyph
 120   corresponding to the specified character.
 121 </simpara></listitem>
 122 </varlistentry>
 123 <varlistentry>
 124 <term><structfield>get_glyph</structfield>&#160;()</term>
 125 <listitem><simpara> Gets the glyph that corresponds to the given
 126   Unicode character.
 127 </simpara></listitem>
 128 </varlistentry>
 129 <varlistentry>
 130 <term><structfield>get_unknown_glyph</structfield>&#160;()</term>
 131 <listitem><simpara> Gets the glyph that should be used to
 132   display an unknown-glyph indication for the specified
 133   Unicode character.
 134   May be <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
 135 </simpara></listitem>
 136 </varlistentry>
 137 <varlistentry>
 138 <term><structfield>shutdown</structfield>&#160;()</term>
 139 <listitem><simpara> Performs any font-specific shutdown code that
 140   needs to be done when pango_fc_font_map_shutdown is called.
 141   May be <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
 142 </simpara></listitem>
 143 </varlistentry>
 144 </variablelist></refsect2>
 145 <refsect2 id="PANGO-RENDER-TYPE-FC--CAPS" role="macro">
 146 <title>PANGO_RENDER_TYPE_FC</title>
 147 <indexterm zone="PANGO-RENDER-TYPE-FC--CAPS"><primary sortas="PANGO_RENDER_TYPE_FC">PANGO_RENDER_TYPE_FC</primary></indexterm><programlisting>#define PANGO_RENDER_TYPE_FC "PangoRenderFc"
 148 </programlisting>
 149 <para>
 150 A string constant used to identify shape engines that work
 151 with the fontconfig based backends. See the <parameter>engine_type</parameter> field
 152 of <link linkend="PangoEngineInfo"><type>PangoEngineInfo</type></link>.</para>
 153 <para>
 154 </para></refsect2>
 155 <refsect2 id="pango-fc-font-lock-face" role="function" condition="since:1.4">
 156 <title>pango_fc_font_lock_face ()</title>
 157 <indexterm zone="pango-fc-font-lock-face" role="1.4"><primary sortas="pango_fc_font_lock_face">pango_fc_font_lock_face</primary></indexterm><programlisting><link linkend="FT-Face">FT_Face</link>             pango_fc_font_lock_face             (<link linkend="PangoFcFont">PangoFcFont</link> *font);</programlisting>
 158 <para>
 159 Gets the FreeType <type>FT_Face</type> associated with a font,
 160 This face will be kept around until you call
 161 <link linkend="pango-fc-font-unlock-face"><function>pango_fc_font_unlock_face()</function></link>.</para>
 162 <para>
 163 </para><variablelist role="params">
 164 <varlistentry><term><parameter>font</parameter>&#160;:</term>
 165 <listitem><simpara> a <link linkend="PangoFcFont"><type>PangoFcFont</type></link>.
 166 </simpara></listitem></varlistentry>
 167 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the FreeType <type>FT_Face</type> associated with <parameter>font</parameter>.
 168
 169 </simpara></listitem></varlistentry>
 170 </variablelist><para role="since">Since 1.4</para></refsect2>
 171 <refsect2 id="pango-fc-font-unlock-face" role="function" condition="since:1.4">
 172 <title>pango_fc_font_unlock_face ()</title>
 173 <indexterm zone="pango-fc-font-unlock-face" role="1.4"><primary sortas="pango_fc_font_unlock_face">pango_fc_font_unlock_face</primary></indexterm><programlisting><link linkend="void">void</link>                pango_fc_font_unlock_face           (<link linkend="PangoFcFont">PangoFcFont</link> *font);</programlisting>
 174 <para>
 175 Releases a font previously obtained with
 176 <link linkend="pango-fc-font-lock-face"><function>pango_fc_font_lock_face()</function></link>.</para>
 177 <para>
 178 </para><variablelist role="params">
 179 <varlistentry><term><parameter>font</parameter>&#160;:</term>
 180 <listitem><simpara> a <link linkend="PangoFcFont"><type>PangoFcFont</type></link>.
 181 </simpara></listitem></varlistentry>
 182 </variablelist><para role="since">Since 1.4</para></refsect2>
 183 <refsect2 id="pango-fc-font-has-char" role="function" condition="since:1.4">
 184 <title>pango_fc_font_has_char ()</title>
 185 <indexterm zone="pango-fc-font-has-char" role="1.4"><primary sortas="pango_fc_font_has_char">pango_fc_font_has_char</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            pango_fc_font_has_char              (<link linkend="PangoFcFont">PangoFcFont</link> *font,
 186                                                          <link linkend="gunichar">gunichar</link> wc);</programlisting>
 187 <para>
 188 Determines whether <parameter>font</parameter> has a glyph for the codepoint <parameter>wc</parameter>.</para>
 189 <para>
 190 </para><variablelist role="params">
 191 <varlistentry><term><parameter>font</parameter>&#160;:</term>
 192 <listitem><simpara> a <link linkend="PangoFcFont"><type>PangoFcFont</type></link>
 193 </simpara></listitem></varlistentry>
 194 <varlistentry><term><parameter>wc</parameter>&#160;:</term>
 195 <listitem><simpara> Unicode codepoint to look up
 196 </simpara></listitem></varlistentry>
 197 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if <parameter>font</parameter> has the requested codepoint.
 198
 199 </simpara></listitem></varlistentry>
 200 </variablelist><para role="since">Since 1.4</para></refsect2>
 201 <refsect2 id="pango-fc-font-get-glyph" role="function" condition="since:1.4">
 202 <title>pango_fc_font_get_glyph ()</title>
 203 <indexterm zone="pango-fc-font-get-glyph" role="1.4"><primary sortas="pango_fc_font_get_glyph">pango_fc_font_get_glyph</primary></indexterm><programlisting><link linkend="guint">guint</link>               pango_fc_font_get_glyph             (<link linkend="PangoFcFont">PangoFcFont</link> *font,
 204                                                          <link linkend="gunichar">gunichar</link> wc);</programlisting>
 205 <para>
 206 Gets the glyph index for a given Unicode character
 207 for <parameter>font</parameter>. If you only want to determine
 208 whether the font has the glyph, use <link linkend="pango-fc-font-has-char"><function>pango_fc_font_has_char()</function></link>.</para>
 209 <para>
 210 </para><variablelist role="params">
 211 <varlistentry><term><parameter>font</parameter>&#160;:</term>
 212 <listitem><simpara> a <link linkend="PangoFcFont"><type>PangoFcFont</type></link>
 213 </simpara></listitem></varlistentry>
 214 <varlistentry><term><parameter>wc</parameter>&#160;:</term>
 215 <listitem><simpara> Unicode character to look up
 216 </simpara></listitem></varlistentry>
 217 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the glyph index, or 0, if the Unicode
 218   character doesn't exist in the font.
 219
 220 </simpara></listitem></varlistentry>
 221 </variablelist><para role="since">Since 1.4</para></refsect2>
 222 <refsect2 id="pango-fc-font-get-unknown-glyph" role="function" condition="deprecated:|since:1.4">
 223 <title>pango_fc_font_get_unknown_glyph ()</title>
 224 <indexterm zone="pango-fc-font-get-unknown-glyph" role="deprecated"><primary sortas="pango_fc_font_get_unknown_glyph">pango_fc_font_get_unknown_glyph</primary></indexterm><indexterm zone="pango-fc-font-get-unknown-glyph" role="1.4"><primary sortas="pango_fc_font_get_unknown_glyph">pango_fc_font_get_unknown_glyph</primary></indexterm><programlisting><link linkend="PangoGlyph">PangoGlyph</link>          pango_fc_font_get_unknown_glyph     (<link linkend="PangoFcFont">PangoFcFont</link> *font,
 225                                                          <link linkend="gunichar">gunichar</link> wc);</programlisting>
 226 <warning><para><literal>pango_fc_font_get_unknown_glyph</literal> is deprecated and should not be used in newly-written code.</para></warning>
 227 <para>
 228 Returns the index of a glyph suitable for drawing <parameter>wc</parameter> as an
 229 unknown character.
 230 </para>
 231 <para>
 232 Use <link linkend="PANGO-GET-UNKNOWN-GLYPH--CAPS"><function>PANGO_GET_UNKNOWN_GLYPH()</function></link> instead.</para>
 233 <para>
 234 </para><variablelist role="params">
 235 <varlistentry><term><parameter>font</parameter>&#160;:</term>
 236 <listitem><simpara> a <link linkend="PangoFcFont"><type>PangoFcFont</type></link>
 237 </simpara></listitem></varlistentry>
 238 <varlistentry><term><parameter>wc</parameter>&#160;:</term>
 239 <listitem><simpara> the Unicode character for which a glyph is needed.
 240 </simpara></listitem></varlistentry>
 241 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a glyph index into <parameter>font</parameter>.
 242
 243 </simpara></listitem></varlistentry>
 244 </variablelist><para role="since">Since 1.4</para></refsect2>
 245 <refsect2 id="pango-fc-font-kern-glyphs" role="function" condition="since:1.4">
 246 <title>pango_fc_font_kern_glyphs ()</title>
 247 <indexterm zone="pango-fc-font-kern-glyphs" role="1.4"><primary sortas="pango_fc_font_kern_glyphs">pango_fc_font_kern_glyphs</primary></indexterm><programlisting><link linkend="void">void</link>                pango_fc_font_kern_glyphs           (<link linkend="PangoFcFont">PangoFcFont</link> *font,
 248                                                          <link linkend="PangoGlyphString">PangoGlyphString</link> *glyphs);</programlisting>
 249 <para>
 250 Adjust each adjacent pair of glyphs in <parameter>glyphs</parameter> according to
 251 kerning information in <parameter>font</parameter>.</para>
 252 <para>
 253 </para><variablelist role="params">
 254 <varlistentry><term><parameter>font</parameter>&#160;:</term>
 255 <listitem><simpara> a <link linkend="PangoFcFont"><type>PangoFcFont</type></link>
 256 </simpara></listitem></varlistentry>
 257 <varlistentry><term><parameter>glyphs</parameter>&#160;:</term>
 258 <listitem><simpara> a <link linkend="PangoGlyphString"><type>PangoGlyphString</type></link>
 259 </simpara></listitem></varlistentry>
 260 </variablelist><para role="since">Since 1.4</para></refsect2>
 261
 262 </refsect1>
 263 <refsect1 id="PangoFcFont.property-details" role="property_details">
 264 <title role="property_details.title">Property Details</title>
 265 <refsect2 id="PangoFcFont--fontmap" role="property"><title>The <literal>&quot;fontmap&quot;</literal> property</title>
 266 <indexterm zone="PangoFcFont--fontmap"><primary sortas="PangoFcFont:fontmap">PangoFcFont:fontmap</primary></indexterm><programlisting>  &quot;fontmap&quot;                  <link linkend="PangoFcFontMap">PangoFcFontMap</link>*       : Read / Write</programlisting>
 267 <para>The PangoFc font map this font is associated with (Since: 1.26).</para></refsect2>
 268 <refsect2 id="PangoFcFont--pattern" role="property"><title>The <literal>&quot;pattern&quot;</literal> property</title>
 269 <indexterm zone="PangoFcFont--pattern"><primary sortas="PangoFcFont:pattern">PangoFcFont:pattern</primary></indexterm><programlisting>  &quot;pattern&quot;                  <link linkend="gpointer">gpointer</link>              : Read / Write / Construct Only</programlisting>
 270 <para>The fontconfig pattern for this font.</para></refsect2>
 271 </refsect1>
 272
 273
 274
 275 <refsect1 id="PangoFcFont.see-also">
 276 <title>See Also</title>
 277 <para>
 278 <variablelist>
 279 <varlistentry>
 280 <term><link linkend="PangoFcFontMap"><type>PangoFcFontMap</type></link></term>
 281 <listitem><para>The base class for font maps; creating a new
 282 Fontconfig-based backend involves deriving from both
 283 <link linkend="PangoFcFontMap"><type>PangoFcFontMap</type></link> and <link linkend="PangoFcFont"><type>PangoFcFont</type></link>.
 284 .</para></listitem>
 285 </varlistentry>
 286 </variablelist>
 287 </para>
 288 </refsect1>
 289
 290 </refentry>