latex include not properly working for links and titlepage

[wxWidgets.git] / 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 @e 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();

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

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

    /**
        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.
        
        @sa 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.
        
        @sa 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.
        
        @sa 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.
        
        @sa 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.
        
        @sa 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.
        
        @sa 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();

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

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

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

    /**
        Gets the associated palette (if any) which may have been loaded from a file
        or set for the bitmap.
        
        @sa wxPalette
    */
    wxPalette* GetPalette();

    /**
        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);

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

    /**
        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.
        
        @sa 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.
        
        @sa wxBitmapHandler
    */
    static void InsertHandler(wxBitmapHandler* handler);

    /**
        Returns @true if bitmap data is present.
    */
#define bool IsOk()     /* implementation is private */

    /**
        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.
        
        @sa 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.
        
        @sa 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.
        
        @sa 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.
        
        @sa GetMask(), wxMask
    */
    void SetMask(wxMask* mask);

    /**
        Sets the associated palette. (Not implemented under GTK+).
        
        @param palette
        The palette to set.
        
        @sa 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);
    //@}
};