hildon-file-system-model

hildon-file-system-model — a tree model that contains file system data.

Synopsis




enum        HildonFileSystemModelColumns;
gboolean    (*HildonFileSystemModelThumbnailCallback)
                                            (const gchar *uri,
                                             const gchar *path,
                                             const gchar *thumbnail_file);
            HildonFileSystemModelPrivate;
#define     hildon_file_system_model_create_backend
gboolean    hildon_file_system_model_finished_loading
                                            (HildonFileSystemModel *model);
gboolean    hildon_file_system_model_search_local_path
                                            (HildonFileSystemModel *model,
                                             const gchar *path,
                                             GtkTreeIter *iter,
                                             GtkTreeIter *start_iter,
                                             gboolean recursive);
gboolean    hildon_file_system_model_search_uri
                                            (HildonFileSystemModel *model,
                                             const gchar *uri,
                                             GtkTreeIter *iter,
                                             GtkTreeIter *start_iter,
                                             gboolean recursive);
gboolean    hildon_file_system_model_search_path
                                            (HildonFileSystemModel *model,
                                             const GtkFilePath *path,
                                             GtkTreeIter *iter,
                                             GtkTreeIter *start_iter,
                                             gboolean recursive);
gboolean    hildon_file_system_model_load_local_path
                                            (HildonFileSystemModel *model,
                                             const gchar *path,
                                             GtkTreeIter *iter);
gboolean    hildon_file_system_model_load_uri
                                            (HildonFileSystemModel *model,
                                             const gchar *uri,
                                             GtkTreeIter *iter);
gboolean    hildon_file_system_model_load_path
                                            (HildonFileSystemModel *model,
                                             const GtkFilePath *path,
                                             GtkTreeIter *iter);
gchar*      hildon_file_system_model_new_item
                                            (HildonFileSystemModel *model,
                                             GtkTreeIter *parent,
                                             const gchar *stub_name,
                                             const gchar *extension);
gchar*      hildon_file_system_model_autoname_uri
                                            (HildonFileSystemModel *model,
                                             const gchar *uri,
                                             GError **error);
void        hildon_file_system_model_iter_available
                                            (HildonFileSystemModel *model,
                                             GtkTreeIter *iter,
                                             gboolean available);
void        hildon_file_system_model_reset_available
                                            (HildonFileSystemModel *model);

Description

HildonFileSystemModel is a GtkTreeModel that mirrors actual file system. It uses heavily GtkFileSystem methods and it's APIs also reflect this. This widget is mainly used by HildonFileSelection, but you can use it to conveniently access the same data that is displayed in the file selection.

You can create a custom file selection by following code:
GtkWidget *selection;
HildonFileSystemModel *model = HILDON_FILE_SYSTEM_MODEL(g_object_new(
  HILDON_TYPE_FILE_SYSTEM_MODEL, "ref-widget", widget, NULL));

selection = hildon_file_selection_new_with_model(model);
Note that you need to provide a reference widget when creating a file system model. This can be any widget on the same screen. Reference widget is needed when creating icons.
You can conveniently access the image or text data used in HildonFileSelection:
GtkTreeIter iter;
GdkPixbuf *pixbuf;
gchar *name;

gtk_tree_model_get_iter_first(GTK_TREE_MODEL(model), &iter); /* First device */

gtk_tree_model_get(GTK_TREE_MODEL(model), &iter, 
  HILDON_FILE_SYSTEM_MODEL_COLUMN_ICON, &pixbuf,
  HILDON_FILE_SYSTEM_MODEL_COLUMN_DISPLAY_NAME, &name, -1);

/* ... use pixbuf and name ... */

g_object_unref(pixbuf);
g_free(name);

Details

enum HildonFileSystemModelColumns

