wxWidgets/interface/bitmap.h

/////////////////////////////////////////////////////////////////////////////
// Name:        bitmap.h
// Purpose:     documentation for wxBitmapHandler class
// Author:      wxWidgets team
// RCS-ID:      $Id$
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////

/**
    @class wxBitmapHandler
    @wxheader{bitmap.h}

    Overview

    This is the base class for implementing bitmap file loading/saving, and bitmap
    creation from data.
    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
    application initialisation.

    @library{wxcore}
    @category{FIXME}

    @seealso
    wxBitmap, wxIcon, wxCursor
*/
class wxBitmapHandler : public wxObject
{
public:
    /**
        Default constructor. In your own default constructor, initialise the members
        m_name, m_extension and m_type.
    */
    wxBitmapHandler();

    /**
        Destroys the wxBitmapHandler object.
    */
    ~wxBitmapHandler();

    /**
        Creates a bitmap from the given data, which can be of arbitrary type. The
        wxBitmap object @a bitmap is
        manipulated by this function.
        
        @param bitmap
            The wxBitmap object.
        @param width
            The width of the bitmap in pixels.
        @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.
        @param data
            Data whose type depends on the value of type.
        @param type
            A bitmap type identifier - see wxBitmapHandler() for a list
            of possible values.
        
        @returns @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);

    /**
        Gets the file extension associated with this handler.
    */
    const wxString GetExtension() const;

    /**
        Gets the name of this handler.
    */
    const wxString GetName() const;

    /**
        Gets the bitmap type associated with this handler.
    */
    long GetType() const;

    /**
        Loads a bitmap from a file or resource, putting the resulting data into @e
        bitmap.
        
        @param bitmap
            The bitmap object which is to be affected by this operation.
        @param name
            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 wxBitmap::LoadFile, wxBitmap::SaveFile, SaveFile()
    */
    bool LoadFile(wxBitmap* bitmap, const wxString& name, long type);

    /**
        Saves a bitmap in the named file.
        
        @param bitmap
            The bitmap object which is to be affected by this operation.
        @param name
            A filename. The meaning of name is determined by the type parameter.
        @param type
            See wxBitmap::wxBitmap for values this can take.
        @param palette
            An optional palette used for saving the bitmap.
        
        @returns @true if the operation succeeded, @false otherwise.
        
        @see wxBitmap::LoadFile, wxBitmap::SaveFile, LoadFile()
    */
    bool SaveFile(wxBitmap* bitmap, const wxString& name, int type,
                  wxPalette* palette = NULL);

    /**
        Sets the handler extension.
        
        @param extension
            Handler extension.
    */
    void SetExtension(const wxString& extension);

    /**
        Sets the handler name.
        
        @param name
            Handler name.
    */
    void SetName(const wxString& name);

    /**
        Sets the handler type.
        
        @param name
            Handler type.
    */
    void SetType(long type);
};


