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.Assistant; 26 27 private import gdkpixbuf.Pixbuf; 28 private import glib.ConstructionException; 29 private import glib.Str; 30 private import gobject.ObjectG; 31 private import gobject.Signals; 32 private import gtk.Widget; 33 private import gtk.Window; 34 public import gtkc.gdktypes; 35 private import gtkc.gtk; 36 public import gtkc.gtktypes; 37 38 39 /** 40 * A #GtkAssistant is a widget used to represent a generally complex 41 * operation splitted in several steps, guiding the user through its 42 * pages and controlling the page flow to collect the necessary data. 43 * 44 * The design of GtkAssistant is that it controls what buttons to show 45 * and to make sensitive, based on what it knows about the page sequence 46 * and the [type][GtkAssistantPageType] of each page, 47 * in addition to state information like the page 48 * [completion][gtk-assistant-set-page-complete] 49 * and [committed][gtk-assistant-commit] status. 50 * 51 * If you have a case that doesn’t quite fit in #GtkAssistants way of 52 * handling buttons, you can use the #GTK_ASSISTANT_PAGE_CUSTOM page 53 * type and handle buttons yourself. 54 * 55 * # GtkAssistant as GtkBuildable 56 * 57 * The GtkAssistant implementation of the #GtkBuildable interface 58 * exposes the @action_area as internal children with the name 59 * “action_area”. 60 * 61 * To add pages to an assistant in #GtkBuilder, simply add it as a 62 * child to the GtkAssistant object, and set its child properties 63 * as necessary. 64 */ 65 public class Assistant : Window 66 { 67 /** the main Gtk struct */ 68 protected GtkAssistant* gtkAssistant; 69 70 /** Get the main Gtk struct */ 71 public GtkAssistant* getAssistantStruct() 72 { 73 return gtkAssistant; 74 } 75 76 /** the main Gtk struct as a void* */ 77 protected override void* getStruct() 78 { 79 return cast(void*)gtkAssistant; 80 } 81 82 protected override void setStruct(GObject* obj) 83 { 84 gtkAssistant = cast(GtkAssistant*)obj; 85 super.setStruct(obj); 86 } 87 88 /** 89 * Sets our main struct and passes it to the parent class. 90 */ 91 public this (GtkAssistant* gtkAssistant, bool ownedRef = false) 92 { 93 this.gtkAssistant = gtkAssistant; 94 super(cast(GtkWindow*)gtkAssistant, ownedRef); 95 } 96 97 /** 98 */ 99 100 public static GType getType() 101 { 102 return gtk_assistant_get_type(); 103 } 104 105 /** 106 * Creates a new #GtkAssistant. 107 * 108 * Return: a newly created #GtkAssistant 109 * 110 * Since: 2.10 111 * 112 * Throws: ConstructionException GTK+ fails to create the object. 113 */ 114 public this() 115 { 116 auto p = gtk_assistant_new(); 117 118 if(p is null) 119 { 120 throw new ConstructionException("null returned by new"); 121 } 122 123 this(cast(GtkAssistant*) p); 124 } 125 126 /** 127 * Adds a widget to the action area of a #GtkAssistant. 128 * 129 * Params: 130 * child = a #GtkWidget 131 * 132 * Since: 2.10 133 */ 134 public void addActionWidget(Widget child) 135 { 136 gtk_assistant_add_action_widget(gtkAssistant, (child is null) ? null : child.getWidgetStruct()); 137 } 138 139 /** 140 * Appends a page to the @assistant. 141 * 142 * Params: 143 * page = a #GtkWidget 144 * 145 * Return: the index (starting at 0) of the inserted page 146 * 147 * Since: 2.10 148 */ 149 public int appendPage(Widget page) 150 { 151 return gtk_assistant_append_page(gtkAssistant, (page is null) ? null : page.getWidgetStruct()); 152 } 153 154 /** 155 * Erases the visited page history so the back button is not 156 * shown on the current page, and removes the cancel button 157 * from subsequent pages. 158 * 159 * Use this when the information provided up to the current 160 * page is hereafter deemed permanent and cannot be modified 161 * or undone. For example, showing a progress page to track 162 * a long-running, unreversible operation after the user has 163 * clicked apply on a confirmation page. 164 * 165 * Since: 2.22 166 */ 167 public void commit() 168 { 169 gtk_assistant_commit(gtkAssistant); 170 } 171 172 /** 173 * Returns the page number of the current page. 174 * 175 * Return: The index (starting from 0) of the current 176 * page in the @assistant, or -1 if the @assistant has no pages, 177 * or no current page. 178 * 179 * Since: 2.10 180 */ 181 public int getCurrentPage() 182 { 183 return gtk_assistant_get_current_page(gtkAssistant); 184 } 185 186 /** 187 * Returns the number of pages in the @assistant 188 * 189 * Return: the number of pages in the @assistant 190 * 191 * Since: 2.10 192 */ 193 public int getNPages() 194 { 195 return gtk_assistant_get_n_pages(gtkAssistant); 196 } 197 198 /** 199 * Returns the child widget contained in page number @page_num. 200 * 201 * Params: 202 * pageNum = the index of a page in the @assistant, 203 * or -1 to get the last page 204 * 205 * Return: the child widget, or %NULL 206 * if @page_num is out of bounds 207 * 208 * Since: 2.10 209 */ 210 public Widget getNthPage(int pageNum) 211 { 212 auto p = gtk_assistant_get_nth_page(gtkAssistant, pageNum); 213 214 if(p is null) 215 { 216 return null; 217 } 218 219 return ObjectG.getDObject!(Widget)(cast(GtkWidget*) p); 220 } 221 222 /** 223 * Gets whether @page is complete. 224 * 225 * Params: 226 * page = a page of @assistant 227 * 228 * Return: %TRUE if @page is complete. 229 * 230 * Since: 2.10 231 */ 232 public bool getPageComplete(Widget page) 233 { 234 return gtk_assistant_get_page_complete(gtkAssistant, (page is null) ? null : page.getWidgetStruct()) != 0; 235 } 236 237 /** 238 * Gets the header image for @page. 239 * 240 * Deprecated: Since GTK+ 3.2, a header is no longer shown; 241 * add your header decoration to the page content instead. 242 * 243 * Params: 244 * page = a page of @assistant 245 * 246 * Return: the header image for @page, 247 * or %NULL if there’s no header image for the page 248 * 249 * Since: 2.10 250 */ 251 public Pixbuf getPageHeaderImage(Widget page) 252 { 253 auto p = gtk_assistant_get_page_header_image(gtkAssistant, (page is null) ? null : page.getWidgetStruct()); 254 255 if(p is null) 256 { 257 return null; 258 } 259 260 return ObjectG.getDObject!(Pixbuf)(cast(GdkPixbuf*) p); 261 } 262 263 /** 264 * Gets the side image for @page. 265 * 266 * Deprecated: Since GTK+ 3.2, sidebar images are not 267 * shown anymore. 268 * 269 * Params: 270 * page = a page of @assistant 271 * 272 * Return: the side image for @page, 273 * or %NULL if there’s no side image for the page 274 * 275 * Since: 2.10 276 */ 277 public Pixbuf getPageSideImage(Widget page) 278 { 279 auto p = gtk_assistant_get_page_side_image(gtkAssistant, (page is null) ? null : page.getWidgetStruct()); 280 281 if(p is null) 282 { 283 return null; 284 } 285 286 return ObjectG.getDObject!(Pixbuf)(cast(GdkPixbuf*) p); 287 } 288 289 /** 290 * Gets the title for @page. 291 * 292 * Params: 293 * page = a page of @assistant 294 * 295 * Return: the title for @page 296 * 297 * Since: 2.10 298 */ 299 public string getPageTitle(Widget page) 300 { 301 return Str.toString(gtk_assistant_get_page_title(gtkAssistant, (page is null) ? null : page.getWidgetStruct())); 302 } 303 304 /** 305 * Gets the page type of @page. 306 * 307 * Params: 308 * page = a page of @assistant 309 * 310 * Return: the page type of @page 311 * 312 * Since: 2.10 313 */ 314 public GtkAssistantPageType getPageType(Widget page) 315 { 316 return gtk_assistant_get_page_type(gtkAssistant, (page is null) ? null : page.getWidgetStruct()); 317 } 318 319 /** 320 * Inserts a page in the @assistant at a given position. 321 * 322 * Params: 323 * page = a #GtkWidget 324 * position = the index (starting at 0) at which to insert the page, 325 * or -1 to append the page to the @assistant 326 * 327 * Return: the index (starting from 0) of the inserted page 328 * 329 * Since: 2.10 330 */ 331 public int insertPage(Widget page, int position) 332 { 333 return gtk_assistant_insert_page(gtkAssistant, (page is null) ? null : page.getWidgetStruct(), position); 334 } 335 336 /** 337 * Navigate to the next page. 338 * 339 * It is a programming error to call this function when 340 * there is no next page. 341 * 342 * This function is for use when creating pages of the 343 * #GTK_ASSISTANT_PAGE_CUSTOM type. 344 * 345 * Since: 3.0 346 */ 347 public void nextPage() 348 { 349 gtk_assistant_next_page(gtkAssistant); 350 } 351 352 /** 353 * Prepends a page to the @assistant. 354 * 355 * Params: 356 * page = a #GtkWidget 357 * 358 * Return: the index (starting at 0) of the inserted page 359 * 360 * Since: 2.10 361 */ 362 public int prependPage(Widget page) 363 { 364 return gtk_assistant_prepend_page(gtkAssistant, (page is null) ? null : page.getWidgetStruct()); 365 } 366 367 /** 368 * Navigate to the previous visited page. 369 * 370 * It is a programming error to call this function when 371 * no previous page is available. 372 * 373 * This function is for use when creating pages of the 374 * #GTK_ASSISTANT_PAGE_CUSTOM type. 375 * 376 * Since: 3.0 377 */ 378 public void previousPage() 379 { 380 gtk_assistant_previous_page(gtkAssistant); 381 } 382 383 /** 384 * Removes a widget from the action area of a #GtkAssistant. 385 * 386 * Params: 387 * child = a #GtkWidget 388 * 389 * Since: 2.10 390 */ 391 public void removeActionWidget(Widget child) 392 { 393 gtk_assistant_remove_action_widget(gtkAssistant, (child is null) ? null : child.getWidgetStruct()); 394 } 395 396 /** 397 * Removes the @page_num’s page from @assistant. 398 * 399 * Params: 400 * pageNum = the index of a page in the @assistant, 401 * or -1 to remove the last page 402 * 403 * Since: 3.2 404 */ 405 public void removePage(int pageNum) 406 { 407 gtk_assistant_remove_page(gtkAssistant, pageNum); 408 } 409 410 /** 411 * Switches the page to @page_num. 412 * 413 * Note that this will only be necessary in custom buttons, 414 * as the @assistant flow can be set with 415 * gtk_assistant_set_forward_page_func(). 416 * 417 * Params: 418 * pageNum = index of the page to switch to, starting from 0. 419 * If negative, the last page will be used. If greater 420 * than the number of pages in the @assistant, nothing 421 * will be done. 422 * 423 * Since: 2.10 424 */ 425 public void setCurrentPage(int pageNum) 426 { 427 gtk_assistant_set_current_page(gtkAssistant, pageNum); 428 } 429 430 /** 431 * Sets the page forwarding function to be @page_func. 432 * 433 * This function will be used to determine what will be 434 * the next page when the user presses the forward button. 435 * Setting @page_func to %NULL will make the assistant to 436 * use the default forward function, which just goes to the 437 * next visible page. 438 * 439 * Params: 440 * pageFunc = the #GtkAssistantPageFunc, or %NULL 441 * to use the default one 442 * data = user data for @page_func 443 * destroy = destroy notifier for @data 444 * 445 * Since: 2.10 446 */ 447 public void setForwardPageFunc(GtkAssistantPageFunc pageFunc, void* data, GDestroyNotify destroy) 448 { 449 gtk_assistant_set_forward_page_func(gtkAssistant, pageFunc, data, destroy); 450 } 451 452 /** 453 * Sets whether @page contents are complete. 454 * 455 * This will make @assistant update the buttons state 456 * to be able to continue the task. 457 * 458 * Params: 459 * page = a page of @assistant 460 * complete = the completeness status of the page 461 * 462 * Since: 2.10 463 */ 464 public void setPageComplete(Widget page, bool complete) 465 { 466 gtk_assistant_set_page_complete(gtkAssistant, (page is null) ? null : page.getWidgetStruct(), complete); 467 } 468 469 /** 470 * Sets a header image for @page. 471 * 472 * Deprecated: Since GTK+ 3.2, a header is no longer shown; 473 * add your header decoration to the page content instead. 474 * 475 * Params: 476 * page = a page of @assistant 477 * pixbuf = the new header image @page 478 * 479 * Since: 2.10 480 */ 481 public void setPageHeaderImage(Widget page, Pixbuf pixbuf) 482 { 483 gtk_assistant_set_page_header_image(gtkAssistant, (page is null) ? null : page.getWidgetStruct(), (pixbuf is null) ? null : pixbuf.getPixbufStruct()); 484 } 485 486 /** 487 * Sets a side image for @page. 488 * 489 * This image used to be displayed in the side area of the assistant 490 * when @page is the current page. 491 * 492 * Deprecated: Since GTK+ 3.2, sidebar images are not 493 * shown anymore. 494 * 495 * Params: 496 * page = a page of @assistant 497 * pixbuf = the new side image @page 498 * 499 * Since: 2.10 500 */ 501 public void setPageSideImage(Widget page, Pixbuf pixbuf) 502 { 503 gtk_assistant_set_page_side_image(gtkAssistant, (page is null) ? null : page.getWidgetStruct(), (pixbuf is null) ? null : pixbuf.getPixbufStruct()); 504 } 505 506 /** 507 * Sets a title for @page. 508 * 509 * The title is displayed in the header area of the assistant 510 * when @page is the current page. 511 * 512 * Params: 513 * page = a page of @assistant 514 * title = the new title for @page 515 * 516 * Since: 2.10 517 */ 518 public void setPageTitle(Widget page, string title) 519 { 520 gtk_assistant_set_page_title(gtkAssistant, (page is null) ? null : page.getWidgetStruct(), Str.toStringz(title)); 521 } 522 523 /** 524 * Sets the page type for @page. 525 * 526 * The page type determines the page behavior in the @assistant. 527 * 528 * Params: 529 * page = a page of @assistant 530 * type = the new type for @page 531 * 532 * Since: 2.10 533 */ 534 public void setPageType(Widget page, GtkAssistantPageType type) 535 { 536 gtk_assistant_set_page_type(gtkAssistant, (page is null) ? null : page.getWidgetStruct(), type); 537 } 538 539 /** 540 * Forces @assistant to recompute the buttons state. 541 * 542 * GTK+ automatically takes care of this in most situations, 543 * e.g. when the user goes to a different page, or when the 544 * visibility or completeness of a page changes. 545 * 546 * One situation where it can be necessary to call this 547 * function is when changing a value on the current page 548 * affects the future page flow of the assistant. 549 * 550 * Since: 2.10 551 */ 552 public void updateButtonsState() 553 { 554 gtk_assistant_update_buttons_state(gtkAssistant); 555 } 556 557 int[string] connectedSignals; 558 559 void delegate(Assistant)[] onApplyListeners; 560 /** 561 * The ::apply signal is emitted when the apply button is clicked. 562 * 563 * The default behavior of the #GtkAssistant is to switch to the page 564 * after the current page, unless the current page is the last one. 565 * 566 * A handler for the ::apply signal should carry out the actions for 567 * which the wizard has collected data. If the action takes a long time 568 * to complete, you might consider putting a page of type 569 * %GTK_ASSISTANT_PAGE_PROGRESS after the confirmation page and handle 570 * this operation within the #GtkAssistant::prepare signal of the progress 571 * page. 572 * 573 * Since: 2.10 574 */ 575 void addOnApply(void delegate(Assistant) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 576 { 577 if ( "apply" !in connectedSignals ) 578 { 579 Signals.connectData( 580 this, 581 "apply", 582 cast(GCallback)&callBackApply, 583 cast(void*)this, 584 null, 585 connectFlags); 586 connectedSignals["apply"] = 1; 587 } 588 onApplyListeners ~= dlg; 589 } 590 extern(C) static void callBackApply(GtkAssistant* assistantStruct, Assistant _assistant) 591 { 592 foreach ( void delegate(Assistant) dlg; _assistant.onApplyListeners ) 593 { 594 dlg(_assistant); 595 } 596 } 597 598 void delegate(Assistant)[] onCancelListeners; 599 /** 600 * The ::cancel signal is emitted when then the cancel button is clicked. 601 * 602 * Since: 2.10 603 */ 604 void addOnCancel(void delegate(Assistant) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 605 { 606 if ( "cancel" !in connectedSignals ) 607 { 608 Signals.connectData( 609 this, 610 "cancel", 611 cast(GCallback)&callBackCancel, 612 cast(void*)this, 613 null, 614 connectFlags); 615 connectedSignals["cancel"] = 1; 616 } 617 onCancelListeners ~= dlg; 618 } 619 extern(C) static void callBackCancel(GtkAssistant* assistantStruct, Assistant _assistant) 620 { 621 foreach ( void delegate(Assistant) dlg; _assistant.onCancelListeners ) 622 { 623 dlg(_assistant); 624 } 625 } 626 627 void delegate(Assistant)[] onCloseListeners; 628 /** 629 * The ::close signal is emitted either when the close button of 630 * a summary page is clicked, or when the apply button in the last 631 * page in the flow (of type %GTK_ASSISTANT_PAGE_CONFIRM) is clicked. 632 * 633 * Since: 2.10 634 */ 635 void addOnClose(void delegate(Assistant) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 636 { 637 if ( "close" !in connectedSignals ) 638 { 639 Signals.connectData( 640 this, 641 "close", 642 cast(GCallback)&callBackClose, 643 cast(void*)this, 644 null, 645 connectFlags); 646 connectedSignals["close"] = 1; 647 } 648 onCloseListeners ~= dlg; 649 } 650 extern(C) static void callBackClose(GtkAssistant* assistantStruct, Assistant _assistant) 651 { 652 foreach ( void delegate(Assistant) dlg; _assistant.onCloseListeners ) 653 { 654 dlg(_assistant); 655 } 656 } 657 658 void delegate(Assistant)[] onEscapeListeners; 659 void addOnEscape(void delegate(Assistant) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 660 { 661 if ( "escape" !in connectedSignals ) 662 { 663 Signals.connectData( 664 this, 665 "escape", 666 cast(GCallback)&callBackEscape, 667 cast(void*)this, 668 null, 669 connectFlags); 670 connectedSignals["escape"] = 1; 671 } 672 onEscapeListeners ~= dlg; 673 } 674 extern(C) static void callBackEscape(GtkAssistant* assistantStruct, Assistant _assistant) 675 { 676 foreach ( void delegate(Assistant) dlg; _assistant.onEscapeListeners ) 677 { 678 dlg(_assistant); 679 } 680 } 681 682 void delegate(Widget, Assistant)[] onPrepareListeners; 683 /** 684 * The ::prepare signal is emitted when a new page is set as the 685 * assistant's current page, before making the new page visible. 686 * 687 * A handler for this signal can do any preparations which are 688 * necessary before showing @page. 689 * 690 * Params: 691 * page = the current page 692 * 693 * Since: 2.10 694 */ 695 void addOnPrepare(void delegate(Widget, Assistant) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 696 { 697 if ( "prepare" !in connectedSignals ) 698 { 699 Signals.connectData( 700 this, 701 "prepare", 702 cast(GCallback)&callBackPrepare, 703 cast(void*)this, 704 null, 705 connectFlags); 706 connectedSignals["prepare"] = 1; 707 } 708 onPrepareListeners ~= dlg; 709 } 710 extern(C) static void callBackPrepare(GtkAssistant* assistantStruct, GtkWidget* page, Assistant _assistant) 711 { 712 foreach ( void delegate(Widget, Assistant) dlg; _assistant.onPrepareListeners ) 713 { 714 dlg(ObjectG.getDObject!(Widget)(page), _assistant); 715 } 716 } 717 }