docs/latex/wx/tbitmap.tex

   1 \section{Bitmaps 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 canvas 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 canvas.
  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 in X and in Windows 3. The alternative is to use the string
  23 version of the bitmap constructor, which loads a file under X and a
  24 resource under Windows 3, but has the disadvantage of requiring the
  25 X icon file to be available at run-time.
  26
  27 \begin{verbatim}
  28 #ifdef wx_x
  29 #include "aiai.xbm"
  30 #endif
  31 #ifdef wx_msw
  32   wxIcon *icon = new wxBitmap("aiai");
  33 #endif
  34 #ifdef wx_x
  35   wxIcon *icon = new wxBitmap(aiai_bits, aiai_width, aiai_height);
  36 #endif
  37 \end{verbatim}
  38
  39 \subsection{Loading bitmaps: further information}
  40
  41 There is provision for a number of bitmap
  42 formats via the standard wxBitmap class. These facilities can
  43 be enabled or disabled using settings in wx\_setup.h.
  44
  45 XPM colour pixmaps may be loaded and saved under Windows and X, with
  46 some restrictions imposed by the lack of colourmap facility when
  47 using XPM files. The user may elect to use XPM files as a cross-platform
  48 stabdard, or translate between XPM and BMP files using a suitable
  49 utility.
  50
  51 Also, under Windows, DIBs (device independent bitmaps with extension BMP)
  52 may be dynamically loaded and saved. Under X, GIF and BMP files may be
  53 loaded but not saved.
  54
  55 \subsection{Bitmap format handlers}
  56
  57 To provide extensibility, the functionality for loading and saving bitmap formats
  58 is not implemented in the wxBitmap class, but in a number of handler classes,
  59 derived from wxBitmapHandler. There is a static list of handlers which wxBitmap
  60 examines when a file load/save operation is requested. Some handlers are provided as standard, but if you
  61 have special requirements, you may wish to initialise the wxBitmap class with
  62 some extra handlers which you write yourself or receive from a third party.
  63
  64 To add a handler object to wxBitmap, your application needs to include the header which implements it, and
  65 then call the static function \helpref{wxBitmap::AddHandler}{wxbitmapaddhandler}. For example:
  66
  67 {\small
  68 \begin{verbatim}
  69   #include "JPEGBitmapHandler.h"
  70   ...
  71   // Initialisation
  72   wxBitmap::AddHandler(new wxJPEGBitmapHandler);
  73   ...
  74 \end{verbatim}
  75 }
  76
  77 Assuming wxJPEGBitmapHandler has been written correctly, you should now be able to load and save JPEG files
  78 using the usual wxBitmap API.
  79
  80 To see how bitmap handlers are implemented, please look at the files {\tt bitmap.h} and {\tt bitmap.cpp}.
  81
  82 \subsection{wxIcon overview}\label{wxiconoverview}
  83
  84 TODO.
  85