:right-sidebar: True Assistant =================================================================== .. currentmodule:: gi.repository.Gtk .. deprecated:: 4.10 This widget will be removed in GTK 5 .. class:: Assistant(*args, **kwargs) :no-contents-entry: Superclasses: :class:`~gi.repository.Gtk.Window`, :class:`~gi.repository.Gtk.Widget`, :class:`~gi.repository.GObject.InitiallyUnowned`, :class:`~gi.repository.GObject.Object` Implemented Interfaces: :class:`~gi.repository.Gtk.Accessible`, :class:`~gi.repository.Gtk.Buildable`, :class:`~gi.repository.Gtk.ConstraintTarget`, :class:`~gi.repository.Gtk.Native`, :class:`~gi.repository.Gtk.Root`, :class:`~gi.repository.Gtk.ShortcutManager` ``GtkAssistant`` is used to represent a complex as a series of steps. .. image:: https://docs.gtk.org/gtk4/assistant.png Each step consists of one or more pages. ``GtkAssistant`` guides the user through the pages, and controls the page flow to collect the data needed for the operation. ``GtkAssistant`` handles which buttons to show and to make sensitive based on page sequence knowledge and the :obj:`~gi.repository.Gtk.AssistantPageType` of each page in addition to state information like the *completed* and *committed* page statuses. If you have a case that doesn’t quite fit in ``GtkAssistant``\s way of handling buttons, you can use the :const:`~gi.repository.Gtk.AssistantPageType.CUSTOM` page type and handle buttons yourself. ``GtkAssistant`` maintains a ``GtkAssistantPage`` object for each added child, which holds additional per-child properties. You obtain the ``GtkAssistantPage`` for a child with :obj:`~gi.repository.Gtk.Assistant.get_page`\. GtkAssistant as GtkBuildable -------------------------------------------------------------------------------- The ``GtkAssistant`` implementation of the ``GtkBuildable`` interface exposes the ``action_area`` as internal children with the name “action_area”. To add pages to an assistant in ``GtkBuilder``\, simply add it as a child to the ``GtkAssistant`` object. If you need to set per-object properties, create a ``GtkAssistantPage`` object explicitly, and set the child widget as a property on it. CSS nodes -------------------------------------------------------------------------------- ``GtkAssistant`` has a single CSS node with the name window and style class .assistant. Constructors ------------ .. rst-class:: interim-class .. class:: Assistant :no-index: .. classmethod:: new() -> ~gi.repository.Gtk.Widget Creates a new ``GtkAssistant``\. .. deprecated:: 4.10 This widget will be removed in GTK 5 Methods ------- .. rst-class:: interim-class .. class:: Assistant :no-index: .. method:: add_action_widget(child: ~gi.repository.Gtk.Widget) -> None Adds a widget to the action area of a ``GtkAssistant``\. .. deprecated:: 4.10 This widget will be removed in GTK 5 :param child: a ``GtkWidget`` .. method:: append_page(page: ~gi.repository.Gtk.Widget) -> int Appends a page to the ``assistant``\. .. deprecated:: 4.10 This widget will be removed in GTK 5 :param page: a ``GtkWidget`` .. method:: commit() -> None Erases the visited page history. GTK will then hide the back button on the current page, and removes the cancel button from subsequent pages. Use this when the information provided up to the current page is hereafter deemed permanent and cannot be modified or undone. For example, showing a progress page to track a long-running, unreversible operation after the user has clicked apply on a confirmation page. .. deprecated:: 4.10 This widget will be removed in GTK 5 .. method:: get_current_page() -> int Returns the page number of the current page. .. deprecated:: 4.10 This widget will be removed in GTK 5 .. method:: get_n_pages() -> int Returns the number of pages in the ``assistant`` .. deprecated:: 4.10 This widget will be removed in GTK 5 .. method:: get_nth_page(page_num: int) -> ~gi.repository.Gtk.Widget | None Returns the child widget contained in page number ``page_num``\. .. deprecated:: 4.10 This widget will be removed in GTK 5 :param page_num: the index of a page in the ``assistant``\, or -1 to get the last page .. method:: get_page(child: ~gi.repository.Gtk.Widget) -> ~gi.repository.Gtk.AssistantPage Returns the ``GtkAssistantPage`` object for ``child``\. .. deprecated:: 4.10 This widget will be removed in GTK 5 :param child: a child of ``assistant`` .. method:: get_page_complete(page: ~gi.repository.Gtk.Widget) -> bool Gets whether ``page`` is complete. .. deprecated:: 4.10 This widget will be removed in GTK 5 :param page: a page of ``assistant`` .. method:: get_page_title(page: ~gi.repository.Gtk.Widget) -> str Gets the title for ``page``\. .. deprecated:: 4.10 This widget will be removed in GTK 5 :param page: a page of ``assistant`` .. method:: get_page_type(page: ~gi.repository.Gtk.Widget) -> ~gi.repository.Gtk.AssistantPageType Gets the page type of ``page``\. .. deprecated:: 4.10 This widget will be removed in GTK 5 :param page: a page of ``assistant`` .. method:: get_pages() -> ~gi.repository.Gio.ListModel Gets a list model of the assistant pages. .. deprecated:: 4.10 This widget will be removed in GTK 5 .. method:: insert_page(page: ~gi.repository.Gtk.Widget, position: int) -> int Inserts a page in the ``assistant`` at a given position. .. deprecated:: 4.10 This widget will be removed in GTK 5 :param page: a ``GtkWidget`` :param position: the index (starting at 0) at which to insert the page, or -1 to append the page to the ``assistant`` .. method:: next_page() -> None Navigate to the next page. It is a programming error to call this function when there is no next page. This function is for use when creating pages of the :const:`~gi.repository.Gtk.AssistantPageType.CUSTOM` type. .. deprecated:: 4.10 This widget will be removed in GTK 5 .. method:: prepend_page(page: ~gi.repository.Gtk.Widget) -> int Prepends a page to the ``assistant``\. .. deprecated:: 4.10 This widget will be removed in GTK 5 :param page: a ``GtkWidget`` .. method:: previous_page() -> None Navigate to the previous visited page. It is a programming error to call this function when no previous page is available. This function is for use when creating pages of the :const:`~gi.repository.Gtk.AssistantPageType.CUSTOM` type. .. deprecated:: 4.10 This widget will be removed in GTK 5 .. method:: remove_action_widget(child: ~gi.repository.Gtk.Widget) -> None Removes a widget from the action area of a ``GtkAssistant``\. .. deprecated:: 4.10 This widget will be removed in GTK 5 :param child: a ``GtkWidget`` .. method:: remove_page(page_num: int) -> None Removes the ``page_num``\’s page from ``assistant``\. .. deprecated:: 4.10 This widget will be removed in GTK 5 :param page_num: the index of a page in the ``assistant``\, or -1 to remove the last page .. method:: set_current_page(page_num: int) -> None Switches the page to ``page_num``\. Note that this will only be necessary in custom buttons, as the ``assistant`` flow can be set with :func:`~gi.repository.Gtk.Assistant.set_forward_page_func`. .. deprecated:: 4.10 This widget will be removed in GTK 5 :param page_num: index of the page to switch to, starting from 0. If negative, the last page will be used. If greater than the number of pages in the ``assistant``\, nothing will be done. .. method:: set_forward_page_func(page_func: ~typing.Callable[[int, ~typing.Any], int] | None = None, data: ~typing.Any = None) -> None Sets the page forwarding function to be ``page_func``\. This function will be used to determine what will be the next page when the user presses the forward button. Setting ``page_func`` to :const:`None` will make the assistant to use the default forward function, which just goes to the next visible page. .. deprecated:: 4.10 This widget will be removed in GTK 5 :param page_func: the ``GtkAssistantPageFunc``\, or :const:`None` to use the default one :param data: user data for ``page_func`` .. method:: set_page_complete(page: ~gi.repository.Gtk.Widget, complete: bool) -> None Sets whether ``page`` contents are complete. This will make ``assistant`` update the buttons state to be able to continue the task. .. deprecated:: 4.10 This widget will be removed in GTK 5 :param page: a page of ``assistant`` :param complete: the completeness status of the page .. method:: set_page_title(page: ~gi.repository.Gtk.Widget, title: str) -> None Sets a title for ``page``\. The title is displayed in the header area of the assistant when ``page`` is the current page. .. deprecated:: 4.10 This widget will be removed in GTK 5 :param page: a page of ``assistant`` :param title: the new title for ``page`` .. method:: set_page_type(page: ~gi.repository.Gtk.Widget, type: ~gi.repository.Gtk.AssistantPageType) -> None Sets the page type for ``page``\. The page type determines the page behavior in the ``assistant``\. .. deprecated:: 4.10 This widget will be removed in GTK 5 :param page: a page of ``assistant`` :param type: the new type for ``page`` .. method:: update_buttons_state() -> None Forces ``assistant`` to recompute the buttons state. GTK automatically takes care of this in most situations, e.g. when the user goes to a different page, or when the visibility or completeness of a page changes. One situation where it can be necessary to call this function is when changing a value on the current page affects the future page flow of the assistant. .. deprecated:: 4.10 This widget will be removed in GTK 5 Properties ---------- .. rst-class:: interim-class .. class:: Assistant :no-index: .. attribute:: props.pages :type: ~gi.repository.Gio.ListModel The type of the None singleton. .. attribute:: props.use_header_bar :type: int The type of the None singleton. .. deprecated:: 4.10 This widget will be removed in GTK 5 Signals ------- .. rst-class:: interim-class .. class:: Assistant.signals :no-index: .. method:: apply() -> None The type of the None singleton. .. deprecated:: 4.10 This widget will be removed in GTK 5 .. method:: cancel() -> None The type of the None singleton. .. deprecated:: 4.10 This widget will be removed in GTK 5 .. method:: close() -> None Emitted either when the close button of a summary page is clicked, or when the apply button in the last page in the flow (of type :const:`~gi.repository.Gtk.AssistantPageType.CONFIRM`) is clicked. .. deprecated:: 4.10 This widget will be removed in GTK 5 .. method:: escape() -> None The type of the None singleton. .. deprecated:: 4.10 This widget will be removed in GTK 5 .. method:: prepare(page: ~gi.repository.Gtk.Widget) -> None The type of the None singleton. .. deprecated:: 4.10 This widget will be removed in GTK 5 :param page: the current page