Libfm-gtk utils

## Libfm-gtk utils Libfm-gtk utils — Different widgets and utilities that use GTK+ |

## Synopsis

    int                 fm_ask                              (GtkWindow *parent,
                                                             const char *title,
                                                             const char *question,
                                                             ...);
    int                 fm_ask_valist                       (GtkWindow *parent,
                                                             const char *title,
                                                             const char *question,
                                                             va_list options);
    int                 fm_askv                             (GtkWindow *parent,
                                                             const char *title,
                                                             const char *question,
                                                             char * const*options);
    #define             fm_copy_file                        (parent,
                                                             file,
                                                             dest_dir)
    void                fm_copy_files                       (GtkWindow *parent,
                                                             FmPathList *files,
                                                             FmPath *dest_dir);
    #define             fm_copy_files_to                    (parent,
                                                             files)
    void                fm_delete_files                     (GtkWindow *parent,
                                                             FmPathList *files);
    gboolean            fm_eject_mount                      (GtkWindow *parent,
                                                             GMount *mount,
                                                             gboolean interactive);
    gboolean            fm_eject_volume                     (GtkWindow *parent,
                                                             GVolume *vol,
                                                             gboolean interactive);
    void                fm_empty_trash                      (GtkWindow *parent);
    char *              fm_get_user_input                   (GtkWindow *parent,
                                                             const char *title,
                                                             const char *msg,
                                                             const char *default_text);
    gchar *             fm_get_user_input_n                 (GtkWindow *parent,
                                                             const char *title,
                                                             const char *msg,
                                                             const char *default_text,
                                                             gint n,
                                                             GtkWidget *extra);
    FmPath *            fm_get_user_input_path              (GtkWindow *parent,
                                                             const char *title,
                                                             const char *msg,
                                                             FmPath *default_path);
    void                fm_hide_file                        (GtkWindow *parent,
                                                             FmPath *file);
    void                fm_link_files                       (GtkWindow *parent,
                                                             FmPathList *files,
                                                             FmPath *dest_dir);
    gboolean            fm_mount_path                       (GtkWindow *parent,
                                                             FmPath *path,
                                                             gboolean interactive);
    gboolean            fm_mount_volume                     (GtkWindow *parent,
                                                             GVolume *vol,
                                                             gboolean interactive);
    #define             fm_move_file                        (parent,
                                                             file,
                                                             dest_dir)
    void                fm_move_files                       (GtkWindow *parent,
                                                             FmPathList *files,
                                                             FmPath *dest_dir);
    #define             fm_move_files_to                    (parent,
                                                             files)
    void                fm_move_or_copy_files_to            (GtkWindow *parent,
                                                             FmPathList *files,
                                                             gboolean is_move);
    gboolean            fm_ok_cancel                        (GtkWindow *parent,
                                                             const char *title,
                                                             const char *question,
                                                             gboolean default_ok);
    void                fm_rename_file                      (GtkWindow *parent,
                                                             FmPath *file);
    FmPath *            fm_select_file                      (GtkWindow *parent,
                                                             const char *title,
                                                             const char *default_folder,
                                                             gboolean local_only,
                                                             gboolean show_preview,
                                                             ...);
    FmPath *            fm_select_folder                    (GtkWindow *parent,
                                                             const char *title);
    void                fm_set_busy_cursor                  (GtkWidget *widget);
    void                fm_show_error                       (GtkWindow *parent,
                                                             const char *title,
                                                             const char *msg);
    void                fm_trash_files                      (GtkWindow *parent,
                                                             FmPathList *files);
    void                fm_trash_or_delete_files            (GtkWindow *parent,
                                                             FmPathList *files);
    void                fm_unhide_file                      (GtkWindow *parent,
                                                             FmPath *file);
    gboolean            fm_unmount_mount                    (GtkWindow *parent,
                                                             GMount *mount,
                                                             gboolean interactive);
    gboolean            fm_unmount_volume                   (GtkWindow *parent,
                                                             GVolume *vol,
                                                             gboolean interactive);
    void                fm_unset_busy_cursor                (GtkWidget *widget);
    void                fm_untrash_files                    (GtkWindow *parent,
                                                             FmPathList *files);
    void                fm_widget_menu_fix_tooltips         (GtkMenu *menu);
    gboolean            fm_yes_no                           (GtkWindow *parent,
                                                             const char *title,
                                                             const char *question,
                                                             gboolean default_yes);

## Description

`include`: libfm/fm-gtk.h

## Details

