Adw.MessageDialog¶

Subclasses:: None

Methods¶

Inherited:: Gtk.Window (62), Gtk.Widget (181), GObject.Object (37), Gtk.Accessible (15), Gtk.Buildable (1), Gtk.Native (6), Gtk.Root (3)
Structs:: Gtk.WidgetClass (18), GObject.ObjectClass (5)

class	`new` (parent, heading, body)
	`add_response` (id, label)
	`choose` (cancellable, callback, *user_data)
	`choose_finish` (result)
	`get_body` ()
	`get_body_use_markup` ()
	`get_close_response` ()
	`get_default_response` ()
	`get_extra_child` ()
	`get_heading` ()
	`get_heading_use_markup` ()
	`get_response_appearance` (response)
	`get_response_enabled` (response)
	`get_response_label` (response)
	`has_response` (response)
	`remove_response` (id)
	`response` (response)
	`set_body` (body)
	`set_body_use_markup` (use_markup)
	`set_close_response` (response)
	`set_default_response` (response)
	`set_extra_child` (child)
	`set_heading` (heading)
	`set_heading_use_markup` (use_markup)
	`set_response_appearance` (response, appearance)
	`set_response_enabled` (response, enabled)
	`set_response_label` (response, label)

Virtual Methods¶

Inherited:: Gtk.Window (5), Gtk.Widget (25), GObject.Object (7), Gtk.Accessible (6), Gtk.Buildable (9), Gtk.ShortcutManager (2)

do_response (response)

Properties¶

Inherited:: Gtk.Window (25), Gtk.Widget (34), Gtk.Accessible (1)

Name	Type	Flags
`body`	`str`	r/w/en
`body-use-markup`	`bool`	r/w/en
`close-response`	`str`	r/w/en
`default-response`	`str`	r/w/en
`extra-child`	`Gtk.Widget`	r/w/en
`heading`	`str`	r/w/en
`heading-use-markup`	`bool`	r/w/en

Signals¶

Inherited:: Gtk.Window (5), Gtk.Widget (13), GObject.Object (1)

Name	Short Description
`response`	This signal is emitted when the dialog is closed.

Fields¶

Inherited:: Gtk.Window (5), Gtk.Widget (13), GObject.Object (1)

Name	Type	Access	Description
parent_instance	`Gtk.Window`	r

Class Details¶

class Adw.MessageDialog(*args, **kwargs)¶

Bases:: Gtk.Window
Abstract:: No
Structure:: Adw.MessageDialogClass

A dialog presenting a message or a question.

Message dialogs have a heading, a body, an optional child widget, and one or multiple responses, each presented as a button.

Each response has a unique string ID, and a button label. Additionally, each response can be enabled or disabled, and can have a suggested or destructive appearance.

When one of the responses is activated, or the dialog is closed, the [signal`MessageDialog`:py:func:::response<Adw.MessageDialog.signals.response>] signal will be emitted. This signal is detailed, and the detail, as well as the response parameter will be set to the ID of the activated response, or to the value of the [property`MessageDialog`:py:data::close-response<Adw.MessageDialog.props.close_response>] property if the dialog had been closed without activating any of the responses.

Response buttons can be presented horizontally or vertically depending on available space.

When a response is activated, AdwMessageDialog is closed automatically.

An example of using a message dialog:

```c Gtk.Widget *dialog;

dialog = Adw.MessageDialog.new (parent, _(“Replace File?”), None);

adw_message_dialog_format_body (ADW_MESSAGE_DIALOG (dialog), _(“A file named “%s” already exists. Do you want to replace it?”), filename);

adw_message_dialog_add_responses (ADW_MESSAGE_DIALOG (dialog), “cancel”, _(”_Cancel”), “replace”, _(”_Replace”), None);

Adw.MessageDialog.set_response_appearance (ADW_MESSAGE_DIALOG (dialog), “replace”, Adw.ResponseAppearance.DESTRUCTIVE);

Adw.MessageDialog.set_default_response (ADW_MESSAGE_DIALOG (dialog), “cancel”); Adw.MessageDialog.set_close_response (ADW_MESSAGE_DIALOG (dialog), “cancel”);

g_signal_connect (dialog, “response”, G_CALLBACK (response_cb), self);

Gtk.Window.present (GTK_WINDOW (dialog)); ```

