]>
Commit | Line | Data |
---|---|---|
1 | ///////////////////////////////////////////////////////////////////////////// | |
2 | // Name: bitmap.h | |
3 | // Purpose: topic overview | |
4 | // Author: wxWidgets team | |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows license | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
9 | /** | |
10 | ||
11 | @page overview_bitmap Bitmaps and Icons | |
12 | ||
13 | Classes: | |
14 | @li wxBitmap | |
15 | @li wxBitmapHandler | |
16 | @li wxIcon | |
17 | @li wxCursor | |
18 | ||
19 | The wxBitmap class encapsulates the concept of a platform-dependent bitmap, | |
20 | either monochrome or colour. Platform-specific methods for creating a wxBitmap | |
21 | object from an existing file are catered for, and this is an occasion where | |
22 | conditional compilation will sometimes be required. | |
23 | ||
24 | A bitmap created dynamically or loaded from a file can be selected into a | |
25 | memory device context (instance of wxMemoryDC). This enables the bitmap to be | |
26 | copied to a window or memory device context using wxDC::Blit(), or to be used | |
27 | as a drawing surface. | |
28 | ||
29 | See wxMemoryDC for an example of drawing onto a bitmap. | |
30 | ||
31 | All wxWidgets platforms support XPMs for small bitmaps and icons. You may | |
32 | include the XPM inline as below, since it's C code, or you can load it at | |
33 | run-time. | |
34 | ||
35 | @code | |
36 | #include "mondrian.xpm" | |
37 | @endcode | |
38 | ||
39 | Sometimes you wish to use a .ico resource on Windows, and XPMs on other | |
40 | platforms (for example to take advantage of Windows' support for multiple icon | |
41 | resolutions). | |
42 | ||
43 | A macro, wxICON(), is available which creates an icon using an XPM on the | |
44 | appropriate platform, or an icon resource on Windows: | |
45 | ||
46 | @code | |
47 | wxIcon icon(wxICON(mondrian)); | |
48 | ||
49 | // The above line is equivalent to this: | |
50 | ||
51 | #if defined(__WXGTK__) || defined(__WXMOTIF__) | |
52 | wxIcon icon(mondrian_xpm); | |
53 | #endif | |
54 | ||
55 | #if defined(__WXMSW__) | |
56 | wxIcon icon("mondrian"); | |
57 | #endif | |
58 | @endcode | |
59 | ||
60 | There is also a corresponding wxBITMAP() macro which allows to create the | |
61 | bitmaps in much the same way as wxICON() creates icons. It assumes that bitmaps | |
62 | live in resources under Windows or OS2 and XPM files under all other platforms | |
63 | (for XPMs, the corresponding file must be included before this macro is used, | |
64 | of course, and the name of the bitmap should be the same as the resource name | |
65 | under Windows with @c _xpm suffix). For example: | |
66 | ||
67 | @code | |
68 | // an easy and portable way to create a bitmap | |
69 | wxBitmap bmp(wxBITMAP(bmpname)); | |
70 | ||
71 | // which is roughly equivalent to the following | |
72 | #if defined(__WXMSW__) || defined(__WXPM__) | |
73 | wxBitmap bmp("bmpname", wxBITMAP_TYPE_RESOURCE); | |
74 | #else // Unix | |
75 | wxBitmap bmp(bmpname_xpm, wxBITMAP_TYPE_XPM); | |
76 | #endif | |
77 | @endcode | |
78 | ||
79 | You should always use wxICON() and wxBITMAP() macros because they work for any | |
80 | platform (unlike the code above which doesn't deal with wxMac, wxX11, ...) and | |
81 | are shorter and more clear than versions with many @ifdef_ blocks. Even better, | |
82 | use the same XPMs on all platforms. | |
83 | ||
84 | @li @ref overview_bitmap_supportedformats | |
85 | @li @ref overview_bitmap_handlers | |
86 | ||
87 | ||
88 | <hr> | |
89 | ||
90 | ||
91 | @section overview_bitmap_supportedformats Supported Bitmap File Formats | |
92 | ||
93 | The following lists the formats handled on different platforms. Note that | |
94 | missing or partially-implemented formats are automatically supplemented by | |
95 | using wxImage to load the data, and then converting it to wxBitmap form. Note | |
96 | that using wxImage is the preferred way to load images in wxWidgets, with the | |
97 | exception of resources (XPM-files or native Windows resources). | |
98 | ||
99 | Writing an image format handler for wxImage is also far easier than writing one | |
100 | for wxBitmap, because wxImage has exactly one format on all platforms whereas | |
101 | wxBitmap can store pixel data very differently, depending on colour depths and | |
102 | platform. | |
103 | ||
104 | @subsection overview_bitmap_supportedformats_bmp wxBitmap | |
105 | ||
106 | Under Windows, wxBitmap may load the following formats: | |
107 | ||
108 | @li Windows bitmap resource (wxBITMAP_TYPE_BMP_RESOURCE) | |
109 | @li Windows bitmap file (wxBITMAP_TYPE_BMP) | |
110 | @li XPM data and file (wxBITMAP_TYPE_XPM) | |
111 | @li All formats that are supported by the wxImage class. | |
112 | ||
113 | Under wxGTK, wxBitmap may load the following formats: | |
114 | ||
115 | @li XPM data and file (wxBITMAP_TYPE_XPM) | |
116 | @li All formats that are supported by the wxImage class. | |
117 | ||
118 | Under wxMotif and wxX11, wxBitmap may load the following formats: | |
119 | ||
120 | @li XBM data and file (wxBITMAP_TYPE_XBM) | |
121 | @li XPM data and file (wxBITMAP_TYPE_XPM) | |
122 | @li All formats that are supported by the wxImage class. | |
123 | ||
124 | @subsection overview_bitmap_supportedformats_icon wxIcon | |
125 | ||
126 | Under Windows, wxIcon may load the following formats: | |
127 | ||
128 | @li Windows icon resource (wxBITMAP_TYPE_ICO_RESOURCE) | |
129 | @li Windows icon file (wxBITMAP_TYPE_ICO) | |
130 | @li XPM data and file (wxBITMAP_TYPE_XPM) | |
131 | ||
132 | Under wxGTK, wxIcon may load the following formats: | |
133 | ||
134 | @li XPM data and file (wxBITMAP_TYPE_XPM) | |
135 | @li All formats that are supported by the wxImage class. | |
136 | ||
137 | Under wxMotif and wxX11, wxIcon may load the following formats: | |
138 | ||
139 | @li XBM data and file (wxBITMAP_TYPE_XBM) | |
140 | @li XPM data and file (wxBITMAP_TYPE_XPM) | |
141 | @li All formats that are supported by the wxImage class. | |
142 | ||
143 | @subsection overview_bitmap_supportedformats_cursor wxCursor | |
144 | ||
145 | Under Windows, wxCursor may load the following formats: | |
146 | ||
147 | @li Windows cursor resource (wxBITMAP_TYPE_CUR_RESOURCE) | |
148 | @li Windows cursor file (wxBITMAP_TYPE_CUR) | |
149 | @li Windows icon file (wxBITMAP_TYPE_ICO) | |
150 | @li Windows bitmap file (wxBITMAP_TYPE_BMP) | |
151 | ||
152 | Under wxGTK, wxCursor may load the following formats (in addition to stock | |
153 | cursors): | |
154 | ||
155 | @li None (stock cursors only). | |
156 | ||
157 | Under wxMotif and wxX11, wxCursor may load the following formats: | |
158 | ||
159 | @li XBM data and file (wxBITMAP_TYPE_XBM) | |
160 | ||
161 | ||
162 | @section overview_bitmap_handlers Bitmap Format Handlers | |
163 | ||
164 | To provide extensibility, the functionality for loading and saving bitmap | |
165 | formats is not implemented in the wxBitmap class, but in a number of handler | |
166 | classes, derived from wxBitmapHandler. There is a static list of handlers which | |
167 | wxBitmap examines when a file load/save operation is requested. | |
168 | ||
169 | Some handlers are provided as standard, but if you have special requirements, | |
170 | you may wish to initialise the wxBitmap class with some extra handlers which | |
171 | you write yourself or receive from a third party. | |
172 | ||
173 | To add a handler object to wxBitmap, your application needs to include the | |
174 | header which implements it, and then call the static function | |
175 | wxBitmap::AddHandler(). | |
176 | ||
177 | @note Bitmap handlers are not implemented on all platforms, and new ones rarely | |
178 | need to be implemented since wxImage can be used for loading most formats, as | |
179 | noted earlier. | |
180 | ||
181 | */ | |
182 |