|  |  | GTK+ Reference Manual |
Top | Description | Object Hierarchy | Child Properties | Style Properties | Signals

## GtkAssistant

GtkAssistant — Виджет проводящий пользователя через многошаговые операции

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

    #include <gtk/gtk.h>

                GtkAssistant;
    GtkWidget*  gtk_assistant_new               (void);
    gint        gtk_assistant_get_current_page  (GtkAssistant *assistant);
    void        gtk_assistant_set_current_page  (GtkAssistant *assistant,
                                                 gint page_num);

    gint        gtk_assistant_get_n_pages       (GtkAssistant *assistant);
    GtkWidget*  gtk_assistant_get_nth_page      (GtkAssistant *assistant,
                                                 gint page_num);

    gint        gtk_assistant_prepend_page      (GtkAssistant *assistant,
                                                 GtkWidget *page);
    gint        gtk_assistant_append_page       (GtkAssistant *assistant,
                                                 GtkWidget *page);

    gint        gtk_assistant_insert_page       (GtkAssistant *assistant,
                                                 GtkWidget *page,
                                                 gint position);
    gint        (*GtkAssistantPageFunc)         (gint current_page,
                                                 gpointer data);
    void        gtk_assistant_set_forward_page_func

                                                (GtkAssistant *assistant,
                                                 GtkAssistantPageFunc page_func,
                                                 gpointer data,
                                                 GDestroyNotify destroy);
    enum        GtkAssistantPageType;
    void        gtk_assistant_set_page_type     (GtkAssistant *assistant,
                                                 GtkWidget *page,
                                                 GtkAssistantPageType type);

    GtkAssistantPageType gtk_assistant_get_page_type
                                                (GtkAssistant *assistant,
                                                 GtkWidget *page);
    void        gtk_assistant_set_page_title    (GtkAssistant *assistant,
                                                 GtkWidget *page,
                                                 const gchar *title);
    const gchar* gtk_assistant_get_page_title   (GtkAssistant *assistant,
                                                 GtkWidget *page);
    void        gtk_assistant_set_page_header_image

                                                (GtkAssistant *assistant,
                                                 GtkWidget *page,
                                                 GdkPixbuf *pixbuf);
    GdkPixbuf*  gtk_assistant_get_page_header_image
                                                (GtkAssistant *assistant,
                                                 GtkWidget *page);
    void        gtk_assistant_set_page_side_image

                                                (GtkAssistant *assistant,
                                                 GtkWidget *page,
                                                 GdkPixbuf *pixbuf);
    GdkPixbuf*  gtk_assistant_get_page_side_image
                                                (GtkAssistant *assistant,
                                                 GtkWidget *page);
    void        gtk_assistant_set_page_complete (GtkAssistant *assistant,
                                                 GtkWidget *page,
                                                 gboolean complete);

    gboolean    gtk_assistant_get_page_complete (GtkAssistant *assistant,
                                                 GtkWidget *page);
    void        gtk_assistant_add_action_widget (GtkAssistant *assistant,
                                                 GtkWidget *child);
    void        gtk_assistant_remove_action_widget

                                                (GtkAssistant *assistant,
                                                 GtkWidget *child);
    void        gtk_assistant_update_buttons_state
                                                (GtkAssistant *assistant);

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

      GObject
       +----GInitiallyUnowned
             +----GtkObject
                   +----GtkWidget

                         +----GtkContainer
                               +----GtkBin
                                     +----GtkWindow
                                           +----GtkAssistant

## Осуществляемые интерфейсы

GtkAssistant осуществляет AtkImplementorIface.

## Дочерние свойства

      "complete"             gboolean              : Read / Write
      "header-image"         GdkPixbuf             : Read / Write
      "page-type"            GtkAssistantPageType  : Read / Write
      "sidebar-image"        GdkPixbuf             : Read / Write
      "title"                gchararray            : Read / Write

