DhSettings: Devhelp 3 Reference Manual

## DhSettings DhSettings — libdevhelp settings |

## Functions

DhSettings * | dh_settings_get_default ()
void | dh_settings_bind_all ()
gboolean | dh_settings_get_group_books_by_language ()
void | dh_settings_set_group_books_by_language ()
void | dh_settings_bind_group_books_by_language ()
gboolean | dh_settings_is_book_enabled ()
void | dh_settings_set_book_enabled ()
void | dh_settings_freeze_books_disabled_changed ()
void | dh_settings_thaw_books_disabled_changed ()
void | dh_settings_get_selected_fonts ()
gboolean | dh_settings_get_use_system_fonts ()
void | dh_settings_set_use_system_fonts ()
const gchar * | dh_settings_get_variable_font ()
void | dh_settings_set_variable_font ()
const gchar * | dh_settings_get_fixed_font ()
void | dh_settings_set_fixed_font ()
void | dh_settings_bind_fonts ()

## Properties

gchar * | fixed-font | Read / Write / Construct
gboolean | group-books-by-language | Read / Write / Construct
gboolean | use-system-fonts | Read / Write / Construct
gchar * | variable-font | Read / Write / Construct

## Signals

void | books-disabled-changed | Run First
void | fonts-changed | Run First

## Types and Values

struct | DhSettings

## Object Hierarchy

        GObject
        ╰── DhSettings

## Includes

    #include <devhelp/devhelp.h>

## Description

DhSettings represents the libdevhelp settings. The libdevhelp provides a GSettings schema, but for some settings the use of GSettings is optional: it is instead possible to set the DhSettings property and do not bind it to the GSettings key, to force a certain value and to not provide a user configuration for it in the application.

To have the documentation about the available GSettings keys, their types, the default values, etc, read the `*.gschema.xml` file.

Note that DhSettings do not expose the GSettings objects, you should use the DhSettings wrapper API instead. So instead of using `g_settings_bind()`, you should use `g_object_bind_property()` with a DhSettings property as the source. This has the small drawback that the writability of the GSettings keys are not exposed, it is assumed that all keys are writable; if knowing the writability of the GSettings keys is really wanted, the DhSettings API can be changed to expose publicly the GSettings objects (for that purpose only).

### Different default value

If you want to save a DhSettings setting with GSettings, but with a different default value than the one provided by the libdevhelp GSettings schema, the recommended thing to do is to *not* call the bind function provided by DhSettings for that property, provide your own GSettings schema with the same key but with a different default value, and call yourself `g_settings_bind()`.

### GSettings keys without corresponding properties

For the following GSettings keys, the use of GSettings is mandatory, there are no corresponding DhSettings properties (and thus no bind function).

- `"books-disabled"`: if the use of GSettings is not wanted, a custom DhBookList can be created instead.

## Functions

### dh_settings_get_default ()

    DhSettings *
    dh_settings_get_default (void);

Gets the default DhSettings object. It has the default GSettings paths (see DhSettingsBuilder) and `dh_settings_bind_all()` has been called.

#### Returns

the default DhSettings object.

[transfer none]

Since: 3.30

### dh_settings_bind_all ()

    void
    dh_settings_bind_all (DhSettings *settings);

Binds all the DhSettings properties to their corresponding GSettings keys.

#### Parameters

settings | a DhSettings. |

Since: 3.30

### dh_settings_get_group_books_by_language ()

    gboolean
    dh_settings_get_group_books_by_language
                                   (DhSettings *settings);

#### Parameters

settings | a DhSettings. |

#### Returns

the value of the “group-books-by-language” property.

Since: 3.30

### dh_settings_set_group_books_by_language ()

    void
    dh_settings_set_group_books_by_language
                                   (DhSettings *settings,
                                    gboolean group_books_by_language);

Sets the “group-books-by-language” property.

#### Parameters

settings | a DhSettings. |
group_books_by_language | the new value. |

Since: 3.30

### dh_settings_bind_group_books_by_language ()

    void
    dh_settings_bind_group_books_by_language
                                   (DhSettings *settings);

Binds the “group-books-by-language” property to the corresponding GSettings key.

#### Parameters

settings | a DhSettings. |

Since: 3.30

### dh_settings_is_book_enabled ()

    gboolean
    dh_settings_is_book_enabled (DhSettings *settings,
                                 DhBook *book);

Returns whether `book` is enabled according to the "books-disabled" GSettings key. If the `book` ID is present in "books-disabled", this function returns `FALSE`, otherwise `TRUE` is returned.

#### Parameters

settings | a DhSettings. |
book | a DhBook. |

#### Returns

whether `book` is enabled.

Since: 3.30

### dh_settings_set_book_enabled ()

    void
    dh_settings_set_book_enabled (DhSettings *settings,
                                  DhBook *book,
                                  gboolean enabled);

Modifies the "books-disabled" GSettings key. It adds or removes the `book` ID from "books-disabled".

#### Parameters

settings | a DhSettings. |
book | a DhBook. |
enabled | the new value. |

Since: 3.30

