FmFolderView

FmFolderView — A folder view generic interface.

Synopsis

                    FmFolderView;
enum                FmFolderViewClickType;
struct              FmFolderViewColumnInfo;
struct              FmFolderViewInterface;
void                (*FmFolderViewUpdatePopup)          (FmFolderView *fv,
                                                         GtkWindow *window,
                                                         GtkUIManager *ui,
                                                         GtkActionGroup *act_grp,
                                                         FmFileInfoList *files);
GtkMenu *           fm_folder_view_add_popup            (FmFolderView *fv,
                                                         GtkWindow *parent,
                                                         FmFolderViewUpdatePopup update_popup);
void                fm_folder_view_bounce_action        (GtkAction *act,
                                                         FmFolderView *fv);
FmPathList *        fm_folder_view_dup_selected_file_paths
                                                        (FmFolderView *fv);
FmFileInfoList *    fm_folder_view_dup_selected_files   (FmFolderView *fv);
GSList *            fm_folder_view_get_columns          (FmFolderView *fv);
FmPath *            fm_folder_view_get_cwd              (FmFolderView *fv);
FmFileInfo *        fm_folder_view_get_cwd_info         (FmFolderView *fv);
FmFolder *          fm_folder_view_get_folder           (FmFolderView *fv);
guint               fm_folder_view_get_mode             (FmFolderView *fv);
FmFolderModel *     fm_folder_view_get_model            (FmFolderView *fv);
gint                fm_folder_view_get_n_selected_files (FmFolderView *fv);
GtkSelectionMode    fm_folder_view_get_selection_mode   (FmFolderView *fv);
gboolean            fm_folder_view_get_show_hidden      (FmFolderView *fv);
FmFolderModelCol    fm_folder_view_get_sort_by          (FmFolderView *fv);
GtkSortType         fm_folder_view_get_sort_type        (FmFolderView *fv);
void                fm_folder_view_item_clicked         (FmFolderView *fv,
                                                         GtkTreePath *path,
                                                         FmFolderViewClickType type);
FmFolderView *      fm_folder_view_new                  (guint mode);
void                fm_folder_view_sel_changed          (GObject *obj,
                                                         FmFolderView *fv);
void                fm_folder_view_select_all           (FmFolderView *fv);
void                fm_folder_view_select_custom        (FmFolderView *fv,
                                                         GFunc filter,
                                                         gpointer user_data);
void                fm_folder_view_select_file_path     (FmFolderView *fv,
                                                         FmPath *path);
void                fm_folder_view_select_file_paths    (FmFolderView *fv,
                                                         FmPathList *paths);
void                fm_folder_view_select_invert        (FmFolderView *fv);
void                fm_folder_view_set_active           (FmFolderView *fv,
                                                         gboolean set);
gboolean            fm_folder_view_set_columns          (FmFolderView *fv,
                                                         const GSList *cols);
void                fm_folder_view_set_mode             (FmFolderView *fv,
                                                         guint mode);
void                fm_folder_view_set_model            (FmFolderView *fv,
                                                         FmFolderModel *model);
void                fm_folder_view_set_selection_mode   (FmFolderView *fv,
                                                         GtkSelectionMode mode);
void                fm_folder_view_set_show_hidden      (FmFolderView *fv,
                                                         gboolean show);
void                fm_folder_view_sort                 (FmFolderView *fv,
                                                         GtkSortType type,
                                                         FmFolderModelCol by);
void                fm_folder_view_unselect_all         (FmFolderView *fv);

Object Hierarchy

  GInterface
   +----FmFolderView

Prerequisites

FmFolderView requires GtkWidget.

Known Implementations

FmFolderView is implemented by FmStandardView.

Signals

  "clicked"                                        : Run First
  "filter-changed"                                 : Run First
  "sel-changed"                                    : Run First
  "sort-changed"                                   : Run First

Description

include: libfm/fm-folder-view.h

The FmFolderView generic interface is used to implement folder views common code including handling sorting change, and keyboard and mouse buttons events.

The FmFolderView interface methods can attach context menu to widget which does folder operations and consists of items:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
CreateNew -> NewFolder
             NewBlank
             NewShortcut
             <placeholder name='ph1'/>
------------------------
Paste
Cut
Copy
Del
Remove
FileProp
------------------------
SelAll
InvSel
------------------------
Sort -> Asc
        Desc
        ----------------
        ByName
        ByMTime
        BySize
        ByType
        ----------------
        <placeholder name='CustomSortOps'/>
ShowHidden
Rename
<placeholder name='CustomFolderOps'/>
------------------------
<placeholder name='CustomCommonOps'/>
------------------------
Prop

