Fix missing documentation for several GDI functions.

[wxWidgets.git] / include / wx / mimetype.h

/////////////////////////////////////////////////////////////////////////////
// Name:        wx/mimetype.h
// Purpose:     classes and functions to manage MIME types
// Author:      Vadim Zeitlin
// Modified by:
//  Chris Elliott (biol75@york.ac.uk) 5 Dec 00: write support for Win32
// Created:     23.09.98
// RCS-ID:      $Id$
// Copyright:   (c) 1998 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
// Licence:     wxWindows licence (part of wxExtra library)
/////////////////////////////////////////////////////////////////////////////

#ifndef _WX_MIMETYPE_H_
#define _WX_MIMETYPE_H_

// ----------------------------------------------------------------------------
// headers and such
// ----------------------------------------------------------------------------

#include "wx/defs.h"

#if wxUSE_MIMETYPE

// the things we really need
#include "wx/string.h"
#include "wx/dynarray.h"
#include "wx/arrstr.h"

#include <stdarg.h>

// fwd decls
class WXDLLIMPEXP_FWD_BASE wxIconLocation;
class WXDLLIMPEXP_FWD_BASE wxFileTypeImpl;
class WXDLLIMPEXP_FWD_BASE wxMimeTypesManagerImpl;

// these constants define the MIME informations source under UNIX and are used
// by wxMimeTypesManager::Initialize()
enum wxMailcapStyle
{
    wxMAILCAP_STANDARD = 1,
    wxMAILCAP_NETSCAPE = 2,
    wxMAILCAP_KDE = 4,
    wxMAILCAP_GNOME = 8,

    wxMAILCAP_ALL = 15
};

/*
    TODO: would it be more convenient to have this class?

class WXDLLIMPEXP_BASE wxMimeType : public wxString
{
public:
    // all string ctors here

    wxString GetType() const { return BeforeFirst(wxT('/')); }
    wxString GetSubType() const { return AfterFirst(wxT('/')); }

    void SetSubType(const wxString& subtype)
    {
        *this = GetType() + wxT('/') + subtype;
    }

    bool Matches(const wxMimeType& wildcard)
    {
        // implement using wxMimeTypesManager::IsOfType()
    }
};

*/

// wxMimeTypeCommands stores the verbs defined for the given MIME type with
// their values
class WXDLLIMPEXP_BASE wxMimeTypeCommands
{
public:
    wxMimeTypeCommands() {}

    wxMimeTypeCommands(const wxArrayString& verbs,
                       const wxArrayString& commands)
        : m_verbs(verbs),
          m_commands(commands)
    {
    }

    // add a new verb with the command or replace the old value
    void AddOrReplaceVerb(const wxString& verb, const wxString& cmd);
    void Add(const wxString& s)
    {
        m_verbs.Add(s.BeforeFirst(wxT('=')));
        m_commands.Add(s.AfterFirst(wxT('=')));
    }

    // access the commands
    size_t GetCount() const { return m_verbs.GetCount(); }
    const wxString& GetVerb(size_t n) const { return m_verbs[n]; }
    const wxString& GetCmd(size_t n) const { return m_commands[n]; }

    bool HasVerb(const wxString& verb) const
        { return m_verbs.Index(verb) != wxNOT_FOUND; }

    // returns empty string and wxNOT_FOUND in idx if no such verb
    wxString GetCommandForVerb(const wxString& verb, size_t *idx = NULL) const;

    // get a "verb=command" string
    wxString GetVerbCmd(size_t n) const;

private:
    wxArrayString m_verbs;
    wxArrayString m_commands;
};

// ----------------------------------------------------------------------------
// wxFileTypeInfo: static container of information accessed via wxFileType.
//
// This class is used with wxMimeTypesManager::AddFallbacks() and Associate()
// ----------------------------------------------------------------------------

class WXDLLIMPEXP_BASE wxFileTypeInfo
{
private:
    void DoVarArgInit(const wxString& mimeType,
                      const wxString& openCmd,
                      const wxString& printCmd,
                      const wxString& desc,
                      va_list argptr);

    void VarArgInit(const wxString *mimeType,
                    const wxString *openCmd,
                    const wxString *printCmd,
                    const wxString *desc,
                    // the other parameters form a NULL terminated list of
                    // extensions
                    ...);

public:
    // NB: This is a helper to get implicit conversion of variadic ctor's
    //     fixed arguments into something that can be passed to VarArgInit().
    //     Do not use, it's used by the ctor only.
    struct CtorString
    {
        CtorString(const char *str) : m_str(str) {}
        CtorString(const wchar_t *str) : m_str(str) {}
        CtorString(const wxString& str) : m_str(str) {}
        CtorString(const wxCStrData& str) : m_str(str) {}
        CtorString(const wxScopedCharBuffer& str) : m_str(str) {}
        CtorString(const wxScopedWCharBuffer& str) : m_str(str) {}

