interface/wx/icon.h

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