docs/latex/wx/tbitmap.tex

   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.  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
  17 version of the graphic which appears on the main window.
  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
  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.
  26
  27 \begin{verbatim}
  28 #if defined(__WXGTK__) || defined(__WXMOTIF__)
  29 #include "mondrian.xpm"
  30 #endif
  31 \end{verbatim}
  32
  33 A macro, wxICON, is available which creates an icon using an XPM
  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);
  43 #endif
  44
  45 #if defined(__WXMSW__)
  46 wxIcon icon("mondrian");
  47 #endif
  48 \end{verbatim}
  49
  50 \subsection{Supported bitmap file formats}\label{supportedbitmapformats}
  51
  52 The following lists the formats handled on different platforms. Note
  53 that missing or partially-implemented formats can be supplemented
  54 by using \helpref{wxImage}{wximage} to load the data, and then converting
  55 it to wxBitmap form.
  56
  57 \wxheading{wxBitmap}
  58
  59 Under Windows, wxBitmap may load the following formats:
  60
  61 \begin{itemize}\itemsep=0pt
  62 \item Windows bitmap resource (wxBITMAP\_TYPE\_BMP\_RESOURCE)
  63 \item Windows bitmap file (wxBITMAP\_TYPE\_BMP)
  64 \item PNG file (wxBITMAP\_TYPE\_PNG). Currently 4-bit (16-colour) PNG files do not load properly.
  65 \item XPM data and file (wxBITMAP\_TYPE\_XPM)
  66 \end{itemize}
  67
  68 Under wxGTK, wxBitmap may load the following formats:
  69
  70 \begin{itemize}\itemsep=0pt
  71 \item Windows bitmap file (wxBITMAP\_TYPE\_BMP)
  72 \item PNG (wxBITMAP\_TYPE\_PNG).
  73 \item XPM data and file (wxBITMAP\_TYPE\_XPM)
  74 \end{itemize}
  75
  76 Under wxMotif, wxBitmap may load the following formats:
  77
  78 \begin{itemize}\itemsep=0pt
  79 %\item Windows bitmap file (wxBITMAP\_TYPE\_BMP)
  80 %\item PNG (wxBITMAP\_TYPE\_PNG).
  81 \item XBM data and file (wxBITMAP\_TYPE\_XBM)
  82 \item XPM data and file (wxBITMAP\_TYPE\_XPM)
  83 \end{itemize}
  84
  85 \wxheading{wxIcon}
  86
  87 Under Windows, wxIcon may load the following formats:
  88
  89 \begin{itemize}\itemsep=0pt
  90 \item Windows icon resource (wxBITMAP\_TYPE\_ICO\_RESOURCE)
  91 \item Windows icon file (wxBITMAP\_TYPE\_ICO)
  92 \item XPM data and file (wxBITMAP\_TYPE\_XPM)
  93 \end{itemize}
  94
  95 Under wxGTK, wxIcon may load the following formats:
  96
  97 \begin{itemize}\itemsep=0pt
  98 \item PNG (wxBITMAP\_TYPE\_PNG).
  99 \item XPM data and file (wxBITMAP\_TYPE\_XPM)
 100 \end{itemize}
 101
 102 Under wxMotif, wxIcon may load the following formats:
 103
 104 \begin{itemize}\itemsep=0pt
 105 %\item Windows bitmap file (wxBITMAP\_TYPE\_BMP)
 106 %\item PNG (wxBITMAP\_TYPE\_PNG).
 107 \item XBM data and file (wxBITMAP\_TYPE\_XBM)
 108 \item XPM data and file (wxBITMAP\_TYPE\_XPM)
 109 \end{itemize}
 110
 111 \wxheading{wxCursor}
 112
 113 Under Windows, wxCursor may load the following formats:
 114
 115 \begin{itemize}\itemsep=0pt
 116 \item Windows cursor resource (wxBITMAP\_TYPE\_CUR\_RESOURCE)
 117 \item Windows cursor file (wxBITMAP\_TYPE\_CUR)
 118 \item Windows icon file (wxBITMAP\_TYPE\_ICO)
 119 \item Windows bitmap file (wxBITMAP\_TYPE\_BMP)
 120 \end{itemize}
 121
 122 Under wxGTK, wxCursor may load the following formats (in additional
 123 to stock cursors):
 124
 125 \begin{itemize}\itemsep=0pt
 126 \item None (stock cursors only).
 127 \end{itemize}
 128
 129 Under wxMotif, wxCursor may load the following formats:
 130
 131 \begin{itemize}\itemsep=0pt
 132 \item XBM data and file (wxBITMAP\_TYPE\_XBM)
 133 \end{itemize}
 134
 135 \subsection{Bitmap format handlers}\label{bitmaphandlers}
 136
 137 To provide extensibility, the functionality for loading and saving bitmap formats
 138 is not implemented in the wxBitmap class, but in a number of handler classes,
 139 derived from wxBitmapHandler. There is a static list of handlers which wxBitmap
 140 examines when a file load/save operation is requested. Some handlers are provided as standard, but if you
 141 have special requirements, you may wish to initialise the wxBitmap class with
 142 some extra handlers which you write yourself or receive from a third party.
 143
 144 To add a handler object to wxBitmap, your application needs to include the header which implements it, and
 145 then call the static function \helpref{wxBitmap::AddHandler}{wxbitmapaddhandler}. For example:
 146
 147 {\small
 148 \begin{verbatim}
 149   #include <wx/pnghand.h>
 150   #include <wx/xpmhand.h>
 151   ...
 152   // Initialisation
 153   wxBitmap::AddHandler(new wxPNGFileHandler);
 154   wxBitmap::AddHandler(new wxXPMFileHandler);
 155   wxBitmap::AddHandler(new wxXPMDataHandler);
 156   ...
 157 \end{verbatim}
 158 }
 159
 160 Assuming the handlers have been written correctly, you should now be able to load and save PNG files
 161 and XPM files using the usual wxBitmap API.
 162
 163 {\bf Note:} bitmap handlers are not implemented on all platforms. Currently, the above is only necessary on
 164 Windows, to save the extra overhead of formats that may not be necessary (if you don't use them, they
 165 are not linked into the executable). Unix platforms have PNG and XPM capability built-in (where supported).
 166