## Свойства стиля

      "content-padding"      gint                  : Read
      "header-padding"       gint                  : Read

## Сигналы

    "apply"     void        user_function      (GtkAssistant *assistant,
                                                gpointer      user_data)      : Run last
    "cancel"    void        user_function      (GtkAssistant *assistant,
                                                gpointer      user_data)      : Run last
    "close"     void        user_function      (GtkAssistant *assistant,
                                                gpointer      user_data)      : Run last
    "prepare"   void        user_function      (GtkAssistant *assistant,
                                                GtkWidget    *page,
                                                gpointer      user_data)      : Run last

## Описание

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

## Детали

### GtkAssistant

    typedef struct _GtkAssistant GtkAssistant;

### gtk_assistant_new ()

    GtkWidget*  gtk_assistant_new               (void);

Создаёт новый GtkAssistant.

Возвращает: | вновь созданный GtkAssistant

Начиная с версии 2.10

### gtk_assistant_get_current_page ()

    gint        gtk_assistant_get_current_page  (GtkAssistant *assistant);

Возвращает номер текущей страницы

`assistant` : | GtkAssistant
Возвращает: | Перечень (начиная с 0) текущих страниц в `assistant`, если `assistant` не имеет страниц, то возвращается -1

Начиная с версии 2.10

### gtk_assistant_set_current_page ()

    void        gtk_assistant_set_current_page  (GtkAssistant *assistant,
                                                 gint page_num);

Переключает страницу в `page_num`. Помните это необходимо только в выборе кнопок, поскольку `assistant` может быть установлен с помощью `gtk_assistant_set_forward_page_func()`.

`assistant` : | GtkAssistant
`page_num` : | Перечень переключаемых страниц, начинается с 0. Если отрицательное, используется последняя страница. Если большее чем количество страниц в `assistant`, ничего не произойдет.

Начиная с версии 2.10

### gtk_assistant_get_n_pages ()

    gint        gtk_assistant_get_n_pages       (GtkAssistant *assistant);

Возвращает количество страниц в `assistant`

`assistant` : | GtkAssistant
Возвращает: | Количество страниц в `assistant`.

Начиная с версии 2.10

### gtk_assistant_get_nth_page ()

    GtkWidget*  gtk_assistant_get_nth_page      (GtkAssistant *assistant,
                                                 gint page_num);

Возвращает дочерний виджет содержащийся в странице под номером `page_num`.

`assistant` : | GtkAssistant
`page_num` : | Перечень страниц в `assistant`, или -1 для получения последней;
Возвращает: | Дочерний виджет, или `NULL` если `page_num` выходит за предел.

Начиная с версии 2.10

### gtk_assistant_prepend_page ()

    gint        gtk_assistant_prepend_page      (GtkAssistant *assistant,
                                                 GtkWidget *page);

Добавляет страницу в начало `assistant`.

`assistant` : | GtkAssistant
`page` : | GtkWidget
Возвращает: | перечень (начинается с 0) вставляемых страниц

Начиная с версии 2.10

### gtk_assistant_append_page ()

    gint        gtk_assistant_append_page       (GtkAssistant *assistant,
                                                 GtkWidget *page);

Добавляет страницу в конец `assistant`.

`assistant` : | GtkAssistant
`page` : | GtkWidget
Возвращает: | перечень (начинается с 0) вставляемых страниц

Начиная с версии 2.10

### gtk_assistant_insert_page ()

    gint        gtk_assistant_insert_page       (GtkAssistant *assistant,
                                                 GtkWidget *page,
                                                 gint position);

Вставляет страницу в `assistant` в данной позиции.

`assistant` : | GtkAssistant
`page` : | GtkWidget
`position` : | Позиция (начиная с 0) в которую вставляется страница, или -1 для вставки в конец `assistant`
Возвращает: | Позицию (начиная с 0) вставленной страницы

Начиная с версии 2.10

