non-pch build fix

[wxWidgets.git] / interface / bitmap.h

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

-// Purpose:     interface of wxBitmapHandler
+// 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.
 
     If you wish to extend the capabilities of wxBitmap, derive a class from
     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

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

     application initialisation.
 
     @library{wxcore}
     application initialisation.
 
     @library{wxcore}

-    @category{FIXME}
+    @category{misc}

 
 

-    @see wxBitmap, wxIcon, wxCursor
+    @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();
 


@@ -41,10 +46,9 @@ public:
     ~wxBitmapHandler();
 
     /**
     ~wxBitmapHandler();
 
     /**

-        Creates a bitmap from the given data, which can be of arbitrary type. The
-        wxBitmap object @a bitmap is
-        manipulated by this function.
-        
+        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
         @param bitmap
             The wxBitmap object.
         @param width


@@ -52,75 +56,74 @@ public:
         @param height
             The height of the bitmap in pixels.
         @param depth
         @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.
+            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
         @param data
             Data whose type depends on the value of type.
         @param type

-            A bitmap type identifier - see wxBitmapHandler() for a list
+            A bitmap type identifier - see ::wxBitmapType for a list

             of possible values.
             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;
+    const wxString& GetExtension() const;

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

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

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

-    long GetType() const;
+    wxBitmapType GetType() const;

 
     /**
 
     /**

-        Loads a bitmap from a file or resource, putting the resulting data into @e
-        bitmap.
-        
+        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
         @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.
-        
+            See ::wxBitmapType for values this can take.
+

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

-        
+

         @see 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
         @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.
+            See ::wxBitmapType for values this can take.

         @param palette
             An optional palette used for saving the bitmap.
         @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.

-        
+

         @see wxBitmap::LoadFile, wxBitmap::SaveFile, LoadFile()
     */
         @see wxBitmap::LoadFile, wxBitmap::SaveFile, LoadFile()
     */

-    bool SaveFile(wxBitmap* bitmap, const wxString& name, int type,
+    bool SaveFile(wxBitmap* bitmap, const wxString& name, wxBitmapType type,

                   wxPalette* palette = NULL);
 
     /**
         Sets the handler extension.
                   wxPalette* palette = NULL);
 
     /**
         Sets the handler extension.

-        
+

         @param extension
             Handler extension.
     */
         @param extension
             Handler extension.
     */


@@ -128,7 +131,7 @@ public:
 
     /**
         Sets the handler name.
 
     /**
         Sets the handler name.

-        
+

         @param name
             Handler name.
     */
         @param name
             Handler name.
     */


@@ -136,15 +139,14 @@ public:
 
     /**
         Sets the handler type.
 
     /**
         Sets the handler type.

-        
-        @param name
+
+        @param type

             Handler type.
     */
             Handler type.
     */

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

 };
 
 
 };
 
 

-

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


@@ -152,36 +154,86 @@ public:
     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}
 
     @stdobjects
     @library{wxcore}
     @category{gdi}
 
     @stdobjects

-    ::Objects:, ::wxNullBitmap,
+    ::wxNullBitmap

 
 

-    @see @ref overview_wxbitmapoverview "wxBitmap overview", @ref
-    overview_supportedbitmapformats "supported bitmap file formats", wxDC::Blit, wxIcon, wxCursor, wxBitmap, wxMemoryDC
+    @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.
-        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.
-        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).
-        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.
-        
+        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
         @param bits
             Specifies an array of pixel values.
         @param width


@@ -189,139 +241,85 @@ public:
         @param height
             Specifies the height of the bitmap.
         @param depth
         @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.
+            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
         @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.
+            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
         @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.
+            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
+        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
+        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
+        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 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.
-        
-        @see LoadFile()
+        @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.
         @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);
         @see wxBitmapHandler
     */
     static void AddHandler(wxBitmapHandler* handler);


@@ -344,65 +342,81 @@ 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 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.
         @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.
-        
+

         @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.
-        
-        @see wxBitmap()
-    */
-    virtual bool Create(int width, int height, int depth = -1);
+
+        This overload depends on the @a type of data.
+

     virtual bool Create(const void* data, int type, int width,
     virtual bool Create(const void* data, int type, int width,

-                        int height,
-                        int depth = -1);
-    //@}
+                        int height, int depth = -1);
+
+        NOTE: leave this undoc for the same reason of the relative ctor.
+    */

 
 

-    //@{

     /**
     /**

-        Finds the handler associated with the given bitmap type.
-        
-        @param name
-            The handler name.
+        Finds the handler with the given @a name.
+
+        @returns A pointer to the handler if found, @NULL otherwise.
+    */
+    static wxBitmapHandler* FindHandler(const wxString& name);
+
+    /**
+        Finds the handler associated with the given @a extension and @a type.
+

         @param extension
         @param extension

-            The file extension, such as "bmp".
+            The file extension, such as "bmp" (without the dot).

         @param bitmapType
         @param bitmapType

-            The bitmap type, such as wxBITMAP_TYPE_BMP.
-        
+            The bitmap type managed by the handler, see ::wxBitmapType.
+

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

-        
-        @see wxBitmapHandler

     */
     */

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

     static wxBitmapHandler* FindHandler(const wxString& extension,
                                         wxBitmapType bitmapType);
     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);
     static wxBitmapHandler* FindHandler(wxBitmapType bitmapType);