typedef enum {
    HILDON_FILE_SYSTEM_MODEL_COLUMN_GTK_PATH = 0,
    HILDON_FILE_SYSTEM_MODEL_COLUMN_LOCAL_PATH,
    HILDON_FILE_SYSTEM_MODEL_COLUMN_URI,
    HILDON_FILE_SYSTEM_MODEL_COLUMN_FILE_NAME,
    HILDON_FILE_SYSTEM_MODEL_COLUMN_DISPLAY_NAME,
    HILDON_FILE_SYSTEM_MODEL_COLUMN_SORT_KEY,
    HILDON_FILE_SYSTEM_MODEL_COLUMN_MIME_TYPE,
    HILDON_FILE_SYSTEM_MODEL_COLUMN_FILE_SIZE,
    HILDON_FILE_SYSTEM_MODEL_COLUMN_FILE_TIME,
    HILDON_FILE_SYSTEM_MODEL_COLUMN_IS_FOLDER,
    HILDON_FILE_SYSTEM_MODEL_COLUMN_IS_AVAILABLE,
    HILDON_FILE_SYSTEM_MODEL_COLUMN_HAS_LOCAL_PATH,
    HILDON_FILE_SYSTEM_MODEL_COLUMN_TYPE,
    HILDON_FILE_SYSTEM_MODEL_COLUMN_ICON,
    HILDON_FILE_SYSTEM_MODEL_COLUMN_ICON_EXPANDED,  /* Normal icon with
                                                       expanded emblem */
    HILDON_FILE_SYSTEM_MODEL_COLUMN_ICON_COLLAPSED, /* Normal icon with 
                                                       collapsed emblem */
    HILDON_FILE_SYSTEM_MODEL_COLUMN_THUMBNAIL,
    HILDON_FILE_SYSTEM_MODEL_COLUMN_LOAD_READY,
    HILDON_FILE_SYSTEM_MODEL_COLUMN_FREE_SPACE, /* Only for devices */

    HILDON_FILE_SYSTEM_MODEL_COLUMN_TITLE,
    HILDON_FILE_SYSTEM_MODEL_COLUMN_AUTHOR,

    HILDON_FILE_SYSTEM_MODEL_COLUMN_IS_HIDDEN,

    HILDON_FILE_SYSTEM_MODEL_NUM_COLUMNS
} HildonFileSystemModelColumns;


HildonFileSystemModelThumbnailCallback ()

gboolean    (*HildonFileSystemModelThumbnailCallback)
                                            (const gchar *uri,
                                             const gchar *path,
                                             const gchar *thumbnail_file);

Setting this callback is depricated and it don't do anything.

uri : Location of the source file.
path : Local path of the source file (can be NULL if no local path is available).
thumbnail_file : Name of the thumbnail file to be generated.
Returns : TRUE, if thumbnail generation succeeded.

HildonFileSystemModelPrivate

typedef struct _HildonFileSystemModelPrivate HildonFileSystemModelPrivate;


hildon_file_system_model_create_backend

#define hildon_file_system_model_create_backend hildon_file_system_create_backend

Returns :

hildon_file_system_model_finished_loading ()

gboolean    hildon_file_system_model_finished_loading
                                            (HildonFileSystemModel *model);

Checks if model has data in it's processing queue. Note! This api is broken an DEPRICATED. It only checks internal processing queue and this information is mostly useless.

model : a HildonFileSystemModel.
Returns : TRUE, data queues are empty.

hildon_file_system_model_search_local_path ()

gboolean    hildon_file_system_model_search_local_path
                                            (HildonFileSystemModel *model,
                                             const gchar *path,
                                             GtkTreeIter *iter,
                                             GtkTreeIter *start_iter,
                                             gboolean recursive);

a wrapped for hildon_file_system_model_search_path that accepts local paths.

model : a HildonFileSystemModel.
path : a GtkFilePath to load.
iter : a GtkTreeIter for the result.
start_iter : a GtkTreeIter for starting point. NULL for entire model.
recursive : if FALSE, only immediate children of the parent are searched. TRUE searches the entire subtree.
Returns : TRUE, if the iterator points to desired file. FALSE otherwise.

hildon_file_system_model_search_uri ()

gboolean    hildon_file_system_model_search_uri
                                            (HildonFileSystemModel *model,
                                             const gchar *uri,
                                             GtkTreeIter *iter,
                                             GtkTreeIter *start_iter,
                                             gboolean recursive);

a wrapped for hildon_file_system_model_search_path that accepts URIs.

model : a HildonFileSystemModel.
uri :
iter : a GtkTreeIter for the result.
start_iter : a GtkTreeIter for starting point. NULL for entire model.
recursive : if FALSE, only immediate children of the parent are searched. TRUE searches the entire subtree.
Returns : TRUE, if the iterator points to desired file. FALSE otherwise.