### GtkAssistantPageFunc ()

    gint        (*GtkAssistantPageFunc)         (gint current_page,
                                                 gpointer data);

Функция используемая `gtk_assistant_set_forward_page_func()` чтобы знать какая страница является текущей для вычисления следующей за ней. Она вызывается и для того чтобы вычислить следующую страницу когда пользователь нажал на кнопку "forward" и для обработки поведения кнопки "last".

`current_page` : | Номер страницы используемый для вычисления следующей страницы.
`data` : | Пользовательские данные.
Возвращает: | Номер следующей страницы.

### gtk_assistant_set_forward_page_func ()

    void        gtk_assistant_set_forward_page_func
                                                (GtkAssistant *assistant,
                                                 GtkAssistantPageFunc page_func,
                                                 gpointer data,
                                                 GDestroyNotify destroy);

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

`assistant` : | GtkAssistant
`page_func` : | GtkAssistantPageFunc, или `NULL` для использования значения по умолчанию
`data` : | Пользовательские данные для `page_func`
`destroy` : | Уведомление закрытия для `data`

Начиная с версии 2.10

### перечисление GtkAssistantPageType

    typedef enum
    {
      GTK_ASSISTANT_PAGE_CONTENT,
      GTK_ASSISTANT_PAGE_INTRO,
      GTK_ASSISTANT_PAGE_CONFIRM,
      GTK_ASSISTANT_PAGE_SUMMARY,
      GTK_ASSISTANT_PAGE_PROGRESS
    } GtkAssistantPageType;

Перечисление для определения роли страниц в нутри GtkAssistant. Используется для обработки видимости и чувствительности кнопок.

Помните что помошник должен заканчивать поток страниц страницей типа GTK_ASSISTANT_PAGE_CONFIRM или GTK_ASSISTANT_PAGE_SUMMARY для корректности.

`GTK_ASSISTANT_PAGE_CONTENT` | Страница с обычным содержимым.
`GTK_ASSISTANT_PAGE_INTRO` | Страница содержит введение в помошник.
`GTK_ASSISTANT_PAGE_CONFIRM` | Страница позволяет пользователю подтверждать или отменять изменения.
`GTK_ASSISTANT_PAGE_SUMMARY` | Страница информирующая пользователя о принятых изменениях.
`GTK_ASSISTANT_PAGE_PROGRESS` | Используется для больших задач требующих много времени для выполнения, блокирует помошник до полного выполнения заполнения страницы.

### gtk_assistant_set_page_type ()

    void        gtk_assistant_set_page_type     (GtkAssistant *assistant,
                                                 GtkWidget *page,
                                                 GtkAssistantPageType type);

Устанавливает тип страницы для `page`. Тип страницы определяет поведение страниц в `assistant`.

`assistant` : | GtkAssistant
`page` : | Страница в `assitant`
`type` : | Новый тип для `page`

Начиная с версии 2.10

### gtk_assistant_get_page_type ()

    GtkAssistantPageType gtk_assistant_get_page_type
                                                (GtkAssistant *assistant,
                                                 GtkWidget *page);

Выдаёт тип страницы `page`.

`assistant` : | GtkAssistant
`page` : | Страница в `assistant`
Возвращает: | Тип страницы `page`.

Начиная с версии 2.10

### gtk_assistant_set_page_title ()

    void        gtk_assistant_set_page_title    (GtkAssistant *assistant,
                                                 GtkWidget *page,
                                                 const gchar *title);

Устанавливает заголовок для `page`. Заголовок отображается в заголовочной области помошника когда `page` является текущей страницей.

`assistant` : | GtkAssistant
`page` : | Страница в `assitant`
`title` : | Новый заголовок для `page`

Начиная с версии 2.10

### gtk_assistant_get_page_title ()

    const gchar* gtk_assistant_get_page_title   (GtkAssistant *assistant,
                                                 GtkWidget *page);

Получает заголовок для `page`.