Async API

AdwMessageDialog can also be used via the [method`MessageDialog`.choose] method. This API follows the GIO async pattern, and the result can be obtained by calling [method`MessageDialog`.choose_finish], for example:

```c static void dialog_cb (Adw.MessageDialog *dialog, Gio.AsyncResult *result, MyWindow *self) { const str *response = Adw.MessageDialog.choose_finish (dialog, result);

// … }

static void show_dialog (MyWindow *self) { Gtk.Widget *dialog;

dialog = Adw.MessageDialog.new (GTK_WINDOW (self), _(“Replace File?”), None);

adw_message_dialog_format_body (ADW_MESSAGE_DIALOG (dialog), _(“A file named “%s” already exists. Do you want to replace it?”), filename);

adw_message_dialog_add_responses (ADW_MESSAGE_DIALOG (dialog), “cancel”, _(”_Cancel”), “replace”, _(”_Replace”), None);

Adw.MessageDialog.set_response_appearance (ADW_MESSAGE_DIALOG (dialog), “replace”, Adw.ResponseAppearance.DESTRUCTIVE);

Adw.MessageDialog.set_default_response (ADW_MESSAGE_DIALOG (dialog), “cancel”); Adw.MessageDialog.set_close_response (ADW_MESSAGE_DIALOG (dialog), “cancel”);

Adw.MessageDialog.choose (ADW_MESSAGE_DIALOG (dialog), None, (Gio.AsyncReadyCallback) dialog_cb, self); } ```

Adw.MessageDialog as Gtk.Buildable

AdwMessageDialog supports adding responses in UI definitions by via the <responses> element that may contain multiple <response> elements, each respresenting a response.

Each of the <response> elements must have the id attribute specifying the response ID. The contents of the element are used as the response label.

Response labels can be translated with the usual translatable, context and comments attributes.

The <response> elements can also have enabled and/or appearance attributes. See [method`MessageDialog`.set_response_enabled] and [method`MessageDialog`.set_response_appearance] for details.

Example of an AdwMessageDialog UI definition:

``xml <object class=”AdwMessageDialog” id=”dialog”>

<property name=”heading” translatable=”yes”>Save Changes?</property> <property name=”body” translatable=”yes”>Open documents contain unsaved changes. Changes which are not saved will be permanently lost.</property> <property name=”default-response”>save</property> <property name=”close-response”>cancel</property> <signal name=”response” handler=”response_cb”/> <responses>

<response id=”cancel” translatable=”yes”>_Cancel</response> <response id=”discard” translatable=”yes” appearance=”destructive”>_Discard</response> <response id=”save” translatable=”yes” appearance=”suggested” enabled=”false”>_Save</response>

</responses>

</object> ``

Accessibility

AdwMessageDialog uses the GTK_ACCESSIBLE_ROLE_DIALOG role.

New in version 1.2.

classmethod new(parent, heading, body)¶

Parameters:

parent (Gtk.Window or None) – transient parent
heading (str or None) – the heading
body (str or None) – the body text

Returns:

the newly created AdwMessageDialog

Return type:

Gtk.Widget

Creates a new AdwMessageDialog.

heading and body can be set to NULL. This can be useful if they need to be formatted or use markup. In that case, set them to NULL and call [method`MessageDialog`.format_body] or similar methods afterwards:

```c Gtk.Widget *dialog;

dialog = Adw.MessageDialog.new (parent, _(“Replace File?”), None); adw_message_dialog_format_body (ADW_MESSAGE_DIALOG (dialog), _(“A file named “%s” already exists. Do you want to replace it?”), filename); ```

New in version 1.2.

add_response(id, label)¶

Parameters:

id (str) – the response ID
label (str) – the response label

Adds a response with id and label to self.

Responses are represented as buttons in the dialog.

Response ID must be unique. It will be used in [signal`MessageDialog`:py:func:::response<Adw.MessageDialog.signals.response>] to tell which response had been activated, as well as to inspect and modify the response later.

An embedded underline in label indicates a mnemonic.

