краткое описание

#include <gtk/gtk.h>


            gtkfilechooser;
enum        gtkfilechooseraction;
enum        gtkfilechooserconfirmation;
#define     gtk_file_chooser_error

enum        gtkfilechoosererror;
void        gtk_file_chooser_set_action     (gtkfilechooser *chooser,
                                             gtkfilechooseraction action);
gtkfilechooseraction gtk_file_chooser_get_action
                                            (gtkfilechooser *chooser);
void        gtk_file_chooser_set_local_only (gtkfilechooser *chooser,
                                             gboolean local_only);

gboolean    gtk_file_chooser_get_local_only (gtkfilechooser *chooser);
void        gtk_file_chooser_set_select_multiple
                                            (gtkfilechooser *chooser,
                                             gboolean select_multiple);

gboolean    gtk_file_chooser_get_select_multiple
                                            (gtkfilechooser *chooser);
void        gtk_file_chooser_set_show_hidden
                                            (gtkfilechooser *chooser,
                                             gboolean show_hidden);

gboolean    gtk_file_chooser_get_show_hidden
                                            (gtkfilechooser *chooser);
void        gtk_file_chooser_set_do_overwrite_confirmation
                                            (gtkfilechooser *chooser,
                                             gboolean do_overwrite_confirmation);

gboolean    gtk_file_chooser_get_do_overwrite_confirmation
                                            (gtkfilechooser *chooser);
void        gtk_file_chooser_set_current_name
                                            (gtkfilechooser *chooser,
                                             const gchar *name);

gchar*      gtk_file_chooser_get_filename   (gtkfilechooser *chooser);
gboolean    gtk_file_chooser_set_filename   (gtkfilechooser *chooser,
                                             const char *filename);
gboolean    gtk_file_chooser_select_filename

                                            (gtkfilechooser *chooser,
                                             const char *filename);
void        gtk_file_chooser_unselect_filename
                                            (gtkfilechooser *chooser,
                                             const char *filename);
void        gtk_file_chooser_select_all     (gtkfilechooser *chooser);
void        gtk_file_chooser_unselect_all   (gtkfilechooser *chooser);

gslist*     gtk_file_chooser_get_filenames  (gtkfilechooser *chooser);
gboolean    gtk_file_chooser_set_current_folder
                                            (gtkfilechooser *chooser,
                                             const gchar *filename);

gchar*      gtk_file_chooser_get_current_folder
                                            (gtkfilechooser *chooser);
gchar*      gtk_file_chooser_get_uri        (gtkfilechooser *chooser);

gboolean    gtk_file_chooser_set_uri        (gtkfilechooser *chooser,
                                             const char *uri);
gboolean    gtk_file_chooser_select_uri     (gtkfilechooser *chooser,
                                             const char *uri);
void        gtk_file_chooser_unselect_uri   (gtkfilechooser *chooser,
                                             const char *uri);

gslist*     gtk_file_chooser_get_uris       (gtkfilechooser *chooser);
gboolean    gtk_file_chooser_set_current_folder_uri
                                            (gtkfilechooser *chooser,
                                             const gchar *uri);

gchar*      gtk_file_chooser_get_current_folder_uri
                                            (gtkfilechooser *chooser);
void        gtk_file_chooser_set_preview_widget
                                            (gtkfilechooser *chooser,
                                             gtkwidget *preview_widget);

gtkwidget*  gtk_file_chooser_get_preview_widget
                                            (gtkfilechooser *chooser);
void        gtk_file_chooser_set_preview_widget_active
                                            (gtkfilechooser *chooser,
                                             gboolean active);

gboolean    gtk_file_chooser_get_preview_widget_active
                                            (gtkfilechooser *chooser);
void        gtk_file_chooser_set_use_preview_label
                                            (gtkfilechooser *chooser,
                                             gboolean use_label);

gboolean    gtk_file_chooser_get_use_preview_label
                                            (gtkfilechooser *chooser);
char*       gtk_file_chooser_get_preview_filename
                                            (gtkfilechooser *chooser);
char*       gtk_file_chooser_get_preview_uri

                                            (gtkfilechooser *chooser);
void        gtk_file_chooser_set_extra_widget
                                            (gtkfilechooser *chooser,
                                             gtkwidget *extra_widget);
gtkwidget*  gtk_file_chooser_get_extra_widget

                                            (gtkfilechooser *chooser);
void        gtk_file_chooser_add_filter     (gtkfilechooser *chooser,
                                             gtkfilefilter *filter);
void        gtk_file_chooser_remove_filter  (gtkfilechooser *chooser,
                                             gtkfilefilter *filter);

gslist*     gtk_file_chooser_list_filters   (gtkfilechooser *chooser);
void        gtk_file_chooser_set_filter     (gtkfilechooser *chooser,
                                             gtkfilefilter *filter);

gtkfilefilter* gtk_file_chooser_get_filter  (gtkfilechooser *chooser);
gboolean    gtk_file_chooser_add_shortcut_folder
                                            (gtkfilechooser *chooser,
                                             const char *folder,
                                             gerror **error);

gboolean    gtk_file_chooser_remove_shortcut_folder
                                            (gtkfilechooser *chooser,
                                             const char *folder,
                                             gerror **error);
gslist*     gtk_file_chooser_list_shortcut_folders
                                            (gtkfilechooser *chooser);

gboolean    gtk_file_chooser_add_shortcut_folder_uri
                                            (gtkfilechooser *chooser,
                                             const char *uri,
                                             gerror **error);
gboolean    gtk_file_chooser_remove_shortcut_folder_uri
                                            (gtkfilechooser *chooser,
                                             const char *uri,
                                             gerror **error);

gslist*     gtk_file_chooser_list_shortcut_folder_uris
                                            (gtkfilechooser *chooser);

иерархия объектов

  ginterface
   +----gtkfilechooser