`assistant` : | GtkAssistant
`page` : | Страница в `assistant`
Возвращает: | Заголовок для `page`.

Начиная с версии 2.10

### gtk_assistant_set_page_header_image ()

    void        gtk_assistant_set_page_header_image
                                                (GtkAssistant *assistant,
                                                 GtkWidget *page,
                                                 GdkPixbuf *pixbuf);

Устанавливает изображение заголовка для `page`. Это изображение отображается в заголовочной области помошника когда `page` является текущей страницей.

`assistant` : | GtkAssistant
`page` : | Страница в `assitant`
`pixbuf` : | Новое заголовочное изображение `page`

Начиная с версии 2.10

### gtk_assistant_get_page_header_image ()

    GdkPixbuf*  gtk_assistant_get_page_header_image
                                                (GtkAssistant *assistant,
                                                 GtkWidget *page);

Получает заголовочное изображение для `page`.

`assistant` : | GtkAssistant
`page` : | Страница в `assistant`
Возвращает: | Заголовочное изображение для `page`, или `NULL` если нет изображения для данной страницы.

Начиная с версии 2.10

### gtk_assistant_set_page_side_image ()

    void        gtk_assistant_set_page_side_image
                                                (GtkAssistant *assistant,
                                                 GtkWidget *page,
                                                 GdkPixbuf *pixbuf);

Устанавливает боковое изображение для `page`. Это изображение отображается в боковой области помошника когда `page` является текущей страницей.

`assistant` : | GtkAssistant
`page` : | Страница в `assitant`
`pixbuf` : | Новое заголовочное изображение `page`

Начиная с версии 2.10

### gtk_assistant_get_page_side_image ()

    GdkPixbuf*  gtk_assistant_get_page_side_image
                                                (GtkAssistant *assistant,
                                                 GtkWidget *page);

Получает заголовочное изображение для `page`.

`assistant` : | GtkAssistant
`page` : | Страница в `assistant`
Возвращает: | Боковое изображение для `page`, или `NULL` если у страницы нет бокового изображения.

Начиная с версии 2.10

### gtk_assistant_set_page_complete ()

    void        gtk_assistant_set_page_complete (GtkAssistant *assistant,
                                                 GtkWidget *page,
                                                 gboolean complete);

Устанавливает заполнено ли содержимое `page`. Это заставляет `assistant` обновить состояние кнопок чтобы быть готовым продолжать выполнение задачи.

`assistant` : | GtkAssistant
`page` : | Страница в `assitant`
`complete` : | Статус заполнения страницы

Начиная с версии 2.10

### gtk_assistant_get_page_complete ()

    gboolean    gtk_assistant_get_page_complete (GtkAssistant *assistant,
                                                 GtkWidget *page);

Определяет заполнена ли `page`.

`assistant` : | GtkAssistant
`page` : | Страница в `assistant`
Возвращает: | `TRUE` если `page` заполнена.

Начиная с версии 2.10

### gtk_assistant_add_action_widget ()

    void        gtk_assistant_add_action_widget (GtkAssistant *assistant,
                                                 GtkWidget *child);

Добавляет виджет в область дейтвия в GtkAssistant.

`assistant` : | GtkAssistant
`child` : | GtkWidget

Начиная с версии 2.10

### gtk_assistant_remove_action_widget ()

    void        gtk_assistant_remove_action_widget
                                                (GtkAssistant *assistant,
                                                 GtkWidget *child);

Удаляет виджет из области действия в GtkAssistant.

`assistant` : | GtkAssistant
`child` : | GtkWidget

Начиная с версии 2.10

### gtk_assistant_update_buttons_state ()

    void        gtk_assistant_update_buttons_state
                                                (GtkAssistant *assistant);

Заставляет `assistant` пересчитать состояние кнопок.

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

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

`assistant` : | GtkAssistant

Начиная с версии 2.10

## Детали дочерних свойств

