/src/wrappers/gtk/library/gtk_about_dialog.e

  1indexing
  2	description: "GtkAboutDialog - Display information about an application."
  3	copyright: "[
  4					Copyright (C) 2006 Paolo Redaelli, GTK+ team
  5					
  6					This library is free software; you can redistribute it and/or
  7					modify it under the terms of the GNU Lesser General Public License
  8					as published by the Free Software Foundation; either version 2.1 of
  9					the License, or (at your option) any later version.
 10					
 11					This library is distributed in the hopeOA that it will be useful, but
 12					WITHOUT ANY WARRANTY; without even the implied warranty of
 13					MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 14					Lesser General Public License for more details.
 15
 16					You should have received a copy of the GNU Lesser General Public
 17					License along with this library; if not, write to the Free Software
 18					Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 19					02110-1301 USA
 20					]"
 21
 22class GTK_ABOUT_DIALOG
 23	-- The GtkAboutDialog offers a simple way to display information
 24	-- about a program like its logo, name, copyright, website and
 25	-- license. It is also possible to give credits to the authors,
 26	-- documenters, translators and artists who have worked on the
 27	-- program. An about dialog is typically opened when the user
 28	-- selects the About option from the Help menu. All parts of the
 29	-- dialog are optional.
 30
 31	-- About dialog often contain links and email
 32	-- addresses. GtkAboutDialog supports this by offering global
 33	-- hooks, which are called when the user clicks on a link or email
 34	-- address, see (TODO) gtk_about_dialog_set_email_hook() and
 35	-- gtk_about_dialog_set_url_hook(). Email addresses in the authors,
 36	-- documenters and artists properties are recognized by looking for
 37	-- <user@host>, URLs are recognized by looking for http://url, with
 38	-- url extending to the next space, tab or line break.
 39
 40	-- To make constructing a GtkAboutDialog as convenient as
 41	-- possible, you can use the function gtk_show_about_dialog()
 42	-- which constructs and shows a dialog and keeps it around so
 43	-- that it can be shown again.
 44
 45inherit
 46	GTK_DIALOG
 47		redefine
 48			make, struct_size
 49		end
 50		-- TODO: GtkAboutDialog implements AtkImplementorIface.	
 51
 52insert GTK_ABOUT_DIALOG_EXTERNALS
 53
 54creation make, from_external_pointer
 55
 56feature {} -- Creation
 57	make is
 58			-- a newly created GtkAboutDialog
 59		do
 60			from_external_pointer (gtk_about_dialog_new)
 61		end
 62
 63feature -- Queries
 64	program_name: STRING is
 65			-- the program name displayed in the about dialog.
 66		do
 67			-- The string returned by gtk_about_dialog_get_name is owned
 68			-- by the about dialog and must not be modified.
 69			create {CONST_STRING} Result.from_external (gtk_about_dialog_get_program_name (handle))
 70		end
 71
 72	version: STRING is
 73		do
 74			create {CONST_STRING} Result.from_external
 75			(gtk_about_dialog_get_version (handle))
 76		end
 77
 78	copyright: STRING is
 79			-- the copyright string
 80		do
 81			create {CONST_STRING} Result.from_external
 82			(gtk_about_dialog_get_copyright (handle))
 83		end
 84
 85	comments: STRING is
 86		do
 87			create {CONST_STRING} Result.from_external
 88			(gtk_about_dialog_get_comments (handle))
 89		end
 90
 91	license: STRING is
 92			-- the license information
 93		do
 94			create {CONST_STRING} Result.from_external
 95			(gtk_about_dialog_get_license (handle))
 96		end
 97
 98	is_license_wrapped: BOOLEAN is
 99			-- Is the license text in about automatically wrapped?
