Win32 Fonts and Rendering: Pango Reference Manual

## Win32 Fonts and Rendering Win32 Fonts and Rendering — Functions for shape engines to manipulate Win32 fonts |

## Functions

PangoContext * | pango_win32_get_context ()
void | pango_win32_render ()
void | pango_win32_render_transformed ()
void | pango_win32_render_layout_line ()
void | pango_win32_render_layout ()
PangoGlyph | pango_win32_get_unknown_glyph ()
gint | pango_win32_font_get_glyph_index ()
gboolean | pango_win32_font_select_font ()
void | pango_win32_font_done_font ()
double | pango_win32_font_get_metrics_factor ()
gboolean | pango_win32_get_debug_flag ()
HDC | pango_win32_get_dc ()
PangoWin32FontCache * | pango_win32_font_cache_new ()
void | pango_win32_font_cache_free ()
HFONT | pango_win32_font_cache_load ()
HFONT | pango_win32_font_cache_loadw ()
void | pango_win32_font_cache_unload ()
PangoFontMap * | pango_win32_font_map_for_display ()
void | pango_win32_shutdown_display ()
PangoWin32FontCache * | pango_win32_font_map_get_font_cache ()
LOGFONTA * | pango_win32_font_logfont ()
LOGFONTW * | pango_win32_font_logfontw ()
PangoFontDescription * | pango_win32_font_description_from_logfont ()
PangoFontDescription * | pango_win32_font_description_from_logfontw ()

## Types and Values

#define | PANGO_RENDER_TYPE_WIN32
| PangoWin32FontCache

## Description

The macros and functions in this section are used to access fonts natively on Win32 systems and to render text in conjunction with Win32 APIs.

## Functions

### pango_win32_get_context ()

    PangoContext *
    pango_win32_get_context (void);

`pango_win32_get_context` has been deprecated since version 1.22 and should not be used in newly-written code.

Use `pango_win32_font_map_for_display()` followed by `pango_font_map_create_context()` instead.

Retrieves a PangoContext appropriate for rendering with Windows fonts.

#### Returns

the new PangoContext

### pango_win32_render ()

    void
    pango_win32_render (HDC hdc,
                        PangoFont *font,
                        PangoGlyphString *glyphs,
                        gint x,
                        gint y);

Render a PangoGlyphString onto a Windows DC

#### Parameters

hdc | the device context |
font | the font in which to draw the string |
glyphs | the glyph string to draw |
x | the x position of start of string (in pixels) |
y | the y position of baseline (in pixels) |

### pango_win32_render_transformed ()

    void
    pango_win32_render_transformed (HDC hdc,
                                    const PangoMatrix *matrix,
                                    PangoFont *font,
                                    PangoGlyphString *glyphs,
                                    int x,
                                    int y);

Renders a PangoGlyphString onto a windows DC, possibly transforming the layed-out coordinates through a transformation matrix. Note that the transformation matrix for `font` is not changed, so to produce correct rendering results, the `font` must have been loaded using a PangoContext with an identical transformation matrix to that passed in to this function.

#### Parameters

hdc | a windows device context |
matrix | a PangoMatrix, or `NULL` to use an identity transformation. | [nullable]
font | the font in which to draw the string |
glyphs | the glyph string to draw |
x | the x position of the start of the string (in Pango units in user space coordinates) |
y | the y position of the baseline (in Pango units in user space coordinates) |

### pango_win32_render_layout_line ()

    void
    pango_win32_render_layout_line (HDC hdc,
                                    PangoLayoutLine *line,
                                    int x,
                                    int y);

Render a PangoLayoutLine onto a device context. For underlining to work property the text alignment of the DC should have TA_BASELINE and TA_LEFT.

#### Parameters

hdc | DC to use for drawing |
line | a PangoLayoutLine |
x | the x position of start of string (in pixels) |
y | the y position of baseline (in pixels) |

### pango_win32_render_layout ()

    void
    pango_win32_render_layout (HDC hdc,
                               PangoLayout *layout,
                               int x,
                               int y);

Render a PangoLayoutLine onto an X drawable

#### Parameters

hdc | HDC to use for drawing |
layout | a PangoLayout |
x | the X position of the left of the layout (in pixels) |
y | the Y position of the top of the layout (in pixels) |

