#include <wx/mimetype.h>

Detailed Description

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 several different ways: the program might know the file extension and wish to find out the corresponding MIME type or, conversely, it might want to find the right extension for the file to which it writes the contents of given MIME type. Depending on how it was created some fields may be unknown so the return value of all the accessors must be checked: false will be returned if the corresponding information couldn't be found.

The objects of this class are never created by the application code but are returned by wxMimeTypesManager::GetFileTypeFromMimeType and wxMimeTypesManager::GetFileTypeFromExtension methods. But it is your responsibility to delete the returned pointer when you're done with it!

A brief reminder about what the MIME types are (see the RFC 1341 for more information): basically, it is just a pair category/type (for example, "text/plain") where the category is a basic indication of what a file is. Examples of categories are "application", "image", "text", "binary", and type is a precise definition of the document format: "plain" in the example above means just ASCII text without any formatting, while "text/html" is the HTML document source.

A MIME type may have one or more associated extensions: "text/plain" will typically correspond to the extension ".txt", but may as well be associated with ".ini" or ".conf".

MessageParameters class

One of the most common usages of MIME is to encode an e-mail message. The MIME type of the encoded message is an example of a message parameter. These parameters are found in the message headers ("Content-XXX").

At the very least, they must specify the MIME type and the version of MIME used, but almost always they provide additional information about the message such as the original file name or the charset (for the text documents). These parameters may be useful to the program used to open, edit, view or print the message, so, for example, an e-mail client program will have to pass them to this program. Because wxFileType itself cannot know about these parameters, it uses MessageParameters class to query them.

The default implementation only requires the caller to provide the file name (always used by the program to be called - it must know which file to open) and the MIME type and supposes that there are no other parameters.

If you wish to supply additional parameters, you must derive your own class from MessageParameters and override GetParamValue() function, for example:

// provide the message parameters for the MIME type manager
class MailMessageParameters : public wxFileType::MessageParameters
{
public:
    MailMessageParameters(const wxString& filename,
                            const wxString& mimetype)
        : wxFileType::MessageParameters(filename, mimetype)
    {
    }
    virtual wxString GetParamValue(const wxString& name) const
    {
        // parameter names are not case-sensitive
        if ( name.CmpNoCase("charset") == 0 )
            return "US-ASCII";
        else
            return wxFileType::MessageParameters::GetParamValue(name);
    }
};

Now you only need to create an object of this class and pass it to, for example, GetOpenCommand like this:

wxString command;
if ( filetype->GetOpenCommand(&command,
                            MailMessageParameters("foo.txt", "text/plain")) )
{
    // the full command for opening the text documents is in 'command'
    // (it might be "notepad foo.txt" under Windows or "cat foo.txt" under Unix)
}
else
{
    // we don't know how to handle such files...
}

Windows: As only the file name is used by the program associated with the given extension anyhow (but no other message parameters), there is no need to ever derive from MessageParameters class for a Windows-only program.

Library: wxBase

Category: Data Structures

See Also: wxMimeTypesManager

Classes
class	MessageParameters
	Class representing message parameters. More...

Public Member Functions
	wxFileType (const wxFileTypeInfo &ftInfo)
	Copy ctor.

	~wxFileType ()
	The destructor of this class is not virtual, so it should not be derived from.

bool	GetDescription (wxString *desc) const
	If the function returns true, the string pointed to by desc is filled with a brief description for this file type: for example, "text document" for the "text/plain" MIME type.

bool	GetExtensions (wxArrayString &extensions)
	If the function returns true, the array extensions is filled with all extensions associated with this file type: for example, it may contain the following two elements for the MIME type "text/html" (notice the absence of the leading dot): "html" and "htm".

bool	GetIcon (wxIconLocation *iconLoc) const
	If the function returns true, the `iconLoc` is filled with the location of the icon for this MIME type.

bool	GetMimeType (wxString *mimeType) const
	If the function returns true, the string pointed to by mimeType is filled with full MIME type specification for this file type: for example, "text/plain".

bool	GetMimeTypes (wxArrayString &mimeTypes) const
	Same as GetMimeType() but returns array of MIME types.

bool	GetPrintCommand (wxString *command, const MessageParameters &params) const
	If the function returns true, the string pointed to by command is filled with the command which must be executed (see wxExecute()) in order to print the file of the given type.

size_t	GetAllCommands (wxArrayString verbs, wxArrayString commands, const wxFileType::MessageParameters &params) const
	Returns the number of commands for this mime type, and fills the verbs and commands arrays with the command information.


