: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] | None = None, *data: ~typing.Any) -> 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 ``GListModel`` containing the pages. .. attribute:: props.use_header_bar :type: int :const:`True` if the assistant uses a ``GtkHeaderBar`` for action buttons instead of the action-area. For technical reasons, this property is declared as an integer property, but you should only set it to :const:`True` or :const:`False`. .. deprecated:: 4.10 This widget will be removed in GTK 5 Signals ------- .. rst-class:: interim-class .. class:: Assistant.signals :no-index: .. method:: apply() -> None Emitted when the apply button is clicked. The default behavior of the ``GtkAssistant`` is to switch to the page after the current page, unless the current page is the last one. A handler for the ::apply signal should carry out the actions for which the wizard has collected data. If the action takes a long time to complete, you might consider putting a page of type :const:`~gi.repository.Gtk.AssistantPageType.PROGRESS` after the confirmation page and handle this operation within the :obj:`~gi.repository.Gtk.Assistant.signals.prepare` signal of the progress page. .. deprecated:: 4.10 This widget will be removed in GTK 5 .. method:: cancel() -> None Emitted when then the cancel button is clicked. .. 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 action signal for the Escape binding. .. deprecated:: 4.10 This widget will be removed in GTK 5 .. method:: prepare(page: ~gi.repository.Gtk.Widget) -> None Emitted when a new page is set as the assistant's current page, before making the new page visible. A handler for this signal can do any preparations which are necessary before showing ``page``. .. deprecated:: 4.10 This widget will be removed in GTK 5 :param page: the current page