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