added wxArtProvider technote

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@14985 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

diff --git a/docs/tech/index.txt b/docs/tech/index.txt
index 7aabf09ee3f9a707f2c7ef18cb19349fff7430be..87d5f86239eb1fae676c33b5c4f8df20995a5214 100644 (file)
--- a/docs/tech/index.txt
+++ b/docs/tech/index.txt
@@ -12,6 +12,7 @@ TN0011   All about version numbers
 TN0012   wxWindows platform, toolkit and library names
 TN0013   how to make a wxGTK distribution
 TN0014   XRC resources format specification
+TN0015   how to add new bitmaps to wxWindows UI elements
 
 
 Version: $Id$

diff --git a/docs/tech/tn0015.txt b/docs/tech/tn0015.txt
new file mode 100644 (file)
index 0000000..cd2debb
--- /dev/null
+++ b/docs/tech/tn0015.txt
@@ -0,0 +1,89 @@
+                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")
+
+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:
+    #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$