]> git.saurik.com Git - wxWidgets.git/blame_incremental - docs/tech/tn0015.txt
Only include <unistd.h> under Unix in wxGTK code.
[wxWidgets.git] / docs / tech / tn0015.txt
... / ...
CommitLineData
1 How to add new bitmaps to wxWidgets UI elements
2 ===============================================
3
40. Introduction
5---------------
6
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.
11
12wxArtProvider should be used instead, to allow users to customize the look of
13their wxWidgets app. This technote is a detailed description of steps needed
14when adding new bitmap/icon.
15
161. Adding new resource
17----------------------
18
19(Please see wxArtProvider reference documentation for explanation of "art ID"
20 and "art client" terms.)
21
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.
24 #define wxART_MY_BITMAP wxART_MAKE_ART_ID(wxART_MY_BITMAP)
25
26Add it to interface/wx/artprov.h, too.
27
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
31client. Just add it to the list of existing clients (and don't forget to
32update artprov.tex):
33 #define wxART_MY_CLIENT wxART_MAKE_CLIENT_ID(wxART_MY_CLIENT)
34
35Alternatively, you may use wxART_OTHER when accessing the resource if the
36bitmap is standalone.
37
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.
47
48Finally, wxDefaultArtProvider in $(wx)/src/common/artstd.cpp must be updated.
49This 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
56That's all. The bitmap is now available to wxArtProvider users.
57
58Note: there's no difference between icons and bitmaps, always treat them as
59bitmaps inside wx(Default)ArtProvider.
60
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
902. Accessing the resource
91-------------------------
92
93The file that will use the bitmap needs to include "wx/artprov.h". The code to
94access 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
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).
104
1053. Providing a demo
106-------------------
107
108It is highly desirable to let the users know what stock bitmaps are available
109in wxWidgets. The "artprov" sample serves this purpose: it contains a browser
110dialog that displays all available art resources.
111
112It has to be updated to accommodate for new bitmaps. Fortunately, this is
113trivial: open $(wx)/samples/artprov/artbrows.cpp in text editor and
114ART_ICON(wxART_MY_BITMAP) line to the FillBitmaps() function.
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
121Version: $Id$