Fonts

These interfaces are used to implement clients for centralised font configuration.

namespace fonts

Enums

enum class font_family_model

Values:

enumerator automatic

Returns the typographic font family name if known, otherwise the weight-stretch-style family name.

enumerator weight_stretch_style

Requests the weight-stretch-style family name. May return an empty string if not known.

enumerator typographic

Requests the typographic family name. May return an empty string if not known.

enum font_type_t

Values:

enumerator font_type_items

enumerator font_type_labels

enum font_type_flag_t

Values:

enumerator font_type_flag_items

enumerator font_type_flag_labels

Functions

PFC_DECLARE_EXCEPTION (exception_font_client_not_found, pfc::exception, "Font client not found")

std::optional<LOGFONT> get_log_font(GUID font_id)

Get a LOGFONT for a particular client or common font.

Parameters:

font_id – GUID of the font client or common font

Returns:

populated LOGFONT structure, or empty optional if Columns UI is not installed

LOGFONT get_log_font_with_fallback(GUID font_id)

Get a LOGFONT for a particular client or common font, falling back to the system icon font if Columns UI is not installed.

Parameters:

font_id – GUID of the font client or common font

Returns:

populated LOGFONT structure

HFONT create_hfont_with_fallback(GUID font_id)

Get an HFONT for a particular font client or common font, falling back to the system icon font if Columns UI is not installed.

Parameters:

font_id – GUID of the font client or common font

Returns:

HFONT handle. The caller must delete it using DeleteObject when it’s no longer required.

font::ptr get_font(GUID font_id)

Get a font::ptr for a particular font. This is mainly intended for DirectWrite usage.

Note

Requires Columns UI 3.0.0 or newer. You must check if the returned service pointer is valid.

Parameters:

font_id – font client or common font GUID

Throws:

exception_font_client_not_found – thrown if an invalid GUID is supplied

Returns:

font::ptr for the specified font client. Will be empty if a compatible Columns UI version is not installed.

callback_token::ptr on_common_font_changed(std::function<void(uint32_t changed_items_mask)> callback_func)

Register a function to be called when a common font has changed.

This is a simple wrapper around manager::register_common_callback() and manager::deregister_common_callback().

Note

Generally it’s recommended to implement a client object rather than use common fonts, so that fonts can be customised specifically for your panel. This callback is only useful if you do not do that and use common fonts instead.

Parameters:

callback_func – function to be called when a common font has changed

Returns:

callback token that should be reset when you no longer want the callback function to be called

Variables

constexpr GUID items_font_id = {0x1d1be0c7, 0x59f8, 0x44ff, {0x9e, 0xbb, 0x07, 0xda, 0xf2, 0x27, 0xa9, 0x0f}}

ID for the common items font.

Note

Added in Columns UI 3.0.0 alpha 1.

constexpr GUID labels_font_id = {0x238cc90a, 0x9d4c, 0x471d, {0x8b, 0x02, 0xec, 0xdc, 0x78, 0x10, 0x58, 0x8c}}

ID for the common labels font.

Note

Added in Columns UI 3.0.0 alpha 1.

constexpr GUID core_console_font_id = {0xe9f4d060, 0x6feb, 0x4626, {0xb2, 0x5d, 0xba, 0x09, 0x0f, 0x75, 0xf7, 0xa5}}

ID for the core console font.

This corresponds to the ui_font_console font available via ui_config_manager when Columns UI is the active UI.

Note

Added in Columns UI 2.0.0.

constexpr GUID core_default_font_id = {0x1adbc094, 0x3b35, 0x4bab, {0x82, 0xd5, 0x3b, 0xdd, 0x4a, 0x5c, 0x6a, 0xf9}}

ID for the default core font.

This corresponds to any font other than ui_font_console, ui_font_lists and ui_font_playlists available via ui_config_manager when Columns UI is the active UI.

Note

Added in Columns UI 2.0.0.

constexpr GUID core_lists_font_id = {0xfc3cb3a8, 0x72db, 0x4448, {0xb1, 0x2c, 0x2e, 0xf7, 0x6a, 0x15, 0xd7, 0x53}}

ID for the core lists font.

