docs/tech/tn0015.txt

   1                 How to add new bitmaps to wxWidgets UI elements
   2                 ===============================================
   3
   4 0. Introduction
   5 ---------------
   6
   7 Since the introduction of wxArtProvider class, it is no longer desired to
   8 hardcode art resources (e.g. icons and toolbar or button bitmaps) into the
   9 code. This was previously done either by including the bitmap in win32
  10 resource file (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
  13 their wxWidgets app. This technote is a detailed description of steps needed
  14 when adding new bitmap/icon.
  15
  16 1. Adding new resource
  17 ----------------------
  18
  19 (Please see wxArtProvider reference documentation for explanation of "art ID"
  20  and "art client" terms.)
  21
  22 First of all, you have to add new wxArtID constant to include/wx/artprov.h.
  23 Look for "Art IDs" and add new definition to the list, e.g.
  24     #define wxART_MY_BITMAP     wxART_MAKE_ART_ID(wxART_MY_BITMAP)
  25
  26 Add it to interface/wx/artprov.h, too.
  27
  28 It may happen that the intended use of the new resource doesn't fit into any
  29 of defined client categories (search for "Art clients" in the header). In case
  30 the new resource is part of a larger category, you need to define a new
  31 client. Just add it to the list of existing clients (and don't forget to
  32 update artprov.tex):
  33     #define wxART_MY_CLIENT wxART_MAKE_CLIENT_ID(wxART_MY_CLIENT)
  34
  35 Alternatively, you may use wxART_OTHER when accessing the resource if the
  36 bitmap is standalone.
  37
  38 Once the header is updated, it's time to add XPM file with the bitmap to
  39 $(wx)/art. Add it to $(wx)/art if it is platform-independent or to
  40 $(wx)/art/$(toolkit) if it is something specific to one of the toolkits. Note
  41 that "specific to one of the toolkits" doesn't mean that the bitmap is *used*
  42 by only one toolkit, but that it doesn't make sense for any of the others! For
  43 example, a GTK wxART_WARNING icon ($(wx)/art/gtk/warning.xpm) is specific to
  44 wxGTK, but new_dir.xpm makes sense even under wxMSW even though it is
  45 currently only used by the generic file dialog. Remember that wxArtProvider
  46 can be used by users, not only the library.
  47
  48 Finally, wxDefaultArtProvider in $(wx)/src/common/artstd.cpp must be updated.
  49 This consists of two steps:
  50
  51   a) add #include line for your XPM file, e.g. #include "../../art/my_bmp.xpm"
  52   b) add ART(...) line to wxDefaultArtProvider::CreateBitmap(). The first
  53      argument is wxArtID, the other is XPM file name (w/o extension), e.g.
  54      ART(wxART_MY_BITMAP, my_bmp)
  55
  56 That's all. The bitmap is now available to wxArtProvider users.
  57
  58 Note: there's no difference between icons and bitmaps, always treat them as
  59 bitmaps inside wx(Default)ArtProvider.
  60
  61 1b. Adding Tango version of the resource.
  62 -----------------------------------------
  63
  64 While all the bitmaps are provided in XPM format so that they are available in
  65 all builds of wxWidgets, we also provide most of them in PNG format with full
  66 transparency support that is not available in XPM. Another advantage of the PNG
  67 versions is that the icons used are those of the Tango project and so have the
  68 consistent look, unlike the XPM ones.
  69
  70 So if you an icon exists in http://tango.freedesktop.org/Tango_Icon_Gallery you
  71 should add it too. For this you need to:
  72
  73 1. Convert the PNG to a C array of bytes suitable for inclusion in the code.
  74    This is done using misc/scripts/png2c.py script, e.g. if the variable "f"
  75    contains the name of the icon you want to add and you have installed Tango
  76    icons in a standard location under a Linux system:
  77
  78     ./misc/scripts/png2c.py -s /usr/share/icons/Tango/{16x16,24x24}/*/$f.png >
  79         art/tango/${f//-/_}.h
  80
  81    Of course, the same command may be ran with different paths under Windows.
  82    Just remember to add both 16 and 24 pixel versions of the bitmap to the
  83    header and use the "-s" option to embed the image size in its array name.
  84
  85 2. Add #include for the newly created file to src/common/arttango.cpp.
  86
  87 3. Add an entry to s_allBitmaps array in the same file.
  88
  89
  90 2. Accessing the resource
  91 -------------------------
  92
  93 The file that will use the bitmap needs to include "wx/artprov.h". The code to
  94 access the bitmap (or icon) is trivial:
  95
  96     wxBitmap bmp = wxArtProvider::GetBitmap(wxART_MY_BITMAP, wxART_MY_CLIENT);
  97         // this would be "wxBitmap bmp(my_bmp_xpm);" before
  98     wxIcon icon = wxArtProvider::GetIcon(wxART_MY_ICON, wxART_MY_CLIENT);
  99
 100 Substitute wxART_MY_CLIENT in the example with a suitable client ID. If the
 101 client is wxART_OTHER you may write only
 102
 103     wxArtProvider::GetBitmap(wxART_MY_BITMAP).
 104
 105 3. Providing a demo
 106 -------------------
 107
 108 It is highly desirable to let the users know what stock bitmaps are available
 109 in wxWidgets. The "artprov" sample serves this purpose: it contains a browser
 110 dialog that displays all available art resources.
 111
 112 It has to be updated to accommodate for new bitmaps. Fortunately, this is
 113 trivial: open $(wx)/samples/artprov/artbrows.cpp in text editor and
 114 ART_ICON(wxART_MY_BITMAP) line to the FillBitmaps() function.
 115
 116 Similarly, if you add a new client, please update FillClients() by adding new
 117 client to the end of the list.
 118
 119 === EOF ===
 120