| 1 | \section{Bitmaps and icons overview}\label{wxbitmapoverview} |
| 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 |
| 13 | enables the bitmap to be copied to a window or memory device context |
| 14 | using \helpref{wxDC::Blit}{wxdcblit}, or to be used as a drawing surface. |
| 15 | |
| 16 | See \helpref{wxMemoryDC}{wxmemorydc} for an example of drawing onto a bitmap. |
| 17 | |
| 18 | All wxWidgets platforms support XPMs for small bitmaps and icons. |
| 19 | You may include the XPM inline as below, since it's C code, or you |
| 20 | can load it at run-time. |
| 21 | |
| 22 | \begin{verbatim} |
| 23 | #include "mondrian.xpm" |
| 24 | \end{verbatim} |
| 25 | |
| 26 | Sometimes you wish to use a .ico resource on Windows, and XPMs on |
| 27 | other platforms (for example to take advantage of Windows' support for multiple icon resolutions). |
| 28 | A macro, \helpref{wxICON}{wxiconmacro}, is available which creates an icon using an XPM |
| 29 | on the appropriate platform, or an icon resource on Windows. |
| 30 | |
| 31 | \begin{verbatim} |
| 32 | wxIcon icon(wxICON(mondrian)); |
| 33 | |
| 34 | // Equivalent to: |
| 35 | |
| 36 | #if defined(__WXGTK__) || defined(__WXMOTIF__) |
| 37 | wxIcon icon(mondrian_xpm); |
| 38 | #endif |
| 39 | |
| 40 | #if defined(__WXMSW__) |
| 41 | wxIcon icon("mondrian"); |
| 42 | #endif |
| 43 | \end{verbatim} |
| 44 | |
| 45 | There is also a corresponding \helpref{wxBITMAP}{wxbitmapmacro} macro which allows |
| 46 | to create the bitmaps in much the same way as \helpref{wxICON}{wxiconmacro} creates |
| 47 | icons. It assumes that bitmaps live in resources under Windows or OS2 and XPM |
| 48 | files under all other platforms (for XPMs, the corresponding file must be |
| 49 | included before this macro is used, of course, and the name of the bitmap |
| 50 | should be the same as the resource name under Windows with {\tt \_xpm} |
| 51 | suffix). For example: |
| 52 | |
| 53 | \begin{verbatim} |
| 54 | // an easy and portable way to create a bitmap |
| 55 | wxBitmap bmp(wxBITMAP(bmpname)); |
| 56 | |
| 57 | // which is roughly equivalent to the following |
| 58 | #if defined(__WXMSW__) || defined(__WXPM__) |
| 59 | wxBitmap bmp("bmpname", wxBITMAP_TYPE_RESOURCE); |
| 60 | #else // Unix |
| 61 | wxBitmap bmp(bmpname_xpm, wxBITMAP_TYPE_XPM); |
| 62 | #endif |
| 63 | \end{verbatim} |
| 64 | |
| 65 | You should always use wxICON and wxBITMAP macros because they work for any |
| 66 | platform (unlike the code above which doesn't deal with wxMac, wxX11, ...) and |
| 67 | are more short and clear than versions with {\tt \#ifdef}s. Even better, |
| 68 | use the same XPMs on all platforms. |
| 69 | |
| 70 | \subsection{Supported bitmap file formats}\label{supportedbitmapformats} |
| 71 | |
| 72 | The following lists the formats handled on different platforms. Note |
| 73 | that missing or partially-implemented formats are automatically supplemented |
| 74 | by the \helpref{wxImage}{wximage} to load the data, and then converting |
| 75 | it to wxBitmap form. Note that using wxImage is the preferred way to |
| 76 | load images in wxWidgets, with the exception of resources (XPM-files or |
| 77 | native Windows resources). Writing an image format handler for wxImage |
| 78 | is also far easier than writing one for wxBitmap, because wxImage has |
| 79 | exactly one format on all platforms whereas wxBitmap can store pixel data |
| 80 | very differently, depending on colour depths and platform. |
| 81 | |
| 82 | \wxheading{wxBitmap} |
| 83 | |
| 84 | Under Windows, wxBitmap may load the following formats: |
| 85 | |
| 86 | \begin{itemize}\itemsep=0pt |
| 87 | \item Windows bitmap resource (wxBITMAP\_TYPE\_BMP\_RESOURCE) |
| 88 | \item Windows bitmap file (wxBITMAP\_TYPE\_BMP) |
| 89 | \item XPM data and file (wxBITMAP\_TYPE\_XPM) |
| 90 | \item All formats that are supported by the \helpref{wxImage}{wximage} class. |
| 91 | \end{itemize} |
| 92 | |
| 93 | Under wxGTK, wxBitmap may load the following formats: |
| 94 | |
| 95 | \begin{itemize}\itemsep=0pt |
| 96 | \item XPM data and file (wxBITMAP\_TYPE\_XPM) |
| 97 | \item All formats that are supported by the \helpref{wxImage}{wximage} class. |
| 98 | \end{itemize} |
| 99 | |
| 100 | Under wxMotif and wxX11, wxBitmap may load the following formats: |
| 101 | |
| 102 | \begin{itemize}\itemsep=0pt |
| 103 | \item XBM data and file (wxBITMAP\_TYPE\_XBM) |
| 104 | \item XPM data and file (wxBITMAP\_TYPE\_XPM) |
| 105 | \item All formats that are supported by the \helpref{wxImage}{wximage} class. |
| 106 | \end{itemize} |
| 107 | |
| 108 | \wxheading{wxIcon} |
| 109 | |
| 110 | Under Windows, wxIcon may load the following formats: |
| 111 | |
| 112 | \begin{itemize}\itemsep=0pt |
| 113 | \item Windows icon resource (wxBITMAP\_TYPE\_ICO\_RESOURCE) |
| 114 | \item Windows icon file (wxBITMAP\_TYPE\_ICO) |
| 115 | \item XPM data and file (wxBITMAP\_TYPE\_XPM) |
| 116 | \end{itemize} |
| 117 | |
| 118 | Under wxGTK, wxIcon may load the following formats: |
| 119 | |
| 120 | \begin{itemize}\itemsep=0pt |
| 121 | \item XPM data and file (wxBITMAP\_TYPE\_XPM) |
| 122 | \item All formats that are supported by the \helpref{wxImage}{wximage} class. |
| 123 | \end{itemize} |
| 124 | |
| 125 | Under wxMotif and wxX11, wxIcon may load the following formats: |
| 126 | |
| 127 | \begin{itemize}\itemsep=0pt |
| 128 | \item XBM data and file (wxBITMAP\_TYPE\_XBM) |
| 129 | \item XPM data and file (wxBITMAP\_TYPE\_XPM) |
| 130 | \item All formats that are supported by the \helpref{wxImage}{wximage} class. |
| 131 | \end{itemize} |
| 132 | |
| 133 | \wxheading{wxCursor} |
| 134 | |
| 135 | Under Windows, wxCursor may load the following formats: |
| 136 | |
| 137 | \begin{itemize}\itemsep=0pt |
| 138 | \item Windows cursor resource (wxBITMAP\_TYPE\_CUR\_RESOURCE) |
| 139 | \item Windows cursor file (wxBITMAP\_TYPE\_CUR) |
| 140 | \item Windows icon file (wxBITMAP\_TYPE\_ICO) |
| 141 | \item Windows bitmap file (wxBITMAP\_TYPE\_BMP) |
| 142 | \end{itemize} |
| 143 | |
| 144 | Under wxGTK, wxCursor may load the following formats (in additional |
| 145 | to stock cursors): |
| 146 | |
| 147 | \begin{itemize}\itemsep=0pt |
| 148 | \item None (stock cursors only). |
| 149 | \end{itemize} |
| 150 | |
| 151 | Under wxMotif and wxX11, wxCursor may load the following formats: |
| 152 | |
| 153 | \begin{itemize}\itemsep=0pt |
| 154 | \item XBM data and file (wxBITMAP\_TYPE\_XBM) |
| 155 | \end{itemize} |
| 156 | |
| 157 | \subsection{Bitmap format handlers}\label{bitmaphandlers} |
| 158 | |
| 159 | To provide extensibility, the functionality for loading and saving bitmap formats |
| 160 | is not implemented in the wxBitmap class, but in a number of handler classes, |
| 161 | derived from wxBitmapHandler. There is a static list of handlers which wxBitmap |
| 162 | examines when a file load/save operation is requested. Some handlers are provided as standard, but if you |
| 163 | have special requirements, you may wish to initialise the wxBitmap class with |
| 164 | some extra handlers which you write yourself or receive from a third party. |
| 165 | |
| 166 | To add a handler object to wxBitmap, your application needs to include the header which implements it, and |
| 167 | then call the static function \helpref{wxBitmap::AddHandler}{wxbitmapaddhandler}. |
| 168 | |
| 169 | {\bf Note:} bitmap handlers are not implemented on all platforms, and new ones rarely need |
| 170 | to be implemented since wxImage can be used for loading most formats, as noted earlier. |
| 171 | |