предварительные требования

gtkfilechooser требует gtkwidget.

известные реализации

gtkfilechooser реализован в gtkfilechooserwidget, gtkfilechooserbutton и gtkfilechooserdialog.

свойства

  "action"               gtkfilechooseraction  : read / write
  "do-overwrite-confirmation" gboolean              : read / write
  "extra-widget"         gtkwidget             : read / write
  "file-system-backend"  gchararray            : write / construct only
  "filter"               gtkfilefilter         : read / write
  "local-only"           gboolean              : read / write
  "preview-widget"       gtkwidget             : read / write
  "preview-widget-active" gboolean              : read / write
  "select-multiple"      gboolean              : read / write
  "show-hidden"          gboolean              : read / write
  "use-preview-label"    gboolean              : read / write

сигналы

"confirm-overwrite"
            gtkfilechooserconfirmationuser_function      (gtkfilechooser *filechooser,
                                            gpointer        user_data)        : run last
"current-folder-changed"
            void        user_function      (gtkfilechooser *chooser,
                                            gpointer        user_data)      : run last
"file-activated"
            void        user_function      (gtkfilechooser *chooser,
                                            gpointer        user_data)      : run last
"selection-changed"
            void        user_function      (gtkfilechooser *chooser,
                                            gpointer        user_data)      : run last
"update-preview"
            void        user_function      (gtkfilechooser *chooser,
                                            gpointer        user_data)      : run last

описание

gtkfilechooser это интерфейс который реализуется виджетами выбора файлов. в gtk+, основными объектами реализующими этот интерфейс являются gtkfilechooserwidget, gtkfilechooserdialog, и gtkfilechooserbutton. вам не нужно создавать объект реализующий gtkfilechooser интерфейс, исключая случаи когда вы пробуете приспособить существующий селектор файлов для экспозиции стандартного программного интерфейса.

gtkfilechooser учитывает ярлыки для различных мест файловой системы. по умолчанию они отображаются в левой области окна. это может по началу немного запутать, ярлыки происходят из различных источников и с разными особенностями, поэтому здесь приводится объясняющая терминология:

имена файлов и кодировки

когда пользователь заканчивает выбор файла в gtkfilechooser, ваша программа может получить каждое выбранное имя как имя файла (filenames) или как uris. для uris, обычно применяются завершающие правила если uri содержит не-ascii символы. однако имена файлов всегда возвращаются в наборе символов определённом переменной окруженияя g_filename_encoding. пожалуйста посмотрите документацию по glib для получения большей информации об этой переменной.

важно

это значит что в то время как вы помещаете результат gtk_file_chooser_get_filename() в open(2) или fopen(3), вы не можете непосредственно установить его как текст виджета gtklabel, за исключением случаев когда вы сначала преобразуете его в utf-8, которую поддерживают все виджеты gtk+. вы должны использовать g_filename_to_utf8() для преобразования файловых имен в строку которую можно поместить в виджеты gtk+.

добавление виджета предварительного просмотра

вы можете добавить выборочный виджет просмотра в виджет выбора файла и затем получить уведомление о том когда предварительный просмотр должен обновляться. для установки виджета предварительного просмотра используйте gtk_file_chooser_set_preview_widget(). затем, подключите сигнал gtkfilechooser::update-preview для получения уведомления об обновлении содержимого предварительного просмотра.

ваш обратный вызов должен использовать gtk_file_chooser_get_preview_filename() чтобы видеть какой предварительный просмотр необходим. как только вы сгенерировали предварительный просмотр для соответствующего файла, вы должны вызвать gtk_file_chooser_set_preview_widget_active() с логическим флагом указывающим полностью ли сгенерирован предварительный просмотр.

пример 2. образец использования

{
  gtkimage *preview;

  ...

  preview = gtk_image_new ();

  gtk_file_chooser_set_preview_widget (my_file_chooser, preview);
  g_signal_connect (my_file_chooser, "update-preview",
                    g_callback (update_preview_cb), preview);
}

static void
update_preview_cb (gtkfilechooser *file_chooser, gpointer data)
{
  gtkwidget *preview;
  char *filename;
  gdkpixbuf *pixbuf;
  gboolean have_preview;

  preview = gtk_widget (data);
  filename = gtk_file_chooser_get_preview_filename (file_chooser);

  pixbuf = gdk_pixbuf_new_from_file_at_size (filename, 128, 128, null);
  have_preview = (pixbuf != null);
  g_free (filename);

  gtk_image_set_from_pixbuf (gtk_image (preview), pixbuf);
  if (pixbuf)
    gobject_unref (pixbuf);

  gtk_file_chooser_set_preview_widget_active (file_chooser, have_preview);
}
        

добавление дополнительных виджетов

вы можете добавить дополнительные виджеты в селектор файлов для обеспечения опций которые не представляет интерфейс по умолчанию. например, вы можете добавить кнопки переключатели для получения пользователем опции открытия файла только для чтения. вы можете использовать gtk_file_chooser_set_extra_widget() для вставки дополнительных виджетов в селектор файлов.

пример 3. образец использования

{
  gtkwidget *toggle;

  ...

  toggle = gtk_check_button_new_with_label ("open file read-only");
  gtk_widget_show (toggle);
  gtk_file_chooser_set_extra_widget (my_file_chooser, toggle);
}
        

помните

если вам нужно установить больше чем один виджет, вы можете использовать контейнер, такой как gtkvbox или gtktable для встраивания ваших виджетов. затем установить контейнер как целый дополнительный виджет.

привязки клавиш

внутренне, gtk+ реализует интерфейс выбора файла с закрытым gtkfilechooserdefaultclass. этот виджет имеет несколько привязок клавиш key bindings и связанные с ними сигналы. этот раздел описывает доступные сигналы привязок клавиш.

