.. wxPython Phoenix documentation

   This file was generated by Phoenix's sphinx generator and associated
   tools, do not edit by hand.

   Copyright: (c) 2011-2018 by Total Control Software
   License:   wxWindows License

.. include:: headings.inc



.. _wx.FileType:

==========================================================================================================================================
|phoenix_title|  **wx.FileType**
==========================================================================================================================================

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 :meth:`wx.MimeTypesManager.GetFileTypeFromMimeType`   and :meth:`wx.MimeTypesManager.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". 



|phoenix_title| 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 :ref:`wx.FileType`  itself cannot know about these parameters, it uses :ref:`wx.FileType.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 :ref:`wx.FileType.MessageParameters`  and override GetParamValue() function, for example: ::

        # provide the message parameters for the MIME type manager
        class MailMessageParameters(wx.MessageParameters):

            def __init__(self, filename, mimetype):

                wx.MessageParameters.__init__(self, filename, mimetype)


            def GetParamValue(self, name):

                # parameter names are not case-sensitive
                if name.lower() == "charset":
                    return "US-ASCII"
                else:
                    return wx.MessageParameters.GetParamValue(name)

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

        if filetype.GetOpenCommand(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)
            HandleCommand()

        else:

            # we don't know how to handle such files...
            pass

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 :ref:`wx.FileType.MessageParameters`  class for a Windows-only program.   



.. seealso:: :ref:`wx.MimeTypesManager`    







|

|class_hierarchy| Class Hierarchy
=================================

.. raw:: html

   <div id="toggleBlock" onclick="return toggleVisibility(this)" class="closed" style="cursor:pointer;">
   <img id="toggleBlock-trigger" src="_static/images/closed.png"/>
   Inheritance diagram for class <strong>FileType</strong>:
   </div>
   <div id="toggleBlock-summary" style="display:block;"></div>
   <div id="toggleBlock-content" style="display:none;">
   <p class="graphviz">
   <center><img src="_static/images/inheritance/wx.FileType_inheritance.png" alt="Inheritance diagram of FileType" usemap="#dummy" class="inheritance"/></center>
   </div>
   <script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.FileType.html" title="wx.FileType" alt="" coords="5,5,96,35"/> </map> 
   </p>

|


|method_summary| Methods Summary
================================

================================================================================ ================================================================================
:meth:`~wx.FileType.__init__`                                                    Copy constructor.
:meth:`~wx.FileType.ExpandCommand`                                               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.
:meth:`~wx.FileType.GetAllCommands`                                              Returns a tuple containing the `verbs` and `commands` arrays, corresponding for the registered information for this mime type.
:meth:`~wx.FileType.GetDescription`                                              Returns a brief description for this file type: for example, "text document" for
:meth:`~wx.FileType.GetExtensions`                                               Returns all extensions associated with this file type: for
:meth:`~wx.FileType.GetIcon`                                                     Return the icon associated with this mime type, if any.
:meth:`~wx.FileType.GetIconInfo`                                                 Returns a tuple containing the Icon for this file type, the file where the
:meth:`~wx.FileType.GetIconLocation`                                             Returns a wx.IconLocation that can be used to fetch the icon for this mime type.
:meth:`~wx.FileType.GetMimeType`                                                 Returns full MIME type specification for this file type: for example, "text/plain".
:meth:`~wx.FileType.GetMimeTypes`                                                Same as GetMimeType but returns a list of types.  This will usually contain
:meth:`~wx.FileType.GetOpenCommand`                                              Returns the command which must be executed (see wx.Execute()) in order
:meth:`~wx.FileType.GetPrintCommand`                                             Returns the command which must be executed (see Execute()) in order to
================================================================================ ================================================================================


|


|property_summary| Properties Summary
=====================================

================================================================================ ================================================================================
:attr:`~wx.FileType.Description`                                                 See :meth:`~wx.FileType.GetDescription`
:attr:`~wx.FileType.Extensions`                                                  See :meth:`~wx.FileType.GetExtensions`
:attr:`~wx.FileType.Icon`                                                        See :meth:`~wx.FileType.GetIcon`
:attr:`~wx.FileType.IconInfo`                                                    See :meth:`~wx.FileType.GetIconInfo`
:attr:`~wx.FileType.IconLocation`                                                See :meth:`~wx.FileType.GetIconLocation`
:attr:`~wx.FileType.MimeType`                                                    See :meth:`~wx.FileType.GetMimeType`
:attr:`~wx.FileType.MimeTypes`                                                   See :meth:`~wx.FileType.GetMimeTypes`
:attr:`~wx.FileType.OpenCommand`                                                 See :meth:`~wx.FileType.GetOpenCommand`
:attr:`~wx.FileType.PrintCommand`                                                See :meth:`~wx.FileType.GetPrintCommand`
================================================================================ ================================================================================


