ThunarxFileInfo
3
THUNARX Library

# ThunarxFileInfo

Abstraction of a file handled within the file manager

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <thunarx/thunarx.h>

                        ThunarxFileInfoIface;
                        ThunarxFileInfo;
    gchar*              thunarx_file_info_get_name          (ThunarxFileInfo *file_info);
    gchar*              thunarx_file_info_get_uri           (ThunarxFileInfo *file_info);
    gchar*              thunarx_file_info_get_parent_uri    (ThunarxFileInfo *file_info);
    gchar*              thunarx_file_info_get_uri_scheme    (ThunarxFileInfo *file_info);
    gchar*              thunarx_file_info_get_mime_type     (ThunarxFileInfo *file_info);
    gboolean            thunarx_file_info_has_mime_type     (ThunarxFileInfo *file_info,
                                                             const gchar *mime_type);
    gboolean            thunarx_file_info_is_directory      (ThunarxFileInfo *file_info);
    ThunarVfsInfo*      thunarx_file_info_get_vfs_info      (ThunarxFileInfo *file_info);
    void                thunarx_file_info_changed           (ThunarxFileInfo *file_info);
    void                thunarx_file_info_renamed           (ThunarxFileInfo *file_info);
    #define             THUNARX_TYPE_FILE_INFO_LIST
    GList*              thunarx_file_info_list_copy         (GList *file_infos);
    void                thunarx_file_info_list_free         (GList *file_infos);

## Object Hierarchy

      GInterface
       +----ThunarxFileInfo

## Prerequisites

ThunarxFileInfo requires GObject.

## Signals

      "changed"                                        : Run First
      "renamed"                                        : Run First

## Description

The ThunarxFileInfo interface provides extensions with a way to access information about a file handled within the file manager.

## Details

### ThunarxFileInfoIface

    typedef struct {
      /* virtual methods */
      gchar         *(*get_name)        (ThunarxFileInfo *file_info);

      gchar         *(*get_uri)         (ThunarxFileInfo *file_info);
      gchar         *(*get_parent_uri)  (ThunarxFileInfo *file_info);
      gchar         *(*get_uri_scheme)  (ThunarxFileInfo *file_info);

      gchar         *(*get_mime_type)   (ThunarxFileInfo *file_info);
      gboolean       (*has_mime_type)   (ThunarxFileInfo *file_info,
                                         const gchar     *mime_type);

      gboolean       (*is_directory)    (ThunarxFileInfo *file_info);

      ThunarVfsInfo *(*get_vfs_info)    (ThunarxFileInfo *file_info);

      /* signals */
      void (*changed) (ThunarxFileInfo *file_info);
      void (*renamed) (ThunarxFileInfo *file_info);
    } ThunarxFileInfoIface;

Interface with virtual methods implemented by the file manager and accessible from the extensions.

get_name ()

  See `thunarx_file_info_get_name()`.

get_uri ()

  See `thunarx_file_info_get_uri()`.

get_parent_uri ()

  See `thunarx_file_info_get_parent_uri()`.

get_uri_scheme ()

  See `thunarx_file_info_get_uri_scheme()`.

get_mime_type ()

  See `thunarx_file_info_get_mime_type()`.

has_mime_type ()

  See `thunarx_file_info_has_mime_type()`.

is_directory ()

  See `thunarx_file_info_is_directory()`.

get_vfs_info ()

  See `thunarx_file_info_get_vfs_info()`.

changed ()

  See `thunarx_file_info_changed()`.

renamed ()

  See `thunarx_file_info_renamed()`.

### ThunarxFileInfo

    typedef struct _ThunarxFileInfo ThunarxFileInfo;

File info type, which is mapped to the real file info implementation within the file manager.

### thunarx_file_info_get_name ()

    gchar*              thunarx_file_info_get_name          (ThunarxFileInfo *file_info);

Returns the real name of the file represented by `file_info` in the local file system encoding. You can use `g_filename_display_name()` or similar functions to generate an UTF-8 version of the name, which is suitable for use in the user interface.

The caller is responsible to free the returned string using `g_free()` when no longer needed.

`file_info` :

  a ThunarxFileInfo.

Returns :

  the real name of the file represented by `file_info`.

### thunarx_file_info_get_uri ()

    gchar*              thunarx_file_info_get_uri           (ThunarxFileInfo *file_info);

Returns the escaped, fully qualified URI of the file object represented by `file_info`. You may use `g_filename_from_uri()` and similar functions to work with the returned URI.

The caller is responsible to free the returned string using `g_free()` when no longer needed.

`file_info` :

  a ThunarxFileInfo.

Returns :

  the fully qualified URI of `file_info`.

### thunarx_file_info_get_parent_uri ()

    gchar*              thunarx_file_info_get_parent_uri    (ThunarxFileInfo *file_info);

Returns the URI to the parent file of `file_info` or `NULL` if `file_info` has no parent. Note that the parent URI may be of a different type than the URI of `file_info`. For example, the parent of "file:///" is "computer:///".

The caller is responsible to free the returned string using `g_free()` when no longer needed.

`file_info` :

  a ThunarxFileInfo.

Returns :

  the parent URI for `file_info` or `NULL`.

### thunarx_file_info_get_uri_scheme ()

    gchar*              thunarx_file_info_get_uri_scheme    (ThunarxFileInfo *file_info);

