Dialogs

TIP

Some elements in this module are pure JavaScript and do not support GObject features like property bindings.

The Dialog and ModalDialog modules contain classes for creating dialogs in GNOME Shell. Extension authors might use these when they would normally use a GTK dialog, which can't be created in the GNOME Shell process.

Shell

WARNING

The Shell import is a C library, available only to GNOME Shell and extensions. These elements are documented here due to an unfixed bug in the official Shell API Documentation, which should be preferred for all other cases.

Shell.ActionMode

Controls in which GNOME Shell states an action (like keybindings and gestures) should be handled.

• Shell.ActionMode
  • Shell.ActionMode.NONE — block action
  • Shell.ActionMode.NORMAL — allow action when in window mode, e.g. when the focus is in an application window
  • Shell.ActionMode.OVERVIEW — allow action while the overview is active
  • Shell.ActionMode.LOCK_SCREEN — allow action when the screen is locked, e.g. when the screen shield is shown
  • Shell.ActionMode.UNLOCK_SCREEN — allow action in the unlock dialog
  • Shell.ActionMode.LOGIN_SCREEN — allow action in the login screen
  • Shell.ActionMode.SYSTEM_MODAL — allow action when a system modal dialog (e.g. authentication or session dialogs) is open
  • Shell.ActionMode.LOOKING_GLASS — allow action in looking glass
  • Shell.ActionMode.POPUP — allow action while a shell menu is open
  • Shell.ActionMode.ALL — always allow action

Dialog

The Dialog module contains base classes for creating and working with dialogs in GNOME Shell.

Dialog.Dialog

Parent Class: St.Widget

The base class for dialog layouts. This is a fairly simple widget, with a content area and an action area for buttons, used as the layout widget for most dialogs.

The dialog handles key events, invoking the callback for buttons added with Dialog.addButton() if they include a matching key.

Methods

• new Dialog.Dialog(parentActor, styleClass) — Constructor
  • parentActor (Clutter.Actor) — The parent actor to add the layout to
  • styleClass (String) — Optional CSS class for the dialog
• addButton(buttonInfo) — Add a button to the dialog
  • buttonInfo (Object) — Button properties
    • label (String) — The button label
    • action (Function) — Optional button activation callback
    • key (Number) — Optional key constant, such as Clutter.KEY_A or Clutter.KEY_space
    • isDefault (Boolean) — If true, the button will be activated by the enter key and receive the default focus
• clearButtons() — Removes all buttons from the dialog

Properties

• contentLayout (St.BoxLayout) — The content area of the dialog (JavaScript: read-only)
• buttonLayout (St.BoxLayout) — The action area, where buttons are added (JavaScript: read-only)

Example

import St from 'gi://St';

import * as Dialog from 'resource:///org/gnome/shell/ui/dialog.js';


// Creating a dialog layout
const parentActor = new St.Widget();
const dialogLayout = new Dialog.Dialog(parentActor, 'my-dialog');

// Adding a widget to the content area
const icon = new St.Icon({icon_name: 'dialog-information-symbolic'});
dialogLayout.contentLayout.add_child(icon);

// Adding a default button
dialogLayout.addButton({
    label: 'Close',
    isDefault: true,
    action: () => {
        dialogLayout.destroy();
    },
});

Dialog.MessageDialogContent

Parent Class: St.BoxLayout

A widget for the common case of creating a dialog with a title and description, like Gtk.MessageDialog.

Methods

• new Dialog.MessageDialogContent(params) — Constructor
  • params (Object) — A dictionary of GObject construct properties

Properties

• title (String) — The message title (GObject: read-write)
• description (String) — The message description (GObject: read-write)

Example

import St from 'gi://St';

import * as Dialog from 'resource:///org/gnome/shell/ui/dialog.js';


// Creating a dialog layout
const parentActor = new St.Widget();
const dialogLayout = new Dialog.Dialog(parentActor, 'my-dialog');

