2 // Generated by gtkmmproc -- DO NOT MODIFY!
3 #ifndef _GTKMM_DIALOG_H
4 #define _GTKMM_DIALOG_H
12 * Copyright (C) 1998-2002 The gtkmm Development Team
14 * This library is free software; you can redistribute it and/or
15 * modify it under the terms of the GNU Library General Public
16 * License as published by the Free Software Foundation; either
17 * version 2 of the License, or (at your option) any later version.
19 * This library is distributed in the hope that it will be useful,
20 * but WITHOUT ANY WARRANTY; without even the implied warranty of
21 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
22 * Library General Public License for more details.
24 * You should have received a copy of the GNU Library General Public
25 * License along with this library; if not, write to the Free
26 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
29 #include <gtkmm/window.h>
30 #include <gtkmm/box.h>
31 #include <gtkmm/button.h>
32 #include <gtkmm/buttonbox.h>
35 #ifndef DOXYGEN_SHOULD_SKIP_THIS
36 typedef struct _GtkDialog GtkDialog;
37 typedef struct _GtkDialogClass GtkDialogClass;
38 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
42 { class Dialog_Class; } // namespace Gtk
46 /** @defgroup Dialogs Dialogs
50 /** @addtogroup gtkmmEnums Enums and Flags */
60 RESPONSE_DELETE_EVENT = -4,
73 #ifndef DOXYGEN_SHOULD_SKIP_THIS
78 class Value<Gtk::ResponseType> : public Glib::Value_Enum<Gtk::ResponseType>
81 static GType value_type() G_GNUC_CONST;
85 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
92 /** Create popup windows.
94 * Dialog boxes are a convenient way to prompt the user for a small amount
95 * of input, eg. to display a message, ask a question, or anything else that
96 * does not require extensive effort on the user's part.
98 * gtkmm treats a dialog as a window split vertically. The top section is a
99 * Gtk::VBox, and is where widgets such as a Gtk::Label or a Gtk::Entry should be
100 * packed. The bottom area is known as the action_area. This is generally
101 * used for packing buttons into the dialog which may perform functions such
102 * as cancel, ok, or apply. The two areas are separated by a Gtk::HSeparator.
104 * The dialog can be 'modal' (that is, one which freezes the rest of the
105 * application from user input) - this can be specified in the Gtk::Dialog
108 * When adding buttons using add_button(), clicking the button will emit
109 * signal_response() with a "response id" you specified. You are encouraged
110 * to use the Gtk::ResponseType enum. If a dialog receives a delete event,
111 * the "response" signal will be emitted with a response id of
112 * Gtk::RESPONSE_NONE.
114 * If you want to block waiting for a dialog to return before returning control
115 * flow to your code, you can call run(). This function enters a
116 * recursive main loop and waits for the user to respond to the dialog, returning
117 * the response ID corresponding to the button the user clicked.
122 class Dialog : public Window
125 #ifndef DOXYGEN_SHOULD_SKIP_THIS
126 typedef Dialog CppObjectType;
127 typedef Dialog_Class CppClassType;
128 typedef GtkDialog BaseObjectType;
129 typedef GtkDialogClass BaseClassType;
130 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
134 #ifndef DOXYGEN_SHOULD_SKIP_THIS
137 friend class Dialog_Class;
138 static CppClassType dialog_class_;
141 Dialog(const Dialog&);
142 Dialog& operator=(const Dialog&);
145 explicit Dialog(const Glib::ConstructParams& construct_params);
146 explicit Dialog(GtkDialog* castitem);
148 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
151 #ifndef DOXYGEN_SHOULD_SKIP_THIS
152 static GType get_type() G_GNUC_CONST;
153 static GType get_base_type() G_GNUC_CONST;
156 ///Provides access to the underlying C GtkObject.
157 GtkDialog* gobj() { return reinterpret_cast<GtkDialog*>(gobject_); }
159 ///Provides access to the underlying C GtkObject.
160 const GtkDialog* gobj() const { return reinterpret_cast<GtkDialog*>(gobject_); }
164 //C++ methods used to invoke GTK+ virtual functions:
167 //GTK+ Virtual Functions (override these to change behaviour):
169 //Default Signal Handlers::
170 virtual void on_response(int response_id);
178 explicit Dialog(const Glib::ustring& title, bool modal = false, bool use_separator = false);
179 Dialog(const Glib::ustring& title, Gtk::Window& parent, bool modal = false, bool use_separator = false);
182 /** Adds an activatable widget to the action area of a Gtk::Dialog,
183 * connecting a signal handler that will emit the "response" signal on
184 * the dialog when the widget is activated. The widget is appended to
185 * the end of the dialog's action area. If you want to add a
186 * non-activatable widget, simply pack it into the
187 * <tt>action_area</tt> field of the Gtk::Dialog struct.
188 * @param child An activatable widget.
189 * @param response_id Response ID for @a child .
191 void add_action_widget(Widget& child, int response_id);
193 /** Adds a button with the given text (or a stock button, if @a button_text is a
194 * stock ID) and sets things up so that clicking the button will emit the
195 * "response" signal with the given @a response_id . The button is appended to the
196 * end of the dialog's action area. The button widget is returned, but usually
198 * @param button_text Text of button, or stock ID.
199 * @param response_id Response ID for the button.
200 * @return The button widget that was added.
202 Button* add_button(const Glib::ustring& button_text, int response_id);
204 /** Adds a button with the given text (or a stock button, if @a button_text is a
205 * stock ID) and sets things up so that clicking the button will emit the
206 * "response" signal with the given @a response_id . The button is appended to the
207 * end of the dialog's action area. The button widget is returned, but usually
209 * @param button_text Text of button, or stock ID.
210 * @param response_id Response ID for the button.
211 * @return The button widget that was added.
213 Button* add_button(const Gtk::StockID& stock_id, int response_id);
215 /** Calls <tt>gtk_widget_set_sensitive (widget, @a setting )</tt>
216 * for each widget in the dialog's action area with the given @a response_id .
217 * A convenient way to sensitize/desensitize dialog buttons.
218 * @param response_id A response ID.
219 * @param setting <tt>true</tt> for sensitive.
221 void set_response_sensitive(int response_id, bool setting = true);
223 /** Sets the last widget in the dialog's action area with the given @a response_id
224 * as the default widget for the dialog. Pressing "Enter" normally activates
225 * the default widget.
226 * @param response_id A response ID.
228 void set_default_response(int response_id);
230 /** Sets whether the dialog has a separator above the buttons.
231 * <tt>true</tt> by default.
232 * @param setting <tt>true</tt> to have a separator.
234 void set_has_separator(bool setting = true);
236 /** Accessor for whether the dialog has a separator.
237 * @return <tt>true</tt> if the dialog has a separator.
239 bool get_has_separator() const;
242 /** Returns <tt>true</tt> if dialogs are expected to use an alternative
243 * button order on the screen @a screen . See
244 * Gtk::Dialog::set_alternative_button_order() for more details
245 * about alternative button order.
247 * If you need to use this function, you should probably connect
248 * to the ::notify:gtk-alternative-button-order signal on the
249 * Gtk::Settings object associated to @a screen , in order to be
250 * notified if the button order setting changes.
251 * @param screen A Gdk::Screen, or <tt>0</tt> to use the default screen.
252 * @return Whether the alternative button order should be used
256 static bool alternative_button_order(const Glib::RefPtr<const Gdk::Screen>& screen);
258 //TODO: Document this:
259 void set_alternative_button_order_from_array(const Glib::ArrayHandle<int>& new_order);
262 /** Emits the "response" signal with the given response ID. Used to
263 * indicate that the user has responded to the dialog in some way;
264 * typically either you or run() will be monitoring the
265 * "response" signal and take appropriate action.
266 * @param response_id Response ID.
268 void response(int response_id);
270 /** Blocks in a recursive main loop until the @a dialog emits the
271 * response signal. It returns the response ID from the "response" signal emission.
272 * Before entering the recursive main loop, run() calls
273 * Gtk::Widget::show() on the dialog for you. Note that you still
274 * need to show any children of the dialog yourself.
276 * If the dialog receives "delete_event", Gtk::Dialog::run() will return
277 * Gtk::RESPONSE_DELETE_EVENT. Also, during Gtk::Dialog::run() the dialog will be
278 * modal. You can force Gtk::Dialog::run() to return at any time by
279 * calling Gtk::Dialog::response() to emit the "response"
282 * After Gtk::Dialog::run() returns, you are responsible for hiding or
283 * destroying the dialog if you wish to do so.
285 * Typical usage of this function might be:
287 * <tt>int</tt> result = dialog.run();
290 * case GTK_RESPONSE_ACCEPT:
291 * do_application_specific_something (<!-- -->);
294 * do_nothing_since_dialog_was_cancelled (<!-- -->);
298 * @return Response ID.
303 const VBox* get_vbox() const;
304 HButtonBox* get_action_area();
305 const HButtonBox* get_action_area() const;
307 /** The dialog has a separator bar above its buttons.
309 * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
310 * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
311 * the value of the property changes.
313 Glib::PropertyProxy<bool> property_has_separator() ;
315 /** The dialog has a separator bar above its buttons.
317 * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
318 * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
319 * the value of the property changes.
321 Glib::PropertyProxy_ReadOnly<bool> property_has_separator() const;
324 Glib::SignalProxy1< void,int > signal_response();
328 void construct_(bool modal, bool use_separator);
333 } /* namespace Gtk */
338 /** @relates Gtk::Dialog
339 * @param object The C instance
340 * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
341 * @result A C++ instance that wraps this C instance.
343 Gtk::Dialog* wrap(GtkDialog* object, bool take_copy = false);
345 #endif /* _GTKMM_DIALOG_H */