1 /* 2 * This file is part of gtkD. 3 * 4 * gtkD is free software; you can redistribute it and/or modify 5 * it under the terms of the GNU Lesser General Public License 6 * as published by the Free Software Foundation; either version 3 7 * of the License, or (at your option) any later version, with 8 * some exceptions, please read the COPYING file. 9 * 10 * gtkD is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 * GNU Lesser General Public License for more details. 14 * 15 * You should have received a copy of the GNU Lesser General Public License 16 * along with gtkD; if not, write to the Free Software 17 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA 18 */ 19 20 // generated automatically - do not change 21 // find conversion definition on APILookup.txt 22 // implement new conversion functionalities on the wrap.utils pakage 23 24 25 module gtk.Dialog; 26 27 private import gdk.Screen; 28 private import glib.ConstructionException; 29 private import glib.Str; 30 private import gobject.ObjectG; 31 private import gobject.Signals; 32 private import gtk.Button; 33 private import gtk.HButtonBox; 34 private import gtk.VBox; 35 private import gtk.Widget; 36 private import gtk.Window; 37 private import gtkc.gtk; 38 public import gtkc.gtktypes; 39 private import std.algorithm; 40 41 42 /** 43 * Dialog boxes are a convenient way to prompt the user for a small amount 44 * of input, e.g. to display a message, ask a question, or anything else 45 * that does not require extensive effort on the user’s part. 46 * 47 * GTK+ treats a dialog as a window split vertically. The top section is a 48 * #GtkVBox, and is where widgets such as a #GtkLabel or a #GtkEntry should 49 * be packed. The bottom area is known as the 50 * “action area”. This is generally used for 51 * packing buttons into the dialog which may perform functions such as 52 * cancel, ok, or apply. 53 * 54 * #GtkDialog boxes are created with a call to gtk_dialog_new() or 55 * gtk_dialog_new_with_buttons(). gtk_dialog_new_with_buttons() is 56 * recommended; it allows you to set the dialog title, some convenient 57 * flags, and add simple buttons. 58 * 59 * If “dialog” is a newly created dialog, the two primary areas of the 60 * window can be accessed through gtk_dialog_get_content_area() and 61 * gtk_dialog_get_action_area(), as can be seen from the example below. 62 * 63 * A “modal” dialog (that is, one which freezes the rest of the application 64 * from user input), can be created by calling gtk_window_set_modal() on the 65 * dialog. Use the GTK_WINDOW() macro to cast the widget returned from 66 * gtk_dialog_new() into a #GtkWindow. When using gtk_dialog_new_with_buttons() 67 * you can also pass the #GTK_DIALOG_MODAL flag to make a dialog modal. 68 * 69 * If you add buttons to #GtkDialog using gtk_dialog_new_with_buttons(), 70 * gtk_dialog_add_button(), gtk_dialog_add_buttons(), or 71 * gtk_dialog_add_action_widget(), clicking the button will emit a signal 72 * called #GtkDialog::response with a response ID that you specified. GTK+ 73 * will never assign a meaning to positive response IDs; these are entirely 74 * user-defined. But for convenience, you can use the response IDs in the 75 * #GtkResponseType enumeration (these all have values less than zero). If 76 * a dialog receives a delete event, the #GtkDialog::response signal will 77 * be emitted with a response ID of #GTK_RESPONSE_DELETE_EVENT. 78 * 79 * If you want to block waiting for a dialog to return before returning 80 * control flow to your code, you can call gtk_dialog_run(). This function 81 * enters a recursive main loop and waits for the user to respond to the 82 * dialog, returning the response ID corresponding to the button the user 83 * clicked. 84 * 85 * For the simple dialog in the following example, in reality you’d probably 86 * use #GtkMessageDialog to save yourself some effort. But you’d need to 87 * create the dialog contents manually if you had more than a simple message 88 * in the dialog. 89 * 90 * An example for simple GtkDialog usage: 91 * |[<!-- language="C" --> 92 * // Function to open a dialog box with a message 93 * void 94 * quick_message (GtkWindow *parent, gchar *message) 95 * { 96 * GtkWidget *dialog, *label, *content_area; 97 * GtkDialogFlags flags; 98 * 99 * // Create the widgets 100 * flags = GTK_DIALOG_DESTROY_WITH_PARENT; 101 * dialog = gtk_dialog_new_with_buttons ("Message", 102 * parent, 103 * flags, 104 * _("_OK"), 105 * GTK_RESPONSE_NONE, 106 * NULL); 107 * content_area = gtk_dialog_get_content_area (GTK_DIALOG (dialog)); 108 * label = gtk_label_new (message); 109 * 110 * // Ensure that the dialog box is destroyed when the user responds 111 * 112 * g_signal_connect_swapped (dialog, 113 * "response", 114 * G_CALLBACK (gtk_widget_destroy), 115 * dialog); 116 * 117 * // Add the label, and show everything we’ve added 118 * 119 * gtk_container_add (GTK_CONTAINER (content_area), label); 120 * gtk_widget_show_all (dialog); 121 * } 122 * ]| 123 * 124 * # GtkDialog as GtkBuildable 125 * 126 * The GtkDialog implementation of the #GtkBuildable interface exposes the 127 * @vbox and @action_area as internal children with the names “vbox” and 128 * “action_area”. 129 * 130 * GtkDialog supports a custom <action-widgets> element, which can contain 131 * multiple <action-widget> elements. The “response” attribute specifies a 132 * numeric response, and the content of the element is the id of widget 133 * (which should be a child of the dialogs @action_area). To mark a response 134 * as default, set the “default“ attribute of the <action-widget> element 135 * to true. 136 * 137 * GtkDialog supports adding action widgets by specifying “action“ as 138 * the “type“ attribute of a <child> element. The widget will be added 139 * either to the action area or the headerbar of the dialog, depending 140 * on the “use-header-bar“ property. The response id has to be associated 141 * with the action widget using the <action-widgets> element. 142 * 143 * An example of a #GtkDialog UI definition fragment: 144 * |[ 145 * <object class="GtkDialog" id="dialog1"> 146 * <child type="action"> 147 * <object class="GtkButton" id="button_cancel"/> 148 * </child> 149 * <child type="action"> 150 * <object class="GtkButton" id="button_ok"> 151 * <property name="can-default">True</property> 152 * </object> 153 * </child> 154 * <action-widgets> 155 * <action-widget response="cancel">button_cancel</action-widget> 156 * <action-widget response="ok" default="true">button_ok</action-widget> 157 * </action-widgets> 158 * </object> 159 * ]| 160 */ 161 public class Dialog : Window 162 { 163 /** the main Gtk struct */ 164 protected GtkDialog* gtkDialog; 165 166 /** Get the main Gtk struct */ 167 public GtkDialog* getDialogStruct(bool transferOwnership = false) 168 { 169 if (transferOwnership) 170 ownedRef = false; 171 return gtkDialog; 172 } 173 174 /** the main Gtk struct as a void* */ 175 protected override void* getStruct() 176 { 177 return cast(void*)gtkDialog; 178 } 179 180 protected override void setStruct(GObject* obj) 181 { 182 gtkDialog = cast(GtkDialog*)obj; 183 super.setStruct(obj); 184 } 185 186 /** 187 * Sets our main struct and passes it to the parent class. 188 */ 189 public this (GtkDialog* gtkDialog, bool ownedRef = false) 190 { 191 this.gtkDialog = gtkDialog; 192 super(cast(GtkWindow*)gtkDialog, ownedRef); 193 } 194 195 /** 196 * Both title and parent can be null. 197 */ 198 this(string title, Window parent, GtkDialogFlags flags, string[] buttonsText, ResponseType[] responses) 199 { 200 auto p = gtk_dialog_new_with_buttons(Str.toStringz(title), (parent is null) ? null : parent.getWindowStruct(), flags, Str.toStringz(buttonsText[0]), responses[0], null); 201 if(p is null) 202 { 203 throw new ConstructionException("null returned by gtk_dialog_new_with_buttons"); 204 } 205 206 this(cast(GtkDialog*)p); 207 208 addButtons(buttonsText[1 .. $], responses[1 .. $]); 209 } 210 211 /** ditto */ 212 this(string title, Window parent, GtkDialogFlags flags, StockID[] stockIDs, ResponseType[] responses) 213 { 214 auto p = gtk_dialog_new_with_buttons(Str.toStringz(title), (parent is null) ? null : parent.getWindowStruct(), flags, Str.toStringz(stockIDs[0]), responses[0], null); 215 if(p is null) 216 { 217 throw new ConstructionException("null returned by gtk_dialog_new_with_buttons"); 218 } 219 220 this(cast(GtkDialog*)p); 221 222 addButtons(stockIDs[1 .. $], responses[1 .. $]); 223 } 224 225 /** */ 226 public Button addButton(StockID stockID, int responseId) 227 { 228 auto p = gtk_dialog_add_button(gtkDialog, Str.toStringz(stockID), responseId); 229 230 if ( p is null ) 231 { 232 return null; 233 } 234 235 return new Button(cast(GtkButton*)p); 236 } 237 238 /** */ 239 public void addButtons(string[] buttonsText, ResponseType[] responses) 240 { 241 for ( int i=0 ; i<buttonsText.length && i<responses.length ; i++) 242 { 243 addButton(buttonsText[i], responses[i]); 244 } 245 } 246 247 /** */ 248 public void addButtons(StockID[] stockIDs, ResponseType[] responses) 249 { 250 for ( int i=0 ; i<stockIDs.length && i<responses.length ; i++) 251 { 252 addButton(stockIDs[i], responses[i]); 253 } 254 } 255 256 //Return the corect class instead of Widget 257 /** 258 * Returns the action area of dialog. 259 * Since: 2.14 260 * Returns: the action area. 261 */ 262 public HButtonBox getActionArea() 263 { 264 auto p = gtk_dialog_get_action_area(gtkDialog); 265 if(p is null) 266 { 267 return null; 268 } 269 return new HButtonBox(cast(GtkHButtonBox*) p); 270 } 271 272 //Return the corect class instead of Widget 273 /** 274 * Returns the content area of dialog. 275 * Since: 2.14 276 * Returns: the content area GtkVBox. 277 */ 278 public VBox getContentArea() 279 { 280 auto p = gtk_dialog_get_content_area(gtkDialog); 281 if(p is null) 282 { 283 return null; 284 } 285 return new VBox(cast(GtkVBox*) p); 286 } 287 288 /** 289 */ 290 291 /** */ 292 public static GType getType() 293 { 294 return gtk_dialog_get_type(); 295 } 296 297 /** 298 * Creates a new dialog box. 299 * 300 * Widgets should not be packed into this #GtkWindow 301 * directly, but into the @vbox and @action_area, as described above. 302 * 303 * Returns: the new dialog as a #GtkWidget 304 * 305 * Throws: ConstructionException GTK+ fails to create the object. 306 */ 307 public this() 308 { 309 auto p = gtk_dialog_new(); 310 311 if(p is null) 312 { 313 throw new ConstructionException("null returned by new"); 314 } 315 316 this(cast(GtkDialog*) p); 317 } 318 319 /** 320 * Adds an activatable widget to the action area of a #GtkDialog, 321 * connecting a signal handler that will emit the #GtkDialog::response 322 * signal on the dialog when the widget is activated. The widget is 323 * appended to the end of the dialog’s action area. If you want to add a 324 * non-activatable widget, simply pack it into the @action_area field 325 * of the #GtkDialog struct. 326 * 327 * Params: 328 * child = an activatable widget 329 * responseId = response ID for @child 330 */ 331 public void addActionWidget(Widget child, int responseId) 332 { 333 gtk_dialog_add_action_widget(gtkDialog, (child is null) ? null : child.getWidgetStruct(), responseId); 334 } 335 336 /** 337 * Adds a button with the given text and sets things up so that 338 * clicking the button will emit the #GtkDialog::response signal with 339 * the given @response_id. The button is appended to the end of the 340 * dialog’s action area. The button widget is returned, but usually 341 * you don’t need it. 342 * 343 * Params: 344 * buttonText = text of button 345 * responseId = response ID for the button 346 * 347 * Returns: the #GtkButton widget that was added 348 */ 349 public Widget addButton(string buttonText, int responseId) 350 { 351 auto p = gtk_dialog_add_button(gtkDialog, Str.toStringz(buttonText), responseId); 352 353 if(p is null) 354 { 355 return null; 356 } 357 358 return ObjectG.getDObject!(Widget)(cast(GtkWidget*) p); 359 } 360 361 /** 362 * Returns the header bar of @dialog. Note that the 363 * headerbar is only used by the dialog if the 364 * #GtkDialog:use-header-bar property is %TRUE. 365 * 366 * Returns: the header bar 367 * 368 * Since: 3.12 369 */ 370 public Widget getHeaderBar() 371 { 372 auto p = gtk_dialog_get_header_bar(gtkDialog); 373 374 if(p is null) 375 { 376 return null; 377 } 378 379 return ObjectG.getDObject!(Widget)(cast(GtkWidget*) p); 380 } 381 382 /** 383 * Gets the response id of a widget in the action area 384 * of a dialog. 385 * 386 * Params: 387 * widget = a widget in the action area of @dialog 388 * 389 * Returns: the response id of @widget, or %GTK_RESPONSE_NONE 390 * if @widget doesn’t have a response id set. 391 * 392 * Since: 2.8 393 */ 394 public int getResponseForWidget(Widget widget) 395 { 396 return gtk_dialog_get_response_for_widget(gtkDialog, (widget is null) ? null : widget.getWidgetStruct()); 397 } 398 399 /** 400 * Gets the widget button that uses the given response ID in the action area 401 * of a dialog. 402 * 403 * Params: 404 * responseId = the response ID used by the @dialog widget 405 * 406 * Returns: the @widget button that uses the given 407 * @response_id, or %NULL. 408 * 409 * Since: 2.20 410 */ 411 public Widget getWidgetForResponse(int responseId) 412 { 413 auto p = gtk_dialog_get_widget_for_response(gtkDialog, responseId); 414 415 if(p is null) 416 { 417 return null; 418 } 419 420 return ObjectG.getDObject!(Widget)(cast(GtkWidget*) p); 421 } 422 423 /** 424 * Emits the #GtkDialog::response signal with the given response ID. 425 * Used to indicate that the user has responded to the dialog in some way; 426 * typically either you or gtk_dialog_run() will be monitoring the 427 * ::response signal and take appropriate action. 428 * 429 * Params: 430 * responseId = response ID 431 */ 432 public void response(int responseId) 433 { 434 gtk_dialog_response(gtkDialog, responseId); 435 } 436 437 /** 438 * Blocks in a recursive main loop until the @dialog either emits the 439 * #GtkDialog::response signal, or is destroyed. If the dialog is 440 * destroyed during the call to gtk_dialog_run(), gtk_dialog_run() returns 441 * #GTK_RESPONSE_NONE. Otherwise, it returns the response ID from the 442 * ::response signal emission. 443 * 444 * Before entering the recursive main loop, gtk_dialog_run() calls 445 * gtk_widget_show() on the dialog for you. Note that you still 446 * need to show any children of the dialog yourself. 447 * 448 * During gtk_dialog_run(), the default behavior of #GtkWidget::delete-event 449 * is disabled; if the dialog receives ::delete_event, it will not be 450 * destroyed as windows usually are, and gtk_dialog_run() will return 451 * #GTK_RESPONSE_DELETE_EVENT. Also, during gtk_dialog_run() the dialog 452 * will be modal. You can force gtk_dialog_run() to return at any time by 453 * calling gtk_dialog_response() to emit the ::response signal. Destroying 454 * the dialog during gtk_dialog_run() is a very bad idea, because your 455 * post-run code won’t know whether the dialog was destroyed or not. 456 * 457 * After gtk_dialog_run() returns, you are responsible for hiding or 458 * destroying the dialog if you wish to do so. 459 * 460 * Typical usage of this function might be: 461 * |[<!-- language="C" --> 462 * gint result = gtk_dialog_run (GTK_DIALOG (dialog)); 463 * switch (result) 464 * { 465 * case GTK_RESPONSE_ACCEPT: 466 * do_application_specific_something (); 467 * break; 468 * default: 469 * do_nothing_since_dialog_was_cancelled (); 470 * break; 471 * } 472 * gtk_widget_destroy (dialog); 473 * ]| 474 * 475 * Note that even though the recursive main loop gives the effect of a 476 * modal dialog (it prevents the user from interacting with other 477 * windows in the same window group while the dialog is run), callbacks 478 * such as timeouts, IO channel watches, DND drops, etc, will 479 * be triggered during a gtk_dialog_run() call. 480 * 481 * Returns: response ID 482 */ 483 public int run() 484 { 485 return gtk_dialog_run(gtkDialog); 486 } 487 488 /** 489 * Sets an alternative button order. If the 490 * #GtkSettings:gtk-alternative-button-order setting is set to %TRUE, 491 * the dialog buttons are reordered according to the order of the 492 * response ids in @new_order. 493 * 494 * See gtk_dialog_set_alternative_button_order() for more information. 495 * 496 * This function is for use by language bindings. 497 * 498 * Deprecated: Deprecated 499 * 500 * Params: 501 * nParams = the number of response ids in @new_order 502 * newOrder = an array of response ids of 503 * @dialog’s buttons 504 * 505 * Since: 2.6 506 */ 507 public void setAlternativeButtonOrder(int[] newOrder) 508 { 509 gtk_dialog_set_alternative_button_order_from_array(gtkDialog, cast(int)newOrder.length, newOrder.ptr); 510 } 511 512 /** 513 * Sets the last widget in the dialog’s action area with the given @response_id 514 * as the default widget for the dialog. Pressing “Enter” normally activates 515 * the default widget. 516 * 517 * Params: 518 * responseId = a response ID 519 */ 520 public void setDefaultResponse(int responseId) 521 { 522 gtk_dialog_set_default_response(gtkDialog, responseId); 523 } 524 525 /** 526 * Calls `gtk_widget_set_sensitive (widget, @setting)` 527 * for each widget in the dialog’s action area with the given @response_id. 528 * A convenient way to sensitize/desensitize dialog buttons. 529 * 530 * Params: 531 * responseId = a response ID 532 * setting = %TRUE for sensitive 533 */ 534 public void setResponseSensitive(int responseId, bool setting) 535 { 536 gtk_dialog_set_response_sensitive(gtkDialog, responseId, setting); 537 } 538 539 protected class OnCloseDelegateWrapper 540 { 541 static OnCloseDelegateWrapper[] listeners; 542 void delegate(Dialog) dlg; 543 gulong handlerId; 544 545 this(void delegate(Dialog) dlg) 546 { 547 this.dlg = dlg; 548 this.listeners ~= this; 549 } 550 551 void remove(OnCloseDelegateWrapper source) 552 { 553 foreach(index, wrapper; listeners) 554 { 555 if (wrapper.handlerId == source.handlerId) 556 { 557 listeners[index] = null; 558 listeners = std.algorithm.remove(listeners, index); 559 break; 560 } 561 } 562 } 563 } 564 565 /** 566 * The ::close signal is a 567 * [keybinding signal][GtkBindingSignal] 568 * which gets emitted when the user uses a keybinding to close 569 * the dialog. 570 * 571 * The default binding for this signal is the Escape key. 572 */ 573 gulong addOnClose(void delegate(Dialog) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 574 { 575 auto wrapper = new OnCloseDelegateWrapper(dlg); 576 wrapper.handlerId = Signals.connectData( 577 this, 578 "close", 579 cast(GCallback)&callBackClose, 580 cast(void*)wrapper, 581 cast(GClosureNotify)&callBackCloseDestroy, 582 connectFlags); 583 return wrapper.handlerId; 584 } 585 586 extern(C) static void callBackClose(GtkDialog* dialogStruct, OnCloseDelegateWrapper wrapper) 587 { 588 wrapper.dlg(wrapper.outer); 589 } 590 591 extern(C) static void callBackCloseDestroy(OnCloseDelegateWrapper wrapper, GClosure* closure) 592 { 593 wrapper.remove(wrapper); 594 } 595 596 protected class OnResponseDelegateWrapper 597 { 598 static OnResponseDelegateWrapper[] listeners; 599 void delegate(int, Dialog) dlg; 600 gulong handlerId; 601 602 this(void delegate(int, Dialog) dlg) 603 { 604 this.dlg = dlg; 605 this.listeners ~= this; 606 } 607 608 void remove(OnResponseDelegateWrapper source) 609 { 610 foreach(index, wrapper; listeners) 611 { 612 if (wrapper.handlerId == source.handlerId) 613 { 614 listeners[index] = null; 615 listeners = std.algorithm.remove(listeners, index); 616 break; 617 } 618 } 619 } 620 } 621 622 /** 623 * Emitted when an action widget is clicked, the dialog receives a 624 * delete event, or the application programmer calls gtk_dialog_response(). 625 * On a delete event, the response ID is #GTK_RESPONSE_DELETE_EVENT. 626 * Otherwise, it depends on which action widget was clicked. 627 * 628 * Params: 629 * responseId = the response ID 630 */ 631 gulong addOnResponse(void delegate(int, Dialog) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 632 { 633 auto wrapper = new OnResponseDelegateWrapper(dlg); 634 wrapper.handlerId = Signals.connectData( 635 this, 636 "response", 637 cast(GCallback)&callBackResponse, 638 cast(void*)wrapper, 639 cast(GClosureNotify)&callBackResponseDestroy, 640 connectFlags); 641 return wrapper.handlerId; 642 } 643 644 extern(C) static void callBackResponse(GtkDialog* dialogStruct, int responseId, OnResponseDelegateWrapper wrapper) 645 { 646 wrapper.dlg(responseId, wrapper.outer); 647 } 648 649 extern(C) static void callBackResponseDestroy(OnResponseDelegateWrapper wrapper, GClosure* closure) 650 { 651 wrapper.remove(wrapper); 652 } 653 654 /** 655 * Returns %TRUE if dialogs are expected to use an alternative 656 * button order on the screen @screen. See 657 * gtk_dialog_set_alternative_button_order() for more details 658 * about alternative button order. 659 * 660 * If you need to use this function, you should probably connect 661 * to the ::notify:gtk-alternative-button-order signal on the 662 * #GtkSettings object associated to @screen, in order to be 663 * notified if the button order setting changes. 664 * 665 * Deprecated: Deprecated 666 * 667 * Params: 668 * screen = a #GdkScreen, or %NULL to use the default screen 669 * 670 * Returns: Whether the alternative button order should be used 671 * 672 * Since: 2.6 673 */ 674 public static bool alternativeDialogButtonOrder(Screen screen) 675 { 676 return gtk_alternative_dialog_button_order((screen is null) ? null : screen.getScreenStruct()) != 0; 677 } 678 }