:right-sidebar: True

FontDialog
===================================================================

.. currentmodule:: gi.repository.Gtk


.. versionadded:: 4.10




.. class:: FontDialog(**properties: ~typing.Any)
   :no-contents-entry:


Superclasses: :class:`~gi.repository.GObject.Object`





A ``GtkFontDialog`` object collects the arguments that
are needed to present a font chooser dialog to the
user, such as a title for the dialog and whether it
should be modal.

The dialog is shown with the :obj:`~gi.repository.Gtk.FontDialog.choose_font`
function or its variants. This API follows the GIO async pattern,
and the result can be obtained by calling the corresponding
finish function, such as :obj:`~gi.repository.Gtk.FontDialog.choose_font_finish`.

See :obj:`~gi.repository.Gtk.FontDialogButton` for a convenient control
that uses ``GtkFontDialog`` and presents the results.



Constructors
------------

.. rst-class:: interim-class

.. class:: FontDialog
   :no-index:


   .. classmethod:: new() -> ~gi.repository.Gtk.FontDialog

      Creates a new ``GtkFontDialog`` object.



      .. versionadded:: 4.10












Methods
-------

.. rst-class:: interim-class

.. class:: FontDialog
   :no-index:


   .. method:: choose_face(parent: ~gi.repository.Gtk.Window | None = None, initial_value: ~gi.repository.Pango.FontFace | None = None, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[...], None] | None = None, *user_data: ~typing.Any) -> None

      This function initiates a font selection operation by
      presenting a dialog to the user for selecting a font face
      (i.e. a font family and style, but not a specific font size).

      The ``callback`` will be called when the dialog is dismissed.
      It should call :obj:`~gi.repository.Gtk.FontDialog.choose_face_finish`
      to obtain the result.



      .. versionadded:: 4.10





      :param parent: the parent ``GtkWindow``


      :param initial_value: the initial value


      :param cancellable: a ``GCancellable`` to cancel the operation


      :param callback: a callback to call when the operation is complete


      :param user_data: data to pass to ``callback``





   .. method:: choose_face_finish(result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.Pango.FontFace | None

      Finishes the :obj:`~gi.repository.Gtk.FontDialog.choose_face` call
      and returns the resulting font face.



      .. versionadded:: 4.10





      :param result: a ``GAsyncResult``





   .. method:: choose_family(parent: ~gi.repository.Gtk.Window | None = None, initial_value: ~gi.repository.Pango.FontFamily | None = None, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[...], None] | None = None, *user_data: ~typing.Any) -> None

      This function initiates a font selection operation by
      presenting a dialog to the user for selecting a font family.

      The ``callback`` will be called when the dialog is dismissed.
      It should call :obj:`~gi.repository.Gtk.FontDialog.choose_family_finish`
      to obtain the result.



      .. versionadded:: 4.10





      :param parent: the parent ``GtkWindow``


      :param initial_value: the initial value


      :param cancellable: a ``GCancellable`` to cancel the operation


      :param callback: a callback to call when the operation is complete


      :param user_data: data to pass to ``callback``





   .. method:: choose_family_finish(result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.Pango.FontFamily | None

      Finishes the :obj:`~gi.repository.Gtk.FontDialog.choose_family` call
      and returns the resulting family.

      This function never returns an error. If the operation is
      not finished successfully, the value passed as ``initial_value``
      to :obj:`~gi.repository.Gtk.FontDialog.choose_family` is returned.



      .. versionadded:: 4.10





      :param result: a ``GAsyncResult``





   .. method:: choose_font(parent: ~gi.repository.Gtk.Window | None = None, initial_value: ~gi.repository.Pango.FontDescription | None = None, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[...], None] | None = None, *user_data: ~typing.Any) -> None

      This function initiates a font selection operation by
      presenting a dialog to the user for selecting a font.

      The ``callback`` will be called when the dialog is dismissed.
      It should call :obj:`~gi.repository.Gtk.FontDialog.choose_font_finish`
      to obtain the result.

      If you want to let the user select font features as well,
      use :obj:`~gi.repository.Gtk.FontDialog.choose_font_and_features` instead.



      .. versionadded:: 4.10





      :param parent: the parent ``GtkWindow``


      :param initial_value: the font to select initially


      :param cancellable: a ``GCancellable`` to cancel the operation


      :param callback: a callback to call when the operation is complete


      :param user_data: data to pass to ``callback``





   .. method:: choose_font_and_features(parent: ~gi.repository.Gtk.Window | None = None, initial_value: ~gi.repository.Pango.FontDescription | None = None, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[...], None] | None = None, *user_data: ~typing.Any) -> None

      This function initiates a font selection operation by
      presenting a dialog to the user for selecting a font and
      font features.

      Font features affect how the font is rendered, for example
      enabling glyph variants or ligatures.

      The ``callback`` will be called when the dialog is dismissed.
      It should call :obj:`~gi.repository.Gtk.FontDialog.choose_font_and_features_finish`
      to obtain the result.



      .. versionadded:: 4.10





      :param parent: the parent ``GtkWindow``


      :param initial_value: the font to select initially


      :param cancellable: a ``GCancellable`` to cancel the operation


      :param callback: a callback to call when the operation is complete


      :param user_data: data to pass to ``callback``





   .. method:: choose_font_and_features_finish(result: ~gi.repository.Gio.AsyncResult) -> tuple[bool, ~gi.repository.Pango.FontDescription, str, ~gi.repository.Pango.Language]

      Finishes the :obj:`~gi.repository.Gtk.FontDialog.choose_font_and_features`
      call and returns the resulting font description and font features.



      .. versionadded:: 4.10





      :param result: a ``GAsyncResult``





   .. method:: choose_font_finish(result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.Pango.FontDescription | None

      Finishes the :obj:`~gi.repository.Gtk.FontDialog.choose_font` call
      and returns the resulting font description.



      .. versionadded:: 4.10





      :param result: a ``GAsyncResult``





   .. method:: get_filter() -> ~gi.repository.Gtk.Filter | None

      Returns the filter that decides which fonts to display
      in the font chooser dialog.



      .. versionadded:: 4.10








   .. method:: get_font_map() -> ~gi.repository.Pango.FontMap | None

      Returns the fontmap from which fonts are selected,
      or ``NULL`` for the default fontmap.



      .. versionadded:: 4.10








   .. method:: get_language() -> ~gi.repository.Pango.Language | None

      Returns the language for which font features are applied.



      .. versionadded:: 4.10








   .. method:: get_modal() -> bool

      Returns whether the font chooser dialog
      blocks interaction with the parent window
      while it is presented.



      .. versionadded:: 4.10








   .. method:: get_title() -> str

      Returns the title that will be shown on the
      font chooser dialog.



      .. versionadded:: 4.10








   .. method:: set_filter(filter: ~gi.repository.Gtk.Filter | None = None) -> None

      Adds a filter that decides which fonts to display
      in the font chooser dialog.

      The ``GtkFilter`` must be able to handle both ``PangoFontFamily``
      and ``PangoFontFace`` objects.



      .. versionadded:: 4.10





      :param filter: a ``GtkFilter``





   .. method:: set_font_map(fontmap: ~gi.repository.Pango.FontMap | None = None) -> None

      Sets the fontmap from which fonts are selected.

      If ``fontmap`` is ``NULL``, the default fontmap is used.



      .. versionadded:: 4.10





      :param fontmap: the fontmap





   .. method:: set_language(language: ~gi.repository.Pango.Language) -> None

      Sets the language for which font features are applied.



      .. versionadded:: 4.10





      :param language: the language for font features





   .. method:: set_modal(modal: bool) -> None

      Sets whether the font chooser dialog
      blocks interaction with the parent window
      while it is presented.



      .. versionadded:: 4.10





      :param modal: the new value





   .. method:: set_title(title: str) -> None

      Sets the title that will be shown on the
      font chooser dialog.



      .. versionadded:: 4.10





      :param title: the new title









Properties
----------

.. rst-class:: interim-class

.. class:: FontDialog
   :no-index:
   

   .. attribute:: props.filter
      :type: ~gi.repository.Gtk.Filter

      Sets a filter to restrict what fonts are shown
      in the font chooser dialog.



      .. versionadded:: 4.10





   .. attribute:: props.font_map
      :type: ~gi.repository.Pango.FontMap

      Sets a custom font map to select fonts from.

      A custom font map can be used to present application-specific
      fonts instead of or in addition to the normal system fonts.



      .. versionadded:: 4.10





   .. attribute:: props.language
      :type: ~gi.repository.Pango.Language

      The language for which the font features are selected.



      .. versionadded:: 4.10





   .. attribute:: props.modal
      :type: bool

      Whether the font chooser dialog is modal.



      .. versionadded:: 4.10





   .. attribute:: props.title
      :type: str

      A title that may be shown on the font chooser
      dialog that is presented by :obj:`~gi.repository.Gtk.FontDialog.choose_font`.



      .. versionadded:: 4.10