        operator const wxString*() const { return &m_str; }

        wxString m_str;
    };

    // ctors

    // Ctor specifying just the MIME type (which is mandatory), the other
    // fields can be set later if needed.
    wxFileTypeInfo(const wxString& mimeType)
        : m_mimeType(mimeType)
    {
    }

    // Ctor allowing to specify the values of all fields at once:
    //
    // wxFileTypeInfo(const wxString& mimeType,
    //               const wxString& openCmd,
    //               const wxString& printCmd,
    //               const wxString& desc,
    //               // the other parameters form a list of extensions for this
    //               // file type and should be terminated with wxNullPtr (not
    //               // just NULL!)
    //               ...);
    WX_DEFINE_VARARG_FUNC_CTOR(wxFileTypeInfo,
                               4, (const CtorString&,
                                   const CtorString&,
                                   const CtorString&,
                                   const CtorString&),
                               VarArgInit, VarArgInit)
#ifdef __WATCOMC__
    // workaround for http://bugzilla.openwatcom.org/show_bug.cgi?id=351
    WX_VARARG_WATCOM_WORKAROUND_CTOR(
                                wxFileTypeInfo,
                                4, (const wxString&,
                                    const wxString&,
                                    const wxString&,
                                    const wxString&),
                                (CtorString(f1),
                                 CtorString(f2),
                                 CtorString(f3),
                                 CtorString(f4)));
    WX_VARARG_WATCOM_WORKAROUND_CTOR(
                                wxFileTypeInfo,
                                4, (const wxCStrData&,
                                    const wxCStrData&,
                                    const wxCStrData&,
                                    const wxCStrData&),
                                (CtorString(f1),
                                 CtorString(f2),
                                 CtorString(f3),
                                 CtorString(f4)));
    WX_VARARG_WATCOM_WORKAROUND_CTOR(
                                wxFileTypeInfo,
                                4, (const char*,
                                    const char*,
                                    const char*,
                                    const char*),
                                (CtorString(f1),
                                 CtorString(f2),
                                 CtorString(f3),
                                 CtorString(f4)));
    WX_VARARG_WATCOM_WORKAROUND_CTOR(
                                wxFileTypeInfo,
                                4, (const wchar_t*,
                                    const wchar_t*,
                                    const wchar_t*,
                                    const wchar_t*),
                                (CtorString(f1),
                                 CtorString(f2),
                                 CtorString(f3),
                                 CtorString(f4)));
#endif

        // the array elements correspond to the parameters of the ctor above in
        // the same order
    wxFileTypeInfo(const wxArrayString& sArray);

        // invalid item - use this to terminate the array passed to
        // wxMimeTypesManager::AddFallbacks
    wxFileTypeInfo() { }

    // test if this object can be used
    bool IsValid() const { return !m_mimeType.empty(); }

    // setters
        // set the open/print commands
    void SetOpenCommand(const wxString& command) { m_openCmd = command; }
    void SetPrintCommand(const wxString& command) { m_printCmd = command; }

        // set the description
    void SetDescription(const wxString& desc) { m_desc = desc; }

        // add another extension corresponding to this file type
    void AddExtension(const wxString& ext) { m_exts.push_back(ext); }

        // set the icon info
    void SetIcon(const wxString& iconFile, int iconIndex = 0)
    {
        m_iconFile = iconFile;
        m_iconIndex = iconIndex;
    }
        // set the short desc
    void SetShortDesc(const wxString& shortDesc) { m_shortDesc = shortDesc; }

    // accessors
        // get the MIME type
    const wxString& GetMimeType() const { return m_mimeType; }
        // get the open command
    const wxString& GetOpenCommand() const { return m_openCmd; }
        // get the print command
    const wxString& GetPrintCommand() const { return m_printCmd; }
        // get the short description (only used under Win32 so far)
    const wxString& GetShortDesc() const { return m_shortDesc; }
        // get the long, user visible description
    const wxString& GetDescription() const { return m_desc; }
        // get the array of all extensions
    const wxArrayString& GetExtensions() const { return m_exts; }
    size_t GetExtensionsCount() const {return m_exts.GetCount(); }
        // get the icon info
    const wxString& GetIconFile() const { return m_iconFile; }
    int GetIconIndex() const { return m_iconIndex; }

private:
    wxString m_mimeType,    // the MIME type in "type/subtype" form
             m_openCmd,     // command to use for opening the file (%s allowed)
             m_printCmd,    // command to use for printing the file (%s allowed)
             m_shortDesc,   // a short string used in the registry
             m_desc;        // a free form description of this file type