|


|api| Class API
===============


.. class:: wx.FileType(object)

   **Possible constructors**::

       FileType(ftInfo)
       
   
   This class holds information about a given file type.



   .. method:: __init__(self, ftInfo)

      Copy constructor.                  


      :param `ftInfo`: 
      :type `ftInfo`: wx.FileTypeInfo







   .. staticmethod:: ExpandCommand(command, 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.                  

      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 :ref:`wx.FileType.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.                  


      :param `command`: 
      :type `command`: string
      :param `params`: 
      :type `params`: wx.FileType.MessageParameters




      :rtype: `string`








   .. method:: GetAllCommands(self, params)

      Returns a tuple containing the `verbs` and `commands` arrays, corresponding for the registered information for this mime type. 


      :param `params`: 
      :type `params`: FileType.MessageParameters




      :rtype: `tuple`







      :returns: 

         ( `verbs`, `commands` ) 








   .. method:: GetDescription(self)

                              Returns a brief description for this file type: for example, "text document" for
                              the "text/plain" MIME type. 

      :rtype: `string`








   .. method:: GetExtensions(self)

                              Returns 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".

                              This function is not implemented on Windows, there is no (efficient)
                              way to retrieve associated extensions from the given MIME type on
                              this platform.  

      :rtype: `list of strings`








   .. method:: GetIcon(self)

      Return the icon associated with this mime type, if any. 

      :rtype: :ref:`wx.Icon`








   .. method:: GetIconInfo(self)

                              Returns a tuple containing the Icon for this file type, the file where the
                              icon is found, and the index of the image in that file, if applicable.
                         

      :rtype: :ref:`PyObject`








   .. method:: GetIconLocation(self)

      Returns a wx.IconLocation that can be used to fetch the icon for this mime type. 

      :rtype: :ref:`wx.IconLocation`








   .. method:: GetMimeType(self)

      Returns full MIME type specification for this file type: for example, "text/plain". 

      :rtype: `string`








   .. method:: GetMimeTypes(self)

                              Same as GetMimeType but returns a list of types.  This will usually contain
                              only one item, but sometimes, such as on Unix with KDE more than one type
                              if there are differences between KDE< mailcap and mime.types. 

      :rtype: `list of strings`








   .. method:: GetOpenCommand(self, *args, **kw)



      |overload| Overloaded Implementations:

      **~~~**

      
      **GetOpenCommand** `(self, params)`
      
                              Returns the command which must be executed (see wx.Execute()) in order
                              to open the file of the given type. The name of the file as well as
                              any other parameters is retrieved from MessageParameters() class. 
      
      :rtype: `string`
      
      
      
      
      
      
      
      **~~~**

      
      **GetOpenCommand** `(self, filename)`
      
                              Returns the command which should be used to open the given
                              filename. 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). 
      
      :rtype: `string`
      
      
      
      
      
      
      
      **~~~**






   .. method:: GetPrintCommand(self, params)

                              Returns the command which must be executed (see Execute()) in order to
                              print the file of the given type. The name of the file is retrieved from
                              the MessageParameters class. 

      :rtype: `string`








   .. attribute:: Description

      See :meth:`~wx.FileType.GetDescription`


   .. attribute:: Extensions

      See :meth:`~wx.FileType.GetExtensions`


   .. attribute:: Icon

      See :meth:`~wx.FileType.GetIcon`


   .. attribute:: IconInfo

      See :meth:`~wx.FileType.GetIconInfo`


   .. attribute:: IconLocation

      See :meth:`~wx.FileType.GetIconLocation`


   .. attribute:: MimeType

      See :meth:`~wx.FileType.GetMimeType`


   .. attribute:: MimeTypes

      See :meth:`~wx.FileType.GetMimeTypes`


   .. attribute:: OpenCommand

      See :meth:`~wx.FileType.GetOpenCommand`


   .. attribute:: PrintCommand

      See :meth:`~wx.FileType.GetPrintCommand`