Dialog boxes are a convenient way to prompt the user for a small amount of
input, to display a message, ask a question, or anything else that does
not require extensive effort on the user's part.
GTK+ treats a dialog as a window split vertically. The top section is a
VBox
, and is where widgets such as a
Label
or a
Entry
should be packed. The bottom area is known as the
actionArea. This 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
HSeparator
.
A 'modal' dialog (that is, one which freezes the rest of the application
from user input), can be created by calling
Window.setModal(boolean)
on the
dialog.
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.
addButton
public void addButton(String buttonText,
int responseId)
Adds a button with the given text and sets things up so that
clicking the button will emit the "response" event with the
given responseId
.
buttonText
- The text string to display on the button.responseId
- The response ID to emit when the user clicks the
button that is to be added.
addButton
public void addButton(GtkStockItem stockItem,
int responseId)
Adds a button with the given stock button and sets things up so
that clicking the button will emit the "response" event with
the given responseId
.
responseId
- The response ID to emit when the user clicks the
button that is to be added.
addWidget
public void addWidget(Widget child,
int responseId)
Adds an activatable widget to the action area of the 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.
child
- An activatable Widget to add to the dialog.responseId
- The response ID to emit when the user clicks the
widget.
fireButtonEvent
protected void fireButtonEvent(DialogEvent event)
getActionArea
public HButtonBox getActionArea()
The lower area of the Dialog where the buttons are located is a HButtonBox.
This methos will return that container.
- The HButton box that is known as the action area.
getActionArea
protected static final Handle getActionArea(Handle cptr)
getDialogLayout
public VBox getDialogLayout()
The upper area of the Dialog where widgets can be added is a VBox. This
method will return that layout control.
- The VBox that is the layout control for the dialog.
getEventListenerClass
public Class getEventListenerClass(String signal)
- getEventListenerClass in interface Container
getEventType
public EventType getEventType(String signal)
- getEventType in interface Container
getHasSeparator
public boolean getHasSeparator()
Access for whether the dialog has a separator.
- true if the Dialog has a separator.
getType
public static Type getType()
Retrieve the runtime type used by the GLib library.
- getType in interface Window
gtk_dialog_add_action_widget
protected static final void gtk_dialog_add_action_widget(Handle dialog,
Handle child,
int responseId)
gtk_dialog_add_button
protected static final Handle gtk_dialog_add_button(Handle dialog,
String buttonText,
int responseId)
gtk_dialog_get_has_separator
protected static final boolean gtk_dialog_get_has_separator(Handle dialog)
gtk_dialog_get_type
protected static final int gtk_dialog_get_type()
gtk_dialog_new
protected static final Handle gtk_dialog_new()
gtk_dialog_response
protected static final void gtk_dialog_response(Handle dialog,
int responseId)
gtk_dialog_run
protected static final int gtk_dialog_run(Handle dialog)
gtk_dialog_set_default_response
protected static final void gtk_dialog_set_default_response(Handle dialog,
int responseId)
gtk_dialog_set_has_separator
protected static final void gtk_dialog_set_has_separator(Handle dialog,
boolean setting)
gtk_dialog_set_response_sensitive
protected static final void gtk_dialog_set_response_sensitive(Handle dialog,
int responseId,
boolean setting)
run
public int run()
Blocks in a recursive main loop until the
dialog either emits a
response signal or is destroyed. The return value can be compared against
a
ResponseType
to determine if a standard return value is emitted.
The developer can also set the response type when a button or widget is
added to the dialog. If the dialog is destroyed the run method will
return RESPONSE_NONE.
- The response that indicates which button the user pressed or
RESPONSE_NONE if the window was destroyed.
setDefaultResponse
public void setDefaultResponse(int responseId)
Sets the last widget in the dialog's action area with the given
responseId as the default widget for the dialog. Pressing
"Enter" normally activates the default widget.
responseId
- The response ID.
setHasSeparator
public void setHasSeparator(boolean setting)
Sets whether the dialog has a separator above the buttons. This
is true by default.
setting
- Indicates if a separator should be added to the dialog.