Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
136 lines (106 sloc) 6 KB
Dialogs
=======
Dialog windows are very similar to standard windows, and are used to provide or
retrieve information from the user. They are often used to provide a preferences
window, for example. The major difference a dialog has is some prepacked widgets
which layout the dialog automatically. From there, we can simply add labels,
buttons, check buttons, etc. Another big difference is the handling of responses
to control how the application should behave after the dialog has been interacted
with.
There are several derived Dialog classes which you might find useful.
:class:`Gtk.MessageDialog` is used for most simple notifications. But at other
times you might need to derive your own dialog class to provide more complex
functionality.
Custom Dialogs
--------------
To pack widgets into a custom dialog, you should pack them into the
:class:`Gtk.Box`, available via :meth:`Gtk.Dialog.get_content_area`. To just add
a :class:`Gtk.Button` to the bottom of the dialog, you could use the
:meth:`Gtk.Dialog.add_button` method.
A 'modal' dialog (that is, one which freezes the rest of the application from user
input), can be created by calling :class:`Gtk.Dialog.set_modal` on the dialog or
set the ``flags`` argument of the :class:`Gtk.Dialog` constructor to include
the :attr:`Gtk.DialogFlags.MODAL` flag.
Clicking a button will emit a signal called "response". If you want to block
waiting for a dialog to return before returning control flow to your code, you
can call :meth:`Gtk.Dialog.run`. This method returns an int which may be a value
from the :class:`Gtk.ResponseType` or it could be the custom response value that
you specified in the :class:`Gtk.Dialog` constructor or :meth:`Gtk.Dialog.add_button`.
Finally, there are two ways to remove a dialog.
The :meth:`Gtk.Widget.hide` method removes the dialog from view, however keeps
it stored in memory. This is useful to prevent having to construct the dialog
again if it needs to be accessed at a later time. Alternatively, the
:meth:`Gtk.Widget.destroy` method can be used to delete the dialog from memory
once it is no longer needed. It should be noted that if the dialog needs to be
accessed after it has been destroyed, it will need to be constructed again
otherwise the dialog window will be empty.
Example
^^^^^^^
.. image:: ../images/dialog_example.png
.. literalinclude:: ../examples/dialog_example.py
:linenos:
MessageDialog
-------------
:class:`Gtk.MessageDialog` is a convenience class, used to create simple,
standard message dialogs, with a message, an icon, and buttons for user response
You can specify the type of message and the text in the :class:`Gtk.MessageDialog`
constructor, as well as specifying standard buttons.
In some dialogs which require some further explanation of what has happened,
a secondary text can be added. In this case, the primary message entered when
creating the message dialog is made bigger and set to bold text. The secondary
message can be set by calling :meth:`Gtk.MessageDialog.format_secondary_text`.
Example
^^^^^^^
.. image:: ../images/messagedialog_example.png
.. literalinclude:: ../examples/messagedialog_example.py
:linenos:
FileChooserDialog
-----------------
The :class:`Gtk.FileChooserDialog` is suitable for use with "File/Open" or
"File/Save" menu items. You can use all of the :class:`Gtk.FileChooser` methods
on the file chooser dialog as well as those for :class:`Gtk.Dialog`.
When creating a :class:`Gtk.FileChooserDialog` you have to define the dialog's
purpose:
* To select a file for opening, as for a File/Open command, use
:attr:`Gtk.FileChooserAction.OPEN`
* To save a file for the first time, as for a File/Save command, use
:attr:`Gtk.FileChooserAction.SAVE`, and suggest a name such as "Untitled"
with :meth:`Gtk.FileChooser.set_current_name`.
* To save a file under a different name, as for a File/Save As command, use
:attr:`Gtk.FileChooserAction.SAVE`, and set the existing filename with
:meth:`Gtk.FileChooser.set_filename`.
* To choose a folder instead of a file, use :attr:`Gtk.FileChooserAction.SELECT_FOLDER`.
:class:`Gtk.FileChooserDialog` inherits from :class:`Gtk.Dialog`, so buttons have
response IDs such as :attr:`Gtk.ResponseType.ACCEPT` and :attr:`Gtk.ResponseType.CANCEL`
which can be specified in the :class:`Gtk.FileChooserDialog` constructor.
In contrast to :class:`Gtk.Dialog`, you can not use custom response codes with
:class:`Gtk.FileChooserDialog`. It expects that at least one button will have
of the following response IDs:
* :attr:`Gtk.ResponseType.ACCEPT`
* :attr:`Gtk.ResponseType.OK`
* :attr:`Gtk.ResponseType.YES`
* :attr:`Gtk.ResponseType.APPLY`
When the user is finished selecting files, your program can get the selected
names either as filenames (:meth:`Gtk.FileChooser.get_filename`) or as URIs
(:meth:`Gtk.FileChooser.get_uri`).
By default, :class:`Gtk.FileChooser` only allows a single file to be selected at
a time. To enable multiple files to be selected, use
:meth:`Gtk.FileChooser.set_select_multiple`. Retrieving a list of selected files
is possible with either :meth:`Gtk.FileChooser.get_filenames` or
:meth:`Gtk.FileChooser.get_uris`.
:class:`Gtk.FileChooser` also supports a variety of options which make the files
and folders more configurable and accessible.
* :meth:`Gtk.FileChooser.set_local_only`: Only local files can be selected.
* :meth:`Gtk.FileChooser.show_hidden`: Hidden files and folders are displayed.
* :meth:`Gtk.FileChooser.set_do_overwrite_confirmation`: If the file chooser
was configured in :attr:`Gtk.FileChooserAction.SAVE` mode, it will present
a confirmation dialog if the user types a file name that already exists.
Furthermore, you can specify which kind of files are displayed by creating
:class:`Gtk.FileFilter` objects and calling :meth:`Gtk.FileChooser.add_filter`.
The user can then select one of the added filters from a combo box at the bottom
of the file chooser.
Example
^^^^^^^
.. image:: ../images/filechooserdialog_example.png
.. literalinclude:: ../examples/filechooserdialog_example.py
:linenos: