]> git.saurik.com Git - wxWidgets.git/blame - docs/tech/tn0015.txt
Add wxHtmlTag::GetParamAsString() convenience method.
[wxWidgets.git] / docs / tech / tn0015.txt
CommitLineData
fc2171bd 1 How to add new bitmaps to wxWidgets UI elements
ea67ba0f
VS
2 ===============================================
3
40. Introduction
5---------------
6
a5823953
VZ
7Since the introduction of wxArtProvider class, it is no longer desired to
8hardcode art resources (e.g. icons and toolbar or button bitmaps) into the
9code. This was previously done either by including the bitmap in win32
10resource file (include/wx/msw/wx.rc) or by including XPM files in the code.
ea67ba0f 11
a5823953 12wxArtProvider should be used instead, to allow users to customize the look of
fc2171bd 13their wxWidgets app. This technote is a detailed description of steps needed
a5823953 14when adding new bitmap/icon.
ea67ba0f
VS
15
161. Adding new resource
17----------------------
18
a5823953
VZ
19(Please see wxArtProvider reference documentation for explanation of "art ID"
20 and "art client" terms.)
ea67ba0f 21
a5823953
VZ
22First of all, you have to add new wxArtID constant to include/wx/artprov.h.
23Look for "Art IDs" and add new definition to the list, e.g.
82e94f59 24 #define wxART_MY_BITMAP wxART_MAKE_ART_ID(wxART_MY_BITMAP)
c1d2466a
VZ
25
26Add it to interface/wx/artprov.h, too.
ea67ba0f 27
a5823953
VZ
28It may happen that the intended use of the new resource doesn't fit into any
29of defined client categories (search for "Art clients" in the header). In case
30the new resource is part of a larger category, you need to define a new
0dec0ec2
VS
31client. Just add it to the list of existing clients (and don't forget to
32update artprov.tex):
82e94f59 33 #define wxART_MY_CLIENT wxART_MAKE_CLIENT_ID(wxART_MY_CLIENT)
ea67ba0f 34
a5823953
VZ
35Alternatively, you may use wxART_OTHER when accessing the resource if the
36bitmap is standalone.
ea67ba0f 37
a5823953
VZ
38Once 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
41that "specific to one of the toolkits" doesn't mean that the bitmap is *used*
42by only one toolkit, but that it doesn't make sense for any of the others! For
43example, a GTK wxART_WARNING icon ($(wx)/art/gtk/warning.xpm) is specific to
44wxGTK, but new_dir.xpm makes sense even under wxMSW even though it is
45currently only used by the generic file dialog. Remember that wxArtProvider
46can be used by users, not only the library.
ea67ba0f 47
a5823953 48Finally, wxDefaultArtProvider in $(wx)/src/common/artstd.cpp must be updated.
c1d2466a 49This consists of two steps:
ea67ba0f 50
a5823953
VZ
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)
ea67ba0f
VS
55
56That's all. The bitmap is now available to wxArtProvider users.
57
a5823953
VZ
58Note: there's no difference between icons and bitmaps, always treat them as
59bitmaps inside wx(Default)ArtProvider.
ea67ba0f 60
c1d2466a
VZ
611b. Adding Tango version of the resource.
62-----------------------------------------
63
64While all the bitmaps are provided in XPM format so that they are available in
65all builds of wxWidgets, we also provide most of them in PNG format with full
66transparency support that is not available in XPM. Another advantage of the PNG
67versions is that the icons used are those of the Tango project and so have the
68consistent look, unlike the XPM ones.
69
70So if you an icon exists in http://tango.freedesktop.org/Tango_Icon_Gallery you
71should add it too. For this you need to:
72
731. 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
852. Add #include for the newly created file to src/common/arttango.cpp.
86
873. Add an entry to s_allBitmaps array in the same file.
88
89
ea67ba0f
VS
902. Accessing the resource
91-------------------------
92
a5823953
VZ
93The file that will use the bitmap needs to include "wx/artprov.h". The code to
94access the bitmap (or icon) is trivial:
ea67ba0f
VS
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
a5823953
VZ
100Substitute wxART_MY_CLIENT in the example with a suitable client ID. If the
101client is wxART_OTHER you may write only
102
103 wxArtProvider::GetBitmap(wxART_MY_BITMAP).
ea67ba0f
VS
104
1053. Providing a demo
106-------------------
107
a5823953 108It is highly desirable to let the users know what stock bitmaps are available
fc2171bd 109in wxWidgets. The "artprov" sample serves this purpose: it contains a browser
a5823953 110dialog that displays all available art resources.
ea67ba0f 111
dbd94b75 112It has to be updated to accommodate for new bitmaps. Fortunately, this is
a5823953
VZ
113trivial: open $(wx)/samples/artprov/artbrows.cpp in text editor and
114ART_ICON(wxART_MY_BITMAP) line to the FillBitmaps() function.
ea67ba0f
VS
115
116Similarly, if you add a new client, please update FillClients() by adding new
117client to the end of the list.
118
119=== EOF ===
120