revised base64.h;bitmap.h

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52553 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

diff --git a/interface/base64.h b/interface/base64.h
index 1aae84304c405573439054b4ec1113fb7c5dec89..ea51aea48d4b5f5df07709710c0f088cd4648153 100644 (file)
--- a/interface/base64.h
+++ b/interface/base64.h
@@ -6,38 +6,69 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 

+
+// ============================================================================
+// Global functions/macros
+// ============================================================================
+
+/** @ingroup group_funcmacro_misc */

 //@{
 //@{

+

 /**
 /**

-    These functions encode the given data using base64. The first of them is the
-    raw encoding function writing the output string into provided buffer while the
-    other ones return the output as wxString. There is no error return for these
-    functions except for the first one which returns @c wxCONV_FAILED if the
-    output buffer is too small. To allocate the buffer of the correct size, use
-    wxBase64EncodedSize() or call this function with
-    @a dst set to @NULL -- it will then return the necessary buffer size.
+    This function encodes the given data using base64.
+
+    To allocate the buffer of the correct size, use wxBase64EncodedSize() or call
+    this function with @a dst set to @NULL -- it will then return the necessary
+    buffer size.
+
+    This raw encoding function overload writes the output string into the
+    provided buffer; the other overloads return it as a wxString.

 
     @param dst
 
     @param dst

-        The output buffer, may be @NULL to retrieve the needed buffer
-        size.
+        The output buffer, may be @NULL to retrieve the needed buffer size.

     @param dstLen
         The output buffer size, ignored if dst is @NULL.
     @param src
         The input buffer, must not be @NULL.
     @param srcLen
         The length of the input data.
     @param dstLen
         The output buffer size, ignored if dst is @NULL.
     @param src
         The input buffer, must not be @NULL.
     @param srcLen
         The length of the input data.

+
+    @returns @c wxCONV_FAILED if the output buffer is too small.

 */
 size_t wxBase64Encode(char* dst, size_t dstLen,
                       const void* src,
                       size_t srcLen);
 */
 size_t wxBase64Encode(char* dst, size_t dstLen,
                       const void* src,
                       size_t srcLen);

+
+/**
+    This function encodes the given data using base64 and returns the output
+    as a wxString.
+
+    There is no error return.
+
+    To allocate the buffer of the correct size, use wxBase64EncodedSize() or call
+    this function with @a dst set to @NULL -- it will then return the necessary
+    buffer size.
+
+    @param src
+        The input buffer, must not be @NULL.
+    @param srcLen
+        The length of the input data.
+*/

 wxString wxBase64Encode(const void* src, size_t srcLen);
 wxString wxBase64Encode(const void* src, size_t srcLen);

+
+/**
+    This function encodes the given data using base64 and returns the output
+    as a wxString.
+
+    There is no error return.
+*/

 wxString wxBase64Encode(const wxMemoryBuffer& buf);
 wxString wxBase64Encode(const wxMemoryBuffer& buf);

-//@}

 
 
 /**
 
 
 /**

-Returns the size of the buffer necessary to contain the data encoded in a
-base64 string of length @e srcLen. This can be useful for allocating a
-buffer to be passed to wxBase64Decode().
+    Returns the size of the buffer necessary to contain the data encoded in a
+    base64 string of length @e srcLen. This can be useful for allocating a
+    buffer to be passed to wxBase64Decode().

 */
 size_t wxBase64DecodedSize(size_t srcLen);
 
 */
 size_t wxBase64DecodedSize(size_t srcLen);
 


@@ -48,41 +79,34 @@ size_t wxBase64DecodedSize(size_t srcLen);
 */
 size_t wxBase64EncodedSize(size_t len);
 
 */
 size_t wxBase64EncodedSize(size_t len);
 