In created menu items 'Cut', 'Copy', 'Del', 'Remove', 'FileProp', and 'Rename' are hidden.

Widget can modity the menu replacing placeholders and hiding or enabling existing items in it. Widget can do that in callback which is supplied for call fm_folder_view_add_popup().

If click was not on widget but on some item in it then not this context menu but one with FmFileMenu object will be opened instead.

Details

FmFolderView

typedef struct _FmFolderView FmFolderView;

enum FmFolderViewClickType

typedef enum {
    FM_FV_CLICK_NONE,
    FM_FV_ACTIVATED,
    FM_FV_MIDDLE_CLICK,
    FM_FV_CONTEXT_MENU
} FmFolderViewClickType;

Click type for "clicked" signal handlers.

FM_FV_CLICK_NONE

no click

FM_FV_ACTIVATED

this can be triggered by both left single or double click depending on whether single-click activation is used or not.

FM_FV_MIDDLE_CLICK

middle mouse button pressed

FM_FV_CONTEXT_MENU

right mouse button pressed

struct FmFolderViewColumnInfo

struct FmFolderViewColumnInfo {
    FmFolderModelCol col_id;
};

FmFolderView column setup data.

FmFolderModelCol col_id;

column type

struct FmFolderViewInterface

struct FmFolderViewInterface {
    /* signals */
    void (*clicked)(FmFolderView* fv, FmFolderViewClickType type, FmFileInfo* file);
    void (*sel_changed)(FmFolderView* fv, FmFileInfoList* sels);
    void (*sort_changed)(FmFolderView* fv);
    /* void (*filter_changed)(FmFolderView* fv); */
    //void (*chdir)(FmFolderView* fv, FmPath* path);

    /* VTable */
    void (*set_sel_mode)(FmFolderView* fv, GtkSelectionMode mode);
    GtkSelectionMode (*get_sel_mode)(FmFolderView* fv);

    void (*set_sort)(FmFolderView* fv, GtkSortType type, FmFolderModelCol by);
    void (*get_sort)(FmFolderView* fv, GtkSortType* type, FmFolderModelCol* by);

    void (*set_show_hidden)(FmFolderView* fv, gboolean show);
    gboolean (*get_show_hidden)(FmFolderView* fv);

    FmFolder* (*get_folder)(FmFolderView* fv);

    void (*set_model)(FmFolderView* fv, FmFolderModel* model);
    FmFolderModel* (*get_model)(FmFolderView* fv);

    gint (*count_selected_files)(FmFolderView* fv);
    FmFileInfoList* (*dup_selected_files)(FmFolderView* fv);
    FmPathList* (*dup_selected_file_paths)(FmFolderView* fv);

    void (*select_all)(FmFolderView* fv);
    void (*unselect_all)(FmFolderView* fv);
    void (*select_invert)(FmFolderView* fv);
    void (*select_file_path)(FmFolderView* fv, FmPath* path);

    /* for implementation internal usage */
    void (*get_custom_menu_callbacks)(FmFolderView* fv, FmFolderViewUpdatePopup*,
                                      FmLaunchFolderFunc*);
    /* FIXME: add few reserved after ABI change */
};

clicked ()

the class closure for "clicked" signal

sel_changed ()

the class closure for "sel-changed" signal

sort_changed ()

the class closure for "sort-changed" signal

set_sel_mode ()

VTable func, see fm_folder_view_set_selection_mode()

get_sel_mode ()

VTable func, see fm_folder_view_get_selection_mode()

set_sort ()

unused since 1.0.2, will be removed from ABI 5

get_sort ()

unused since 1.0.2, will be removed from ABI 5

set_show_hidden ()

function to save show_hidden in the object structure

get_show_hidden ()

function to retrieve show_hidden from the object structure

get_folder ()

VTable func, see fm_folder_view_get_folder()

set_model ()

VTable func, see fm_folder_view_set_model()

get_model ()

VTable func, see fm_folder_view_get_model()

count_selected_files ()

VTable func, see fm_folder_view_get_n_selected_files()

dup_selected_files ()

VTable func, see fm_folder_view_dup_selected_files()

dup_selected_file_paths ()

VTable func, see fm_folder_view_dup_selected_file_paths()

select_all ()

VTable func, see fm_folder_view_select_all()

unselect_all ()

VTable func, see fm_folder_view_unselect_all()

select_invert ()

VTable func, see fm_folder_view_select_invert()

select_file_path ()

VTable func, see fm_folder_view_select_file_path()

get_custom_menu_callbacks ()

function to retrieve callbacks for popup menu setup

FmFolderViewUpdatePopup ()

