AssistantProtocol

public protocol AssistantProtocol : WindowProtocol

GtkAssistant is used to represent a complex as a series of steps.

An example GtkAssistant

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.

The AssistantProtocol protocol exposes the methods and properties of an underlying GtkAssistant instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see Assistant. Alternatively, use AssistantRef as a lighweight, unowned reference if you already have an instance you just want to use.

Show on GitHub
  • ptr

    Untyped pointer to the underlying GtkAssistant instance.

    Declaration

    Swift

    var ptr: UnsafeMutableRawPointer! { get }
    Show on GitHub
  • assistant_ptr Default implementation

    Typed pointer to the underlying GtkAssistant instance.

    Default Implementation

    Return the stored, untyped pointer as a typed pointer to the GtkAssistant instance.

    Declaration

    Swift

    var assistant_ptr: UnsafeMutablePointer<GtkAssistant>! { get }
    Show on GitHub

  • Required Initialiser for types conforming to AssistantProtocol

    Declaration

    Swift

    init(raw: UnsafeMutableRawPointer)
    Show on GitHub

Assistant Class

  • Bind a AssistantPropertyName source property to a given target object.

    Declaration

    Swift

    @discardableResult
@inlinable
func bind<Q, T>(property source_property: AssistantPropertyName, to target: T, _ target_property: Q, flags f: BindingFlags = .default, transformFrom transform_from: @escaping GLibObject.ValueTransformer = { $0.transform(destValue: $1) }, transformTo transform_to: @escaping GLibObject.ValueTransformer = { $0.transform(destValue: $1) }) -> BindingRef! where Q : PropertyNameProtocol, T : ObjectProtocol

    Parameters

    source_property

    the source property to bind
    target

    the target object to bind to
    target_property

    the target property to bind to
    flags

    the flags to pass to the Binding
    transform_from

    ValueTransformer to use for forward transformation
    transform_to

    ValueTransformer to use for backwards transformation

    Return Value

    binding reference or nil in case of an error

    Show on GitHub
  • get(property:) Extension method

    Get the value of a Assistant property

    Declaration

    Swift

    @inlinable
func get(property: AssistantPropertyName) -> GLibObject.Value

    Parameters

    property

    the property to get the value for

    Return Value

    the value of the named property

    Show on GitHub
  • set(property:value:) Extension method

    Set the value of a Assistant property. Note that this will only have an effect on properties that are writable and not construct-only!

    Declaration

    Swift

    @inlinable
func set(property: AssistantPropertyName, value v: GLibObject.Value)

    Parameters

    property

    the property to get the value for

    Return Value

    the value of the named property

    Show on GitHub

Assistant signals

  • Connect a Swift signal handler to the given, typed AssistantSignalName signal

    Declaration

    Swift

    @discardableResult
@inlinable
func connect(signal s: AssistantSignalName, flags f: ConnectFlags = ConnectFlags(0), handler h: @escaping SignalHandler) -> Int

    Parameters

    signal

    The signal to connect
    flags

    The connection flags to use
    data

    A pointer to user data to provide to the callback
    destroyData

    A GClosureNotify C function to destroy the data pointed to by userData
    handler

    The Swift signal handler (function or callback) to invoke on the given signal

    Return Value

    The signal handler ID (always greater than 0 for successful connections)

    Show on GitHub

  • Connect a C signal handler to the given, typed AssistantSignalName signal

    Declaration

    Swift

    @discardableResult
