DialogProtocol

public protocol DialogProtocol : WindowProtocol

Dialog boxes are a convenient way to prompt the user for a small amount of input, e.g. to display a message, ask a question, or anything else that does not require extensive effort on the user’s part.

GTK+ treats a dialog as a window split vertically. The top section is a GtkVBox, and is where widgets such as a GtkLabel or a GtkEntry should be packed. The bottom area is known as the “action area”. This is generally used for packing buttons into the dialog which may perform functions such as cancel, ok, or apply.

GtkDialog boxes are created with a call to gtk_dialog_new() or gtk_dialog_new_with_buttons(). gtk_dialog_new_with_buttons() is recommended; it allows you to set the dialog title, some convenient flags, and add simple buttons.

If “dialog” is a newly created dialog, the two primary areas of the window can be accessed through gtk_dialog_get_content_area() and gtk_dialog_get_action_area(), as can be seen from the example below.

A “modal” dialog (that is, one which freezes the rest of the application from user input), can be created by calling gtk_window_set_modal() on the dialog. Use the GTK_WINDOW() macro to cast the widget returned from gtk_dialog_new() into a GtkWindow. When using gtk_dialog_new_with_buttons() you can also pass the GTK_DIALOG_MODAL flag to make a dialog modal.

If you add buttons to GtkDialog using gtk_dialog_new_with_buttons(), gtk_dialog_add_button(), gtk_dialog_add_buttons(), or gtk_dialog_add_action_widget(), clicking the button will emit a signal called GtkDialog::response with a response ID that you specified. GTK+ will never assign a meaning to positive response IDs; these are entirely user-defined. But for convenience, you can use the response IDs in the GtkResponseType enumeration (these all have values less than zero). If a dialog receives a delete event, the GtkDialog::response signal will be emitted with a response ID of GTK_RESPONSE_DELETE_EVENT.

If you want to block waiting for a dialog to return before returning control flow to your code, you can call gtk_dialog_run(). This function enters a recursive main loop and waits for the user to respond to the dialog, returning the response ID corresponding to the button the user clicked.

For the simple dialog in the following example, in reality you’d probably use GtkMessageDialog to save yourself some effort. But you’d need to create the dialog contents manually if you had more than a simple message in the dialog.

An example for simple GtkDialog usage: (C Language Example):

// Function to open a dialog box with a message
void
quick_message (GtkWindow *parent, gchar *message)
{
 GtkWidget *dialog, *label, *content_area;
 GtkDialogFlags flags;

 // Create the widgets
 flags = GTK_DIALOG_DESTROY_WITH_PARENT;
 dialog = gtk_dialog_new_with_buttons ("Message",
                                       parent,
                                       flags,
                                       _("_OK"),
                                       GTK_RESPONSE_NONE,
                                       NULL);
 content_area = gtk_dialog_get_content_area (GTK_DIALOG (dialog));
 label = gtk_label_new (message);

 // Ensure that the dialog box is destroyed when the user responds

 g_signal_connect_swapped (dialog,
                           "response",
                           G_CALLBACK (gtk_widget_destroy),
                           dialog);

 // Add the label, and show everything we’ve added

 gtk_container_add (GTK_CONTAINER (content_area), label);
 gtk_widget_show_all (dialog);
}

GtkDialog as GtkBuildable

The GtkDialog implementation of the GtkBuildable interface exposes the vbox and action_area as internal children with the names “vbox” and “action_area”.

GtkDialog supports a custom <action-widgets> element, which can contain multiple <action-widget> elements. The “response” attribute specifies a numeric response, and the content of the element is the id of widget (which should be a child of the dialogs action_area). To mark a response as default, set the “default“ attribute of the <action-widget> element to true.

GtkDialog supports adding action widgets by specifying “action“ as the “type“ attribute of a <child> element. The widget will be added either to the action area or the headerbar of the dialog, depending on the “use-header-bar“ property. The response id has to be associated with the action widget using the <action-widgets> element.

An example of a GtkDialog UI definition fragment:

<object class="GtkDialog" id="dialog1">
  <child type="action">
    <object class="GtkButton" id="button_cancel"/>
  </child>
  <child type="action">
    <object class="GtkButton" id="button_ok">
      <property name="can-default">True</property>
    </object>
  </child>
  <action-widgets>
    <action-widget response="cancel">button_cancel</action-widget>
    <action-widget response="ok" default="true">button_ok</action-widget>
  </action-widgets>
