Name
gtk.Dialog — popup windows for user information and action
Signal Prototypes
"close" | def callback(dialog, user_param1, ...) |
"response" | def callback(dialog, response_id, user_param1, ...) |
Description
Dialog boxes are a convenient way to prompt the user for a small
amount of input, e.g. to display a message, ask a question, or anything else
that does not require extensive effort on the user's part. Dialogs are
organized as a window split vertically. The top section is a gtk.VBox, and is where
widgets such as a gtk.Label or a gtk.Entry should be
packed. The bottom area is known as the action_area which is generally used
for packing buttons into the dialog which may perform functions such as
cancel, ok, or apply. The two areas are separated by a gtk.HSeparator.
The gtk.Dialog boxes are
created with a call to gtk.Dialog()()
that sets the dialog title, some convenient flags, and adds simple buttons.
In a newly created dialog, the two primary areas of the window can be
accessed as the vbox and action_area attributes, as can be seen from the
example, below. A modal dialog (that is, one which freezes the rest of the
application from user input), can be created by passing the
gtk.DIALOG_MODAL flag to the gtk.Dialog()
constructor or by calling set_modal()
on the dialog.
If you add buttons to gtk.Dialog using
gtk.Dialog(),
add_button(),
or add_action_widget(),
clicking the button will emit a signal called "response" with a response ID
that you specified. PyGTK will never assign a meaning to positive response
IDs; these are entirely user-defined. But for convenience, you can use the
pre-defined response IDs (these all have values less than zero):
- gtk.RESPONSE_NONE
- gtk.RESPONSE_REJECT
- gtk.RESPONSE_ACCEPT
- gtk.RESPONSE_DELETE_EVENT
- gtk.RESPONSE_OK
- gtk.RESPONSE_CANCEL
- gtk.RESPONSE_CLOSE
- gtk.RESPONSE_YES
- gtk.RESPONSE_NO
- gtk.RESPONSE_APPLY
- gtk.RESPONSE_HELP
If a dialog receives a delete event, the "response" signal will be
emitted with a response ID of gtk.RESPONSE_NONE.
If you want to block waiting for a dialog to return before
returning control flow to your code, you can call run(). This
function enters a recursive main loop and waits for the user to respond to
the dialog, returning the response ID corresponding to the button the user
clicked.
Constructor
gtk.Dialog(title=None, parent=None, flags=0, first_button_text=None)
|
title : | The title of the dialog, or
None |
parent : | The transient parent of the dialog, or
None |
flags : | flags that control the operation of the
dialog |
buttons : | a tuple containing button text/response id pairs
or None |
Returns : | a new gtk.Dialog |
Creates a new gtk.Dialog with the
title text specified by title (or
None for the default title; see gtk.Window.set_title())
and transient parent window specified by parent (or
None for none; see gtk.Window.set_transient_for()).
The flags argument can be used to make the dialog
modal (gtk.DIALOG_MODAL) and/or to have it destroyed
along with its transient parent
(gtk.DIALOG_DESTROY_WITH_PARENT) and/or remove the
separator (gtk.DIALOG_NO_SEPARATOR). After
flags, a tuple of button text/response ID pairs
should be listed, or None (the default value) is no
buttons are needed. The button text can be either a stock ID such as
gtk.STOCK_OK, or some arbitrary text. A response ID can
be any positive number, or one of the pre-defined values:
- gtk.RESPONSE_NONE
- gtk.RESPONSE_REJECT
- gtk.RESPONSE_ACCEPT
- gtk.RESPONSE_DELETE_EVENT
- gtk.RESPONSE_OK
- gtk.RESPONSE_CANCEL
- gtk.RESPONSE_CLOSE
- gtk.RESPONSE_YES
- gtk.RESPONSE_NO
- gtk.RESPONSE_APPLY
- gtk.RESPONSE_HELP
If the user clicks one of these dialog buttons, the gtk.Dialog will emit
the "response" signal with the corresponding response ID. If a gtk.Dialog receives
the "delete_event" signal, it will emit "response" with a response ID of
gtk.RESPONSE_DELETE_EVENT. However, destroying a dialog
does not emit the "response" signal; so be careful relying on "response"
when using the gtk.DIALOG_DESTROY_WITH_PARENT flag.
Buttons are added from left to right, so the first button in the list will
be the leftmost button in the dialog.
Here's a simple example:
dialog = gtk.Dialog("My dialog",
main_app_window,
gtk.DIALOG_MODAL | gtk_.DIALOG_DESTROY_WITH_PARENT,
(gtk.STOCK_OK, gtk.RESPONSE_ACCEPT,
gtk.STOCK_CANCEL, gtk.RESPONSE_REJECT))
|
Methods
gtk.Dialog.add_action_widget
def add_action_widget(child, response_id)
|
child : | an activatable widget |
response_id : | a response ID |
The add_action_widget() method adds an
activatable widget to the action area of a gtk.Dialog,
connecting a signal handler that will emit the "response" signal on the
dialog when the widget is activated. The widget is appended to the end of
the dialog's action area. If you want to add a non-activatable widget,
simply pack it into the action_area.
gtk.Dialog.add_button
def add_button(button_text, response_id)
|
button_text : | the text of the button, or a stock
ID |
response_id : | the response ID for the
button |
Returns : | the button widget that was
added |
The add_button() method adds a button
with the text specified by button_text (or a stock
button, if button_text is a stock ID) and sets things
up so that clicking the button will emit the "response" signal with the
specified response_id. The button is appended to the
end of the dialog's action area. The button widget is returned, but usually
you don't need it.
gtk.Dialog.add_buttons
buttons : | a tuple containing 2-tuples each containing
button text (or stock ID) and a response id |
The add_buttons() method adds several
buttons to the gtk.Dialog using the
data specified in buttons. This method is the same as
calling the gtk.Dialog.add_button()
repeatedly. buttons is a tuple containing 2-tuples specifying the data for
one button - button text and a response ID integer.
gtk.Dialog.set_response_sensitive
def set_response_sensitive(response_id, setting)
|
response_id : | a response ID |
setting : | the new value for
sensitive |
The set_response_sensitive() method
calls the gtk.Window.set_sensitive()
method with the specified response_id for each widget
in the dialog's action area. This method is a convenience function to
sensitize/desensitize all dialog buttons at once.
gtk.Dialog.set_default_response
def set_default_response(response_id)
|
response_id : | a response ID |
The set_default_response() method sets
the last widget in the dialog's action area with the specified
response_id as the default widget for the dialog.
Pressing Enter normally activates the default
widget.
gtk.Dialog.set_has_separator
def set_has_separator(setting)
|
setting : | If TRUE use a
separator |
The set_has_separator() method sets the
"has-separator" property to the value of setting. If
setting is TRUE (the default
value) the dialog has a separator above the buttons.
gtk.Dialog.get_has_separator
Returns : | the value of the "has-separator"
property |
The get_has_separator() method returns
the value of the "has-separator" property.
gtk.Dialog.response
def response(response_id)
|
The response() method emits the
"response" signal with the value specified in
response_id. This method is used to indicate that the
user has responded to the dialog in some way; typically either you or gtk.Dialog.run()
will be monitoring the "response" signal and take appropriate action.
gtk.Dialog.run
The run() method blocks in a recursive
main loop until the dialog either emits the "response" signal, or is
destroyed. If the dialog is destroyed, the run()
method returns gtk.RESPONSE_NONE; otherwise, it returns
the response ID from the "response" signal emission. Before entering the
recursive main loop, the run() method calls the
gtk.Widget.show()
on the dialog for you. Note that you still need to show any children of the
dialog yourself.
During the run() method, the default
behavior of "delete_event" is disabled; if the dialog receives a
"delete_event", it will not be destroyed as windows usually are, and the
run() method will return
gtk.RESPONSE_DELETE_EVENT. Also, during the
run() method the dialog will be modal. You can
force the run() method to return at any time by
calling response()
to emit the "response" signal. Destroying the dialog during the
run() method is a very bad idea, because your
post-run code won't know whether the dialog was destroyed or not.
After the run() method returns, you are
responsible for hiding or destroying the dialog as needed.
Signals
The "close" gtk.Dialog Signal
def callback(dialog, user_param1, ...)
|
dialog : | the dialog that received the
signal |
user_param1 : | the first user parameter (if any) specified
with the connect()
method |
... : | additional user parameters (if
any) |
The "close" signal is emitted when the dialog is closed.
The "response" gtk.Dialog Signal
def callback(dialog, response_id, user_param1, ...)
|
dialog : | the dialog that received the
signal |
response_id : | the response id received by the
dialog |
user_param1 : | the first user parameter (if any) specified
with the connect()
method |
... : | additional user parameters (if
any) |
The "response" signal is emitted when an action_area widget is
activated (button "clicked"), the dialog receives a delete_event or the
application calls the response()
method. When a delete_event triggers the "response" signal the
response_id will be
gtk.RESPONSE_NONE.