hildon_file_system_model_search_path ()

gboolean    hildon_file_system_model_search_path
                                            (HildonFileSystemModel *model,
                                             const GtkFilePath *path,
                                             GtkTreeIter *iter,
                                             GtkTreeIter *start_iter,
                                             gboolean recursive);

Searches the model for given path and fills an iterator pointing to it. Note that the path must already exist in model.

model : a HildonFileSystemModel.
path : a GtkFilePath to load.
iter : a GtkTreeIter for the result.
start_iter : a GtkTreeIter for starting point. NULL for entire model.
recursive : if FALSE, only immediate children of the parent are searched. TRUE searches the entire subtree.
Returns : TRUE, if the iterator points to desired file. FALSE otherwise.

hildon_file_system_model_load_local_path ()

gboolean    hildon_file_system_model_load_local_path
                                            (HildonFileSystemModel *model,
                                             const gchar *path,
                                             GtkTreeIter *iter);

Converts the given path to GtkFilePath and calls hildon_file_system_model_load_path.

model : a HildonFileSystemModel.
path : a path to load.
iter : a GtkTreeIter for the result.
Returns : TRUE, if the iterator points to desired file. FALSE otherwise.

hildon_file_system_model_load_uri ()

gboolean    hildon_file_system_model_load_uri
                                            (HildonFileSystemModel *model,
                                             const gchar *uri,
                                             GtkTreeIter *iter);

Converts the given URI to GtkFilePath and calls hildon_file_system_model_load_path.

model : a HildonFileSystemModel.
uri :
iter : a GtkTreeIter for the result.
Returns : TRUE, if the iterator points to desired file. FALSE otherwise.

hildon_file_system_model_load_path ()

gboolean    hildon_file_system_model_load_path
                                            (HildonFileSystemModel *model,
                                             const GtkFilePath *path,
                                             GtkTreeIter *iter);

This method locates the given path from data model. New branches are loaded if the given path doesn't exist in memory. Otherwise similar to hildon_file_system_model_search_path.

model : a HildonFileSystemModel.
path : a GtkFilePath to load.
iter : a GtkTreeIter for the result.
Returns : TRUE, if the iterator points to desired file. FALSE otherwise.

hildon_file_system_model_new_item ()

gchar*      hildon_file_system_model_new_item
                                            (HildonFileSystemModel *model,
                                             GtkTreeIter *parent,
                                             const gchar *stub_name,
                                             const gchar *extension);

Creates a new unique name under parent. The returned name can be used when creating a new file. If there are no name collisions, stub name will be the final name. If a file with that name already exists, then a number is appended to stub. This function is mainly used by dialog implementations. It's probably not needed in application development.

model : a HildonFileSystemModel.
parent : a parent iterator.
stub_name : a boby of the new name.
extension : extension of the new name.
Returns : a New unique name. You have to release this with g_free. Can be NULL, if the directory is not yet loaded.

hildon_file_system_model_autoname_uri ()

gchar*      hildon_file_system_model_autoname_uri
                                            (HildonFileSystemModel *model,
                                             const gchar *uri,
                                             GError **error);

This function checks if the given URI already exists in the model. if not, then a copy of it is returned unmodified. If the URI already exists then a number is added in a form file://file(2).html.

model : a HildonFileSystemModel.
uri : an URI to be autonamed.
error : a GError to hold possible error information.
Returns : either the same uri given as parameter or a modified uri that contains proper index number. In both cases free this value using g_free. Value can be NULL, if error was encountered.

hildon_file_system_model_iter_available ()

void        hildon_file_system_model_iter_available
                                            (HildonFileSystemModel *model,
                                             GtkTreeIter *iter,
                                             gboolean available);

This function sets some paths available/not available. Locations that are not available are usually shown dimmed in the gui. This function can be used if program needs for some reason to disable some locations. By default all paths are available.

model : a HildonFileSystemModel.
iter : a GtkTreeIter to location to modify.
available : new availability state.

hildon_file_system_model_reset_available ()

void        hildon_file_system_model_reset_available
                                            (HildonFileSystemModel *model);

Cancels all changes made by hildon_file_system_model_iter_available. Selection is back to it's default state.

model : a HildonFileSystemModel.