mac paths updated

[wxWidgets.git] / interface / bitmap.h

diff --git a/interface/bitmap.h b/interface/bitmap.h
index 01d43706b56d7b146472b9c240c24f7a4e760617..1bcf959e19af98c378fab2c040e562b82ee5b045 100644 (file)
--- a/interface/bitmap.h
+++ b/interface/bitmap.h
@@ -6,6 +6,12 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // 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}


@@ -15,7 +21,7 @@
     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}


@@ -37,7 +43,7 @@ public:
     /**
         Destroys the wxBitmapHandler object.
     */
     /**
         Destroys the wxBitmapHandler object.
     */

-    ~wxBitmapHandler();
+    virtual ~wxBitmapHandler();

 
     /**
         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.


@@ -50,35 +56,33 @@ 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
             A bitmap type identifier - see ::wxBitmapType for a list
             of possible values.
 
         @param data
             Data whose type depends on the value of type.
         @param type
             A bitmap type identifier - see ::wxBitmapType for a list
             of possible values.
 

-@todo why type is an int and not a wxBitmapType?
-
-        @returns @true if the call succeeded, @false otherwise (the default).
+        @return @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 = 1);

 
     /**
         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.

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

     */
     */

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

 
     /**
         Loads a bitmap from a file or resource, putting the resulting data into
 
     /**
         Loads a bitmap from a file or resource, putting the resulting data into


@@ -90,15 +94,18 @@ public:
             Either a filename or a Windows resource name.
             The meaning of name is determined by the type parameter.
         @param type
             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.
-
-        @returns @true if the operation succeeded, @false otherwise.
+            See ::wxBitmapType for values this can take.
+        @param desiredWidth
+            The desired width for the loaded bitmap.
+        @param desiredHeight
+            The desired height for the loaded bitmap.

 
 

-@todo why type is an int and not a wxBitmapType?
+        @return @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);
+    virtual bool LoadFile(wxBitmap* bitmap, const wxString& name, wxBitmapType type,
+                          int desiredWidth, int desiredHeight);

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


@@ -108,18 +115,16 @@ public:
         @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

-            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.
-
-@todo why type is an int and not a wxBitmapType?
+        @return @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,
-                  wxPalette* palette = NULL);
+    virtual bool SaveFile(const wxBitmap* bitmap, const wxString& name, wxBitmapType type,
+                          const wxPalette* palette = NULL) const;

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


@@ -140,12 +145,10 @@ public:
     /**
         Sets the handler type.
 
     /**
         Sets the handler type.
 

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

         @param type
             Handler type.
     */
         @param type
             Handler type.
     */

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

 };
 
 
 };
 
 


@@ -155,10 +158,15 @@ 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.

+    
+    If you need direct access the bitmap data instead going through
+    drawing to it using wxMemoryDC you need to use the wxPixelData
+    class (either wxNativePixelData for RGB bitmaps or wxAlphaPixelData
+    for bitmaps with an additionaly alpha channel).

 
     @note
 
     @note

-    Many wxBitmap functions take a @e type parameter, which is a value of
-    the ::wxBitmapType enumeration.
+    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,
     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,


@@ -175,7 +183,7 @@ public:
     ::wxNullBitmap
 
     @see @ref overview_bitmap, @ref overview_bitmap_supportedformats,
     ::wxNullBitmap
 
     @see @ref overview_bitmap, @ref overview_bitmap_supportedformats,

-         wxDC::Blit, wxIcon, wxCursor, wxBitmap, wxMemoryDC
+         wxDC::Blit, wxIcon, wxCursor, wxMemoryDC, wxImage, wxPixelData

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


@@ -199,7 +207,8 @@ public:
     */
     wxBitmap(const wxBitmap& bitmap);
 
     */
     wxBitmap(const wxBitmap& bitmap);
 

-    /**
+
+    /*

         Creates a bitmap from the given @a data which is interpreted in
         platform-dependent manner.
 
         Creates a bitmap from the given @a data which is interpreted in
         platform-dependent manner.
 


@@ -216,11 +225,13 @@ public:
         @param depth
             Specifies the depth of the bitmap.
             If this is omitted, the display depth of the screen is used.
         @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);

 
 

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

 
 

+        NOTE: this ctor is not implemented by all ports, is somewhat useless
+              without further description of the "data" supported formats and
+              uses 'int type' instead of wxBitmapType, so don't document it.

     */
     */

