update KDE guide link; added to the list of the 'Changes which are compatible' the...

[wxWidgets.git] / docs / tech / tn0015.txt

                How to add new bitmaps to wxWidgets 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 wxWidgets 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     wxART_MAKE_ART_ID(wxART_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 wxART_MAKE_CLIENT_ID(wxART_MY_CLIENT)

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 wxWidgets. The "artprov" sample serves this purpose: it contains a browser
dialog that displays all available art resources.

It has to be updated to accommodate 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$