    // icon stuff
    wxString m_iconFile;    // the file containing the icon
    int      m_iconIndex;   // icon index in this file

    wxArrayString m_exts;   // the extensions which are mapped on this filetype


#if 0 // TODO
    // the additional (except "open" and "print") command names and values
    wxArrayString m_commandNames,
                  m_commandValues;
#endif // 0
};

WX_DECLARE_USER_EXPORTED_OBJARRAY(wxFileTypeInfo, wxArrayFileTypeInfo,
                                  WXDLLIMPEXP_BASE);

// ----------------------------------------------------------------------------
// wxFileType: gives access to all information about the files of given type.
//
// This class holds information about a given "file type". File type is the
// same as MIME type under Unix, but under Windows it corresponds more to an
// extension than to MIME type (in fact, several extensions may correspond to a
// file type). This object may be created in many different ways and depending
// on how it was created some fields may be unknown so the return value of all
// the accessors *must* be checked!
// ----------------------------------------------------------------------------

class WXDLLIMPEXP_BASE wxFileType
{
friend class WXDLLIMPEXP_FWD_BASE wxMimeTypesManagerImpl;  // it has access to m_impl

public:
    // An object of this class must be passed to Get{Open|Print}Command. The
    // default implementation is trivial and doesn't know anything at all about
    // parameters, only filename and MIME type are used (so it's probably ok for
    // Windows where %{param} is not used anyhow)
    class MessageParameters
    {
    public:
        // ctors
        MessageParameters() { }
        MessageParameters(const wxString& filename,
                          const wxString& mimetype = wxEmptyString)
            : m_filename(filename), m_mimetype(mimetype) { }

        // accessors (called by GetOpenCommand)
            // filename
        const wxString& GetFileName() const { return m_filename; }
            // mime type
        const wxString& GetMimeType() const { return m_mimetype; }

        // override this function in derived class
        virtual wxString GetParamValue(const wxString& WXUNUSED(name)) const
            { return wxEmptyString; }

        // virtual dtor as in any base class
        virtual ~MessageParameters() { }

    protected:
        wxString m_filename, m_mimetype;
    };

    // ctor from static data
    wxFileType(const wxFileTypeInfo& ftInfo);

    // accessors: all of them return true if the corresponding information
    // could be retrieved/found, false otherwise (and in this case all [out]
    // parameters are unchanged)
        // return the MIME type for this file type
    bool GetMimeType(wxString *mimeType) const;
    bool GetMimeTypes(wxArrayString& mimeTypes) const;
        // fill passed in array with all extensions associated with this file
        // type
    bool GetExtensions(wxArrayString& extensions);
        // get the icon corresponding to this file type and of the given size
    bool GetIcon(wxIconLocation *iconloc) const;
    bool GetIcon(wxIconLocation *iconloc,
                 const MessageParameters& params) const;
        // get a brief file type description ("*.txt" => "text document")
    bool GetDescription(wxString *desc) const;

    // get the command to be used to open/print the given file.
        // get the command to execute the file of given type
    bool GetOpenCommand(wxString *openCmd,
                        const MessageParameters& params) const;
        // a simpler to use version of GetOpenCommand() -- it only takes the
        // filename and returns an empty string on failure
    wxString GetOpenCommand(const wxString& filename) const;
        // get the command to print the file of given type
    bool GetPrintCommand(wxString *printCmd,
                         const MessageParameters& params) const;


        // return the number of commands defined for this file type, 0 if none
    size_t GetAllCommands(wxArrayString *verbs, wxArrayString *commands,
                          const wxFileType::MessageParameters& params) const;

    // set an arbitrary command, ask confirmation if it already exists and
    // overwriteprompt is true
    bool SetCommand(const wxString& cmd, const wxString& verb,
        bool overwriteprompt = true);

    bool SetDefaultIcon(const wxString& cmd = wxEmptyString, int index = 0);


    // remove the association for this filetype from the system MIME database:
    // notice that it will only work if the association is defined in the user
    // file/registry part, we will never modify the system-wide settings
    bool Unassociate();

    // operations
        // expand a string in the format of GetOpenCommand (which may contain
        // '%s' and '%t' format specifiers for the file name and mime type
        // and %{param} constructions).
    static wxString ExpandCommand(const wxString& command,
                                  const MessageParameters& params);