bool	GetOpenCommand (wxString *command, const MessageParameters &params)
	With the first version of this method, if the true is returned, the string pointed to by command is filled with the command which must be executed (see wxExecute()) in order to open the file of the given type.

wxString	GetOpenCommand (const wxString &filename) const
	With the first version of this method, if the true is returned, the string pointed to by command is filled with the command which must be executed (see wxExecute()) in order to open the file of the given type.

Static Public Member Functions
static wxString	ExpandCommand (const wxString &command, const MessageParameters &params)
	This function is primarily intended for GetOpenCommand and GetPrintCommand usage but may be also used by the application directly if, for example, you want to use some non-default command to open the file.

Constructor & Destructor Documentation

wxFileType::wxFileType ( const wxFileTypeInfo & ftInfo )

Copy ctor.

wxFileType::~wxFileType ( )

The destructor of this class is not virtual, so it should not be derived from.

Member Function Documentation

static wxString wxFileType::ExpandCommand	(	const wxString &	command,
		const MessageParameters &	params
	)

static

This function is primarily intended for GetOpenCommand and GetPrintCommand usage but may be also used by the application directly if, for example, you want to use some non-default command to open the file.

The function replaces all occurrences of:

s with the full file name
t with the MIME type
%{param} with the value of the parameter param using the MessageParameters object you pass to it.

If there is no 's' in the command string (and the string is not empty), it is assumed that the command reads the data on stdin and so the effect is the same as " %s" were appended to the string.

Unlike all other functions of this class, there is no error return for this function.

size_t wxFileType::GetAllCommands	(	wxArrayString *	verbs,
		wxArrayString *	commands,
		const wxFileType::MessageParameters &	params
	)		const

Returns the number of commands for this mime type, and fills the verbs and commands arrays with the command information.

bool wxFileType::GetDescription ( wxString * desc ) const

If the function returns true, the string pointed to by desc is filled with a brief description for this file type: for example, "text document" for the "text/plain" MIME type.

bool wxFileType::GetExtensions ( wxArrayString & extensions )

If the function returns true, the array extensions is filled with all extensions associated with this file type: for example, it may contain the following two elements for the MIME type "text/html" (notice the absence of the leading dot): "html" and "htm".

Windows: This function is currently not implemented: there is no (efficient) way to retrieve associated extensions from the given MIME type on this platform, so it will only return true if the wxFileType object was created by wxMimeTypesManager::GetFileTypeFromExtension function in the first place.

bool wxFileType::GetIcon ( wxIconLocation * iconLoc ) const

If the function returns true, the iconLoc is filled with the location of the icon for this MIME type.

A wxIcon may be created from iconLoc later.

Note: Under Unix MIME manager gathers information about icons from GNOME and KDE settings and thus GetIcon's success depends on availability of these desktop environments.

bool wxFileType::GetMimeType ( wxString * mimeType ) const

If the function returns true, the string pointed to by mimeType is filled with full MIME type specification for this file type: for example, "text/plain".

bool wxFileType::GetMimeTypes ( wxArrayString & mimeTypes ) const

Same as GetMimeType() but returns array of MIME types.

This array will contain only one item in most cases but sometimes, notably under Unix with KDE, may contain more MIME types. This happens when one file extension is mapped to different MIME types by KDE, mailcap and mime.types.

bool wxFileType::GetOpenCommand	(	wxString *	command,
		const MessageParameters &	params
	)

With the first version of this method, if the true is returned, the string pointed to by command is filled with the command which must be executed (see wxExecute()) in order to open the file of the given type.

In this case, the name of the file as well as any other parameters is retrieved from MessageParameters() class.

In the second case, only the filename is specified and the command to be used to open this kind of file is returned directly. An empty string is returned to indicate that an error occurred (typically meaning that there is no standard way to open this kind of files).

wxString wxFileType::GetOpenCommand ( const wxString & filename ) const

With the first version of this method, if the true is returned, the string pointed to by command is filled with the command which must be executed (see wxExecute()) in order to open the file of the given type.

In this case, the name of the file as well as any other parameters is retrieved from MessageParameters() class.

In the second case, only the filename is specified and the command to be used to open this kind of file is returned directly. An empty string is returned to indicate that an error occurred (typically meaning that there is no standard way to open this kind of files).

bool wxFileType::GetPrintCommand	(	wxString *	command,
		const MessageParameters &	params
	)		const

If the function returns true, the string pointed to by command is filled with the command which must be executed (see wxExecute()) in order to print the file of the given type.

The name of the file is retrieved from the MessageParameters class.

Detailed Description

MessageParameters class

Classes

Public Member Functions

Static Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation