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