wxPython/src/_about.i

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        _about.i
   3 // Purpose:     SWIG interface for wxAboutDialog
   4 //
   5 // Author:      Robin Dunn
   6 //
   7 // Created:     08-Oct-2006
   8 // RCS-ID:      $Id$
   9 // Copyright:   (c) 2006 by Total Control Software
  10 // Licence:     wxWindows license
  11 /////////////////////////////////////////////////////////////////////////////
  12
  13 // Not a %module
  14
  15 %{
  16 #include <wx/aboutdlg.h>
  17 %}
  18
  19 //---------------------------------------------------------------------------
  20 %newgroup
  21
  22
  23 DocStr(wxAboutDialogInfo,
  24 "`wx.AboutDialogInfo` contains information to be shown in the standard
  25 About dialog displayed by the `wx.AboutBox` function.  This class
  26 contains the general information about the program, such as its name,
  27 version, copyright and so on, as well as lists of the program
  28 developers, documentation writers, artists and translators.
  29
  30 While all the main platforms have a native implementation of the about
  31 dialog, they are often more limited than the generic version provided
  32 by wxWidgets and so the generic version is used if
  33 `wx.AboutDialogInfo` has any fields not supported by the native
  34 version. Currently GTK+ version supports all the possible fields
  35 natively but MSW and Mac versions don't support URLs, licence text nor
  36 custom icons in the about dialog and if either of those is used,
  37 wxAboutBox() will automatically use the generic version so you should
  38 avoid specifying these fields to achieve more native look and feel.
  39 ", "");
  40
  41 class wxAboutDialogInfo
  42 {
  43 public:
  44     wxAboutDialogInfo();
  45     ~wxAboutDialogInfo();
  46
  47     DocDeclStr(
  48         void , SetName(const wxString& name),
  49         "Set the name of the program. If this method is not called, the string
  50 returned by `wx.App.GetAppName` will be shown in the dialog.", "");
  51
  52     DocDeclStr(
  53         wxString , GetName() const,
  54         "Returns the program name.", "");
  55
  56     %property(Name, GetName, SetName);
  57
  58     DocDeclStr(
  59         void , SetVersion(const wxString& version),
  60         "Set the version of the program. The version is in free format,
  61 i.e. not necessarily in the x.y.z form but it shouldn't contain the
  62 \"version\" word.", "");
  63
  64     DocDeclStr(
  65         bool , HasVersion() const,
  66         "Returns ``True`` if the version property has been set.", "");
  67
  68     DocDeclStr(
  69         wxString , GetVersion() const,
  70         "Returns the version value.", "");
  71
  72     %property(Version, GetVersion, SetVersion);
  73
  74
  75     DocDeclStr(
  76         void , SetDescription(const wxString& desc),
  77         "Set brief, but possibly multiline, description of the program.", "");
  78
  79     DocDeclStr(
  80         bool , HasDescription() const,
  81         "Returns ``True`` if the description property has been set.", "");
  82
  83     DocDeclStr(
  84         wxString , GetDescription() const,
  85         "Returns the description value.", "");
  86
  87     %property(Description, GetDescription, SetDescription);
  88
  89
  90     DocDeclStr(
  91         void , SetCopyright(const wxString& copyright),
  92         "Set the short string containing the program copyright
  93 information. Notice that any occurrences of \"(C)\" in ``copyright``
  94 will be replaced by the copyright symbol (circled C) automatically,
  95 which means that you can avoid using this symbol in the program source
  96 code which can be problematic.", "");
  97
  98     DocDeclStr(
  99         bool , HasCopyright() const,
 100         "Returns ``True`` if the copyright property has been set.", "");
 101
 102     DocDeclStr(
 103         wxString , GetCopyright() const,
 104         "Returns the copyright value.", "");
 105
 106     %property(Copyright, GetCopyright, SetCopyright);
 107
 108
 109     DocDeclStr(
 110         void , SetLicence(const wxString& licence),
 111         "Set the long, multiline string containing the text of the program
 112 licence.
 113
 114 Only GTK+ version supports showing the licence text in the native
 115 about dialog currently so the generic version will be used under all
 116 the other platforms if this method is called. To preserve the native
 117 look and feel it is advised that you do not call this method but
 118 provide a separate menu item in the \"Help\" menu for displaying the
 119 text of your program licence.
 120 ", "");
 121
 122     DocDeclStr(
 123         void , SetLicense(const wxString& licence),
 124         "This is the same as `SetLicence`.", "");
 125
 126     DocDeclStr(
 127         bool , HasLicence() const,
 128         "Returns ``True`` if the licence property has been set.", "");
 129
 130     DocDeclStr(
 131         wxString , GetLicence() const,
 132         "Returns the licence value.", "");
 133
 134     %property(Licence, GetLicence, SetLicence);
 135     %pythoncode { License = Licence }
 136
 137
 138     DocDeclStr(
 139         void , SetIcon(const wxIcon& icon),
 140         "Set the icon to be shown in the dialog. By default the icon of the
 141 main frame will be shown if the native about dialog supports custom
 142 icons. If it doesn't but a valid icon is specified using this method,
 143 the generic about dialog is used instead so you should avoid calling
 144 this function for maximally native look and feel.", "");
 145
 146     DocDeclStr(
 147         bool , HasIcon() const,
 148         "Returns ``True`` if the icon property has been set.", "");
 149
 150     DocDeclStr(
 151         wxIcon , GetIcon() const,
 152         "Return the current icon value.", "");
 153
 154     %property(Icon, GetIcon, SetIcon);
 155
 156
 157     // web site for the program and its description (defaults to URL itself if
 158     // empty)
 159     %Rename(_SetWebSite,
 160             void , SetWebSite(const wxString& url, const wxString& desc = wxEmptyString));
 161     %Rename(_GetWebSiteURL,
 162             wxString , GetWebSiteURL() const);
 163     %Rename(_GetWebSiteDescription,
 164             wxString , GetWebSiteDescription() const);
 165     bool HasWebSite() const;
 166
 167     %pythoncode {
 168         def SetWebSite(self, args):
 169             """
 170             SetWebSite(self, URL, [Description])
 171
 172             Set the web site property.  The ``args`` parameter can
 173             either be a single string for the URL, to a 2-tuple of
 174             (URL, Description) strings.
 175             """
 176             if type(args) in [str, unicode]:
 177                 self._SetWebSite(args)
 178             else:
 179                 self._SetWebSite(args[0], args[1])
 180
 181         def GetWebSite(self):
 182             """
 183             GetWebSite(self) --> (URL, Description)
 184             """
 185             return (self._GetWebSiteURL(), self._GetWebSiteDescription())
 186     }
 187     %property(WebSite, GetWebSite, SetWebSite)
 188
 189
 190
 191     DocDeclAStr(
 192         void , SetDevelopers(const wxArrayString& developers),
 193         "SetDevelopers(self, list developers)",
 194         "Set the list of the developers of the program.", "");
 195
 196     DocDeclStr(
 197         void , AddDeveloper(const wxString& developer),
 198         "Add a string to the list of developers.", "");
 199
 200     DocDeclStr(
 201         bool , HasDevelopers() const,
 202         "Returns ``True if any developers have been set.", "");
 203
 204     DocDeclAStr(
 205         const wxArrayString& , GetDevelopers() const,
 206         "GetDevelopers(self) --> list",
 207         "Returns the list of developers.", "");
 208
 209     %property(Developers, GetDevelopers, SetDevelopers);
 210
 211
 212     DocDeclAStr(
 213         void , SetDocWriters(const wxArrayString& docwriters),
 214         "SetDocWriters(self, list docwriters)",
 215         "Set the list of the documentation writers.", "");
 216
 217     DocDeclStr(
 218         void , AddDocWriter(const wxString& docwriter),
 219         "Add a string to the list of documentation writers.", "");
 220
 221     DocDeclStr(
 222         bool , HasDocWriters() const,
 223         "Returns ``True if any documentation writers have been set.", "");
 224
 225     DocDeclAStr(
 226         const wxArrayString& , GetDocWriters() const,
 227         "GetDocWriters(self) --> list",
 228         "Returns the list of documentation writers.", "");
 229
 230     %property(DocWriters, GetDocWriters, SetDocWriters);
 231
 232
 233     DocDeclAStr(
 234         void , SetArtists(const wxArrayString& artists),
 235         "SetArtists(self, list artists)",
 236         "Set the list of artists for the program.", "");
 237
 238     DocDeclStr(
 239         void , AddArtist(const wxString& artist),
 240         "Add a string to the list of artists.", "");
 241
 242     DocDeclStr(
 243         bool , HasArtists() const,
 244         "Returns ``True`` if any artists have been set.", "");
 245
 246     DocDeclAStr(
 247         const wxArrayString& , GetArtists() const,
 248         "GetArtists(self) --> list",
 249         "Returns the list od artists.", "");
 250
 251     %property(Artists, GetArtists, SetArtists);
 252
 253
 254
 255     DocDeclAStr(
 256         void , SetTranslators(const wxArrayString& translators),
 257         "SetTranslators(self, list translators)",
 258         "Sets the list of program translators.", "");
 259
 260     DocDeclStr(
 261         void , AddTranslator(const wxString& translator),
 262         "Add a string to the list of translators.", "");
 263
 264     DocDeclStr(
 265         bool , HasTranslators() const,
 266         "Returns ``True`` if any translators have been set.", "");
 267
 268     DocDeclAStr(
 269         const wxArrayString& , GetTranslators() const,
 270         "GetTranslators(self) --> list",
 271         "Returns the list of program translators.", "");
 272
 273     %property(Translators, GetTranslators, SetTranslators);
 274
 275
 276     // implementation only
 277     // -------------------
 278
 279     // "simple" about dialog shows only textual information (with possibly
 280     // default icon but without hyperlink nor any long texts such as the
 281     // licence text)
 282     bool IsSimple() const;
 283
 284     // get the description and credits (i.e. all of developers, doc writers,
 285     // artists and translators) as a one long multiline string
 286     wxString GetDescriptionAndCredits() const;
 287
 288 };
 289
 290
 291
 292 DocStr(wxAboutBox,
 293        "This function shows the standard about dialog containing the
 294 information specified in ``info``. If the current platform has a
 295 native about dialog which is capable of showing all the fields in
 296 `wx.AboutDialogInfo`, the native dialog is used, otherwise the
 297 function falls back to the generic wxWidgets version of the dialog.", "");
 298
 299 void wxAboutBox(const wxAboutDialogInfo& info);
 300
 301
 302 //---------------------------------------------------------------------------