This corresponds to the ui_font_lists and ui_font_playlists fonts available via ui_config_manager when Columns UI is the active UI.

Note

Added in Columns UI 2.0.0.

struct axis_value

Public Members

uint32_t axis_tag

float value

class rendering_options : public service_base

Defines text rendering options, as configured in Columns UI Colours and fonts preferences.

Note

Added in Columns UI 3.0.0.

Subclassed by cui::fonts::rendering_options_impl

Public Functions

virtual DWRITE_RENDERING_MODE rendering_mode() const noexcept = 0

Retrieves the rendering mode configured in Columns UI preferences.

Note

You do not need to use this method if you use create_rendering_params(), use_gdi_compatible_layout() and use_gdi_natural().

virtual bool use_greyscale_antialiasing() const noexcept = 0

Retrieves the value of the ‘Use greyscale anti-aliasing’ setting in Columns UI preferences.

If enabled, DWRITE_TEXT_ANTIALIAS_MODE_GRAYSCALE or D2D1_TEXT_ANTIALIAS_MODE_GRAYSCALE should be used.

See also

dwrite_text_antialiasing_mode(), d2d_text_antialiasing_mode()

virtual bool use_colour_glyphs() const noexcept = 0

Retrieves the value of the ‘Use colour glyphs when available’ setting in Columns UI preferences.

For ID2D1RenderTarget::DrawTextLayout() and similar methods, this refers to the D2D1_DRAW_TEXT_OPTIONS_ENABLE_COLOR_FONT flag.

virtual HRESULT create_rendering_params(IDWriteFactory *factory, HMONITOR monitor, IDWriteRenderingParams **rendering_params) const noexcept = 0

Create an IDWriteRenderingParams object for the specified monitor and the values returned by rendering_mode() and use_greyscale_antialiasing() value.

inline DWRITE_TEXT_ANTIALIAS_MODE dwrite_text_antialiasing_mode() const noexcept

Helper function that returns the Direct2D text antialiasing mode.

This can be used with ID2D1RenderTarget::SetTextAntialiasMode().

inline D2D1_TEXT_ANTIALIAS_MODE d2d_text_antialiasing_mode() const noexcept

Helper function that returns the Direct2D text antialiasing mode.

This can be used with ID2D1RenderTarget::SetTextAntialiasMode().

inline bool use_gdi_compatible_layout() const noexcept

Helper function that returns whether a GDI-compatible text layout should be used.

If this returns true, IDWriteFactory::CreateGdiCompatibleTextLayout() should be used instead of IDWriteFactory::CreateTextLayout().

inline bool use_gdi_natural() const noexcept

Helper function that returns the value of the useGdiNatural argument of IDWriteFactory::CreateGdiCompatibleTextLayout().

See also

use_gdi_compatible_layout()

class rendering_options_impl : public cui::fonts::rendering_options

Implementation of rendering_options. Can be used to create an instance of rendering_options when the manager_v3 service is missing (due to a compatible version of Columns UI not being installed).

To create an instance of this class, use fb2k::service_new() function:

const auto rendering_options_ptr = fb2k::service_new<RenderingOptions>(
  // constructor arguments
);

Public Functions

inline rendering_options_impl()

inline rendering_options_impl(DWRITE_RENDERING_MODE rendering_mode, bool use_greyscale_antialiasing, bool use_colour_glyphs)

inline virtual DWRITE_RENDERING_MODE rendering_mode() const noexcept override

Retrieves the rendering mode configured in Columns UI preferences.

Note

You do not need to use this method if you use create_rendering_params(), use_gdi_compatible_layout() and use_gdi_natural().

inline virtual bool use_greyscale_antialiasing() const noexcept override

Retrieves the value of the ‘Use greyscale anti-aliasing’ setting in Columns UI preferences.

If enabled, DWRITE_TEXT_ANTIALIAS_MODE_GRAYSCALE or D2D1_TEXT_ANTIALIAS_MODE_GRAYSCALE should be used.

See also

dwrite_text_antialiasing_mode(), d2d_text_antialiasing_mode()

inline virtual bool use_colour_glyphs() const noexcept override