-//@{

 /**
 /**

-    These function decode a Base64-encoded string. The first version is a raw
-    decoding function and decodes the data into the provided buffer @a dst of
-    the given size @e dstLen. An error is returned if the buffer is not large
-    enough -- that is not at least wxBase64DecodedSize(srcLen)()
-    bytes. The second version allocates memory internally and returns it as
-    wxMemoryBuffer and is recommended for normal use.
-    The first version returns the number of bytes written to the buffer or the
+    This function decodes a Base64-encoded string.
+
+    This overload is a raw decoding function and decodes the data into the provided
+    buffer @a dst of the given size @e dstLen. An error is returned if the buffer
+    is not large enough -- that is not at least wxBase64DecodedSize(srcLen)() bytes.
+
+    This overload returns the number of bytes written to the buffer or the

     necessary buffer size if @a dst was @NULL or @c wxCONV_FAILED on
     error, e.g. if the output buffer is too small or invalid characters were
     necessary buffer size if @a dst was @NULL or @c wxCONV_FAILED on
     error, e.g. if the output buffer is too small or invalid characters were

-    encountered in the input string. The second version returns a buffer with the
-    base64 decoded binary equivalent of the input string. In neither case is the
-    buffer NUL-terminated.
+    encountered in the input string.

 
     @param dst
         Pointer to output buffer, may be @NULL to just compute the
         necessary buffer size.
     @param dstLen
 
     @param dst
         Pointer to output buffer, may be @NULL to just compute the
         necessary buffer size.
     @param dstLen

-        The size of the output buffer, ignored if dst is
-        @NULL.
+        The size of the output buffer, ignored if dst is @NULL.

     @param src
         The input string, must not be @NULL. For the version using
         wxString, the input string should contain only ASCII characters.
     @param srcLen
     @param src
         The input string, must not be @NULL. For the version using
         wxString, the input string should contain only ASCII characters.
     @param srcLen

-        The length of the input string or special value
-        wxNO_LEN if the string is NUL-terminated and the length should be
-        computed by this function itself.
+        The length of the input string or special value wxNO_LEN if the string is
+        NUL-terminated and the length should be computed by this function itself.

     @param mode
     @param mode

-        This parameter specifies the function behaviour when invalid
-        characters are encountered in input. By default, any such character stops
-    the
+        This parameter specifies the function behaviour when invalid characters 
+        are encountered in input. By default, any such character stops the

         decoding with error. If the mode is wxBase64DecodeMode_SkipWS, then the
         decoding with error. If the mode is wxBase64DecodeMode_SkipWS, then the

-    white
-        space characters are silently skipped instead. And if it is
+        white space characters are silently skipped instead. And if it is

         wxBase64DecodeMode_Relaxed, then all invalid characters are skipped.
     @param posErr
         If this pointer is non-@NULL and an error occurs during
         wxBase64DecodeMode_Relaxed, then all invalid characters are skipped.
     @param posErr
         If this pointer is non-@NULL and an error occurs during


@@ -93,12 +117,32 @@ size_t wxBase64Decode(void* dst, size_t dstLen,
                       size_t srcLen = wxNO_LEN,
                       wxBase64DecodeMode mode = wxBase64DecodeMode_Strict,
                       size_t posErr = NULL);
                       size_t srcLen = wxNO_LEN,
                       wxBase64DecodeMode mode = wxBase64DecodeMode_Strict,
                       size_t posErr = NULL);

+
+/**
+    See the wxBase64Decode(void*,size_t,const char*,size_t,wxBase64DecodeMode,size_t)
+    overload for more info about the parameters of this function.
+
+    This overload allocates memory internally and returns it as wxMemoryBuffer
+    and is recommended for normal use.
+
+    This overload returns a buffer with the base64 decoded binary equivalent 
+    of the input string. In neither case is the buffer @NULL-terminated.
+*/

 wxMemoryBuffer wxBase64Decode(const char* src,
                               size_t srcLen = wxNO_LEN,
                               wxBase64DecodeMode mode = wxBase64DecodeMode_Strict,
                               size_t posErr = NULL);
 wxMemoryBuffer wxBase64Decode(const char* src,
                               size_t srcLen = wxNO_LEN,
                               wxBase64DecodeMode mode = wxBase64DecodeMode_Strict,
                               size_t posErr = NULL);

+
+/**
+    See the wxBase64Decode(void*,size_t,const char*,size_t,wxBase64DecodeMode,size_t)
+    overload for more info about the parameters of this function.
+
+    This overload takes as input a wxString and returns the internally-allocated
+    memory as a wxMemoryBuffer, containing the base64 decoded data.
+*/

 wxMemoryBuffer wxBase64Decode(const wxString& src,
                               wxBase64DecodeMode mode = wxBase64DecodeMode_Strict,
                               size_t posErr = NULL);
 wxMemoryBuffer wxBase64Decode(const wxString& src,
                               wxBase64DecodeMode mode = wxBase64DecodeMode_Strict,
                               size_t posErr = NULL);

+

 //@}
 
 //@}
 

diff --git a/interface/bitmap.h b/interface/bitmap.h
index 22710d45ca4b552faa01385e9c4e686a14ce3ff5..01d43706b56d7b146472b9c240c24f7a4e760617 100644 (file)
--- a/interface/bitmap.h
+++ b/interface/bitmap.h
@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // 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