</object>

The DialogProtocol protocol exposes the methods and properties of an underlying GtkDialog 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 Dialog. Alternatively, use DialogRef 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 GtkDialog instance.

    Declaration

    Swift

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

    Typed pointer to the underlying GtkDialog instance.

    Default Implementation

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

    Declaration

    Swift

    var dialog_ptr: UnsafeMutablePointer<GtkDialog>! { get }
    Show on GitHub

  • Required Initialiser for types conforming to DialogProtocol

    Declaration

    Swift

    init(raw: UnsafeMutableRawPointer)
    Show on GitHub

Dialog Class

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

    Declaration

    Swift

    @discardableResult
@inlinable
func bind<Q, T>(property source_property: DialogPropertyName, 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 Dialog property

    Declaration

    Swift

    @inlinable
func get(property: DialogPropertyName) -> 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 Dialog property. Note that this will only have an effect on properties that are writable and not construct-only!

    Declaration

    Swift

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

    Parameters

    property

    the property to get the value for

    Return Value

    the value of the named property

    Show on GitHub

Dialog signals

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

    Declaration

    Swift

    @discardableResult
@inlinable
func connect(signal s: DialogSignalName, 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 DialogSignalName signal

    Declaration

    Swift

    @discardableResult
@inlinable
func connect(signal s: DialogSignalName, 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
  • onClose(flags:handler:) Extension method

    The close signal is a keybinding signal which gets emitted when the user uses a keybinding to close the dialog.

    The default binding for this signal is the Escape key.

    Note

    This represents the underlying close signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onClose(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: DialogRef) -> 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: DialogSignalName { get }
    Show on GitHub
  • onResponse(flags:handler:) Extension method

    Emitted when an action widget is clicked, the dialog receives a delete event, or the application programmer calls gtk_dialog_response(). On a delete event, the response ID is GTK_RESPONSE_DELETE_EVENT. Otherwise, it depends on which action widget was clicked.

    Note

    This represents the underlying response signal

    Declaration

    Swift

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

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    responseID

    the response ID
    handler

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

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

    Declaration

    Swift

    static var responseSignal: DialogSignalName { 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: DialogRef, _ 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: DialogSignalName { get }
    Show on GitHub

Dialog Class: DialogProtocol extension (methods and fields)

  • Adds an activatable widget to the action area of a GtkDialog, connecting a signal handler that will emit the GtkDialog::response signal on the dialog when the widget is activated. The widget is appended to the end of the dialog’s action area. If you want to add a non-activatable widget, simply pack it into the action_area field of the GtkDialog struct.

    Declaration

    Swift

    @inlinable
func addActionWidget<WidgetT>(child: WidgetT, responseID: Int) where WidgetT : WidgetProtocol
    Show on GitHub

  • Adds a button with the given text and sets things up so that clicking the button will emit the GtkDialog::response signal with the given response_id. The button is appended to the end of the dialog’s action area. The button widget is returned, but usually you don’t need it.

    Declaration

    Swift

    @inlinable
func addButton(buttonText: UnsafePointer<gchar>!, responseID: Int) -> WidgetRef!
    Show on GitHub
  • getActionArea() Extension method

    Returns the action area of dialog.

    get_action_area is deprecated: Direct access to the action area is discouraged; use gtk_dialog_add_button(), etc.

    Declaration

    Swift

    @available(*, deprecated)
@inlinable
func getActionArea() -> BoxRef!
    Show on GitHub
  • getContentArea() Extension method

    Returns the content area of dialog.

    Declaration

    Swift

    @inlinable
func getContentArea() -> BoxRef!
    Show on GitHub
  • getHeaderBar() Extension method

    Returns the header bar of dialog. Note that the headerbar is only used by the dialog if the GtkDialog:use-header-bar property is true.

    Declaration

    Swift

    @inlinable
func getHeaderBar() -> HeaderBarRef!
    Show on GitHub
  • getResponseFor(widget:) Extension method

    Gets the response id of a widget in the action area of a dialog.

    Declaration

    Swift

    @inlinable
func getResponseFor<WidgetT>(widget: WidgetT) -> Int where WidgetT : WidgetProtocol
    Show on GitHub

  • Gets the widget button that uses the given response ID in the action area of a dialog.

    Declaration

    Swift

    @inlinable
func getWidgetForResponse(responseID: Int) -> WidgetRef!
    Show on GitHub
  • response(responseID:) Extension method

    Emits the GtkDialog::response signal with the given response ID. Used to indicate that the user has responded to the dialog in some way; typically either you or gtk_dialog_run() will be monitoring the response signal and take appropriate action.

    Declaration

    Swift

    @inlinable
func response(responseID: Int)
    Show on GitHub
  • run() Extension method

    Blocks in a recursive main loop until the dialog either emits the GtkDialog::response signal, or is destroyed. If the dialog is destroyed during the call to gtk_dialog_run(), gtk_dialog_run() returns GTK_RESPONSE_NONE. Otherwise, it returns the response ID from the response signal emission.

    Before entering the recursive main loop, gtk_dialog_run() calls gtk_widget_show() on the dialog for you. Note that you still need to show any children of the dialog yourself.

    During gtk_dialog_run(), the default behavior of GtkWidget::delete-event is disabled; if the dialog receives delete_event, it will not be destroyed as windows usually are, and gtk_dialog_run() will return GTK_RESPONSE_DELETE_EVENT. Also, during gtk_dialog_run() the dialog will be modal. You can force gtk_dialog_run() to return at any time by calling gtk_dialog_response() to emit the response signal. Destroying the dialog during gtk_dialog_run() is a very bad idea, because your post-run code won’t know whether the dialog was destroyed or not.

    After gtk_dialog_run() returns, you are responsible for hiding or destroying the dialog if you wish to do so.

    Typical usage of this function might be: (C Language Example):

      GtkWidget *dialog = gtk_dialog_new ();
  // Set up dialog...

  int result = gtk_dialog_run (GTK_DIALOG (dialog));
  switch (result)
    {
      case GTK_RESPONSE_ACCEPT:
         // do_application_specific_something ();
         break;
      default:
         // do_nothing_since_dialog_was_cancelled ();
         break;
    }
  gtk_widget_destroy (dialog);

    Note that even though the recursive main loop gives the effect of a modal dialog (it prevents the user from interacting with other windows in the same window group while the dialog is run), callbacks such as timeouts, IO channel watches, DND drops, etc, will be triggered during a gtk_dialog_run() call.

    Declaration

    Swift

    @inlinable
func run() -> Int
    Show on GitHub

  • Sets an alternative button order. If the GtkSettings:gtk-alternative-button-order setting is set to true, the dialog buttons are reordered according to the order of the response ids in new_order.

    See gtk_dialog_set_alternative_button_order() for more information.

    This function is for use by language bindings.

    set_alternative_button_order_from_array is deprecated: Deprecated

    Declaration

    Swift

    @available(*, deprecated)
@inlinable
func setAlternativeButtonOrderFromArray(nParams: Int, newOrder: UnsafeMutablePointer<gint>!)
    Show on GitHub

  • Sets the last widget in the dialog’s action area with the given response_id as the default widget for the dialog. Pressing “Enter” normally activates the default widget.

    Declaration

    Swift

    @inlinable
func setDefaultResponse(responseID: Int)
    Show on GitHub

  • Calls gtk_widget_set_sensitive (widget,setting) for each widget in the dialog’s action area with the given response_id. A convenient way to sensitize/desensitize dialog buttons.

    Declaration

    Swift

    @inlinable
func setResponseSensitive(responseID: Int, setting: Bool)
    Show on GitHub
  • actionArea Extension method

    Returns the action area of dialog.

    get_action_area is deprecated: Direct access to the action area is discouraged; use gtk_dialog_add_button(), etc.

    Declaration

    Swift

    @inlinable
var actionArea: BoxRef! { get }
    Show on GitHub
  • contentArea Extension method

    Returns the content area of dialog.

    Declaration

    Swift

    @inlinable
var contentArea: BoxRef! { get }
    Show on GitHub
  • headerBar Extension method

    Returns the header bar of dialog. Note that the headerbar is only used by the dialog if the GtkDialog:use-header-bar property is true.

    Declaration

    Swift

    @inlinable
var headerBar: HeaderBarRef! { get }
    Show on GitHub
  • window Extension method

    Undocumented

    Declaration

    Swift

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