@inlinable
func connect(signal s: AssistantSignalName, flags f: ConnectFlags = ConnectFlags(0), data userData: gpointer!, destroyData destructor: GClosureNotify? = nil, signalHandler h: @escaping GCallback) -> Int

    Parameters

    signal

    The signal to connect
    flags

    The connection flags to use
    data

    A pointer to user data to provide to the callback
    destroyData

    A GClosureNotify C function to destroy the data pointed to by userData
    signalHandler

    The C function to be called on the given signal

    Return Value

    The signal handler ID (always greater than 0 for successful connections)

    Show on GitHub
  • onApply(flags:handler:) Extension method

    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.

    Note

    This represents the underlying apply signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onApply(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: AssistantRef) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    handler

    The signal handler to call Run the given callback whenever the apply signal is emitted
    Show on GitHub
  • applySignal Extension method

    Typed apply signal for using the connect(signal:) methods

    Declaration

    Swift

    static var applySignal: AssistantSignalName { get }
    Show on GitHub
  • onCancel(flags:handler:) Extension method

    Emitted when then the cancel button is clicked.

    Note

    This represents the underlying cancel signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onCancel(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: AssistantRef) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    handler

    The signal handler to call Run the given callback whenever the cancel signal is emitted
    Show on GitHub
  • cancelSignal Extension method

    Typed cancel signal for using the connect(signal:) methods

    Declaration

    Swift

    static var cancelSignal: AssistantSignalName { get }
    Show on GitHub
  • onClose(flags:handler:) Extension method

    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.

    Note

    This represents the underlying close signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onClose(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: AssistantRef) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    handler

    The signal handler to call Run the given callback whenever the close signal is emitted
    Show on GitHub
  • closeSignal Extension method

    Typed close signal for using the connect(signal:) methods

    Declaration

    Swift

    static var closeSignal: AssistantSignalName { get }
    Show on GitHub
  • onEscape(flags:handler:) Extension method

    The action signal for the Escape binding.

    Note

    This represents the underlying escape signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onEscape(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: AssistantRef) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    handler

    The signal handler to call Run the given callback whenever the escape signal is emitted
    Show on GitHub
  • escapeSignal Extension method

    Typed escape signal for using the connect(signal:) methods

    Declaration

    Swift

    static var escapeSignal: AssistantSignalName { get }
    Show on GitHub
  • onPrepare(flags:handler:) Extension method

    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.

    Note

    This represents the underlying prepare signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onPrepare(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: AssistantRef, _ page: WidgetRef) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    page

    the current page
    handler

    The signal handler to call Run the given callback whenever the prepare signal is emitted
    Show on GitHub
  • prepareSignal Extension method

    Typed prepare signal for using the connect(signal:) methods

    Declaration

    Swift

    static var prepareSignal: AssistantSignalName { get }
    Show on GitHub

  • The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.

    Note that getting this signal doesn’t itself guarantee that the value of the property has actually changed. When it is emitted is determined by the derived GObject class. If the implementor did not create the property with G_PARAM_EXPLICIT_NOTIFY, then any call to g_object_set_property() results in notify being emitted, even if the new value is the same as the old. If they did pass G_PARAM_EXPLICIT_NOTIFY, then this signal is emitted only when they explicitly call g_object_notify() or g_object_notify_by_pspec(), and common practice is to do that only when the value has actually changed.

    This signal is typically used to obtain change notification for a single property, by specifying the property name as a detail in the g_signal_connect() call, like this:

    (C Language Example):

    g_signal_connect (text_view->buffer, "notify::paste-target-list",
                  G_CALLBACK (gtk_text_view_target_list_notify),
                  text_view)

    It is important to note that you must use canonical parameter names as detail strings for the notify signal.

    Note

    This represents the underlying notify::pages signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onNotifyPages(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: AssistantRef, _ pspec: ParamSpecRef) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    pspec

    the GParamSpec of the property which changed.
    handler

    The signal handler to call Run the given callback whenever the notifyPages signal is emitted
    Show on GitHub
  • notifyPagesSignal Extension method

    Typed notify::pages signal for using the connect(signal:) methods

    Declaration

    Swift

    static var notifyPagesSignal: AssistantSignalName { get }
    Show on GitHub

  • The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.

    Note that getting this signal doesn’t itself guarantee that the value of the property has actually changed. When it is emitted is determined by the derived GObject class. If the implementor did not create the property with G_PARAM_EXPLICIT_NOTIFY, then any call to g_object_set_property() results in notify being emitted, even if the new value is the same as the old. If they did pass G_PARAM_EXPLICIT_NOTIFY, then this signal is emitted only when they explicitly call g_object_notify() or g_object_notify_by_pspec(), and common practice is to do that only when the value has actually changed.

    This signal is typically used to obtain change notification for a single property, by specifying the property name as a detail in the g_signal_connect() call, like this:

    (C Language Example):

    g_signal_connect (text_view->buffer, "notify::paste-target-list",
                  G_CALLBACK (gtk_text_view_target_list_notify),
                  text_view)

    It is important to note that you must use canonical parameter names as detail strings for the notify signal.

    Note

    This represents the underlying notify::use-header-bar signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onNotifyUseHeaderBar(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: AssistantRef, _ pspec: ParamSpecRef) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    pspec

    the GParamSpec of the property which changed.
    handler

    The signal handler to call Run the given callback whenever the notifyUseHeaderBar signal is emitted
    Show on GitHub
  • notifyUseHeaderBarSignal Extension method

    Typed notify::use-header-bar signal for using the connect(signal:) methods

    Declaration

    Swift

    static var notifyUseHeaderBarSignal: AssistantSignalName { get }
    Show on GitHub

Assistant Class: AssistantProtocol extension (methods and fields)

  • addActionWidget(child:) Extension method

    Adds a widget to the action area of a GtkAssistant.

    Declaration

    Swift

    @inlinable
func addActionWidget<WidgetT>(child: WidgetT) where WidgetT : WidgetProtocol
    Show on GitHub
  • append(page:) Extension method

    Appends a page to the assistant.

    Declaration

    Swift

    @inlinable
func append<WidgetT>(page: WidgetT) -> Int where WidgetT : WidgetProtocol
    Show on GitHub
  • commit() Extension method

    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.

    Declaration

    Swift

    @inlinable
func commit()
    Show on GitHub
  • getCurrentPage() Extension method

    Returns the page number of the current page.

    Declaration

    Swift

    @inlinable