пример 4. gtkfilechooser пример клавишных привязок

по умолчанию клавиши активизирующие сигналы привязок клавиш в gtkfilechooserdefaultclass следующие:

вы можете изменить значения по умолчанию на собственные. например, для добавления модификатора shift к некоторым привязкам по умолчанию, вы можете включить следующий фрагмент в ваш .gtkrc-2.0 файл:

binding "my-own-gtkfilechooser-bindings" {
        bind "<alt><shift>up" {
                "up-folder" ()
        }
        bind "<alt><shift>down" {
                "down-folder" ()
        }
        bind "<alt><shift>home" {
                "home-folder" ()
        }
}

class "gtkfilechooserdefault" binding "my-own-gtkfilechooser-bindings"
        

сигнал "gtkfilechooserdefault::location-popup"

          void user_function (gtkfilechooserdefault *chooser,
                              const char            *path,
                              gpointer user_data);
        

используется для отображения селектором файла диалога "location", который используется для ручного ввода имени выбираемого файла. параметр path это строка которая вставляется в текстовый ввод для определения имени файла. по умолчанию диалог ввода файла появляется при нажатии control-l с пустой строкой "" в параметре path . а также при нажатии на / (слэш) появляется строка ввода имени файла с параметром path равным строке "/" (слэш): это позволяет вам вводить путь имени файла или каталога. в unix системах, параметр path равный строке "~/" приводит непосредственно в домашний каталог.

подсказка

вы можете создать свою собственную привязку для сигнала всплывающего размещения с выборочной строкой параметра path и иметь заготовочную форму для для лёгкого ввода закладок. например, вы часто обращаетесь к /home/username/misc. тогда вы можете создать горячую клавишу alt-m включив следующий код в ваш .gtkrc-2.0:

binding "misc-shortcut" {
        bind "<alt>m" {
                "location-popup" ("/home/username/misc")
        }
}

class "gtkfilechooserdefault" binding "misc-shortcut"
          

сигнал "gtkfilechooserdefault::up-folder"

          void user_function (gtkfilechooserdefault *chooser,
                              gpointer user_data);
        

этот сигнал заставляет селектор файлов обратиться к родительской папке текущемго каталога в иерархии файлов. по умолчанию это происходит при нажатии клавиши backspace и alt-up (клавиша up на цифровой клавиатуре также работает).

сигнал "gtkfilechooserdefault::down-folder"

          void user_function (gtkfilechooserdefault *chooser,
                              gpointer user_data);
        

этот сигнал заставляет селектор файлов обратиться к дочерней папке текущемго каталога в иерархии файлов. подкаталог который будет использован для отображения в пути панели виджета селектора файлов. например, если путь отображаемый в панели "/foo/bar/baz", то в этом случае селектор файлов переключится на подкаталог "baz". по умолчанию это управляется нажатием alt-down (клавиша down цифровой клавиатуры также поддерживается).

сигнал "gtkfilechooserdefault::home-folder"

          void user_function (gtkfilechooserdefault *chooser,
                              gpointer user_data);
        

этот сигнал заставляет селектор файлов показать домашний каталог пользователя в списке файлов. по умолчанию он управляется клавишами alt-home (клавиша home цифровой клавиатуры также поддерживается).

сигнал "gtkfilechooserdefault::desktop-folder"

          void user_function (gtkfilechooserdefault *chooser,
                              gpointer user_data);
        

этот сигнал заставляет показать каталог рабочего стола пользователя. по умолчанию управляется с помощью alt-d.

сигнал "gtkfilechooserdefault::quick-bookmark"

          void user_function (gtkfilechooserdefault *chooser,
                              gint bookmark_index,
                              gpointer user_data);
        

используется для создания переключателя селектора файлов в закладке определённой параметром bookmark_index. например, если вы имеете дерево закладок, вы можете поместить 0, 1, 2 в этот сигнал для переключения каждого элемента соответственно. по умолчанию привязан к alt-1, alt-2, и так далее до alt-0. помните что в привязке по умолчанию, alt-1 фактически определён для переключения закладки с индексом 0, и далее последовательно; alt-0 определён для переключения закладки с индексом 10.

детали

gtkfilechooser

typedef struct _gtkfilechooser gtkfilechooser;

enum gtkfilechooseraction

typedef enum
{
  gtk_file_chooser_action_open,
  gtk_file_chooser_action_save,
  gtk_file_chooser_action_select_folder,
  gtk_file_chooser_action_create_folder
} gtkfilechooseraction;

описывает используется ли gtkfilechooser для открытия существующих файлов или возможного сохранения нового файла.

enum gtkfilechooserconfirmation

typedef enum
{
  gtk_file_chooser_confirmation_confirm,
  gtk_file_chooser_confirmation_accept_filename,
  gtk_file_chooser_confirmation_select_again
} gtkfilechooserconfirmation;

используется как возвращаемое значение обработчиков для сигнала confirm-overwrite gtkfilechooser. это значение определяет представляет ли селектор файлов готовый диалог подтверждений, принимающий выбранное пользователем имя, или позволяет пользователю выбрать другое имя файла.

начиная с версии 2.8

gtk_file_chooser_error

#define gtk_file_chooser_error (gtk_file_chooser_error_quark ())

используется для получения gerror восклицание для ошибок gtkfilechooser.

enum gtkfilechoosererror

typedef enum {
  gtk_file_chooser_error_nonexistent,
  gtk_file_chooser_error_bad_filename,
  gtk_file_chooser_error_already_exists
} gtkfilechoosererror;

идентифицирует варианты ошибок которые могут произойти во время вызова функций gtkfilechooser.

gtk_file_chooser_set_action ()

void        gtk_file_chooser_set_action     (gtkfilechooser *chooser,
                                             gtkfilechooseraction action);