-    wxBitmap(const void* data, int type, int width, int height, int depth = -1);

 
     /**
         Creates a bitmap from the given array @a bits.
 
     /**
         Creates a bitmap from the given array @a bits.


@@ -229,8 +240,9 @@ public:
 
         For other bit depths, the behaviour is platform dependent: under Windows,
         the data is passed without any changes to the underlying CreateBitmap() API.
 
         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.
+        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 bits
             Specifies an array of pixel values.


@@ -240,18 +252,20 @@ public:
             Specifies the height of the bitmap.
         @param depth
             Specifies the depth of the bitmap.
             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.
+            If this is omitted, then a value of 1 (monochrome bitmap) is used.

     */
     wxBitmap(const char bits[], int width, int height, int depth = 1);
 
     /**
     */
     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
+        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+.
     */
         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);
+    wxBitmap(int width, int height, int depth = wxBITMAP_SCREEN_DEPTH);

 
     /**
         Creates a bitmap from XPM data.
 
     /**
         Creates a bitmap from XPM data.


@@ -270,15 +284,16 @@ public:
 
         @see LoadFile()
     */
 
         @see LoadFile()
     */

-    wxBitmap(const wxString& name, long type);
+    wxBitmap(const wxString& name, wxBitmapType type = wxBITMAP_TYPE_XPM);

 
     /**
 
     /**

-        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.
+        Creates this bitmap object from the given image.
+        This has to be done to actually display an image as you cannot draw an
+        image directly on a window.

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

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

 
         When in 8-bit mode (PseudoColour mode), the GTK port will use a color cube
         created on program start-up to look up colors. This ensures a very fast conversion,
 
         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,


@@ -295,8 +310,7 @@ public:
             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 wxImage& img, int depth = -1);
-
+    wxBitmap(const wxImage& img, int depth = wxBITMAP_SCREEN_DEPTH);

 
     /**
         Destructor.
 
     /**
         Destructor.


@@ -308,7 +322,7 @@ public:
         @warning
         Do not delete a bitmap that is selected into a memory device context.
     */
         @warning
         Do not delete a bitmap that is selected into a memory device context.
     */

-    ~wxBitmap();
+    virtual ~wxBitmap();

 
     /**
         Adds a handler to the end of the static list of format handlers.
 
     /**
         Adds a handler to the end of the static list of format handlers.


@@ -332,13 +346,12 @@ public:
         mask information so that bitmaps and images can be converted back
         and forth without loss in that respect.
     */
         mask information so that bitmaps and images can be converted back
         and forth without loss in that respect.
     */

-    wxImage ConvertToImage();
+    virtual wxImage ConvertToImage() const;

 
     /**
         Creates the bitmap from an icon.
     */
 
     /**
         Creates the bitmap from an icon.
     */

-    bool CopyFromIcon(const wxIcon& icon);
-
+    virtual bool CopyFromIcon(const wxIcon& icon);

 
     /**
         Creates a fresh bitmap.
 
     /**
         Creates a fresh bitmap.


@@ -346,9 +359,9 @@ public:
 
         This overload works on all platforms.
     */
 
         This overload works on all platforms.
     */

-    virtual bool Create(int width, int height, int depth = -1);
+    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.
 
         @param data
         Creates a bitmap from the given data, which can be of arbitrary type.
 
         @param data


@@ -363,18 +376,20 @@ public:
         @param depth
             The depth of the bitmap in pixels. If this is -1, the screen depth is used.
 
         @param depth
             The depth of the bitmap in pixels. If this is -1, the screen depth is used.
 

-        @returns @true if the call succeeded, @false otherwise.
+        @return @true if the call succeeded, @false otherwise.

 
         This overload depends on the @a type of data.
 
         This overload depends on the @a type of data.

-    */

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

+        NOTE: leave this undoc for the same reason of the relative ctor.
+    */
+

     /**
         Finds the handler with the given @a name.
 
     /**
         Finds the handler with the given @a name.
 

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

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


@@ -386,7 +401,7 @@ public:
         @param bitmapType
             The bitmap type managed by the handler, see ::wxBitmapType.
 
         @param bitmapType
             The bitmap type managed by the handler, see ::wxBitmapType.
 

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

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


@@ -397,7 +412,7 @@ public:
         @param bitmapType
             The bitmap type managed by the handler, see ::wxBitmapType.
 
         @param bitmapType
             The bitmap type managed by the handler, see ::wxBitmapType.
 

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

 
         @see wxBitmapHandler
     */
 
         @see wxBitmapHandler
     */


@@ -405,10 +420,10 @@ public:
     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;
