HildonFileSelection

HildonFileSelection

Synopsis

enum                HildonFileSelectionMode;
enum                HildonFileSelectionSortKey;
enum                HildonFileSelectionPane;
enum                HildonFileSelectionVisibleColumns;
                    HildonFileSelectionPrivate;
                    HildonFileSelection;
GtkWidget*          hildon_file_selection_new_with_model
                                                        (HildonFileSystemModel *model);
void                hildon_file_selection_set_empty_text
                                                        (HildonFileSelection *file_selection,
                                                         const gchar *empty_text);
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_uri
                                                        (HildonFileSelection *self,
                                                         const char *folder,
                                                         GError **error);
char*               hildon_file_selection_get_current_folder_uri
                                                        (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);
void                hildon_file_selection_set_current_folder_iter
                                                        (HildonFileSelection *self,
                                                         GtkTreeIter *main_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_uri    (HildonFileSelection *self,
                                                         const char *uri,
                                                         GError **error);
void                hildon_file_selection_unselect_uri  (HildonFileSelection *self,
                                                         const char *uri);
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_uris
                                                        (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_column_headers_visible
                                                        (HildonFileSelection *self,
                                                         gbooleanvisible );
gboolean            hildon_file_selection_get_column_headers_visible
                                                        (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_navigation_pane
                                                        (HildonFileSelection *self);
void                hildon_file_selection_hide_content_pane
                                                        (HildonFileSelection *self);
void                hildon_file_selection_show_content_pane
                                                        (HildonFileSelection *self);
void                hildon_file_selection_move_cursor_to_uri
                                                        (HildonFileSelection *self,
                                                         const gchar *uri);

Object Hierarchy

  GObject
   +----GInitiallyUnowned
         +----GtkObject
               +----GtkWidget
                     +----GtkContainer
                           +----HildonFileSelection

Implemented Interfaces

HildonFileSelection implements AtkImplementorIface and GtkBuildable.

Properties

  "active-pane"              gint                  : Read / Write
  "currently-dragging"       gboolean              : Read
  "drag-enabled"             gboolean              : Read / Write / Construct Only
  "edit-mode"                gboolean              : Read / Write / Construct Only
  "empty-text"               gchar*                : Read / Write
  "hide-navi"                gboolean              : Read / Write / Construct Only
  "local-only"               gboolean              : Read / Write
  "model"                    HildonFileSystemModel*  : Read / Write / Construct Only
  "pane-position"            gint                  : Read / Write / Construct
  "safe-folder"              GtkFilePath*          : Read / Write
  "show-files"               gboolean              : Read / Write / Construct
  "show-folders"             gboolean              : Read / Write / Construct
  "show-hidden"              gboolean              : Read / Write
  "show-readonly"            gboolean              : Read / Write / Construct
  "show-upnp"                gboolean              : Read / Write / Construct
  "visible-columns"          gint                  : Read / Write / Construct Only

Signals

  "content-pane-context-menu"                      : Run Last
  "current-folder-changed"                         : Run Last
  "file-activated"                                 : Run Last
  "folder-activated"                               : Run Last
  "location-insensitive"                           : Run Last
  "navigation-pane-context-menu"                   : Run Last
  "selection-changed"                              : Run Last
  "uris-dropped"                                   : Run Last

Description

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.


HildonFileSelection

typedef struct _HildonFileSelection HildonFileSelection;


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_empty_text ()

void                hildon_file_selection_set_empty_text
                                                        (HildonFileSelection *file_selection,
                                                         const gchar *empty_text);

file_selection :
empty_text :

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_uri ()

gboolean            hildon_file_selection_set_current_folder_uri
                                                        (HildonFileSelection *self,
                                                         const char *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_uri ()

char*               hildon_file_selection_get_current_folder_uri
                                                        (HildonFileSelection *self);

Gets the URI of the currently active folder (the folder which is displayed in the content pane). You have to release the returned string with g_free.

self : a pointer to HildonFileSelection
Returns : a string.

hildon_file_selection_get_current_content_iter ()

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

Warning

hildon_file_selection_get_current_content_iter is deprecated and should not be used in newly-written code.

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_set_current_folder_iter ()

void                hildon_file_selection_set_current_folder_iter
                                                        (HildonFileSelection *self,
                                                         GtkTreeIter *main_iter);

self :
main_iter :

hildon_file_selection_get_active_content_iter ()

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

Warning

hildon_file_selection_get_active_content_iter is deprecated and should not be used in newly-written code.

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);

Warning

hildon_file_selection_content_iter_is_selected is deprecated and should not be used in newly-written code.

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_uri ()

gboolean            hildon_file_selection_select_uri    (HildonFileSelection *self,
                                                         const char *uri,
                                                         GError **error);

Selects the given file. If the URI 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
uri : 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_uri ()

void                hildon_file_selection_unselect_uri  (HildonFileSelection *self,
                                                         const char *uri);

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
uri : file to unselect

hildon_file_selection_select_all ()

void                hildon_file_selection_select_all    (HildonFileSelection *self);

Selects the first row in the content pane.

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_uris ()

GSList*             hildon_file_selection_get_selected_uris
                                                        (HildonFileSelection *self);

Gets list of selected URIs from content pane. You have to release the returned list with g_free for the individual URIs and g_slist_free for the list nodes. 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_uris or hildon_file_selection_get_current_folder_uri.

self : a pointer to HildonFileSelection
Returns : a GSList containing strings.

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.

Since 2.1.4 this function has no effect. Create a separate HildonFileSelection with "edit-mode" set to TRUE instead.

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_column_headers_visible ()

void                hildon_file_selection_set_column_headers_visible
                                                        (HildonFileSelection *self,
                                                         gbooleanvisible );

Shown/hides column headers from list view.

self : a HildonFileSelection.
Param2 :

hildon_file_selection_get_column_headers_visible ()

gboolean            hildon_file_selection_get_column_headers_visible
                                                        (HildonFileSelection *self);

Returns whether column headers are shown or not.

self : a HildonFileSelection.
Returns : Whether column headers are shown or not.

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_navigation_pane ()

void                hildon_file_selection_hide_navigation_pane
                                                        (HildonFileSelection *self);

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

self : a pointer to HildonFileSelection

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

hildon_file_selection_move_cursor_to_uri ()

void                hildon_file_selection_move_cursor_to_uri
                                                        (HildonFileSelection *self,
                                                         const gchar *uri);

self :
uri :

Property Details

The "active-pane" property

  "active-pane"              gint                  : Read / Write

Allowed values: [0,1]

Default value: 0


The "currently-dragging" property

  "currently-dragging"       gboolean              : Read

Whether or not dragging is ongoing.

Default value: FALSE


The "drag-enabled" property

  "drag-enabled"             gboolean              : Read / Write / Construct Only

Ask file selection to enable drag'n'drop support.

Default value: FALSE


The "edit-mode" property

  "edit-mode"                gboolean              : Read / Write / Construct Only

create GtkTreeView in Edit Mode if this property is TRUE (FALSE by default).

Default value: FALSE


The "empty-text" property

  "empty-text"               gchar*                : Read / Write

String to use when selected folder is empty.

Default value: NULL


The "hide-navi" property

  "hide-navi"                gboolean              : Read / Write / Construct Only

Hide the left navigation pane if this property is TRUE (FALSE by default).

Default value: FALSE


The "local-only" property

  "local-only"               gboolean              : Read / Write

Whether or not all the displayed items should have a local file path.

Default value: FALSE


The "model" property

  "model"                    HildonFileSystemModel*  : Read / Write / Construct Only

Set the HildonFileSystemModel to display.


The "pane-position" property

  "pane-position"            gint                  : Read / Write / Construct

The position of the division between the both panes.

Allowed values: >= 0

Default value: 250


The "safe-folder" property

  "safe-folder"              GtkFilePath*          : Read / Write

Safe folder to use as fallback in various operations.


The "show-files" property

  "show-files"               gboolean              : Read / Write / Construct

show the files in the content pane if this property is TRUE (TRUE by default).

Default value: TRUE


The "show-folders" property

  "show-folders"             gboolean              : Read / Write / Construct

show folders in the content pane if this property is TRUE (TRUE by default).

Default value: TRUE


The "show-hidden" property

  "show-hidden"              gboolean              : Read / Write

Show hidden files in file selector widgets.

Default value: FALSE


The "show-readonly" property

  "show-readonly"            gboolean              : Read / Write / Construct

show readonly files and folders in the content pane if this property is TRUE (TRUE by default).

Default value: TRUE


The "show-upnp" property

  "show-upnp"                gboolean              : Read / Write / Construct

Whether or not to show UPNP devices.

Default value: FALSE


The "visible-columns" property

  "visible-columns"          gint                  : Read / Write / Construct Only

Defines the columns shown on content pane.

Allowed values: [0,7]

Default value: 7

Signal Details

The "content-pane-context-menu" signal

void                user_function                      (HildonFileSelection *self,
                                                        gpointer             user_data)      : Run Last

This signal is emitted when a context menu (if any) should be displayed on content pane.

self : a HildonFileSelection widget
user_data : user data set when the signal handler was connected.

The "current-folder-changed" signal

void                user_function                      (HildonFileSelection *self,
                                                        gpointer             user_data)      : Run Last

::current-folder-changed signal is emitted when current folder changes in navigation pane. Use hildon_file_selection_get_current_folder to receive folder path.

self : a HildonFileSelection widget
user_data : user data set when the signal handler was connected.

The "file-activated" signal

void                user_function                      (HildonFileSelection *self,
                                                        gpointer             user_data)      : Run Last

::file-activated signal is emitted when user selects an item from content pane.

self : a HildonFileSelection widget
user_data : user data set when the signal handler was connected.

The "folder-activated" signal

void                user_function                      (HildonFileSelection *self,
                                                        gpointer             user_data)      : Run Last

::folder-activated signal is emitted when user selects an folder item from content pane.

self : a HildonFileSelection widget
user_data : user data set when the signal handler was connected.

The "location-insensitive" signal

void                user_function                      (HildonFileSelection *self,
                                                        GtkTreeIter         *location,
                                                        gpointer             user_data)      : Run Last

This signal is emitted when user tries to interact with dimmed location.

self : a HildonFileSelection widget
location : insensitive location.
user_data : user data set when the signal handler was connected.

The "navigation-pane-context-menu" signal

void                user_function                      (HildonFileSelection *self,
                                                        gpointer             user_data)      : Run Last

This signal is emitted when a context menu (if any) should be displayed on navigation pane.

self : a HildonFileSelection widget
user_data : user data set when the signal handler was connected.

The "selection-changed" signal

void                user_function                      (HildonFileSelection *self,
                                                        gpointer             user_data)      : Run Last

This signal is emitted when selection changes on content pane. Use hildon_file_selection_get_selected_paths to receive paths.

self : a HildonFileSelection widget
user_data : user data set when the signal handler was connected.

The "uris-dropped" signal

void                user_function                      (HildonFileSelection *self,
                                                        gchar               *destination,
                                                        gpointer             sources,
                                                        gpointer             user_data)        : Run Last

This signal is emitted when user drags one or more items to some folder. This signal is emitted only if drag'n'drop is enabled during widget creation.

self : a HildonFileSelection widget
destination : Destination URI (this is quaranteed to be a directory).
sources : List of URIs that should be transferred to destination.
user_data : user data set when the signal handler was connected.