устанавливает тип операции выполняемой селектором; интерфейс пользователя адаптируется для действий выбора. например, опция для создания нового каталога может быть показана если действие равно gtk_file_chooser_action_save, а не gtk_file_chooser_action_open.

начиная с версии 2.4

gtk_file_chooser_get_action ()

gtkfilechooseraction gtk_file_chooser_get_action
                                            (gtkfilechooser *chooser);

в качестве результата получает тип действия выполняемого селектором файла; смотрите gtk_file_chooser_set_action().

начиная с версии 2.4

gtk_file_chooser_set_local_only ()

void        gtk_file_chooser_set_local_only (gtkfilechooser *chooser,
                                             gboolean local_only);

устанавливает только ли локальные файлы могут быть выбраны в селекторе файлов. если local_only это true (значение по умолчанию), то выбранные файлы гарантировано являются файлами доступными через родную файловую систему и поэтому приложение должно беспокоиться только о функциях имени файла в gtkfilechooser, таких как gtk_file_chooser_get_filename(), а не о функциях uri таких как gtk_file_chooser_get_uri(),

начиная с версии 2.4

gtk_file_chooser_get_local_only ()

gboolean    gtk_file_chooser_get_local_only (gtkfilechooser *chooser);

определяет только ли локальные файлы могут быть выбраны в селекторе файлов. смотрите gtk_file_chooser_set_local_only()

начиная с версии 2.4

gtk_file_chooser_set_select_multiple ()

void        gtk_file_chooser_set_select_multiple
                                            (gtkfilechooser *chooser,
                                             gboolean select_multiple);

устанавливает возможен ли множественный выбор фалов в селекторе файлов. уместно только если действие установлено в gtk_file_chooser_action_open или gtk_file_chooser_action_select_folder.

начиная с версии 2.4

gtk_file_chooser_get_select_multiple ()

gboolean    gtk_file_chooser_get_select_multiple
                                            (gtkfilechooser *chooser);

определяет возможен ли множественный выбор в селекторе файлов. смотрите gtk_file_chooser_set_select_multiple().

начиная с версии 2.4

gtk_file_chooser_set_show_hidden ()

void        gtk_file_chooser_set_show_hidden
                                            (gtkfilechooser *chooser,
                                             gboolean show_hidden);

устанавливает отображаются ли скрытые файлы и каталоги в селекторе файлов.

начиная с версии 2.6

gtk_file_chooser_get_show_hidden ()

gboolean    gtk_file_chooser_get_show_hidden
                                            (gtkfilechooser *chooser);

определяет отображаются ли скрытые файлы и каталоги в селекторе файлов. смотрите gtk_file_chooser_set_show_hidden().

начиная с версии 2.6

gtk_file_chooser_set_do_overwrite_confirmation ()

void        gtk_file_chooser_set_do_overwrite_confirmation
                                            (gtkfilechooser *chooser,
                                             gboolean do_overwrite_confirmation);

устанавливает находится ли селектор файлов в режиме gtk_file_chooser_action_save представляя диалог подтверждения если пользователь вводит имя файла который уже существует. значение по умолчанию false.

независимо от этой установки, chooser издаст сигнал "confirm-overwrite".

если диалог подтверждения необходим вам постоянно, установите это свойство в значение true. вы можете изменить способ выполнения подтверждения фактически обрабатывая сигнал "confirm-overwrite"; пожалуйста обратитесь к документации для детального изучения.

начиная с версии 2.8

gtk_file_chooser_get_do_overwrite_confirmation ()

gboolean    gtk_file_chooser_get_do_overwrite_confirmation
                                            (gtkfilechooser *chooser);

запрашивает установлено ли подтверждение при попытке пользователя ввести имя существующего файла.

начиная с версии 2.8

gtk_file_chooser_set_current_name ()

void        gtk_file_chooser_set_current_name
                                            (gtkfilechooser *chooser,
                                             const gchar *name);

устанавливает текущеме имя в селекторе файлов, как будто введённое пользователем. помните что помещаемое здесь имя – это строка utf-8 а не имя файла (filename). эта функция предназначена для использования в таких диалогах как "сохранить как...".

если вам нужно выбрать специальный существующий файл, вы должны использовать gtk_file_chooser_set_filename() или gtk_file_chooser_set_uri() вместо неё. пожалуйста посмотрите документацию по использованию этих функций, а также gtk_file_chooser_set_current_name().

начиная с версии 2.4

gtk_file_chooser_get_filename ()

gchar*      gtk_file_chooser_get_filename   (gtkfilechooser *chooser);

в качестве результата получает имя файла используемое в данный момент в селекторе файлов. если выбрано множество файлов, то возвращается имя одного из них наугад.

если селектор файлов в режиме каталога, эта функция вернёт имя каталога.

начиная с версии 2.4

gtk_file_chooser_set_filename ()

gboolean    gtk_file_chooser_set_filename   (gtkfilechooser *chooser,
                                             const char *filename);

устанавливает filename как текущеме имя файла для селектора файлов, изменяя родительскую папку файлов и фактически выбирая файл из списка. если chooser в режиме gtk_file_chooser_action_save, основное имя файла также появится в диалоге ввода имени файла.

если имя файла не находится в текущемм каталоге chooser, то текущий каталог селектора файлов chooser изменяется в каталог содержащий filename. это равноценно последовательности gtk_file_chooser_unselect_all() следующей за gtk_file_chooser_select_filename().

помните что файл должен существовать, или ничего не произойдёт за исключением смены каталога.

если вы реализуете диалог file/save as..., вы должны использовать эту функцию если вы уже имеете имя файла который пользователь может сохранить; например, когда пользователь открывает существующий файл а затем выполняет file/save as... для него. если нет уже существующего имени файла — например, если пользователь просто создал новый файл и сохраняет его в первый раз, не вызывайте эту функцию. вместо неё используйте что-то похожее на:

