]>
Commit | Line | Data |
---|---|---|
2fd284a4 | 1 | \section{Bitmaps and icons overview}\label{wxbitmapoverview} |
a660d684 KB |
2 | |
3 | Classes: \helpref{wxBitmap}{wxbitmap}, \helpref{wxBitmapHandler}{wxbitmaphandler}, \helpref{wxIcon}{wxicon}, \helpref{wxCursor}{wxcursor}. | |
4 | ||
5 | The wxBitmap class encapsulates the concept of a platform-dependent bitmap, | |
6 | either monochrome or colour. Platform-specific methods for creating a | |
7 | wxBitmap object from an existing file are catered for, and | |
8 | this is an occasion where conditional compilation will sometimes be | |
9 | required. | |
10 | ||
11 | A bitmap created dynamically or loaded from a file can be selected | |
12 | into a memory device context (instance of \helpref{wxMemoryDC}{wxmemorydc}). This | |
fe604ccd | 13 | enables the bitmap to be copied to a window or memory device context |
a660d684 KB |
14 | using \helpref{wxDC::Blit}{wxdcblit}, or to be used as a drawing surface. The {\bf |
15 | wxToolBarSimple} class is implemented using bitmaps, and the toolbar demo | |
16 | shows one of the toolbar bitmaps being used for drawing a miniature | |
fe604ccd | 17 | version of the graphic which appears on the main window. |
a660d684 KB |
18 | |
19 | See \helpref{wxMemoryDC}{wxmemorydc} for an example of drawing onto a bitmap. | |
20 | ||
21 | The following shows the conditional compilation required to load a | |
2fd284a4 JS |
22 | bitmap under Unix and in Windows. The alternative is to use the string |
23 | version of the bitmap constructor, which loads a file under Unix and a | |
24 | resource or file under Windows, but has the disadvantage of requiring the | |
25 | XPM icon file to be available at run-time. | |
a660d684 KB |
26 | |
27 | \begin{verbatim} | |
2fd284a4 JS |
28 | #if defined(__WXGTK__) || defined(__WXMOTIF__) |
29 | #include "mondrian.xpm" | |
a660d684 | 30 | #endif |
2fd284a4 JS |
31 | \end{verbatim} |
32 | ||
0c5d3e1c | 33 | A macro, \helpref{wxICON}{wxicon}, is available which creates an icon using an XPM |
2fd284a4 JS |
34 | on the appropriate platform, or an icon resource on Windows. |
35 | ||
36 | \begin{verbatim} | |
37 | wxIcon icon(wxICON(mondrian)); | |
38 | ||
39 | // Equivalent to: | |
40 | ||
41 | #if defined(__WXGTK__) || defined(__WXMOTIF__) | |
42 | wxIcon icon(mondrian_xpm); | |
a660d684 | 43 | #endif |
2fd284a4 JS |
44 | |
45 | #if defined(__WXMSW__) | |
46 | wxIcon icon("mondrian"); | |
a660d684 KB |
47 | #endif |
48 | \end{verbatim} | |
49 | ||
0c5d3e1c VZ |
50 | There is also a corresponding \helpref{wxBITMAP}{wxbitmap} macro which allows |
51 | to create the bitmaps in much the same way as \helpref{wxICON}{wxicon} creates | |
52 | icons. It assumes that bitmaps live in resources under Windows or OS2 and XPM | |
53 | files under all other platforms (for XPMs, the corresponding file must be | |
54 | included before this macro is used, of course, and the name of the bitmap | |
55 | should be the same as the resource name under Windows with {\tt \_xpm} | |
56 | suffix). For example: | |
57 | ||
58 | \begin{verbatim} | |
59 | // an easy and portable way to create a bitmap | |
60 | wxBitmap bmp(wxBITMAP(bmpname)); | |
61 | ||
62 | // which is roughly equivalent to the following | |
63 | #if defined(__WXMSW__) || defined(__WXPM__) | |
64 | wxBitmap bmp("bmpname", wxBITMAP_TYPE_RESOURCE); | |
65 | #else // Unix | |
66 | wxBitmap bmp(bmpname_xpm, wxBITMAP_TYPE_XPM); | |
67 | #endif | |
68 | \end{verbatim} | |
69 | ||
70 | You should always use wxICON and wxBITMAP macros because they work for any | |
71 | platform (unlike the code above which doesn't deal with wxMac, wxBe, ...) and | |
72 | are more short and clear than versions with {\tt #ifdef}s. | |
73 | ||
2fd284a4 JS |
74 | \subsection{Supported bitmap file formats}\label{supportedbitmapformats} |
75 | ||
76 | The following lists the formats handled on different platforms. Note | |
77 | that missing or partially-implemented formats can be supplemented | |
78 | by using \helpref{wxImage}{wximage} to load the data, and then converting | |
79 | it to wxBitmap form. | |
80 | ||
81 | \wxheading{wxBitmap} | |
82 | ||
83 | Under Windows, wxBitmap may load the following formats: | |
84 | ||
85 | \begin{itemize}\itemsep=0pt | |
86 | \item Windows bitmap resource (wxBITMAP\_TYPE\_BMP\_RESOURCE) | |
87 | \item Windows bitmap file (wxBITMAP\_TYPE\_BMP) | |
88 | \item PNG file (wxBITMAP\_TYPE\_PNG). Currently 4-bit (16-colour) PNG files do not load properly. | |
89 | \item XPM data and file (wxBITMAP\_TYPE\_XPM) | |
90 | \end{itemize} | |
91 | ||
92 | Under wxGTK, wxBitmap may load the following formats: | |
93 | ||
94 | \begin{itemize}\itemsep=0pt | |
95 | \item Windows bitmap file (wxBITMAP\_TYPE\_BMP) | |
96 | \item PNG (wxBITMAP\_TYPE\_PNG). | |
97 | \item XPM data and file (wxBITMAP\_TYPE\_XPM) | |
98 | \end{itemize} | |
99 | ||
100 | Under wxMotif, wxBitmap may load the following formats: | |
a660d684 | 101 | |
2fd284a4 JS |
102 | \begin{itemize}\itemsep=0pt |
103 | %\item Windows bitmap file (wxBITMAP\_TYPE\_BMP) | |
104 | %\item PNG (wxBITMAP\_TYPE\_PNG). | |
105 | \item XBM data and file (wxBITMAP\_TYPE\_XBM) | |
106 | \item XPM data and file (wxBITMAP\_TYPE\_XPM) | |
107 | \end{itemize} | |
a660d684 | 108 | |
2fd284a4 | 109 | \wxheading{wxIcon} |
a660d684 | 110 | |
2fd284a4 | 111 | Under Windows, wxIcon may load the following formats: |
a660d684 | 112 | |
2fd284a4 JS |
113 | \begin{itemize}\itemsep=0pt |
114 | \item Windows icon resource (wxBITMAP\_TYPE\_ICO\_RESOURCE) | |
115 | \item Windows icon file (wxBITMAP\_TYPE\_ICO) | |
116 | \item XPM data and file (wxBITMAP\_TYPE\_XPM) | |
117 | \end{itemize} | |
118 | ||
119 | Under wxGTK, wxIcon may load the following formats: | |
120 | ||
121 | \begin{itemize}\itemsep=0pt | |
122 | \item PNG (wxBITMAP\_TYPE\_PNG). | |
123 | \item XPM data and file (wxBITMAP\_TYPE\_XPM) | |
124 | \end{itemize} | |
125 | ||
126 | Under wxMotif, wxIcon may load the following formats: | |
127 | ||
128 | \begin{itemize}\itemsep=0pt | |
129 | %\item Windows bitmap file (wxBITMAP\_TYPE\_BMP) | |
130 | %\item PNG (wxBITMAP\_TYPE\_PNG). | |
131 | \item XBM data and file (wxBITMAP\_TYPE\_XBM) | |
132 | \item XPM data and file (wxBITMAP\_TYPE\_XPM) | |
133 | \end{itemize} | |
134 | ||
135 | \wxheading{wxCursor} | |
136 | ||
137 | Under Windows, wxCursor may load the following formats: | |
138 | ||
139 | \begin{itemize}\itemsep=0pt | |
140 | \item Windows cursor resource (wxBITMAP\_TYPE\_CUR\_RESOURCE) | |
141 | \item Windows cursor file (wxBITMAP\_TYPE\_CUR) | |
142 | \item Windows icon file (wxBITMAP\_TYPE\_ICO) | |
143 | \item Windows bitmap file (wxBITMAP\_TYPE\_BMP) | |
144 | \end{itemize} | |
145 | ||
146 | Under wxGTK, wxCursor may load the following formats (in additional | |
147 | to stock cursors): | |
148 | ||
149 | \begin{itemize}\itemsep=0pt | |
150 | \item None (stock cursors only). | |
151 | \end{itemize} | |
152 | ||
153 | Under wxMotif, wxCursor may load the following formats: | |
154 | ||
155 | \begin{itemize}\itemsep=0pt | |
156 | \item XBM data and file (wxBITMAP\_TYPE\_XBM) | |
157 | \end{itemize} | |
158 | ||
159 | \subsection{Bitmap format handlers}\label{bitmaphandlers} | |
a660d684 KB |
160 | |
161 | To provide extensibility, the functionality for loading and saving bitmap formats | |
162 | is not implemented in the wxBitmap class, but in a number of handler classes, | |
163 | derived from wxBitmapHandler. There is a static list of handlers which wxBitmap | |
164 | examines when a file load/save operation is requested. Some handlers are provided as standard, but if you | |
165 | have special requirements, you may wish to initialise the wxBitmap class with | |
166 | some extra handlers which you write yourself or receive from a third party. | |
167 | ||
168 | To add a handler object to wxBitmap, your application needs to include the header which implements it, and | |
169 | then call the static function \helpref{wxBitmap::AddHandler}{wxbitmapaddhandler}. For example: | |
170 | ||
171 | {\small | |
172 | \begin{verbatim} | |
2fd284a4 JS |
173 | #include <wx/pnghand.h> |
174 | #include <wx/xpmhand.h> | |
a660d684 KB |
175 | ... |
176 | // Initialisation | |
2fd284a4 JS |
177 | wxBitmap::AddHandler(new wxPNGFileHandler); |
178 | wxBitmap::AddHandler(new wxXPMFileHandler); | |
179 | wxBitmap::AddHandler(new wxXPMDataHandler); | |
a660d684 KB |
180 | ... |
181 | \end{verbatim} | |
182 | } | |
183 | ||
2fd284a4 JS |
184 | Assuming the handlers have been written correctly, you should now be able to load and save PNG files |
185 | and XPM files using the usual wxBitmap API. | |
a660d684 | 186 | |
2fd284a4 JS |
187 | {\bf Note:} bitmap handlers are not implemented on all platforms. Currently, the above is only necessary on |
188 | Windows, to save the extra overhead of formats that may not be necessary (if you don't use them, they | |
189 | are not linked into the executable). Unix platforms have PNG and XPM capability built-in (where supported). | |
a660d684 | 190 |