FmFolderView

FmFolderView — A folder view generic interface.

Functions

Signals

void clicked Run First
void columns-changed Run First
void filter-changed Run First
void sel-changed Run First
void sort-changed Run First

Types and Values

Object Hierarchy

    GInterface
    ╰── FmFolderView

Prerequisites

FmFolderView requires GtkWidget.

Known Implementations

FmFolderView is implemented by FmStandardView.

Description

include : libfm/fm-gtk.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
32
33
34
35
CreateNew -> NewFolder
             <placeholder name='ph1'/>
             ----------------
             NewBlank
------------------------
<placeholder name='CustomFileOps'/>
------------------------
Paste
Cut
Copy
Del
Remove
FileProp
------------------------
SelAll
InvSel
------------------------
Sort -> Asc
        Desc
        ----------------
        ByName
        ByMTime
        BySize
        ByType
        ----------------
        MingleDirs
        SortIgnoreCase
        <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.

Functions

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.

If callback is called on folder context menu then files is NULL.

Parameters

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 or after next call to fm_folder_view_add_popup() on the same fv .

Since plugins may change popup menu appearance in accordance with the folder, implementaions are encouraged to use this API each time the model is changed on the fv .

Parameters

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 (or text from editable) into clipboard

  • Copy : copy files (or text from editable) into clipboard

  • Paste : paste files (or text from editable) from clipboard

  • Del : move files into trash bin (or delete text from editable)

  • Remove : delete files from filesystem (for editable does Cut)

  • SelAll : select all

  • InvSel : invert selection

  • Rename : rename the folder

  • Prop : folder properties dialog

  • FileProp : file properties dialog

  • NewFolder : create new folder here

  • NewBlank : create an empty file here

Actions 'Cut', 'Copy', 'Paste', 'Del', 'Remove', 'SelAll' do nothing if current keyboard focus is neither on fv nor on some GtkEditable.

See also: fm_folder_view_add_popup().

Parameters

act

an action to execute

 

fv

a widget to apply

 

Since: 1.0.1


fm_folder_view_columns_changed ()

void
fm_folder_view_columns_changed (FmFolderView *fv);

Emits the “columns-changed” signal.

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

Parameters

fv

the folder view widget to apply

 

Since: 1.2.0


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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

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.

Parameters

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.

Parameters

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.

Parameters

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 .

Parameters

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

Parameters

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

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

Parameters

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

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 .

Parameters

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. Otherwise the user_data for it will be GtkWindow the menu is attached to.

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

Parameters

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

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.

Parameters

mode

initial mode of view

 

Returns

a new FmFolderView widget.

Since: 0.1.0


fm_folder_view_scroll_to_path ()

void
fm_folder_view_scroll_to_path (FmFolderView *fv,
                               FmPath *path,
                               gboolean focus);

Scrolls the view to get item defined by path closely to center of the view window. If focus is TRUE then also keyboard focus will be set to the path .

Parameters

fv

the folder view widget to query

 

path

the item to scroll

 

focus

TRUE to set cursor focus on item

 

Since: 1.2.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.

Parameters

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.

Parameters

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

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.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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

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.

Parameters

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 .

Parameters

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 .

Parameters

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

Parameters

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

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.

Parameters

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.

Parameters

fv

a widget to apply

 

Since: 1.0.1

Types and Values

FM_MODULE_gtk_menu_scheme_VERSION

#define FM_MODULE_gtk_menu_scheme_VERSION 1

struct FmContextMenuSchemeAddonInit

struct FmContextMenuSchemeAddonInit {
    void (*init)(void);
    void (*finalize)(void);
    /* mask: scheme for all files ("*" allowed) */
    FmFileMenuUpdatePopup update_file_menu_for_scheme;
    /* mask: scheme for folder ("*" allowed) */
    FmFolderViewUpdatePopup update_folder_menu;
};

The init and finalize callbacks are called on application start and exit.

The update_file_menu_for_scheme callback will be called each time context menu is created for files that are on the same file system equal to the scheme defined as plugin name is created.

The update_folder_menu callback will be called each time application runs fm_folder_view_add_popup() on folder of the same scheme.

This structure is used for "gtk_menu_scheme" module initialization. The key for module of this type is scheme name to support. It may be "*" if module should be called on any file. No wildcards is allowed otherwise.

Members

init ()

callback for plugin initialization.

[allow-none]

finalize ()

callback to free resources allocated by init .

[allow-none]

FmFileMenuUpdatePopup update_file_menu_for_scheme;

callback to update selection context menu.

[allow-none]

FmFolderViewUpdatePopup update_folder_menu;

callback to update folder context menu.

[allow-none]

Since: 1.2.0


FmFolderView

typedef struct _FmFolderView FmFolderView;

enum FmFolderViewClickType

Click type for “clicked” signal handlers.

Members

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;
    gint width;
};

FmFolderView column setup data.

Members

FmFolderModelCol col_id;

column type

 

gint width;

width of column; 0 for auto, >0 for fixed width, <0 to use default

 

struct FmFolderViewInterface

struct FmFolderViewInterface {
    /* signals */
    void (*clicked)(FmFolderView* fv, FmFolderViewClickType type, FmFileInfo* file);
    void (*sel_changed)(FmFolderView* fv, gint n_sels);
    void (*sort_changed)(FmFolderView* fv);
    void (*filter_changed)(FmFolderView* fv);
    void (*columns_changed)(FmFolderView* fv);

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

    gboolean (*set_columns)(FmFolderView* fv, const GSList* cols);
    GSList* (*get_columns)(FmFolderView* fv);

    /* for implementation internal usage */
    void (*get_custom_menu_callbacks)(FmFolderView* fv, FmFolderViewUpdatePopup*,
                                      FmLaunchFolderFunc*);

    void (*scroll_to_path)(FmFolderView* fv, FmPath *path, gboolean focus);
};

Members

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

 

filter_changed ()

(since 1.2.0) the class closure for “filter-changed” signal

 

columns_changed ()

(since 1.2.0) the class closure for “columns-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 ()

unused since 1.2.0

 

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

 

set_columns ()

.

[since 1.2.0) VTable func, see fm_folder_view_set_columns(]

get_columns ()

.

[since 1.2.0) VTable func, see fm_folder_view_get_columns(]

get_custom_menu_callbacks ()

function to retrieve callbacks for popup menu setup

 

scroll_to_path ()

.

[since 1.2.0) VTable func, see fm_folder_view_scroll_to_path(]

fm_module_init_gtk_menu_scheme

extern FmContextMenuSchemeAddonInit fm_module_init_gtk_menu_scheme;

Signal Details

The “clicked” signal

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

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

Parameters

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.

 

Flags: Run First

Since: 0.1.0


The “columns-changed” signal

void
user_function (FmFolderView *view,
               gpointer      user_data)

The “columns-changed” signal is emitted when layout of FmFolderView instance is changed, i.e. some column is added, deleted, or changed its size.

Parameters

view

the widget that emitted the signal

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First

Since: 1.2.0


The “filter-changed” signal

void
user_function (FmFolderView *view,
               gpointer      user_data)

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

Parameters

view

the widget that emitted the signal

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First

Since: 1.0.2


The “sel-changed” signal

void
user_function (FmFolderView *view,
               int           n_sel,
               gpointer      user_data)

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

Before 1.0.0 parameter was list of currently selected files.

Parameters

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.

 

Flags: Run First

Since: 0.1.0


The “sort-changed” signal

void
user_function (FmFolderView *view,
               gpointer      user_data)

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

Parameters

view

the widget that emitted the signal

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First

Since: 0.1.10