### pango_win32_get_unknown_glyph ()

    PangoGlyph
    pango_win32_get_unknown_glyph (PangoFont *font,
                                   gunichar wc);

`pango_win32_get_unknown_glyph` is deprecated and should not be used in newly-written code.

Returns the index of a glyph suitable for drawing `wc` as an unknown character.

Use `PANGO_GET_UNKNOWN_GLYPH()` instead.

#### Parameters

font | a PangoFont |
wc | the Unicode character for which a glyph is needed. |

#### Returns

a glyph index into `font`

### pango_win32_font_get_glyph_index ()

    gint
    pango_win32_font_get_glyph_index (PangoFont *font,
                                      gunichar wc);

`pango_win32_font_get_glyph_index` is deprecated and should not be used in newly-written code.

Obtains the index of the glyph for `wc` in `font` , or 0, if not covered.

#### Parameters

font | a PangoFont. |
wc | a Unicode character. |

#### Returns

the glyph index for `wc` .

### pango_win32_font_select_font ()

    gboolean
    pango_win32_font_select_font (PangoFont *font,
                                  HDC hdc);

Selects the font into the specified DC and changes the mapping mode and world transformation of the DC appropriately for the font. You may want to surround the use of this function with calls to `SaveDC()` and `RestoreDC()`. Call `pango_win32_font_done_font()` when you are done using the DC to release allocated resources.

See `pango_win32_font_get_metrics_factor()` for information about converting from the coordinate space used by this function into Pango units.

#### Parameters

font | a PangoFont from the Win32 backend |
hdc | a windows device context |

#### Returns

`TRUE` if the operation succeeded.

### pango_win32_font_done_font ()

    void
    pango_win32_font_done_font (PangoFont *font);

Releases any resources allocated by `pango_win32_font_done_font()`

#### Parameters

font | a PangoFont from the win32 backend |

### pango_win32_font_get_metrics_factor ()

    double
    pango_win32_font_get_metrics_factor (PangoFont *font);

Returns the scale factor from logical units in the coordinate space used by `pango_win32_font_select_font()` to Pango units in user space.

#### Parameters

font | a PangoFont from the win32 backend |

#### Returns

factor to multiply logical units by to get Pango units.

### pango_win32_get_debug_flag ()

    gboolean
    pango_win32_get_debug_flag (void);

Returns whether debugging is turned on.

#### Returns

`TRUE` if debugging is turned on.

Since: 1.2

### pango_win32_get_dc ()

    HDC
    pango_win32_get_dc (void);

Obtains a handle to the Windows device context that is used by Pango.

#### Returns

A handle to the Windows device context that is used by Pango.

### pango_win32_font_cache_new ()

    PangoWin32FontCache *
    pango_win32_font_cache_new (void);

Creates a font cache.

#### Returns

The new font cache. This must be freed with `pango_win32_font_cache_free()`.

### pango_win32_font_cache_free ()

    void
    pango_win32_font_cache_free (PangoWin32FontCache *cache);

Frees a PangoWin32FontCache and all associated memory. All fonts loaded through this font cache will be freed along with the cache.

#### Parameters

cache | a PangoWin32FontCache |

### pango_win32_font_cache_load ()

    HFONT
    pango_win32_font_cache_load (PangoWin32FontCache *cache,
                                 const LOGFONTA *logfont);

Creates a HFONT from a LOGFONTA. The result may be newly loaded, or it may have been previously stored

#### Parameters

cache | a PangoWin32FontCache |
logfont | a pointer to a LOGFONTA structure describing the font to load. |

#### Returns

The font structure, or `NULL` if the font could not be loaded. In order to free this structure, you must call `pango_win32_font_cache_unload()`.

[nullable]

### pango_win32_font_cache_loadw ()

    HFONT
    pango_win32_font_cache_loadw (PangoWin32FontCache *cache,
                                  const LOGFONTW *logfont);

Creates a HFONT from a LOGFONTW. The result may be newly loaded, or it may have been previously stored

#### Parameters

cache | a PangoWin32FontCache |
logfont | a pointer to a LOGFONTW structure describing the font to load. |

#### Returns

The font structure, or `NULL` if the font could not be loaded. In order to free this structure, you must call `pango_win32_font_cache_unload()`.

