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         @param width
  45             Specifies the width of the icon.
  46         @param height
  47             Specifies the height of the icon.
  48         @param desiredWidth
  49             Specifies the desired width of the icon. This
  50             parameter only has an effect in Windows (32-bit) where icon resources can
  51         contain
  52             several icons of different sizes.
  53         @param desiredWidth
  54             Specifies the desired height of the icon. This
  55             parameter only has an effect in Windows (32-bit) where icon resources can
  56         contain
  57             several icons of different sizes.
  58         @param depth
  59             Specifies the depth of the icon. If this is omitted, the display depth of
  60         the
  61             screen is used.
  62         @param name
  63             This can refer to a resource name under MS Windows, or a filename under MS
  64         Windows and X.
  65             Its meaning is determined by the flags parameter.
  66         @param loc
  67             The object describing the location of the native icon, see
  68             wxIconLocation.
  69         @param type
  70             May be one of the following:
  71
  72
  73
  74
  75
  76
  77
  78             wxBITMAP_TYPE_ICO
  79
  80
  81
  82
  83             Load a Windows icon file.
  84
  85
  86
  87
  88
  89             wxBITMAP_TYPE_ICO_RESOURCE
  90
  91
  92
  93
  94             Load a Windows icon from the resource database.
  95
  96
  97
  98
  99
 100             wxBITMAP_TYPE_GIF
 101
 102
 103
 104
 105             Load a GIF bitmap file.
 106
 107
 108
 109
 110
 111             wxBITMAP_TYPE_XBM
 112
 113
 114
 115
 116             Load an X bitmap file.
 117
 118
 119
 120
 121
 122             wxBITMAP_TYPE_XPM
 123
 124
 125
 126
 127             Load an XPM bitmap file.
 128
 129
 130
 131
 132
 133             The validity of these flags depends on the platform and wxWidgets
 134         configuration.
 135             If all possible wxWidgets settings are used, the Windows platform supports
 136         ICO file, ICO resource,
 137             XPM data, and XPM file. Under wxGTK, the available formats are BMP file,
 138         XPM data, XPM file, and PNG file.
 139             Under wxMotif, the available formats are XBM data, XBM file, XPM data, XPM
 140         file.
 141
 142         @remarks The first form constructs an icon object with no data; an
 143                  assignment or another member function such as Create or
 144                  LoadFile must be called subsequently.
 145     */
 146     wxIcon();
 147     wxIcon(const wxIcon& icon);
 148     wxIcon(void* data, int type, int width, int height,
 149            int depth = -1);
 150     wxIcon(const char bits[], int width, int height,
 151            int depth = 1);
 152     wxIcon(int width, int height, int depth = -1);
 153     wxIcon(const char* const* bits);
 154     wxIcon(const wxString& name, wxBitmapType type,
 155            int desiredWidth = -1,
 156            int desiredHeight = -1);
 157     wxIcon(const wxIconLocation& loc);
 158     //@}
 159
 160     /**
 161         Destructor.
 162         See @ref overview_refcountdestruct "reference-counted object destruction" for
 163         more info.
 164         If the application omits to delete the icon explicitly, the icon will be
 165         destroyed automatically by wxWidgets when the application exits.
 166         Do not delete an icon that is selected into a memory device context.
 167     */
 168     ~wxIcon();
 169
 170     /**
 171         Copies @a bmp bitmap to this icon. Under MS Windows the bitmap
 172         must have mask colour set.
 173
 174         LoadFile()
 175
 176         Wx::Icon-new( width, height, depth = -1 )
 177         Wx::Icon-new( name, type, desiredWidth = -1, desiredHeight = -1 )
 178         Wx::Icon-newFromBits( bits, width, height, depth = 1 )
 179         Wx::Icon-newFromXPM( data )
 180     */
 181     void CopyFromBitmap(const wxBitmap& bmp);
 182
 183     /**
 184         Gets the colour depth of the icon. A value of 1 indicates a
 185         monochrome icon.
 186     */
 187     int GetDepth() const;
 188
 189     /**
 190         Gets the height of the icon in pixels.
 191     */
 192     int GetHeight() const;
 193
 194     /**
 195         Gets the width of the icon in pixels.
 196
 197         @see GetHeight()
 198     */
 199     int GetWidth() const;
 200
 201     /**
 202         Returns @true if icon data is present.
 203     */
 204     bool IsOk() const;
 205
 206     /**
 207         Loads an icon from a file or resource.
 208
 209         @param name
 210             Either a filename or a Windows resource name.
 211             The meaning of name is determined by the type parameter.
 212         @param type
 213             One of the following values:
 214
 215
 216
 217
 218
 219
 220
 221             wxBITMAP_TYPE_ICO
 222
 223
 224
 225
 226             Load a Windows icon file.
 227
 228
 229
 230
 231
 232             wxBITMAP_TYPE_ICO_RESOURCE
 233
 234
 235
 236
 237             Load a Windows icon from the resource database.
 238
 239
 240
 241
 242
 243             wxBITMAP_TYPE_GIF
 244
 245
 246
 247
 248             Load a GIF bitmap file.
 249
 250
 251
 252
 253
 254             wxBITMAP_TYPE_XBM
 255
 256
 257
 258
 259             Load an X bitmap file.
 260
 261
 262
 263
 264
 265             wxBITMAP_TYPE_XPM
 266
 267
 268
 269
 270             Load an XPM bitmap file.
 271
 272
 273
 274
 275
 276             The validity of these flags depends on the platform and wxWidgets
 277         configuration.
 278
 279         @returns @true if the operation succeeded, @false otherwise.
 280
 281         @see wxIcon()
 282     */
 283     bool LoadFile(const wxString& name, wxBitmapType type);
 284
 285     /**
 286         Sets the depth member (does not affect the icon data).
 287
 288         @param depth
 289             Icon depth.
 290     */
 291     void SetDepth(int depth);
 292
 293     /**
 294         Sets the height member (does not affect the icon data).
 295
 296         @param height
 297             Icon height in pixels.
 298     */
 299     void SetHeight(int height);
 300
 301     /**
 302         Sets the width member (does not affect the icon data).
 303
 304         @param width
 305             Icon width in pixels.
 306     */
 307     void SetWidth(int width);
 308
 309     /**
 310         Assignment operator, using @ref overview_trefcount "reference counting".
 311
 312         @param icon
 313             Icon to assign.
 314     */
 315     wxIcon operator =(const wxIcon& icon);
 316 };