interface/wx/icon.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        icon.h
   3 // Purpose:     interface of wxIcon
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8
   9
  10 /**
  11     In wxIcon context this value means: "use the screen depth".
  12 */
  13 #define wxICON_SCREEN_DEPTH       (-1)
  14
  15
  16 /**
  17     @class wxIcon
  18
  19     An icon is a small rectangular bitmap usually used for denoting a minimized
  20     application.
  21
  22     It differs from a wxBitmap in always having a mask associated with it for
  23     transparent drawing. On some platforms, icons and bitmaps are implemented
  24     identically, since there is no real distinction between a wxBitmap with a
  25     mask and an icon; and there is no specific icon format on some platforms
  26     (X-based applications usually standardize on XPMs for small bitmaps and icons).
  27     However, some platforms (such as Windows) make the distinction, so a
  28     separate class is provided.
  29
  30     @remarks
  31     It is usually desirable to associate a pertinent icon with a frame.
  32     Icons can also be used for other purposes, for example with wxTreeCtrl and wxListCtrl.
  33     Icons have different formats on different platforms therefore separate icons
  34     will usually be created for the different environments.
  35     Platform-specific methods for creating a wxIcon structure are catered for,
  36     and this is an occasion where conditional compilation will probably be required.
  37     Note that a new icon must be created for every time the icon is to be used
  38     for a new window. In Windows, the icon will not be reloaded if it has already
  39     been used.
  40     An icon allocated to a frame will be deleted when the frame is deleted.
  41     For more information please see @ref overview_bitmap.
  42
  43     @library{wxcore}
  44     @category{gdi}
  45
  46     @stdobjects
  47     ::wxNullIcon
  48
  49     @see @ref overview_bitmap, @ref overview_bitmap_supportedformats,
  50          wxDC::DrawIcon, wxCursor
  51 */
  52 class wxIcon : public wxGDIObject
  53 {
  54 public:
  55     /**
  56         Default ctor.
  57
  58         Constructs an icon object with no data; an assignment or another member
  59         function such as LoadFile() must be called subsequently.
  60     */
  61     wxIcon();
  62
  63     /**
  64         Copy ctor.
  65     */
  66     wxIcon(const wxIcon& icon);
  67
  68     /*
  69         Creates an icon from the given data, which can be of arbitrary type.
  70
  71     wxIcon(void* data, int type, int width, int height, int depth = -1);
  72
  73         NOTE: this ctor is not implemented by all ports, is somewhat useless
  74               without further description of the "data" supported formats and
  75               uses 'int type' instead of wxBitmapType, so don't document it.
  76     */
  77
  78     /**
  79         Creates an icon from an array of bits.
  80         You should only use this function for monochrome bitmaps (depth 1) in
  81         portable programs: in this case the bits parameter should contain an XBM image.
  82
  83         For other bit depths, the behaviour is platform dependent: under Windows,
  84         the data is passed without any changes to the underlying CreateBitmap() API.
  85         Under other platforms, only monochrome bitmaps may be created using this
  86         constructor and wxImage should be used for creating colour bitmaps from
  87         static data.
  88
  89         @param bits
  90             Specifies an array of pixel values.
  91         @param width
  92             The width of the image.
  93         @param height
  94             The height of the image.
  95
  96         @beginWxPerlOnly
  97         In wxPerl use Wx::Icon->newBits(bits, width, height, depth = -1);
  98         @endWxPerlOnly
  99
 100         @onlyfor{wxmsw,wxosx}
 101     */
 102     wxIcon(const char bits[], int width, int height);
 103
 104     /**
 105         Creates a bitmap from XPM data.
 106         To use this constructor, you must first include an XPM file.
 107         For example, assuming that the file mybitmap.xpm contains an XPM array
 108         of character pointers called @e mybitmap:
 109
 110         @code
 111         #include "mybitmap.xpm"
 112         ...
 113         wxIcon *icon = new wxIcon(mybitmap);
 114         @endcode
 115
 116         A macro, wxICON, is available which creates an icon using an XPM on
 117         the appropriate platform, or an icon resource on Windows.
 118
 119         @code
 120         wxIcon icon(wxICON(sample));
 121
 122         // Equivalent to:
 123         #if defined(__WXGTK__) || defined(__WXMOTIF__)
 124         wxIcon icon(sample_xpm);
 125         #endif
 126
 127         #if defined(__WXMSW__)
 128         wxIcon icon("sample");
 129         #endif
 130         @endcode
 131
 132         @beginWxPerlOnly
 133         In wxPerl use Wx::Icon->newFromXPM(data).
 134         @endWxPerlOnly
 135     */
 136     wxIcon(const char* const* bits);
 137
 138     /**
 139         Loads an icon from a file or resource.
 140
 141         @param name
 142             This can refer to a resource name or a filename under MS Windows and X.
 143             Its meaning is determined by the @a type parameter.
 144         @param type
 145             May be one of the ::wxBitmapType values and indicates which type of
 146             bitmap should be loaded. See the note in the class detailed description.
 147             Note that the wxICON_DEFAULT_TYPE constant has different value under
 148             different wxWidgets ports. See the icon.h header for the value it takes
 149             for a specific port.
 150         @param desiredWidth
 151             Specifies the desired width of the icon. This parameter only has
 152             an effect in Windows where icon resources can contain several icons
 153             of different sizes.
 154         @param desiredHeight
 155             Specifies the desired height of the icon. This parameter only has
 156             an effect in Windows where icon resources can contain several icons
 157             of different sizes.
 158
 159         @see LoadFile()
 160     */
 161     wxIcon(const wxString& name, wxBitmapType type = wxICON_DEFAULT_TYPE,
 162            int desiredWidth = -1, int desiredHeight = -1);
 163
 164     /**
 165         Loads an icon from the specified location.
 166     */
 167     wxIcon(const wxIconLocation& loc);
 168
 169     /**
 170         Destructor.
 171         See @ref overview_refcount_destruct for more info.
 172
 173         If the application omits to delete the icon explicitly, the icon will be
 174         destroyed automatically by wxWidgets when the application exits.
 175
 176         @warning
 177         Do not delete an icon that is selected into a memory device context.
 178     */
 179     virtual ~wxIcon();
 180
 181     /**
 182         Attach a Windows icon handle.
 183
 184         This wxMSW-specific method allows to assign a native Windows @c HICON
 185         (which must be castes to @c WXHICON opaque handle type) to wxIcon.
 186         Notice that this means that the @c HICON will be destroyed by wxIcon
 187         when it is destroyed.
 188
 189         @return @true if successful.
 190
 191         @onlyfor{wxmsw}
 192
 193         @since 2.9.5
 194     */
 195     bool CreateFromHICON(WXHICON icon);
 196
 197     /**
 198         Returns disabled (dimmed) version of the icon.
 199
 200         This method is available in wxIcon only under wxMSW, other ports only
 201         have it in wxBitmap. You can always use wxImage::ConvertToDisabled()
 202         and create the icon from wxImage manually however.
 203
 204         @onlyfor{wxmsw}
 205
 206         @since 2.9.0
 207     */
 208     wxIcon ConvertToDisabled(unsigned char brightness = 255) const;
 209
 210     /**
 211         Copies @a bmp bitmap to this icon.
 212         Under MS Windows the bitmap must have mask colour set.
 213
 214         @see LoadFile()
 215     */
 216     void CopyFromBitmap(const wxBitmap& bmp);
 217
 218     /**
 219         Gets the colour depth of the icon.
 220         A value of 1 indicates a monochrome icon.
 221     */
 222     int GetDepth() const;
 223
 224     /**
 225         Gets the height of the icon in pixels.
 226
 227         @see GetWidth()
 228     */
 229     int GetHeight() const;
 230
 231     /**
 232         Gets the width of the icon in pixels.
 233
 234         @see GetHeight()
 235     */
 236     int GetWidth() const;
 237
 238     /**
 239         Returns @true if icon data is present.
 240     */
 241     virtual bool IsOk() const;
 242
 243     /**
 244         Loads an icon from a file or resource.
 245
 246         @param name
 247             Either a filename or a Windows resource name.
 248             The meaning of name is determined by the @a type parameter.
 249         @param type
 250             One of the ::wxBitmapType values; see the note in the class
 251             detailed description.
 252             Note that the wxICON_DEFAULT_TYPE constant has different value under
 253             different wxWidgets ports. See the icon.h header for the value it takes
 254             for a specific port.
 255         @param desiredWidth
 256             Specifies the desired width of the icon. This parameter only has
 257             an effect in Windows where icon resources can contain several icons
 258             of different sizes.
 259         @param desiredHeight
 260             Specifies the desired height of the icon. This parameter only has
 261             an effect in Windows where icon resources can contain several icons
 262             of different sizes.
 263
 264         @return @true if the operation succeeded, @false otherwise.
 265     */
 266     bool LoadFile(const wxString& name, wxBitmapType type = wxICON_DEFAULT_TYPE,
 267                   int desiredWidth = -1, int desiredHeight = -1);
 268
 269     /**
 270         Sets the depth member (does not affect the icon data).
 271
 272         @param depth
 273             Icon depth.
 274     */
 275     void SetDepth(int depth);
 276
 277     /**
 278         Sets the height member (does not affect the icon data).
 279
 280         @param height
 281             Icon height in pixels.
 282     */
 283     void SetHeight(int height);
 284
 285     /**
 286         Sets the width member (does not affect the icon data).
 287
 288         @param width
 289             Icon width in pixels.
 290     */
 291     void SetWidth(int width);
 292
 293     /**
 294         Assignment operator, using @ref overview_refcount.
 295
 296         @param icon
 297             Icon to assign.
 298     */
 299     wxIcon& operator=(const wxIcon& icon);
 300 };
 301
 302 /**
 303     An empty wxIcon.
 304 */
 305 wxIcon wxNullIcon;
 306
 307