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