About all my projects
Gnome::Gtk4::Dialog

Gnome::Gtk4::Dialog

Description

Dialogs are a convenient way to prompt the user for a small amount of input.

No caption

Typical uses are to display a message, ask a question, or anything else that does not require extensive effort on the user’s part.

The main area of a Gnome::Gtk4::Dialog is called the "content area", and is yours to populate with widgets such a Gnome::Gtk4::Label or Gnome::Gtk4::Entry, to present your information, questions, or tasks to the user.

In addition, dialogs allow you to add "action widgets". Most commonly, action widgets are buttons. Depending on the platform, action widgets may be presented in the header bar at the top of the window, or at the bottom of the window. To add action widgets, create your Gnome::Gtk4::Dialog using .new-with-buttons(), or use .add-button(), .add-buttons(), or .add-action-widget().

GtkDialogs uses some heuristics to decide whether to add a close button to the window decorations. If any of the action buttons use the response ID GTK_RESPONSE_CLOSE or GTK_RESPONSE_CANCEL, the close button is omitted.

Clicking a button that was added as an action widget will emit the response signal 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 enumeration ResponseType from Gnome::Gtk4::T-dialog enumeration (these all have values less than zero). If a dialog receives a delete event, the response signal will be emitted with the GTK_RESPONSE_DELETE_EVENT response ID.

Dialogs are created with a call to .newdialog() or .new-with-buttons(). The latter is recommended; it allows you to set the dialog title, some convenient flags, and add buttons.

A “modal” dialog (that is, one which freezes the rest of the application from user input), can be created by calling .set-modal() in class Gnome::Gtk4::Window on the dialog. When using .new-with-buttons(), you can also pass the GTK_DIALOG_MODAL flag to make a dialog modal.

For the simple dialog in the following example, a Gnome::Gtk4::MessageDialog would save 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 Gnome::Gtk4::Dialog usage:

GtkDialog as GtkBuildable

The Gnome::Gtk4::Dialog implementation of the Gnome::Gtk4::R-Buildable interface exposes the $content-area as an internal child with the name “content_area”.

Gnome::Gtk4::Dialog 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.

Gnome::Gtk4::Dialog 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 Gnome::Gtk4::Dialog UI definition fragment:

Accessibility

Gnome::Gtk4::Dialog uses the GTK_ACCESSIBLE_ROLE_DIALOG role.

Class initialization

Note: The native version of this class is deprecated in gtk4-lib() since version 4.10

new

:native-object

Create an object using a native object from elsewhere. See also Gnome::N::TopLevelSupportClass.

multi method new ( N-Object :$native-object! )

new-dialog

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Creates a new dialog box.

Widgets should not be packed into the Gnome::Gtk4::Window directly, but into the $content-area and $action-area, as described above.

method new-dialog ( --> Gnome::Gtk4::Dialog \)

new-with-buttons This function is not yet available

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Creates a new Gnome::Gtk4::Dialog with the given title and transient parent.

The $flags argument can be used to make the dialog modal, have it destroyed along with its transient parent, or make it use a headerbar.

Button text/response ID pairs should be listed in pairs, with a undefined pointer ending the list. Button text can be arbitrary text. A response ID can be any positive number, or one of the values in the enumeration ResponseType from Gnome::Gtk4::T-dialog enumeration. If the user clicks one of these buttons, Gnome::Gtk4::Dialog will emit the response signal with the corresponding response ID.

If a Gnome::Gtk4::Dialog receives a delete event, it will emit response with a response ID of GTK_RESPONSE_DELETE_EVENT.

However, destroying a dialog does not emit the response signal; so be careful relying on response when using the GTK_DIALOG_DESTROY_WITH_PARENT flag.

Here’s a simple example:

method new-with-buttons ( Str $title, N-Object() $parent, UInt $flags, Str $first-button-text, … --> Gnome::Gtk4::Dialog \)

  • $title; Title of the dialog.

  • $parent; Transient parent of the dialog.

  • $flags; from bit field GtkDialogFlags defined in Gnome::Gtk4::T-dialog.

  • $first-button-text; text to go in first button.

  • …; …. Note that each argument must be specified as a type followed by its value!

Methods

add-action-widget

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Adds an activatable widget to the action area of a Gnome::Gtk4::Dialog.

GTK connects a signal handler that will emit the 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 Gnome::Gtk4::Dialog struct.

method add-action-widget ( N-Object() $child, Int() $response-id )

  • $child; an activatable widget.

  • $response-id; response ID for $child.

add-button

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Adds a button with the given text.

GTK arranges things so that clicking the button will emit the 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.

method add-button ( Str $button-text, Int() $response-id --> N-Object )

  • $button-text; text of button.

  • $response-id; response ID for the button.

Return value; the Gnome::Gtk4::Button widget that was added.

add-buttons This function is not yet available

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Adds multiple buttons.

This is the same as calling .add-button() repeatedly. The variable argument list should be undefined-terminated as with .new-with-buttons(). Each button must have both text and response ID.

method add-buttons ( Str $first-button-text, … )

  • $first-button-text; button text.

  • …; …. Note that each argument must be specified as a type followed by its value!

get-content-area

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Returns the content area of $dialog.

method get-content-area (--> N-Object )

Return value; the content area Gnome::Gtk4::Box..

get-header-bar

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Returns the header bar of $dialog.

Note that the headerbar is only used by the dialog if the use-header-bar property is True.

method get-header-bar (--> N-Object )

Return value; the header bar.

get-response-for-widget

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

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

method get-response-for-widget ( N-Object() $widget --> Int )

  • $widget; a widget in the action area of $dialog.

Return value; the response id of $widget, or GTK_RESPONSE_NONE if $widget doesn’t have a response id set..

get-widget-for-response

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

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

method get-widget-for-response ( Int() $response-id --> N-Object )

  • $response-id; the response ID used by the $dialog widget.

Return value; the $widget button that uses the given $response-id.

response

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Emits the response signal with the given response ID.

Used to indicate that the user has responded to the dialog in some way.

method response ( Int() $response-id )

  • $response-id; response ID.

set-default-response

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Sets the default widget for the dialog based on the response ID.

Pressing “Enter” normally activates the default widget.

method set-default-response ( Int() $response-id )

  • $response-id; a response ID.

set-response-sensitive

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

A convenient way to sensitize/desensitize dialog buttons.

Calls gtk_widget_set_sensitive (widget, $setting)` for each widget in the dialog’s action area with the given $response-id.

method set-response-sensitive ( Int() $response-id, Bool() $setting )

  • $response-id; a response ID.

  • $setting; True for sensitive.

Signals

close

Emitted when the user uses a keybinding to close the dialog.

This is a [keybinding signal](class.SignalAction.html).

The default binding for this signal is the Escape key.

method handler (
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::Dialog :$_widget,
  *C<user>-options
)

  • $_handle_id; The registered event handler id.

  • $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::Dialog object.

  • $_widget; The object which registered the signal. User code may have left the object going out of scope.

  • user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

response

Emitted when an action widget is clicked.

The signal is also emitted when the dialog receives a delete event, and when .response() is called. On a delete event, the response ID is GTK_RESPONSE_DELETE_EVENT. Otherwise, it depends on which action widget was clicked.

method handler (
  gint $response-id,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::Dialog :$_widget,
  *C<user>-options
)

  • $response-id; the response ID.

  • $_handle_id; The registered event handler id.

  • $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::Dialog object.

  • $_widget; The object which registered the signal. User code may have left the object going out of scope.

  • user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.