1 // -*- c++ -*- 2 // Generated by gmmproc 2.45.3 -- DO NOT MODIFY! 3 #ifndef _GTKMM_DIALOG_H 4 #define _GTKMM_DIALOG_H 5 6 7 #include <glibmm/ustring.h> 8 #include <sigc++/sigc++.h> 9 10 /* $Id: dialog.hg,v 1.8 2006/03/22 16:53:22 murrayc Exp $ */ 11 12 /* dialog.h 13 * 14 * Copyright (C) 1998-2002 The gtkmm Development Team 15 * 16 * This library is free software; you can redistribute it and/or 17 * modify it under the terms of the GNU Lesser General Public 18 * License as published by the Free Software Foundation; either 19 * version 2.1 of the License, or (at your option) any later version. 20 * 21 * This library is distributed in the hope that it will be useful, 22 * but WITHOUT ANY WARRANTY; without even the implied warranty of 23 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 24 * Lesser General Public License for more details. 25 * 26 * You should have received a copy of the GNU Lesser General Public 27 * License along with this library; if not, write to the Free 28 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 29 */ 30 31 #include <gtkmm/box.h> 32 #include <gtkmm/window.h> 33 #include <gtkmm/button.h> 34 #include <gtkmm/buttonbox.h> 35 36 37 #ifndef DOXYGEN_SHOULD_SKIP_THIS 38 typedef struct _GtkDialog GtkDialog; 39 typedef struct _GtkDialogClass GtkDialogClass; 40 #endif /* DOXYGEN_SHOULD_SKIP_THIS */ 41 42 43 namespace Gtk 44 { class Dialog_Class; } // namespace Gtk 45 namespace Gtk 46 { 47 48 /** @defgroup Dialogs Dialogs 49 */ 50 51 52 /** @addtogroup gtkmmEnums gtkmm Enums and Flags */ 53 54 /** 55 * 56 * @ingroup gtkmmEnums 57 */ 58 enum ResponseType 59 { 60 RESPONSE_NONE = -1, 61 RESPONSE_REJECT = -2, 62 RESPONSE_ACCEPT = -3, 63 RESPONSE_DELETE_EVENT = -4, 64 RESPONSE_OK = -5, 65 RESPONSE_CANCEL = -6, 66 RESPONSE_CLOSE = -7, 67 RESPONSE_YES = -8, 68 RESPONSE_NO = -9, 69 RESPONSE_APPLY = -10, 70 RESPONSE_HELP = -11 71 }; 72 73 } // namespace Gtk 74 75 76 #ifndef DOXYGEN_SHOULD_SKIP_THIS 77 namespace Glib 78 { 79 80 template <> 81 class Value<Gtk::ResponseType> : public Glib::Value_Enum<Gtk::ResponseType> 82 { 83 public: 84 static GType value_type() G_GNUC_CONST; 85 }; 86 87 } // namespace Glib 88 #endif /* DOXYGEN_SHOULD_SKIP_THIS */ 89 90 91 namespace Gtk 92 { 93 94 95 /** Create popup windows. 96 * 97 * Dialog boxes are a convenient way to prompt the user for a small amount 98 * of input, eg. to display a message, ask a question, or anything else that 99 * does not require extensive effort on the user's part. 100 * 101 * gtkmm treats a dialog as a window split vertically. The top section is a 102 * Gtk::VBox, and is where widgets such as a Gtk::Label or a Gtk::Entry should be 103 * packed. The bottom area is known as the action_area. This is generally 104 * used for packing buttons into the dialog which may perform functions such 105 * as cancel, ok, or apply. The two areas are separated by a Gtk::HSeparator. 106 * 107 * The dialog can be 'modal' (that is, one which freezes the rest of the 108 * application from user input) - this can be specified in the Gtk::Dialog 109 * constructor. 110 * 111 * When adding buttons using add_button(), clicking the button will emit 112 * signal_response() with a "response id" you specified. You are encouraged 113 * to use the Gtk::ResponseType enum. If a dialog receives a delete event, 114 * the "response" signal will be emitted with a response id of 115 * Gtk::RESPONSE_NONE. 116 * 117 * If you want to block waiting for a dialog to return before returning control 118 * flow to your code, you can call run(). This function enters a 119 * recursive main loop and waits for the user to respond to the dialog, returning 120 * the response ID corresponding to the button the user clicked. 121 * 122 * @ingroup Dialogs 123 */ 124 125 class Dialog : public Window 126 { 127 public: 128 #ifndef DOXYGEN_SHOULD_SKIP_THIS 129 typedef Dialog CppObjectType; 130 typedef Dialog_Class CppClassType; 131 typedef GtkDialog BaseObjectType; 132 typedef GtkDialogClass BaseClassType; 133 #endif /* DOXYGEN_SHOULD_SKIP_THIS */ 134 135 virtual ~Dialog(); 136 137 #ifndef DOXYGEN_SHOULD_SKIP_THIS 138 139 private: 140 friend class Dialog_Class; 141 static CppClassType dialog_class_; 142 143 // noncopyable 144 Dialog(const Dialog&); 145 Dialog& operator=(const Dialog&); 146 147 protected: 148 explicit Dialog(const Glib::ConstructParams& construct_params); 149 explicit Dialog(GtkDialog* castitem); 150 151 #endif /* DOXYGEN_SHOULD_SKIP_THIS */ 152 153 public: 154 #ifndef DOXYGEN_SHOULD_SKIP_THIS 155 static GType get_type() G_GNUC_CONST; 156 157 158 static GType get_base_type() G_GNUC_CONST; 159 #endif 160 161 ///Provides access to the underlying C GtkObject. gobj()162 GtkDialog* gobj() { return reinterpret_cast<GtkDialog*>(gobject_); } 163 164 ///Provides access to the underlying C GtkObject. gobj()165 const GtkDialog* gobj() const { return reinterpret_cast<GtkDialog*>(gobject_); } 166 167 168 public: 169 //C++ methods used to invoke GTK+ virtual functions: 170 171 protected: 172 //GTK+ Virtual Functions (override these to change behaviour): 173 174 //Default Signal Handlers:: 175 /// This is a default handler for the signal signal_response(). 176 virtual void on_response(int response_id); 177 178 179 private: 180 181 182 public: 183 Dialog(); 184 explicit Dialog(const Glib::ustring& title, bool modal = false, bool use_separator = false); 185 Dialog(const Glib::ustring& title, Gtk::Window& parent, bool modal = false, bool use_separator = false); 186 187 188 /** Adds an activatable widget to the action area of a Gtk::Dialog, 189 * connecting a signal handler that will emit the Gtk::Dialog::signal_response() 190 * signal on the dialog when the widget is activated. The widget is 191 * appended to the end of the dialog's action area. If you want to add a 192 * non-activatable widget, simply pack it into the @a action_area field 193 * of the Gtk::Dialog struct. 194 * 195 * @param child An activatable widget. 196 * @param response_id Response ID for @a child. 197 */ 198 void add_action_widget(Widget& child, int response_id); 199 200 /** Adds a button with the given text (or a stock button, if @a button_text is a 201 * stock ID) and sets things up so that clicking the button will emit the 202 * Gtk::Dialog::signal_response() signal with the given @a response_id. The button is 203 * appended to the end of the dialog's action area. The button widget is 204 * returned, but usually you don't need it. 205 * 206 * @param button_text Text of button, or stock ID. 207 * @param response_id Response ID for the button. 208 * @return The button widget that was added. 209 */ 210 Button* add_button(const Glib::ustring& button_text, int response_id); 211 212 /** Adds a button with the given text (or a stock button, if @a button_text is a 213 * stock ID) and sets things up so that clicking the button will emit the 214 * Gtk::Dialog::signal_response() signal with the given @a response_id. The button is 215 * appended to the end of the dialog's action area. The button widget is 216 * returned, but usually you don't need it. 217 * 218 * @param button_text Text of button, or stock ID. 219 * @param response_id Response ID for the button. 220 * @return The button widget that was added. 221 */ 222 Button* add_button(const Gtk::StockID& stock_id, int response_id); 223 224 /** Calls <tt>gtk_widget_set_sensitive (widget, @a setting)</tt> 225 * for each widget in the dialog's action area with the given @a response_id. 226 * A convenient way to sensitize/desensitize dialog buttons. 227 * 228 * @param response_id A response ID. 229 * @param setting <tt>true</tt> for sensitive. 230 */ 231 void set_response_sensitive(int response_id, bool setting = true); 232 233 /** Sets the last widget in the dialog's action area with the given @a response_id 234 * as the default widget for the dialog. Pressing "Enter" normally activates 235 * the default widget. 236 * 237 * @param response_id A response ID. 238 */ 239 void set_default_response(int response_id); 240 241 /** Gets the widget button that uses the given response ID in the action area 242 * of a dialog. 243 * 244 * @newin{2,20} 245 * 246 * @param response_id The response ID used by the @a dialog widget. 247 * @return The @a widget button that uses the given @a response_id, or <tt>0</tt>. 248 */ 249 Widget* get_widget_for_response(int response_id); 250 251 /** Gets the widget button that uses the given response ID in the action area 252 * of a dialog. 253 * 254 * @newin{2,20} 255 * 256 * @param response_id The response ID used by the @a dialog widget. 257 * @return The @a widget button that uses the given @a response_id, or <tt>0</tt>. 258 */ 259 const Widget* get_widget_for_response(int response_id) const; 260 261 /** Gets the response id of a widget in the action area 262 * of a dialog. 263 * 264 * @newin{2,8} 265 * 266 * @param widget A widget in the action area of @a dialog. 267 * @return The response id of @a widget, or Gtk::RESPONSE_NONE 268 * if @a widget doesn't have a response id set. 269 */ 270 int get_response_for_widget(const Gtk::Widget& widget) const; 271 272 /** Sets whether the dialog has a separator above the buttons. 273 * 274 * Deprecated: 2.22: This function will be removed in GTK+ 3 275 * 276 * @param setting <tt>true</tt> to have a separator. 277 */ 278 void set_has_separator(bool setting = true); 279 280 /** Accessor for whether the dialog has a separator. 281 * 282 * Deprecated: 2.22: This function will be removed in GTK+ 3 283 * 284 * @return <tt>true</tt> if the dialog has a separator. 285 */ 286 bool get_has_separator() const; 287 288 289 /** Returns <tt>true</tt> if dialogs are expected to use an alternative 290 * button order on the screen @a screen. See 291 * Gtk::Dialog::set_alternative_button_order() for more details 292 * about alternative button order. 293 * 294 * If you need to use this function, you should probably connect 295 * to the ::notify:gtk-alternative-button-order signal on the 296 * Gtk::Settings object associated to @a screen, in order to be 297 * notified if the button order setting changes. 298 * 299 * @newin{2,6} 300 * 301 * @param screen A Gdk::Screen, or <tt>0</tt> to use the default screen. 302 * @return Whether the alternative button order should be used. 303 */ 304 static bool alternative_button_order(const Glib::RefPtr<const Gdk::Screen>& screen); 305 306 /** Sets an alternative button order. If the gtk-alternative-button-order 307 * setting is set to true, the dialog buttons are reordered according to 308 * the order of the response ids in @a new_order. 309 * 310 * By default, GTK+ dialogs use the button order advocated by the Gnome 311 * <ulink url="http://developer.gnome.org/projects/gup/hig/2.0/">Human 312 * Interface Guidelines</ulink> with the affirmative button at the far 313 * right, and the cancel button left of it. But the builtin GTK+ dialogs 314 * and #GtkMessageDialog<!-- -->s do provide an alternative button order, 315 * which is more suitable on some platforms, e.g. Windows. 316 * 317 * Use this function after adding all the buttons to your dialog 318 * 319 * @param new_order an array of response ids of the dialog's buttons. 320 * 321 * @newinp26 322 */ 323 void set_alternative_button_order_from_array(const Glib::ArrayHandle<int>& new_order); 324 325 326 /** Emits the Gtk::Dialog::signal_response() signal with the given response ID. 327 * Used to indicate that the user has responded to the dialog in some way; 328 * typically either you or run() will be monitoring the 329 * signal_response() signal and take appropriate action. 330 * 331 * @param response_id Response ID. 332 */ 333 void response(int response_id); 334 335 /** Blocks in a recursive main loop until the @a dialog emits the 336 * response signal. It returns the response ID from the "response" signal emission. 337 * Before entering the recursive main loop, run() calls 338 * Gtk::Widget::show() on the dialog for you. Note that you still 339 * need to show any children of the dialog yourself. 340 * 341 * If the dialog receives "delete_event", Gtk::Dialog::run() will return 342 * Gtk::RESPONSE_DELETE_EVENT. Also, during Gtk::Dialog::run() the dialog will be 343 * modal. You can force Gtk::Dialog::run() to return at any time by 344 * calling Gtk::Dialog::response() to emit the "response" 345 * signal. 346 * 347 * After Gtk::Dialog::run() returns, you are responsible for hiding or 348 * destroying the dialog if you wish to do so. 349 * 350 * Typical usage of this function might be: 351 * <informalexample><programlisting> 352 * int result = dialog.run(); 353 * switch (result) 354 * { 355 * case Gtk::RESPONSE_ACCEPT: 356 * do_application_specific_something(); 357 * break; 358 * default: 359 * do_nothing_since_dialog_was_cancelled(); 360 * break; 361 * } 362 * </programlisting></informalexample> 363 * 364 * @return Response ID. 365 */ 366 int run(); 367 368 // This previously returned an HButtonBox*, which broke on Maemo Fremantle. 369 // Changed post-2.18.2 370 371 /** Returns the action area of @a dialog. 372 * 373 * @newin{2,14} 374 * 375 * @return The action area. 376 */ 377 ButtonBox* get_action_area(); 378 379 /** Returns the action area of @a dialog. 380 * 381 * @newin{2,14} 382 * 383 * @return The action area. 384 */ 385 const ButtonBox* get_action_area() const; 386 387 //TODO: Rename to get_content_area() when we do an ABI break. 388 //We kept it as get_vbox() when reimplementing a MEMBER_GET with this new C function: 389 390 /** Returns the content area of @a dialog. 391 * 392 * @newin{2,14} 393 * 394 * @return The content area Gtk::VBox. 395 */ 396 VBox* get_vbox(); 397 398 /** Returns the content area of @a dialog. 399 * 400 * @newin{2,14} 401 * 402 * @return The content area Gtk::VBox. 403 */ 404 const VBox* get_vbox() const; 405 406 /** The dialog has a separator bar above its buttons. 407 * 408 * @return A PropertyProxy that allows you to get or set the value of the property, 409 * or receive notification when the value of the property changes. 410 */ 411 Glib::PropertyProxy< bool > property_has_separator() ; 412 413 /** The dialog has a separator bar above its buttons. 414 * 415 * @return A PropertyProxy_ReadOnly that allows you to get the value of the property, 416 * or receive notification when the value of the property changes. 417 */ 418 Glib::PropertyProxy_ReadOnly< bool > property_has_separator() const; 419 420 421 /** 422 * @par Slot Prototype: 423 * <tt>void on_my_%response(int response_id)</tt> 424 * 425 */ 426 427 Glib::SignalProxy1< void,int > signal_response(); 428 429 430 //_WRAP_PROPERTY("has-separator", bool) //deprecated. 431 432 433 protected: 434 void construct_(bool modal, bool use_separator); 435 436 437 }; 438 439 } /* namespace Gtk */ 440 441 442 namespace Glib 443 { 444 /** A Glib::wrap() method for this object. 445 * 446 * @param object The C instance. 447 * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref. 448 * @result A C++ instance that wraps this C instance. 449 * 450 * @relates Gtk::Dialog 451 */ 452 Gtk::Dialog* wrap(GtkDialog* object, bool take_copy = false); 453 } //namespace Glib 454 455 456 #endif /* _GTKMM_DIALOG_H */ 457 458