/**
    @class wxBitmap
    @wxheader{bitmap.h}

    This class encapsulates the concept of a platform-dependent bitmap,
    either monochrome or colour or colour with alpha channel support.

    @library{wxcore}
    @category{gdi}

    @stdobjects
    Objects:
    wxNullBitmap

    @seealso
    @ref overview_wxbitmapoverview "wxBitmap overview", @ref
    overview_supportedbitmapformats "supported bitmap file formats", wxDC::Blit, wxIcon, wxCursor, wxBitmap, wxMemoryDC
*/
class wxBitmap : public wxGDIObject
{
public:
    //@{
    /**
        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.
        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.
        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, but
        the image quality won't be perfect (and could be better for photo images using
        more
        sophisticated dithering algorithms).
        On Windows, if there is a palette present (set with SetPalette), it will be
        used when
        creating the wxBitmap (most useful in 8-bit display mode). On other platforms,
        the palette is currently ignored.
        
        @param bits
            Specifies an array of pixel values.
        @param width
            Specifies the width of the bitmap.
        @param height
            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.
        @param name
            This can refer to a resource name under MS Windows, or a filename under MS
        Windows and X.
            Its meaning is determined by the type parameter.
        @param type
            May be one of the following:
        
        
        
        
        
        
        
            wxBITMAP_TYPE_BMP
        
        
        
        
            Load a Windows bitmap file.
        
        
        
        
        
            wxBITMAP_TYPE_BMP_RESOURCE
        
        
        
        
            Load a Windows bitmap resource from the executable. Windows only.
        
        
        
        
        
            wxBITMAP_TYPE_PICT_RESOURCE
        
        
        
        
            Load a PICT image resource from the executable. Mac OS only.
        
        
        
        
        
            wxBITMAP_TYPE_GIF
        
        
        
        
            Load a GIF bitmap file.
        
        
        
        
        
            wxBITMAP_TYPE_XBM
        
        
        
        
            Load an X bitmap file.
        
        
        
        
        
            wxBITMAP_TYPE_XPM
        
        
        
        
            Load an XPM bitmap file.
        
        
        
        
        
            The validity of these flags depends on the platform and wxWidgets
        configuration.
            If all possible wxWidgets settings are used, the Windows platform supports
        BMP file, BMP resource,
            XPM data, and XPM. Under wxGTK, the available formats are BMP file, XPM
        data, XPM file, and PNG file.
            Under wxMotif, the available formats are XBM data, XBM file, XPM data, XPM
        file.
            In addition, wxBitmap can read all formats that wxImage can, which
        currently include
            wxBITMAP_TYPE_JPEG, wxBITMAP_TYPE_TIF, wxBITMAP_TYPE_PNG,
        wxBITMAP_TYPE_GIF, wxBITMAP_TYPE_PCX,
            and wxBITMAP_TYPE_PNM. Of course, you must have wxImage handlers loaded.
        @param img
            Platform-independent wxImage object.
        
        @remarks The first form constructs a bitmap object with no data; an
                 assignment or another member function such as Create or
                 LoadFile must be called subsequently.
        
        @see LoadFile()
    */
    wxBitmap();
    wxBitmap(const wxBitmap& bitmap);
    wxBitmap(const void* data, int type, int width, int height,
             int depth = -1);
    wxBitmap(const char bits[], int width, int height,
             int depth = 1);
    wxBitmap(int width, int height, int depth = -1);
    wxBitmap(const char* const* bits);
    wxBitmap(const wxString& name, long type);
    wxBitmap(const wxImage& img, int depth = -1);
    //@}

    /**
        Destructor.
        See @ref overview_refcountdestruct "reference-counted object destruction" for
        more info.
        If the application omits to delete the bitmap explicitly, the bitmap will be
        destroyed automatically by wxWidgets when the application exits.
        Do not delete a bitmap that is selected into a memory device context.
    */
    ~wxBitmap();

    /**
        Adds a handler to the end of the static list of format handlers.
        
        @param handler
            A new bitmap format handler object. There is usually only one instance
            of a given handler class in an application session.
        
        @see wxBitmapHandler
    */
    static void AddHandler(wxBitmapHandler* handler);

    /**
        Deletes all bitmap handlers.
        This function is called by wxWidgets on exit.
    */
    static void CleanUpHandlers();

    /**
        Creates an image from a platform-dependent bitmap. This preserves
        mask information so that bitmaps and images can be converted back
        and forth without loss in that respect.
    */
    wxImage ConvertToImage();

    /**
        Creates the bitmap from an icon.
    */
    bool CopyFromIcon(const wxIcon& icon);

    //@{
    /**
        Creates a bitmap from the given data, which can be of arbitrary type.
        
        @param width
            The width of the bitmap in pixels.
        @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.
        @param data
            Data whose type depends on the value of type.
        @param type
            A bitmap type identifier - see wxBitmap() for a list
            of possible values.
        
        @returns @true if the call succeeded, @false otherwise.
        
        @remarks The first form works on all platforms. The portability of the
                 second form depends on the type of data.
        
        @see wxBitmap()
    */
    virtual bool Create(int width, int height, int depth = -1);
    virtual bool Create(const void* data, int type, int width,
                        int height,
                        int depth = -1);
    //@}