[method`MessageDialog`.set_response_label] can be used to change the response label after it had been added.

[method`MessageDialog`.set_response_enabled] and [method`MessageDialog`.set_response_appearance] can be used to customize the responses further.

New in version 1.2.

choose(cancellable, callback, *user_data)¶

Parameters:

cancellable (Gio.Cancellable or None) – a GCancellable to cancel the operation
callback (Gio.AsyncReadyCallback or None) – a callback to call when the operation is complete
user_data (object or None) – data to pass to callback

This function shows self to the user.

The callback will be called when the alert is dismissed. It should call [method`MessageDialog`.choose_finish] to obtain the result.

New in version 1.3.

choose_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a GAsyncResult
Returns:: the ID of the response that was selected, or [property`MessageDialog`:py:data::close-response<Adw.MessageDialog.props.close_response>] if the call was cancelled.
Return type:: str

Finishes the [method`MessageDialog`.choose] call and returns the response ID.

New in version 1.3.

get_body()¶

Returns:: the body of self.
Return type:: str

Gets the body text of self.

New in version 1.2.

get_body_use_markup()¶

Returns:: whether self uses markup for body text
Return type:: bool

Gets whether the body text of self includes Pango markup.

New in version 1.2.

get_close_response()¶

Returns:: the close response ID
Return type:: str

Gets the ID of the close response of self.

New in version 1.2.

get_default_response()¶

Returns:: the default response ID
Return type:: str or None

Gets the ID of the default response of self.

New in version 1.2.

get_extra_child()¶

Returns:: the child widget of self.
Return type:: Gtk.Widget or None

Gets the child widget of self.

New in version 1.2.

get_heading()¶

Returns:: the heading of self.
Return type:: str or None

Gets the heading of self.

New in version 1.2.

get_heading_use_markup()¶

Returns:: whether self uses markup for heading
Return type:: bool

Gets whether the heading of self includes Pango markup.

New in version 1.2.

get_response_appearance(response)¶

Parameters:: response (str) – a response ID
Returns:: the appearance of response
Return type:: Adw.ResponseAppearance

Gets the appearance of response.

See [method`MessageDialog`.set_response_appearance].

New in version 1.2.

get_response_enabled(response)¶

Parameters:: response (str) – a response ID
Returns:: whether response is enabled
Return type:: bool

Gets whether response is enabled.

See [method`MessageDialog`.set_response_enabled].

New in version 1.2.

get_response_label(response)¶

Parameters:: response (str) – a response ID
Returns:: the label of response
Return type:: str

Gets the label of response.

See [method`MessageDialog`.set_response_label].

New in version 1.2.

has_response(response)¶

Parameters:: response (str) – response ID
Returns:: whether self has a response with the ID response.
Return type:: bool

Gets whether self has a response with the ID response.

New in version 1.2.

remove_response(id)¶

Parameters:: id (str) – the response ID

Removes a response from self.

New in version 1.5.

response(response)¶

Parameters:: response (str) – response ID

Emits the [signal`MessageDialog`:py:func:::response<Adw.MessageDialog.signals.response>] signal with the given response ID.

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

New in version 1.2.

set_body(body)¶

Parameters:: body (str) – the body of self

Sets the body text of self.

New in version 1.2.

set_body_use_markup(use_markup)¶

Parameters:: use_markup (bool) – whether to use markup for body text

Sets whether the body text of self includes Pango markup.

See [func`Pango`.parse_markup].

New in version 1.2.

set_close_response(response)¶

Parameters:: response (str) – the close response ID

Sets the ID of the close response of self.

It will be passed to [signal`MessageDialog`:py:func:::response<Adw.MessageDialog.signals.response>] if the window is closed by pressing <kbd>Escape</kbd> or with a system action.

It doesn’t have to correspond to any of the responses in the dialog.

The default close response is close.

New in version 1.2.

set_default_response(response)¶

Parameters:: response (str or None) – the default response ID

Sets the ID of the default response of self.

If set, pressing <kbd>Enter</kbd> will activate the corresponding button.

If set to NULL or to a non-existent response ID, pressing <kbd>Enter</kbd> will do nothing.

New in version 1.2.

set_extra_child(child)¶