void                (*FmFolderViewUpdatePopup)          (FmFolderView *fv,
                                                         GtkWindow *window,
                                                         GtkUIManager *ui,
                                                         GtkActionGroup *act_grp,
                                                         FmFileInfoList *files);

The callback to update popup menu. It can disable items of menu, add some new, replace actions, etc. depending of the window and files.

fv :

the folder view widget

window :

the window where fv is present

ui :

the object to add interface

act_grp :

group of actions to add action

files :

list of files for current popup menu

fm_folder_view_add_popup ()

GtkMenu *           fm_folder_view_add_popup            (FmFolderView *fv,
                                                         GtkWindow *parent,
                                                         FmFolderViewUpdatePopup update_popup);

Adds popup menu to window parent associated with widget fv. This includes hotkeys for popup menu items. Popup will be destroyed and hotkeys will be removed from parent when fv is finalized.

fv :

a widget to apply

parent :

parent window of fv

update_popup :

function to extend popup menu for folder

Returns :

a new created widget. [transfer none]

Since 1.0.1


fm_folder_view_bounce_action ()

void                fm_folder_view_bounce_action        (GtkAction *act,
                                                         FmFolderView *fv);

Executes the action with the same name as act in popup menu of fv. The popup menu should be created with fm_folder_view_add_popup() before this call.

Implemented actions are:

  • Cut : cut files into clipboard

  • Copy : copy files into clipboard

  • Paste : paste files from clipboard

  • Del : move files into trash bin

  • Remove : delete files from filesystem

  • SelAll : select all

  • InvSel : invert selection

  • Rename : rename the folder

  • Prop : folder properties dialog

  • FileProp : file properties dialog

  • NewFolder : create new folder here

See also: fm_folder_view_add_popup().

act :

an action to execute

fv :

a widget to apply

Since 1.0.1


fm_folder_view_dup_selected_file_paths ()

FmPathList *        fm_folder_view_dup_selected_file_paths
                                                        (FmFolderView *fv);

Retrieves a list of the currently selected files. The list should be freed after usage with fm_path_list_unref(). If there are no files selected then returns NULL.

Before 1.0.0 this API had name fm_folder_view_get_selected_file_paths.

fv :

a FmFolderView object

Returns :

list of selected file paths. [transfer full][element-type FmPath]

Since 0.1.0


fm_folder_view_dup_selected_files ()

FmFileInfoList *    fm_folder_view_dup_selected_files   (FmFolderView *fv);

Retrieves a list of the currently selected files. The list should be freed after usage with fm_file_info_list_unref(). If there are no files selected then returns NULL.

Before 1.0.0 this API had name fm_folder_view_get_selected_files.

fv :

a FmFolderView object

Returns :

list of selected file infos. [transfer full][element-type FmFileInfo]

Since 0.1.0


fm_folder_view_get_columns ()

GSList *            fm_folder_view_get_columns          (FmFolderView *fv);

Retrieves current composition of fv as list of column infos. Returned list should be freed with g_slist_free() after usage.

fv :

the folder view widget to query

Returns :

list of column infos. [transfer container][element-type FmFolderViewColumnInfo]

Since 1.0.2


fm_folder_view_get_cwd ()

FmPath *            fm_folder_view_get_cwd              (FmFolderView *fv);

Retrieves file path of the folder shown by fv. Returned data are owned by fv and should not be freed by caller.

fv :

a widget to inspect

Returns :

file path of the folder. [transfer none]

Since 0.1.0


fm_folder_view_get_cwd_info ()

FmFileInfo *        fm_folder_view_get_cwd_info         (FmFolderView *fv);

Retrieves file info of the folder shown by fv. Returned data are owned by fv and should not be freed by caller.

fv :

a widget to inspect

Returns :

file info descriptor of the folder. [transfer none]

Since 0.1.0


fm_folder_view_get_folder ()

FmFolder *          fm_folder_view_get_folder           (FmFolderView *fv);

Retrieves the folder shown by fv. Returned data are owned by fv and should not be freed by caller.

fv :

a widget to inspect

Returns :

the folder of view. [transfer none]

Since 1.0.0


fm_folder_view_get_mode ()

guint               fm_folder_view_get_mode             (FmFolderView *fv);

Warning

fm_folder_view_get_mode has been deprecated since version 1.0.1 and should not be used in newly-written code. Use fm_standard_view_get_mode() instead.

fv :

a widget to inspect

Returns :

current mode of view.

Since 0.1.0


fm_folder_view_get_model ()

FmFolderModel *     fm_folder_view_get_model            (FmFolderView *fv);

Retrieves the model used by fv. Returned data are owned by fv and should not be freed by caller.

