]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/image.h
remove tabs added by error in previous commit
[wxWidgets.git] / interface / wx / image.h
index 4ab6761c9e32a57bdb95df363f0f1688710cdf28..3062fe641382d88430146371d6529b85064dee86 100644 (file)
@@ -6,6 +6,35 @@
 // 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
 
@@ -503,13 +532,6 @@ public:
     */
     bool ConvertAlphaToMask(unsigned char threshold = wxIMAGE_ALPHA_THRESHOLD);
 
-    /**
-        @deprecated
-        Use the equivalent @ref wxBitmap::wxBitmap "wxBitmap constructor"
-        (which takes wxImage and depth as its arguments) instead.
-    */
-    wxBitmap ConvertToBitmap() const;
-
     /**
         Returns a greyscale version of the image.
 
@@ -641,7 +663,7 @@ public:
         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.
@@ -676,6 +698,8 @@ public:
 
     /**
         Gets the height of the image in pixels.
+
+        @see GetWidth(), GetSize()
     */
     int GetHeight() const;
 
@@ -748,31 +772,74 @@ public:
     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()
+
+        @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;
 
     /**
-        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.
 
-        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).
 
-        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()
+
+        @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;
 
@@ -804,6 +871,15 @@ public:
     */
     wxImage GetSubImage(const wxRect& rect) const;
 
+    /**
+        Returns the size of the image in pixels.
+
+        @since 2.9.0
+
+        @see GetHeight(), GetWidth()
+    */
+    wxSize GetSize() const;
+
     /**
         Gets the type of image found by LoadFile() or specified with SaveFile().
 
@@ -814,7 +890,7 @@ public:
     /**
         Gets the width of the image in pixels.
 
-        @see GetHeight()
+        @see GetHeight(), GetSize()
     */
     int GetWidth() const;
 
@@ -932,7 +1008,9 @@ public:
 
         @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.
@@ -1221,6 +1299,7 @@ public:
     */
     void SetAlpha(int x, int y, unsigned char alpha);
 
+    //@{
     /**
         Sets the image data without performing checks.
 
@@ -1235,7 +1314,10 @@ public:
         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.
@@ -1303,7 +1385,8 @@ public:
         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);