Parameters:: child (Gtk.Widget or None) – the child widget

Sets the child widget of self.

The child widget is displayed below the heading and body.

New in version 1.2.

set_heading(heading)¶

Parameters:: heading (str or None) – the heading of self

Sets the heading of self.

New in version 1.2.

set_heading_use_markup(use_markup)¶

Parameters:: use_markup (bool) – whether to use markup for heading

Sets whether the heading of self includes Pango markup.

See [func`Pango`.parse_markup].

New in version 1.2.

set_response_appearance(response, appearance)¶

Parameters:

response (str) – a response ID
appearance (Adw.ResponseAppearance) – appearance for response

Sets the appearance for response.

Use ADW_RESPONSE_SUGGESTED to mark important responses such as the affirmative action, like the Save button in the example.

Use ADW_RESPONSE_DESTRUCTIVE to draw attention to the potentially damaging consequences of using response. This appearance acts as a warning to the user. The Discard button in the example is using this appearance.

The default appearance is ADW_RESPONSE_DEFAULT.

Negative responses like Cancel or Close should use the default appearance.

New in version 1.2.

set_response_enabled(response, enabled)¶

Parameters:

response (str) – a response ID
enabled (bool) – whether to enable response

Sets whether response is enabled.

If response is not enabled, the corresponding button will have [property`Gtk`.Widget:sensitive] set to FALSE and it can’t be activated as a default response.

response can still be used as [property`MessageDialog`:py:data::close-response<Adw.MessageDialog.props.close_response>] while it’s not enabled.

Responses are enabled by default.

New in version 1.2.

set_response_label(response, label)¶

Parameters:

response (str) – a response ID
label (str) – the label of response

Sets the label of response to label.

Labels are displayed on the dialog buttons. An embedded underline in label indicates a mnemonic.

New in version 1.2.

do_response(response) virtual¶

Parameters:: response (str) – response ID

Emits the [signal`MessageDialog`:py:func:::response<Adw.MessageDialog.signals.response>] signal with the given response ID.

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

New in version 1.2.

Signal Details¶

Adw.MessageDialog.signals.response(message_dialog, response)¶

Signal Name:

response

Flags:

RUN_LAST, DETAILED

Parameters:

message_dialog (Adw.MessageDialog) – The object which received the signal
response (str) – the response ID

This signal is emitted when the dialog is closed.

response will be set to the response ID of the button that had been activated.

if the dialog was closed by pressing <kbd>Escape</kbd> or with a system action, response will be set to the value of [property`MessageDialog`:py:data::close-response<Adw.MessageDialog.props.close_response>].

New in version 1.2.

Property Details¶

Adw.MessageDialog.props.body¶

Name:: body
Type:: str
Default Value:: ''
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The body text of the dialog.

New in version 1.2.

Adw.MessageDialog.props.body_use_markup¶

Name:: body-use-markup
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether the body text includes Pango markup.

See [func`Pango`.parse_markup].

New in version 1.2.

Adw.MessageDialog.props.close_response¶

Name:: close-response
Type:: str
Default Value:: 'close'
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The ID of the close response.

It will be passed to [signal`MessageDialog`:py:func:::response<Adw.MessageDialog.signals.response>] if the window is closed by pressing <kbd>Escape</kbd> or with a system action.

It doesn’t have to correspond to any of the responses in the dialog.

The default close response is close.

New in version 1.2.

Adw.MessageDialog.props.default_response¶

Name:: default-response
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The response ID of the default response.

If set, pressing <kbd>Enter</kbd> will activate the corresponding button.

If set to NULL or a non-existent response ID, pressing <kbd>Enter</kbd> will do nothing.

New in version 1.2.

Adw.MessageDialog.props.extra_child¶

Name:: extra-child
Type:: Gtk.Widget
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The child widget.

Displayed below the heading and body.

New in version 1.2.

Adw.MessageDialog.props.heading¶

Name:: heading
Type:: str
Default Value:: ''
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The heading of the dialog.

New in version 1.2.

Adw.MessageDialog.props.heading_use_markup¶

Name:: heading-use-markup
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether the heading includes Pango markup.

See [func`Pango`.parse_markup].

New in version 1.2.