HildonFileSelection

HildonFileSelection — A file tree widget

Synopsis




enum        HildonFileSelectionMode;
enum        HildonFileSelectionSortKey;
enum        HildonFileSelectionPane;
enum        HildonFileSelectionVisibleColumns;
            HildonFileSelectionPrivate;
GtkWidget*  hildon_file_selection_new_with_model
                                            (HildonFileSystemModel *model);
void        hildon_file_selection_set_mode  (HildonFileSelection *self,
                                             HildonFileSelectionMode mode);
HildonFileSelectionMode hildon_file_selection_get_mode
                                            (HildonFileSelection *self);
void        hildon_file_selection_set_sort_key
                                            (HildonFileSelection *self,
                                             HildonFileSelectionSortKey key,
                                             GtkSortType order);
void        hildon_file_selection_get_sort_key
                                            (HildonFileSelection *self,
                                             HildonFileSelectionSortKey *key,
                                             GtkSortType *order);
gboolean    hildon_file_selection_set_current_folder
                                            (HildonFileSelection *self,
                                             const GtkFilePath *folder,
                                             GError **error);
GtkFilePath* hildon_file_selection_get_current_folder
                                            (HildonFileSelection *self);
gboolean    hildon_file_selection_get_current_content_iter
                                            (HildonFileSelection *self,
                                             GtkTreeIter *iter);
gboolean    hildon_file_selection_get_current_folder_iter
                                            (HildonFileSelection *self,
                                             GtkTreeIter *iter);
gboolean    hildon_file_selection_get_active_content_iter
                                            (HildonFileSelection *self,
                                             GtkTreeIter *iter);
gboolean    hildon_file_selection_content_iter_is_selected
                                            (HildonFileSelection *self,
                                             GtkTreeIter *iter);
gboolean    hildon_file_selection_select_path
                                            (HildonFileSelection *self,
                                             const GtkFilePath *path,
                                             GError **error);
void        hildon_file_selection_unselect_path
                                            (HildonFileSelection *self,
                                             const GtkFilePath *path);
void        hildon_file_selection_select_all
                                            (HildonFileSelection *self);
void        hildon_file_selection_unselect_all
                                            (HildonFileSelection *self);
void        hildon_file_selection_clear_multi_selection
                                            (HildonFileSelection *self);
GSList*     hildon_file_selection_get_selected_paths
                                            (HildonFileSelection *self);
void        hildon_file_selection_set_select_multiple
                                            (HildonFileSelection *self,
                                             gboolean select_multiple);
gboolean    hildon_file_selection_get_select_multiple
                                            (HildonFileSelection *self);
void        hildon_file_selection_set_filter
                                            (HildonFileSelection *self,
                                             GtkFileFilter *filter);
GtkFileFilter* hildon_file_selection_get_filter
                                            (HildonFileSelection *self);
void        hildon_file_selection_dim_current_selection
                                            (HildonFileSelection *self);
void        hildon_file_selection_undim_all (HildonFileSelection *self);
HildonFileSelectionPane hildon_file_selection_get_active_pane
                                            (HildonFileSelection *self);
void        hildon_file_selection_hide_content_pane
                                            (HildonFileSelection *self);
void        hildon_file_selection_show_content_pane
                                            (HildonFileSelection *self);

Description

HildonFileSelection displays file system as a two (by default) paned view. Navigation pane on the left lets the user to change directory that is automatically show on the content pane on the right. You can define a filter that is used when deciding which files to display on the content pane. You can also select the sorting order and view type (list or thumbnail). However, you probably don't need to use HildonFileSelection directly, but a more convenient HildonFileChooserDialog.

HildonFileSelection uses HildonFileSystemModel as its data store. Multiple file selections can share a common data model. This reduces memory consumption and loading times. This approach is used in HildonFileChooserDialog.

Details

enum HildonFileSelectionMode

    typedef enum {
    HILDON_FILE_SELECTION_MODE_LIST,
    HILDON_FILE_SELECTION_MODE_THUMBNAILS
} HildonFileSelectionMode;