fv :

a widget to inspect

Returns :

the model of view. [transfer none]

Since 0.1.16


fm_folder_view_get_n_selected_files ()

gint                fm_folder_view_get_n_selected_files (FmFolderView *fv);

Retrieves number of the currently selected files.

fv :

a widget to inspect

Returns :

number of files selected.

Since 1.0.1


fm_folder_view_get_selection_mode ()

GtkSelectionMode    fm_folder_view_get_selection_mode   (FmFolderView *fv);

Retrieves current selection mode in fv.

fv :

a widget to inspect

Returns :

current selection mode.

Since 0.1.0


fm_folder_view_get_show_hidden ()

gboolean            fm_folder_view_get_show_hidden      (FmFolderView *fv);

Retrieves setting whether hidden files in folder shown in fv should be visible or not.

See also: fm_folder_view_set_show_hidden().

fv :

a widget to inspect

Returns :

TRUE if hidden files are visible.

Since 0.1.0


fm_folder_view_get_sort_by ()

FmFolderModelCol    fm_folder_view_get_sort_by          (FmFolderView *fv);

Warning

fm_folder_view_get_sort_by has been deprecated since version 1.0.2 and should not be used in newly-written code. use fm_folder_model_get_sort() instead.

Retrieves current criteria of sorting in fv (e.g. by name).

fv :

a widget to inspect

Returns :

criteria of sorting.

Since 0.1.0


fm_folder_view_get_sort_type ()

GtkSortType         fm_folder_view_get_sort_type        (FmFolderView *fv);

Warning

fm_folder_view_get_sort_type has been deprecated since version 1.0.2 and should not be used in newly-written code. use fm_folder_model_get_sort() instead.

Retrieves current sorting type in fv.

fv :

a widget to inspect

Returns :

mode of sorting (ascending or descending)

Since 0.1.0


fm_folder_view_item_clicked ()

void                fm_folder_view_item_clicked         (FmFolderView *fv,
                                                         GtkTreePath *path,
                                                         FmFolderViewClickType type);

