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