View mode used for content pane.

HILDON_FILE_SELECTION_MODE_LIST List mode.
HILDON_FILE_SELECTION_MODE_THUMBNAILS Thumbnail mode.

enum HildonFileSelectionSortKey

typedef enum {
    HILDON_FILE_SELECTION_SORT_NAME = 0,
    HILDON_FILE_SELECTION_SORT_TYPE,
    HILDON_FILE_SELECTION_SORT_MODIFIED,
    HILDON_FILE_SELECTION_SORT_SIZE
} HildonFileSelectionSortKey;

Defines the sort key used in content pane. Folders are always sorted by name, regardless of this setting. Because of this setting doesn't affect navigation pane.

HILDON_FILE_SELECTION_SORT_NAME Sort by name. This is the default setting.
HILDON_FILE_SELECTION_SORT_TYPE Sort by MIME type.
HILDON_FILE_SELECTION_SORT_MODIFIED Sort by modification time.
HILDON_FILE_SELECTION_SORT_SIZE Sort by file size.

enum HildonFileSelectionPane

typedef enum {
    HILDON_FILE_SELECTION_PANE_NAVIGATION = 0,
    HILDON_FILE_SELECTION_PANE_CONTENT
} HildonFileSelectionPane;

Defines the logical panes. These can be used to query active pane or change it.

HILDON_FILE_SELECTION_PANE_NAVIGATION Navigation pane (left).
HILDON_FILE_SELECTION_PANE_CONTENT Content pane (right).

enum HildonFileSelectionVisibleColumns

typedef enum {
    HILDON_FILE_SELECTION_SHOW_NAME = 1,
    HILDON_FILE_SELECTION_SHOW_MODIFIED = 2,
    HILDON_FILE_SELECTION_SHOW_SIZE = 4,
    HILDON_FILE_SELECTION_SHOW_ALL = 7
} HildonFileSelectionVisibleColumns;

Defines what information about files and folder is shown in the context pane. You Can combine the values any way you like.

HILDON_FILE_SELECTION_SHOW_NAME Show filename.
HILDON_FILE_SELECTION_SHOW_MODIFIED Show modification time.
HILDON_FILE_SELECTION_SHOW_SIZE Show file size.
HILDON_FILE_SELECTION_SHOW_ALL Show all information.

HildonFileSelectionPrivate

typedef struct _HildonFileSelectionPrivate HildonFileSelectionPrivate;

This structure contains just internal data and shouldn't be accessed directly.


hildon_file_selection_new_with_model ()

GtkWidget*  hildon_file_selection_new_with_model
                                            (HildonFileSystemModel *model);

Creates a new HildonFileSelection using given model.

model : a HildonFileSystemModel to display.
Returns : a new HildonFileSelection

hildon_file_selection_set_mode ()

void        hildon_file_selection_set_mode  (HildonFileSelection *self,
                                             HildonFileSelectionMode mode);

Swithces file selection between list and thumbnail modes. Note that this function works only after widget is shown because of GtkNotebook implementation.

self : a pointer to HildonFileSelection
mode : New mode for current folder.

hildon_file_selection_get_mode ()

HildonFileSelectionMode hildon_file_selection_get_mode
                                            (HildonFileSelection *self);

Gets Current view mode for file selection widget. If widget is not shown this will return an invalid mode (-1). This is because of GtkNotebook implementation.

self : a pointer to HildonFileSelection
Returns : Current view mode.

hildon_file_selection_set_sort_key ()

void        hildon_file_selection_set_sort_key
                                            (HildonFileSelection *self,
                                             HildonFileSelectionSortKey key,
                                             GtkSortType order);

Changes sort settings for views. Key only affects content page, navigation pane is always sorted by name.

self : a pointer to HildonFileSelection
key : New sort key.
order : New sort order.

hildon_file_selection_get_sort_key ()

void        hildon_file_selection_get_sort_key
                                            (HildonFileSelection *self,
                                             HildonFileSelectionSortKey *key,
                                             GtkSortType *order);