Handles left click and right click in folder area. If some item was left-clicked then fm_folder_view_item_clicked() tries to launch it. If some item was right-clicked then opens file menu (applying the update_popup returned by get_custom_menu_callbacks interface function before opening it if it's not NULL). If it was right-click on empty space of folder view (so path is NULL) then opens folder popup menu that was created by fm_folder_view_add_popup(). After that emits the "clicked" signal.

If open_folders callback from interface function get_custom_menu_callbacks is NULL then assume it was old API call so click will be not handled by this function and signal handler will handle it instead.

This API is internal for FmFolderView and should be used only in class implementations.

fv :

the folder view widget

path :

path to current pointed item. [allow-none]

type :

what click was received

Since 1.0.1


fm_folder_view_new ()

FmFolderView *      fm_folder_view_new                  (guint mode);

Warning

fm_folder_view_new has been deprecated since version 1.0.1 and should not be used in newly-written code. Use fm_standard_view_new() instead.

mode :

initial mode of view

Returns :

a new FmFolderView widget.

Since 0.1.0


fm_folder_view_sel_changed ()

void                fm_folder_view_sel_changed          (GObject *obj,
                                                         FmFolderView *fv);

Emits the "sel-changed" signal.

This API is internal for FmFolderView and should be used only in class implementations.

obj :

some object; unused

fv :

the folder view widget to apply

Since 1.0.1


fm_folder_view_select_all ()

void                fm_folder_view_select_all           (FmFolderView *fv);

Selects all files in folder.

fv :

a widget to apply

Since 0.1.0


fm_folder_view_select_custom ()

void                fm_folder_view_select_custom        (FmFolderView *fv,
                                                         GFunc filter,
                                                         gpointer user_data);

Warning

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


fm_folder_view_select_file_path ()

void                fm_folder_view_select_file_path     (FmFolderView *fv,
                                                         FmPath *path);

Selects a file in the folder.

fv :

a widget to apply

path :

a file path to select

Since 0.1.0


fm_folder_view_select_file_paths ()

void                fm_folder_view_select_file_paths    (FmFolderView *fv,
                                                         FmPathList *paths);

Selects few files in the folder.

fv :

a widget to apply

paths :

list of files to select

Since 0.1.0


fm_folder_view_select_invert ()

void                fm_folder_view_select_invert        (FmFolderView *fv);

Selects all unselected files in fv but unselects all selected.

fv :

a widget to apply

Since 0.1.0


fm_folder_view_set_active ()

void                fm_folder_view_set_active           (FmFolderView *fv,
                                                         gboolean set);

If set is TRUE then activates accelerators on the fv that were created with fm_folder_view_add_popup() before. If set is FALSE then deactivates accelerators on the fv. This API is useful if the application window contains more than one folder view so gestures will be used only on active view. This API has no effect in no popup menu was created with fm_folder_view_add_popup() before this call.

See also: fm_folder_view_add_popup().

fv :

the folder view widget to apply

set :

state of accelerators to be set

Since 1.0.1


fm_folder_view_set_columns ()

gboolean            fm_folder_view_set_columns          (FmFolderView *fv,
                                                         const GSList *cols);

Changes composition (rendering) of folder view fv in accordance to new list of column infos.

fv :

the folder view widget to apply

cols :

new list of column infos. [element-type FmFolderViewColumnInfo]

Returns :

TRUE in case of success.

Since 1.0.2


fm_folder_view_set_mode ()

void                fm_folder_view_set_mode             (FmFolderView *fv,
                                                         guint mode);

Warning

fm_folder_view_set_mode has been deprecated since version 1.0.1 and should not be used in newly-written code. Use fm_standard_view_set_mode() instead.

fv :

a widget to apply

mode :

new mode of view

Since 0.1.0


fm_folder_view_set_model ()

void                fm_folder_view_set_model            (FmFolderView *fv,
                                                         FmFolderModel *model);

Changes model for the fv.

fv :

a widget to apply

model :

new view model. [allow-none]

Since 1.0.0


fm_folder_view_set_selection_mode ()

void                fm_folder_view_set_selection_mode   (FmFolderView *fv,
                                                         GtkSelectionMode mode);

Changes selection mode in fv.

fv :

a widget to apply

mode :

new mode of selection in fv.

Since 0.1.0


fm_folder_view_set_show_hidden ()

void                fm_folder_view_set_show_hidden      (FmFolderView *fv,
                                                         gboolean show);

Changes whether hidden files in folder shown in fv should be visible or not.

See also: fm_folder_view_get_show_hidden().

fv :

a widget to apply

show :

new setting

Since 0.1.0


fm_folder_view_sort ()

void                fm_folder_view_sort                 (FmFolderView *fv,
                                                         GtkSortType type,
                                                         FmFolderModelCol by);

Warning

fm_folder_view_sort has been deprecated since version 1.0.2 and should not be used in newly-written code. Use fm_folder_model_set_sort() instead.

Changes sorting in the view. Invalid values for type or by are ignored (will not change sorting).

Since 1.0.2 values passed to this API aren't remembered in the fv object. If fv has no model then this API has no effect. After the model is removed from fv (calling fm_folder_view_set_model() with NULL) there is no possibility to recover last settings and any model added to fv later will get defaults: FM_FOLDER_MODEL_COL_DEFAULT and FM_SORT_DEFAULT.

fv :

a widget to apply

type :

new mode of sorting (ascending or descending)

by :

criteria of sorting

Since 0.1.0


fm_folder_view_unselect_all ()

void                fm_folder_view_unselect_all         (FmFolderView *fv);

Unselects all files in folder.

fv :

a widget to apply

Since 1.0.1

Signal Details

The "clicked" signal

void                user_function                      (FmFolderView *view,
                                                        guint         type,
                                                        gpointer      file,
                                                        gpointer      user_data)      : Run First

The "clicked" signal is emitted when user clicked somewhere in the folder area. If click was on free folder area then file is NULL.

view :

the widget that emitted the signal

type :

(FmFolderViewClickType) type of click

file :

(FmFileInfo *) file on which cursor is

user_data :

user data set when the signal handler was connected.

Since 0.1.0


The "filter-changed" signal

void                user_function                      (FmFolderView *view,
                                                        gpointer      user_data)      : Run First

The "filter-changed" signal is emitted when filter of the view model got changed. It's just bouncer for the same signal of FmFolderModel.

view :

the widget that emitted the signal

user_data :

user data set when the signal handler was connected.

Since 1.0.2


The "sel-changed" signal

void                user_function                      (FmFolderView *view,
                                                        gint          n_sel,
                                                        gpointer      user_data)      : Run First

The "sel-changed" signal is emitted when selection of the view got changed.

Before 1.0.0 parameter was list of currently selected files.

view :

the widget that emitted the signal

n_sel :

number of files currently selected in the folder

user_data :

user data set when the signal handler was connected.

Since 0.1.0


The "sort-changed" signal

void                user_function                      (FmFolderView *view,
                                                        gpointer      user_data)      : Run First

The "sort-changed" signal is emitted when sorting of the view got changed.

view :

the widget that emitted the signal

user_data :

user data set when the signal handler was connected.

Since 0.1.10