GetSocketManager() has no GUI-specific version under Darwin finally

[wxWidgets.git] / interface / image.h

diff --git a/interface/image.h b/interface/image.h
index 719731aaa654b44544162dc0394a14e345f2a846..74d814fde76a5326f1d93b4114287fb2faa0cdac 100644 (file)
--- a/interface/image.h
+++ b/interface/image.h
@@ -10,15 +10,17 @@
     @class wxImageHandler
     @wxheader{image.h}
 
     @class wxImageHandler
     @wxheader{image.h}
 

-    This is the base class for implementing image file loading/saving, and image
-    creation from data.
+    This is the base class for implementing image file loading/saving, and
+    image creation from data.

     It is used within wxImage and is not normally seen by the application.
 
     If you wish to extend the capabilities of wxImage, derive a class from
     It is used within wxImage and is not normally seen by the application.
 
     If you wish to extend the capabilities of wxImage, derive a class from

-    wxImageHandler
-    and add the handler using wxImage::AddHandler in your
+    wxImageHandler and add the handler using wxImage::AddHandler in your

     application initialisation.
 
     application initialisation.
 

+    @stdobjects
+    ::wxNullImage
+

     @library{wxcore}
     @category{FIXME}
 
     @library{wxcore}
     @category{FIXME}
 


@@ -141,18 +143,16 @@ public:
     @class wxImage
     @wxheader{image.h}
 
     @class wxImage
     @wxheader{image.h}
 

-    This class encapsulates a platform-independent image. An image can be created
-    from data, or using wxBitmap::ConvertToImage. An image
-    can be loaded from a file in a variety of formats, and is extensible to new
-    formats
-    via image format handlers. Functions are available to set and get image bits, so
-    it can be used for basic image manipulation.
+    This class encapsulates a platform-independent image. An image can be
+    created from data, or using wxBitmap::ConvertToImage. An image can be
+    loaded from a file in a variety of formats, and is extensible to new
+    formats via image format handlers. Functions are available to set and
+    get image bits, so it can be used for basic image manipulation.

 
     A wxImage cannot (currently) be drawn directly to a wxDC. Instead,
     a platform-specific wxBitmap object must be created from it using
     the wxBitmap::wxBitmap(wxImage,int depth) constructor.
 
     A wxImage cannot (currently) be drawn directly to a wxDC. Instead,
     a platform-specific wxBitmap object must be created from it using
     the wxBitmap::wxBitmap(wxImage,int depth) constructor.

-    This bitmap can then
-    be drawn in a device context, using wxDC::DrawBitmap.
+    This bitmap can then be drawn in a device context, using wxDC::DrawBitmap.

 
     One colour value of the image may be used as a mask colour which will lead to
     the automatic creation of a wxMask object associated to the bitmap object.
 
     One colour value of the image may be used as a mask colour which will lead to
     the automatic creation of a wxMask object associated to the bitmap object.


@@ -163,12 +163,30 @@ public:
     @stdobjects
     ::wxNullImage
 
     @stdobjects
     ::wxNullImage
 