if (document_is_new)
  {
    /* пользователь просто создаёт новый документ */
    gtk_file_chooser_set_current_folder (chooser, default_folder_for_saving);
    gtk_file_chooser_set_current_name (chooser, "untitled document");
  }
else
  {
    /* пользователь редактирует существующий документ */ 
    gtk_file_chooser_set_filename (chooser, existing_filename);
  }

начиная с версии 2.4

gtk_file_chooser_select_filename ()

gboolean    gtk_file_chooser_select_filename
                                            (gtkfilechooser *chooser,
                                             const char *filename);

выбирает имя файла. если имя файла не находится в текущемй папке селектора файлов chooser, то текущий каталог chooser будет изменён на каталог содержащий файл filename.

начиная с версии 2.4

gtk_file_chooser_unselect_filename ()

void        gtk_file_chooser_unselect_filename
                                            (gtkfilechooser *chooser,
                                             const char *filename);

снимает текущеме выделение файла. если имени файла нет в текущемм каталоге или нет текущемго выделения файла, то ничего не происходит.

начиная с версии 2.4

gtk_file_chooser_select_all ()

void        gtk_file_chooser_select_all     (gtkfilechooser *chooser);

выбирает все файлы в текущемм каталоге селектора файлов.

начиная с версии 2.4

gtk_file_chooser_unselect_all ()

void        gtk_file_chooser_unselect_all   (gtkfilechooser *chooser);

снимает выделение всех файлов в текущемм каталоге селектора файлов.

начиная с версии 2.4

gtk_file_chooser_get_filenames ()

gslist*     gtk_file_chooser_get_filenames  (gtkfilechooser *chooser);

в качестве результата получает списки всех выделенных файлов и подкаталогов в текущемм каталоге селектора файлов chooser. возвращаемые имена являются абсолютными путями. если файлы в текущемм каталоге не могут быть представлены с локальными именами, то они будут проигнорированы. (смотрите gtk_file_chooser_get_uris())

начиная с версии 2.4

gtk_file_chooser_set_current_folder ()

gboolean    gtk_file_chooser_set_current_folder
                                            (gtkfilechooser *chooser,
                                             const gchar *filename);

устанавливает текущий каталог селектора файлов chooser из локального имени. пользователю будет показано полное содержимое текущемго каталога, плюс элементы пользовательского интерфейса для навигации по другим каталогам.

начиная с версии 2.4

gtk_file_chooser_get_current_folder ()

gchar*      gtk_file_chooser_get_current_folder
                                            (gtkfilechooser *chooser);

получает текущий каталог селектора файлов chooser как локальное имя. смотрите gtk_file_chooser_set_current_folder().

помните, это текущий отображаемый каталог селектора файлов (например "/home/username/documents"), это не тоже самое как текущий выбранный каталог если селектор файлов находится в режиме gtk_file_chooser_select_folder (например "/home/username/documents/selected-folder/"). для получения текущемго выбранного каталога в этом режиме, используйте gtk_file_chooser_get_uri() как удобный способ получения выбора.

начиная с версии 2.4

gtk_file_chooser_get_uri ()

gchar*      gtk_file_chooser_get_uri        (gtkfilechooser *chooser);

получает в качестве результата uri текущемго выбранного файла в селекторе файлов. если выбрано множество файлов, возвращается произвольно выбранное имя одного из них.

если селектор файлов в режиме каталога, эта функция возвращает выбранный каталог.

начиная с версии 2.4

gtk_file_chooser_set_uri ()

gboolean    gtk_file_chooser_set_uri        (gtkfilechooser *chooser,
                                             const char *uri);

устанавливает файл на который ссылается uri как текущий файл селектора файлов, изменяет uri's родительского каталога и фактически выделяет uri в списке. если chooser в режиме gtk_file_chooser_action_save, основное имя uri's также появится в воде имени файлового диалога.

если uri не текущий каталог селектора файлов chooser, то текущий каталог chooser будет сменён на каталог содержащий uri. это равносильно последовательности gtk_file_chooser_unselect_all() затем gtk_file_chooser_select_uri().

помните что uri уже должен существовать, или ничего не произойдёт кроме смены каталога. если вы реализуете диалог file/save as..., вы должны использовать эту функцию если вы уже имеете имя файла который пользователь может сохранить; например, когда пользователь открывает существующий файл а затем выполняет file/save as... для него. если нет уже существующего имени файла — например, если пользователь просто создал новый файл и сохраняет его в первый раз, не вызывайте эту функцию. вместо неё используйте что-то похожее на:

if (document_is_new)
  {
    /* пользователь просто создаёт новый документ */
    gtk_file_chooser_set_current_folder_uri (chooser, default_folder_for_saving);
    gtk_file_chooser_set_current_name (chooser, "untitled document");
  }
else
  {
    /* пользователь редактирует существующий документ */ 
    gtk_file_chooser_set_uri (chooser, existing_uri);
  }

начиная с версии 2.4

gtk_file_chooser_select_uri ()

gboolean    gtk_file_chooser_select_uri     (gtkfilechooser *chooser,
                                             const char *uri);

выбирает файл соответствующий uri. если uri не ссылается на файл в текущемм каталоге chooser, то текущий каталог селектора файлов chooser изменяется на каталог содержащий filename.

начиная с версии 2.4

gtk_file_chooser_unselect_uri ()

void        gtk_file_chooser_unselect_uri   (gtkfilechooser *chooser,
                                             const char *uri);

снимает выделение файла на который ссылается uri. если файл не существует или нет текущемго выделения, то ничего не происходит.

начиная с версии 2.4

gtk_file_chooser_get_uris ()

gslist*     gtk_file_chooser_get_uris       (gtkfilechooser *chooser);

список всех выделенных файлов и подкаталогов в текущемм каталоге селектора файлов chooser. возвращаются абсолютные имена uris.