+    virtual int GetDepth() const;

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


@@ -420,7 +435,7 @@ public:
     /**
         Gets the height of the bitmap in pixels.
     */
     /**
         Gets the height of the bitmap in pixels.
     */

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

 
     /**
         Gets the associated mask (if any) which may have been loaded from a file
 
     /**
         Gets the associated mask (if any) which may have been loaded from a file


@@ -428,7 +443,7 @@ public:
 
         @see SetMask(), wxMask
     */
 
         @see SetMask(), wxMask
     */

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

 
     /**
         Gets the associated palette (if any) which may have been loaded from a file
 
     /**
         Gets the associated palette (if any) which may have been loaded from a file


@@ -436,20 +451,20 @@ public:
 
         @see wxPalette
     */
 
         @see wxPalette
     */

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

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

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

 
     /**
         Gets the width of the bitmap in pixels.
 
         @see GetHeight()
     */
 
     /**
         Gets the width of the bitmap in pixels.
 
         @see GetHeight()
     */

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

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


@@ -488,7 +503,7 @@ public:
             One of the ::wxBitmapType values; see the note in the class
             detailed description.
 
             One of the ::wxBitmapType values; see the note in the class
             detailed description.
 

-        @returns @true if the operation succeeded, @false otherwise.
+        @return @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
 
         @remarks A palette may be associated with the bitmap if one exists
                  (especially for colour Windows bitmaps), and if the


@@ -497,7 +512,7 @@ public:
 
         @see SaveFile()
     */
 
         @see SaveFile()
     */

-    bool LoadFile(const wxString& name, wxBitmapType type);
+    virtual bool LoadFile(const wxString& name, wxBitmapType type);

 
     /**
         Finds the handler with the given name, and removes it.
 
     /**
         Finds the handler with the given name, and removes it.


@@ -506,7 +521,7 @@ public:
         @param name
             The handler name.
 
         @param name
             The handler name.
 

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

 
         @see wxBitmapHandler
     */
 
         @see wxBitmapHandler
     */


@@ -523,15 +538,15 @@ public:
         @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.
+        @return @true if the operation succeeded, @false otherwise.

 
         @remarks Depending on how wxWidgets has been configured, not all formats
                  may be available.
 
         @see LoadFile()
     */
 
         @remarks Depending on how wxWidgets has been configured, not all formats
                  may be available.
 
         @see LoadFile()
     */

-    bool SaveFile(const wxString& name, wxBitmapType type,
-                  wxPalette* palette = NULL);
+    virtual bool SaveFile(const wxString& name, wxBitmapType type,
+                          const wxPalette* palette = NULL) const;

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


@@ -542,7 +557,7 @@ public:
         @param depth
             Bitmap depth.
     */
         @param depth
             Bitmap depth.
     */

-    void SetDepth(int depth);
+    virtual void SetDepth(int depth);

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


@@ -550,7 +565,7 @@ public:
         @param height
             Bitmap height in pixels.
     */
         @param height
             Bitmap height in pixels.
     */

-    void SetHeight(int height);
+    virtual void SetHeight(int height);

 
     /**
         Sets the mask for this bitmap.
 
     /**
         Sets the mask for this bitmap.


@@ -559,7 +574,7 @@ public:
 
         @see GetMask(), wxMask
     */
 
         @see GetMask(), wxMask
     */

-    void SetMask(wxMask* mask);
+    virtual void SetMask(wxMask* mask);

 
     /**
         Sets the associated palette. (Not implemented under GTK+).
 
     /**
         Sets the associated palette. (Not implemented under GTK+).


@@ -569,7 +584,7 @@ public:
 
         @see wxPalette
     */
 
         @see wxPalette
     */

-    void SetPalette(const wxPalette& palette);
+    virtual void SetPalette(const wxPalette& palette);

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


@@ -577,15 +592,7 @@ public:
         @param width
             Bitmap width in pixels.
     */
         @param width
             Bitmap width in pixels.
     */

-    void SetWidth(int width);
-
-    /**
-        Assignment operator, using @ref overview_refcount "reference counting".
-
-        @param bitmap
-            Bitmap to assign.
-    */
-    wxBitmap operator =(const wxBitmap& bitmap);
+    virtual void SetWidth(int width);

 };
 
 /**
 };
 
 /**


@@ -653,7 +660,7 @@ public:
     /**
         Destroys the wxMask object and the underlying bitmap data.
     */
     /**
         Destroys the wxMask object and the underlying bitmap data.
     */

-    ~wxMask();
+    virtual ~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