Currently active sort settings are stored to user provided pointers.

self : a pointer to HildonFileSelection
key : a place to store sort key.
order : a place to store sort order.

hildon_file_selection_set_current_folder ()

gboolean    hildon_file_selection_set_current_folder
                                            (HildonFileSelection *self,
                                             const GtkFilePath *folder,
                                             GError **error);

Changes the content pane to display the given folder.

self : a pointer to HildonFileSelection
folder : a new folder.
error : a place to store possible error.
Returns : TRUE if directory change was succesful, FALSE if error occurred.

hildon_file_selection_get_current_folder ()

GtkFilePath* hildon_file_selection_get_current_folder
                                            (HildonFileSelection *self);

Gets a path to the currently active folder (the folder which is displayed in the content pane). You have to release the returned path with gtk_file_path_free.

self : a pointer to HildonFileSelection
Returns : a GtkFilePath.

hildon_file_selection_get_current_content_iter ()

gboolean    hildon_file_selection_get_current_content_iter
                                            (HildonFileSelection *self,
                                             GtkTreeIter *iter);

Similar to hildon_file_selection_get_current_folder_iter but this works with content pane. However, this function fails also if the content pane is not currently visible, more than one item is selected or if the current folder is empty.

Note! This function is DEPRECATED. You probably want to use hildon_file_selection_get_active_content_iter instead if you are intrested in single item.

self : a HildonFileSelection
iter : a GtkTreeIter for the result.
Returns : TRUE, if the given iterator is set, FALSE otherwise.

hildon_file_selection_get_current_folder_iter ()

gboolean    hildon_file_selection_get_current_folder_iter
                                            (HildonFileSelection *self,
                                             GtkTreeIter *iter);

Fills the given iterator to match currently selected item in the navigation pane. Internally this gets the selection from the tree and then the current iterator from selection and converts the result accordingly.

self : a HildonFileSelection
iter : a GtkTreeIter for the result.
Returns : TRUE, if the given iterator is set, FALSE otherwise.

hildon_file_selection_get_active_content_iter ()

gboolean    hildon_file_selection_get_active_content_iter
                                            (HildonFileSelection *self,
                                             GtkTreeIter *iter);

Gets an iterator to the item with active focus in content pane (cursor in GtkTreeView). Returned item need not to be selected, it just has the active focus. If there is no focus on the content pane, this function fails.

This function differs from hildon_file_selection_get_current_content_iter, because this function uses cursor, not GtkTreeSelection.

After checkboxes were removed there is no reason for this function to exists. That's why this is DEPRECATED.

self : a HildonFileSelection
iter : a GtkTreeIter for the result.
Returns : TRUE, if the given iterator is set, FALSE otherwise.

hildon_file_selection_content_iter_is_selected ()

gboolean    hildon_file_selection_content_iter_is_selected
                                            (HildonFileSelection *self,
                                             GtkTreeIter *iter);

Checks if the given iterator is selected in the content pane. There is no much use for this function. Treat this as DEPRECATED.

self : a HildonFileSelection
iter : a GtkTreeIter for the result.
Returns : TRUE, if the iterator is selected, FALSE otherwise.

hildon_file_selection_select_path ()

gboolean    hildon_file_selection_select_path
                                            (HildonFileSelection *self,
                                             const GtkFilePath *path,
                                             GError **error);

Selects the given file. If the path doesn't point to current folder the folder is changed accordingly. If multiple selection is disabled then the previous selection will dissappear.

self : a pointer to HildonFileSelection
path : a file to select.
error : a place to store possible error.
Returns : TRUE if folder was succesfully selected, FALSE if the path doesn't contain a valid folder.

hildon_file_selection_unselect_path ()

void        hildon_file_selection_unselect_path
                                            (HildonFileSelection *self,
                                             const GtkFilePath *path);

Unselects a currently selected filename. If the filename is not in the current directory, does not exist, or is otherwise not currently selected, does nothing.