### fm_ask ()

    int                 fm_ask                              (GtkWindow *parent,
                                                             const char *title,
                                                             const char *question,
                                                             ...);

Ask the user a question with several options provided.

Before 0.1.16 this call had different arguments.

`parent` : | toplevel parent widget
`title` : | title for the window with question
`question` : | the question to show to the user
`...` : | a NULL terminated list of button labels
Returns : | the index of selected button, or -1 if the dialog is closed.

Since 0.1.0

### fm_ask_valist ()

    int                 fm_ask_valist                       (GtkWindow *parent,
                                                             const char *title,
                                                             const char *question,
                                                             va_list options);

Ask the user a question with several options provided.

Before 0.1.16 this call had different arguments.

`parent` : | toplevel parent widget
`title` : | title for the window with question
`question` : | the question to show to the user
`options` : | va_arg list of button labels
Returns : | the index of selected button, or -1 if the dialog is closed.

Since 0.1.0

### fm_askv ()

    int                 fm_askv                             (GtkWindow *parent,
                                                             const char *title,
                                                             const char *question,
                                                             char * const*options);

Ask the user a question with several options provided.

Before 0.1.16 this call had different arguments.

`parent` : | toplevel parent widget
`title` : | title for the window with question
`question` : | the question to show to the user
`options` : | a NULL terminated list of button labels
Returns : | the index of selected button, or -1 if the dialog is closed.

Since 0.1.0

### fm_copy_file()

    #define             fm_copy_file(parent, file, dest_dir)

### fm_copy_files ()

    void                fm_copy_files                       (GtkWindow *parent,
                                                             FmPathList *files,
                                                             FmPath *dest_dir);

Copies files opening progress dialog if that operation takes some time.

Before 0.1.15 this call had different arguments.

`parent` : | a window to place progress dialog over it
`files` : | list of files to copy
`dest_dir` : | target directory

Since 0.1.0

### fm_copy_files_to()

    #define fm_copy_files_to(parent, files)   fm_move_or_copy_files_to(parent, files, FALSE)

### fm_delete_files ()

    void                fm_delete_files                     (GtkWindow *parent,
                                                             FmPathList *files);

Wipes out files opening progress dialog if that operation takes some time.

Before 0.1.15 this call had different arguments.

`parent` : | a window to place progress dialog over it
`files` : | list of files to delete

Since 0.1.0

### fm_eject_mount ()

    gboolean            fm_eject_mount                      (GtkWindow *parent,
                                                             GMount *mount,
                                                             gboolean interactive);

Ejects the media in `mount`.

`parent` : | a window to place dialog over it
`mount` : | the mounted media
`interactive` : | `TRUE` to open dialog window
Returns : | `TRUE` in case of success.

Since 0.1.0

### fm_eject_volume ()

    gboolean            fm_eject_volume                     (GtkWindow *parent,
                                                             GVolume *vol,
                                                             gboolean interactive);

Ejects the media in `vol`.

`parent` : | a window to place dialog over it
`vol` : | the mounted media
`interactive` : | `TRUE` to open dialog window
Returns : | `TRUE` in case of success.

Since 0.1.0

### fm_empty_trash ()

    void                fm_empty_trash                      (GtkWindow *parent);

Asks user to confirm the emptying trash can and empties it if confirmed.

Before 0.1.15 this call had different arguments.

`parent` : | a window to place dialog over it

Since 0.1.0

### fm_get_user_input ()

    char *              fm_get_user_input                   (GtkWindow *parent,
                                                             const char *title,
                                                             const char *msg,
                                                             const char *default_text);

Presents the message to user and retrieves entered text. Returned data should be freed with `g_free()` after usage.

`parent` : | a window to place dialog over it
`title` : | title for dialog window
`msg` : | the message to present to the user
`default_text` : | the default answer
Returns : | entered text. [transfer full]

Since 0.1.0

### fm_get_user_input_n ()

    gchar *             fm_get_user_input_n                 (GtkWindow *parent,
                                                             const char *title,
                                                             const char *msg,
                                                             const char *default_text,
                                                             gint n,
                                                             GtkWidget *extra);

Presents the message to user and retrieves entered text. In presented dialog the part of `default_text` with length `n` will be preselected for edition (n < 0 means select all). Returned data should be freed with `g_free()` after usage.

`parent` : | a window to place dialog over it
`title` : | title for dialog window
`msg` : | the message to present to the user
`default_text` : | the default answer
`n` : | which part of default answer should be selected
`extra` : | additional widgets to display (can be focusable)
Returns : | entered text. [transfer full]

