forked from AuroraMiddleware/gtk
0bee26c7ba
2001-06-28 Havoc Pennington <hp@pobox.com> * gdk/x11/gdkimage-x11.c (_gdk_x11_get_image): Clip the retrieved image data to the screen, using a server grab to avoid race conditions. * gtk/gtkitemfactory.c (gtk_item_factory_create_item): remove check for NULL return from gtk_image_new_from_stock(), it never returns NULL. (gtk_item_factory_create_item): fix bug where we parsed the stock ID as an inline pixbuf * gtk/gtktext.c (gtk_text_key_press): numeric keypad support * gtk/gtkspinbutton.c (gtk_spin_button_key_press): numeric keypad support (should be using binding set here) * gtk/gtkoptionmenu.c (gtk_option_menu_key_press): numeric keypad support (should be using binding set here) * gtk/gtkmenushell.c (gtk_menu_shell_class_init): numeric keypad support * gtk/gtkmenu.c (gtk_menu_class_init): numeric keypad support * gtk/gtkmenubar.c (gtk_menu_bar_class_init): numeric keypad * gtk/gtklistitem.c (gtk_list_item_class_init): numeric keypad * gtk/gtkimcontextsimple.c (gtk_im_context_simple_filter_keypress): keypad * gtk/gtkfilesel.c (gtk_file_selection_key_press): keypad * gtk/gtkentry.c (gtk_entry_class_init): numeric keypad fixes * gtk/gtkctree.c (gtk_ctree_class_init): numeric keypad support * gtk/gtkcolorsel.c (palette_activate): keypad support (of course, should be binding-setted) * gtk/gtkwindow.c (gtk_window_class_init): numeric keypad fixes * gtk/gtkclist.c (gtk_clist_class_init): numeric keypad fixes * gtk/gtkcalendar.c: numeric keypad fixes * gtk/gtktextview.c (gtk_text_view_class_init): numeric keypad support * gdk/gdkwindow.c (gdk_window_get_clip_region): fix infinite loop screwup * gdk/gdkpixbuf-render.c (gdk_pixbuf_render_to_drawable_alpha): clip the render area to the drawable's clip region in advance, so we don't get data from the server that we don't need. * gdk/gdkpixbuf-render.c (gdk_pixbuf_render_to_drawable_alpha): check return value of gdk_pixbuf_get_from_drawable(), fall back to bilevel alpha if we can't get the pixbuf to composite against. * gdk/gdkdraw.c (gdk_drawable_get_image): set the image colormap * gdk/gdkimage.c (gdk_image_get_colormap): add gdk_image_set_colormap, gdk_image_get_colormap * gdk/gdkpixbuf-drawable.c (rgbconvert): Change all converters to take a region of the image, instead of converting the entire image. * gtk/gtkwidget.h (struct _GtkWidgetClass): add show_help keybinding signal. Add default bindings for it. Add default handler for show_help that shows the tooltip for the widget. * gtk/gtkdialog.c (gtk_dialog_class_init): add binding set and "close" keybinding signal, remove key press handler. * gtk/gtktooltips.c (gtk_tooltips_set_colors): Just remove this, it's not our usual practice to leave a deprecated function around with a runtime warning, plus we don't want it to appear in docs, plus if we make them yellow no one will want to change them anyhow.
299 lines
7.2 KiB
Plaintext
299 lines
7.2 KiB
Plaintext
<!-- ##### SECTION Title ##### -->
|
|
GtkDialog
|
|
|
|
<!-- ##### SECTION Short_Description ##### -->
|
|
|
|
create popup windows.
|
|
|
|
<!-- ##### SECTION Long_Description ##### -->
|
|
|
|
<para>
|
|
Dialog boxes are a convenient way to prompt the user for a small amount of
|
|
input, eg. to display a message, ask a question, or anything else that does not
|
|
require extensive effort on the user's part.
|
|
</para>
|
|
|
|
<para>
|
|
Gtk+ treats a dialog as a window split horizontally. The top section is a
|
|
#GtkVBox, and is where widgets such as a #GtkLabel or a #GtkEntry should be
|
|
packed. The second area is known as the
|
|
<structfield>action_area</structfield>. 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 #GtkHSeparator.
|
|
</para>
|
|
|
|
<para>
|
|
#GtkDialog boxes are created with a call to gtk_dialog_new() or
|
|
gtk_dialog_new_with_buttons(). gtk_dialog_new_with_buttons() is recommended; it
|
|
allows you to set the dialog title, some convenient flags, and add simple
|
|
buttons.
|
|
</para>
|
|
|
|
<para>
|
|
If 'dialog' is a newly created dialog, the two primary areas of the window
|
|
can be accessed as GTK_DIALOG(dialog)->vbox and GTK_DIALOG(dialog)->action_area,
|
|
as can be seen from the example, below.
|
|
</para>
|
|
|
|
<para>
|
|
A 'modal' dialog (that is, one which freezes the rest of the application from
|
|
user input), can be created by calling gtk_window_set_modal() on the dialog. Use
|
|
the GTK_WINDOW() macro to cast the widget returned from gtk_dialog_new() into a
|
|
#GtkWindow. When using gtk_dialog_new_with_buttons() you can also pass the
|
|
GTK_DIALOG_MODAL flag to make a dialog modal.
|
|
</para>
|
|
|
|
<para>
|
|
If you add buttons to #GtkDialog using gtk_dialog_new_with_buttons(),
|
|
gtk_dialog_add_button(), gtk_dialog_add_buttons(), or
|
|
gtk_dialog_add_action_widget(), clicking the button will emit a signal called
|
|
"response" with a response ID that you specified. GTK+ will never assign a
|
|
meaning to positive response IDs; these are entirely user-defined. But for
|
|
convenience, you can use the response IDs in the #GtkResponseType enumeration
|
|
(these all have values less than zero). If a dialog receives a delete event, the
|
|
"response" signal will be emitted with a response ID of GTK_RESPONSE_NONE.
|
|
</para>
|
|
|
|
|
|
<para>
|
|
If you want to block waiting for a dialog to return before returning control
|
|
flow to your code, you can call gtk_dialog_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.
|
|
</para>
|
|
|
|
<para>
|
|
For the simple dialog in the following example, in reality you'd probably use
|
|
#GtkMessageDialog to save yourself some effort. But you'd need to create the
|
|
dialog contents manually if you had more than a simple message in the dialog.
|
|
<example>
|
|
<title>Simple #GtkDialog usage.</title>
|
|
<programlisting>
|
|
|
|
/* Function to open a dialog box displaying the message provided. */
|
|
|
|
void quick_message(#gchar *message) {
|
|
|
|
#GtkWidget *dialog, *label;
|
|
|
|
/* Create the widgets */
|
|
|
|
dialog = gtk_dialog_new_with_buttons ("Message",
|
|
main_application_window,
|
|
GTK_DIALOG_DESTROY_WITH_PARENT,
|
|
GTK_STOCK_BUTTON_OK,
|
|
GTK_RESPONSE_NONE,
|
|
NULL);
|
|
label = gtk_label_new (message);
|
|
|
|
/* Ensure that the dialog box is destroyed when the user responds. */
|
|
|
|
gtk_signal_connect_object (GTK_OBJECT (dialog), "response",
|
|
GTK_SIGNAL_FUNC (gtk_widget_destroy),
|
|
GTK_OBJECT (dialog));
|
|
|
|
/* Add the label, and show everything we've added to the dialog. */
|
|
|
|
gtk_container_add (GTK_CONTAINER (GTK_DIALOG(dialog)->vbox),
|
|
label);
|
|
gtk_widget_show_all (dialog);
|
|
}
|
|
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
|
|
<!-- ##### SECTION See_Also ##### -->
|
|
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>#GtkVBox</term>
|
|
<listitem><para>Pack widgets vertically.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>#GtkWindow</term>
|
|
<listitem><para>Alter the properties of your dialog box.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>#GtkButton</term>
|
|
<listitem><para>Add them to the <structfield>action_area</structfield> to get a
|
|
response from the user.</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
|
|
<!-- ##### STRUCT GtkDialog ##### -->
|
|
<para>
|
|
<structfield>window</structfield> is a #GtkWindow, but should not be
|
|
modified directly, (use the functions provided, such as
|
|
gtk_window_set_title(). See the #GtkWindow section for more).
|
|
</para>
|
|
<para>
|
|
<structfield>vbox</structfield> is a #GtkVBox - the main part of the dialog box.
|
|
</para>
|
|
<para>
|
|
<structfield>action_area</structfield> is a #GtkHBox packed below the dividing #GtkHSeparator in the dialog. It is treated exactly the same as any other #GtkHBox.
|
|
</para>
|
|
|
|
|
|
<!-- ##### ENUM GtkDialogFlags ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@GTK_DIALOG_MODAL:
|
|
@GTK_DIALOG_DESTROY_WITH_PARENT:
|
|
@GTK_DIALOG_NO_SEPARATOR:
|
|
|
|
<!-- ##### ENUM GtkResponseType ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@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:
|
|
|
|
<!-- ##### FUNCTION gtk_dialog_new ##### -->
|
|
<para>
|
|
Creates a new dialog box. Widgets should not be packed into this #GtkWindow
|
|
directly, but into the vbox and action_area, as described above.
|
|
</para>
|
|
|
|
@Returns: a #GtkWidget - the newly created dialog box.
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_dialog_new_with_buttons ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@title:
|
|
@parent:
|
|
@flags:
|
|
@first_button_text:
|
|
@Varargs:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_dialog_run ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@dialog:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_dialog_response ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@dialog:
|
|
@response_id:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_dialog_add_button ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@dialog:
|
|
@button_text:
|
|
@response_id:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_dialog_add_buttons ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@dialog:
|
|
@first_button_text:
|
|
@Varargs:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_dialog_add_action_widget ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@dialog:
|
|
@child:
|
|
@response_id:
|
|
<!-- # Unused Parameters # -->
|
|
@widget:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_dialog_get_has_separator ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@dialog:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_dialog_set_default_response ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@dialog:
|
|
@response_id:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_dialog_set_has_separator ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@dialog:
|
|
@setting:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_dialog_set_response_sensitive ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@dialog:
|
|
@response_id:
|
|
@setting:
|
|
|
|
|
|
<!-- ##### SIGNAL GtkDialog::close ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@dialog: the object which received the signal.
|
|
|
|
<!-- ##### SIGNAL GtkDialog::response ##### -->
|
|
<para>
|
|
Emitted when an action widget is clicked, the dialog receives a delete event, or
|
|
the application programmer calls gtk_dialog_response(). On a delete event, the
|
|
response ID is GTK_RESPONSE_NONE. Otherwise, it depends on which action widget
|
|
was clicked.
|
|
</para>
|
|
|
|
@dialog: the object which received the signal.
|
|
@arg1: the response ID
|
|
|
|
<!-- ##### ARG GtkDialog:has-separator ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|