func getCurrentPage() -> Int
    Show on GitHub
  • getNPages() Extension method

    Returns the number of pages in the assistant

    Declaration

    Swift

    @inlinable
func getNPages() -> Int
    Show on GitHub
  • getNthPage(pageNum:) Extension method

    Returns the child widget contained in page number page_num.

    Declaration

    Swift

    @inlinable
func getNthPage(pageNum: Int) -> WidgetRef!
    Show on GitHub
  • getPage(child:) Extension method

    Returns the GtkAssistantPage object for child.

    Declaration

    Swift

    @inlinable
func getPage<WidgetT>(child: WidgetT) -> AssistantPageRef! where WidgetT : WidgetProtocol
    Show on GitHub
  • getPageComplete(page:) Extension method

    Gets whether page is complete.

    Declaration

    Swift

    @inlinable
func getPageComplete<WidgetT>(page: WidgetT) -> Bool where WidgetT : WidgetProtocol
    Show on GitHub
  • getPageTitle(page:) Extension method

    Gets the title for page.

    Declaration

    Swift

    @inlinable
func getPageTitle<WidgetT>(page: WidgetT) -> String! where WidgetT : WidgetProtocol
    Show on GitHub
  • getPageType(page:) Extension method

    Gets the page type of page.

    Declaration

    Swift

    @inlinable
func getPageType<WidgetT>(page: WidgetT) -> GtkAssistantPageType where WidgetT : WidgetProtocol
    Show on GitHub
  • getPages() Extension method

    Gets a list model of the assistant pages.

    Declaration

    Swift

    @inlinable
func getPages() -> GIO.ListModelRef!
    Show on GitHub
  • insert(page:position:) Extension method

    Inserts a page in the assistant at a given position.

    Declaration

    Swift

    @inlinable
func insert<WidgetT>(page: WidgetT, position: Int) -> Int where WidgetT : WidgetProtocol
    Show on GitHub
  • nextPage() Extension method

    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.

    Declaration

    Swift

    @inlinable
func nextPage()
    Show on GitHub
  • prepend(page:) Extension method

    Prepends a page to the assistant.

    Declaration

    Swift

    @inlinable
func prepend<WidgetT>(page: WidgetT) -> Int where WidgetT : WidgetProtocol
    Show on GitHub
  • previousPage() Extension method

    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.

    Declaration

    Swift

    @inlinable
func previousPage()
    Show on GitHub
  • removeActionWidget(child:) Extension method

    Removes a widget from the action area of a GtkAssistant.

    Declaration

    Swift

    @inlinable
func removeActionWidget<WidgetT>(child: WidgetT) where WidgetT : WidgetProtocol
    Show on GitHub
  • removePage(pageNum:) Extension method

    Removes the page_num’s page from assistant.

    Declaration

    Swift

    @inlinable
func removePage(pageNum: Int)
    Show on GitHub
  • setCurrentPage(pageNum:) Extension method

    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().

    Declaration

    Swift

    @inlinable
func setCurrentPage(pageNum: Int)
    Show on GitHub

  • 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 nil will make the assistant to use the default forward function, which just goes to the next visible page.

    Declaration

    Swift

    @inlinable
func setForward(pageFunc: GtkAssistantPageFunc? = nil, data: gpointer! = nil, destroy: GDestroyNotify?)
    Show on GitHub

  • Sets whether page contents are complete.

    This will make assistant update the buttons state to be able to continue the task.

    Declaration

    Swift

    @inlinable
func setPageComplete<WidgetT>(page: WidgetT, complete: Bool) where WidgetT : WidgetProtocol
    Show on GitHub
  • setPageTitle(page:title:) Extension method

    Sets a title for page.

    The title is displayed in the header area of the assistant when page is the current page.

    Declaration

    Swift

    @inlinable
func setPageTitle<WidgetT>(page: WidgetT, title: UnsafePointer<CChar>!) where WidgetT : WidgetProtocol
    Show on GitHub
  • setPageType(page:type:) Extension method

    Sets the page type for page.

    The page type determines the page behavior in the assistant.

    Declaration

    Swift

    @inlinable
func setPageType<WidgetT>(page: WidgetT, type: GtkAssistantPageType) where WidgetT : WidgetProtocol
    Show on GitHub
  • updateButtonsState() Extension method

    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.

    Declaration

    Swift

    @inlinable
func updateButtonsState()
    Show on GitHub
  • currentPage Extension method

    Returns the page number of the current page.

    Declaration

    Swift

    @inlinable
var currentPage: Int { get nonmutating set }
    Show on GitHub
  • nPages Extension method

    Returns the number of pages in the assistant

    Declaration

    Swift

    @inlinable
var nPages: Int { get }
    Show on GitHub
  • pages Extension method

    GListModel containing the pages.

    Declaration

    Swift

    @inlinable
var pages: GIO.ListModelRef! { get }
    Show on GitHub