X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ae3c17b4013e80b99976c750c19fca47729517f6..95b4a59e67af301bb6ff061055ac5a9a09b96d6c:/interface/wx/icon.h?ds=sidebyside diff --git a/interface/wx/icon.h b/interface/wx/icon.h index acfca50218..c81d0d4188 100644 --- a/interface/wx/icon.h +++ b/interface/wx/icon.h @@ -6,20 +6,40 @@ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// + + +/** + In wxIcon context this value means: "use the screen depth". +*/ +#define wxICON_SCREEN_DEPTH (-1) + + /** @class wxIcon - @wxheader{icon.h} - - An icon is a small rectangular bitmap usually used for denoting a - minimized application. It differs from a wxBitmap in always - having a mask associated with it for transparent drawing. On some platforms, - icons and bitmaps are implemented identically, since there is no real - distinction between - a wxBitmap with a mask and an icon; and there is no specific icon format on - some platforms (X-based applications usually standardize on XPMs for small - bitmaps - and icons). However, some platforms (such as Windows) make the distinction, so - a separate class is provided. + + An icon is a small rectangular bitmap usually used for denoting a minimized + application. + + It differs from a wxBitmap in always having a mask associated with it for + transparent drawing. On some platforms, icons and bitmaps are implemented + identically, since there is no real distinction between a wxBitmap with a + mask and an icon; and there is no specific icon format on some platforms + (X-based applications usually standardize on XPMs for small bitmaps and icons). + However, some platforms (such as Windows) make the distinction, so a + separate class is provided. + + @remarks + It is usually desirable to associate a pertinent icon with a frame. + Icons can also be used for other purposes, for example with wxTreeCtrl and wxListCtrl. + Icons have different formats on different platforms therefore separate icons + will usually be created for the different environments. + Platform-specific methods for creating a wxIcon structure are catered for, + and this is an occasion where conditional compilation will probably be required. + Note that a new icon must be created for every time the icon is to be used + for a new window. In Windows, the icon will not be reloaded if it has already + been used. + An icon allocated to a frame will be deleted when the frame is deleted. + For more information please see @ref overview_bitmap. @library{wxcore} @category{gdi} @@ -27,165 +47,159 @@ @stdobjects ::wxNullIcon - @see @ref overview_wxbitmapoverview "Bitmap and icon overview", @ref - overview_supportedbitmapformats "supported bitmap file formats", wxDC::DrawIcon, wxCursor + @see @ref overview_bitmap, @ref overview_bitmap_supportedformats, + wxDC::DrawIcon, wxCursor */ class wxIcon : public wxBitmap { public: - //@{ /** - Loads an icon from the specified location(). - - @param bits - Specifies an array of pixel values. - @param width - Specifies the width of the icon. - @param height - Specifies the height of the icon. - @param desiredWidth - Specifies the desired width of the icon. This - parameter only has an effect in Windows (32-bit) where icon resources can - contain - several icons of different sizes. - @param desiredWidth - Specifies the desired height of the icon. This - parameter only has an effect in Windows (32-bit) where icon resources can - contain - several icons of different sizes. - @param depth - Specifies the depth of the icon. If this is omitted, the display depth of - the - screen is used. - @param name - This can refer to a resource name under MS Windows, or a filename under MS - Windows and X. - Its meaning is determined by the flags parameter. - @param loc - The object describing the location of the native icon, see - wxIconLocation. - @param type - May be one of the following: - - - - - - - - wxBITMAP_TYPE_ICO - - - - - Load a Windows icon file. - - - - - - wxBITMAP_TYPE_ICO_RESOURCE - - - - - Load a Windows icon from the resource database. - - - - - - wxBITMAP_TYPE_GIF - - - - - Load a GIF bitmap file. - - - - - - wxBITMAP_TYPE_XBM - - - - - Load an X bitmap file. + Default ctor. + Constructs an icon object with no data; an assignment or another member + function such as LoadFile() must be called subsequently. + */ + wxIcon(); + /** + Copy ctor. + */ + wxIcon(const wxIcon& icon); + /* + Creates an icon from the given data, which can be of arbitrary type. + wxIcon(void* data, int type, int width, int height, int depth = -1); - wxBITMAP_TYPE_XPM + NOTE: this ctor is not implemented by all ports, is somewhat useless + without further description of the "data" supported formats and + uses 'int type' instead of wxBitmapType, so don't document it. + */ + /** + Creates an icon from an array of bits. + You should only use this function for monochrome bitmaps (depth 1) in + portable programs: in this case the bits parameter should contain an XBM image. + For other bit depths, the behaviour is platform dependent: under Windows, + the data is passed without any changes to the underlying CreateBitmap() API. + Under other platforms, only monochrome bitmaps may be created using this + constructor and wxImage should be used for creating colour bitmaps from + static data. + @param bits + Specifies an array of pixel values. + @param width + Specifies the width of the bitmap. + @param height + Specifies the height of the bitmap. + @param depth + Specifies the depth of the bitmap. + If this is omitted, then a value of 1 (monochrome bitmap) is used. + */ + wxIcon(const char bits[], int width, int height, int depth = 1); - Load an XPM bitmap file. + /** + Creates a new icon. A depth of ::wxICON_SCREEN_DEPTH indicates the + depth of the current screen or visual. + Some platforms only support 1 for monochrome and ::wxICON_SCREEN_DEPTH for + the current colour setting. + */ + wxIcon(int width, int height, int depth = wxICON_SCREEN_DEPTH); + /** + Creates a bitmap from XPM data. + To use this constructor, you must first include an XPM file. + For example, assuming that the file mybitmap.xpm contains an XPM array + of character pointers called @e mybitmap: + + @code + #include "mybitmap.xpm" + ... + wxIcon *icon = new wxIcon(mybitmap); + @endcode + + A macro, wxICON, is available which creates an icon using an XPM on + the appropriate platform, or an icon resource on Windows. + + @code + wxIcon icon(wxICON(mondrian)); + + // Equivalent to: + #if defined(__WXGTK__) || defined(__WXMOTIF__) + wxIcon icon(mondrian_xpm); + #endif + + #if defined(__WXMSW__) + wxIcon icon("mondrian"); + #endif + @endcode + */ + wxIcon(const char* const* bits); + /** + Loads an icon from a file or resource. - The validity of these flags depends on the platform and wxWidgets - configuration. - If all possible wxWidgets settings are used, the Windows platform supports - ICO file, ICO resource, - XPM data, and XPM file. Under wxGTK, the available formats are BMP file, - XPM data, XPM file, and PNG file. - Under wxMotif, the available formats are XBM data, XBM file, XPM data, XPM - file. + @param name + This can refer to a resource name or a filename under MS Windows and X. + Its meaning is determined by the @a type parameter. + @param type + May be one of the ::wxBitmapType values and indicates which type of + bitmap should be loaded. See the note in the class detailed description. + Note that the wxICON_DEFAULT_TYPE constant has different value under + different wxWidgets ports. See the icon.h header for the value it takes + for a specific port. + @param desiredWidth + Specifies the desired width of the icon. This parameter only has + an effect in Windows where icon resources can contain several icons + of different sizes. + @param desiredHeight + Specifies the desired height of the icon. This parameter only has + an effect in Windows where icon resources can contain several icons + of different sizes. + + @see LoadFile() + */ + wxIcon(const wxString& name, wxBitmapType type = wxICON_DEFAULT_TYPE, + int desiredWidth = -1, int desiredHeight = -1); - @remarks The first form constructs an icon object with no data; an - assignment or another member function such as Create or - LoadFile must be called subsequently. + /** + Loads an icon from the specified location. */ - wxIcon(); - wxIcon(const wxIcon& icon); - wxIcon(void* data, int type, int width, int height, - int depth = -1); - wxIcon(const char bits[], int width, int height, - int depth = 1); - wxIcon(int width, int height, int depth = -1); - wxIcon(const char* const* bits); - wxIcon(const wxString& name, wxBitmapType type, - int desiredWidth = -1, - int desiredHeight = -1); wxIcon(const wxIconLocation& loc); - //@} /** Destructor. - See @ref overview_refcountdestruct "reference-counted object destruction" for - more info. + See @ref overview_refcount_destruct for more info. + If the application omits to delete the icon explicitly, the icon will be destroyed automatically by wxWidgets when the application exits. + + @warning Do not delete an icon that is selected into a memory device context. */ - ~wxIcon(); + virtual ~wxIcon(); /** - Copies @a bmp bitmap to this icon. Under MS Windows the bitmap - must have mask colour set. + Copies @a bmp bitmap to this icon. + Under MS Windows the bitmap must have mask colour set. - LoadFile() - - Wx::Icon-new( width, height, depth = -1 ) - Wx::Icon-new( name, type, desiredWidth = -1, desiredHeight = -1 ) - Wx::Icon-newFromBits( bits, width, height, depth = 1 ) - Wx::Icon-newFromXPM( data ) + @see LoadFile() */ void CopyFromBitmap(const wxBitmap& bmp); /** - Gets the colour depth of the icon. A value of 1 indicates a - monochrome icon. + Gets the colour depth of the icon. + A value of 1 indicates a monochrome icon. */ int GetDepth() const; /** Gets the height of the icon in pixels. + + @see GetWidth() */ int GetHeight() const; @@ -206,79 +220,26 @@ public: @param name Either a filename or a Windows resource name. - The meaning of name is determined by the type parameter. + The meaning of name is determined by the @a type parameter. @param type - One of the following values: - - - - - - - - wxBITMAP_TYPE_ICO - - - - - Load a Windows icon file. - - - - - - wxBITMAP_TYPE_ICO_RESOURCE - - - - - Load a Windows icon from the resource database. - - - - - - wxBITMAP_TYPE_GIF - - - - - Load a GIF bitmap file. - - - - - - wxBITMAP_TYPE_XBM - - - - - Load an X bitmap file. - - - - - - wxBITMAP_TYPE_XPM - - - - - Load an XPM bitmap file. - - - - - - The validity of these flags depends on the platform and wxWidgets - configuration. + One of the ::wxBitmapType values; see the note in the class + detailed description. + Note that the wxICON_DEFAULT_TYPE constant has different value under + different wxWidgets ports. See the icon.h header for the value it takes + for a specific port. + @param desiredWidth + Specifies the desired width of the icon. This parameter only has + an effect in Windows where icon resources can contain several icons + of different sizes. + @param desiredHeight + Specifies the desired height of the icon. This parameter only has + an effect in Windows where icon resources can contain several icons + of different sizes. @return @true if the operation succeeded, @false otherwise. - - @see wxIcon() */ - bool LoadFile(const wxString& name, wxBitmapType type); + bool LoadFile(const wxString& name, wxBitmapType type = wxICON_DEFAULT_TYPE, + int desiredWidth = -1, int desiredHeight = -1); /** Sets the depth member (does not affect the icon data). @@ -305,7 +266,7 @@ public: void SetWidth(int width); /** - Assignment operator, using @ref overview_trefcount "reference counting". + Assignment operator, using @ref overview_refcount. @param icon Icon to assign.