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