-    @see wxBitmap, wxInitAllImageHandlers()
+    @see wxBitmap, wxInitAllImageHandlers(), wxPixelData

 */
 class wxImage : public wxObject
 {
 public:
 */
 class wxImage : public wxObject
 {
 public:

-    //@{
+    
+    /**
+         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.
+         
+        @param width
+            Specifies the width of the image.
+        @param height
+            Specifies the height of the image.
+        @clear
+            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
     /**
         Creates an image from data in memory. If static_data is false
         then the wxImage will take ownership of the data and free it


@@ -180,32 +198,30 @@ public:
             Specifies the height of the image.
         @param data
             A pointer to RGB data
             Specifies the height of the image.
         @param data
             A pointer to RGB data

-        @param apha
-            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,  bool static_data = false);
     wxImage(int width, int height, unsigned char* data,  bool static_data = false);

-    //@}

     
     /**
     
     /**

-         Creates an image with the given size and clears it if requested.
-         Does not create an alpha channel.
-    */
-    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 empty wxImage object. Does not create
-         an alpha channel.
-         

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

-        @clear
-            Clear the image with zeros.
+        @param data
+            A pointer to RGB data
+        @param alpha
+            A pointer to alpha-channel data
+        @param static_data
+            Indicates if the data should be free'd after use
+        

     */
     */

-    wxImage();
+    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.


@@ -214,31 +230,27 @@ public:
             A pointer to XPM image data.
     */
     wxImage(const char* const* xpmData);
             A pointer to XPM image data.
     */
     wxImage(const char* const* xpmData);

-    //@{
+    

     /**
     /**

+        Creates an image from a file.
+    

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

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

         @param type
             May be one of the following:
         @param type
             May be one of the following:

-            wxBITMAP_TYPE_BMP: Load a Windows bitmap file.
-            wxBITMAP_TYPE_GIF: Load a GIF bitmap file.
-            wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file.
-            wxBITMAP_TYPE_PNG: Load a PNG bitmap file.
-            wxBITMAP_TYPE_PCX: Load a PCX bitmap file.
-            wxBITMAP_TYPE_PNM: Load a PNM bitmap file.
-            wxBITMAP_TYPE_TIF: Load a TIFF bitmap file.
-            wxBITMAP_TYPE_TGA: Load a TGA bitmap file.
-            wxBITMAP_TYPE_XPM: Load a XPM bitmap file.
-            wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO).
-            wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR).
-            wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI).
-            wxBITMAP_TYPE_ANY: Will try to autodetect the format.
-            
-        @param mimetype
-            MIME type string (for example 'image/jpeg')
+            @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file.
+            @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file.
+            @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file.
+            @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file.
+            @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file.
+            @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file.
+            @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file.
+            @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file.
+            @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file.
+            @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO).
+            @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR).
+            @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI).
+            @li wxBITMAP_TYPE_ANY: Will try to autodetect the format.

         @param index
             Index of the image to load in the case that the image file contains
             multiple images. This is only used by GIF, ICO and TIFF handlers.
         @param index
             Index of the image to load in the case that the image file contains
             multiple images. This is only used by GIF, ICO and TIFF handlers.


@@ -252,10 +264,46 @@ public:
         @see LoadFile()
     */
     wxImage(const wxString& name, long type = wxBITMAP_TYPE_ANY, int index = -1);
         @see LoadFile()
     */
     wxImage(const wxString& name, long type = wxBITMAP_TYPE_ANY, int index = -1);

+    
+    /**
+        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
+            See above
+        @param mimetype
+            MIME type string (for example 'image/jpeg')
+        @param index
+            See above
+    */

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

-    wxImage(wxInputStream& stream, long type = wxBITMAP_TYPE_ANY, int index = -1);
+    
+    /**
+        Creates an image from a stream.
+    
+        @param stream
+            Opened input stream from which to load the image. Currently,
+            the stream must support seeking.
+        @param type
+            See above
+        @param index
+            See above.
+    */
+    wxImage(wxInputStream& stream, long type = wxBITMAP_TYPE_ANY, int index = -1);    
+    
+    /**
+        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 mimetype
+            MIME type string (for example 'image/jpeg')
+        @param index
+            See above.
+    */

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

-    //@}

     
 
     /**
     
 
     /**


@@ -265,21 +313,17 @@ public:
     */
     ~wxImage();
 
     */
     ~wxImage();
 

-    //@{

     /**
     /**

-        returns @true if the current image handlers can read this file
+        Register an image handler.

     */
     static void AddHandler(wxImageHandler* handler);
     */
     static void AddHandler(wxImageHandler* handler);

-    See also bool CanRead(const wxString& filename);
-    //@}

 
     /**
 
     /**

-        Blurs the image in both horizontal and vertical directions by the specified
-        pixel
-        @e blurRadius. This should not be used when using a single mask colour
-        for transparency.
+        Blurs the image in both horizontal and vertical directions by the
+        specified pixel @e blurRadius. This should not be used when using
+        a single mask colour for transparency.

 
 

-        @see @ref horzblur() BlurHorizontal, @ref vertblur() BlurVertical
+        @see BlurHorizontal(), BlurVertical()

     */
     wxImage Blur(int blurRadius);
 
     */
     wxImage Blur(int blurRadius);
 


@@ -287,7 +331,7 @@ public:
         Blurs the image in the horizontal direction only. This should not be used
         when using a single mask colour for transparency.
 
         Blurs the image in the horizontal direction only. This should not be used
         when using a single mask colour for transparency.
 

-        @see Blur(), @ref vertblur() BlurVertical
+        @see Blur(), BlurVertical()

     */
     wxImage BlurHorizontal(int blurRadius);
 
     */
     wxImage BlurHorizontal(int blurRadius);
 


@@ -295,9 +339,14 @@ public:
         Blurs the image in the vertical direction only. This should not be used
         when using a single mask colour for transparency.
 
         Blurs the image in the vertical direction only. This should not be used
         when using a single mask colour for transparency.
 

-        @see Blur(), @ref horzblur() BlurHorizontal
+        @see Blur(), BlurHorizontal()

     */
     wxImage BlurVertical(int blurRadius);
     */
     wxImage BlurVertical(int blurRadius);

+    
+    /**
+        Returns @true if the current image handlers can read this file
+    */
+    bool CanRead(const wxString& filename);

 
     /**
         Deletes all image handlers.
 
     /**
         Deletes all image handlers.


@@ -412,16 +461,18 @@ public:
     static wxImageHandler* FindHandlerMime(const wxString& mimetype);
     //@}
 
     static wxImageHandler* FindHandlerMime(const wxString& mimetype);
     //@}
 

-    //@{
+    /**
+        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
         does have it, this pointer may be used to directly manipulate the alpha values
     /**
         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
         does have it, this pointer may be used to directly manipulate the alpha values

-        which are stored as the @ref getdata() RGB ones.
+        which are stored as the RGB ones.

     */
     */

-    unsigned char GetAlpha(int x, int y) const;

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

-    //@}

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


@@ -471,19 +522,19 @@ public:
             support seeking.
         @param type
             May be one of the following:
             support seeking.
         @param type
             May be one of the following:

-            wxBITMAP_TYPE_BMP: Load a Windows bitmap file.
-            wxBITMAP_TYPE_GIF: Load a GIF bitmap file.
-            wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file.
-            wxBITMAP_TYPE_PNG: Load a PNG bitmap file.
-            wxBITMAP_TYPE_PCX: Load a PCX bitmap file.
-            wxBITMAP_TYPE_PNM: Load a PNM bitmap file.
-            wxBITMAP_TYPE_TIF: Load a TIFF bitmap file.
-            wxBITMAP_TYPE_TGA: Load a TGA bitmap file.
-            wxBITMAP_TYPE_XPM: Load a XPM bitmap file.
-            wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO).
-            wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR).
-            wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI).
-            wxBITMAP_TYPE_ANY: Will try to autodetect the format.
+            @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file.
+            @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file.
+            @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file.
+            @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file.
+            @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file.
+            @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file.
+            @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file.
+            @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file.
+            @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file.
+            @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO).
+            @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR).
+            @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
                  (exceptions are TIFF and ICO formats).
 
         @returns Number of available images. For most image handlers, this is 1
                  (exceptions are TIFF and ICO formats).