// Adding a widget to the content area
const messageLayout = new Dialog.MessageDialogContent({
    title: 'Important',
    description: 'Something happened that you should know about!',
});
dialogLayout.contentLayout.add_child(messageLayout);

// Adding a default button
dialogLayout.addButton({
    label: 'Close',
    isDefault: true,
    action: () => {
        dialogLayout.destroy();
    },
});

Dialog.ListSection

Parent Class: St.BoxLayout

A widget for the common case of creating a dialog with a list box of items, such as a dialog for connecting to a wireless network. This is intended to be used with Dialog.ListSectionItem.

Methods

• new Dialog.ListSection(params) — Constructor
  • params (Object) — A dictionary of GObject construct properties

Properties

• title (String) — The list title (GObject: read-write)
• list (St.BoxLayout) — The list box (JavaScript: read-only)

Example

import St from 'gi://St';

import * as Dialog from 'resource:///org/gnome/shell/ui/dialog.js';


// Creating a dialog layout
const parentActor = new St.Widget();
const dialogLayout = new Dialog.Dialog(parentActor, 'my-dialog');

// Adding a widget to the content area
const listLayout = new Dialog.ListSection({
    title: 'Todo List',
});
dialogLayout.contentLayout.add_child(listLayout);

const taskOne = new Dialog.ListSectionItem({
    icon_actor: new St.Icon({icon_name: 'dialog-information-symbolic'}),
    title: 'Task One',
    description: 'The first thing I need to do',
});
listLayout.list.add_child(taskOne);

const taskTwo = new Dialog.ListSectionItem({
    icon_actor: new St.Icon({icon_name: 'dialog-information-symbolic'}),
    title: 'Task Two',
    description: 'The next thing I need to do',
});
listLayout.list.add_child(taskTwo);

// Adding a default button
dialogLayout.addButton({
    label: 'Close',
    action: () => {
        dialogLayout.destroy();
    },
});

Dialog.ListSectionItem

Parent Class: St.BoxLayout

A widget for the common case of creating a dialog with a title and description, like Gtk.MessageDialog.

Methods

• new Dialog.MessageDialogContent(params) — Constructor
  • params (Object) — A dictionary of GObject construct properties

Properties

• icon-actor (Clutter.Actor) — An icon for the item (GObject: read-write)
• title (String) — The item title (GObject: read-write)
• description (String) — The item description (GObject: read-write)

Example

See the example for Dialog.ListSection

ModalDialog

The ModalDialog module includes the primary class for creating dialogs, ModalDialog.ModalDialog.

This is a fairly lightweight class, so it is often wrapped by an object that creates instances of ModalDialog.ModalDialog on-demand that are destroyed when closed.

ModalDialog.State

Enumeration of dialog states.

• ModalDialog.State
  • ModalDialog.State.OPENED — The dialog is opened
  • ModalDialog.State.CLOSED — The dialog is closed
  • ModalDialog.State.OPENING — The dialog is opening
  • ModalDialog.State.CLOSING — The dialog is closing
  • ModalDialog.State.FADED_OUT — The dialog is faded out

ModalDialog.ModalDialog

Parent Class: St.Widget

A modal dialog. This class sets up a Dialog.Dialog layout automatically.

Methods

• new ModalDialog.ModalDialog(params) — Constructor
  • params (Object) — A dictionary of specific construct properties
    • shellReactive (Boolean) — Whether the shell is sensitive when the dialog is open (default: false)
    • actionMode (Shell.ActionMode) — A Shell.ActionMode (default: Shell.ActionMode.SYSTEM_MODAL)
    • shouldFadeIn (Boolean) — Whether the dialog should fade in when opened (default: true)
    • shouldFadeOut (Boolean) — Whether the dialog should fade out when closed (default: true)
    • destroyOnClose (Boolean) — Whether the dialog should be destroyed when closed (default: true)
    • styleClass (String) — CSS class for the dialog (default: null)