Retrieves the value of the ‘Use colour glyphs when available’ setting in Columns UI preferences.

For ID2D1RenderTarget::DrawTextLayout() and similar methods, this refers to the D2D1_DRAW_TEXT_OPTIONS_ENABLE_COLOR_FONT flag.

inline virtual HRESULT create_rendering_params(IDWriteFactory *factory, HMONITOR monitor, IDWriteRenderingParams **rendering_params) const noexcept override

Create an IDWriteRenderingParams object for the specified monitor and the values returned by rendering_mode() and use_greyscale_antialiasing() value.

class font : public service_base

Defines a font, as configured in Columns UI Colours and fonts preferences.

The recommended methods to use are create_text_format() and rendering_options(). However, access to the underlying data is also provided for less common use cases.

Note

Added in Columns UI 3.0.0.

Public Functions

virtual const wchar_t *family_name(font_family_model font_family_model = font_family_model::automatic) noexcept = 0

virtual DWRITE_FONT_WEIGHT weight() noexcept = 0

virtual DWRITE_FONT_STRETCH stretch() noexcept = 0

virtual DWRITE_FONT_STYLE style() noexcept = 0

virtual float size() noexcept = 0

Get the font size, in DIP units.

virtual size_t axis_count() const noexcept = 0

Get the number of configured font axes. May be zero, in which case the weight-stretch-style values should be used.

virtual axis_value axis_value(size_t index) const = 0

Get an axis value.

Parameters:

index – Axis index. Must be in the range 0 <= index < axis_count().

Throws:

std::out_of_range – on invalid index

virtual LOGFONT log_font() noexcept = 0

Get a GDI-compatible LOGFONT for this font.

Note that the LOGFONT returned is the closest equivalent as GDI does not support modern font features.

virtual LOGFONT log_font_for_dpi(unsigned dpi) noexcept = 0

Get a GDI-compatible LOGFONT for this font and a specific DPI.

Note that the LOGFONT returned is the closest equivalent as GDI does not support modern font features.

virtual HRESULT create_font_fallback(IDWriteFontFallback **font_fallback) noexcept = 0

Create a font fallback object that should be applied to the text format using IDWriteTextFormat1::SetFontFallback().

The custom font fallback object is used for the ‘Use alternative emoji font selection logic’ option in Columns UI text rendering options.

If a custom font fallback object is not in use, S_FALSE will be returned and *font_fallback will be set to nullptr. Do not use *font_fallback without checking that it is not equal to nullptr.

Note

You do not need to use this method if the text format was created using create_text_format().

virtual HRESULT create_text_format (IDWriteTextFormat **text_format, const wchar_t *locale_name=L"") noexcept=0

Create a DirectWrite text format for this font.

The font fallback object for the font will be automatically configured if needed.

No further customisation of the text format is performed. You should configure text alignment, paragraph alignment, word wrapping and other options according to your needs.

virtual rendering_options::ptr rendering_options() noexcept = 0

Retrieves text rendering options.

These options should be used when rendering text using the created text format.

class manager_v3 : public service_base

DirectWrite-friendly manager_v3 interface.

Note

Added in Columns UI 3.0.0.

Public Functions

virtual font::ptr get_font(GUID id) const = 0

Get a font definition for a particular font client or a common font.

Parameters:

id – font client or common font GUID

Throws:

exception_font_client_not_found – thrown if an invalid GUID is supplied

Returns:

service pointer for a font instance.

virtual rendering_options::ptr get_default_rendering_options() noexcept = 0

Retrieves the default text rendering options.

Remark

font::rendering_options() should be used in preference to this method. This method is only provided to allow access to the configured rendering options when the font being used is not provided by Columns UI.

See also

font::rendering_options()

virtual HRESULT get_default_font_fallback(IDWriteFontFallback **font_fallback) noexcept = 0

Get the default Columns UI font fallback object when it’s required.

Remark

font::create_font_fallback() should be used in preference to this method. This method is only provided to allow access to the font fallback object when the font being used is not provided by Columns UI.

See also

See font::create_font_fallback() for more details about the font fallback object returned.

virtual void set_font_size(GUID id, float size) = 0

Set the font size for a client font.

Parameters:

