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