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