]> git.saurik.com Git - wxWidgets.git/blame - interface/aboutdlg.h
add default parameters for width and style parameters of FindOrCreatePen() for consis...
[wxWidgets.git] / interface / aboutdlg.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: aboutdlg.h
463b4bfa 3// Purpose: interface of wxAboutDialogInfo
23324ae1
FM
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
9/**
10 @class wxAboutDialogInfo
11 @wxheader{aboutdlg.h}
7c913512 12
23324ae1 13 wxAboutDialogInfo contains information shown in the standard @e About
3a65144e 14 dialog displayed by the wxAboutBox() function.
7c913512 15
23324ae1
FM
16 This class contains the general information about the program, such as its
17 name, version, copyright and so on, as well as lists of the program developers,
18 documentation writers, artists and translators. The simple properties from the
19 former group are represented as a string with the exception of the program icon
7c913512 20 and the program web site, while the lists from the latter group are stored as
463b4bfa
FM
21 wxArrayString and can be either set entirely at once using
22 wxAboutDialogInfo::SetDevelopers and similar functions or built one by one using
23 wxAboutDialogInfo::AddDeveloper etc.
7c913512 24
23324ae1
FM
25 Please also notice that while all the main platforms have the native
26 implementation of the about dialog, they are often more limited than the
27 generic version provided by wxWidgets and so the generic version is used if
28 wxAboutDialogInfo has any fields not supported by the native version. Currently
29 GTK+ version supports all the possible fields natively but MSW and Mac versions
30 don't support URLs, licence text nor custom icons in the about dialog and if
3a65144e
FM
31 either of those is used, wxAboutBox() will automatically use the generic version
32 so you should avoid specifying these fields to achieve more native look and feel.
7c913512 33
23324ae1 34 @library{wxadv}
3a65144e 35 @category{misc}
7c913512 36
3a65144e 37 @see wxAboutDialogInfo::SetArtists
23324ae1 38*/
7c913512 39class wxAboutDialogInfo
23324ae1
FM
40{
41public:
42 /**
43 Default constructor leaves all fields are initially uninitialized, in general
463b4bfa 44 you should call at least SetVersion(), SetCopyright() and SetDescription().
23324ae1
FM
45 */
46 wxAboutDialogInfo();
47
48 /**
49 Adds an artist name to be shown in the program credits.
3c4f71cc 50
4cc4bfaf 51 @see SetArtists()
23324ae1
FM
52 */
53 void AddArtist(const wxString& artist);
54
55 /**
56 Adds a developer name to be shown in the program credits.
3c4f71cc 57
4cc4bfaf 58 @see SetDevelopers()
23324ae1
FM
59 */
60 void AddDeveloper(const wxString& developer);
61
62 /**
63 Adds a documentation writer name to be shown in the program credits.
3c4f71cc 64
4cc4bfaf 65 @see SetDocWriters()
23324ae1
FM
66 */
67 void AddDocWriter(const wxString& docwriter);
68
69 /**
70 Adds a translator name to be shown in the program credits. Notice that if no
3a65144e 71 translator names are specified explicitely, wxAboutBox() will try to use the
463b4bfa
FM
72 translation of the string @c translator-credits from the currently used message
73 catalog -- this can be used to show just the name of the translator of the
74 program in the current language.
3c4f71cc 75
4cc4bfaf 76 @see SetTranslators()
23324ae1
FM
77 */
78 void AddTranslator(const wxString& translator);
79
80 /**
81 Sets the the list of artists to be shown in the program credits.
3c4f71cc 82
4cc4bfaf 83 @see AddArtist()
23324ae1
FM
84 */
85 void SetArtists(const wxArrayString& artists);
86
87 /**
4cc4bfaf
FM
88 Set the short string containing the program copyright information. Notice that
89 any occurrences of @c "(C)" in @a copyright will be replaced by the
23324ae1
FM
90 copyright symbol (circled C) automatically, which means that you can avoid
91 using this symbol in the program source code which can be problematic,
92 */
93 void SetCopyright(const wxString& copyright);
94
95 /**
96 Set brief, but possibly multiline, description of the program.
97 */
98 void SetDescription(const wxString& desc);
99
100 /**
101 Set the list of developers of the program.
3c4f71cc 102
4cc4bfaf 103 @see AddDeveloper()
23324ae1
FM
104 */
105 void SetDevelopers(const wxArrayString& developers);
106
107 /**
108 Set the list of documentation writers.
3c4f71cc 109
4cc4bfaf 110 @see AddDocWriter()
23324ae1
FM
111 */
112 void SetDocWriters(const wxArrayString& docwriters);
113
114 /**
115 Set the icon to be shown in the dialog. By default the icon of the main frame
116 will be shown if the native about dialog supports custom icons. If it doesn't
117 but a valid icon is specified using this method, the generic about dialog is
118 used instead so you should avoid calling this function for maximally native
119 look and feel.
120 */
121 void SetIcon(const wxIcon& icon);
122
123 /**
124 Set the long, multiline string containing the text of the program licence.
463b4bfa 125
23324ae1
FM
126 Only GTK+ version supports showing the licence text in the native about dialog
127 currently so the generic version will be used under all the other platforms if
128 this method is called. To preserve the native look and feel it is advised that
7c913512 129 you do not call this method but provide a separate menu item in the
23324ae1
FM
130 @c "Help" menu for displaying the text of your program licence.
131 */
132 void SetLicence(const wxString& licence);
133
134 /**
135 This is the same as SetLicence().
136 */
137 void SetLicense(const wxString& licence);
138
139 /**
140 Set the name of the program. If this method is not called, the string returned
141 by wxApp::GetAppName will be shown in the dialog.
142 */
143 void SetName(const wxString& name);
144
145 /**
463b4bfa 146 Set the list of translators. Please see AddTranslator() for additional
23324ae1
FM
147 discussion.
148 */
149 void SetTranslators(const wxArrayString& translators);
150
151 /**
152 Set the version of the program. The version is in free format, i.e. not
463b4bfa 153 necessarily in the @c x.y.z form but it shouldn't contain the "version" word.
23324ae1
FM
154 */
155 void SetVersion(const wxString& version);
156
157 /**
463b4bfa 158 Set the web site for the program and its description (which defaults to @a url
23324ae1 159 itself if empty).
463b4bfa 160
23324ae1
FM
161 Please notice that only GTK+ version currently supports showing the link in the
162 native about dialog so if this method is called, the generic version will be
163 used under all the other platforms.
164 */
165 void SetWebSite(const wxString& url,
166 const wxString& desc = wxEmptyString);
167};
168
169
170// ============================================================================
171// Global functions/macros
172// ============================================================================
173
39fb8056
FM
174/** @ingroup group_funcmacro_dialog */
175//@{
176
23324ae1
FM
177/**
178 This function shows the standard about dialog containing the information
463b4bfa
FM
179 specified in @a info. If the current platform has a native about dialog
180 which is capable of showing all the fields in @a info, the native dialog is
181 used, otherwise the function falls back to the generic wxWidgets version of
182 the dialog, i.e. does the same thing as wxGenericAboutBox.
183
23324ae1 184 Here is an example of how this function may be used:
7c913512 185
23324ae1
FM
186 @code
187 void MyFrame::ShowSimpleAboutDialog(wxCommandEvent& WXUNUSED(event))
188 {
189 wxAboutDialogInfo info;
190 info.SetName(_("My Program"));
191 info.SetVersion(_("1.2.3 Beta"));
192 info.SetDescription(_("This program does something great."));
ba2874ff 193 info.SetCopyright(_T("(C) 2007 Me <my@email.addre.ss>"));
7c913512 194
23324ae1
FM
195 wxAboutBox(info);
196 }
197 @endcode
7c913512 198
463b4bfa
FM
199 Please see the @ref page_utils_samples_dialogs for more examples of
200 using this function and wxAboutDialogInfo for the description of the
201 information which can be shown in the about dialog.
ba2874ff
BP
202
203 @header{wx/aboutdlg.h}
23324ae1
FM
204*/
205void wxAboutBox(const wxAboutDialogInfo& info);
206
207/**
3a65144e 208 This function does the same thing as wxAboutBox() except that it always uses
463b4bfa
FM
209 the generic wxWidgets version of the dialog instead of the native one.
210
211 This is mainly useful if you need to customize the dialog by e.g. adding
212 custom controls to it (customizing the native dialog is not currently
23324ae1 213 supported).
463b4bfa
FM
214
215 See the @ref page_utils_samples_dialogs for an example of about dialog
4cc4bfaf 216 customization.
7c913512 217
4cc4bfaf 218 @see wxAboutDialogInfo
ba2874ff
BP
219
220 @header{wx/aboutdlg.h}
23324ae1
FM
221*/
222void wxGenericAboutBox(const wxAboutDialogInfo& info);
223
39fb8056 224//@}