100		do
101			Result:=(gtk_about_dialog_get_wrap_license(handle)).to_boolean
102		end
103
104	website: STRING is
105			-- The website URL. 
106		do
107			create {CONST_STRING} Result.from_external
108			(gtk_about_dialog_get_website (handle))
109			-- The string is owned by the about dialog and must not be 
110			-- modified.
111		end
112
113	website_label: STRING is
114			-- The label used for the website link. 
115		do
116			-- The C string is owned by the about dialog and must not be 
117			-- modified. So we use CONST_STRING
118			create {CONST_STRING} Result.from_external
119			(gtk_about_dialog_get_website_label (handle))
120		end
121
122	-- TODO: const gchar* const * gtk_about_dialog_get_authors
123	-- 														  (GtkAboutDialog *about);
124	
125	-- Returns the string which are displayed in the authors tab of the secondary credits dialog.
126	
127	-- about : 	a GtkAboutDialog
128	-- Returns : 	A NULL-terminated string array containing the authors. The array is owned by the about dialog and must not be modified.
129
130feature -- Setters
131	set_program_name (a_name: STRING) is
132			-- Sets the name to display in the about dialog. If this is
133			-- not set, it defaults to result of the C function-g_get_application_name().
134		require
135			name_not_void: a_name/=Void
136		do
137			gtk_about_dialog_set_program_name (handle, a_name.to_external)
138		end
139
140	set_version (a_version: STRING) is
141			-- Sets the version string to display in the about dialog.
142		require version_not_void: a_version /= Void
143		do
144			gtk_about_dialog_set_version (handle, a_version.to_external)
145		end
146
147	set_copyright (a_copyright: STRING) is
148			-- Sets the copyright string to display in the about dialog. This
149			-- should be a short string of one or two lines.
150		require copyright_not_void: a_copyright /= Void
151		do
152			gtk_about_dialog_set_copyright (handle, a_copyright.to_external)
153		end
154
155	set_comments (some_comments: STRING) is
156			-- Sets the comments string to display in the about dialog. This should
157			-- be a short string of one or two lines.
158		require comments_not_void: some_comments /= Void
159		do
160			gtk_about_dialog_set_comments (handle, some_comments.to_external)
161		end
162
163	set_license (a_license: STRING) is
164			-- Sets the license information to be displayed in the secondary
165			-- license dialog. 
166		require license_not_void: a_license /= Void
167		do
168			-- Note: if license is NULL, the license button is hidden.
169			gtk_about_dialog_set_license (handle, a_license.to_external)
170		end
171
172	hide_license is
173			-- Hide the license button.
174		do
175			gtk_about_dialog_set_license (handle, default_pointer)
176		end
177
178	set_wrap_license is
179			-- Automatically wraps the license text in about.
180		do
181			gtk_about_dialog_set_wrap_license (handle, 1)
182		end
183
184	unset_wrap_license is
185			-- Automatically unwraps the license text in about.
186		do
187			gtk_about_dialog_set_wrap_license (handle, 0)
188		end
189
190	set_website (a_website: STRING) is
191			-- Sets the URL to use for the website link. `a_website' is
192			-- an URL starting with "http://"
193		do
194			gtk_about_dialog_set_website (handle, a_website.to_external)
195		end
196
197	set_website_label (a_website_label: STRING) is
198			-- Sets the label to be used for the website link. It defaults to the website URL.
199		do
200			gtk_about_dialog_set_website_label (handle, a_website_label.to_external)
201		end
202
203	-- TODO: gtk_about_dialog_set_authors ()
204	
205	-- void        gtk_about_dialog_set_authors    (GtkAboutDialog *about,
206	-- 															const gchar **authors);
207	
208	-- Sets the strings which are displayed in the authors tab of the secondary credits dialog.
209	
210	-- about : 	a GtkAboutDialog
211	-- authors : 	a NULL-terminated array of strings
212	
213	-- Since 2.6
214	-- gtk_about_dialog_get_artists ()
215	
216	-- const gchar* const * gtk_about_dialog_get_artists
217	-- 														  (GtkAboutDialog *about);
218
219	-- Returns the string which are displayed in the artists tab of the secondary credits dialog.
220
221	-- about : 	a GtkAboutDialog
222	-- Returns : 	A NULL-terminated string array containing the artists. The array is owned by the about dialog and must not be modified.
223
224	-- Since 2.6
225	-- gtk_about_dialog_set_artists ()
226
227	-- void        gtk_about_dialog_set_artists    (GtkAboutDialog *about,
228	-- 															const gchar **artists);
229
230	-- Sets the strings which are displayed in the artists tab of the secondary credits dialog.
231
232	-- about : 	a GtkAboutDialog
233	-- artists : 	a NULL-terminated array of strings
234
235	-- Since 2.6
236	-- gtk_about_dialog_get_documenters ()
237
238	-- const gchar* const * gtk_about_dialog_get_documenters
239	-- 														  (GtkAboutDialog *about);
240
241	-- Returns the string which are displayed in the documenters tab of the secondary credits dialog.
242
243	-- about : 	a GtkAboutDialog
244	-- Returns : 	A NULL-terminated string array containing the documenters. The array is owned by the about dialog and must not be modified.
245
246	-- Since 2.6
247	-- gtk_about_dialog_set_documenters ()
248
249	-- void        gtk_about_dialog_set_documenters
250	-- 														  (GtkAboutDialog *about,
251	-- 															const gchar **documenters);
252
253	-- Sets the strings which are displayed in the documenters tab of the secondary credits dialog.
254
255	-- about : 	a GtkAboutDialog
256	-- documenters : 	a NULL-terminated array of strings
257
258	-- Since 2.6
259
260	translator_credits: STRING is
261			-- The translator credits string.
262		do
263			-- The string is owned by the about dialog and must not be
264			-- modified.
265			create {CONST_STRING} Result.from_external
266			(gtk_about_dialog_get_translator_credits (handle))
267		end
268
269	set_translator_credits (some_translator_credits: STRING) is
270			-- Sets the translator credits string which is displayed in
271			-- the translators tab of the secondary credits dialog.
272		
273			-- The intended use for this string is to display the
274			-- translator of the language which is currently used in the
275			-- user interface. Using gettext(), a simple way to achieve
276			-- that is to mark the string for translation:
277		
278			-- gtk_about_dialog_set_translator_credits(about,_("translator-credits"));
279		
280			-- It is a good idea to use the customary msgid
281			-- "translator-credits" for this purpose, since translators
282			-- will already know the purpose of that msgid, and since
283			-- GtkAboutDialog will detect if "translator-credits" is
284			-- untranslated and hide the tab.
285		do
286			gtk_about_dialog_set_translator_credits
287			(handle, some_translator_credits.to_external)
288		end
289
290	logo: GDK_PIXBUF is
291			-- the pixbuf displayed as logo in the about dialog.
292		local ptr: POINTER
293		do
294			ptr := gtk_about_dialog_get_logo(handle)
295			if ptr.is_not_null then
296				create Result.from_external_pointer(ptr)
297				-- The return value of gtk_about_dialog_get_logo is the
298				-- pixbuf displayed as logo. The pixbuf is owned by the
299				-- about dialog. If you want to keep a reference to it,
300				-- you have to call g_object_ref() on it.
301				Result.ref
302			end
303		end
304
305	set_logo (a_pixbuf: GDK_PIXBUF) is
306			-- Sets the pixbuf to be displayed as logo in the about
307			-- dialog. If it is NULL, the default window icon set with
308			-- gtk_window_set_default_icon() will be used.
309		require pixbuf_not_void: a_pixbuf /= Void
310		do
311			gtk_about_dialog_set_logo (handle, a_pixbuf.handle)
312		end
313
314	unset_logo is
315			-- Use the default window icon set with
316			-- `GTK_WINDOW.set_default_icon' will be used.
317		do
318			gtk_about_dialog_set_logo (handle, default_pointer)
319		end
320
321	logo_icon_name: STRING is
322			-- The icon name displayed as logo in the about dialog.
323		do
324			create {CONST_STRING} Result.from_external
325			(gtk_about_dialog_get_logo_icon_name (handle))
326			-- gtk_about_dialog_get_logo_icon_name returns the icon name
327			-- displayed as logo. The string is owned by the dialog. If
328			-- you want to keep a reference to it, you have to call
329			-- g_strdup() on it.
330		end
331
332	set_logo_icon_name (an_icon_name: STRING) is
333			-- Sets the pixbuf to be displayed as logo in the about
334			-- dialog. 
335		require name_not_void: an_icon_name /= Void
336		do
337			gtk_about_dialog_set_logo_icon_name (handle, an_icon_name.to_external)
338		end
339
340	unset_logo_icon_name (an_icon_name: STRING) is
341			-- Use the default window icon set with
342			-- `GTK_WINDOW.set_default_icon' will be used.
343		do
344			gtk_about_dialog_set_logo_icon_name (handle, default_pointer)
345		end
346
347	-- Since 2.6
348	-- GtkAboutDialogActivateLinkFunc ()
349
350	-- void        (*GtkAboutDialogActivateLinkFunc)
351	-- 														  (GtkAboutDialog *about,
352	-- 															const gchar *link,
353	-- 															gpointer data);
354
355	-- The type of a function which is called when a URL or email link is activated.
356	-- about : 	the GtkAboutDialog in which the link was activated
357	-- link : 	the URL or email address to whiche the activated link points
358	-- data : 	user data that was passed when the function was registered with gtk_about_dialog_set_email_hook() or gtk_about_dialog_set_url_hook()
359	-- gtk_about_dialog_set_email_hook ()
360
361	-- GtkAboutDialogActivateLinkFunc gtk_about_dialog_set_email_hook
362	-- 														  (GtkAboutDialogActivateLinkFunc func,
363	-- 															gpointer data,
364	-- 															GDestroyNotify destroy);
365
366	-- Installs a global function to be called whenever the user activates an email link in an about dialog.
367
368	-- func : 	a function to call when an email link is activated.
369	-- data : 	data to pass to func
370	-- destroy : 	GDestroyNotify for data
371	-- Returns : 	the previous email hook.
372
373	-- gtk_about_dialog_set_url_hook ()
374
375	-- GtkAboutDialogActivateLinkFunc gtk_about_dialog_set_url_hook
376	-- 														  (GtkAboutDialogActivateLinkFunc func,
377	-- 															gpointer data,
378	-- 															GDestroyNotify destroy);
379
380	-- Installs a global function to be called whenever the user activates a URL link in an about dialog.
381
382	-- func : 	a function to call when a URL link is activated.
383	-- data : 	data to pass to func
384	-- destroy : 	GDestroyNotify for data
385	-- Returns : 	the previous URL hook.
386
387	-- Since 2.6
388	-- gtk_show_about_dialog ()
389
390	-- void        gtk_show_about_dialog           (GtkWindow *parent,
391	-- 															const gchar *first_property_name,
392	-- 															...);
393
394	-- This is a convenience function for showing an application's about box. The constructed dialog is associated with the parent window and reused for future invocations of this function.
395
396	-- parent : 	transient parent, or NULL for none
397	-- first_property_name : 	the name of the first property
398	-- ... : 	value of first property, followed by more properties, NULL-terminated
399
400feature -- Property Details
401	-- The "artists" property
402
403	--   "artists"              GStrv                 : Read / Write
404
405	-- The people who contributed artwork to the program, as a NULL-terminated array of strings. Each string may contain email addresses and URLs, which will be displayed as links, see the introduction for more details.
406
407	-- Since 2.6
408	-- The "authors" property
409
410	--   "authors"              GStrv                 : Read / Write
411
412	-- The authors of the program, as a NULL-terminated array of strings. Each string may contain email addresses and URLs, which will be displayed as links, see the introduction for more details.
413
414	-- Since 2.6
415	-- The "comments" property
416
417	--   "comments"             gchararray            : Read / Write
418
419	-- Comments about the program. This string is displayed in a label in the main dialog, thus it should be a short explanation of the main purpose of the program, not a detailed list of features.
420
421	-- Default value: NULL
422
423	-- Since 2.6
424	-- The "copyright" property
425
426	--   "copyright"            gchararray            : Read / Write
427
428	-- Copyright information for the program.
429
430	-- Default value: NULL
431
432	-- Since 2.6
433	-- The "documenters" property
434
435	--   "documenters"          GStrv                 : Read / Write
436
437	-- The people documenting the program, as a NULL-terminated array of strings. Each string may contain email addresses and URLs, which will be displayed as links, see the introduction for more details.
438
439	-- Since 2.6
440	-- The "license" property
441
442	--   "license"              gchararray            : Read / Write
443
444	-- The license of the program. This string is displayed in a text view in a secondary dialog, therefore it is fine to use a long multi-paragraph text. Note that the text is only wrapped in the text view if the "wrap-license" property is set to TRUE; otherwise the text itself must contain the intended linebreaks.
445
446	-- Default value: NULL
447
448	-- Since 2.6
449	-- The "logo" property
450
451	--   "logo"                 GdkPixbuf             : Read / Write
452
453	-- A logo for the about box. If this is not set, it defaults to gtk_window_get_default_icon_list().
454
455	-- Since 2.6
456	-- The "logo-icon-name" property
457
458	--   "logo-icon-name"       gchararray            : Read / Write
459
460	-- A named icon to use as the logo for the about box. This property overrides the logo property.
461
462	-- Default value: NULL
463
464	-- Since 2.6
465	-- The "name" property
466
467	--   "name"                 gchararray            : Read / Write
468
469	-- The name of the program. If this is not set, it defaults to g_get_application_name().
470
471	-- Default value: NULL
472
473	-- Since 2.6
474	-- The "translator-credits" property
475
476	--   "translator-credits"   gchararray            : Read / Write
477
478	-- Credits to the translators. This string should be marked as translatable. The string may contain email addresses and URLs, which will be displayed as links, see the introduction for more details.
479
480	-- Default value: NULL
481
482	-- Since 2.6
483	-- The "version" property
484
485	--   "version"              gchararray            : Read / Write
486
487	-- The version of the program.
488
489	-- Default value: NULL
490
491	-- Since 2.6
492	-- The "website" property
493
494	--   "website"              gchararray            : Read / Write
495
496	-- The URL for the link to the website of the program. This should be a string starting with "http://.
497
498	-- Default value: NULL
499
500	-- Since 2.6
501	-- The "website-label" property
502
503	--   "website-label"        gchararray            : Read / Write
504
505	-- The label for the link to the website of the program. If this is not set, it defaults to the URL specified in the website property.
506
507	-- Default value: NULL
508
509	-- Since 2.6
510	-- The "wrap-license" property
511
512	--   "wrap-license"         gboolean              : Read / Write
513
514	-- Whether to wrap the text in the license dialog.
515
516	-- Default value: FALSE
517
518	-- Since 2.8
519	-- See Als
520
521	-- feature -- 
522	-- Properties
523
524	--   "artists"              GStrv                 : Read / Write
525	--   "authors"              GStrv                 : Read / Write
526	--   "comments"             gchararray            : Read / Write
527	--   "copyright"            gchararray            : Read / Write
528	--   "documenters"          GStrv                 : Read / Write
529	--   "license"              gchararray            : Read / Write
530	--   "logo"                 GdkPixbuf             : Read / Write
531	--   "logo-icon-name"       gchararray            : Read / Write
532	--   "name"                 gchararray            : Read / Write
533	--   "translator-credits"   gchararray            : Read / Write
534	--   "version"              gchararray            : Read / Write
535	--   "website"              gchararray            : Read / Write
536	--   "website-label"        gchararray            : Read / Write
537	--   "wrap-license"         gboolean              : Read / Write
538
539feature
540	struct_size: INTEGER is
541		external "C inline use <gtk/gtk.h>"
542		alias "sizeof(GtkAboutDialog)"
543		end
544
545end -- class GTK_ABOUT_DIALOG