Since 1.2.0

### fm_get_user_input_path ()

    FmPath *            fm_get_user_input_path              (GtkWindow *parent,
                                                             const char *title,
                                                             const char *msg,
                                                             FmPath *default_path);

### Warning

`fm_get_user_input_path` has been deprecated since version 1.2.0 and should not be used in newly-written code.

Presents the message to user and retrieves entered path string. Returned data should be freed with `fm_path_unref()` after usage.

`parent` : | a window to place dialog over it
`title` : | title for dialog window
`msg` : | the message to present to the user
`default_path` : | the default path
Returns : | entered text. [transfer full]

Since 0.1.0

### fm_hide_file ()

    void                fm_hide_file                        (GtkWindow *parent,
                                                             FmPath *file);

Sets file attribute "hidden" for `file`.

`parent` : | a window to place progress dialog over it
`file` : | the file

Since 1.2.0

### fm_link_files ()

    void                fm_link_files                       (GtkWindow *parent,
                                                             FmPathList *files,
                                                             FmPath *dest_dir);

Create symbolic links for some files in the target directory with progress dialog.

`parent` : | window to base progress dialog over it
`files` : | list of files to make symbolic links to
`dest_dir` : | directory where symbolic links should be created

Since 1.0.0

### fm_mount_path ()

    gboolean            fm_mount_path                       (GtkWindow *parent,
                                                             FmPath *path,
                                                             gboolean interactive);

Mounts a volume.

`parent` : | a window to place dialog over it
`path` : | a path to the volume
`interactive` : | `TRUE` to open dialog window
Returns : | `TRUE` in case of success.

Since 0.1.0

### fm_mount_volume ()

    gboolean            fm_mount_volume                     (GtkWindow *parent,
                                                             GVolume *vol,
                                                             gboolean interactive);

Mounts a volume.

`parent` : | a window to place dialog over it
`vol` : | a volume to mount
`interactive` : | `TRUE` to open dialog window
Returns : | `TRUE` in case of success.

Since 0.1.0

### fm_move_file()

    #define             fm_move_file(parent, file, dest_dir)

### fm_move_files ()

    void                fm_move_files                       (GtkWindow *parent,
                                                             FmPathList *files,
                                                             FmPath *dest_dir);

Moves files opening progress dialog if that operation takes some time.

Before 0.1.15 this call had different arguments.

`parent` : | a window to place progress dialog over it
`files` : | list of files to move
`dest_dir` : | directory where to move files to

Since 0.1.0

### fm_move_files_to()

    #define fm_move_files_to(parent, files)   fm_move_or_copy_files_to(parent, files, TRUE)

### fm_move_or_copy_files_to ()

    void                fm_move_or_copy_files_to            (GtkWindow *parent,
                                                             FmPathList *files,
                                                             gboolean is_move);

Opens a dialog to choose destination directory. If it was not cancelled by user then moves or copies `files` into chosen directory with progress dialog.

Before 0.1.15 this call had different arguments.

`parent` : | a window to place progress dialog over it
`files` : | list of files
`is_move` : | `TRUE` to move, `FALSE` to copy

Since 0.1.0

### fm_ok_cancel ()

    gboolean            fm_ok_cancel                        (GtkWindow *parent,
                                                             const char *title,
                                                             const char *question,
                                                             gboolean default_ok);

Presents the question to user and gives user choices 'OK' and 'Cancel'.

Before 0.1.16 this call had different arguments.

`parent` : | a window to place dialog over it
`title` : | title for dialog window
`question` : | the question to show to the user
`default_ok` : | the default answer
Returns : | `TRUE` if user chose 'OK'.

Since 0.1.0

### fm_rename_file ()

    void                fm_rename_file                      (GtkWindow *parent,
                                                             FmPath *file);

Opens a dialog to choose new name for `file`. If it was not cancelled by user then renames `file`.

Before 0.1.15 this call had different arguments.

`parent` : | a window to place dialog over it
`file` : | the file

Since 0.1.0

### fm_select_file ()

    FmPath *            fm_select_file                      (GtkWindow *parent,
                                                             const char *title,
                                                             const char *default_folder,
                                                             gboolean local_only,
                                                             gboolean show_preview,
                                                             ...);

Presents the message to user and lets him/her to select a file. Returned data should be freed with `fm_path_unref()` after usage.

