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.AboutDialog; 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.Dialog; 33 private import gtk.Widget; 34 private import gtk.Window; 35 private import gtk.c.functions; 36 public import gtk.c.types; 37 public import gtkc.gtktypes; 38 private import std.algorithm; 39 40 41 /** 42 * The GtkAboutDialog offers a simple way to display information about 43 * a program like its logo, name, copyright, website and license. It is 44 * also possible to give credits to the authors, documenters, translators 45 * and artists who have worked on the program. An about dialog is typically 46 * opened when the user selects the `About` option from the `Help` menu. 47 * All parts of the dialog are optional. 48 * 49 * About dialogs often contain links and email addresses. GtkAboutDialog 50 * displays these as clickable links. By default, it calls gtk_show_uri_on_window() 51 * when a user clicks one. The behaviour can be overridden with the 52 * #GtkAboutDialog::activate-link signal. 53 * 54 * To specify a person with an email address, use a string like 55 * "Edgar Allan Poe <edgar\@poe.com>". To specify a website with a title, 56 * use a string like "GTK+ team http://www.gtk.org". 57 * 58 * To make constructing a GtkAboutDialog as convenient as possible, you can 59 * use the function gtk_show_about_dialog() which constructs and shows a dialog 60 * and keeps it around so that it can be shown again. 61 * 62 * Note that GTK+ sets a default title of `_("About %s")` on the dialog 63 * window (where \%s is replaced by the name of the application, but in 64 * order to ensure proper translation of the title, applications should 65 * set the title property explicitly when constructing a GtkAboutDialog, 66 * as shown in the following example: 67 * |[<!-- language="C" --> 68 * GdkPixbuf *example_logo = gdk_pixbuf_new_from_file ("./logo.png", NULL); 69 * gtk_show_about_dialog (NULL, 70 * "program-name", "ExampleCode", 71 * "logo", example_logo, 72 * "title", _("About ExampleCode"), 73 * NULL); 74 * ]| 75 * 76 * It is also possible to show a #GtkAboutDialog like any other #GtkDialog, 77 * e.g. using gtk_dialog_run(). In this case, you might need to know that 78 * the “Close” button returns the #GTK_RESPONSE_CANCEL response id. 79 */ 80 public class AboutDialog : Dialog 81 { 82 /** the main Gtk struct */ 83 protected GtkAboutDialog* gtkAboutDialog; 84 85 /** Get the main Gtk struct */ 86 public GtkAboutDialog* getAboutDialogStruct(bool transferOwnership = false) 87 { 88 if (transferOwnership) 89 ownedRef = false; 90 return gtkAboutDialog; 91 } 92 93 /** the main Gtk struct as a void* */ 94 protected override void* getStruct() 95 { 96 return cast(void*)gtkAboutDialog; 97 } 98 99 protected override void setStruct(GObject* obj) 100 { 101 gtkAboutDialog = cast(GtkAboutDialog*)obj; 102 super.setStruct(obj); 103 } 104 105 /** 106 * Sets our main struct and passes it to the parent class. 107 */ 108 public this (GtkAboutDialog* gtkAboutDialog, bool ownedRef = false) 109 { 110 this.gtkAboutDialog = gtkAboutDialog; 111 super(cast(GtkDialog*)gtkAboutDialog, ownedRef); 112 } 113 114 115 /** */ 116 public static GType getType() 117 { 118 return gtk_about_dialog_get_type(); 119 } 120 121 /** 122 * Creates a new #GtkAboutDialog. 123 * 124 * Returns: a newly created #GtkAboutDialog 125 * 126 * Since: 2.6 127 * 128 * Throws: ConstructionException GTK+ fails to create the object. 129 */ 130 public this() 131 { 132 auto p = gtk_about_dialog_new(); 133 134 if(p is null) 135 { 136 throw new ConstructionException("null returned by new"); 137 } 138 139 this(cast(GtkAboutDialog*) p); 140 } 141 142 /** 143 * Creates a new section in the Credits page. 144 * 145 * Params: 146 * sectionName = The name of the section 147 * people = The people who belong to that section 148 * 149 * Since: 3.4 150 */ 151 public void addCreditSection(string sectionName, string[] people) 152 { 153 gtk_about_dialog_add_credit_section(gtkAboutDialog, Str.toStringz(sectionName), Str.toStringzArray(people)); 154 } 155 156 /** 157 * Returns the string which are displayed in the artists tab 158 * of the secondary credits dialog. 159 * 160 * Returns: A 161 * %NULL-terminated string array containing the artists. The array is 162 * owned by the about dialog and must not be modified. 163 * 164 * Since: 2.6 165 */ 166 public string[] getArtists() 167 { 168 return Str.toStringArray(gtk_about_dialog_get_artists(gtkAboutDialog)); 169 } 170 171 /** 172 * Returns the string which are displayed in the authors tab 173 * of the secondary credits dialog. 174 * 175 * Returns: A 176 * %NULL-terminated string array containing the authors. The array is 177 * owned by the about dialog and must not be modified. 178 * 179 * Since: 2.6 180 */ 181 public string[] getAuthors() 182 { 183 return Str.toStringArray(gtk_about_dialog_get_authors(gtkAboutDialog)); 184 } 185 186 /** 187 * Returns the comments string. 188 * 189 * Returns: The comments. The string is owned by the about 190 * dialog and must not be modified. 191 * 192 * Since: 2.6 193 */ 194 public string getComments() 195 { 196 return Str.toString(gtk_about_dialog_get_comments(gtkAboutDialog)); 197 } 198 199 /** 200 * Returns the copyright string. 201 * 202 * Returns: The copyright string. The string is owned by the about 203 * dialog and must not be modified. 204 * 205 * Since: 2.6 206 */ 207 public string getCopyright() 208 { 209 return Str.toString(gtk_about_dialog_get_copyright(gtkAboutDialog)); 210 } 211 212 /** 213 * Returns the string which are displayed in the documenters 214 * tab of the secondary credits dialog. 215 * 216 * Returns: A 217 * %NULL-terminated string array containing the documenters. The 218 * array is owned by the about dialog and must not be modified. 219 * 220 * Since: 2.6 221 */ 222 public string[] getDocumenters() 223 { 224 return Str.toStringArray(gtk_about_dialog_get_documenters(gtkAboutDialog)); 225 } 226 227 /** 228 * Returns the license information. 229 * 230 * Returns: The license information. The string is owned by the about 231 * dialog and must not be modified. 232 * 233 * Since: 2.6 234 */ 235 public string getLicense() 236 { 237 return Str.toString(gtk_about_dialog_get_license(gtkAboutDialog)); 238 } 239 240 /** 241 * Retrieves the license set using gtk_about_dialog_set_license_type() 242 * 243 * Returns: a #GtkLicense value 244 * 245 * Since: 3.0 246 */ 247 public GtkLicense getLicenseType() 248 { 249 return gtk_about_dialog_get_license_type(gtkAboutDialog); 250 } 251 252 /** 253 * Returns the pixbuf displayed as logo in the about dialog. 254 * 255 * Returns: the pixbuf displayed as logo. The 256 * pixbuf is owned by the about dialog. If you want to keep a 257 * reference to it, you have to call g_object_ref() on it. 258 * 259 * Since: 2.6 260 */ 261 public Pixbuf getLogo() 262 { 263 auto p = gtk_about_dialog_get_logo(gtkAboutDialog); 264 265 if(p is null) 266 { 267 return null; 268 } 269 270 return ObjectG.getDObject!(Pixbuf)(cast(GdkPixbuf*) p); 271 } 272 273 /** 274 * Returns the icon name displayed as logo in the about dialog. 275 * 276 * Returns: the icon name displayed as logo. The string is 277 * owned by the dialog. If you want to keep a reference 278 * to it, you have to call g_strdup() on it. 279 * 280 * Since: 2.6 281 */ 282 public string getLogoIconName() 283 { 284 return Str.toString(gtk_about_dialog_get_logo_icon_name(gtkAboutDialog)); 285 } 286 287 /** 288 * Returns the program name displayed in the about dialog. 289 * 290 * Returns: The program name. The string is owned by the about 291 * dialog and must not be modified. 292 * 293 * Since: 2.12 294 */ 295 public string getProgramName() 296 { 297 return Str.toString(gtk_about_dialog_get_program_name(gtkAboutDialog)); 298 } 299 300 /** 301 * Returns the translator credits string which is displayed 302 * in the translators tab of the secondary credits dialog. 303 * 304 * Returns: The translator credits string. The string is 305 * owned by the about dialog and must not be modified. 306 * 307 * Since: 2.6 308 */ 309 public string getTranslatorCredits() 310 { 311 return Str.toString(gtk_about_dialog_get_translator_credits(gtkAboutDialog)); 312 } 313 314 /** 315 * Returns the version string. 316 * 317 * Returns: The version string. The string is owned by the about 318 * dialog and must not be modified. 319 * 320 * Since: 2.6 321 */ 322 public string getVersion() 323 { 324 return Str.toString(gtk_about_dialog_get_version(gtkAboutDialog)); 325 } 326 327 /** 328 * Returns the website URL. 329 * 330 * Returns: The website URL. The string is owned by the about 331 * dialog and must not be modified. 332 * 333 * Since: 2.6 334 */ 335 public string getWebsite() 336 { 337 return Str.toString(gtk_about_dialog_get_website(gtkAboutDialog)); 338 } 339 340 /** 341 * Returns the label used for the website link. 342 * 343 * Returns: The label used for the website link. The string is 344 * owned by the about dialog and must not be modified. 345 * 346 * Since: 2.6 347 */ 348 public string getWebsiteLabel() 349 { 350 return Str.toString(gtk_about_dialog_get_website_label(gtkAboutDialog)); 351 } 352 353 /** 354 * Returns whether the license text in @about is 355 * automatically wrapped. 356 * 357 * Returns: %TRUE if the license text is wrapped 358 * 359 * Since: 2.8 360 */ 361 public bool getWrapLicense() 362 { 363 return gtk_about_dialog_get_wrap_license(gtkAboutDialog) != 0; 364 } 365 366 /** 367 * Sets the strings which are displayed in the artists tab 368 * of the secondary credits dialog. 369 * 370 * Params: 371 * artists = a %NULL-terminated array of strings 372 * 373 * Since: 2.6 374 */ 375 public void setArtists(string[] artists) 376 { 377 gtk_about_dialog_set_artists(gtkAboutDialog, Str.toStringzArray(artists)); 378 } 379 380 /** 381 * Sets the strings which are displayed in the authors tab 382 * of the secondary credits dialog. 383 * 384 * Params: 385 * authors = a %NULL-terminated array of strings 386 * 387 * Since: 2.6 388 */ 389 public void setAuthors(string[] authors) 390 { 391 gtk_about_dialog_set_authors(gtkAboutDialog, Str.toStringzArray(authors)); 392 } 393 394 /** 395 * Sets the comments string to display in the about dialog. 396 * This should be a short string of one or two lines. 397 * 398 * Params: 399 * comments = a comments string 400 * 401 * Since: 2.6 402 */ 403 public void setComments(string comments) 404 { 405 gtk_about_dialog_set_comments(gtkAboutDialog, Str.toStringz(comments)); 406 } 407 408 /** 409 * Sets the copyright string to display in the about dialog. 410 * This should be a short string of one or two lines. 411 * 412 * Params: 413 * copyright = the copyright string 414 * 415 * Since: 2.6 416 */ 417 public void setCopyright(string copyright) 418 { 419 gtk_about_dialog_set_copyright(gtkAboutDialog, Str.toStringz(copyright)); 420 } 421 422 /** 423 * Sets the strings which are displayed in the documenters tab 424 * of the secondary credits dialog. 425 * 426 * Params: 427 * documenters = a %NULL-terminated array of strings 428 * 429 * Since: 2.6 430 */ 431 public void setDocumenters(string[] documenters) 432 { 433 gtk_about_dialog_set_documenters(gtkAboutDialog, Str.toStringzArray(documenters)); 434 } 435 436 /** 437 * Sets the license information to be displayed in the secondary 438 * license dialog. If @license is %NULL, the license button is 439 * hidden. 440 * 441 * Params: 442 * license = the license information or %NULL 443 * 444 * Since: 2.6 445 */ 446 public void setLicense(string license) 447 { 448 gtk_about_dialog_set_license(gtkAboutDialog, Str.toStringz(license)); 449 } 450 451 /** 452 * Sets the license of the application showing the @about dialog from a 453 * list of known licenses. 454 * 455 * This function overrides the license set using 456 * gtk_about_dialog_set_license(). 457 * 458 * Params: 459 * licenseType = the type of license 460 * 461 * Since: 3.0 462 */ 463 public void setLicenseType(GtkLicense licenseType) 464 { 465 gtk_about_dialog_set_license_type(gtkAboutDialog, licenseType); 466 } 467 468 /** 469 * Sets the pixbuf to be displayed as logo in the about dialog. 470 * If it is %NULL, the default window icon set with 471 * gtk_window_set_default_icon() will be used. 472 * 473 * Params: 474 * logo = a #GdkPixbuf, or %NULL 475 * 476 * Since: 2.6 477 */ 478 public void setLogo(Pixbuf logo) 479 { 480 gtk_about_dialog_set_logo(gtkAboutDialog, (logo is null) ? null : logo.getPixbufStruct()); 481 } 482 483 /** 484 * Sets the pixbuf to be displayed as logo in the about dialog. 485 * If it is %NULL, the default window icon set with 486 * gtk_window_set_default_icon() will be used. 487 * 488 * Params: 489 * iconName = an icon name, or %NULL 490 * 491 * Since: 2.6 492 */ 493 public void setLogoIconName(string iconName) 494 { 495 gtk_about_dialog_set_logo_icon_name(gtkAboutDialog, Str.toStringz(iconName)); 496 } 497 498 /** 499 * Sets the name to display in the about dialog. 500 * If this is not set, it defaults to g_get_application_name(). 501 * 502 * Params: 503 * name = the program name 504 * 505 * Since: 2.12 506 */ 507 public void setProgramName(string name) 508 { 509 gtk_about_dialog_set_program_name(gtkAboutDialog, Str.toStringz(name)); 510 } 511 512 /** 513 * Sets the translator credits string which is displayed in 514 * the translators tab of the secondary credits dialog. 515 * 516 * The intended use for this string is to display the translator 517 * of the language which is currently used in the user interface. 518 * Using gettext(), a simple way to achieve that is to mark the 519 * string for translation: 520 * |[<!-- language="C" --> 521 * GtkWidget *about = gtk_about_dialog_new (); 522 * gtk_about_dialog_set_translator_credits (GTK_ABOUT_DIALOG (about), 523 * _("translator-credits")); 524 * ]| 525 * It is a good idea to use the customary msgid “translator-credits” for this 526 * purpose, since translators will already know the purpose of that msgid, and 527 * since #GtkAboutDialog will detect if “translator-credits” is untranslated 528 * and hide the tab. 529 * 530 * Params: 531 * translatorCredits = the translator credits 532 * 533 * Since: 2.6 534 */ 535 public void setTranslatorCredits(string translatorCredits) 536 { 537 gtk_about_dialog_set_translator_credits(gtkAboutDialog, Str.toStringz(translatorCredits)); 538 } 539 540 /** 541 * Sets the version string to display in the about dialog. 542 * 543 * Params: 544 * versio = the version string 545 * 546 * Since: 2.6 547 */ 548 public void setVersion(string versio) 549 { 550 gtk_about_dialog_set_version(gtkAboutDialog, Str.toStringz(versio)); 551 } 552 553 /** 554 * Sets the URL to use for the website link. 555 * 556 * Params: 557 * website = a URL string starting with "http://" 558 * 559 * Since: 2.6 560 */ 561 public void setWebsite(string website) 562 { 563 gtk_about_dialog_set_website(gtkAboutDialog, Str.toStringz(website)); 564 } 565 566 /** 567 * Sets the label to be used for the website link. 568 * 569 * Params: 570 * websiteLabel = the label used for the website link 571 * 572 * Since: 2.6 573 */ 574 public void setWebsiteLabel(string websiteLabel) 575 { 576 gtk_about_dialog_set_website_label(gtkAboutDialog, Str.toStringz(websiteLabel)); 577 } 578 579 /** 580 * Sets whether the license text in @about is 581 * automatically wrapped. 582 * 583 * Params: 584 * wrapLicense = whether to wrap the license 585 * 586 * Since: 2.8 587 */ 588 public void setWrapLicense(bool wrapLicense) 589 { 590 gtk_about_dialog_set_wrap_license(gtkAboutDialog, wrapLicense); 591 } 592 593 protected class OnActivateLinkDelegateWrapper 594 { 595 bool delegate(string, AboutDialog) dlg; 596 gulong handlerId; 597 598 this(bool delegate(string, AboutDialog) dlg) 599 { 600 this.dlg = dlg; 601 onActivateLinkListeners ~= this; 602 } 603 604 void remove(OnActivateLinkDelegateWrapper source) 605 { 606 foreach(index, wrapper; onActivateLinkListeners) 607 { 608 if (wrapper.handlerId == source.handlerId) 609 { 610 onActivateLinkListeners[index] = null; 611 onActivateLinkListeners = std.algorithm.remove(onActivateLinkListeners, index); 612 break; 613 } 614 } 615 } 616 } 617 OnActivateLinkDelegateWrapper[] onActivateLinkListeners; 618 619 /** 620 * The signal which gets emitted to activate a URI. 621 * Applications may connect to it to override the default behaviour, 622 * which is to call gtk_show_uri_on_window(). 623 * 624 * Params: 625 * uri = the URI that is activated 626 * 627 * Returns: %TRUE if the link has been activated 628 * 629 * Since: 2.24 630 */ 631 gulong addOnActivateLink(bool delegate(string, AboutDialog) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 632 { 633 auto wrapper = new OnActivateLinkDelegateWrapper(dlg); 634 wrapper.handlerId = Signals.connectData( 635 this, 636 "activate-link", 637 cast(GCallback)&callBackActivateLink, 638 cast(void*)wrapper, 639 cast(GClosureNotify)&callBackActivateLinkDestroy, 640 connectFlags); 641 return wrapper.handlerId; 642 } 643 644 extern(C) static int callBackActivateLink(GtkAboutDialog* aboutdialogStruct, char* uri, OnActivateLinkDelegateWrapper wrapper) 645 { 646 return wrapper.dlg(Str.toString(uri), wrapper.outer); 647 } 648 649 extern(C) static void callBackActivateLinkDestroy(OnActivateLinkDelegateWrapper wrapper, GClosure* closure) 650 { 651 wrapper.remove(wrapper); 652 } 653 }