@@ -10,28 +10,27 @@
     @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 +40,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


@@ -56,15 +54,15 @@ public:
         @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.

-        
+
+@todo why type is an int and not a wxBitmapType?
+

         @returns @true if the call succeeded, @false otherwise (the default).
     */
     virtual bool Create(wxBitmap* bitmap, const void* data, int type,
         @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);
+                        int width, int height, int depth = -1);

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


@@ -78,13 +76,14 @@ public:
 
     /**
         Gets the bitmap type associated with this handler.
 
     /**
         Gets the bitmap type associated with this handler.

+@todo why type is an int and not a wxBitmapType?

     */
     long GetType() const;
 
     /**
     */
     long 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
         @param bitmap
             The bitmap object which is to be affected by this operation.
         @param name


@@ -92,16 +91,18 @@ public:
             The meaning of name is determined by the type parameter.
         @param type
             See wxBitmap::wxBitmap for values this can take.
             The meaning of name is determined by the type parameter.
         @param type
             See wxBitmap::wxBitmap for values this can take.

-        
+

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

-        
+
+@todo why type is an int and not a wxBitmapType?
+

         @see wxBitmap::LoadFile, wxBitmap::SaveFile, SaveFile()
     */
     bool LoadFile(wxBitmap* bitmap, const wxString& name, long type);
 
     /**
         Saves a bitmap in the named file.
         @see wxBitmap::LoadFile, wxBitmap::SaveFile, SaveFile()
     */
     bool LoadFile(wxBitmap* bitmap, const wxString& name, long type);
 
     /**
         Saves a bitmap in the named file.

-        
+

         @param bitmap
             The bitmap object which is to be affected by this operation.
         @param name
         @param bitmap
             The bitmap object which is to be affected by this operation.
         @param name


@@ -110,9 +111,11 @@ public:
             See wxBitmap::wxBitmap for values this can take.
         @param palette
             An optional palette used for saving the bitmap.
             See wxBitmap::wxBitmap 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.

-        
+
+@todo why type is an int and not a wxBitmapType?
+

         @see wxBitmap::LoadFile, wxBitmap::SaveFile, LoadFile()
     */
     bool SaveFile(wxBitmap* bitmap, const wxString& name, int type,
         @see wxBitmap::LoadFile, wxBitmap::SaveFile, LoadFile()
     */
     bool SaveFile(wxBitmap* bitmap, const wxString& name, int type,


@@ -120,7 +123,7 @@ public:
 
     /**
         Sets the handler extension.
 
     /**
         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,16 @@ public:
 
     /**
         Sets the handler type.
 
     /**
         Sets the handler type.

-        
-        @param name
+
+@todo why type is an int and not a wxBitmapType?
+
+        @param type

             Handler type.
     */
     void SetType(long type);
 };
 
 
             Handler type.
     */
     void SetType(long type);
 };
 
 

-

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


@@ -152,36 +156,82 @@ 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.
+
+@todo why type is an int and not a wxBitmapType?
+
+    */
+    wxBitmap(const void* data, int type, int width, int height, int depth = -1);
+
+    /**
+        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 +239,84 @@ 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, the display depth of the screen is used.
+    */
+    wxBitmap(const char bits[], int width, int height, int depth = 1);
+
+    /**
+        Creates a new bitmap. A depth of -1 indicates the depth of the current
+        screen or visual. Some platforms only support 1 for monochrome and -1 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 = -1);
+
+    /**
+        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.
-        @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.
-        
+            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()
     */
         @see LoadFile()
     */

-    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 wxString& name, long type);

+
+    /**
+        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.
+
+        @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(const wxImage& img, int depth = -1);
     wxBitmap(const wxImage& img, int depth = -1);

-    //@}
+

 
     /**
         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,55 +339,70 @@ 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 = -1);
+

     /**
         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()
+
+        This overload depends on the @a type of data.

     */
     */

-    virtual bool Create(int width, int height, int depth = -1);
+

     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);

 
 