### dh_settings_freeze_books_disabled_changed ()

    void
    dh_settings_freeze_books_disabled_changed
                                   (DhSettings *settings);

Tells `settings` to not emit the “books-disabled-changed” signal until `dh_settings_thaw_books_disabled_changed()` is called.

A bit like `g_object_freeze_notify()`, except that there is no freeze count.

This function is useful if you call `dh_settings_set_book_enabled()` several times in a row.

#### Parameters

settings | a DhSettings. |

Since: 3.30

### dh_settings_thaw_books_disabled_changed ()

    void
    dh_settings_thaw_books_disabled_changed
                                   (DhSettings *settings);

Stops the effect of `dh_settings_freeze_books_disabled_changed()`, and emits the “books-disabled-changed” signal.

A bit like `g_object_thaw_notify()`, except that there is no freeze count.

#### Parameters

settings | a DhSettings. |

Since: 3.30

### dh_settings_get_selected_fonts ()

    void
    dh_settings_get_selected_fonts (DhSettings *settings,
                                    gchar **variable_font,
                                    gchar **fixed_font);

If “use-system-fonts” is `TRUE`, returns the system fonts. Otherwise returns the values of the “variable-font” and “fixed-font” properties.

#### Parameters

settings | a DhSettings. |
variable_font | location to store the font name for text with variable width. Free with `g_free()`. | [out]
fixed_font | location to store the font name for text with fixed width. Free with `g_free()`. | [out]

Since: 3.30

### dh_settings_get_use_system_fonts ()

    gboolean
    dh_settings_get_use_system_fonts (DhSettings *settings);

#### Parameters

settings | a DhSettings. |

#### Returns

the value of the “use-system-fonts” property.

Since: 3.30

### dh_settings_set_use_system_fonts ()

    void
    dh_settings_set_use_system_fonts (DhSettings *settings,
                                      gboolean use_system_fonts);

Sets the “use-system-fonts” property.

#### Parameters

settings | a DhSettings. |
use_system_fonts | the new value. |

Since: 3.30

### dh_settings_get_variable_font ()

    const gchar *
    dh_settings_get_variable_font (DhSettings *settings);

Warning: you probably want to use the `dh_settings_get_selected_fonts()` function instead, to take into account the “use-system-fonts” property.

#### Parameters

settings | a DhSettings. |

#### Returns

the value of the “variable-font” property.

Since: 3.30

### dh_settings_set_variable_font ()

    void
    dh_settings_set_variable_font (DhSettings *settings,
                                   const gchar *variable_font);

Sets the “variable-font” property.

#### Parameters

settings | a DhSettings. |
variable_font | the new value. |

Since: 3.30

### dh_settings_get_fixed_font ()

    const gchar *
    dh_settings_get_fixed_font (DhSettings *settings);

Warning: you probably want to use the `dh_settings_get_selected_fonts()` function instead, to take into account the “use-system-fonts” property.

#### Parameters

settings | a DhSettings. |

#### Returns

the value of the “fixed-font” property.

Since: 3.30

### dh_settings_set_fixed_font ()

    void
    dh_settings_set_fixed_font (DhSettings *settings,
                                const gchar *fixed_font);

Sets the “fixed-font” property.

#### Parameters

settings | a DhSettings. |
fixed_font | the new value. |

Since: 3.30

### dh_settings_bind_fonts ()

    void
    dh_settings_bind_fonts (DhSettings *settings);

Binds the “use-system-fonts”, “variable-font” and “fixed-font” properties to their corresponding GSettings keys.

#### Parameters

settings | a DhSettings. |

Since: 3.30

## Types and Values

### struct DhSettings

    struct DhSettings;

## Property Details

### The `“fixed-font”` property

      “fixed-font”               gchar *

Font for text with fixed width, such as code examples.

This property is independent of “use-system-fonts”.

Flags: Read / Write / Construct

Default value: "Monospace 12"

Since: 3.30

### The `“group-books-by-language”` property

      “group-books-by-language”  gboolean

Whether books should be grouped by programming language in the UI.

Flags: Read / Write / Construct

Default value: FALSE

Since: 3.30

### The `“use-system-fonts”` property

      “use-system-fonts”         gboolean

Whether to use the system default fonts.

Flags: Read / Write / Construct

Default value: TRUE

Since: 3.30

### The `“variable-font”` property

      “variable-font”            gchar *

Font for text with variable width.

This property is independent of “use-system-fonts”.

Flags: Read / Write / Construct

Default value: "Sans 12"

Since: 3.30

## Signal Details

### The `“books-disabled-changed”` signal

    void
    user_function (DhSettings *settings,
                   gpointer    user_data)

The ::books-disabled-changed signal is emitted when the "books-disabled" GSettings key changes.

#### Parameters

settings | the DhSettings emitting the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run First

Since: 3.30

### The `“fonts-changed”` signal

    void
    user_function (DhSettings *settings,
                   gpointer    user_data)

The ::fonts-changed signal is emitted when the return values of `dh_settings_get_selected_fonts()` have potentially changed.

#### Parameters

settings | the DhSettings emitting the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run First

Since: 3.30