interface/icon.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        icon.h
   3 // Purpose:     documentation for wxIcon class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxIcon
  11     @wxheader{icon.h}
  12
  13     An icon is a small rectangular bitmap usually used for denoting a
  14     minimized application. It differs from a wxBitmap in always
  15     having a mask associated with it for transparent drawing. On some platforms,
  16     icons and bitmaps are implemented identically, since there is no real
  17     distinction between
  18     a wxBitmap with a mask and an icon; and there is no specific icon format on
  19     some platforms (X-based applications usually standardize on XPMs for small
  20     bitmaps
  21     and icons). However, some platforms (such as Windows) make the distinction, so
  22     a separate class is provided.
  23
  24     @library{wxcore}
  25     @category{gdi}
  26
  27     @stdobjects
  28     Objects:
  29     wxNullIcon
  30
  31     @seealso
  32     @ref overview_wxbitmapoverview "Bitmap and icon overview", @ref
  33     overview_supportedbitmapformats "supported bitmap file formats", wxDC::DrawIcon, wxCursor
  34 */
  35 class wxIcon : public wxBitmap
  36 {
  37 public:
  38     //@{
  39     /**
  40         Loads an icon from the specified location.
  41
  42         @param bits
  43         Specifies an array of pixel values.
  44
  45         @param width
  46         Specifies the width of the icon.
  47
  48         @param height
  49         Specifies the height of the icon.
  50
  51         @param desiredWidth
  52         Specifies the desired width of the icon. This
  53         parameter only has an effect in Windows (32-bit) where icon resources can
  54         contain
  55         several icons of different sizes.
  56
  57         @param desiredWidth
  58         Specifies the desired height of the icon. This
  59         parameter only has an effect in Windows (32-bit) where icon resources can
  60         contain
  61         several icons of different sizes.
  62
  63         @param depth
  64         Specifies the depth of the icon. If this is omitted, the display depth of the
  65         screen is used.
  66
  67         @param name
  68         This can refer to a resource name under MS Windows, or a filename under MS
  69         Windows and X.
  70         Its meaning is determined by the flags parameter.
  71
  72         @param loc
  73         The object describing the location of the native icon, see
  74         wxIconLocation.
  75
  76         @param type
  77         May be one of the following:
  78
  79
  80         wxBITMAP_TYPE_ICO
  81
  82
  83         Load a Windows icon file.
  84
  85         wxBITMAP_TYPE_ICO_RESOURCE
  86
  87
  88         Load a Windows icon from the resource database.
  89
  90         wxBITMAP_TYPE_GIF
  91
  92
  93         Load a GIF bitmap file.
  94
  95         wxBITMAP_TYPE_XBM
  96
  97
  98         Load an X bitmap file.
  99
 100         wxBITMAP_TYPE_XPM
 101
 102
 103         Load an XPM bitmap file.
 104
 105         The validity of these flags depends on the platform and wxWidgets configuration.
 106         If all possible wxWidgets settings are used, the Windows platform supports ICO
 107         file, ICO resource,
 108         XPM data, and XPM file. Under wxGTK, the available formats are BMP file, XPM
 109         data, XPM file, and PNG file.
 110         Under wxMotif, the available formats are XBM data, XBM file, XPM data, XPM file.
 111
 112         @remarks The first form constructs an icon object with no data; an
 113                    assignment or another member function such as Create
 114                    or LoadFile must be called subsequently.
 115     */
 116     wxIcon();
 117     wxIcon(const wxIcon& icon);
 118     wxIcon(void* data, int type, int width, int height,
 119            int depth = -1);
 120     wxIcon(const char bits[], int width, int height,
 121            int depth = 1);
 122     wxIcon(int width, int height, int depth = -1);
 123     wxIcon(const char* const* bits);
 124     wxIcon(const wxString& name, wxBitmapType type,
 125            int desiredWidth = -1,
 126            int desiredHeight = -1);
 127     wxIcon(const wxIconLocation& loc);
 128     //@}
 129
 130     /**
 131         Destructor.
 132         See @ref overview_refcountdestruct "reference-counted object destruction" for
 133         more info.
 134
 135         If the application omits to delete the icon explicitly, the icon will be
 136         destroyed automatically by wxWidgets when the application exits.
 137
 138         Do not delete an icon that is selected into a memory device context.
 139     */
 140     ~wxIcon();
 141
 142     /**
 143         Copies @e bmp bitmap to this icon. Under MS Windows the bitmap
 144         must have mask colour set.
 145         LoadFile()
 146
 147         Wx::Icon-new( width, height, depth = -1 )
 148         Wx::Icon-new( name, type, desiredWidth = -1, desiredHeight = -1 )
 149         Wx::Icon-newFromBits( bits, width, height, depth = 1 )
 150         Wx::Icon-newFromXPM( data )
 151     */
 152     void CopyFromBitmap(const wxBitmap& bmp);
 153
 154     /**
 155         Gets the colour depth of the icon. A value of 1 indicates a
 156         monochrome icon.
 157     */
 158     int GetDepth();
 159
 160     /**
 161         Gets the height of the icon in pixels.
 162     */
 163     int GetHeight();
 164
 165     /**
 166         Gets the width of the icon in pixels.
 167
 168         @sa GetHeight()
 169     */
 170     int GetWidth();
 171
 172     /**
 173         Returns @true if icon data is present.
 174     */
 175 #define bool IsOk()     /* implementation is private */
 176
 177     /**
 178         Loads an icon from a file or resource.
 179
 180         @param name
 181         Either a filename or a Windows resource name.
 182         The meaning of name is determined by the type parameter.
 183
 184         @param type
 185         One of the following values:
 186
 187
 188         wxBITMAP_TYPE_ICO
 189
 190
 191         Load a Windows icon file.
 192
 193         wxBITMAP_TYPE_ICO_RESOURCE
 194
 195
 196         Load a Windows icon from the resource database.
 197
 198         wxBITMAP_TYPE_GIF
 199
 200
 201         Load a GIF bitmap file.
 202
 203         wxBITMAP_TYPE_XBM
 204
 205
 206         Load an X bitmap file.
 207
 208         wxBITMAP_TYPE_XPM
 209
 210
 211         Load an XPM bitmap file.
 212
 213         The validity of these flags depends on the platform and wxWidgets configuration.
 214
 215         @returns @true if the operation succeeded, @false otherwise.
 216
 217         @sa wxIcon()
 218     */
 219     bool LoadFile(const wxString& name, wxBitmapType type);
 220
 221     /**
 222         Sets the depth member (does not affect the icon data).
 223
 224         @param depth
 225         Icon depth.
 226     */
 227     void SetDepth(int depth);
 228
 229     /**
 230         Sets the height member (does not affect the icon data).
 231
 232         @param height
 233         Icon height in pixels.
 234     */
 235     void SetHeight(int height);
 236
 237     /**
 238         Sets the width member (does not affect the icon data).
 239
 240         @param width
 241         Icon width in pixels.
 242     */
 243     void SetWidth(int width);
 244
 245     /**
 246         Assignment operator, using @ref overview_trefcount "reference counting".
 247
 248         @param icon
 249         Icon to assign.
 250     */
 251     wxIcon operator =(const wxIcon& icon);
 252 };