-    //@{

     /**
     /**

-        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
 
     /**
         Gets the colour depth of the bitmap. A value of 1 indicates a


@@ -402,7 +412,7 @@ public:
 
     /**
         Returns the static list of bitmap format handlers.
 
     /**
         Returns the static list of bitmap format handlers.

-        
+

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


@@ -415,7 +425,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 +433,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 +446,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,187 +480,54 @@ 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,


@@ -657,7 +535,10 @@ public:
 
     /**
         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 +546,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 +554,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 +601,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 +614,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);
-    //@}

 };
 
 };
 

diff --git a/interface/gdicmn.h b/interface/gdicmn.h
index b74721661847e224905963638c4e5a4e350cfeca..2160ab0be559ca526304fb015d830f6c9750dff7 100644 (file)
--- a/interface/gdicmn.h
+++ b/interface/gdicmn.h
@@ -6,6 +6,93 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 

+
+/**
+    Bitmap flags.
+*/
+enum wxBitmapType
+{
+    wxBITMAP_TYPE_INVALID,
+    wxBITMAP_TYPE_BMP,
+    wxBITMAP_TYPE_BMP_RESOURCE,
+    wxBITMAP_TYPE_RESOURCE = wxBITMAP_TYPE_BMP_RESOURCE,
+    wxBITMAP_TYPE_ICO,
+    wxBITMAP_TYPE_ICO_RESOURCE,
+    wxBITMAP_TYPE_CUR,
+    wxBITMAP_TYPE_CUR_RESOURCE,
+    wxBITMAP_TYPE_XBM,
+    wxBITMAP_TYPE_XBM_DATA,
+    wxBITMAP_TYPE_XPM,
+    wxBITMAP_TYPE_XPM_DATA,
+    wxBITMAP_TYPE_TIF,
+    wxBITMAP_TYPE_TIF_RESOURCE,
+    wxBITMAP_TYPE_GIF,
+    wxBITMAP_TYPE_GIF_RESOURCE,
+    wxBITMAP_TYPE_PNG,
+    wxBITMAP_TYPE_PNG_RESOURCE,
+    wxBITMAP_TYPE_JPEG,
+    wxBITMAP_TYPE_JPEG_RESOURCE,
+    wxBITMAP_TYPE_PNM,
+    wxBITMAP_TYPE_PNM_RESOURCE,
+    wxBITMAP_TYPE_PCX,
+    wxBITMAP_TYPE_PCX_RESOURCE,
+    wxBITMAP_TYPE_PICT,
+    wxBITMAP_TYPE_PICT_RESOURCE,
+    wxBITMAP_TYPE_ICON,
+    wxBITMAP_TYPE_ICON_RESOURCE,
+    wxBITMAP_TYPE_ANI,
+    wxBITMAP_TYPE_IFF,
+    wxBITMAP_TYPE_TGA,
+    wxBITMAP_TYPE_MACCURSOR,
+    wxBITMAP_TYPE_MACCURSOR_RESOURCE,
+    wxBITMAP_TYPE_ANY = 50
+};
+
+/**
+    Standard cursors.
+*/
+enum wxStockCursor
+{
+    wxCURSOR_NONE,
+    wxCURSOR_ARROW,
+    wxCURSOR_RIGHT_ARROW,
+    wxCURSOR_BULLSEYE,
+    wxCURSOR_CHAR,
+    wxCURSOR_CROSS,
+    wxCURSOR_HAND,
+    wxCURSOR_IBEAM,
+    wxCURSOR_LEFT_BUTTON,
+    wxCURSOR_MAGNIFIER,
+    wxCURSOR_MIDDLE_BUTTON,
+    wxCURSOR_NO_ENTRY,
+    wxCURSOR_PAINT_BRUSH,
+    wxCURSOR_PENCIL,
+    wxCURSOR_POINT_LEFT,
+    wxCURSOR_POINT_RIGHT,
+    wxCURSOR_QUESTION_ARROW,
+    wxCURSOR_RIGHT_BUTTON,
+    wxCURSOR_SIZENESW,
+    wxCURSOR_SIZENS,
+    wxCURSOR_SIZENWSE,
+    wxCURSOR_SIZEWE,
+    wxCURSOR_SIZING,
+    wxCURSOR_SPRAYCAN,
+    wxCURSOR_WAIT,
+    wxCURSOR_WATCH,
+    wxCURSOR_BLANK,
+    wxCURSOR_DEFAULT,       //!< standard X11 cursor
+    wxCURSOR_COPY_ARROW ,   //!< MacOS Theme Plus arrow
+    // Not yet implemented for Windows
+    wxCURSOR_CROSS_REVERSE,
+    wxCURSOR_DOUBLE_ARROW,
+    wxCURSOR_BASED_ARROW_UP,
+    wxCURSOR_BASED_ARROW_DOWN,
+    wxCURSOR_ARROWWAIT,
+    wxCURSOR_MAX
+};
+
+
+

 /**
     @class wxRealPoint
     @wxheader{gdicmn.h}
 /**
     @class wxRealPoint
     @wxheader{gdicmn.h}