0dec0ec2a7
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@15182 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
94 lines
3.8 KiB
Plaintext
94 lines
3.8 KiB
Plaintext
How to add new bitmaps to wxWindows UI elements
|
|
===============================================
|
|
|
|
0. Introduction
|
|
---------------
|
|
|
|
Since the introduction of wxArtProvider class, it is no longer desired to
|
|
hardcode art resources (e.g. icons and toolbar or button bitmaps) into the
|
|
code. This was previously done either by including the bitmap in win32
|
|
resource file (include/wx/msw/wx.rc) or by including XPM files in the code.
|
|
|
|
wxArtProvider should be used instead, to allow users to customize the look of
|
|
their wxWindows app. This technote is a detailed description of steps needed
|
|
when adding new bitmap/icon.
|
|
|
|
1. Adding new resource
|
|
----------------------
|
|
|
|
(Please see wxArtProvider reference documentation for explanation of "art ID"
|
|
and "art client" terms.)
|
|
|
|
First of all, you have to add new wxArtID constant to include/wx/artprov.h.
|
|
Look for "Art IDs" and add new definition to the list, e.g.
|
|
#define wxART_MY_BITMAP _T("my_bitmap")
|
|
|
|
Add it to docs/latex/wx/artprov.tex, too.
|
|
|
|
It may happen that the intended use of the new resource doesn't fit into any
|
|
of defined client categories (search for "Art clients" in the header). In case
|
|
the new resource is part of a larger category, you need to define a new
|
|
client. Just add it to the list of existing clients (and don't forget to
|
|
update artprov.tex):
|
|
#define wxART_MY_CLIENT _T("my_client_C")
|
|
(Note that you *have* to add the trailing "_C"!)
|
|
|
|
Alternatively, you may use wxART_OTHER when accessing the resource if the
|
|
bitmap is standalone.
|
|
|
|
Once the header is updated, it's time to add XPM file with the bitmap to
|
|
$(wx)/art. Add it to $(wx)/art if it is platform-independent or to
|
|
$(wx)/art/$(toolkit) if it is something specific to one of the toolkits. Note
|
|
that "specific to one of the toolkits" doesn't mean that the bitmap is *used*
|
|
by only one toolkit, but that it doesn't make sense for any of the others! For
|
|
example, a GTK wxART_WARNING icon ($(wx)/art/gtk/warning.xpm) is specific to
|
|
wxGTK, but new_dir.xpm makes sense even under wxMSW even though it is
|
|
currently only used by the generic file dialog. Remember that wxArtProvider
|
|
can be used by users, not only the library.
|
|
|
|
Finally, wxDefaultArtProvider in $(wx)/src/common/artstd.cpp must be updated.
|
|
This consists of two steps:
|
|
|
|
a) add #include line for your XPM file, e.g. #include "../../art/my_bmp.xpm"
|
|
b) add ART(...) line to wxDefaultArtProvider::CreateBitmap(). The first
|
|
argument is wxArtID, the other is XPM file name (w/o extension), e.g.
|
|
ART(wxART_MY_BITMAP, my_bmp)
|
|
|
|
That's all. The bitmap is now available to wxArtProvider users.
|
|
|
|
Note: there's no difference between icons and bitmaps, always treat them as
|
|
bitmaps inside wx(Default)ArtProvider.
|
|
|
|
2. Accessing the resource
|
|
-------------------------
|
|
|
|
The file that will use the bitmap needs to include "wx/artprov.h". The code to
|
|
access the bitmap (or icon) is trivial:
|
|
|
|
wxBitmap bmp = wxArtProvider::GetBitmap(wxART_MY_BITMAP, wxART_MY_CLIENT);
|
|
// this would be "wxBitmap bmp(my_bmp_xpm);" before
|
|
wxIcon icon = wxArtProvider::GetIcon(wxART_MY_ICON, wxART_MY_CLIENT);
|
|
|
|
Substitute wxART_MY_CLIENT in the example with a suitable client ID. If the
|
|
client is wxART_OTHER you may write only
|
|
|
|
wxArtProvider::GetBitmap(wxART_MY_BITMAP).
|
|
|
|
3. Providing a demo
|
|
-------------------
|
|
|
|
It is highly desirable to let the users know what stock bitmaps are available
|
|
in wxWindows. The "artprov" sample serves this purpose: it contains a browser
|
|
dialog that displays all available art resources.
|
|
|
|
It has to be updated to accomodate for new bitmaps. Fortunately, this is
|
|
trivial: open $(wx)/samples/artprov/artbrows.cpp in text editor and
|
|
ART_ICON(wxART_MY_BITMAP) line to the FillBitmaps() function.
|
|
|
|
Similarly, if you add a new client, please update FillClients() by adding new
|
|
client to the end of the list.
|
|
|
|
=== EOF ===
|
|
|
|
Version: $Id$
|