Struct AboutDialog

Source

pub struct AboutDialog { /* private fields */ }

Available on crate feature v1_5 only.

Expand description

A dialog showing information about the application.

an about dialog is typically opened when the user activates the About … item in the application’s primary menu. All parts of the dialog are optional.

§Main page

AboutDialog prominently displays the application’s icon, name, developer name and version. They can be set with the application-icon, application-name, developer-name and version respectively.

§What’s New

AboutDialog provides a way for applications to display their release notes, set with the release-notes property.

Release notes are formatted the same way as AppStream descriptions.

The supported formatting options are:

Paragraph ()
Ordered list (<ol>), with list items (<li>)
Unordered list (<ul>), with list items (<li>)

Within paragraphs and list items, emphasis () and inline code (<code>) text styles are supported. The emphasis is rendered in italic, while inline code is shown in a monospaced font.

Any text outside paragraphs or list items is ignored.

Nested lists are not supported.

Only one version can be shown at a time. By default, the displayed version number matches version. Use release-notes-version to override it.

§Details

The Details page displays the application comments and links.

The comments can be set with the comments property. Unlike [comments][struct@crate::Gtk::AboutDialog#comments], this string can be long and detailed. It can also contain links and Pango markup.

To set the application website, use website. To add extra links below the website, use add_link().

If the Details page doesn’t have any other content besides website, the website will be displayed on the main page instead.

§Troubleshooting

AboutDialog displays the following two links on the main page:

Support Questions, set with the support-url property,
Report an Issue, set with the issue-url property.

Additionally, applications can provide debugging information. It will be shown separately on the Troubleshooting page. Use the debug-info property to specify it.

It’s intended to be attached to issue reports when reporting issues against the application. As such, it cannot contain markup or links.

AboutDialog provides a quick way to save debug information to a file. When saving, debug-info-filename would be used as the suggested filename.

§Credits and Acknowledgements

The Credits page has the following default sections:

Developers, set with the developers property,
Designers, set with the designers property,
Artists, set with the artists property,
Documenters, set with the documenters property,
Translators, set with the translator-credits property.

When setting translator credits, use the strings "translator-credits" or "translator_credits" and mark them as translatable.

The default sections that don’t contain any names won’t be displayed.

The Credits page can also contain an arbitrary number of extra sections below the default ones. Use add_credit_section() to add them.

The Acknowledgements page can be used to acknowledge additional people and organizations for their non-development contributions. Use add_acknowledgement_section() to add sections to it. For example, it can be used to list backers in a crowdfunded project or to give special thanks.

Each of the people or organizations can have an email address or a website specified. To add a email address, use a string like Edgar Allan Poe <edgar@poe.com>. To specify a website with a title, use a string like The GNOME Project https://www.gnome.org:

§Legal

The Legal page displays the copyright and licensing information for the application and other modules.

Licensing information can be quickly set from a list of known licenses with the license-type property. If the application’s license is not in the list, license can be used instead.

To add information about other modules, such as application dependencies or data, use add_legal_section().

§Other applications

AboutDialog can show links to your other apps at the end of the main page. To add them, use add_other_app().

§Constructing

To make constructing an AboutDialog as convenient as possible, you can use the function show_about_dialog() which constructs and shows a dialog.

⚠️ The following code is in c ⚠️

static void
show_about (GtkApplication *app)
{
  const char *developers[] = {
    "Angela Avery",
    NULL
  };

  const char *designers[] = {
    "GNOME Design Team",
    NULL
  };

  adw_show_about_dialog (GTK_WIDGET (gtk_application_get_active_window (app)),
                         "application-name", _("Example"),
                         "application-icon", "org.example.App",
                         "version", "1.2.3",
                         "copyright", "© 2022 Angela Avery",
                         "issue-url", "https://gitlab.gnome.org/example/example/-/issues/",
                         "license-type", GTK_LICENSE_GPL_3_0,
                         "developers", developers,
                         "designers", designers,
                         "translator-credits", _("translator-credits"),
                         NULL);
}

§CSS nodes

AboutDialog has a main CSS node with the name dialog and the style class .about.

§Properties

§`application-icon`

The name of the application icon.

The icon is displayed at the top of the main page.

Readable | Writeable

§`application-name`

The name of the application.

The name is displayed at the top of the main page.

Readable | Writeable

§`artists`

The list of artists of the application.

It will be displayed on the Credits page.

Each name may contain email addresses and URLs, see the introduction for more details.

See also:

Readable | Writeable

§`comments`

The comments about the application.

Comments will be shown on the Details page, above links.

Unlike [comments][struct@crate::Gtk::AboutDialog#comments], this string can be long and detailed. It can also contain links and Pango markup.

Readable | Writeable

§`copyright`

The copyright information.

The copyright information will be displayed on the Legal page, above the application license.

AboutDialog::add_legal_section() can be used to add copyright information for the application dependencies or other components.

Readable | Writeable

§`debug-info`

The debug information.

Debug information will be shown on the Troubleshooting page. It’s intended to be attached to issue reports when reporting issues against the application.

AboutDialog provides a quick way to save debug information to a file. When saving, debug-info-filename would be used as the suggested filename.

Debug information cannot contain markup or links.

Readable | Writeable

§`debug-info-filename`

The debug information filename.

It will be used as the suggested filename when saving debug information to a file.

See debug-info.

Readable | Writeable

§`designers`

The list of designers of the application.

It will be displayed on the Credits page.

Each name may contain email addresses and URLs, see the introduction for more details.

See also:

Readable | Writeable

§`developer-name`

The developer name.

The developer name is displayed on the main page, under the application name.

If the application is developed by multiple people, the developer name can be set to values like “AppName team”, “AppName developers” or “The AppName project”, and the individual contributors can be listed on the Credits page, with developers and related properties.

Readable | Writeable

§`developers`

The list of developers of the application.

It will be displayed on the Credits page.

Each name may contain email addresses and URLs, see the introduction for more details.

See also:

Readable | Writeable

§`documenters`

The list of documenters of the application.

It will be displayed on the Credits page.

Each name may contain email addresses and URLs, see the introduction for more details.

See also:

Readable | Writeable

§`issue-url`

The URL for the application’s issue tracker.

The issue tracker link is displayed on the main page.

Readable | Writeable

§`license`

The license text.

This can be used to set a custom text for the license if it can’t be set via license-type.

When set, license-type will be set to GTK_LICENSE_CUSTOM.

The license text will be displayed on the Legal page, below the copyright information.

License text can contain Pango markup and links.

AboutDialog::add_legal_section() can be used to add license information for the application dependencies or other components.

Readable | Writeable

§`license-type`

The license type.

Allows to set the application’s license froma list of known licenses.

If the application’s license is not in the list, license can be used instead. The license type will be automatically set to GTK_LICENSE_CUSTOM in that case.

If set to GTK_LICENSE_UNKNOWN, no information will be displayed.

If the license type is different from GTK_LICENSE_CUSTOM. license will be cleared out.

The license description will be displayed on the Legal page, below the copyright information.

AboutDialog::add_legal_section() can be used to add license information for the application dependencies or other components.

Readable | Writeable

§`release-notes`

The release notes of the application.

Release notes are displayed on the the What’s New page.

Release notes are formatted the same way as AppStream descriptions.

The supported formatting options are:

Paragraph ()
Ordered list (<ol>), with list items (<li>)
Unordered list (<ul>), with list items (<li>)

Within paragraphs and list items, emphasis () and inline code (<code>) text styles are supported. The emphasis is rendered in italic, while inline code is shown in a monospaced font.

Any text outside paragraphs or list items is ignored.

Nested lists are not supported.

AboutDialog displays the version above the release notes. If set, the release-notes-version of the property will be used as the version; otherwise, version is used.

Readable | Writeable

§`release-notes-version`

The version described by the application’s release notes.

The release notes version is displayed on the What’s New page, above the release notes.

If not set, version will be used instead.

For example, an application with the current version 2.0.2 might want to keep the release notes from 2.0.0, and set the release notes version accordingly.

See release-notes.

Readable | Writeable

§`support-url`

The URL of the application’s support page.

The support page link is displayed on the main page.

Readable | Writeable

§`translator-credits`

The translator credits string.

It will be displayed on the Credits page.

This string should be "translator-credits" or "translator_credits" and should be marked as translatable.

The string may contain email addresses and URLs, see the introduction for more details.

See also:

Readable | Writeable

§`version`

The version of the application.

The version is displayed on the main page.

If release-notes-version is not set, the version will also be displayed above the release notes on the What’s New page.

Readable | Writeable

§`website`

The URL of the application’s website.

Website is displayed on the Details page, below comments, or on the main page if the Details page doesn’t have any other content.

Applications can add other links below, see AboutDialog::add_link().

Readable | Writeable

Dialog

§`can-close`

Whether the dialog can be closed.

If set to FALSE, the close button, shortcuts and AdwDialogExt::close() will result in close-attempt being emitted instead, and bottom sheet close swipe will be disabled. AdwDialogExt::force_close() still works.

Readable | Writeable

§`child`

The child widget of the Dialog.

Readable | Writeable

§`content-height`

The height of the dialog’s contents.

Set it to -1 to reset it to the content’s natural height.

§`content-width`

The width of the dialog’s contents.

Set it to -1 to reset it to the content’s natural width.

§`current-breakpoint`

The current breakpoint.

Readable

§`default-widget`

The default widget.

It’s activated when the user presses Enter.

Readable | Writeable

§`focus-widget`

The focus widget.

Readable | Writeable

§`follows-content-size`

Whether to size content automatically.

If set to TRUE, always use the content’s natural size instead of content-width and content-height. If the content resizes, the dialog will immediately resize as well.

§`presentation-mode`

The dialog’s presentation mode.

When set to ADW_DIALOG_AUTO, the dialog appears as a bottom sheet when the following condition is met: max-width: 450px or max-height: 360px, and as a floating window otherwise.

Set it to ADW_DIALOG_FLOATING or ADW_DIALOG_BOTTOM_SHEET to always present it a floating window or a bottom sheet respectively, regardless of available size.

Presentation mode does nothing for dialogs presented as a window.

Readable | Writeable

§`title`

The title of the dialog.

Readable | Writeable

Widget

§`can-focus`

Whether the widget or any of its descendents can accept the input focus.

This property is meant to be set by widget implementations, typically in their instance init function.

Readable | Writeable

§`can-target`

Whether the widget can receive pointer events.

Readable | Writeable

§`css-classes`

A list of css classes applied to this widget.

Readable | Writeable

§`css-name`

The name of this widget in the CSS tree.

This property is meant to be set by widget implementations, typically in their instance init function.

Readable | Writeable | Construct Only

§`cursor`

The cursor used by @widget.

Readable | Writeable

§`focus-on-click`

Whether the widget should grab focus when it is clicked with the mouse.

This property is only relevant for widgets that can take focus.

Readable | Writeable

§`focusable`

Whether this widget itself will accept the input focus.

Readable | Writeable

§`halign`

How to distribute horizontal space if widget gets extra space.

Readable | Writeable

§`has-default`

Whether the widget is the default widget.

Readable

§`has-focus`

Whether the widget has the input focus.

Readable

§`has-tooltip`

Enables or disables the emission of the query-tooltip signal on @widget.

A true value indicates that @widget can have a tooltip, in this case the widget will be queried using query-tooltip to determine whether it will provide a tooltip or not.

Readable | Writeable

§`height-request`

Overrides for height request of the widget.

If this is -1, the natural request will be used.

Readable | Writeable

§`hexpand`

Whether to expand horizontally.

Readable | Writeable

§`hexpand-set`

Whether to use the hexpand property.

Readable | Writeable

§`layout-manager`

The gtk::LayoutManager instance to use to compute the preferred size of the widget, and allocate its children.

This property is meant to be set by widget implementations, typically in their instance init function.

Readable | Writeable

§`limit-events`

Makes this widget act like a modal dialog, with respect to event delivery.

Global event controllers will not handle events with targets inside the widget, unless they are set up to ignore propagation limits. See Gtk::EventController::set_propagation_limit().

Readable | Writeable

§`margin-bottom`

Margin on bottom side of widget.

This property adds margin outside of the widget’s normal size request, the margin will be added in addition to the size from [WidgetExtManual::set_size_request()][crate::gtk::prelude::WidgetExtManual::set_size_request()] for example.

Readable | Writeable

§`margin-end`

Margin on end of widget, horizontally.

This property supports left-to-right and right-to-left text directions.

Readable | Writeable

§`margin-start`

Margin on start of widget, horizontally.

This property supports left-to-right and right-to-left text directions.

Readable | Writeable

§`margin-top`

Margin on top side of widget.

Readable | Writeable

§`name`

The name of the widget.

Readable | Writeable

§`opacity`

The requested opacity of the widget.

Readable | Writeable

§`overflow`

How content outside the widget’s content area is treated.

This property is meant to be set by widget implementations, typically in their instance init function.

Readable | Writeable

§`parent`

The parent widget of this widget.

Readable

§`receives-default`

Whether the widget will receive the default action when it is focused.

Readable | Writeable

§`root`

The gtk::Root widget of the widget tree containing this widget.

This will be NULL if the widget is not contained in a root widget.

Readable

§`scale-factor`

The scale factor of the widget.

Readable

§`sensitive`

Whether the widget responds to input.

Readable | Writeable

§`tooltip-markup`

Sets the text of tooltip to be the given string, which is marked up with Pango markup.

Also see Gtk::Tooltip::set_markup().

This is a convenience property which will take care of getting the tooltip shown if the given string is not NULL: has-tooltip will automatically be set to true and there will be taken care of query-tooltip in the default signal handler.

Note that if both tooltip-text and tooltip-markup are set, the last one wins.

Readable | Writeable

§`tooltip-text`

Sets the text of tooltip to be the given string.

Also see Gtk::Tooltip::set_text().

Note that if both tooltip-text and tooltip-markup are set, the last one wins.

Readable | Writeable

§`valign`

How to distribute vertical space if widget gets extra space.

Readable | Writeable

§`vexpand`

Whether to expand vertically.

Readable | Writeable

§`vexpand-set`

Whether to use the vexpand property.

Readable | Writeable

§`visible`

Whether the widget is visible.

Readable | Writeable

§`width-request`

Overrides for width request of the widget.

If this is -1, the natural request will be used.

Readable | Writeable

Accessible

§`accessible-role`

The accessible role of the given gtk::Accessible implementation.

The accessible role cannot be changed once set.

Readable | Writeable

§Signals

§`activate-link`

Emitted when a URL is activated.

Applications may connect to it to override the default behavior, which is to call show_uri().

Dialog

§`close-attempt`

Emitted when the close button or shortcut is used, or AdwDialogExt::close() is called while can-close is set to FALSE.

§`closed`

Emitted when the dialog is successfully closed.

Widget

§`destroy`

Signals that all holders of a reference to the widget should release the reference that they hold.

May result in finalization of the widget if all references are released.

This signal is not suitable for saving widget state.

§`direction-changed`

Emitted when the text direction of a widget changes.

§`hide`

Emitted when @widget is hidden.

§`keynav-failed`

Emitted if keyboard navigation fails.

See [WidgetExtManual::keynav_failed()][crate::gtk::prelude::WidgetExtManual::keynav_failed()] for details.

§`map`

Emitted when @widget is going to be mapped.

A widget is mapped when the widget is visible (which is controlled with visible) and all its parents up to the toplevel widget are also visible.

The ::map signal can be used to determine whether a widget will be drawn, for instance it can resume an animation that was stopped during the emission of unmap.

§`mnemonic-activate`

Emitted when a widget is activated via a mnemonic.

The default handler for this signal activates @widget if @group_cycling is false, or just makes @widget grab focus if @group_cycling is true.

§`move-focus`

Emitted when the focus is moved.

The ::move-focus signal is a keybinding signal.

The default bindings for this signal are Tab to move forward, and Shift+Tab to move backward.

Action

§`query-tooltip`

Emitted when the widget’s tooltip is about to be shown.

This happens when the has-tooltip property is true and the hover timeout has expired with the cursor hovering above @widget; or emitted when @widget got focus in keyboard mode.

Using the given coordinates, the signal handler should determine whether a tooltip should be shown for @widget. If this is the case true should be returned, false otherwise. Note that if @keyboard_mode is true, the values of @x and @y are undefined and should not be used.

The signal handler is free to manipulate @tooltip with the therefore destined function calls.

§`realize`

Emitted when @widget is associated with a GdkSurface.

This means that [WidgetExtManual::realize()][crate::gtk::prelude::WidgetExtManual::realize()] has been called or the widget has been mapped (that is, it is going to be drawn).

§`show`

Emitted when @widget is shown.

§`state-flags-changed`

Emitted when the widget state changes.

See [WidgetExtManual::state_flags()][crate::gtk::prelude::WidgetExtManual::state_flags()].

§`unmap`

Emitted when @widget is going to be unmapped.

A widget is unmapped when either it or any of its parents up to the toplevel widget have been set as hidden.

As ::unmap indicates that a widget will not be shown any longer, it can be used to, for example, stop an animation on the widget.

§`unrealize`

Emitted when the GdkSurface associated with @widget is destroyed.

This means that [WidgetExtManual::unrealize()][crate::gtk::prelude::WidgetExtManual::unrealize()] has been called or the widget has been unmapped (that is, it is going to be hidden).

§Implements

AdwDialogExt, gtk::prelude::WidgetExt, [trait@glib::ObjectExt], gtk::prelude::AccessibleExt, gtk::prelude::BuildableExt, gtk::prelude::ConstraintTargetExt, gtk::prelude::ShortcutManagerExt

GLib type: GObject with reference counted clone semantics.

Struct AboutDialog Copy item path

§Main page

§What’s New

§Details

§Troubleshooting

§Credits and Acknowledgements

§Legal

§Other applications

§Constructing

§CSS nodes

§Properties

§application-icon

§application-name

§artists

§comments

§copyright

§debug-info

§debug-info-filename

§designers

§developer-name

§developers

§documenters

§issue-url

§license

§license-type

§release-notes

§release-notes-version

§support-url

§translator-credits

§version

§website

Dialog

§can-close

§child

§content-height

§content-width

§current-breakpoint

§default-widget

§focus-widget

§follows-content-size

§presentation-mode

§title

Widget

§can-focus

§can-target

§css-classes

§css-name

§cursor

§focus-on-click

§focusable

§halign

§has-default

§has-focus

§has-tooltip

§height-request

§hexpand

§hexpand-set

§layout-manager

§limit-events

§margin-bottom

§margin-end

§margin-start

§margin-top

§name

§opacity

§overflow

§parent

§receives-default

§root

§scale-factor

§sensitive

§tooltip-markup

§tooltip-text

§valign

§vexpand

§vexpand-set

§visible

§width-request

Accessible

§accessible-role

Struct AboutDialog

§`application-icon`

§`application-name`

§`artists`

§`comments`

§`copyright`

§`debug-info`

§`debug-info-filename`

§`designers`

§`developer-name`

§`developers`

§`documenters`

§`issue-url`

§`license`

§`license-type`

§`release-notes`

§`release-notes-version`

§`support-url`

§`translator-credits`

§`version`

§`website`

§`can-close`

§`child`

§`content-height`

§`content-width`

§`current-breakpoint`

§`default-widget`

§`focus-widget`

§`follows-content-size`

§`presentation-mode`

§`title`

§`can-focus`

§`can-target`

§`css-classes`

§`css-name`

§`cursor`

§`focus-on-click`

§`focusable`

§`halign`

§`has-default`

§`has-focus`

§`has-tooltip`

§`height-request`

§`hexpand`

§`hexpand-set`

§`layout-manager`

§`limit-events`

§`margin-bottom`

§`margin-end`

§`margin-start`

§`margin-top`

§`name`

§`opacity`

§`overflow`

§`parent`

§`receives-default`

§`root`

§`scale-factor`

§`sensitive`

§`tooltip-markup`

§`tooltip-text`

§`valign`

§`vexpand`

§`vexpand-set`

§`visible`

§`width-request`

§`accessible-role`

§`activate-link`

§`close-attempt`

§`closed`

§`destroy`

§`direction-changed`

§`hide`

§`keynav-failed`

§`map`

§`mnemonic-activate`

§`move-focus`

§`query-tooltip`

§`realize`

§`show`