• addButton(buttonInfo) — Add a button to the internal Dialog.Dialog
  • buttonInfo (Object) — Button properties
    • label (String) — The button label
    • action (Function) — Optional button activation callback
    • key (Number) — Optional key constant, such as Clutter.KEY_A or Clutter.KEY_space
    • isDefault (Boolean) — If true, the button will be activated by the enter key and receive the default focus
  • Returns (St.Button) — The newly added button
• setButtons(buttonInfos) — Set the buttons for the internal Dialog.Dialog, removing any existing buttons
  • buttonInfos (Array(Object)) — A list of button info objects
• clearButtons() — Removes all buttons from the internal Dialog.Dialog
• setInitialKeyFocus(actor) — Set an actor to receive the initial key focus
  • actor (Clutter.Actor) — The actor to focus
• open(timestamp, onPrimary) — Present the dialog
  • timestamp (Number) — Optional timestamp (i.e. global.get_current_time())
  • onPrimary (Boolean) — Whether to show the dialog on the primary display
  • Returns (Boolean) — true if successful, false otherwise
• close(timestamp) — Hide the dialog
  • timestamp (Number) — Optional timestamp (i.e. global.get_current_time())

Properties

• (Number) state — A ModalDialog.State (GObject: read-only)
• (Dialog.Dialog) dialogLayout — A Dialog.Dialog layout (JavaScript: read-only)
• (St.BoxLayout) contentLayout — The internal Dialog.Dialog.contentLayout (JavaScript: read-only)
• (St.BoxLayout) buttonLayout — The internal Dialog.Dialog.buttonLayout (JavaScript: read-only)

Signals

• closed — Emitted when the dialog closes (GObject: no parameters or return values)
• opened — Emitted when the dialog opens (GObject: no parameters or return values)

Example

import GLib from 'gi://GLib';
import St from 'gi://St';

import * as Dialog from 'resource:///org/gnome/shell/ui/dialog.js';
import * as ModalDialog from 'resource:///org/gnome/shell/ui/modalDialog.js';


// Creating a modal dialog
let testDialog = new ModalDialog.ModalDialog({
    destroyOnClose: false,
    styleClass: 'my-dialog',
});

let reminderId = null;
let closedId = testDialog.connect('closed', () => {
    console.debug('The dialog was dismissed, so set a reminder');

    if (!reminderId) {
        reminderId = GLib.timeout_add_seconds(GLib.PRIORITY_DEFAULT, 60,
            () => {
                testDialog.open(global.get_current_time());

                reminderId = null;
                return GLib.SOURCE_REMOVE;
            });
    }
});

testDialog.connect('destroy', () => {
    console.debug('The dialog was destroyed, so reset everything');

    if (closedId) {
        testDialog.disconnect(closedId);
        closedId = null;
    }

    if (reminderId) {
        GLib.Source.remove(reminderId);
        reminderId = null;
    }

    testDialog = null;
});


// Adding a widget to the content area
const listLayout = new Dialog.ListSection({
    title: 'Todo List',
});
testDialog.contentLayout.add_child(listLayout);

const taskOne = new Dialog.ListSectionItem({
    icon_actor: new St.Icon({icon_name: 'dialog-information-symbolic'}),
    title: 'Task One',
    description: 'The first thing I need to do',
});
listLayout.list.add_child(taskOne);

const taskTwo = new Dialog.ListSectionItem({
    icon_actor: new St.Icon({icon_name: 'dialog-information-symbolic'}),
    title: 'Task Two',
    description: 'The next thing I need to do',
});
listLayout.list.add_child(taskTwo);


// Adding buttons
testDialog.setButtons([
    {
        label: 'Close',
        action: () => testDialog.destroy(),
    },
    {
        label: 'Later',
        isDefault: true,
        action: () => testDialog.close(global.get_current_time()),
    },
]);