`parent` : | a window to place dialog over it
`title` : | title for dialog window
`default_folder` : | the starting folder path
`local_only` : | `TRUE` if select only local paths
`show_preview` : | `TRUE` to show file preview
`...` : | optional filters. [element-type GtkFileFilter]
Returns : | selected file path or `NULL` if dialog was closed. [transfer full]

Since 1.0.0

### fm_select_folder ()

    FmPath *            fm_select_folder                    (GtkWindow *parent,
                                                             const char *title);

Presents the message to user and lets him/her to select a folder. Returned data should be freed with `fm_path_unref()` after usage.

Before 0.1.16 this call had different arguments.

`parent` : | a window to place dialog over it
`title` : | title for dialog window
Returns : | selected folder path or `NULL` if dialog was closed. [transfer full]

Since 0.1.0

### fm_set_busy_cursor ()

    void                fm_set_busy_cursor                  (GtkWidget *widget);

Sets cursor for `widget` to "busy".

See also: `fm_unset_busy_cursor()`.

`widget` : | a widget

Since 1.0.0

### fm_show_error ()

    void                fm_show_error                       (GtkWindow *parent,
                                                             const char *title,
                                                             const char *msg);

Presents error message to user and gives user no choices but close.

Before 0.1.16 this call had different arguments.

`parent` : | a window to place dialog over it
`title` : | title for dialog window
`msg` : | message to present

Since 0.1.0

### fm_trash_files ()

    void                fm_trash_files                      (GtkWindow *parent,
                                                             FmPathList *files);

Removes files into trash can opening progress dialog if that operation takes some time.

Before 0.1.15 this call had different arguments.

`parent` : | a window to place progress dialog over it
`files` : | list of files to move to trash

Since 0.1.0

### fm_trash_or_delete_files ()

    void                fm_trash_or_delete_files            (GtkWindow *parent,
                                                             FmPathList *files);

Removes files into trash can if that operation is supported. Otherwise erases them. If that operation takes some time then progress dialog will be opened.

Before 0.1.15 this call had different arguments.

`parent` : | a window to place progress dialog over it
`files` : | list of files to delete

Since 0.1.0

### fm_unhide_file ()

    void                fm_unhide_file                      (GtkWindow *parent,
                                                             FmPath *file);

Unsets file attribute "hidden" for `file`.

`parent` : | a window to place progress dialog over it
`file` : | the file

Since 1.2.0

### fm_unmount_mount ()

    gboolean            fm_unmount_mount                    (GtkWindow *parent,
                                                             GMount *mount,
                                                             gboolean interactive);

Unmounts a volume.

`parent` : | a window to place dialog over it
`mount` : | the mounted volume
`interactive` : | `TRUE` to open dialog window
Returns : | `TRUE` in case of success.

Since 0.1.0

### fm_unmount_volume ()

    gboolean            fm_unmount_volume                   (GtkWindow *parent,
                                                             GVolume *vol,
                                                             gboolean interactive);

Unmounts a volume.

`parent` : | a window to place dialog over it
`vol` : | the mounted volume
`interactive` : | `TRUE` to open dialog window
Returns : | `TRUE` in case of success.

Since 0.1.0

### fm_unset_busy_cursor ()

    void                fm_unset_busy_cursor                (GtkWidget *widget);

Restores cursor for `widget` to default.

See also: `fm_set_busy_cursor()`.

`widget` : | a widget

Since 1.0.0

### fm_untrash_files ()

    void                fm_untrash_files                    (GtkWindow *parent,
                                                             FmPathList *files);

Restores files from trash can into original place opening progress dialog if that operation takes some time.

Before 0.1.15 this call had different arguments.

`parent` : | a window to place progress dialog over it
`files` : | list of files to restore

Since 0.1.11

### fm_widget_menu_fix_tooltips ()

    void                fm_widget_menu_fix_tooltips         (GtkMenu *menu);

Fix on GTK bug: it does not assign tooltips of menu items from appropriate GtkAction objects. This API assigns them instead.

`menu` : | a GtkMenu instance

Since 1.2.0

### fm_yes_no ()

    gboolean            fm_yes_no                           (GtkWindow *parent,
                                                             const char *title,
                                                             const char *question,
                                                             gboolean default_yes);

Presents the question to user and gives user choices 'Yes' and 'No'.

Before 0.1.16 this call had different arguments.

`parent` : | a window to place dialog over it
`title` : | title for dialog window
`question` : | the question to present to the user
`default_yes` : | the default answer
Returns : | `TRUE` if user chose 'Yes'.

Since 0.1.0