## ModalDialog.ModalDialog

ModalDialog.ModalDialog — A generic object that displays a modal dialog

## Functions

| _init ()
| setButtons ()
| open ()
| close ()
| popModal ()
| pushModal ()
| _fadeOutDialog ()

## Properties

ModalDialog.State | state |
St.BoxLayout | contentLayout |

## Object Hierarchy

        Object
        ╰── ModalDialog.ModalDialog

## Description

The `ModalDialog` object is a generic popup dialog in Cinnamon. It can either be created directly and then manipulated afterwards, or used as a base class for more sophisticated modal dialog.

For simple usage such as displaying a message, or asking for confirmation, the `ConfirmDialog` and `NotifyDialog` classes may be used instead.

## Functions

### _init ()

    _init (JSON   params);

#### Parameters

params | parameters for the modal dialog. Options include `cinnamonReactive`, which determines whether the modal dialog should block Cinnamon input, and `styleClass`, which is the style class the modal dialog should use. |

### setButtons ()

    setButtons (array   buttons);

This sets the buttons in the modal dialog. The buttons is an array of JSON objects, each of which corresponds to one button.

Each JSON object must contain `label` and `action`, which are the text displayed on the button and the callback function to use when the button is clicked respectively.

Optional arguments include `focused`, which determines whether the button is initially focused, and `key`, which is a keybinding associated with the button press such that pressing the keybinding will have the same effect as clicking the button. Other arguments include `default` and `destructive_action` which add additional styling.

An example usage is

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13

    dialog.setButtons([
        {
            label: _("Cancel"),
            action: this.callback.bind(this),
            key: Clutter.KEY_Escape
        },
        {
            label: _("OK"),
            action: this.destroy.bind(this),
            key: Clutter.KEY_Return,
            default: true
        }
    ]);

#### Parameters

buttons | the buttons to display in the modal dialog |

### open ()

    open (int   timestamp);

Opens and displays the modal dialog.

#### Parameters

timestamp | (optional) timestamp optionally used to associate the call with a specific user initiated event |

### close ()

    close (int   timestamp);

Closes the modal dialog.

#### Parameters

timestamp | (optional) timestamp optionally used to associate the call with a specific user initiated event |

### popModal ()

    popModal (int   timestamp);

Drop modal status without closing the dialog; this makes the dialog insensitive as well, so it needs to be followed shortly by either a `close()` or a `pushModal()`

#### Parameters

timestamp | (optional) timestamp optionally used to associate the call with a specific user initiated event |

### pushModal ()

    pushModal (int   timestamp);

Pushes the modal to the modal stack so that it grabs the required inputs.

#### Parameters

timestamp | (optional) timestamp optionally used to associate the call with a specific user initiated event |

### _fadeOutDialog ()

    _fadeOutDialog (int   timestamp);

This method is like `close()`, but fades the dialog out much slower, and leaves the lightbox in place. Once in the faded out state, the dialog can be brought back by an open call, or the lightbox can be dismissed by a close call.

The main point of this method is to give some indication to the user that the dialog response has been acknowledged but will take a few moments before being processed.

e.g., if a user clicked "Log Out" then the dialog should go away immediately, but the lightbox should remain until the logout is complete.

#### Parameters

timestamp | (optional) timestamp optionally used to associate the call with a specific user initiated event |

## Property Details

### The `“state”` property

      “state”                    ModalDialog.State

The state of the modal dialog, which may be `ModalDialog.State.OPENED`, `CLOSED`, `OPENING`, `CLOSING` or `FADED_OUT`.

### The `“contentLayout”` property

      “contentLayout”            St.BoxLayout

The box containing the contents of the modal dialog (excluding the buttons)