• id – font client GUID

• size – new size in DIP units

Throws:

exception_font_client_not_found – thrown if an invalid GUID is supplied

virtual callback_token::ptr on_font_changed(GUID id, basic_callback::ptr callback) = 0

Register a new callback for when a font has changed.

Parameters:

• id – client or common font GUID

• callback – callback function

Returns:

callback token that should be reset when you no longer want the callback function to be called

virtual callback_token::ptr on_default_rendering_options_changed(basic_callback::ptr callback) = 0

Register a new callback for when the default rendering options have changed.

Remark

This callback should only be used if get_default_rendering_options() is being used. Do not use it if you’re using font::rendering_options().

Parameters:

callback – callback function

Returns:

callback token that should be reset when you no longer want the callback function to be called

virtual callback_token::ptr on_default_font_fallback_changed(basic_callback::ptr callback) = 0

Register a new callback for when the font fallback object has changed.

Remark

This callback should only be used if get_default_font_fallback() is being used. Do not use it if you’re using font::font_fallback().

Parameters:

callback – callback function

Returns:

callback token that should be reset when you no longer want the callback function to be called

class common_callback

Use this class if you wish to use the common fonts rather than implementing client

Public Functions

virtual void on_font_changed(uint32_t changed_items_mask) const = 0

class manager : public service_base

One implementation in Columns UI - do not reimplement!

Public Functions

virtual void get_font(const GUID &p_guid, LOGFONT &p_out) const = 0

Retrieves the font for the given client.

virtual void get_font(const font_type_t p_type, LOGFONT &p_out) const = 0

Retrieves common fonts.

virtual void set_font(const GUID &p_guid, const LOGFONT &p_font) = 0

Sets your font as ‘Custom’ and to p_font.

virtual void register_common_callback(common_callback *p_callback) = 0

virtual void deregister_common_callback(common_callback *p_callback) = 0

inline HFONT get_font(const GUID &p_guid) const

Helper

inline HFONT get_font(const font_type_t p_type) const

Helper

FB2K_MAKE_SERVICE_INTERFACE_ENTRYPOINT(manager)

class manager_v2 : public service_base

Font management API with support for custom DPIs.

This was intended for per-monitor DPI support. However, neither Columns UI nor foobar2000 currently support per-monitor DPI.

One implementation in Columns UI - do not reimplement!

Note

Requires Columns UI 1.7.0 beta 1 or newer.

Public Functions

virtual LOGFONT get_client_font(GUID guid, unsigned dpi = USER_DEFAULT_SCREEN_DPI) const = 0

Retrieve the font for the given client.

virtual LOGFONT get_common_font(font_type_t type, unsigned dpi = USER_DEFAULT_SCREEN_DPI) const = 0

Retrieve a common font.

virtual void set_client_font(GUID guid, const LOGFONT &font, int point_size_tenths) = 0

Set your font as ‘Custom’ and to the specified font.

virtual void register_common_callback(common_callback *callback) = 0

virtual void deregister_common_callback(common_callback *callback) = 0

inline HFONT get_client_font_handle(GUID guid, unsigned dpi = USER_DEFAULT_SCREEN_DPI) const

inline HFONT get_common_font_handle(const font_type_t type, unsigned dpi = USER_DEFAULT_SCREEN_DPI) const

FB2K_MAKE_SERVICE_INTERFACE_ENTRYPOINT(manager_v2)

class helper

Helper to simplify retrieving the font for a specific client.

See also

This has been superseded by get_log_font(), get_log_font_with_fallback() and create_hfont_with_fallback()

Public Functions

void get_font(LOGFONT &p_out) const

HFONT get_font() const

inline helper(GUID font_id)

class client : public service_base

Public Types

template<class base>
using factory = service_factory_single_t<base>

Public Functions

virtual const GUID &get_client_guid() const = 0

virtual void get_name(pfc::string_base &p_out) const = 0

virtual font_type_t get_default_font_type() const = 0

virtual void on_font_changed() const = 0

FB2K_MAKE_SERVICE_INTERFACE_ENTRYPOINT(client)

Public Static Functions

static bool create_by_guid(const GUID &p_guid, ptr &p_out)