начиная с версии 2.4

gtk_file_chooser_set_current_folder_uri ()

gboolean    gtk_file_chooser_set_current_folder_uri
                                            (gtkfilechooser *chooser,
                                             const gchar *uri);

устанавливает текущий каталог chooser из uri. пользователю показывается всё содержимое каталога, плюс элементы пользовательского интерфейса для перемещения к другим каталогам.

начиная с версии 2.4

gtk_file_chooser_get_current_folder_uri ()

gchar*      gtk_file_chooser_get_current_folder_uri
                                            (gtkfilechooser *chooser);

в качестве результата получает текущий каталог селектора файлов chooser как uri. смотрите gtk_file_chooser_set_current_folder_uri().

помните что это каталог который селектор файлов отображает в текущий момент (например "file:///home/username/documents"), это не то же самое что текущий выбранные каталог если селектор в режиме gtk_file_chooser_select_folder (например "file:///home/username/documents/selected-folder/"). для получения текущемго выбранного каталога в этом режиме, используйте gtk_file_chooser_get_uri() как удобный способ получения выбора.

начиная с версии 2.4

gtk_file_chooser_set_preview_widget ()

void        gtk_file_chooser_set_preview_widget
                                            (gtkfilechooser *chooser,
                                             gtkwidget *preview_widget);

устанавливает поставляемый приложением виджет используемый для отображения предварительного просмотра выбранного файла. для реализации предварительного просмотра, после установки виджета предварительного просмотра, подключается сигнал ::update-preview и вызывается gtk_file_chooser_get_preview_filename() или gtk_file_chooser_get_preview_uri() для каждого изменения. если вы можете отобразить предварительный просмотр нового файла, обновите ваш виджет и установите предварительный просмотр в активное использование gtk_file_chooser_set_preview_widget_active(). иначе установите предварительный просмотр в неактивное состояние.

когда нет поставляемого приложением виджета предварительного просмотра, или поставляемый приложением виджет в неактивном состоянии, селектор файлов может отображать внутренне сгенерированный предварительный просмотр текущемго файла или может не отобразить никакого предварительного просмотра вообще.

начиная с версии 2.4

gtk_file_chooser_get_preview_widget ()

gtkwidget*  gtk_file_chooser_get_preview_widget
                                            (gtkfilechooser *chooser);

возвращает текущий виджет предварительного просмотра; смотрите gtk_file_chooser_set_preview_widget().

начиная с версии 2.4

gtk_file_chooser_set_preview_widget_active ()

void        gtk_file_chooser_set_preview_widget_active
                                            (gtkfilechooser *chooser,
                                             gboolean active);

устанавливает должен ли виджет предварительного просмотра установленный gtk_file_chooser_set_preview_widget() отображаться для текущемго имени файла. когда параметр active установлен в значение false, селектор файлов может отображать внутренне сгенерированный предварительный просмотр текущемго файла или вообще не показывать его. смотрите gtk_file_chooser_set_preview_widget() для детального изучения.

начиная с версии 2.4

gtk_file_chooser_get_preview_widget_active ()

gboolean    gtk_file_chooser_get_preview_widget_active
                                            (gtkfilechooser *chooser);

определяет должен ли отображаться виджет предварительного просмотра установленный с помощью gtk_file_chooser_set_preview_widget() для текущемго файла. смотрите gtk_file_chooser_set_preview_widget_active().

начиная с версии 2.4

gtk_file_chooser_set_use_preview_label ()

void        gtk_file_chooser_set_use_preview_label
                                            (gtkfilechooser *chooser,
                                             gboolean use_label);

устанавливает должен ли селектор файлов отображать заготовленный ярлык с именем предварительно просматриваемого файла; значение по умолчанию true. приложения которые рисуют всю область предварительного просмотра самостоятельно должны установить false и отобразить имя самостоятельно в их виджете предварительного просмотра.

смотрите также: gtk_file_chooser_set_preview_widget()

начиная с версии 2.4

gtk_file_chooser_get_use_preview_label ()

gboolean    gtk_file_chooser_get_use_preview_label
                                            (gtkfilechooser *chooser);

определяет отображается ли заготовленный ярлык с именем предварительно просматриваемого файла. смотрите gtk_file_chooser_set_use_preview_label().

gtk_file_chooser_get_preview_filename ()

char*       gtk_file_chooser_get_preview_filename
                                            (gtkfilechooser *chooser);

определяет имя файла который должен предварительно просматриваться в выбранном виджете предварительного просмотра. смотрите gtk_file_chooser_set_preview_widget().

начиная с версии 2.4

gtk_file_chooser_get_preview_uri ()

char*       gtk_file_chooser_get_preview_uri
                                            (gtkfilechooser *chooser);

определяет uri который должен предварительно просматриваться в выбранном виджете предварительного просмотра. смотрите gtk_file_chooser_set_preview_widget().

начиная с версии 2.4

gtk_file_chooser_set_extra_widget ()

void        gtk_file_chooser_set_extra_widget
                                            (gtkfilechooser *chooser,
                                             gtkwidget *extra_widget);

устанавливает поставляемый приложением виджет обеспечивающий пользователю дополнительные опции.

начиная с версии 2.4

gtk_file_chooser_get_extra_widget ()

gtkwidget*  gtk_file_chooser_get_extra_widget
                                            (gtkfilechooser *chooser);

определяет текущий виджет предварительного просмотра; смотрите gtk_file_chooser_set_extra_widget().

начиная с версии 2.4

gtk_file_chooser_add_filter ()

void        gtk_file_chooser_add_filter     (gtkfilechooser *chooser,
                                             gtkfilefilter *filter);

добавляет filter в список фильтров между которыми пользователь может делать выбор. когда фильтр выбран, отображаются только файлы соответствующие этому фильтру.

