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 }