AssistantProtocol

public protocol AssistantProtocol : WindowProtocol

A GtkAssistant is a widget used to represent a generally complex operation splitted in several steps, guiding the user through its pages and controlling the page flow to collect the necessary data.

The design of GtkAssistant is that it controls what buttons to show and to make sensitive, based on what it knows about the page sequence and the type of each page, in addition to state information like the page completion and committed status.

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 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, and set its child properties as necessary.

CSS nodes

GtkAssistant has a single CSS node with the name 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

    The apply signal is 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 GtkAssistant::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

    The cancel signal is 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

    The close signal is 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

    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

    The prepare signal is 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::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 so the back button is not shown 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
  • getPageComplete(page:) Extension method

    Gets whether page is complete.

    Declaration

    Swift

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

    Gets whether page has padding.

    Declaration

    Swift

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

    Gets the header image for page.

    get_page_header_image is deprecated: Since GTK+ 3.2, a header is no longer shown; add your header decoration to the page content instead.

    Declaration

    Swift

    @available(*, deprecated)
@inlinable
func getPageHeaderImage<WidgetT>(page: WidgetT) -> PixbufRef! where WidgetT : WidgetProtocol
    Show on GitHub
  • getPageSideImage(page:) Extension method

    Gets the side image for page.

    get_page_side_image is deprecated: Since GTK+ 3.2, sidebar images are not shown anymore.

    Declaration

    Swift

    @available(*, deprecated)
@inlinable
func getPageSideImage<WidgetT>(page: WidgetT) -> PixbufRef! 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
  • 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

  • Sets whether the assistant is adding padding around the page.

    Declaration

    Swift

    @inlinable
func setPageHasPadding<WidgetT>(page: WidgetT, hasPadding: Bool) where WidgetT : WidgetProtocol
    Show on GitHub

  • Sets a header image for page.

    set_page_header_image is deprecated: Since GTK+ 3.2, a header is no longer shown; add your header decoration to the page content instead.

    Declaration

    Swift

    @available(*, deprecated)
@inlinable
func setPageHeaderImage<WidgetT>(page: WidgetT, pixbuf: PixbufRef? = nil) where WidgetT : WidgetProtocol
    Show on GitHub

  • Sets a header image for page.

    set_page_header_image is deprecated: Since GTK+ 3.2, a header is no longer shown; add your header decoration to the page content instead.

    Declaration

    Swift

    @available(*, deprecated)
@inlinable
func setPageHeaderImage<PixbufT, WidgetT>(page: WidgetT, pixbuf: PixbufT?) where PixbufT : PixbufProtocol, WidgetT : WidgetProtocol
    Show on GitHub

  • Sets a side image for page.

    This image used to be displayed in the side area of the assistant when page is the current page.

    set_page_side_image is deprecated: Since GTK+ 3.2, sidebar images are not shown anymore.

    Declaration

    Swift

    @available(*, deprecated)
@inlinable
func setPageSideImage<WidgetT>(page: WidgetT, pixbuf: PixbufRef? = nil) where WidgetT : WidgetProtocol
    Show on GitHub

  • Sets a side image for page.

    This image used to be displayed in the side area of the assistant when page is the current page.

    set_page_side_image is deprecated: Since GTK+ 3.2, sidebar images are not shown anymore.

    Declaration

    Swift

    @available(*, deprecated)
@inlinable
func setPageSideImage<PixbufT, WidgetT>(page: WidgetT, pixbuf: PixbufT?) where PixbufT : PixbufProtocol, 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<gchar>!) 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
  • parent Extension method

    Undocumented

    Declaration

    Swift

    @inlinable
var parent: GtkWindow { get }
    Show on GitHub