[nullable]

Since: 1.16

### pango_win32_font_cache_unload ()

    void
    pango_win32_font_cache_unload (PangoWin32FontCache *cache,
                                   HFONT hfont);

Frees a font structure previously loaded with `pango_win32_font_cache_load()`.

#### Parameters

cache | a PangoWin32FontCache |
hfont | the HFONT to unload |

### pango_win32_font_map_for_display ()

    PangoFontMap *
    pango_win32_font_map_for_display (void);

Returns a PangoWin32FontMap. Font maps are cached and should not be freed. If the font map is no longer needed, it can be released with `pango_win32_shutdown_display()`.

#### Returns

a PangoFontMap.

### pango_win32_shutdown_display ()

    void
    pango_win32_shutdown_display (void);

Free cached resources.

### pango_win32_font_map_get_font_cache ()

    PangoWin32FontCache *
    pango_win32_font_map_get_font_cache (PangoFontMap *font_map);

Obtains the font cache associated with the given font map.

#### Parameters

font_map | a PangoWin32FontMap. |

#### Returns

the PangoWin32FontCache of `font_map` .

### pango_win32_font_logfont ()

    LOGFONTA *
    pango_win32_font_logfont (PangoFont *font);

Determine the LOGFONTA struct for the specified font. Note that Pango internally uses LOGFONTW structs, so if converting the UTF-16 face name in the LOGFONTW struct to system codepage fails, the returned LOGFONTA will have an emppty face name. To get the LOGFONTW of a PangoFont, use `pango_win32_font_logfontw()`. It is recommended to do that always even if you don't expect to come across fonts with odd names.

#### Parameters

font | a PangoFont which must be from the Win32 backend |

#### Returns

A newly allocated LOGFONTA struct. It must be freed with `g_free()`.

### pango_win32_font_logfontw ()

    LOGFONTW *
    pango_win32_font_logfontw (PangoFont *font);

Determine the LOGFONTW struct for the specified font.

#### Parameters

font | a PangoFont which must be from the Win32 backend |

#### Returns

A newly allocated LOGFONTW struct. It must be freed with `g_free()`.

Since: 1.16

### pango_win32_font_description_from_logfont ()

    PangoFontDescription *
    pango_win32_font_description_from_logfont
                                   (const LOGFONTA *lfp);

Creates a PangoFontDescription that matches the specified LOGFONTA.

The face name, italicness and weight fields in the LOGFONTA are used to set up the resulting PangoFontDescription. If the face name in the LOGFONTA contains non-ASCII characters the font is temporarily loaded (using `CreateFontIndirect()`) and an ASCII (usually English) name for it is looked up from the font name tables in the font data. If that doesn't work, the face name is converted from the system codepage to UTF-8 and that is used.

#### Parameters

lfp | a LOGFONTA |

#### Returns

the newly allocated PangoFontDescription, which should be freed using `pango_font_description_free()`

Since: 1.12

### pango_win32_font_description_from_logfontw ()

    PangoFontDescription *
    pango_win32_font_description_from_logfontw
                                   (const LOGFONTW *lfp);

Creates a PangoFontDescription that matches the specified LOGFONTW.

The face name, italicness and weight fields in the LOGFONTW are used to set up the resulting PangoFontDescription. If the face name in the LOGFONTW contains non-ASCII characters the font is temporarily loaded (using `CreateFontIndirect()`) and an ASCII (usually English) name for it is looked up from the font name tables in the font data. If that doesn't work, the face name is converted from UTF-16 to UTF-8 and that is used.

#### Parameters

lfp | a LOGFONTW |

#### Returns

the newly allocated PangoFontDescription, which should be freed using `pango_font_description_free()`

Since: 1.16

## Types and Values

### PANGO_RENDER_TYPE_WIN32

    #define PANGO_RENDER_TYPE_WIN32 "PangoRenderWin32"

A string constant identifying the Win32 renderer. The associated quark (see `g_quark_from_string()`) is used to identify the renderer in `pango_find_map()`.

### PangoWin32FontCache

    typedef struct _PangoWin32FontCache PangoWin32FontCache;

A PangoWin32FontCache caches HFONTs by their LOGFONT descriptions.