declare future-deprecated SetStyle(int) in wxPen/Brush and not wxPen/BrushBase as...

[wxWidgets.git] / interface / image.h

diff --git a/interface/image.h b/interface/image.h
index 74d814fde76a5326f1d93b4114287fb2faa0cdac..ef66408ff0f3542516d9a66bab54c2ec8626b9ad 100644 (file)
--- a/interface/image.h
+++ b/interface/image.h
@@ -25,6 +25,8 @@
     @category{FIXME}
 
     @see wxImage, wxInitAllImageHandlers()
     @category{FIXME}
 
     @see wxImage, wxInitAllImageHandlers()

+
+    @todo Document all image handler types, indicating their library.

 */
 class wxImageHandler : public wxObject
 {
 */
 class wxImageHandler : public wxObject
 {


@@ -54,7 +56,7 @@ public:
             Opened input stream for reading image data. Currently, the stream must
         support seeking.
 
             Opened input stream for reading image data. Currently, the stream must
         support seeking.
 

-        @returns Number of available images. For most image handlers, this is 1
+        @return Number of available images. For most image handlers, this is 1

                  (exceptions are TIFF and ICO formats).
     */
     int GetImageCount(wxInputStream& stream);
                  (exceptions are TIFF and ICO formats).
     */
     int GetImageCount(wxInputStream& stream);


@@ -72,7 +74,7 @@ public:
     /**
         Gets the image type associated with this handler.
     */
     /**
         Gets the image type associated with this handler.
     */

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

 
     /**
         Loads a image from a stream, putting the resulting data into @e image. If the
 
     /**
         Loads a image from a stream, putting the resulting data into @e image. If the


@@ -91,7 +93,7 @@ public:
         @param index
             The index of the image in the file (starting from zero).
 
         @param index
             The index of the image in the file (starting from zero).
 

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

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


@@ -106,7 +108,7 @@ public:
         @param stream
             Opened output stream for writing the data.
 
         @param stream
             Opened output stream for writing the data.
 

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

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


@@ -168,16 +170,16 @@ public:
 class wxImage : public wxObject
 {
 public:
 class wxImage : public wxObject
 {
 public:

-    
+

     /**
          Creates an empty wxImage object without an alpha channel.
     */
     wxImage();
     /**
          Creates an empty wxImage object without an alpha channel.
     */
     wxImage();

-    
+

     /**
          Creates an image with the given size and clears it if requested.
          Does not create an alpha channel.
     /**
          Creates an image with the given size and clears it if requested.
          Does not create an alpha channel.

-         
+

         @param width
             Specifies the width of the image.
         @param height
         @param width
             Specifies the width of the image.
         @param height


@@ -186,12 +188,12 @@ public:
             Clear the image with zeros.
     */
     wxImage(int width, int height, bool clear = true);
             Clear the image with zeros.
     */
     wxImage(int width, int height, bool clear = true);

-    
+

     /**
         Creates an image from data in memory. If static_data is false
         then the wxImage will take ownership of the data and free it
         afterwards. For this, it has to be allocated with @e malloc.
     /**
         Creates an image from data in memory. If static_data is false
         then the wxImage will take ownership of the data and free it
         afterwards. For this, it has to be allocated with @e malloc.

-    
+

         @param width
             Specifies the width of the image.
         @param height
         @param width
             Specifies the width of the image.
         @param height


@@ -200,15 +202,15 @@ public:
             A pointer to RGB data
         @param static_data
             Indicates if the data should be free'd after use
             A pointer to RGB data
         @param static_data
             Indicates if the data should be free'd after use

-        
+

     */
     wxImage(int width, int height, unsigned char* data,  bool static_data = false);
     */
     wxImage(int width, int height, unsigned char* data,  bool static_data = false);

-    
+

     /**
         Creates an image from data in memory. If static_data is false
         then the wxImage will take ownership of the data and free it
         afterwards. For this, it has to be allocated with @e malloc.
     /**
         Creates an image from data in memory. If static_data is false
         then the wxImage will take ownership of the data and free it
         afterwards. For this, it has to be allocated with @e malloc.

-    
+

         @param width
             Specifies the width of the image.
         @param height
         @param width
             Specifies the width of the image.
         @param height


@@ -219,21 +221,21 @@ public:
             A pointer to alpha-channel data
         @param static_data
             Indicates if the data should be free'd after use
             A pointer to alpha-channel data
         @param static_data
             Indicates if the data should be free'd after use

-        
+

     */
     wxImage(int width, int height, unsigned char* data, unsigned char* alpha, bool static_data = false );
     */
     wxImage(int width, int height, unsigned char* data, unsigned char* alpha, bool static_data = false );

-    
+

     /**
         Creates an image from XPM data.
     /**
         Creates an image from XPM data.

-        
+

         @param xpmData
             A pointer to XPM image data.
     */
     wxImage(const char* const* xpmData);
         @param xpmData
             A pointer to XPM image data.
     */
     wxImage(const char* const* xpmData);

-    
+

     /**
         Creates an image from a file.
     /**
         Creates an image from a file.

-    
+

         @param name
             Name of the file from which to load the image.
         @param type
         @param name
             Name of the file from which to load the image.
         @param type


@@ -263,11 +265,11 @@ public:
 
         @see LoadFile()
     */
 
         @see LoadFile()
     */

-    wxImage(const wxString& name, long type = wxBITMAP_TYPE_ANY, int index = -1);
-    
+    wxImage(const wxString& name, wxBitmapType type = wxBITMAP_TYPE_ANY, int index = -1);
+

     /**
         Creates an image from a file using MIME-types to specify the type.
     /**
         Creates an image from a file using MIME-types to specify the type.

-    
+

         @param name
             Name of the file from which to load the image.
         @param type
         @param name
             Name of the file from which to load the image.
         @param type


@@ -278,10 +280,10 @@ public:
             See above
     */
     wxImage(const wxString& name, const wxString& mimetype, int index = -1);
             See above
     */
     wxImage(const wxString& name, const wxString& mimetype, int index = -1);

-    
+

     /**
         Creates an image from a stream.
     /**
         Creates an image from a stream.

-    
+

         @param stream
             Opened input stream from which to load the image. Currently,
             the stream must support seeking.
         @param stream
             Opened input stream from which to load the image. Currently,
             the stream must support seeking.


@@ -290,11 +292,11 @@ public:
         @param index
             See above.
     */
         @param index
             See above.
     */

-    wxImage(wxInputStream& stream, long type = wxBITMAP_TYPE_ANY, int index = -1);    
-    
+    wxImage(wxInputStream& stream, wxBitmapType type = wxBITMAP_TYPE_ANY, int index = -1);
+

     /**
         Creates an image from a stream using MIME-types to specify the type.
     /**
         Creates an image from a stream using MIME-types to specify the type.

-    
+

         @param stream
             Opened input stream from which to load the image. Currently,
             the stream must support seeking.
         @param stream
             Opened input stream from which to load the image. Currently,
             the stream must support seeking.


@@ -304,7 +306,7 @@ public:
             See above.
     */
     wxImage(wxInputStream& stream, const wxString& mimetype, int index = -1);
             See above.
     */
     wxImage(wxInputStream& stream, const wxString& mimetype, int index = -1);

-    
+

 
     /**
         Destructor.
 
     /**
         Destructor.


@@ -342,7 +344,7 @@ public:
         @see Blur(), BlurHorizontal()
     */
     wxImage BlurVertical(int blurRadius);
         @see Blur(), BlurHorizontal()
     */
     wxImage BlurVertical(int blurRadius);

-    
+

     /**
         Returns @true if the current image handlers can read this file
     */
     /**
         Returns @true if the current image handlers can read this file
     */


@@ -359,7 +361,7 @@ public:
         wxImageHistogram object. wxImageHistogram is a specialization of
         wxHashMap "template" and is defined as follows:
 
         wxImageHistogram object. wxImageHistogram is a specialization of
         wxHashMap "template" and is defined as follows:
 

-        @returns Returns number of colours in the histogram.
+        @return Returns number of colours in the histogram.

     */
     unsigned long ComputeHistogram(wxImageHistogram& histogram) const;
 
     */
     unsigned long ComputeHistogram(wxImageHistogram& histogram) const;
 


@@ -371,7 +373,7 @@ public:
         If the image image doesn't have alpha channel,
         ConvertAlphaToMask does nothing.
 
         If the image image doesn't have alpha channel,
         ConvertAlphaToMask does nothing.
 

-        @returns @false if FindFirstUnusedColour returns @false, @true otherwise.
+        @return @false if FindFirstUnusedColour returns @false, @true otherwise.

     */
     bool ConvertAlphaToMask(unsigned char threshold = 128);
 
     */
     bool ConvertAlphaToMask(unsigned char threshold = 128);
 


@@ -413,7 +415,7 @@ public:
         @param height
             The height of the image in pixels.
 
         @param height
             The height of the image in pixels.
 

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

     */
     bool Create(int width, int height, bool clear = true);
 
     */
     bool Create(int width, int height, bool clear = true);
 


@@ -429,7 +431,7 @@ public:
             Initial values of the colour. Returned colour
             will have RGB values equal to or greater than these.
 
             Initial values of the colour. Returned colour
             will have RGB values equal to or greater than these.
 

-        @returns Returns @false if there is no unused colour left, @true on success.
+        @return Returns @false if there is no unused colour left, @true on success.

     */
     bool FindFirstUnusedColour(unsigned char* r, unsigned char* g,
                                unsigned char* b,
     */
     bool FindFirstUnusedColour(unsigned char* r, unsigned char* g,
                                unsigned char* b,


@@ -450,14 +452,14 @@ public:
         @param mimetype
             MIME type.
 
         @param mimetype
             MIME type.
 

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

 
         @see wxImageHandler
     */
     static wxImageHandler* FindHandler(const wxString& name);
     static wxImageHandler* FindHandler(const wxString& extension,
 
         @see wxImageHandler
     */
     static wxImageHandler* FindHandler(const wxString& name);
     static wxImageHandler* FindHandler(const wxString& extension,

-                                       long imageType);
-    static wxImageHandler* FindHandler(long imageType);
+                                       wxBitmapType imageType);
+    static wxImageHandler* FindHandler(wxBitmapType imageType);

     static wxImageHandler* FindHandlerMime(const wxString& mimetype);
     //@}
 
     static wxImageHandler* FindHandlerMime(const wxString& mimetype);
     //@}
 


@@ -465,7 +467,7 @@ public:
         Return alpha value at given pixel location.
     */
     unsigned char GetAlpha(int x, int y) const;
         Return alpha value at given pixel location.
     */
     unsigned char GetAlpha(int x, int y) const;

-    
+

     /**
         Returns pointer to the array storing the alpha values for this image. This
         pointer is @NULL for the images without the alpha channel. If the image
     /**
         Returns pointer to the array storing the alpha values for this image. This
         pointer is @NULL for the images without the alpha channel. If the image


@@ -536,13 +538,13 @@ public:
             @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI).
             @li wxBITMAP_TYPE_ANY: Will try to autodetect the format.
 
             @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI).
             @li wxBITMAP_TYPE_ANY: Will try to autodetect the format.
 

-        @returns Number of available images. For most image handlers, this is 1
+        @return Number of available images. For most image handlers, this is 1

                  (exceptions are TIFF and ICO formats).
     */
     static int GetImageCount(const wxString& filename,
                  (exceptions are TIFF and ICO formats).
     */
     static int GetImageCount(const wxString& filename,

-                             long type = wxBITMAP_TYPE_ANY);
+                             wxBitmapType type = wxBITMAP_TYPE_ANY);

     static int GetImageCount(wxInputStream& stream,
     static int GetImageCount(wxInputStream& stream,

-                             long type = wxBITMAP_TYPE_ANY);
+                             wxBitmapType type = wxBITMAP_TYPE_ANY);

     //@}
 
     /**
     //@}
 
     /**


@@ -550,7 +552,7 @@ public:
         file extension masks
         suitable for passing to file open/save dialog boxes.
 
         file extension masks
         suitable for passing to file open/save dialog boxes.
 

-        @returns The format of the returned string is
+        @return The format of the returned string is

                  "(*.ext1;*.ext2)|*.ext1;*.ext2".
 
         @see wxImageHandler
                  "(*.ext1;*.ext2)|*.ext1;*.ext2".
 
         @see wxImageHandler


@@ -583,12 +585,12 @@ public:
 
     /**
         Gets a user-defined option as an integer. The function is case-insensitive
 
     /**
         Gets a user-defined option as an integer. The function is case-insensitive

-        to @e name. If the given option is not present, the function returns 0. 
+        to @e name. If the given option is not present, the function returns 0.

         Use HasOption() is 0 is a possibly valid value for the option.
         Options for wxPNGHandler
         @li wxIMAGE_OPTION_PNG_FORMAT: Format for saving a PNG file.
         @li wxIMAGE_OPTION_PNG_BITDEPTH: Bit depth for every channel (R/G/B/A).
         Use HasOption() is 0 is a possibly valid value for the option.
         Options for wxPNGHandler
         @li wxIMAGE_OPTION_PNG_FORMAT: Format for saving a PNG file.
         @li wxIMAGE_OPTION_PNG_BITDEPTH: Bit depth for every channel (R/G/B/A).

-        
+

         Supported values for wxIMAGE_OPTION_PNG_FORMAT:
         @li wxPNG_TYPE_COLOUR: Stores RGB image.
         @li wxPNG_TYPE_GREY: Stores grey image, converts from RGB.
         Supported values for wxIMAGE_OPTION_PNG_FORMAT:
         @li wxPNG_TYPE_COLOUR: Stores RGB image.
         @li wxPNG_TYPE_GREY: Stores grey image, converts from RGB.


@@ -624,6 +626,12 @@ public:
     */
     wxImage GetSubImage(const wxRect& rect) const;
 
     */
     wxImage GetSubImage(const wxRect& rect) const;
 

+    /**
+        Gets the type of image found by LoadFile or specified with SaveFile
+        @since 2.9.0
+    */
+    wxBitmapType GetType() const;
+

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


@@ -739,7 +747,7 @@ public:
             interpreted as the first image (index=0) by the GIF and TIFF handler
             and as the largest and most colourful one by the ICO handler.
 
             interpreted as the first image (index=0) by the GIF and TIFF handler
             and as the largest and most colourful one by the ICO handler.
 

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

                  optional index parameter is out of range, @false is
                  returned and a call to wxLogError() takes place.
 
                  optional index parameter is out of range, @false is
                  returned and a call to wxLogError() takes place.
 


@@ -749,11 +757,11 @@ public:
         @see SaveFile()
     */
     bool LoadFile(const wxString& name,
         @see SaveFile()
     */
     bool LoadFile(const wxString& name,

-                  long type = wxBITMAP_TYPE_ANY,
+                  wxBitmapType type = wxBITMAP_TYPE_ANY,

                   int index = -1);
     bool LoadFile(const wxString& name, const wxString& mimetype,
                   int index = -1);
                   int index = -1);
     bool LoadFile(const wxString& name, const wxString& mimetype,
                   int index = -1);

-    bool LoadFile(wxInputStream& stream, long type,
+    bool LoadFile(wxInputStream& stream, wxBitmapType type,

                   int index = -1);
     bool LoadFile(wxInputStream& stream,
                   const wxString& mimetype,
                   int index = -1);
     bool LoadFile(wxInputStream& stream,
                   const wxString& mimetype,


@@ -793,7 +801,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 wxImageHandler
     */
 
         @see wxImageHandler
     */


@@ -884,7 +892,7 @@ public:
         @param mimetype
             MIME type.
 
         @param mimetype
             MIME type.
 

-        @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.
 
         @remarks Depending on how wxWidgets has been configured, not all formats
                  may be available.


@@ -920,8 +928,8 @@ public:
         Example:
 
         @param quality
         Example:
 
         @param quality

-            Determines what method to use for resampling the image. 
-            
+            Determines what method to use for resampling the image.
+

             Can be one of the following:
             @li wxIMAGE_QUALITY_NORMAL: Uses the normal default scaling method of
                 pixel replication
             Can be one of the following:
             @li wxIMAGE_QUALITY_NORMAL: Uses the normal default scaling method of
                 pixel replication


@@ -933,14 +941,14 @@ public:
     wxImage Scale(int width, int height,
                   int quality = wxIMAGE_QUALITY_NORMAL) const;
 
     wxImage Scale(int width, int height,
                   int quality = wxIMAGE_QUALITY_NORMAL) const;
 

-    /** 
+    /**

        Assigns new data as alpha channel to the image.
        If @e static_data is false the data will be
        free()'d after use.
     */
     void SetAlpha(unsigned char* alpha = NULL,
                   bool static_data = false);
        Assigns new data as alpha channel to the image.
        If @e static_data is false the data will be
        free()'d after use.
     */
     void SetAlpha(unsigned char* alpha = NULL,
                   bool static_data = false);

-                  
+

     /**
         Sets the alpha value for the given pixel. This function should only be
         called if the image has alpha channel data, use HasAlpha() to
     /**
         Sets the alpha value for the given pixel. This function should only be
         called if the image has alpha channel data, use HasAlpha() to


@@ -980,7 +988,7 @@ public:
         @param mr,mg,mb
             RGB value of pixels in mask that will be used to create the mask.
 
         @param mr,mg,mb
             RGB value of pixels in mask that will be used to create the mask.
 

-        @returns Returns @false if mask does not have same dimensions as the image
+        @return Returns @false if mask does not have same dimensions as the image

                  or if there is no unused colour left. Returns @true if
                  the mask was successfully applied.
     */
                  or if there is no unused colour left. Returns @true if
                  the mask was successfully applied.
     */


@@ -1039,7 +1047,7 @@ public:
         @param image
             Image to assign.
 
         @param image
             Image to assign.
 

-        @returns Returns 'this' object.
+        @return Returns 'this' object.

     */
     wxImage operator =(const wxImage& image);
 };
     */
     wxImage operator =(const wxImage& image);
 };