### Дочернее свойство "`complete`"

      "complete"             gboolean              : Read / Write

Устанавливает дочернее свойство "complete" в `TRUE` маркируя страницу как заполненную (например: все запрашиваемые поля заполнены). GTK+ использует эту информацию для контроля чувствительности кнопок навигации.

Значение по умолчанию: FALSE

Начиная с версии 2.10

### Дочернее свойство "`header-image`"

      "header-image"         GdkPixbuf             : Read / Write

Изображение показываемое рядом со страницей.

Установите в `NULL` для скрытия боковой панели.

Начиная с версии 2.10

### Дочернее свойство "`page-type`"

      "page-type"            GtkAssistantPageType  : Read / Write

Тип страницы помошника.

Значение по умолчанию: GTK_ASSISTANT_PAGE_CONTENT

Начиная с версии 2.10

### Дочернее свойство "`sidebar-image`"

      "sidebar-image"        GdkPixbuf             : Read / Write

Боковое изображение для страницы помошника.

### Дочернее свойство "`title`"

      "title"                gchararray            : Read / Write

Заголовок отображаемый в заголовке страницы.

Если заголовок и заголовочное изображение оба равны `NULL`, заголовок не отображается.

Значение по умолчанию: NULL

Начиная с версии 2.10

## Детали свойств стиля

### Свойство стиля "`content-padding`"

      "content-padding"      gint                  : Read

Количество пикселей вокруг содержимого страниц.

Допустимые значения: >= 0

Значение по умолчанию: 1

### Свойство стиля "`header-padding`"

      "header-padding"       gint                  : Read

Количество пикселей вокруг заголовка.

Допустимые значения: >= 0

Значение по умолчанию: 6

## Детали сигнала

### Сигнал "apply"

    void        user_function                  (GtkAssistant *assistant,
                                                gpointer      user_data)      : Run last

Сигнал ::apply издаётся когда нажата кнопка «применить». Поведение по умолчанию GtkAssistant – переключение на следующую страницу, если текущая страница не последняя.

Обработчик для сигнала ::apply должен выполнить действия для которых мастер собрал данные. Если действие занимает много времени для выполнения, вы могли бы учесть помещение страницы типа GTK_ASSISTANT_PAGE_PROGRESS после подтверждённой страницы и обработать эту операцию в течении сигнала "prepare" страницы прогресса.

`assistant` : | `GtkAssistant`
`user_data` : | Пользовательские данные установленные когда подключается обработчик сигнала.

Начиная с версии 2.10

### Сигнал "cancel"

    void        user_function                  (GtkAssistant *assistant,
                                                gpointer      user_data)      : Run last

Сигнал ::cancel издаётся когда нажимается кнопка cancel.

`assistant` : | GtkAssistant
`user_data` : | Пользовательские данные устанавливаемые при подключении обработчика сигнала.

Начиная с версии 2.10

### Сигнал "close"

    void        user_function                  (GtkAssistant *assistant,
                                                gpointer      user_data)      : Run last

Сигнал ::close издается либо когда нажата кнопка итоговой страницы, или когда нажата кнопка apply в последней странице потока (тип GTK_ASSISTANT_PAGE_CONFIRM).

`assistant` : | GtkAssistant
`user_data` : | Пользовательские данные устанавливаемые при подключении обработчика сигнала..

Начиная с версии 2.10

### Сигнал "prepare"

    void        user_function                  (GtkAssistant *assistant,
                                                GtkWidget    *page,
                                                gpointer      user_data)      : Run last

Сигнал ::prepared издаётся когда новая страница устанавливается как текущая страница помошника, после создания видимой новой страницы. Обработчик для этого сигнала может выполнить любую подготовку необходимую перед отображением `page`.

`assistant` : | GtkAssistant
`page` : | Текущая страница
`user_data` : | Пользовательские данные устанавливаемые при подключении обработчика сигнала.

Начиная с версии 2.10