    // dtor (not virtual, shouldn't be derived from)
    ~wxFileType();

private:
    // default ctor is private because the user code never creates us
    wxFileType();

    // no copy ctor/assignment operator
    wxFileType(const wxFileType&);
    wxFileType& operator=(const wxFileType&);

    // the static container of wxFileType data: if it's not NULL, it means that
    // this object is used as fallback only
    const wxFileTypeInfo *m_info;

    // the object which implements the real stuff like reading and writing
    // to/from system MIME database
    wxFileTypeImpl *m_impl;
};

//----------------------------------------------------------------------------
// wxMimeTypesManagerFactory
//----------------------------------------------------------------------------

class WXDLLIMPEXP_BASE wxMimeTypesManagerFactory
{
public:
    wxMimeTypesManagerFactory() {}
    virtual ~wxMimeTypesManagerFactory() {}

    virtual wxMimeTypesManagerImpl *CreateMimeTypesManagerImpl();

    static void Set( wxMimeTypesManagerFactory *factory );
    static wxMimeTypesManagerFactory *Get();

private:
    static wxMimeTypesManagerFactory *m_factory;
};

// ----------------------------------------------------------------------------
// wxMimeTypesManager: interface to system MIME database.
//
// This class accesses the information about all known MIME types and allows
// the application to retrieve information (including how to handle data of
// given type) about them.
// ----------------------------------------------------------------------------

class WXDLLIMPEXP_BASE wxMimeTypesManager
{
public:
    // static helper functions
    // -----------------------

        // check if the given MIME type is the same as the other one: the
        // second argument may contain wildcards ('*'), but not the first. If
        // the types are equal or if the mimeType matches wildcard the function
        // returns true, otherwise it returns false
    static bool IsOfType(const wxString& mimeType, const wxString& wildcard);

    // ctor
    wxMimeTypesManager();

    // NB: the following 2 functions are for Unix only and don't do anything
    //     elsewhere

    // loads data from standard files according to the mailcap styles
    // specified: this is a bitwise OR of wxMailcapStyle values
    //
    // use the extraDir parameter if you want to look for files in another
    // directory
    void Initialize(int mailcapStyle = wxMAILCAP_ALL,
                    const wxString& extraDir = wxEmptyString);

    // and this function clears all the data from the manager
    void ClearData();

    // Database lookup: all functions return a pointer to wxFileType object
    // whose methods may be used to query it for the information you're
    // interested in. If the return value is !NULL, caller is responsible for
    // deleting it.
        // get file type from file extension
    wxFileType *GetFileTypeFromExtension(const wxString& ext);
        // get file type from MIME type (in format <category>/<format>)
    wxFileType *GetFileTypeFromMimeType(const wxString& mimeType);

    // enumerate all known MIME types
    //
    // returns the number of retrieved file types
    size_t EnumAllFileTypes(wxArrayString& mimetypes);

    // these functions can be used to provide default values for some of the
    // MIME types inside the program itself
    //
    // The filetypes array should be terminated by either NULL entry or an
    // invalid wxFileTypeInfo (i.e. the one created with default ctor)
    void AddFallbacks(const wxFileTypeInfo *filetypes);
    void AddFallback(const wxFileTypeInfo& ft) { m_fallbacks.Add(ft); }

    // create or remove associations

        // create a new association using the fields of wxFileTypeInfo (at least
        // the MIME type and the extension should be set)
        // if the other fields are empty, the existing values should be left alone
    wxFileType *Associate(const wxFileTypeInfo& ftInfo);

        // undo Associate()
    bool Unassociate(wxFileType *ft) ;

    // dtor (not virtual, shouldn't be derived from)
    ~wxMimeTypesManager();

private:
    // no copy ctor/assignment operator
    wxMimeTypesManager(const wxMimeTypesManager&);
    wxMimeTypesManager& operator=(const wxMimeTypesManager&);

    // the fallback info which is used if the information is not found in the
    // real system database
    wxArrayFileTypeInfo m_fallbacks;

    // the object working with the system MIME database
    wxMimeTypesManagerImpl *m_impl;

    // if m_impl is NULL, create one
    void EnsureImpl();

    friend class wxMimeTypeCmnModule;
};


// ----------------------------------------------------------------------------
// global variables
// ----------------------------------------------------------------------------

// the default mime manager for wxWidgets programs
extern WXDLLIMPEXP_DATA_BASE(wxMimeTypesManager *) wxTheMimeTypesManager;

#endif // wxUSE_MIMETYPE

#endif
  //_WX_MIMETYPE_H_