docs/tech/tn0015.txt

   1                 How to add new bitmaps to wxWindows UI elements
   2                 ===============================================
   3
   4 0. Introduction
   5 ---------------
   6
   7 Since the introduction of wxArtProvider class, it is no longer desired to hardcode
   8 art resources (e.g. icons and toolbar or button bitmaps) into the code. This was
   9 previously done either by including the bitmap in win32 resource file
  10 (include/wx/msw/wx.rc) or by including XPM files in the code.
  11
  12 wxArtProvider should be used instead, to allow users to customize the look of their
  13 wxWindows app. This technote is a detailed description of steps needed when adding
  14 new bitmap/icon.
  15
  16 1. Adding new resource
  17 ----------------------
  18
  19 (Please see wxArtProvider reference documentation for explanation of "art ID" and
  20 "art client" terms.)
  21
  22 First of all, you have to add new wxArtID constant to include/wx/artprov.h. Look for
  23 "Art IDs" and add new definition to the list, e.g.
  24     #define wxART_MY_BITMAP     _T("my_bitmap")
  25
  26 It may happen that the intended use of the new resource doesn't fit into any of defined
  27 client categories (search for "Art clients" in the header). In case the new resource is
  28 part of a larger category, you need to define a new client. Just add it to the list of
  29 existing clients:
  30     #define wxART_MY_CLIENT     _T("my_client_C")
  31 (Note that you *have* to add the trailing "_C"!)
  32
  33 Alternatively, you may use wxART_OTHER when accessing the resource if the bitmap is
  34 standalone.
  35
  36 Once the header is updated, it's time to add XPM file with the bitmap to $(wx)/art. Add
  37 it to $(wx)/art if it is platform-independent or to $(wx)/art/$(toolkit) if it is
  38 something specific to one of the toolkits. Note that "specific to one of the toolkits"
  39 doesn't mean that the bitmap is *used* by only one toolkit, but that it doesn't make
  40 sense for any of the others! For example, a GTK wxART_WARNING icon
  41 ($(wx)/art/gtk/warning.xpm) is specific to wxGTK, but new_dir.xpm makes sense even under
  42 wxMSW even though it is currently only used by the generic file dialog. Remember that
  43 wxArtProvider can be used by users, not only the library.
  44
  45 Finally, wxDefaultArtProvider in $(wx)/src/common/artstd.cpp must be updated. This
  46 consists of two steps:
  47
  48   a) add #include line for your XPM file, e.g.
  49        #include "../../art/my_bmp.xpm"
  50   b) add ART(...) line to wxDefaultArtProvider::CreateBitmap(). The first argument
  51      is wxArtID, the other is XPM file name (w/o extension), e.g.
  52        ART(wxART_MY_BITMAP, my_bmp)
  53
  54 That's all. The bitmap is now available to wxArtProvider users.
  55
  56 Note: there's no difference between icons and bitmaps, always treat them as bitmaps
  57       inside wx(Default)ArtProvider.
  58
  59 2. Accessing the resource
  60 -------------------------
  61
  62 The file that will use the bitmap needs to include "wx/artprov.h". The code to access
  63 the bitmap (or icon) is trivial:
  64
  65     wxBitmap bmp = wxArtProvider::GetBitmap(wxART_MY_BITMAP, wxART_MY_CLIENT);
  66         // this would be "wxBitmap bmp(my_bmp_xpm);" before
  67     wxIcon icon = wxArtProvider::GetIcon(wxART_MY_ICON, wxART_MY_CLIENT);
  68
  69 Substitute wxART_MY_CLIENT in the example with a suitable client ID. If the client
  70 is wxART_OTHER you may write only wxArtProvider::GetBitmap(wxART_MY_BITMAP).
  71
  72 3. Providing a demo
  73 -------------------
  74
  75 It is highly desirable to let the users know what stock bitmaps are available in
  76 wxWindows. The "artprov" sample serves this purpose: it contains a browser dialog
  77 that displays all available art resources.
  78
  79 It has to be updated to accomodate for new bitmaps. Fortunately, this is trivial:
  80 open $(wx)/samples/artprov/artbrows.cpp in text editor and
  81     ART_ICON(wxART_MY_BITMAP)
  82 line to the FillBitmaps() function.
  83
  84 Similarly, if you add a new client, please update FillClients() by adding new
  85 client to the end of the list.
  86
  87 === EOF ===
  88
  89 Version: $Id$