Returns the URI scheme of the file represented by `file_info`. E.g. if `file_info` refers to the file "file:///usr/home", the return value will be "file".

The caller is responsible to free the returned string using `g_free()` when no longer needed.

`file_info` :

  a ThunarxFileInfo.

Returns :

  the URI scheme for `file_info`.

### thunarx_file_info_get_mime_type ()

    gchar*              thunarx_file_info_get_mime_type     (ThunarxFileInfo *file_info);

Returns the MIME-type of the file represented by `file_info` or `NULL` if no MIME-type is known for `file_info`.

The caller is responsible to free the returned string using `g_free()` when no longer needed.

`file_info` :

  a ThunarxFileInfo.

Returns :

  the MIME-type for `file_info` or `NULL`.

### thunarx_file_info_has_mime_type ()

    gboolean            thunarx_file_info_has_mime_type     (ThunarxFileInfo *file_info,
                                                             const gchar *mime_type);

Checks whether `file_info` is of the given `mime_type` or whether the MIME-type of `file_info` is a subclass of `mime_type`.

This is the preferred way for most extensions to check whether they support a given file or not, and you should consider using this method rather than `thunarx_file_info_get_mime_type()`. A simple example would be a menu extension that performs a certain action on text files. In this case you want to check whether a given ThunarxFileInfo refers to any kind of text file, not only to "text/plain" (e.g. this also includes "text/xml" and "application/x-desktop").

But you should be aware that this method may take some time to test whether `mime_type` is valid for `file_info`, so don't call it too often.

`file_info` :

  a ThunarxFileInfo.

`mime_type` :

  a MIME-type (e.g. "text/plain").

Returns :

  `TRUE` if `mime_type` is valid for `file_info`, else `FALSE`.

### thunarx_file_info_is_directory ()

    gboolean            thunarx_file_info_is_directory      (ThunarxFileInfo *file_info);

Checks whether `file_info` refers to a directory.

`file_info` :

  a ThunarxFileInfo.

Returns :

  `TRUE` if `file_info` is a directory.

### thunarx_file_info_get_vfs_info ()

    ThunarVfsInfo*      thunarx_file_info_get_vfs_info      (ThunarxFileInfo *file_info);

Returns the ThunarVfsInfo associated with `file_info`, which includes additional information about the `file_info` as queried from the VFS library earlier. The caller is responsible to free the returned ThunarVfsInfo object using `thunar_vfs_info_unref()` when no longer needed.

Note that the thunarx library itself is not linked to the thunar-vfs library, and so, if you need to use this method, you'll need to include `<thunar-vfs/thunar-vfs.h>` in your code and add ``pkg-config --cflags thunar-vfs-1`` to your `CFLAGS`.

`file_info` :

  a ThunarxFileInfo.

Returns :

  the ThunarVfsInfo object associated with `file_info`, which MUST be freed using `thunar_vfs_info_unref()`.

### thunarx_file_info_changed ()

    void                thunarx_file_info_changed           (ThunarxFileInfo *file_info);

Emits the ::changed signal on `file_info`. This method should not be invoked by Thunar plugins, instead the file manager itself will use this method to emit ::changed whenever it notices a change on `file_info`.

`file_info` :

  a ThunarxFileInfo.

### thunarx_file_info_renamed ()

    void                thunarx_file_info_renamed           (ThunarxFileInfo *file_info);

Emits the ::renamed signal on `file_info`. This method should not be invoked by Thunar plugins, instead the file manager will emit this signal whenever the user renamed the `file_info`.

The plugins should instead connect to the ::renamed signal and update it's internal state and it's user interface after the file manager renamed a file.

`file_info` :

  a ThunarxFileInfo.

### THUNARX_TYPE_FILE_INFO_LIST

    #define THUNARX_TYPE_FILE_INFO_LIST (thunarx_file_info_list_get_type ())

The GType for a boxed type holding a GList of ThunarxFileInfos. See `thunarx_file_info_list_copy()` and `thunarx_file_info_list_free()`.

### thunarx_file_info_list_copy ()

    GList*              thunarx_file_info_list_copy         (GList *file_infos);

Does a deep copy of `file_infos` and returns the new list.

`file_infos` :

  a GList of ThunarxFileInfos.

Returns :

  a copy of `file_infos`.

### thunarx_file_info_list_free ()

    void                thunarx_file_info_list_free         (GList *file_infos);

Frees the resources allocated for the `file_infos` list and decreases the reference count on the ThunarxFileInfos contained within.

`file_infos` :

  a GList of ThunarxFileInfos.

## Signal Details

### The `"changed"` signal

    void                user_function                      (ThunarxFileInfo *file_info,
                                                            gpointer         user_data)      : Run First

Emitted whenever the system notices a change to `file_info`.

Thunar plugins should use this signal to stay informed about changes to a `file_info` for which they currently display information (i.e. in a ThunarxPropertyPage), and update it's user interface whenever a change is noticed on `file_info`.

`file_info` :

  a ThunarxFileInfo.

`user_data` :

  user data set when the signal handler was connected.

### The `"renamed"` signal

    void                user_function                      (ThunarxFileInfo *file_info,
                                                            gpointer         user_data)      : Run First

Emitted when the `file_info` is renamed to another name.

For example, within Thunar, ThunarFolder uses this signal to reregister it's VFS directory monitor, after the corresponding file was renamed.

`file_info` :

  a ThunarxFileInfo

`user_data` :

  user data set when the signal handler was connected.