Gtk.NativeDialog

g GObject.Object GObject.Object Gtk.NativeDialog Gtk.NativeDialog GObject.Object->Gtk.NativeDialog

Subclasses:Gtk.FileChooserNative

Methods

Inherited:GObject.Object (37)
Structs:GObject.ObjectClass (5)
  destroy ()
  get_modal ()
  get_title ()
  get_transient_for ()
  get_visible ()
  hide ()
  run ()
  set_modal (modal)
  set_title (title)
  set_transient_for (parent)
  show ()

Virtual Methods

Inherited:GObject.Object (7)
  do_hide ()
  do_response (response_id)
  do_show ()

Properties

Name Type Flags Short Description
modal bool r/w/en If True, the dialog is modal (other windows are not usable while this one is up)
title str r/w The title of the file chooser dialog
transient-for Gtk.Window r/w/c/en The transient parent of the dialog
visible bool r/w/en Whether the dialog is currently visible

Signals

Inherited:GObject.Object (1)
Name Short Description
response Emitted when the user responds to the dialog.

Fields

Inherited:GObject.Object (1)
Name Type Access Description
parent_instance GObject.Object r  

Class Details

class Gtk.NativeDialog(**kwargs)
Bases:GObject.Object
Abstract:Yes
Structure:Gtk.NativeDialogClass

Native dialogs are platform dialogs that don’t use Gtk.Dialog or Gtk.Window. They are used in order to integrate better with a platform, by looking the same as other native applications and supporting platform specific features.

The Gtk.Dialog functions cannot be used on such objects, but we need a similar API in order to drive them. The Gtk.NativeDialog object is an API that allows you to do this. It allows you to set various common properties on the dialog, as well as show and hide it and get a Gtk.NativeDialog ::response signal when the user finished with the dialog.

There is also a Gtk.NativeDialog.run() helper that makes it easy to run any native dialog in a modal way with a recursive mainloop, similar to Gtk.Dialog.run().

destroy()[source]

Destroys a dialog.

When a dialog is destroyed, it will break any references it holds to other objects. If it is visible it will be hidden and any underlying window system resources will be destroyed.

Note that this does not release any reference to the object (as opposed to destroying a Gtk.Window) because there is no reference from the windowing system to the Gtk.NativeDialog.

New in version 3.20.

get_modal()[source]
Returns:True if the dialog is set to be modal
Return type:bool

Returns whether the dialog is modal. See Gtk.NativeDialog.set_modal().

New in version 3.20.

get_title()[source]
Returns:the title of the dialog, or None if none has been set explicitly. The returned string is owned by the widget and must not be modified or freed.
Return type:str or None

Gets the title of the Gtk.NativeDialog.

New in version 3.20.

get_transient_for()[source]
Returns:the transient parent for this window, or None if no transient parent has been set.
Return type:Gtk.Window or None

Fetches the transient parent for this window. See Gtk.NativeDialog.set_transient_for().

New in version 3.20.

get_visible()[source]
Returns:True if the dialog is visible
Return type:bool

Determines whether the dialog is visible.

New in version 3.20.

hide()[source]

Hides the dialog if it is visilbe, aborting any interaction. Once this is called the Gtk.NativeDialog ::response signal will not be emitted until after the next call to Gtk.NativeDialog.show().

If the dialog is not visible this does nothing.

New in version 3.20.

run()[source]
Returns:response ID
Return type:int

Blocks in a recursive main loop until self emits the Gtk.NativeDialog ::response signal. It then returns the response ID from the ::response signal emission.

Before entering the recursive main loop, Gtk.NativeDialog.run() calls Gtk.NativeDialog.show() on the dialog for you.

After Gtk.NativeDialog.run() returns, then dialog will be hidden.

Typical usage of this function might be:

gint result = gtk_native_dialog_run (GTK_NATIVE_DIALOG (dialog));
switch (result)
  {
    case GTK_RESPONSE_ACCEPT:
       do_application_specific_something ();
       break;
    default:
       do_nothing_since_dialog_was_cancelled ();
       break;
  }
g_object_unref (dialog);

Note that even though the recursive main loop gives the effect of a modal dialog (it prevents the user from interacting with other windows in the same window group while the dialog is run), callbacks such as timeouts, IO channel watches, DND drops, etc, will be triggered during a gtk_nautilus_dialog_run() call.

New in version 3.20.

set_modal(modal)[source]
Parameters:modal (bool) – whether the window is modal

Sets a dialog modal or non-modal. Modal dialogs prevent interaction with other windows in the same application. To keep modal dialogs on top of main application windows, use Gtk.NativeDialog.set_transient_for() to make the dialog transient for the parent; most window managers will then disallow lowering the dialog below the parent.

New in version 3.20.

set_title(title)[source]
Parameters:title (str) – title of the dialog

Sets the title of the Gtk.NativeDialog.

New in version 3.20.

set_transient_for(parent)[source]
Parameters:parent (Gtk.Window or None) – parent window, or None

Dialog windows should be set transient for the main application window they were spawned from. This allows window managers to e.g. keep the dialog on top of the main window, or center the dialog over the main window.

Passing None for parent unsets the current transient window.

New in version 3.20.

show()[source]

Shows the dialog on the display, allowing the user to interact with it. When the user accepts the state of the dialog the dialog will be automatically hidden and the Gtk.NativeDialog ::response signal will be emitted.

Multiple calls while the dialog is visible will be ignored.

New in version 3.20.

do_hide() virtual

Hides the dialog if it is visilbe, aborting any interaction. Once this is called the Gtk.NativeDialog ::response signal will not be emitted until after the next call to Gtk.NativeDialog.show().

If the dialog is not visible this does nothing.

New in version 3.20.

do_response(response_id) virtual
Parameters:response_id (int) –
do_show() virtual

Shows the dialog on the display, allowing the user to interact with it. When the user accepts the state of the dialog the dialog will be automatically hidden and the Gtk.NativeDialog ::response signal will be emitted.

Multiple calls while the dialog is visible will be ignored.

New in version 3.20.

Signal Details

Gtk.NativeDialog.signals.response(native_dialog, response_id)
Signal Name:

response

Flags:

RUN_LAST

Parameters:
  • native_dialog (Gtk.NativeDialog) – The object which received the signal
  • response_id (int) – the response ID

Emitted when the user responds to the dialog.

When this is called the dialog has been hidden.

If you call Gtk.NativeDialog.hide() before the user responds to the dialog this signal will not be emitted.

New in version 3.20.

Property Details

Gtk.NativeDialog.props.modal
Name:modal
Type:bool
Default Value:False
Flags:READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether the window should be modal with respect to its transient parent.

New in version 3.20.

Gtk.NativeDialog.props.title
Name:title
Type:str
Default Value:None
Flags:READABLE, WRITABLE

The title of the dialog window

New in version 3.20.

Gtk.NativeDialog.props.transient_for
Name:transient-for
Type:Gtk.Window
Default Value:None
Flags:READABLE, WRITABLE, CONSTRUCT, EXPLICIT_NOTIFY

The transient parent of the dialog, or None for none.

New in version 3.20.

Gtk.NativeDialog.props.visible
Name:visible
Type:bool
Default Value:False
Flags:READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether the window is currenlty visible.

New in version 3.20.