wxPython/src/_artprov.i

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        _artprov.i
   3 // Purpose:     SWIG interface stuff for wxArtProvider
   4 //
   5 // Author:      Robin Dunn
   6 //
   7 // Created:     18-June-1999
   8 // RCS-ID:      $Id$
   9 // Copyright:   (c) 2003 by Total Control Software
  10 // Licence:     wxWindows license
  11 /////////////////////////////////////////////////////////////////////////////
  12
  13 // Not a %module
  14
  15
  16 //---------------------------------------------------------------------------
  17 %newgroup
  18
  19 %{
  20 #include <wx/artprov.h>
  21 %}
  22
  23 //---------------------------------------------------------------------------
  24
  25
  26 // Art clients
  27 MAKE_CONST_WXSTRING(ART_TOOLBAR);
  28 MAKE_CONST_WXSTRING(ART_MENU);
  29 MAKE_CONST_WXSTRING(ART_FRAME_ICON);
  30 MAKE_CONST_WXSTRING(ART_CMN_DIALOG);
  31 MAKE_CONST_WXSTRING(ART_HELP_BROWSER);
  32 MAKE_CONST_WXSTRING(ART_MESSAGE_BOX);
  33 MAKE_CONST_WXSTRING(ART_BUTTON);
  34 MAKE_CONST_WXSTRING(ART_LIST);
  35 MAKE_CONST_WXSTRING(ART_OTHER);
  36
  37 // Art IDs
  38 MAKE_CONST_WXSTRING(ART_ADD_BOOKMARK);
  39 MAKE_CONST_WXSTRING(ART_DEL_BOOKMARK);
  40 MAKE_CONST_WXSTRING(ART_HELP_SIDE_PANEL);
  41 MAKE_CONST_WXSTRING(ART_HELP_SETTINGS);
  42 MAKE_CONST_WXSTRING(ART_HELP_BOOK);
  43 MAKE_CONST_WXSTRING(ART_HELP_FOLDER);
  44 MAKE_CONST_WXSTRING(ART_HELP_PAGE);
  45 MAKE_CONST_WXSTRING(ART_GO_BACK);
  46 MAKE_CONST_WXSTRING(ART_GO_FORWARD);
  47 MAKE_CONST_WXSTRING(ART_GO_UP);
  48 MAKE_CONST_WXSTRING(ART_GO_DOWN);
  49 MAKE_CONST_WXSTRING(ART_GO_TO_PARENT);
  50 MAKE_CONST_WXSTRING(ART_GO_HOME);
  51 MAKE_CONST_WXSTRING(ART_FILE_OPEN);
  52 MAKE_CONST_WXSTRING(ART_FILE_SAVE);
  53 MAKE_CONST_WXSTRING(ART_FILE_SAVE_AS);
  54 MAKE_CONST_WXSTRING(ART_PRINT);
  55 MAKE_CONST_WXSTRING(ART_HELP);
  56 MAKE_CONST_WXSTRING(ART_TIP);
  57 MAKE_CONST_WXSTRING(ART_REPORT_VIEW);
  58 MAKE_CONST_WXSTRING(ART_LIST_VIEW);
  59 MAKE_CONST_WXSTRING(ART_NEW_DIR);
  60 MAKE_CONST_WXSTRING(ART_HARDDISK);
  61 MAKE_CONST_WXSTRING(ART_FLOPPY);
  62 MAKE_CONST_WXSTRING(ART_CDROM);
  63 MAKE_CONST_WXSTRING(ART_REMOVABLE);
  64 MAKE_CONST_WXSTRING(ART_FOLDER);
  65 MAKE_CONST_WXSTRING(ART_FOLDER_OPEN);
  66 MAKE_CONST_WXSTRING(ART_GO_DIR_UP);
  67 MAKE_CONST_WXSTRING(ART_EXECUTABLE_FILE);
  68 MAKE_CONST_WXSTRING(ART_NORMAL_FILE);
  69 MAKE_CONST_WXSTRING(ART_TICK_MARK);
  70 MAKE_CONST_WXSTRING(ART_CROSS_MARK);
  71 MAKE_CONST_WXSTRING(ART_ERROR);
  72 MAKE_CONST_WXSTRING(ART_QUESTION);
  73 MAKE_CONST_WXSTRING(ART_WARNING);
  74 MAKE_CONST_WXSTRING(ART_INFORMATION);
  75 MAKE_CONST_WXSTRING(ART_MISSING_IMAGE);
  76 MAKE_CONST_WXSTRING(ART_COPY);
  77 MAKE_CONST_WXSTRING(ART_CUT);
  78 MAKE_CONST_WXSTRING(ART_PASTE);
  79 MAKE_CONST_WXSTRING(ART_DELETE);
  80 MAKE_CONST_WXSTRING(ART_NEW);
  81 MAKE_CONST_WXSTRING(ART_UNDO);
  82 MAKE_CONST_WXSTRING(ART_REDO);
  83 MAKE_CONST_WXSTRING(ART_QUIT);
  84 MAKE_CONST_WXSTRING(ART_FIND);
  85 MAKE_CONST_WXSTRING(ART_FIND_AND_REPLACE);
  86
  87 //---------------------------------------------------------------------------
  88
  89 %{  // Python aware wxArtProvider
  90 class wxPyArtProvider : public wxArtProvider  {
  91 public:
  92
  93     virtual wxBitmap CreateBitmap(const wxArtID& id,
  94                                   const wxArtClient& client,
  95                                   const wxSize& size) {
  96         wxBitmap rval = wxNullBitmap;
  97         wxPyBlock_t blocked = wxPyBeginBlockThreads();
  98         if ((wxPyCBH_findCallback(m_myInst, "CreateBitmap"))) {
  99             PyObject* so = wxPyConstructObject((void*)&size, wxT("wxSize"), 0);
 100             PyObject* ro;
 101             wxBitmap* ptr;
 102             PyObject* s1, *s2;
 103             s1 = wx2PyString(id);
 104             s2 = wx2PyString(client);
 105             ro = wxPyCBH_callCallbackObj(m_myInst, Py_BuildValue("(OOO)", s1, s2, so));
 106             Py_DECREF(so);
 107             Py_DECREF(s1);
 108             Py_DECREF(s2);
 109             if (ro) {
 110                 if (wxPyConvertSwigPtr(ro, (void**)&ptr, wxT("wxBitmap")))
 111                     rval = *ptr;
 112                 Py_DECREF(ro);
 113             }
 114         }
 115         wxPyEndBlockThreads(blocked);
 116         return rval;
 117     }
 118
 119     virtual wxIconBundle CreateIconBundle(const wxArtID& id,
 120                                           const wxArtClient& client)
 121     {
 122         wxIconBundle rval = wxNullIconBundle;
 123         wxPyBlock_t blocked = wxPyBeginBlockThreads();
 124         if ((wxPyCBH_findCallback(m_myInst, "CreateIconBundle"))) {
 125             PyObject* ro;
 126             wxIconBundle* ptr;
 127             PyObject* s1, *s2;
 128             s1 = wx2PyString(id);
 129             s2 = wx2PyString(client);
 130             ro = wxPyCBH_callCallbackObj(m_myInst, Py_BuildValue("(OO)", s1, s2));
 131             Py_DECREF(s1);
 132             Py_DECREF(s2);
 133             if (ro) {
 134                 if (wxPyConvertSwigPtr(ro, (void**)&ptr, wxT("wxIconBundle")))
 135                     rval = *ptr;
 136                 Py_DECREF(ro);
 137             }
 138         }
 139         wxPyEndBlockThreads(blocked);
 140         return rval;
 141     }
 142
 143     PYPRIVATE;
 144 };
 145 %}
 146
 147 // The one for SWIG to see
 148
 149
 150
 151 DocStr(wxPyArtProvider,
 152 "The wx.ArtProvider class is used to customize the look of wxWidgets
 153 application. When wxWidgets needs to display an icon or a bitmap (e.g.
 154 in the standard file dialog), it does not use hard-coded resource but
 155 asks wx.ArtProvider for it instead. This way the users can plug in
 156 their own wx.ArtProvider class and easily replace standard art with
 157 his/her own version. It is easy thing to do: all that is needed is
 158 to derive a class from wx.ArtProvider, override it's CreateBitmap
 159 method and register the provider with `wx.ArtProvider.Push`::
 160
 161     class MyArtProvider(wx.ArtProvider):
 162         def __init__(self):
 163             wx.ArtProvider.__init__(self)
 164
 165         def CreateBitmap(self, artid, client, size):
 166             ...
 167             return bmp
 168 ", "
 169
 170 Identifying art resources
 171 -------------------------
 172
 173 Every bitmap is known to wx.ArtProvider under an unique ID that is
 174 used when requesting a resource from it. The IDs can have one of the
 175 following predefined values.  Additionally, any string recognized by
 176 custom art providers registered using `Push` may be used.
 177
 178 GTK+ Note
 179 ---------
 180
 181 When running under GTK+ 2, GTK+ stock item IDs (e.g. 'gtk-cdrom') may be used
 182 as well.  Additionally, if wxGTK was compiled against GTK+ >= 2.4, then it is
 183 also possible to load icons from current icon theme by specifying their name
 184 without the extension and directory components. Icon themes recognized by GTK+
 185 follow the freedesktop.org Icon Themes specification.  Note that themes are
 186 not guaranteed to contain all icons, so wx.ArtProvider may return wx.NullBitmap
 187 or wx.NullIcon.  The default theme is typically installed in /usr/share/icons/hicolor.
 188
 189     * wx.ART_ADD_BOOKMARK
 190     * wx.ART_DEL_BOOKMARK
 191     * wx.ART_HELP_SIDE_PANEL
 192     * wx.ART_HELP_SETTINGS
 193     * wx.ART_HELP_BOOK
 194     * wx.ART_HELP_FOLDER
 195     * wx.ART_HELP_PAGE
 196     * wx.ART_GO_BACK
 197     * wx.ART_GO_FORWARD
 198     * wx.ART_GO_UP
 199     * wx.ART_GO_DOWN
 200     * wx.ART_GO_TO_PARENT
 201     * wx.ART_GO_HOME
 202     * wx.ART_FILE_OPEN
 203     * wx.ART_FILE_SAVE
 204     * wx.ART_FILE_SAVE_AS
 205     * wx.ART_PRINT
 206     * wx.ART_HELP
 207     * wx.ART_TIP
 208     * wx.ART_REPORT_VIEW
 209     * wx.ART_LIST_VIEW
 210     * wx.ART_NEW_DIR
 211     * wx.ART_HARDDISK
 212     * wx.ART_FLOPPY
 213     * wx.ART_CDROM
 214     * wx.ART_REMOVABLE
 215     * wx.ART_FOLDER
 216     * wx.ART_FOLDER_OPEN
 217     * wx.ART_GO_DIR_UP
 218     * wx.ART_EXECUTABLE_FILE
 219     * wx.ART_NORMAL_FILE
 220     * wx.ART_TICK_MARK
 221     * wx.ART_CROSS_MARK
 222     * wx.ART_ERROR
 223     * wx.ART_QUESTION
 224     * wx.ART_WARNING
 225     * wx.ART_INFORMATION
 226     * wx.ART_MISSING_IMAGE
 227     * wx.ART_COPY
 228     * wx.ART_CUT
 229     * wx.ART_PASTE
 230     * wx.ART_DELETE
 231     * wx.ART_NEW
 232     * wx.ART_UNDO
 233     * wx.ART_REDO
 234     * wx.ART_QUIT
 235     * wx.ART_FIND
 236     * wx.ART_FIND_AND_REPLACE
 237
 238
 239 Clients
 240 -------
 241
 242 The Client is the entity that calls wx.ArtProvider's `GetBitmap` or
 243 `GetIcon` function.  Client IDs serve as a hint to wx.ArtProvider
 244 that is supposed to help it to choose the best looking bitmap. For
 245 example it is often desirable to use slightly different icons in menus
 246 and toolbars even though they represent the same action (e.g.
 247 wx.ART_FILE_OPEN). Remember that this is really only a hint for
 248 wx.ArtProvider -- it is common that `wx.ArtProvider.GetBitmap` returns
 249 identical bitmap for different client values!
 250
 251     * wx.ART_TOOLBAR
 252     * wx.ART_MENU
 253     * wx.ART_FRAME_ICON
 254     * wx.ART_CMN_DIALOG
 255     * wx.ART_HELP_BROWSER
 256     * wx.ART_MESSAGE_BOX
 257     * wx.ART_BUTTON
 258     * wx.ART_OTHER (used for all requests that don't fit into any
 259       of the categories above)
 260 ");
 261
 262 MustHaveApp(wxPyArtProvider);
 263 MustHaveApp(wxPyArtProvider::GetBitmap);
 264 MustHaveApp(wxPyArtProvider::GetIcon);
 265 MustHaveApp(wxPyArtProvider::GetBundle);
 266
 267 %rename(ArtProvider) wxPyArtProvider;
 268 class wxPyArtProvider /*: public wxObject*/
 269 {
 270 public:
 271
 272     %pythonAppend wxPyArtProvider setCallbackInfo(ArtProvider);
 273     wxPyArtProvider();
 274     ~wxPyArtProvider();
 275
 276     void _setCallbackInfo(PyObject* self, PyObject* _class);
 277
 278     %disownarg( wxPyArtProvider *provider );
 279
 280     DocDeclStr(
 281         static void , Push(wxPyArtProvider *provider),
 282         "Add new provider to the top of providers stack.", "");
 283     %pythoncode { PushProvider = Push }
 284
 285     DocDeclStr(
 286         static void , Insert(wxPyArtProvider *provider),
 287         "Add new provider to the bottom of providers stack.", "");
 288     %pythoncode { InsertProvider = Insert }
 289
 290     %cleardisown( wxPyArtProvider *provider );
 291
 292
 293     DocDeclStr(
 294         static bool , Pop(),
 295         "Remove latest added provider and delete it.", "");
 296     %pythoncode { PopProvider = Pop }
 297
 298     %pythonAppend Delete "args[1].thisown = 1";
 299     DocDeclStr(
 300         static bool , Delete(wxPyArtProvider *provider),
 301         "Remove provider. The provider must have been added previously!  The
 302 provider is _not_ deleted.", "");
 303     %pythoncode { RemoveProvider = Delete }
 304
 305
 306     DocDeclStr(
 307         static wxBitmap , GetBitmap(const wxString& id,
 308                                     const wxString& client = wxPyART_OTHER,
 309                                     const wxSize& size = wxDefaultSize),
 310         "Query the providers for bitmap with given ID and return it. Return
 311 wx.NullBitmap if no provider provides it.", "");
 312
 313
 314     DocDeclStr(
 315         static wxIcon , GetIcon(const wxString& id,
 316                                 const wxString& client = wxPyART_OTHER,
 317                                 const wxSize& size = wxDefaultSize),
 318         "Query the providers for icon with given ID and return it.  Return
 319 wx.NullIcon if no provider provides it.", "");
 320
 321     DocDeclStr(
 322         static wxIconBundle , GetIconBundle(const wxArtID& id,
 323                                             const wxArtClient& client = wxART_OTHER),
 324         "Query the providers for iconbundle with given ID and return it. Return
 325 wx.NullIconBundle if no provider provides it.", "");
 326
 327
 328     DocDeclStr(
 329         static wxSize , GetSizeHint(const wxString& client, bool platform_dependent = false),
 330         "Get the size hint of an icon from a specific Art Client, queries the
 331 topmost provider if platform_dependent = false", "");
 332
 333
 334
 335     %pythonPrepend Destroy "args[0].this.own(False)"
 336     %extend { void Destroy() { delete self; }}
 337 };
 338
 339
 340
 341 //---------------------------------------------------------------------------
 342 %init %{
 343     wxPyPtrTypeMap_Add("wxArtProvider", "wxPyArtProvider");
 344 %}
 345 //---------------------------------------------------------------------------