-    //@}

 
     /**
 
     /**

-        Gets the colour depth of the bitmap. A value of 1 indicates a
-        monochrome bitmap.
+        Gets the colour depth of the bitmap.
+        A value of 1 indicates a monochrome bitmap.

     */
     int GetDepth() const;
 
     /**
         Returns the static list of bitmap format handlers.
     */
     int GetDepth() const;
 
     /**
         Returns the static list of bitmap format handlers.

-        
+

         @see wxBitmapHandler
     */
     static wxList GetHandlers();
         @see wxBitmapHandler
     */
     static wxList GetHandlers();


@@ -415,7 +429,7 @@ public:
     /**
         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.

-        
+

         @see SetMask(), wxMask
     */
     wxMask* GetMask() const;
         @see SetMask(), wxMask
     */
     wxMask* GetMask() const;


@@ -423,7 +437,7 @@ public:
     /**
         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.

-        
+

         @see wxPalette
     */
     wxPalette* GetPalette() const;
         @see wxPalette
     */
     wxPalette* GetPalette() const;


@@ -436,28 +450,29 @@ public:
 
     /**
         Gets the width of the bitmap in pixels.
 
     /**
         Gets the width of the bitmap in pixels.

-        
+

         @see GetHeight()
     */
     int GetWidth() const;
 
     /**
         Adds the standard bitmap format handlers, which, depending on wxWidgets
         @see GetHeight()
     */
     int GetWidth() const;
 
     /**
         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.

-        
+

         @see wxBitmapHandler
     */
     static void InitStandardHandlers();
 
     /**
         Adds a handler at the start of the static list of format handlers.
         @see wxBitmapHandler
     */
     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.
         @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);
         @see wxBitmapHandler
     */
     static void InsertHandler(wxBitmapHandler* handler);


@@ -469,195 +484,65 @@ public:
 
     /**
         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.
         @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
         @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.)
-        
+            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
                  (especially for colour Windows bitmaps), and if the
                  code supports it. You can check if one has been created
         @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.
-        
+                 by using the GetPalette() member.
+

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

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

         @param name
             The handler name.
         @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.

-        
+

         @see wxBitmapHandler
     */
     static bool RemoveHandler(const wxString& name);
 
     /**
         Saves a bitmap in the named file.
         @see wxBitmapHandler
     */
     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
         @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.)
+            One of the ::wxBitmapType values; see the note in the class
+            detailed description.

         @param palette
             An optional palette used for saving the bitmap.
         @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
                  may be available.
         @remarks Depending on how wxWidgets has been configured, not all formats
                  may be available.

-        
+

         @see LoadFile()
     */
     bool SaveFile(const wxString& name, wxBitmapType type,
         @see LoadFile()
     */
     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).

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

         @param depth
             Bitmap depth.
     */
         @param depth
             Bitmap depth.
     */


@@ -665,7 +550,7 @@ public:
 
     /**
         Sets the height member (does not affect the bitmap data).
 
     /**
         Sets the height member (does not affect the bitmap data).

-        
+

         @param height
             Bitmap height in pixels.
     */
         @param height
             Bitmap height in pixels.
     */


@@ -673,49 +558,42 @@ public:
 
     /**
         Sets the mask for this bitmap.
 
     /**
         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.

-        
+

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

-        
+

         @param palette
             The palette to set.
         @param palette
             The palette to set.

-        
+

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

-        
+

         @param width
             Bitmap width in pixels.
     */
     void SetWidth(int width);
 
     /**
         @param width
             Bitmap width in pixels.
     */
     void SetWidth(int width);
 
     /**

-        Assignment operator, using @ref overview_trefcount "reference counting".
-        
+        Assignment operator, using @ref overview_refcount "reference counting".
+

         @param bitmap
             Bitmap to assign.
     */
     wxBitmap operator =(const wxBitmap& bitmap);
 };
 
         @param bitmap
             Bitmap to assign.
     */
     wxBitmap operator =(const wxBitmap& bitmap);
 };
 

-

 /**
 /**

-    FIXME
-*/
-wxBitmap Objects:
-;
-
-/**
-    FIXME
+    An empty wxBitmap object.

 */
 wxBitmap wxNullBitmap;
 
 */
 wxBitmap wxNullBitmap;
 


@@ -727,11 +605,10 @@ wxBitmap wxNullBitmap;
     @wxheader{bitmap.h}
 
     This class encapsulates a monochrome mask bitmap, where the masked area is
     @wxheader{bitmap.h}
 
     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}


@@ -741,47 +618,67 @@ wxBitmap wxNullBitmap;
 class wxMask : public wxObject
 {
 public:
 class wxMask : public wxObject
 {
 public:

-    //@{
+
+    /**
+        Default constructor.
+    */
+    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.
-        
+        background.
+        Not yet implemented for GTK.
+

         @param bitmap
             A valid bitmap.
         @param bitmap
             A valid bitmap.

-        @param colour
-            A colour specifying the transparency RGB values.

         @param index
             Index into a palette, specifying the transparency colour.
     */
         @param index
             Index into a palette, specifying the transparency colour.
     */

-    wxMask();
-    wxMask(const wxBitmap& bitmap);
-    wxMask(const wxBitmap& bitmap,
-           const wxColour& colour);

     wxMask(const wxBitmap& bitmap, int index);
     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.
-        
+        background.
+        Not yet implemented for GTK.
+

         @param bitmap
             A valid bitmap.
         @param bitmap
             A valid bitmap.

-        @param colour
-            A colour specifying the transparency RGB values.

         @param index
             Index into a palette, specifying the transparency colour.
     */
         @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);

+
+    /**
+        Constructs a mask from a bitmap and a colour that indicates the background.
+    */

     bool Create(const wxBitmap& bitmap, const wxColour& colour);
     bool Create(const wxBitmap& bitmap, const wxColour& colour);

-    bool Create(const wxBitmap& bitmap, int index);
-    //@}

 };
 
 };