GtkAssistant is used to represent a complex as a series of steps.
<picture> <source srcset="assistant-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkAssistant" src="assistant.png"> </picture> 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 [enumGtk.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 GtkAssistants way of handling buttons, you can use the Gtk.Assistant_Page.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 [methodGtk.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.
<group>Windows</group> <gtkada_demo>create_assistant.adb</gtkada_demo> <see>Gtk.Assistant_Page</see>
function "+"
(Widget : access Gtk_Assistant_Record'Class)
return Gtk.Accessible.Gtk_Accessible
function "+"
(Widget : access Gtk_Assistant_Record'Class)
return Gtk.Buildable.Gtk_Buildable
function "+"
(Widget : access Gtk_Assistant_Record'Class)
return Gtk.Constraint_Target.Gtk_Constraint_Target
function "+"
(Widget : access Gtk_Assistant_Record'Class)
return Gtk.Native.Gtk_Native
function "+"
(Widget : access Gtk_Assistant_Record'Class)
return Gtk.Root.Gtk_Root
function "+"
(Widget : access Gtk_Assistant_Record'Class)
return Gtk.Shortcut_Manager.Gtk_Shortcut_Manager
function "-"
(Interf : Gtk.Accessible.Gtk_Accessible)
return Gtk_Assistant
function "-"
(Interf : Gtk.Buildable.Gtk_Buildable)
return Gtk_Assistant
function "-"
(Interf : Gtk.Constraint_Target.Gtk_Constraint_Target)
return Gtk_Assistant
function "-"
(Interf : Gtk.Native.Gtk_Native)
return Gtk_Assistant
function "-"
(Interf : Gtk.Root.Gtk_Root)
return Gtk_Assistant
function "-"
(Interf : Gtk.Shortcut_Manager.Gtk_Shortcut_Manager)
return Gtk_Assistant
procedure Add_Action_Widget
(Self : not null access Gtk_Assistant_Record;
Child : not null access Gtk.Widget.Gtk_Widget_Record'Class)
Adds a widget to the action area of a GtkAssistant. Deprecated since 4.10, 1
a GtkWidget
procedure Announce
(Self : not null access Gtk_Assistant_Record;
Message : UTF8_String;
Priority : Gtk.Accessible.Gtk_Accessible_Announcement_Priority)
function Append_Page
(Self : not null access Gtk_Assistant_Record;
Page : not null access Gtk.Widget.Gtk_Widget_Record'Class)
return Glib.Gint
Appends a page to the Assistant. Deprecated since 4.10, 1
a GtkWidget
the index (starting at 0) of the inserted page
type Cb_GObject_Gtk_Widget_Void is not null access procedure
(Self : access Glib.Object.GObject_Record'Class;
Page : not null access Gtk.Widget.Gtk_Widget_Record'Class);
type Cb_GObject_Void is not null access procedure
(Self : access Glib.Object.GObject_Record'Class);
type Cb_Gtk_Assistant_Gtk_Widget_Void is not null access procedure
(Self : access Gtk_Assistant_Record'Class;
Page : not null access Gtk.Widget.Gtk_Widget_Record'Class);
type Cb_Gtk_Assistant_Void is not null access procedure (Self : access Gtk_Assistant_Record'Class);
procedure Commit (Self : not null access Gtk_Assistant_Record)
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 since 4.10, 1
function Get_Accessible_Id
(Self : not null access Gtk_Assistant_Record) return UTF8_String
function Get_Accessible_Parent
(Self : not null access Gtk_Assistant_Record)
return Gtk.Accessible.Gtk_Accessible
function Get_Accessible_Role
(Self : not null access Gtk_Assistant_Record)
return Gtk.Accessible.Gtk_Accessible_Role
function Get_At_Context
(Self : not null access Gtk_Assistant_Record)
return Gtk.Atcontext.Gtk_Atcontext
function Get_Bounds
(Self : not null access Gtk_Assistant_Record;
X : out Glib.Gint;
Y : out Glib.Gint;
Width : out Glib.Gint;
Height : out Glib.Gint) return Boolean
function Get_Current_Page
(Self : not null access Gtk_Assistant_Record) return Glib.Gint
Returns the page number of the current page. Deprecated since 4.10, 1
The index (starting from 0) of the current page in the Assistant, or -1 if the Assistant has no pages, or no current page
function Get_Display
(Self : not null access Gtk_Assistant_Record) return Gdk.Gdk_Display
function Get_First_Accessible_Child
(Self : not null access Gtk_Assistant_Record)
return Gtk.Accessible.Gtk_Accessible
function Get_Focus
(Self : not null access Gtk_Assistant_Record)
return Gtk.Widget.Gtk_Widget
function Get_N_Pages
(Self : not null access Gtk_Assistant_Record) return Glib.Gint
Returns the number of pages in the Assistant Deprecated since 4.10, 1
the number of pages in the Assistant
function Get_Next_Accessible_Sibling
(Self : not null access Gtk_Assistant_Record)
return Gtk.Accessible.Gtk_Accessible
function Get_Nth_Page
(Self : not null access Gtk_Assistant_Record;
Page_Num : Glib.Gint) return Gtk.Widget.Gtk_Widget
Returns the child widget contained in page number Page_Num. Deprecated since 4.10, 1
the index of a page in the Assistant, or -1 to get the last page
the child widget, or null if Page_Num is out of bounds. Has transfer-ownership='none'.
function Get_Page
(Self : not null access Gtk_Assistant_Record;
Child : not null access Gtk.Widget.Gtk_Widget_Record'Class)
return Gtk.Assistant_Page.Gtk_Assistant_Page
Returns the GtkAssistantPage object for Child. Deprecated since 4.10, 1
a child of Assistant
the GtkAssistantPage for Child. Has transfer-ownership='none'.
function Get_Page_Complete
(Self : not null access Gtk_Assistant_Record;
Page : not null access Gtk.Widget.Gtk_Widget_Record'Class)
return Boolean
Gets whether Page is complete. Deprecated since 4.10, 1
a page of Assistant
True if Page is complete.
function Get_Page_Title
(Self : not null access Gtk_Assistant_Record;
Page : not null access Gtk.Widget.Gtk_Widget_Record'Class)
return UTF8_String
Gets the title for Page. Deprecated since 4.10, 1
a page of Assistant
the title for Page
function Get_Page_Type
(Self : not null access Gtk_Assistant_Record;
Page : not null access Gtk.Widget.Gtk_Widget_Record'Class)
return Gtk.Assistant_Page.Gtk_Assistant_Page_Type
Gets the page type of Page. Deprecated since 4.10, 1
a page of Assistant
the page type of Page
function Get_Pages
(Self : not null access Gtk_Assistant_Record)
return Glib.List_Model.Glist_Model
Gets a list model of the assistant pages. Deprecated since 4.10, 1
A list model of the pages.
function Get_Platform_State
(Self : not null access Gtk_Assistant_Record;
State : Gtk.Accessible.Gtk_Accessible_Platform_State) return Boolean
function Get_Surface
(Self : not null access Gtk_Assistant_Record) return Gdk.Gdk_Surface
procedure Get_Surface_Transform
(Self : not null access Gtk_Assistant_Record;
X : out Gdouble;
Y : out Gdouble)
function Get_Type return Glib.GType
type Gtk_Assistant is access all Gtk_Assistant_Record'Class;
function Gtk_Assistant_New return Gtk_Assistant
Creates a new GtkAssistant.
type Gtk_Assistant_Page_Func is access function (Current_Page : Glib.Gint) return Glib.Gint;
Type of callback used to calculate the next page in a GtkAssistant. It's called both for computing the next page when the user presses the "forward" button and for handling the behavior of the "last" button. See [methodGtk.Assistant.set_forward_page_func].
The page number used to calculate the next page.
The next page number
type Gtk_Assistant_Record is new Gtk_Window_Record with null record;
procedure Gtk_New (Self : out Gtk_Assistant)
Creates a new GtkAssistant. Initialize does nothing if the object was already created with another call to Initialize* or G_New.
package Implements_Gtk_Accessible is new Glib.Types.Implements
(Gtk.Accessible.Gtk_Accessible, Gtk_Assistant_Record, Gtk_Assistant);
package Implements_Gtk_Buildable is new Glib.Types.Implements
(Gtk.Buildable.Gtk_Buildable, Gtk_Assistant_Record, Gtk_Assistant);
package Implements_Gtk_Constraint_Target is new Glib.Types.Implements
(Gtk.Constraint_Target.Gtk_Constraint_Target, Gtk_Assistant_Record, Gtk_Assistant);
package Implements_Gtk_Native is new Glib.Types.Implements
(Gtk.Native.Gtk_Native, Gtk_Assistant_Record, Gtk_Assistant);
package Implements_Gtk_Root is new Glib.Types.Implements
(Gtk.Root.Gtk_Root, Gtk_Assistant_Record, Gtk_Assistant);
package Implements_Gtk_Shortcut_Manager is new Glib.Types.Implements
(Gtk.Shortcut_Manager.Gtk_Shortcut_Manager, Gtk_Assistant_Record, Gtk_Assistant);
procedure Initialize (Self : not null access Gtk_Assistant_Record'Class)
Creates a new GtkAssistant. Initialize does nothing if the object was already created with another call to Initialize* or G_New.
function Insert_Page
(Self : not null access Gtk_Assistant_Record;
Page : not null access Gtk.Widget.Gtk_Widget_Record'Class;
Position : Glib.Gint) return Glib.Gint
Inserts a page in the Assistant at a given position. Deprecated since 4.10, 1
a GtkWidget
the index (starting at 0) at which to insert the page, or -1 to append the page to the Assistant
the index (starting from 0) of the inserted page
procedure Next_Page (Self : not null access Gtk_Assistant_Record)
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 Gtk.Assistant_Page.Custom type. Deprecated since 4.10, 1
procedure On_Apply
(Self : not null access Gtk_Assistant_Record;
Call : Cb_GObject_Void;
Slot : not null access Glib.Object.GObject_Record'Class;
After : Boolean := False)
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 Gtk.Assistant_Page.Progress after the confirmation page and handle this operation within the [signalGtk.Assistant::prepare] signal of the progress page.
procedure On_Apply
(Self : not null access Gtk_Assistant_Record;
Call : Cb_Gtk_Assistant_Void;
After : Boolean := False)
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 Gtk.Assistant_Page.Progress after the confirmation page and handle this operation within the [signalGtk.Assistant::prepare] signal of the progress page.
procedure On_Cancel
(Self : not null access Gtk_Assistant_Record;
Call : Cb_GObject_Void;
Slot : not null access Glib.Object.GObject_Record'Class;
After : Boolean := False)
Emitted when then the cancel button is clicked.
procedure On_Cancel
(Self : not null access Gtk_Assistant_Record;
Call : Cb_Gtk_Assistant_Void;
After : Boolean := False)
Emitted when then the cancel button is clicked.
procedure On_Close
(Self : not null access Gtk_Assistant_Record;
Call : Cb_GObject_Void;
Slot : not null access Glib.Object.GObject_Record'Class;
After : Boolean := False)
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 Gtk.Assistant_Page.Confirm) is clicked.
procedure On_Close
(Self : not null access Gtk_Assistant_Record;
Call : Cb_Gtk_Assistant_Void;
After : Boolean := False)
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 Gtk.Assistant_Page.Confirm) is clicked.
procedure On_Escape
(Self : not null access Gtk_Assistant_Record;
Call : Cb_GObject_Void;
Slot : not null access Glib.Object.GObject_Record'Class;
After : Boolean := False)
The action signal for the Escape binding.
procedure On_Escape
(Self : not null access Gtk_Assistant_Record;
Call : Cb_Gtk_Assistant_Void;
After : Boolean := False)
The action signal for the Escape binding.
procedure On_Prepare
(Self : not null access Gtk_Assistant_Record;
Call : Cb_GObject_Gtk_Widget_Void;
Slot : not null access Glib.Object.GObject_Record'Class;
After : Boolean := False)
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.
procedure On_Prepare
(Self : not null access Gtk_Assistant_Record;
Call : Cb_Gtk_Assistant_Gtk_Widget_Void;
After : Boolean := False)
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.
Pages_Property : constant Glib.Properties.Property_Interface;
Type: Glib.List_Model.Glist_Model GListModel containing the pages.
function Prepend_Page
(Self : not null access Gtk_Assistant_Record;
Page : not null access Gtk.Widget.Gtk_Widget_Record'Class)
return Glib.Gint
Prepends a page to the Assistant. Deprecated since 4.10, 1
a GtkWidget
the index (starting at 0) of the inserted page
procedure Previous_Page (Self : not null access Gtk_Assistant_Record)
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 Gtk.Assistant_Page.Custom type. Deprecated since 4.10, 1
procedure Realize (Self : not null access Gtk_Assistant_Record)
procedure Remove_Action_Widget
(Self : not null access Gtk_Assistant_Record;
Child : not null access Gtk.Widget.Gtk_Widget_Record'Class)
Removes a widget from the action area of a GtkAssistant. Deprecated since 4.10, 1
a GtkWidget
procedure Remove_Page
(Self : not null access Gtk_Assistant_Record;
Page_Num : Glib.Gint)
Removes the Page_Num's page from Assistant. Deprecated since 4.10, 1
the index of a page in the Assistant, or -1 to remove the last page
procedure Reset_Property
(Self : not null access Gtk_Assistant_Record;
Property : Gtk.Accessible.Gtk_Accessible_Property)
procedure Reset_Relation
(Self : not null access Gtk_Assistant_Record;
Relation : Gtk.Accessible.Gtk_Accessible_Relation)
procedure Reset_State
(Self : not null access Gtk_Assistant_Record;
State : Gtk.Accessible.Gtk_Accessible_State)
procedure Set_Accessible_Parent
(Self : not null access Gtk_Assistant_Record;
Parent : Gtk.Accessible.Gtk_Accessible;
Next_Sibling : Gtk.Accessible.Gtk_Accessible)
procedure Set_Current_Page
(Self : not null access Gtk_Assistant_Record;
Page_Num : Glib.Gint)
Switches the page to Page_Num. Note that this will only be necessary in custom buttons, as the Assistant flow can be set with Gtk.Assistant.Set_Forward_Page_Func. Deprecated since 4.10, 1
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.
procedure Set_Focus
(Self : not null access Gtk_Assistant_Record;
Focus : access Gtk.Widget.Gtk_Widget_Record'Class)
procedure Set_Forward_Page_Func
(Self : not null access Gtk_Assistant_Record;
Page_Func : Gtk_Assistant_Page_Func)
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 null will make the assistant to use the default forward function, which just goes to the next visible page. Deprecated since 4.10, 1
the GtkAssistantPageFunc, or null to use the default one
procedure Set_Page_Complete
(Self : not null access Gtk_Assistant_Record;
Page : not null access Gtk.Widget.Gtk_Widget_Record'Class;
Complete : Boolean)
Sets whether Page contents are complete. This will make Assistant update the buttons state to be able to continue the task. Deprecated since 4.10, 1
a page of Assistant
the completeness status of the page
procedure Set_Page_Title
(Self : not null access Gtk_Assistant_Record;
Page : not null access Gtk.Widget.Gtk_Widget_Record'Class;
Title : UTF8_String)
Sets a title for Page. The title is displayed in the header area of the assistant when Page is the current page. Deprecated since 4.10, 1
a page of Assistant
the new title for Page
procedure Set_Page_Type
(Self : not null access Gtk_Assistant_Record;
Page : not null access Gtk.Widget.Gtk_Widget_Record'Class;
The_Type : Gtk.Assistant_Page.Gtk_Assistant_Page_Type)
Sets the page type for Page. The page type determines the page behavior in the Assistant. Deprecated since 4.10, 1
a page of Assistant
the new type for Page
Signal_Apply : constant Glib.Signal_Name := "apply";
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 Gtk.Assistant_Page.Progress after the confirmation page and handle this operation within the [signalGtk.Assistant::prepare] signal of the progress page.
Signal_Cancel : constant Glib.Signal_Name := "cancel";
Emitted when then the cancel button is clicked.
Signal_Close : constant Glib.Signal_Name := "close";
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 Gtk.Assistant_Page.Confirm) is clicked.
Signal_Escape : constant Glib.Signal_Name := "escape";
The action signal for the Escape binding.
Signal_Prepare : constant Glib.Signal_Name := "prepare";
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.
procedure Unrealize (Self : not null access Gtk_Assistant_Record)
procedure Update_Buttons_State
(Self : not null access Gtk_Assistant_Record)
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 since 4.10, 1
procedure Update_Next_Accessible_Sibling
(Self : not null access Gtk_Assistant_Record;
New_Sibling : Gtk.Accessible.Gtk_Accessible)
procedure Update_Platform_State
(Self : not null access Gtk_Assistant_Record;
State : Gtk.Accessible.Gtk_Accessible_Platform_State)
Use_Header_Bar_Property : constant Glib.Properties.Property_Int;
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 True or False.