    //@{
    /**
        Finds the handler associated with the given bitmap type.
        
        @param name
            The handler name.
        @param extension
            The file extension, such as "bmp".
        @param bitmapType
            The bitmap type, such as wxBITMAP_TYPE_BMP.
        
        @returns A pointer to the handler if found, @NULL otherwise.
        
        @see wxBitmapHandler
    */
    static wxBitmapHandler* FindHandler(const wxString& name);
    static wxBitmapHandler* FindHandler(const wxString& extension,
                                        wxBitmapType bitmapType);
    static wxBitmapHandler* FindHandler(wxBitmapType bitmapType);
    //@}

    /**
        Gets the colour depth of the bitmap. A value of 1 indicates a
        monochrome bitmap.
    */
    int GetDepth() const;

    /**
        Returns the static list of bitmap format handlers.
        
        @see wxBitmapHandler
    */
    static wxList GetHandlers();

    /**
        Gets the height of the bitmap in pixels.
    */
    int GetHeight() const;

    /**
        Gets the associated mask (if any) which may have been loaded from a file
        or set for the bitmap.
        
        @see SetMask(), wxMask
    */
    wxMask* GetMask() const;

    /**
        Gets the associated palette (if any) which may have been loaded from a file
        or set for the bitmap.
        
        @see wxPalette
    */
    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.
    */
    wxBitmap GetSubBitmap(const wxRect& rect) const;

    /**
        Gets the width of the bitmap in pixels.
        
        @see GetHeight()
    */
    int GetWidth() const;

    /**
        Adds the standard bitmap format handlers, which, depending on wxWidgets
        configuration, can be handlers for Windows bitmap, Windows bitmap resource, and
        XPM.
        This function is called by wxWidgets on startup.
        
        @see wxBitmapHandler
    */
    static void InitStandardHandlers();

    /**
        Adds a handler at the start of the static list of format handlers.
        
        @param handler
            A new bitmap format handler object. There is usually only one instance
            of a given handler class in an application session.
        
        @see wxBitmapHandler
    */
    static void InsertHandler(wxBitmapHandler* handler);

    /**
        Returns @true if bitmap data is present.
    */
    bool IsOk() const;

    /**
        Loads a bitmap from a file or resource.
        
        @param name
            Either a filename or a Windows resource name.
            The meaning of name is determined by the type parameter.
        @param type
            One of the following values:
        
        
        
        
        
        
        
            wxBITMAP_TYPE_BMP
        
        
        
        
            Load a Windows bitmap file.
        
        
        
        
        
            wxBITMAP_TYPE_BMP_RESOURCE
        
        
        
        
            Load a Windows bitmap resource from the executable.
        
        
        
        
        
            wxBITMAP_TYPE_PICT_RESOURCE
        
        
        
        
            Load a PICT image resource from the executable. Mac OS only.
        
        
        
        
        
            wxBITMAP_TYPE_GIF
        
        
        
        
            Load a GIF bitmap file.
        
        
        
        
        
            wxBITMAP_TYPE_XBM
        
        
        
        
            Load an X bitmap file.
        
        
        
        
        
            wxBITMAP_TYPE_XPM
        
        
        
        
            Load an XPM bitmap file.
        
        
        
        
        
            The validity of these flags depends on the platform and wxWidgets
        configuration.
            In addition, wxBitmap can read all formats that wxImage can
            (wxBITMAP_TYPE_JPEG, wxBITMAP_TYPE_PNG, wxBITMAP_TYPE_GIF,
        wxBITMAP_TYPE_PCX, wxBITMAP_TYPE_PNM).
            (Of course you must have wxImage handlers loaded.)
        
        @returns @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
                 code supports it. You can check if one has been created
                 by using the GetPalette member.
        
        @see SaveFile()
    */
    bool LoadFile(const wxString& name, wxBitmapType type);