@@ -531,34 +582,17 @@ public:
     wxString GetOption(const wxString& name) const;
 
     /**
     wxString GetOption(const wxString& name) const;
 
     /**

-        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. Use
-        HasOption() is 0 is a possibly valid value
-        for the option.
+        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. 
+        Use HasOption() is 0 is a possibly valid value for the option.

         Options for wxPNGHandler
         Options for wxPNGHandler

-
-        wxIMAGE_OPTION_PNG_FORMAT
-
-        Format for saving a PNG file.
-
-        wxIMAGE_OPTION_PNG_BITDEPTH
-
-        Bit depth for every channel (R/G/B/A).
-
+        @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:
         Supported values for wxIMAGE_OPTION_PNG_FORMAT:

-
-        wxPNG_TYPE_COLOUR
-
-        Stores RGB image.
-
-        wxPNG_TYPE_GREY
-
-        Stores grey image, converts from RGB.
-
-        wxPNG_TYPE_GREY_RED
-
-        Stores grey image, uses red value as grey.
+        @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()
     */


@@ -683,19 +717,19 @@ public:
             stream must support seeking.
         @param type
             May be one of the following:
             stream must support seeking.
         @param type
             May be one of the following:

-            wxBITMAP_TYPE_BMP: Load a Windows bitmap file.
-            wxBITMAP_TYPE_GIF: Load a GIF bitmap file.
-            wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file.
-            wxBITMAP_TYPE_PNG: Load a PNG bitmap file.
-            wxBITMAP_TYPE_PCX: Load a PCX bitmap file.
-            wxBITMAP_TYPE_PNM: Load a PNM bitmap file.
-            wxBITMAP_TYPE_TIF: Load a TIFF bitmap file.
-            wxBITMAP_TYPE_TGA: Load a TGA bitmap file.
-            wxBITMAP_TYPE_XPM: Load a XPM bitmap file.
-            wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO).
-            wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR).
-            wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI).
-            wxBITMAP_TYPE_ANY: Will try to autodetect the format.
+            @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file.
+            @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file.
+            @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file.
+            @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file.
+            @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file.
+            @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file.
+            @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file.
+            @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file.
+            @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file.
+            @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO).
+            @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR).
+            @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI).
+            @li wxBITMAP_TYPE_ANY: Will try to autodetect the format.

         @param mimetype
             MIME type string (for example 'image/jpeg')
         @param index
         @param mimetype
             MIME type string (for example 'image/jpeg')
         @param index


