Finished review/fixes of GDI category of functions and macros.

[wxWidgets.git] / interface / bitmap.h

diff --git a/interface/bitmap.h b/interface/bitmap.h
index 64a4b1c6b8d3cfae95f2113b8415fb5078a98393..6c37d33628940124c361e443390122c419ff50ca 100644 (file)
--- a/interface/bitmap.h
+++ b/interface/bitmap.h
@@ -1,38 +1,42 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        bitmap.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        bitmap.h

-// Purpose:     documentation for wxBitmapHandler class
+// Purpose:     interface of wxBitmap* classes

 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 

+
+/**
+    In wxBitmap and wxBitmapHandler context this value means: "use the screen depth".
+*/
+#define wxBITMAP_SCREEN_DEPTH       (-1)
+

 /**
     @class wxBitmapHandler
     @wxheader{bitmap.h}
 /**
     @class wxBitmapHandler
     @wxheader{bitmap.h}

-    
-    Overview
-    
-    This is the base class for implementing bitmap file loading/saving, and bitmap
-    creation from data.
+
+    This is the base class for implementing bitmap file loading/saving, and
+    bitmap creation from data.

     It is used within wxBitmap and is not normally seen by the application.
     It is used within wxBitmap and is not normally seen by the application.

-    
+

     If you wish to extend the capabilities of wxBitmap, derive a class from
     If you wish to extend the capabilities of wxBitmap, derive a class from

-    wxBitmapHandler
-    and add the handler using wxBitmap::AddHandler in your
+    wxBitmapHandler and add the handler using wxBitmap::AddHandler in your

     application initialisation.
     application initialisation.

-    
+

     @library{wxcore}
     @library{wxcore}

-    @category{FIXME}
-    
-    @seealso
-    wxBitmap, wxIcon, wxCursor
+    @category{misc}
+
+    @see @ref overview_bitmap, wxBitmap, wxIcon, wxCursor

 */
 class wxBitmapHandler : public wxObject
 {
 public:
     /**
 */
 class wxBitmapHandler : public wxObject
 {
 public:
     /**

-        Default constructor. In your own default constructor, initialise the members
-        m_name, m_extension and m_type.
+        Default constructor.
+
+        In your own default constructor, initialise the members m_name,
+        m_extension and m_type.

     */
     wxBitmapHandler();
 
     */
     wxBitmapHandler();
 


@@ -42,272 +46,286 @@ public:
     ~wxBitmapHandler();
 
     /**
     ~wxBitmapHandler();
 
     /**

-        Creates a bitmap from the given data, which can be of arbitrary type. The
-        wxBitmap object @e bitmap is
-        manipulated by this function.
-        
-        @param bitmap 
-        The wxBitmap object.
-        
-        @param width 
-        The width of the bitmap in pixels.
-        
-        @param height 
-        The height of the bitmap in pixels.
-        
-        @param depth 
-        The depth of the bitmap in pixels. If this is -1, the screen depth is used.
-        
-        @param data 
-        Data whose type depends on the value of type.
-        
-        @param type 
-        A bitmap type identifier - see wxBitmapHandler() for a list
-        of possible values.
-        
+        Creates a bitmap from the given data, which can be of arbitrary type.
+        The wxBitmap object @a bitmap is manipulated by this function.
+
+        @param bitmap
+            The wxBitmap object.
+        @param width
+            The width of the bitmap in pixels.
+        @param height
+            The height of the bitmap in pixels.
+        @param depth
+            The depth of the bitmap in pixels.
+            If this is ::wxBITMAP_SCREEN_DEPTH, the screen depth is used.
+        @param data
+            Data whose type depends on the value of type.
+        @param type
+            A bitmap type identifier - see ::wxBitmapType for a list
+            of possible values.
+

         @returns @true if the call succeeded, @false otherwise (the default).
     */
         @returns @true if the call succeeded, @false otherwise (the default).
     */

-    virtual bool Create(wxBitmap* bitmap, const void* data, int type,
-                        int width,
-                        int height,
-                        int depth = -1);
+    virtual bool Create(wxBitmap* bitmap, const void* data, wxBitmapType type,
+                        int width, int height, int depth = wxBITMAP_SCREEN_DEPTH);

 
     /**
         Gets the file extension associated with this handler.
     */
 
     /**
         Gets the file extension associated with this handler.
     */

-    const wxString GetExtension();
+    const wxString& GetExtension() const;

 
     /**
         Gets the name of this handler.
     */
 
     /**
         Gets the name of this handler.
     */

-    const wxString GetName();
+    const wxString& GetName() const;

 
     /**
         Gets the bitmap type associated with this handler.
     */
 
     /**
         Gets the bitmap type associated with this handler.
     */

-    long GetType();
-
-    /**
-        Loads a bitmap from a file or resource, putting the resulting data into @e
-        bitmap.
-        
-        @param bitmap 
-        The bitmap object which is to be affected by this operation.
-        
-        @param name 
-        Either a filename or a Windows resource name.
-        The meaning of name is determined by the type parameter.
-        
-        @param type 
-        See wxBitmap::wxBitmap for values this can take.
-        
+    wxBitmapType GetType() const;
+
+    /**
+        Loads a bitmap from a file or resource, putting the resulting data into
+        @a bitmap.
+
+        @param bitmap
+            The bitmap object which is to be affected by this operation.
+        @param name
+            Either a filename or a Windows resource name.
+            The meaning of name is determined by the type parameter.
+        @param type
+            See ::wxBitmapType for values this can take.
+

         @returns @true if the operation succeeded, @false otherwise.
         @returns @true if the operation succeeded, @false otherwise.

-        
-        @sa wxBitmap::LoadFile, wxBitmap::SaveFile, SaveFile()
+
+        @see wxBitmap::LoadFile, wxBitmap::SaveFile, SaveFile()

     */
     */

-    bool LoadFile(wxBitmap* bitmap, const wxString& name, long type);
+    bool LoadFile(wxBitmap* bitmap, const wxString& name, wxBitmapType type);

 
     /**
         Saves a bitmap in the named file.
 
     /**
         Saves a bitmap in the named file.

-        
-        @param bitmap 
-        The bitmap object which is to be affected by this operation.
-        
-        @param name 
-        A filename. The meaning of name is determined by the type parameter.
-        
-        @param type 
-        See wxBitmap::wxBitmap for values this can take.
-        
-        @param palette 
-        An optional palette used for saving the bitmap.
-        
+
+        @param bitmap
+            The bitmap object which is to be affected by this operation.
+        @param name
+            A filename. The meaning of name is determined by the type parameter.
+        @param type
+            See ::wxBitmapType for values this can take.
+        @param palette
+            An optional palette used for saving the bitmap.
+

         @returns @true if the operation succeeded, @false otherwise.
         @returns @true if the operation succeeded, @false otherwise.

-        
-        @sa wxBitmap::LoadFile, wxBitmap::SaveFile, LoadFile()
+
+        @see wxBitmap::LoadFile, wxBitmap::SaveFile, LoadFile()

     */
     */

-    bool SaveFile(wxBitmap* bitmap, const wxString& name, int type,
-                  wxPalette* palette = @NULL);
+    bool SaveFile(wxBitmap* bitmap, const wxString& name, wxBitmapType type,
+                  wxPalette* palette = NULL);

 
     /**
         Sets the handler extension.
 
     /**
         Sets the handler extension.

-        
-        @param extension 
-        Handler extension.
+
+        @param extension
+            Handler extension.

     */
     void SetExtension(const wxString& extension);
 
     /**
         Sets the handler name.
     */
     void SetExtension(const wxString& extension);
 
     /**
         Sets the handler name.

-        
-        @param name 
-        Handler name.
+
+        @param name
+            Handler name.

     */
     void SetName(const wxString& name);
 
     /**
         Sets the handler type.
     */
     void SetName(const wxString& name);
 
     /**
         Sets the handler type.

-        
-        @param name 
-        Handler type.
+
+        @param type
+            Handler type.

     */
     */

-    void SetType(long type);
+    void SetType(wxBitmapType type);

 };
 
 
 /**
     @class wxBitmap
     @wxheader{bitmap.h}
 };
 
 
 /**
     @class wxBitmap
     @wxheader{bitmap.h}

-    
+

     This class encapsulates the concept of a platform-dependent bitmap,
     either monochrome or colour or colour with alpha channel support.
     This class encapsulates the concept of a platform-dependent bitmap,
     either monochrome or colour or colour with alpha channel support.

-    
+
+    @note
+    Many wxBitmap functions take a @e type parameter, which is a value of the
+    ::wxBitmapType enumeration.
+    The validity of those values depends however on the platform where your program
+    is running and from the wxWidgets configuration.
+    If all possible wxWidgets settings are used, the Windows platform supports BMP file,
+    BMP resource, XPM data, and XPM.
+    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.
+    In addition, wxBitmap can load and save all formats that wxImage; see wxImage for
+    more info. Of course, you must have wxImage handlers loaded.
+

     @library{wxcore}
     @category{gdi}
     @library{wxcore}
     @category{gdi}

-    
+

     @stdobjects
     @stdobjects

-    Objects:
-    wxNullBitmap
-    
-    @seealso
-    @ref overview_wxbitmapoverview "wxBitmap overview", @ref
-    overview_supportedbitmapformats "supported bitmap file formats", wxDC::Blit, wxIcon, wxCursor, wxBitmap, wxMemoryDC
+    ::wxNullBitmap
+
+    @see @ref overview_bitmap, @ref overview_bitmap_supportedformats,
+         wxDC::Blit, wxIcon, wxCursor, wxBitmap, wxMemoryDC

 */
 class wxBitmap : public wxGDIObject
 {
 public:
 */
 class wxBitmap : public wxGDIObject
 {
 public:

-    //@{

     /**
     /**

-        Creates bitmap object from the image. This has to be done
-        to actually display an image as you cannot draw an image directly on a window.
+        Default constructor.
+
+        Constructs a bitmap object with no data; an assignment or another member
+        function such as Create() or LoadFile() must be called subsequently.
+    */
+    wxBitmap();
+
+    /**
+        Copy constructor, uses @ref overview_refcount "reference counting".
+        To make a real copy, you can use:
+
+        @code
+        wxBitmap newBitmap = oldBitmap.GetSubBitmap(
+                             wxRect(0, 0, oldBitmap.GetWidth(), oldBitmap.GetHeight()));
+        @endcode
+    */
+    wxBitmap(const wxBitmap& bitmap);
+
+
+    /*
+        Creates a bitmap from the given @a data which is interpreted in
+        platform-dependent manner.
+
+        @param data
+            Specifies the bitmap data in a platform-dependent format.
+        @param type
+            May be one of the ::wxBitmapType values and indicates which type of
+            bitmap does @a data contains. See the note in the class
+            detailed description.
+        @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, the display depth of the screen is used.
+    wxBitmap(const void* data, int type, int width, int height, int depth = -1);
+
+
+        NOTE: this ctor is not implemented by all port, is somewhat useless
+              without further description of the "data" supported formats and
+              uses 'int type' instead of wxBitmapType, so don't document it.
+    */
+
+    /**
+        Creates a bitmap from the given array @a 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.
+    */
+    wxBitmap(const char bits[], int width, int height, int depth = 1);
+
+    /**
+        Creates a new bitmap. A depth of ::wxBITMAP_SCREEN_DEPTH indicates the
+        depth of the current screen or visual.
+        Some platforms only support 1 for monochrome and ::wxBITMAP_SCREEN_DEPTH for
+        the current colour setting.
+
+        A depth of 32 including an alpha channel is supported under MSW, Mac and GTK+.
+    */
+    wxBitmap(int width, int height, int depth = wxBITMAP_SCREEN_DEPTH);
+
+    /**
+        Creates a bitmap from XPM data.
+    */
+    wxBitmap(const char* const* bits);
+
+    /**
+        Loads a bitmap from a file or resource.
+
+        @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.
+
+        @see LoadFile()
+    */
+    wxBitmap(const wxString& name, wxBitmapType type = wxBITMAP_TYPE_XPM);
+
+    /**
+        Creates this bitmap object from the given image.
+        This has to be done to actually display an image as you cannot draw an
+        image directly on a window.
+

         The resulting bitmap will use the provided colour depth (or that of the
         The resulting bitmap will use the provided colour depth (or that of the

-        current system if depth is -1) which entails that a colour reduction has
-        to take place.
-        
+        current system if depth is ::wxBITMAP_SCREEN_DEPTH) which entails that a
+        colour reduction may take place.
+

         When in 8-bit mode (PseudoColour mode), the GTK port will use a color cube
         When in 8-bit mode (PseudoColour mode), the GTK port will use a color cube

-        created
-        on program start-up to look up colors. This ensures a very fast conversion, but
-        the image quality won't be perfect (and could be better for photo images using
-        more
-        sophisticated dithering algorithms).
-        
+        created on program start-up to look up colors. This ensures a very fast conversion,
+        but the image quality won't be perfect (and could be better for photo images using
+        more sophisticated dithering algorithms).
+

         On Windows, if there is a palette present (set with SetPalette), it will be
         On Windows, if there is a palette present (set with SetPalette), it will be

-        used when
-        creating the wxBitmap (most useful in 8-bit display mode). On other platforms,
-        the palette is currently ignored.
-        
-        @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, 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 type parameter.
-        
-        @param type 
-        May be one of the following:
-        
-        
-        wxBITMAP_TYPE_BMP
-        
-        
-        Load a Windows bitmap file.
-        
-        wxBITMAP_TYPE_BMP_RESOURCE
-        
-        
-        Load a Windows bitmap resource from the executable. Windows only.
-        
-        wxBITMAP_TYPE_PICT_RESOURCE
-        
-        
-        Load a PICT image resource from the executable. Mac OS only.
-        
-        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.
-        If all possible wxWidgets settings are used, the Windows platform supports BMP
-        file, BMP resource,
-        XPM data, and XPM. 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.
-        
-        In addition, wxBitmap can read all formats that wxImage can, which currently
-        include
-        wxBITMAP_TYPE_JPEG, wxBITMAP_TYPE_TIF, wxBITMAP_TYPE_PNG, wxBITMAP_TYPE_GIF,
-        wxBITMAP_TYPE_PCX,
-        and wxBITMAP_TYPE_PNM. Of course, you must have wxImage handlers loaded.
-        
-        @param img 
-        Platform-independent wxImage object.
-        
-        @remarks The first form constructs a bitmap object with no data; an
-                   assignment or another member function such as Create
-                   or LoadFile must be called subsequently.
-        
-        @sa LoadFile()
+        used when creating the wxBitmap (most useful in 8-bit display mode).
+        On other platforms, the palette is currently ignored.
+
+        @param img
+            Platform-independent wxImage object.
+        @param depth
+            Specifies the depth of the bitmap.
+            If this is omitted, the display depth of the screen is used.

     */
     */

-    wxBitmap();
-        wxBitmap(const wxBitmap& bitmap);
-        wxBitmap(const void* data, int type, int width, int height,
-                 int depth = -1);
-        wxBitmap(const char bits[], int width, int height,
-                 int depth = 1);
-        wxBitmap(int width, int height, int depth = -1);
-        wxBitmap(const char* const* bits);
-        wxBitmap(const wxString& name, long type);
-        wxBitmap(const wxImage& img, int depth = -1);
-    //@}
+    wxBitmap(const wxImage& img, int depth = wxBITMAP_SCREEN_DEPTH);

 
     /**
         Destructor.
 
     /**
         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 bitmap explicitly, the bitmap will be
         destroyed automatically by wxWidgets when the application exits.
         If the application omits to delete the bitmap explicitly, the bitmap will be
         destroyed automatically by wxWidgets when the application exits.

-        
+
+        @warning

         Do not delete a bitmap that is selected into a memory device context.
     */
     ~wxBitmap();
 
     /**
         Adds a handler to the end of the static list of format handlers.
         Do not delete a bitmap that is selected into a memory device context.
     */
     ~wxBitmap();
 
     /**
         Adds a handler to the end of the static list of format handlers.

-        
-        @param handler 
-        A new bitmap format handler object. There is usually only one instance
-        of a given handler class in an application session.
-        
-        @sa wxBitmapHandler
+
+        @param handler
+            A new bitmap format handler object. There is usually only one instance
+            of a given handler class in an application session.
+
+        @see wxBitmapHandler

     */
     static void AddHandler(wxBitmapHandler* handler);
 
     /**
         Deletes all bitmap handlers.
     */
     static void AddHandler(wxBitmapHandler* handler);
 
     /**
         Deletes all bitmap handlers.

-        

         This function is called by wxWidgets on exit.
     */
     static void CleanUpHandlers();
         This function is called by wxWidgets on exit.
     */
     static void CleanUpHandlers();


@@ -324,374 +342,343 @@ public:
     */
     bool CopyFromIcon(const wxIcon& icon);
 
     */
     bool CopyFromIcon(const wxIcon& icon);
 

-    //@{

     /**
     /**

+        Creates a fresh bitmap.
+        If the final argument is omitted, the display depth of the screen is used.
+
+        This overload works on all platforms.
+    */
+    virtual bool Create(int width, int height, int depth = wxBITMAP_SCREEN_DEPTH);
+
+    /*

         Creates a bitmap from the given data, which can be of arbitrary type.
         Creates a bitmap from the given data, which can be of arbitrary type.

-        
-        @param width 
-        The width of the bitmap in pixels.
-        
-        @param height 
-        The height of the bitmap in pixels.
-        
-        @param depth 
-        The depth of the bitmap in pixels. If this is -1, the screen depth is used.
-        
-        @param data 
-        Data whose type depends on the value of type.
-        
-        @param type 
-        A bitmap type identifier - see wxBitmap() for a list
-        of possible values.
-        
+
+        @param data
+            Data whose type depends on the value of type.
+        @param type
+            A bitmap type identifier; see ::wxBitmapType for the list of values.
+            See the note in the class detailed description for more info.
+        @param width
+            The width of the bitmap in pixels.
+        @param height
+            The height of the bitmap in pixels.
+        @param depth
+            The depth of the bitmap in pixels. If this is -1, the screen depth is used.
+

         @returns @true if the call succeeded, @false otherwise.
         @returns @true if the call succeeded, @false otherwise.

-        
-        @remarks The first form works on all platforms. The portability of the
-                   second form depends on the type of data.
-        
-        @sa wxBitmap()
+
+        This overload depends on the @a type of data.
+
+    virtual bool Create(const void* data, int type, int width,
+                        int height, int depth = -1);
+
+        NOTE: leave this undoc for the same reason of the relative ctor.

     */
     */

-    virtual bool Create(int width, int height, int depth = -1);
-        virtual bool Create(const void* data, int type, int width,
-                            int height,
-                            int depth = -1);
-    //@}

 
 

-    //@{

     /**
     /**

-        Finds the handler associated with the given bitmap type.
-        
-        @param name 
-        The handler name.
-        
-        @param extension 
-        The file extension, such as "bmp".
-        
-        @param bitmapType 
-        The bitmap type, such as wxBITMAP_TYPE_BMP.
-        
+        Finds the handler with the given @a name.
+

         @returns A pointer to the handler if found, @NULL otherwise.
         @returns A pointer to the handler if found, @NULL otherwise.

-        
-        @sa wxBitmapHandler

     */
     static wxBitmapHandler* FindHandler(const wxString& name);
     */
     static wxBitmapHandler* FindHandler(const wxString& name);

-        static wxBitmapHandler* FindHandler(const wxString& extension,
-                                            wxBitmapType bitmapType);
-        static wxBitmapHandler* FindHandler(wxBitmapType bitmapType);
-    //@}

 
     /**
 
     /**

-        Gets the colour depth of the bitmap. A value of 1 indicates a
-        monochrome bitmap.
+        Finds the handler associated with the given @a extension and @a type.
+
+        @param extension
+            The file extension, such as "bmp" (without the dot).
+        @param bitmapType
+            The bitmap type managed by the handler, see ::wxBitmapType.
+
+        @returns A pointer to the handler if found, @NULL otherwise.
+    */
+    static wxBitmapHandler* FindHandler(const wxString& extension,
+                                        wxBitmapType bitmapType);
+
+    /**
+        Finds the handler associated with the given bitmap type.
+
+        @param bitmapType
+            The bitmap type managed by the handler, see ::wxBitmapType.
+
+        @returns A pointer to the handler if found, @NULL otherwise.
+
+        @see wxBitmapHandler
+    */
+
+    static wxBitmapHandler* FindHandler(wxBitmapType bitmapType);
+
+    /**
+        Gets the colour depth of the bitmap.
+        A value of 1 indicates a monochrome bitmap.

     */
     */

-    int GetDepth();
+    int GetDepth() const;

 
     /**
         Returns the static list of bitmap format handlers.
 
     /**
         Returns the static list of bitmap format handlers.

-        
-        @sa wxBitmapHandler
+
+        @see wxBitmapHandler

     */
     static wxList GetHandlers();
 
     /**
         Gets the height of the bitmap in pixels.
     */
     */
     static wxList GetHandlers();
 
     /**
         Gets the height of the bitmap in pixels.
     */

-    int GetHeight();
+    int GetHeight() const;

 
     /**
         Gets the associated mask (if any) which may have been loaded from a file
         or set for the bitmap.
 
     /**
         Gets the associated mask (if any) which may have been loaded from a file
         or set for the bitmap.

-        
-        @sa SetMask(), wxMask
+
+        @see SetMask(), wxMask

     */
     */

-    wxMask* GetMask();
+    wxMask* GetMask() const;

 
     /**
         Gets the associated palette (if any) which may have been loaded from a file
         or set for the bitmap.
 
     /**
         Gets the associated palette (if any) which may have been loaded from a file
         or set for the bitmap.

-        
-        @sa wxPalette
+
+        @see wxPalette

     */
     */

-    wxPalette* GetPalette();
+    wxPalette* GetPalette() const;

 
     /**
         Returns a sub bitmap of the current one as long as the rect belongs entirely to
         the bitmap. This function preserves bit depth and mask information.
     */
 
     /**
         Returns a sub bitmap of the current one as long as the rect belongs entirely to
         the bitmap. This function preserves bit depth and mask information.
     */

-    wxBitmap GetSubBitmap(const wxRect& rect);
+    wxBitmap GetSubBitmap(const wxRect& rect) const;

 
     /**
         Gets the width of the bitmap in pixels.
 
     /**
         Gets the width of the bitmap in pixels.

-        
-        @sa GetHeight()
+
+        @see GetHeight()

     */
     */

-    int GetWidth();
+    int GetWidth() const;

 
     /**
         Adds the standard bitmap format handlers, which, depending on wxWidgets
 
     /**
         Adds the standard bitmap format handlers, which, depending on wxWidgets

-        configuration, can be handlers for Windows bitmap, Windows bitmap resource, and
-        XPM.
-        
+        configuration, can be handlers for Windows bitmap, Windows bitmap resource,
+        and XPM.
+

         This function is called by wxWidgets on startup.
         This function is called by wxWidgets on startup.

-        
-        @sa wxBitmapHandler
+
+        @see wxBitmapHandler

     */
     static void InitStandardHandlers();
 
     /**
         Adds a handler at the start of the static list of format handlers.
     */
     static void InitStandardHandlers();
 
     /**
         Adds a handler at the start of the static list of format handlers.

-        
-        @param handler 
-        A new bitmap format handler object. There is usually only one instance
-        of a given handler class in an application session.
-        
-        @sa wxBitmapHandler
+
+        @param handler
+            A new bitmap format handler object. There is usually only one instance
+            of a given handler class in an application session.
+
+        @see wxBitmapHandler

     */
     static void InsertHandler(wxBitmapHandler* handler);
 
     /**
         Returns @true if bitmap data is present.
     */
     */
     static void InsertHandler(wxBitmapHandler* handler);
 
     /**
         Returns @true if bitmap data is present.
     */

-#define bool IsOk()     /* implementation is private */
+    bool IsOk() const;

 
     /**
         Loads a bitmap from a file or resource.
 
     /**
         Loads a bitmap from a file or resource.

-        
-        @param name 
-        Either a filename or a Windows resource name.
-        The meaning of name is determined by the type parameter.
-        
-        @param type 
-        One of the following values:
-        
-        
-        wxBITMAP_TYPE_BMP
-        
-        
-        Load a Windows bitmap file.
-        
-        wxBITMAP_TYPE_BMP_RESOURCE
-        
-        
-        Load a Windows bitmap resource from the executable.
-        
-        wxBITMAP_TYPE_PICT_RESOURCE
-        
-        
-        Load a PICT image resource from the executable. Mac OS only.
-        
-        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.
-        
-        In addition, wxBitmap can read all formats that wxImage can
-        (wxBITMAP_TYPE_JPEG, wxBITMAP_TYPE_PNG, wxBITMAP_TYPE_GIF, wxBITMAP_TYPE_PCX,
-        wxBITMAP_TYPE_PNM).
-        (Of course you must have wxImage handlers loaded.)
-        
+
+        @param name
+            Either a filename or a Windows resource name.
+            The meaning of name is determined by the @a type parameter.
+        @param type
+            One of the ::wxBitmapType values; see the note in the class
+            detailed description.
+

         @returns @true if the operation succeeded, @false otherwise.
         @returns @true if the operation succeeded, @false otherwise.

-        
+

         @remarks A palette may be associated with the bitmap if one exists
         @remarks A palette may be associated with the bitmap if one exists

-                   (especially for colour Windows bitmaps), and if the
-                   code supports it. You can check if one has been
-                   created by using the GetPalette member.
-        
-        @sa SaveFile()
+                 (especially for colour Windows bitmaps), and if the
+                 code supports it. You can check if one has been created
+                 by using the GetPalette() member.
+
+        @see SaveFile()

     */
     bool LoadFile(const wxString& name, wxBitmapType type);
 
     /**
     */
     bool LoadFile(const wxString& name, wxBitmapType type);
 
     /**

-        Finds the handler with the given name, and removes it. The handler
-        is not deleted.
-        
-        @param name 
-        The handler name.
-        
+        Finds the handler with the given name, and removes it.
+        The handler is not deleted.
+
+        @param name
+            The handler name.
+

         @returns @true if the handler was found and removed, @false otherwise.
         @returns @true if the handler was found and removed, @false otherwise.

-        
-        @sa wxBitmapHandler
+
+        @see wxBitmapHandler

     */
     static bool RemoveHandler(const wxString& name);
 
     /**
         Saves a bitmap in the named file.
     */
     static bool RemoveHandler(const wxString& name);
 
     /**
         Saves a bitmap in the named file.

-        
-        @param name 
-        A filename. The meaning of name is determined by the type parameter.
-        
-        @param type 
-        One of the following values:
-        
-        
-        wxBITMAP_TYPE_BMP
-        
-        
-        Save a Windows bitmap file.
-        
-        wxBITMAP_TYPE_GIF
-        
-        
-        Save a GIF bitmap file.
-        
-        wxBITMAP_TYPE_XBM
-        
-        
-        Save an X bitmap file.
-        
-        wxBITMAP_TYPE_XPM
-        
-        
-        Save an XPM bitmap file.
-        
-        The validity of these flags depends on the platform and wxWidgets configuration.
-        
-        In addition, wxBitmap can save all formats that wxImage can
-        (wxBITMAP_TYPE_JPEG, wxBITMAP_TYPE_PNG).
-        (Of course you must have wxImage handlers loaded.)
-        
-        @param palette 
-        An optional palette used for saving the bitmap.
-        
+
+        @param name
+            A filename. The meaning of name is determined by the type parameter.
+        @param type
+            One of the ::wxBitmapType values; see the note in the class
+            detailed description.
+        @param palette
+            An optional palette used for saving the bitmap.
+

         @returns @true if the operation succeeded, @false otherwise.
         @returns @true if the operation succeeded, @false otherwise.

-        
+

         @remarks Depending on how wxWidgets has been configured, not all formats
         @remarks Depending on how wxWidgets has been configured, not all formats

-                   may be available.
-        
-        @sa LoadFile()
+                 may be available.
+
+        @see LoadFile()

     */
     bool SaveFile(const wxString& name, wxBitmapType type,
     */
     bool SaveFile(const wxString& name, wxBitmapType type,

-                  wxPalette* palette = @NULL);
+                  const wxPalette* palette = NULL);

 
     /**
         Sets the depth member (does not affect the bitmap data).
 
     /**
         Sets the depth member (does not affect the bitmap data).

-        
-        @param depth 
-        Bitmap depth.
+
+        @todo since these functions do not affect the bitmap data,
+              why they exist??
+
+        @param depth
+            Bitmap depth.

     */
     void SetDepth(int depth);
 
     /**
         Sets the height member (does not affect the bitmap data).
     */
     void SetDepth(int depth);
 
     /**
         Sets the height member (does not affect the bitmap data).

-        
-        @param height 
-        Bitmap height in pixels.
+
+        @param height
+            Bitmap height in pixels.

     */
     void SetHeight(int height);
 
     /**
         Sets the mask for this bitmap.
     */
     void SetHeight(int height);
 
     /**
         Sets the mask for this bitmap.

-        
+

         @remarks The bitmap object owns the mask once this has been called.
         @remarks The bitmap object owns the mask once this has been called.

-        
-        @sa GetMask(), wxMask
+
+        @see GetMask(), wxMask

     */
     void SetMask(wxMask* mask);
 
     /**
         Sets the associated palette. (Not implemented under GTK+).
     */
     void SetMask(wxMask* mask);
 
     /**
         Sets the associated palette. (Not implemented under GTK+).

-        
-        @param palette 
-        The palette to set.
-        
-        @sa wxPalette
+
+        @param palette
+            The palette to set.
+
+        @see wxPalette

     */
     void SetPalette(const wxPalette& palette);
 
     /**
         Sets the width member (does not affect the bitmap data).
     */
     void SetPalette(const wxPalette& palette);
 
     /**
         Sets the width member (does not affect the bitmap data).

-        
-        @param width 
-        Bitmap width in pixels.
+
+        @param width
+            Bitmap width in pixels.

     */
     void SetWidth(int width);
 
     /**
     */
     void SetWidth(int width);
 
     /**

-        Assignment operator, using @ref overview_trefcount "reference counting".
-        
-        @param bitmap 
-        Bitmap to assign.
+        Assignment operator, using @ref overview_refcount "reference counting".
+
+        @param bitmap
+            Bitmap to assign.

     */
     wxBitmap operator =(const wxBitmap& bitmap);
 };
 
     */
     wxBitmap operator =(const wxBitmap& bitmap);
 };
 

+/**
+    An empty wxBitmap object.
+*/
+wxBitmap wxNullBitmap;
+
+
+

 
 /**
     @class wxMask
     @wxheader{bitmap.h}
 
 /**
     @class wxMask
     @wxheader{bitmap.h}

-    
+

     This class encapsulates a monochrome mask bitmap, where the masked area is
     This class encapsulates a monochrome mask bitmap, where the masked area is

-    black and
-    the unmasked area is white. When associated with a bitmap and drawn in a device
-    context,
-    the unmasked area of the bitmap will be drawn, and the masked area will not be
-    drawn.
-    
+    black and the unmasked area is white.
+
+    When associated with a bitmap and drawn in a device context, the unmasked
+    area of the bitmap will be drawn, and the masked area will not be drawn.
+

     @library{wxcore}
     @category{gdi}
     @library{wxcore}
     @category{gdi}

-    
-    @seealso
-    wxBitmap, wxDC::Blit, wxMemoryDC
+
+    @see wxBitmap, wxDC::Blit, wxMemoryDC

 */
 class wxMask : public wxObject
 {
 public:
 */
 class wxMask : public wxObject
 {
 public:

-    //@{
+

     /**
     /**

-        Constructs a mask from a bitmap and a palette index that indicates the
-        background. Not
-        yet implemented for GTK.
-        
-        @param bitmap 
-        A valid bitmap.
-        
-        @param colour 
-        A colour specifying the transparency RGB values.
-        
-        @param index 
-        Index into a palette, specifying the transparency colour.
+        Default constructor.

     */
     wxMask();
     */
     wxMask();

-        wxMask(const wxBitmap& bitmap);
-        wxMask(const wxBitmap& bitmap,
-               const wxColour& colour);
-        wxMask(const wxBitmap& bitmap, int index);
-    //@}
+
+    /**
+        Constructs a mask from a bitmap and a palette index that indicates the
+        background.
+        Not yet implemented for GTK.
+
+        @param bitmap
+            A valid bitmap.
+        @param index
+            Index into a palette, specifying the transparency colour.
+    */
+    wxMask(const wxBitmap& bitmap, int index);
+
+    /**
+        Constructs a mask from a monochrome bitmap.
+
+        @beginWxPythonOnly
+        This is the default constructor for wxMask in wxPython.
+        @endWxPythonOnly
+    */
+    wxMask(const wxBitmap& bitmap);
+
+    /**
+        Constructs a mask from a bitmap and a colour that indicates the background.
+
+        @beginWxPythonOnly
+        wxPython has an alternate wxMask constructor matching this form called wxMaskColour.
+        @endWxPythonOnly
+    */
+    wxMask(const wxBitmap& bitmap, const wxColour& colour);

 
     /**
         Destroys the wxMask object and the underlying bitmap data.
     */
     ~wxMask();
 
 
     /**
         Destroys the wxMask object and the underlying bitmap data.
     */
     ~wxMask();
 

-    //@{

     /**
         Constructs a mask from a bitmap and a palette index that indicates the
     /**
         Constructs a mask from a bitmap and a palette index that indicates the

-        background. Not
-        yet implemented for GTK.
-        
-        @param bitmap 
-        A valid bitmap.
-        
-        @param colour 
-        A colour specifying the transparency RGB values.
-        
-        @param index 
-        Index into a palette, specifying the transparency colour.
+        background.
+        Not yet implemented for GTK.
+
+        @param bitmap
+            A valid bitmap.
+        @param index
+            Index into a palette, specifying the transparency colour.
+    */
+    bool Create(const wxBitmap& bitmap, int index);
+
+    /**
+        Constructs a mask from a monochrome bitmap.

     */
     bool Create(const wxBitmap& bitmap);
     */
     bool Create(const wxBitmap& bitmap);

-        bool Create(const wxBitmap& bitmap, const wxColour& colour);
-        bool Create(const wxBitmap& bitmap, int index);
-    //@}
+
+    /**
+        Constructs a mask from a bitmap and a colour that indicates the background.
+    */
+    bool Create(const wxBitmap& bitmap, const wxColour& colour);

 };
 };

+