    /**
        Finds the handler with the given name, and removes it. The handler
        is not deleted.
        
        @param name
            The handler name.
        
        @returns @true if the handler was found and removed, @false otherwise.
        
        @see wxBitmapHandler
    */
    static bool RemoveHandler(const wxString& name);

    /**
        Saves a bitmap in the named file.
        
        @param name
            A filename. The meaning of name is determined by the type parameter.
        @param type
            One of the following values:
        
        
        
        
        
        
        
            wxBITMAP_TYPE_BMP
        
        
        
        
            Save a Windows bitmap file.
        
        
        
        
        
            wxBITMAP_TYPE_GIF
        
        
        
        
            Save a GIF bitmap file.
        
        
        
        
        
            wxBITMAP_TYPE_XBM
        
        
        
        
            Save an X bitmap file.
        
        
        
        
        
            wxBITMAP_TYPE_XPM
        
        
        
        
            Save an XPM bitmap file.
        
        
        
        
        
            The validity of these flags depends on the platform and wxWidgets
        configuration.
            In addition, wxBitmap can save all formats that wxImage can
            (wxBITMAP_TYPE_JPEG, wxBITMAP_TYPE_PNG).
            (Of course you must have wxImage handlers loaded.)
        @param palette
            An optional palette used for saving the bitmap.
        
        @returns @true if the operation succeeded, @false otherwise.
        
        @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);

    /**
        Sets the depth member (does not affect the bitmap data).
        
        @param depth
            Bitmap depth.
    */
    void SetDepth(int depth);

    /**
        Sets the height member (does not affect the bitmap data).
        
        @param height
            Bitmap height in pixels.
    */
    void SetHeight(int height);

    /**
        Sets the mask for this bitmap.
        
        @remarks The bitmap object owns the mask once this has been called.
        
        @see GetMask(), wxMask
    */
    void SetMask(wxMask* mask);

    /**
        Sets the associated palette. (Not implemented under GTK+).
        
        @param palette
            The palette to set.
        
        @see wxPalette
    */
    void SetPalette(const wxPalette& palette);

    /**
        Sets the width member (does not affect the bitmap data).
        
        @param width
            Bitmap width in pixels.
    */
    void SetWidth(int width);

    /**
        Assignment operator, using @ref overview_trefcount "reference counting".
        
        @param bitmap
            Bitmap to assign.
    */
    wxBitmap operator =(const wxBitmap& bitmap);
};


/**
    @class wxMask
    @wxheader{bitmap.h}

    This class encapsulates a monochrome mask bitmap, where the masked area is
    black and
    the unmasked area is white. When associated with a bitmap and drawn in a device
    context,
    the unmasked area of the bitmap will be drawn, and the masked area will not be
    drawn.

    @library{wxcore}
    @category{gdi}

    @seealso
    wxBitmap, wxDC::Blit, wxMemoryDC
*/
class wxMask : public wxObject
{
public:
    //@{
    /**
        Constructs a mask from a bitmap and a palette index that indicates the
        background. Not
        yet implemented for GTK.
        
        @param bitmap
            A valid bitmap.
        @param colour
            A colour specifying the transparency RGB values.
        @param index
            Index into a palette, specifying the transparency colour.
    */
    wxMask();
    wxMask(const wxBitmap& bitmap);
    wxMask(const wxBitmap& bitmap,
           const wxColour& colour);
    wxMask(const wxBitmap& bitmap, int index);
    //@}

    /**
        Destroys the wxMask object and the underlying bitmap data.
    */
    ~wxMask();

    //@{
    /**
        Constructs a mask from a bitmap and a palette index that indicates the
        background. Not
        yet implemented for GTK.
        
        @param bitmap
            A valid bitmap.
        @param colour
            A colour specifying the transparency RGB values.
        @param index
            Index into a palette, specifying the transparency colour.
    */
    bool Create(const wxBitmap& bitmap);
    bool Create(const wxBitmap& bitmap, const wxColour& colour);
    bool Create(const wxBitmap& bitmap, int index);
    //@}
};