document wxFSVolume (fixes #3977)

[wxWidgets.git] / interface / wx / image.h

diff --git a/interface/wx/image.h b/interface/wx/image.h
index f901628f82547b8152e7adaeac515900771edd4e..67710f92e40af1638b52ad2e7ab6bc181f8ebed9 100644 (file)
--- a/interface/wx/image.h
+++ b/interface/wx/image.h
@@ -6,6 +6,35 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 

+/**
+    Possible values for the image resolution option.
+
+    @see wxImage::GetOptionInt().
+ */
+enum wxImageResolution
+{
+    /// Resolution not specified.
+    wxIMAGE_RESOLUTION_NONE = 0,
+
+    /// Resolution specified in inches.
+    wxIMAGE_RESOLUTION_INCHES = 1,
+
+    /// Resolution specified in centimetres.
+    wxIMAGE_RESOLUTION_CM = 2
+};
+
+/**
+    Possible values for PNG image type option.
+
+    @see wxImage::GetOptionInt().
+ */
+enum wxImagePNGType
+{
+    wxPNG_TYPE_COLOUR = 0,      ///< Colour PNG image.
+    wxPNG_TYPE_GREY = 2,        ///< Greyscale PNG image converted from RGB.
+    wxPNG_TYPE_GREY_RED = 3     ///< Greyscale PNG image using red as grey.
+};
+

 /**
     @class wxImageHandler
 
 /**
     @class wxImageHandler
 


@@ -119,6 +148,9 @@ public:
             The image object which is to be affected by this operation.
         @param stream
             Opened output stream for writing the data.
             The image object which is to be affected by this operation.
         @param stream
             Opened output stream for writing the data.

+        @param verbose
+            If set to @true, errors reported by the image handler will produce
+            wxLogMessages.

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


@@ -638,7 +670,7 @@ public:
         does have it, this pointer may be used to directly manipulate the alpha values
         which are stored as the RGB ones.
     */
         does have it, this pointer may be used to directly manipulate the alpha values
         which are stored as the RGB ones.
     */

-    const unsigned char * GetAlpha() const;
+    unsigned char* GetAlpha() const;

 
     /**
         Returns the blue intensity at the given coordinate.
 
     /**
         Returns the blue intensity at the given coordinate.


@@ -745,31 +777,74 @@ public:
     unsigned char GetMaskRed() const;
 
     /**
     unsigned char GetMaskRed() const;
 
     /**

-        Gets a user-defined option. The function is case-insensitive to @a name.
+        Gets a user-defined string-valued option.

 
 

-        For example, when saving as a JPEG file, the option @b quality is
-        used, which is a number between 0 and 100 (0 is terrible, 100 is very good).
+        Currently the only defined string option is
+        @li wxIMAGE_OPTION_FILENAME: The name of the file from which the image
+            was loaded.

 
         @see SetOption(), GetOptionInt(), HasOption()
 
         @see SetOption(), GetOptionInt(), HasOption()

+
+        @param name
+            The name of the option, case-insensitive.
+        @return
+            The value of the option or an empty string if not found. Use
+            HasOption() if an empty string can be a valid option value.

     */
     wxString GetOption(const wxString& name) const;
 
     /**
     */
     wxString GetOption(const wxString& name) const;
 
     /**

-        Gets a user-defined option as an integer.
+        Gets a user-defined integer-valued option.
+

         The function is case-insensitive to @a name.
         If the given option is not present, the function returns 0.
         Use HasOption() is 0 is a possibly valid value for the option.
 
         The function is case-insensitive to @a 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.
+        Generic options:
+        @li wxIMAGE_OPTION_MAX_WIDTH and wxIMAGE_OPTION_MAX_HEIGHT: If either
+            of these options is specified, the loaded image will be scaled down
+            (preserving its aspect ratio) so that its width is less than the
+            max width given if it is not 0 @em and its height is less than the
+            max height given if it is not 0. This is typically used for loading
+            thumbnails and the advantage of using these options compared to
+            calling Rescale() after loading is that some handlers (only JPEG
+            one right now) support rescaling the image during loading which is
+            vastly more efficient than loading the entire huge image and
+            rescaling it later (if these options are not supported by the
+            handler, this is still what happens however). These options must be
+            set before calling LoadFile() to have any effect.
+
+        @li wxIMAGE_OPTION_QUALITY: JPEG quality used when saving. This is an
+            integer in 0..100 range with 0 meaning very poor and 100 excellent
+            (but very badly compressed). This option is currently ignored for
+            the other formats.
+
+        @li wxIMAGE_OPTION_RESOLUTIONUNIT: The value of this option determines
+            whether the resolution of the image is specified in centimetres or
+            inches, see wxImageResolution enum elements.
+
+        @li wxIMAGE_OPTION_RESOLUTION, wxIMAGE_OPTION_RESOLUTIONX and
+            wxIMAGE_OPTION_RESOLUTIONY: These options define the resolution of
+            the image in the units corresponding to wxIMAGE_OPTION_RESOLUTIONUNIT
+            options value. The first option can be set before saving the image
+            to set both horizontal and vertical resolution to the same value.
+            The X and Y options are set by the image handlers if they support
+            the image resolution (currently BMP, JPEG and TIFF handlers do) and
+            the image provides the resolution information and can be queried
+            after loading the image.
+
+        Options specific to wxPNGHandler:
+        @li wxIMAGE_OPTION_PNG_FORMAT: Format for saving a PNG file, see
+            wxImagePNGType for the supported values.

         @li wxIMAGE_OPTION_PNG_BITDEPTH: Bit depth for every channel (R/G/B/A).
 
         @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.
-        @li wxPNG_TYPE_GREY_RED: Stores grey image, uses red value as grey.
-

         @see SetOption(), GetOption()
         @see SetOption(), GetOption()

+
+        @param name
+            The name of the option, case-insensitive.
+        @return
+            The value of the option or 0 if not found. Use HasOption() if 0
+            can be a valid option value.

     */
     int GetOptionInt(const wxString& name) const;
 
     */
     int GetOptionInt(const wxString& name) const;
 


@@ -929,7 +1004,9 @@ public:
 
         @see SaveFile()
     */
 
         @see SaveFile()
     */

-    bool LoadFile(wxInputStream& stream, wxBitmapType type, int index = -1);
+    virtual bool LoadFile(wxInputStream& stream,
+                          wxBitmapType type = wxBITMAP_TYPE_ANY,
+                          int index = -1);

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


@@ -1218,6 +1295,7 @@ public:
     */
     void SetAlpha(int x, int y, unsigned char alpha);
 
     */
     void SetAlpha(int x, int y, unsigned char alpha);
 

+    //@{

     /**
         Sets the image data without performing checks.
 
     /**
         Sets the image data without performing checks.
 


@@ -1232,7 +1310,10 @@ public:
         that will be responsible for deleting it.
         Do not pass to this function a pointer obtained through GetData().
     */
         that will be responsible for deleting it.
         Do not pass to this function a pointer obtained through GetData().
     */

-    void SetData(unsigned char* data);
+    void SetData(unsigned char* data, bool static_data = false);
+    void SetData(unsigned char* data, int new_width, int new_height,
+                 bool static_data = false);
+    //@}

 
     /**
         Specifies whether there is a mask or not.
 
     /**
         Specifies whether there is a mask or not.


@@ -1300,7 +1381,8 @@ public:
         This routine performs bounds-checks for the coordinate so it can be considered
         a safe way to manipulate the data.
     */
         This routine performs bounds-checks for the coordinate so it can be considered
         a safe way to manipulate the data.
     */

-    void SetRGB(wxRect& rect, unsigned char red,
+    void SetRGB(const wxRect& rect,
+                unsigned char red,

                 unsigned char green,
                 unsigned char blue);
 
                 unsigned char green,
                 unsigned char blue);