docs/doxygen/overviews/bitmap.h

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