self : a pointer to HildonFileSelection
path : file to unselect

hildon_file_selection_select_all ()

void        hildon_file_selection_select_all
                                            (HildonFileSelection *self);

Selects all files from the content pane. Multiple selection must be enabled before calling this.

self : a pointer to HildonFileSelection

hildon_file_selection_unselect_all ()

void        hildon_file_selection_unselect_all
                                            (HildonFileSelection *self);

Clears current selection from content pane.

self : a pointer to HildonFileSelection

hildon_file_selection_clear_multi_selection ()

void        hildon_file_selection_clear_multi_selection
                                            (HildonFileSelection *self);

Otherwise similar to hildon_file_selection_unselect_all, but keeps the node with cursor selected. Thus, this function don't have any efect in single selection mode.

self : a pointer to HildonFileSelection

hildon_file_selection_get_selected_paths ()

GSList*     hildon_file_selection_get_selected_paths
                                            (HildonFileSelection *self);

Gets list of selected paths from content pane. You have to release the returned list with gtk_file_paths_free. If you are interested in item that (probably) has active focus, you have to first get the active pane and then call either hildon_file_selection_get_selected_paths or hildon_file_selection_get_current_folder.

self : a pointer to HildonFileSelection
Returns : a GSList containing GtkFilePath objects.

hildon_file_selection_set_select_multiple ()

void        hildon_file_selection_set_select_multiple
                                            (HildonFileSelection *self,
                                             gboolean select_multiple);

If multiple selection is enabled, checkboxes will appear to the last item to the content pane. Multiple selection must be enabled if one wants to call hildon_file_selection_select_all.

self : a pointer to HildonFileSelection
select_multiple : either TRUE or FALSE.

hildon_file_selection_get_select_multiple ()

gboolean    hildon_file_selection_get_select_multiple
                                            (HildonFileSelection *self);

Gets state of multiple selection.

self : a pointer to HildonFileSelection
Returns : TRUE If multiple selection is currently enabled.

hildon_file_selection_set_filter ()

void        hildon_file_selection_set_filter
                                            (HildonFileSelection *self,
                                             GtkFileFilter *filter);

Only the files matching the filter will be displayed in content pane. Use NULL to remove filtering.

self : a pointer to HildonFileSelection
filter : a new GtkFileFilter.

hildon_file_selection_get_filter ()

GtkFileFilter* hildon_file_selection_get_filter
                                            (HildonFileSelection *self);

Get currently active filter set by hildon_file_selection_set filter. Can be NULL if no filter is set.

self : a pointer to HildonFileSelection
Returns : a GtkFileFilter or NULL.

hildon_file_selection_dim_current_selection ()

void        hildon_file_selection_dim_current_selection
                                            (HildonFileSelection *self);

Appends currently selected paths to set of dimmed paths. Note that dimmed paths cannot be selected, so selection no longer contains the same paths after this function.

self : a HildonFileSelection.

hildon_file_selection_undim_all ()

void        hildon_file_selection_undim_all (HildonFileSelection *self);

Undims all from model that are dimmed by code. Simply calls hildon_file_system_model_reset_available for underlying model.

self : a HildonFileSelection.

hildon_file_selection_get_active_pane ()

HildonFileSelectionPane hildon_file_selection_get_active_pane
                                            (HildonFileSelection *self);

Gets the pane that either has active focus or (in case of no pane has it) last time had it.

self : a HildonFileSelection.
Returns : Currently active pane.

hildon_file_selection_hide_content_pane ()

void        hildon_file_selection_hide_content_pane
                                            (HildonFileSelection *self);

Hides the content pane. This is used in certain file management dialogs.

self : a pointer to HildonFileSelection

hildon_file_selection_show_content_pane ()

void        hildon_file_selection_show_content_pane
                                            (HildonFileSelection *self);

Shows the content pane. This is used in certain file management dialogs. The content pane is shown by default. Calling this is needed only if you have hidden

self : a pointer to HildonFileSelection