помните что chooser монопольно владеет фильтром, поэтому вы ссылаетесь и помещаете его, если вам нужно сохранить ссылку.

начиная с версии 2.4

gtk_file_chooser_remove_filter ()

void        gtk_file_chooser_remove_filter  (gtkfilechooser *chooser,
                                             gtkfilefilter *filter);

удаляет filter из списка фильтров выбираемых пользователем.

начиная с версии 2.4

gtk_file_chooser_list_filters ()

gslist*     gtk_file_chooser_list_filters   (gtkfilechooser *chooser);

список текущих установленных фильтров выбираемых пользователем; смотрите gtk_file_chooser_add_filter(), gtk_file_chooser_remove_filter().

начиная с версии 2.4

gtk_file_chooser_set_filter ()

void        gtk_file_chooser_set_filter     (gtkfilechooser *chooser,
                                             gtkfilefilter *filter);

устанавливает текущий фильтр; только фалы соответствующие фильтру будут отображаться. если список фильтров выбираемых пользователем не пуст, то фильтр должен быть одним из фильтров в этом списке. установка текущемго фильтра, когда список пуст, полезна для ограничения пользователя изменять отображение отфильтрованных файлов.

начиная с версии 2.4

gtk_file_chooser_get_filter ()

gtkfilefilter* gtk_file_chooser_get_filter  (gtkfilechooser *chooser);

определяет текущий фильтр; смотрите gtk_file_chooser_set_filter().

начиная с версии 2.4

gtk_file_chooser_add_shortcut_folder ()

gboolean    gtk_file_chooser_add_shortcut_folder
                                            (gtkfilechooser *chooser,
                                             const char *folder,
                                             gerror **error);

добавляет каталог для отображения с ярлыками каталогов в селекторе файлов. помните что ярлыки каталогов не сохраняются, поскольку их обеспечивают приложения. например, вы можете использовать "/usr/share/mydrawprogram/clipart" для добавления каталога в список значений.

начиная с версии 2.4

gtk_file_chooser_remove_shortcut_folder ()

gboolean    gtk_file_chooser_remove_shortcut_folder
                                            (gtkfilechooser *chooser,
                                             const char *folder,
                                             gerror **error);

удаляет каталог из списка ярлыков каталогов селектора файлов.

начиная с версии 2.4

gtk_file_chooser_list_shortcut_folders ()

gslist*     gtk_file_chooser_list_shortcut_folders
                                            (gtkfilechooser *chooser);

запрашивает список ярлыков каталогов в селекторе файлов, которые установлены с помощью gtk_file_chooser_add_shortcut_folder().

начиная с версии 2.4

gtk_file_chooser_add_shortcut_folder_uri ()

gboolean    gtk_file_chooser_add_shortcut_folder_uri
                                            (gtkfilechooser *chooser,
                                             const char *uri,
                                             gerror **error);

добавляет uri для отображения с ярлыками каталогов в селекторе файлов. помните что ярлыки каталогов не сохраняются, поскольку их обеспечивают приложения. например, вы можете использовать "/usr/share/mydrawprogram/clipart" для добавления каталога в список значений.

начиная с версии 2.4

gtk_file_chooser_remove_shortcut_folder_uri ()

gboolean    gtk_file_chooser_remove_shortcut_folder_uri
                                            (gtkfilechooser *chooser,
                                             const char *uri,
                                             gerror **error);

удаляет каталог uri из списка ярлыков каталогов селектора файлов.

начиная с версии 2.4

gtk_file_chooser_list_shortcut_folder_uris ()

gslist*     gtk_file_chooser_list_shortcut_folder_uris
                                            (gtkfilechooser *chooser);

запрашивает список ярлыков каталогов селектора файлов, которые установлены с помощью gtk_file_chooser_add_shortcut_folder_uri().

начиная с версии 2.4

детали свойств

свойство "action"

  "action"               gtkfilechooseraction  : read / write

тип операции выполняемой селектором файлов.

значение по умолчанию: gtk_file_chooser_action_open

свойство "do-overwrite-confirmation"

  "do-overwrite-confirmation" gboolean              : read / write

представляет ли селектор файлов в режиме gtk_file_chooser_action_save диалог подтверждения перезаписи, если пользователь выбрал имя уже существующего файла.

значение по умолчанию: false

начиная с версии 2.8

свойство "extra-widget"

  "extra-widget"         gtkwidget             : read / write

виджет обеспечиваемый приложением для дополнительных опций.

свойство "file-system-backend"

  "file-system-backend"  gchararray            : write / construct only

имя файловой системы внутреннего использования.

значение по умолчанию: null

свойство "filter"

  "filter"               gtkfilefilter         : read / write

текущий фильтр отображаемых файлов.

свойство "local-only"

  "local-only"           gboolean              : read / write

должны ли выбранные файлы ограничиваться локальными файлами: urls.

значение по умолчанию: true

свойство "preview-widget"

  "preview-widget"       gtkwidget             : read / write

виджет поставляемый приложением предварительного просмотра.

свойство "preview-widget-active"

  "preview-widget-active" gboolean              : read / write

должен ли отображаться виджет для предварительного просмотра поставляемый приложением.

значение по умолчанию: true

свойство "select-multiple"

  "select-multiple"      gboolean              : read / write

возможен ли множественный выбор файлов.

значение по умолчанию: false

свойство "show-hidden"

  "show-hidden"          gboolean              : read / write

отображаются ли скрытые файлы и каталоги.

значение по умолчанию: false

свойство "use-preview-label"

  "use-preview-label"    gboolean              : read / write

отображается ли заготовленный ярлык имени предварительно просматриваемого файла.

значение по умолчанию: true

детали сигналов

сигнал "confirm-overwrite"

gtkfilechooserconfirmationuser_function                  (gtkfilechooser *filechooser,
                                            gpointer        user_data)        : run last