@@ -835,18 +869,18 @@ public:
             Opened output stream to save the image to.
         @param type
             Currently these types can be used:
             Opened output stream to save the image to.
         @param type
             Currently these types can be used:

-            wxBITMAP_TYPE_BMP: Save a BMP image file.
-            wxBITMAP_TYPE_JPEG: Save a JPEG image file.
-            wxBITMAP_TYPE_PNG: Save a PNG image file.
-            wxBITMAP_TYPE_PCX: Save a PCX image file (tries to save as 8-bit if possible,
+            @li wxBITMAP_TYPE_BMP: Save a BMP image file.
+            @li wxBITMAP_TYPE_JPEG: Save a JPEG image file.
+            @li wxBITMAP_TYPE_PNG: Save a PNG image file.
+            @li wxBITMAP_TYPE_PCX: Save a PCX image file (tries to save as 8-bit if possible,

                 falls back to 24-bit otherwise).
                 falls back to 24-bit otherwise).

-            wxBITMAP_TYPE_PNM: Save a PNM image file (as raw RGB always).
-            wxBITMAP_TYPE_TIFF: Save a TIFF image file.
-            wxBITMAP_TYPE_XPM: Save a XPM image file.
-            wxBITMAP_TYPE_ICO: Save a Windows icon file (ICO) (the size may
+            @li wxBITMAP_TYPE_PNM: Save a PNM image file (as raw RGB always).
+            @li wxBITMAP_TYPE_TIFF: Save a TIFF image file.
+            @li wxBITMAP_TYPE_XPM: Save a XPM image file.
+            @li wxBITMAP_TYPE_ICO: Save a Windows icon file (ICO) (the size may

                 be up to 255 wide by 127 high. A single image is saved in 8 colors
                 at the size supplied).
                 be up to 255 wide by 127 high. A single image is saved in 8 colors
                 at the size supplied).

-            wxBITMAP_TYPE_CUR: Save a Windows cursor file (CUR).
+            @li wxBITMAP_TYPE_CUR: Save a Windows cursor file (CUR).

         @param mimetype
             MIME type.
 
         @param mimetype
             MIME type.
 


@@ -887,11 +921,11 @@ public:
 
         @param quality
             Determines what method to use for resampling the image. 
 
         @param quality
             Determines what method to use for resampling the image. 

-            Can be one of the following:

             
             

-            wxIMAGE_QUALITY_NORMAL: Uses the normal default scaling method of
+            Can be one of the following:
+            @li wxIMAGE_QUALITY_NORMAL: Uses the normal default scaling method of

                 pixel replication
                 pixel replication

-            wxIMAGE_QUALITY_HIGH: Uses bicubic and box averaging resampling
+            @li wxIMAGE_QUALITY_HIGH: Uses bicubic and box averaging resampling

                 methods for upsampling and downsampling respectively
 
         @see Rescale()
                 methods for upsampling and downsampling respectively
 
         @see Rescale()


@@ -899,16 +933,20 @@ 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;
 

-    //@{
-    /**
-        Sets the alpha value for the given pixel. This function should only be called
-        if the image has alpha channel data, use HasAlpha() to
-        check for this.
+    /** 
+       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);
     */
     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
+        check for this.
+    */

     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. The data given must have
 
     /**
         Sets the image data without performing checks. The data given must have


@@ -1006,12 +1044,6 @@ public:
     wxImage operator =(const wxImage& image);
 };
 
     wxImage operator =(const wxImage& image);
 };
 

-/**
-    An empty wxImage.
-*/
-wxImage wxNullImage;
-
-

 // ============================================================================
 // Global functions/macros
 // ============================================================================
 // ============================================================================
 // Global functions/macros
 // ============================================================================