Struct libadwaita::AboutWindow

source ·

pub struct AboutWindow { /* private fields */ }

Available on crate feature v1_2 only.

Expand description

A window showing information about the application.

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

§Main page

AboutWindow 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

AboutWindow 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

AboutWindow 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.

AboutWindow 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().

§Constructing

To make constructing an AboutWindow as convenient as possible, you can use the function show_about_window() which constructs and shows a window.

⚠️ 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_window (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/new",
                         "license-type", GTK_LICENSE_GPL_3_0,
                         "developers", developers,
                         "designers", designers,
                         "translator-credits", _("translator-credits"),
                         NULL);
}

§CSS nodes

AboutWindow has a main CSS node with the name window 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.

AboutWindow::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.

AboutWindow 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.

AboutWindow::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.

AboutWindow::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.

AboutWindow 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 AboutWindow::add_link().

Readable | Writeable

Window

§`content`

The content widget.

This property should always be used instead of child.

Readable | Writeable

§`current-breakpoint`

The current breakpoint.

Readable

§`dialogs`

The open dialogs.

Readable

§`visible-dialog`

The currently visible dialog

Readable

Window

§`application`

The gtk::Application associated with the window.

The application will be kept alive for at least as long as it has any windows associated with it (see g_application_hold() for a way to keep it alive without windows).

Normally, the connection between the application and the window will remain until the window is destroyed, but you can explicitly remove it by setting the :application property to None.

Readable | Writeable

§`child`

The child widget.

Readable | Writeable

§`decorated`

Whether the window should have a frame (also known as decorations).

Readable | Writeable

§`default-height`

The default height of the window.

Readable | Writeable

§`default-widget`

The default widget.

Readable | Writeable

§`default-width`

The default width of the window.

Readable | Writeable

§`deletable`

Whether the window frame should have a close button.

Readable | Writeable

§`destroy-with-parent`

If this window should be destroyed when the parent is destroyed.

Readable | Writeable

§`display`

The display that will display this window.

Readable | Writeable

§`focus-visible`

Whether ‘focus rectangles’ are currently visible in this window.

This property is maintained by GTK based on user input and should not be set by applications.

Readable | Writeable

§`focus-widget`

The focus widget.

Readable | Writeable

§`fullscreened`

Whether the window is fullscreen.

Setting this property is the equivalent of calling [GtkWindowExtManual::fullscreen()][crate::gtk::prelude::GtkWindowExtManual::fullscreen()] or [GtkWindowExtManual::unfullscreen()][crate::gtk::prelude::GtkWindowExtManual::unfullscreen()]; either operation is asynchronous, which means you will need to connect to the ::notify signal in order to know whether the operation was successful.

Readable | Writeable | Construct

§`handle-menubar-accel`

Whether the window frame should handle F10 for activating menubars.

Readable | Writeable

§`hide-on-close`

If this window should be hidden when the users clicks the close button.

Readable | Writeable

§`icon-name`

Specifies the name of the themed icon to use as the window icon.

See Gtk::IconTheme for more details.

Readable | Writeable

§`is-active`

Whether the toplevel is the currently active window.

Readable

§`maximized`

Whether the window is maximized.

Setting this property is the equivalent of calling [GtkWindowExtManual::maximize()][crate::gtk::prelude::GtkWindowExtManual::maximize()] or [GtkWindowExtManual::unmaximize()][crate::gtk::prelude::GtkWindowExtManual::unmaximize()]; either operation is asynchronous, which means you will need to connect to the ::notify signal in order to know whether the operation was successful.

Readable | Writeable | Construct

§`mnemonics-visible`

Whether mnemonics are currently visible in this window.

This property is maintained by GTK based on user input, and should not be set by applications.

Readable | Writeable

§`modal`

If true, the window is modal.

Readable | Writeable

§`resizable`

If true, users can resize the window.

Readable | Writeable

§`startup-id`

A write-only property for setting window’s startup notification identifier.

Writeable

§`suspended`

Whether the window is suspended.

See [GtkWindowExtManual::is_suspended()][crate::gtk::prelude::GtkWindowExtManual::is_suspended()] for details about what suspended means.

Readable

§`title`

The title of the window.

Readable | Writeable

§`titlebar`

The titlebar widget.

Readable | Writeable

§`transient-for`

The transient parent of the window.

Readable | Writeable | Construct

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 value of true 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`

Override 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

§`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 None 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 None: 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`

Override 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().

Window

§`activate-default`

Emitted when the user activates the default widget of @window.

This is a keybinding signal.

Action

§`activate-focus`

Emitted when the user activates the currently focused widget of @window.

This is a keybinding signal.

Action

§`close-request`

Emitted when the user clicks on the close button of the window.

§`enable-debugging`

Emitted when the user enables or disables interactive debugging.

When @toggle is true, interactive debugging is toggled on or off, when it is false, the debugger will be pointed at the widget under the pointer.

This is a keybinding signal.

The default bindings for this signal are Ctrl-Shift-I and Ctrl-Shift-D.

Action

§`keys-changed`

emitted when the set of accelerators or mnemonics that are associated with @window changes.

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

AdwWindowExt, gtk::prelude::GtkWindowExt, gtk::prelude::WidgetExt, [trait@glib::ObjectExt], gtk::prelude::AccessibleExt, gtk::prelude::BuildableExt, gtk::prelude::ConstraintTargetExt, gtk::prelude::NativeExt, gtk::prelude::RootExt, gtk::prelude::ShortcutManagerExt

Struct libadwaita::AboutWindow

§Main page

§What’s New

§Details

§Troubleshooting

§Credits and Acknowledgements

§Legal

§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

Window

§content

§current-breakpoint

§dialogs

§visible-dialog

Window

§application

§child

§decorated

§default-height

§default-widget

§default-width

§deletable

§destroy-with-parent

§display

§focus-visible

§focus-widget

§fullscreened

§handle-menubar-accel

§hide-on-close

§icon-name

§is-active

§maximized

§mnemonics-visible

§modal

§resizable

§startup-id

§suspended

§title

§titlebar

§transient-for

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

§margin-bottom

§margin-end

§margin-start

§`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`

§`content`

§`current-breakpoint`

§`dialogs`

§`visible-dialog`

§`application`

§`child`

§`decorated`

§`default-height`

§`default-widget`

§`default-width`

§`deletable`

§`destroy-with-parent`

§`display`

§`focus-visible`

§`focus-widget`

§`fullscreened`

§`handle-menubar-accel`

§`hide-on-close`

§`icon-name`

§`is-active`

§`maximized`

§`mnemonics-visible`

§`modal`

§`resizable`

§`startup-id`

§`suspended`

§`title`

§`titlebar`

§`transient-for`

§`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`

§`margin-bottom`

§`margin-end`

§`margin-start`

§`margin-top`

§`name`

§`opacity`

§`overflow`

§`parent`

§`receives-default`

§`root`

§`scale-factor`

§`sensitive`

§`tooltip-markup`

§`tooltip-text`

§`valign`

§`vexpand`