этот сигнал издаётся каждый раз представляя диалог подтверждения когда пользователь выбирает для записи имя уже существующего файла. сигнал издаётся только в режиме gtk_file_chooser_action_save.

большинство приложений просто отключит свойство do-overwrite-confirmation (или вызов функции gtk_file_chooser_set_do_overwrite_confirmation()), и они автоматически получат заготовленный диалог подтверждения. приложения которые нуждаются в настройке этого поведения должны сделать это, а также подключить сигнал confirm-overwrite.

обработчик этого сигнала должен вернуть значение gtkfilechooserconfirmation, которое указывает принятое действие. если обработчик определяет что пользователь должен выбрать другое имя файла, он должен вернуть gtk_file_chooser_confirmation_select_again. если он определит что пользователь удовлетворён своим выбором имени файла, он должен вернуть gtk_file_chooser_confirmation_accept_filename. с другой стороны, если он определит что заготовленный диалог подтверждения должен использоваться, он возвращает gtk_file_chooser_confirmation_confirm. следующий пример иллюстрирует это.

пример 5. выборочная конфигурация

static gtkfilechooserconfirmation
confirm_overwrite_callback (gtkfilechooser *chooser, gpointer data)
{
  char *uri;

  uri = gtk_file_chooser_get_uri (chooser);

  if (is_uri_read_only (uri))
    {
      if (user_wants_to_replace_read_only_file (uri))
        return gtk_file_chooser_confirmation_accept_filename;
      else
        return gtk_file_chooser_confirmation_select_again;
    } else
      return gtk_file_chooser_confirmation_confirm; /* fall back to the default dialog */
}

...

chooser = gtk_file_chooser_dialog_new (...);

gtk_file_chooser_set_do_overwrite_confirmation (gtk_file_chooser (dialog), true);
g_signal_connect (chooser, "confirm-overwrite",
                  g_callback (confirm_overwrite_callback), null);

if (gtk_dialog_run (chooser) == gtk_response_accept)
        save_to_file (gtk_file_chooser_get_filename (gtk_file_chooser (chooser));

gtk_widget_destroy (chooser);
      

начиная с версии 2.8

сигнал "current-folder-changed"

void        user_function                  (gtkfilechooser *chooser,
                                            gpointer        user_data)      : run last

этот сигнал издаётся при смене текущемго каталога в gtkfilechooser. это может произойти в результате выбора пользователем некоторых действий сменяющих каталог, таких как выбор каталога в закладках. это может также произойти как результат вызова функции для явной смены каталога в селекторе файлов.

обычно вам не нужно подключать этот сигнал, если вы не отслеживаете какой каталог показывает селектор файлов.

смотрите также: gtk_file_chooser_set_current_folder(), gtk_file_chooser_get_current_folder(), gtk_file_chooser_set_current_folder_uri(), gtk_file_chooser_get_current_folder_uri().

сигнал "file-activated"

void        user_function                  (gtkfilechooser *chooser,
                                            gpointer        user_data)      : run last

этот сигнал издаётся когда пользователь "активизирует" файл в селекторе файлов. это может произойти при двойном щелчке мышью на файле в списке файлов, или при нажатии клавиши enter.

обычно вам не нужно подключать этот сигнал. он используется внутри gtkfilechooserdialog для определения какую кнопку активизировать по умолчанию в диалоге.

смотрите также: gtk_file_chooser_get_filename(), gtk_file_chooser_get_filenames(), gtk_file_chooser_get_uri(), gtk_file_chooser_get_uris().

сигнал "selection-changed"

void        user_function                  (gtkfilechooser *chooser,
                                            gpointer        user_data)      : run last

этот сигнал издаётся при появлении изменений в наборе выбранных файлов в gtkfilechooser. это может произойти когда пользователь изменяет выделение с помощью мыши или клавиатуры, или когда явно вызывается функция для изменения выделения.

обычно вам не нужно подключать этот сигнал, поскольку проще подождать пока селектор файлов закончит выполнение, а затем получить список выделенных файлов используя функции упомянутые ниже.

смотрите также: gtk_file_chooser_select_filename(), gtk_file_chooser_unselect_filename(), gtk_file_chooser_get_filename(), gtk_file_chooser_get_filenames(), gtk_file_chooser_select_uri(), gtk_file_chooser_unselect_uri(), gtk_file_chooser_get_uri(), gtk_file_chooser_get_uris().

сигнал "update-preview"

void        user_function                  (gtkfilechooser *chooser,
                                            gpointer        user_data)      : run last

этот сигнал издаётся когда предварительный просмотр в селекторе файлов должен быть сгенерирован заново. например, это может произойти при изменении текущемго выбранного файла. вы должны использовать этот сигнал если вам нужен селектор файлов имеющий виджеты предварительного просмотра.

как только вы установили виджет предварительного просмотра используя gtk_file_chooser_set_preview_widget(), вы должны обновить его когда издастся сигнал. вы можете использовать функции gtk_file_chooser_get_preview_filename() или gtk_file_chooser_get_preview_uri() для получения имени файла для предварительного просмотра. ваш виджет возможно не будет в состоянии просматривать все виды файлов; поэтому ваша callback-функция должна вызывать gtk_file_chooser_set_preview_wiget_active() для информирования селектора файлов об успешной или не успешной генерации предварительного просмотра.

пожалуйста посмотрите примерный код в the section called “adding a preview widget”.

смотрите также: gtk_file_chooser_set_preview_widget(), gtk_file_chooser_set_preview_widget_active(), gtk_file_chooser_set_use_preview_label(), gtk_file_chooser_get_preview_filename(), gtk_file_chooser_get_preview_uri().

смотрите также

gtkfilechooserdialog, gtkfilechooserwidget, gtkfilechooserbutton