From ea67ba0fe2e5c48a6b2ac7df83c2de4642a1cda9 Mon Sep 17 00:00:00 2001 From: =?utf8?q?V=C3=A1clav=20Slav=C3=ADk?= Date: Sun, 7 Apr 2002 16:05:11 +0000 Subject: [PATCH] added wxArtProvider technote git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@14985 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/tech/index.txt | 1 + docs/tech/tn0015.txt | 89 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 90 insertions(+) create mode 100644 docs/tech/tn0015.txt diff --git a/docs/tech/index.txt b/docs/tech/index.txt index 7aabf09ee3..87d5f86239 100644 --- 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 index 0000000000..cd2debbd7a --- /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$ -- 2.45.2