GtkContainer

Высота для управления геометрией по ширине

GTK+ использует систему управления геометрией «высота для ширины» (и «ширина для высоты»). «Высота для ширины» означает, что виджет может изменять необходимое вертикальное пространство в зависимости от предоставленного горизонтального пространства (и аналогично для «ширина для высоты»).

Следует учитывать некоторые моменты при реализации виджетов-контейнеров, использующих систему управления геометрией GTK+ «высота для ширины». Во-первых, важно отметить, что контейнер должен отдавать приоритет одному из измерений, то есть виджет или контейнер может иметь только GtkSizeRequestMode, который является GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH или GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT. Однако каждый виджет и контейнер должен уметь реагировать на API для обоих измерений, то есть даже если виджет имеет режим запроса «высота для ширины», его родитель может запросить его размеры с помощью API «ширина для высоты».

Чтобы обеспечить правильную работу, при реализации контейнеров «высота для ширины» (или «ширина для высоты») необходимо соблюдать следующие рекомендации.

Каждый режим запроса включает 2 виртуальных метода. API «высота для ширины» проходят через gtk_widget_get_preferred_width(), а затем через gtk_widget_get_preferred_height_for_width(). При обработке запросов в обратном GtkSizeRequestMode важно, чтобы каждый виджет запрашивал по крайней мере достаточно места для отображения всего своего содержимого в любое время.

Когда вызывается gtk_widget_get_preferred_height() для контейнера, который имеет режим «высота для ширины», контейнер должен вернуть высоту для его минимальной ширины. Это легко достигается путем простого вызова обратных API, реализованных для него следующим образом:

Аналогично, когда вызывается gtk_widget_get_preferred_width_for_height() для контейнера или виджета, который имеет режим «высота для ширины», ему нужно только вернуть базовую минимальную ширину, как показано ниже:

Запросы «высота для ширины» обычно реализуются в терминах виртуального распределения виджетов в входном направлении. Предположим, что режим запроса «высота для ширины»; контейнер реализует виртуальную функцию get_preferred_height_for_width() путем сначала вызова gtk_widget_get_preferred_width() для каждого из своих дочерних элементов.

Для каждой потенциальной группы дочерних элементов, расположенных в ряд, значения, возвращаемые функцией gtk_widget_get_preferred_width(), должны быть собраны в массив структур GtkRequestedSize. Любое расстояние между дочерними элементами должно быть удалено из входного параметра for_width, а затем общий размер должен быть распределен с помощью функции-помощника gtk_distribute_natural_allocation().

Затем контейнер переходит к запросу предпочтительной высоты для каждого дочернего элемента, используя gtk_widget_get_preferred_height_for_width() и используя размеры, сохраненные в массиве GtkRequestedSize.

Для распределения контейнера «высота для ширины» важно учитывать, что контейнер должен отдавать приоритет одному измерению. Итак, если контейнер — это контейнер «высота для ширины», он должен сначала распределить все виджеты по горизонтали, используя массив GtkRequestedSize и gtk_distribute_natural_allocation(), а затем добавить любое дополнительное пространство (если и где это необходимо) для расширения виджета.

После добавления всего пространства для расширения контейнер предполагает, что ему была предоставлена достаточная высота для размещения всего его содержимого. В этот момент контейнер должен использовать общие горизонтальные размеры каждого виджета для запроса высоты «высота для ширины» каждого из его дочерних элементов и сохранять запросы в массиве GtkRequestedSize для любых виджетов, которые выстраиваются вертикально (для табличных контейнеров это можно обобщить на высоты и ширины строк и столбцов). Затем вертикальное пространство должно быть снова распределено с помощью gtk_distribute_natural_allocation(), учитывая при этом выделенную высоту виджета за вычетом любого вертикального отступа, добавляемого контейнером. Затем следует добавить вертикальное пространство для расширения, где это уместно и доступно, и контейнер должен приступить к фактическому размещению дочерних виджетов.

См. раздел управления геометрией GtkWidget, чтобы узнать больше о реализации управления геометрией «высота для ширины» для виджетов.

Свойства дочерних элементов

GtkContainer вводит свойства дочерних элементов. Это свойства объектов, которые не относятся ни к контейнеру, ни к содержащему виджету, а скорее к их взаимосвязи. Типичные примеры свойств дочерних элементов — это позиция или тип размещения виджета, который содержится в GtkBox.

Используйте gtk_container_class_install_child_property() для установки свойств дочерних элементов для класса контейнера и gtk_container_class_find_child_property() или gtk_container_class_list_child_properties() для получения информации о существующих свойствах дочерних элементов.

Для установки значения свойства дочернего элемента используйте gtk_container_child_set_property(), gtk_container_child_set() или gtk_container_child_set_valist(). Для получения значения свойства дочернего элемента используйте gtk_container_child_get_property(), gtk_container_child_get() или gtk_container_child_get_valist(). Для отправки уведомлений об изменениях свойств дочерних элементов используйте gtk_widget_child_notify().

GtkContainer как GtkBuildable

Реализация GtkContainer интерфейса GtkBuildable поддерживает элемент <packing> для дочерних элементов, который может содержать несколько элементов <property>, задающих свойства дочерних элементов.

Начиная с версии 2.16, свойства дочерних элементов также могут быть помечены как переводимые с помощью тех же атрибутов «translatable», «comments» и «context», что используются для обычных свойств.

Начиная с версии 3.16, контейнеры могут иметь элемент <focus-chain>, содержащий несколько элементов <widget>, по одному для каждого дочернего элемента, который должен быть добавлен в цепочку фокуса. Атрибут «name» задаёт идентификатор виджета.

Пример этих свойств в определениях пользовательского интерфейса:

static void
foo_container_get_preferred_height (GtkWidget *widget,
                                    gint *min_height,
                                    gint *nat_height)
{
   if (i_am_in_height_for_width_mode)
     {
       gint min_width;

       GTK_WIDGET_GET_CLASS (widget)->get_preferred_width (widget,
                                                           &min_width,
                                                           NULL);
       GTK_WIDGET_GET_CLASS (widget)->get_preferred_height_for_width
                                                          (widget,
                                                           min_width,
                                                           min_height,
                                                           nat_height);
     }
   else
     {
       ... many containers support both request modes, execute the
       real width-for-height request here by returning the
       collective heights of all widgets that are stacked
       vertically (or whatever is appropriate for this container)
       ...
     }
}

GTK_IS_RESIZE_CONTAINER()

#define             GTK_IS_RESIZE_CONTAINER(widget)

GTK_CONTAINER_WARN_INVALID_CHILD_PROPERTY_ID()

#define             GTK_CONTAINER_WARN_INVALID_CHILD_PROPERTY_ID(object, property_id, pspec)

Эта макрокоманда должна использоваться для выдачи стандартного предупреждения об неожиданных свойствах в реализациях set_child_property() и get_child_property().

gtk_container_add ()

void
gtk_container_add (GtkContainer *container,
                   GtkWidget *widget);

Добавляет widget в container. Обычно используется для простых контейнеров, таких как GtkWindow, GtkFrame или GtkButton; для более сложных контейнеров макета, таких как GtkBox или GtkGrid, эта функция выберет параметры упаковки по умолчанию, которые могут быть некорректными. Поэтому рассмотрите функции, такие как gtk_box_pack_start() и gtk_grid_attach() в качестве альтернативы gtk_container_add() в таких случаях. Виджет может быть добавлен только в один контейнер за раз; вы не можете разместить один и тот же виджет в двух разных контейнерах.

Обратите внимание, что некоторые контейнеры, такие как GtkScrolledWindow или GtkListBox, могут добавлять промежуточных потомков между добавленным виджетом и контейнером.

gtk_container_remove ()

void
gtk_container_remove (GtkContainer *container,
                      GtkWidget *widget);

Удаляет widget из container. widget должен находиться внутри container. Обратите внимание, что container будет владеть ссылкой на widget, и это может быть последняя удерживаемая ссылка; поэтому удаление виджета из его контейнера может привести к уничтожению этого виджета. Если вы хотите повторно использовать widget, вам нужно добавить к нему ссылку перед удалением из контейнера, используя g_object_ref(). Если вы не хотите повторно использовать widget, обычно более эффективно просто уничтожить его напрямую с помощью gtk_widget_destroy(), так как это удалит его из контейнера и поможет разорвать любые циклы счётчика циклической ссылки.

gtk_container_add_with_properties ()

void
gtk_container_add_with_properties (GtkContainer *container,
                                   GtkWidget *widget,
                                   const gchar *first_prop_name,
                                   ...);

Добавляет widget в container, одновременно устанавливая свойства дочернего элемента. См. gtk_container_add() и gtk_container_child_set() для получения более подробной информации.

gtk_container_get_resize_mode ()

GtkResizeMode
gtk_container_get_resize_mode (GtkContainer *container);

Возвращает режим изменения размера контейнера. См. gtk_container_set_resize_mode().

gtk_container_set_resize_mode ()

void
gtk_container_set_resize_mode (GtkContainer *container,
                               GtkResizeMode resize_mode);

Устанавливает режим изменения размера контейнера.

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

gtk_container_check_resize ()

void
gtk_container_check_resize (GtkContainer *container);

gtk_container_foreach ()

void
gtk_container_foreach (GtkContainer *container,
                       GtkCallback callback,
                       gpointer callback_data);

Вызывает callback для каждого дочернего элемента, не являющегося внутренним, container. См. gtk_container_forall() для получения подробностей о том, что представляет собой «внутренний» дочерний элемент. Для всех практических целей эта функция должна перебирать только те виджеты-потомки, которые были добавлены в контейнер приложением с явными add() вызовами.

Разрешается удалить дочерний элемент из обработчика callback.

Большинство приложений должны использовать gtk_container_foreach(), а не gtk_container_forall().

gtk_container_get_children ()

GList *
gtk_container_get_children (GtkContainer *container);

Возвращает дочерние элементы контейнера, не являющиеся внутренними. Подробнее о том, что считается "внутренним" элементом, см. gtk_container_forall().

gtk_container_get_path_for_child ()

GtkWidgetPath *
gtk_container_get_path_for_child (GtkContainer *container,
                                  GtkWidget *child);

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

gtk_container_set_reallocate_redraws ()

void
gtk_container_set_reallocate_redraws (GtkContainer *container,
                                      gboolean needs_redraws);

Устанавливает флаг reallocate_redraws контейнера в указанное значение.

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

gtk_container_get_focus_child ()

GtkWidget *
gtk_container_get_focus_child (GtkContainer *container);

Возвращает текущий виджет, получивший фокус внутри container . Это не текущий виджет с фокусом. Его можно получить, вызвав gtk_window_get_focus().

С: 2.14

gtk_container_set_focus_child ()

void
gtk_container_set_focus_child (GtkContainer *container,
                               GtkWidget *child);

Устанавливает или отменяет фокусировку дочернего элемента container, если child равно NULL.

Данная функция излучает сигнал GtkContainer::set_focus_child объекта container. Реализации GtkContainer могут переопределить стандартное поведение, переопределив обработку этого сигнала.

Эта функция в основном предназначена для использования виджетами. Приложения могут использовать gtk_widget_grab_focus() для ручного установки фокуса на определенный виджет.

gtk_container_get_focus_vadjustment ()

GtkAdjustment *
gtk_container_get_focus_vadjustment (GtkContainer *container);

Получает вертикальную настройку фокуса для контейнера. Смотрите gtk_container_set_focus_vadjustment().

gtk_container_set_focus_vadjustment ()

void
gtk_container_set_focus_vadjustment (GtkContainer *container,
                                     GtkAdjustment *adjustment);

Подключает настройку к обработке фокуса в контейнере, так что при фокусировке дочернего элемента контейнера, настройка прокручивается для отображения этого виджета. Эта функция устанавливает вертикальное выравнивание. Смотрите gtk_scrolled_window_get_vadjustment() для типового способа получения настройки и gtk_container_set_focus_hadjustment() для установки горизонтальной настройки.

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

gtk_container_get_focus_hadjustment ()

GtkAdjustment *
gtk_container_get_focus_hadjustment (GtkContainer *container);

Получает горизонтальную настройку фокуса для контейнера. Смотрите gtk_container_set_focus_hadjustment().

gtk_container_set_focus_hadjustment ()

void
gtk_container_set_focus_hadjustment (GtkContainer *container,
                                     GtkAdjustment *adjustment);

Подключает регулировку к обработке фокуса в контейнере, поэтому при получении фокуса дочерним элементом контейнера регулировка прокручивается для отображения этого виджета. Эта функция устанавливает горизонтальное выравнивание. См. gtk_scrolled_window_get_hadjustment() для типичного способа получения регулировки и gtk_container_set_focus_vadjustment() для установки вертикальной регулировки.

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

gtk_container_resize_children ()

void
gtk_container_resize_children (GtkContainer *container);

gtk_container_child_type ()

GType
gtk_container_child_type (GtkContainer *container);

Возвращает тип дочерних элементов, поддерживаемых контейнером.

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

gtk_container_child_get ()

void
gtk_container_child_get (GtkContainer *container,
                         GtkWidget *child,
                         const gchar *first_prop_name,
                         ...);

Получает значения одного или нескольких свойств дочерних элементов для child и container .

gtk_container_child_set ()

void
gtk_container_child_set (GtkContainer *container,
                         GtkWidget *child,
                         const gchar *first_prop_name,
                         ...);

Устанавливает одно или несколько свойств дочерних элементов для child и container .

gtk_container_child_get_property ()

void
gtk_container_child_get_property (GtkContainer *container,
                                  GtkWidget *child,
                                  const gchar *property_name,
                                  GValue *value);

Получает значение свойства дочернего элемента для child и container .

gtk_container_child_set_property ()

void
gtk_container_child_set_property (GtkContainer *container,
                                  GtkWidget *child,
                                  const gchar *property_name,
                                  const GValue *value);

Устанавливает свойство дочернего элемента для child и container .

gtk_container_child_get_valist ()

void
gtk_container_child_get_valist (GtkContainer *container,
                                GtkWidget *child,
                                const gchar *first_property_name,
                                va_list var_args);

Получает значения одного или нескольких свойств дочерних элементов для child и container .

gtk_container_child_set_valist ()

void
gtk_container_child_set_valist (GtkContainer *container,
                                GtkWidget *child,
                                const gchar *first_property_name,
                                va_list var_args);

Устанавливает одно или несколько свойств дочерних элементов для child и container .

gtk_container_child_notify ()

void
gtk_container_child_notify (GtkContainer *container,
                            GtkWidget *child,
                            const gchar *child_property);

Вызывает сигнал “child-notify” для свойства дочернего элемента child_property.

Это аналог g_object_notify() для свойств дочерних элементов.

Также см. gtk_widget_child_notify().

С: 3.2

gtk_container_child_notify_by_pspec ()

void
gtk_container_child_notify_by_pspec (GtkContainer *container,
                                     GtkWidget *child,
                                     GParamSpec *pspec);

Вызывает сигнал “child-notify” для свойства дочернего элемента, указанного в pspec.

Это аналог g_object_notify_by_pspec() для свойств дочерних элементов.

С: 3.18

gtk_container_forall ()

void
gtk_container_forall (GtkContainer *container,
                      GtkCallback callback,
                      gpointer callback_data);

Вызывает callback для каждого непосредственного дочернего элемента container, включая дочерние элементы, считающиеся «внутренними» (детали реализации контейнера). «Внутренние» дочерние элементы обычно не добавлялись пользователем контейнера, а были добавлены самой реализацией контейнера.

Большинство приложений должны использовать gtk_container_foreach(), а не gtk_container_forall().

[virtual forall]

gtk_container_get_border_width ()

guint
gtk_container_get_border_width (GtkContainer *container);

Возвращает ширину границы контейнера. См. gtk_container_set_border_width().

gtk_container_set_border_width ()

void
gtk_container_set_border_width (GtkContainer *container,
                                guint border_width);

Устанавливает ширину границы контейнера.

Ширина границы контейнера — это количество места, которое следует оставить снаружи контейнера. Единственное исключение — GtkWindow; так как верхние окна не могут оставлять пространство снаружи, они оставляют пространство внутри. Граница добавляется по всем сторонам контейнера. Чтобы добавить пространство только с одной стороны, используйте конкретное свойство “margin” дочернего виджета, например, “margin-top”.

gtk_container_propagate_draw ()

void
gtk_container_propagate_draw (GtkContainer *container,
                              GtkWidget *child,
                              cairo_t *cr);

Когда контейнер получает вызов функции рисования, он должен отправлять синтетические вызовы “draw” всем дочерним элементам, которые не имеют собственных GdkWindows. Эта функция предоставляет удобный способ сделать это. Контейнер, получив вызов своей функции рисования “draw”, вызывает gtk_container_propagate_draw() один раз для каждого дочернего элемента, передавая cr, полученное контейнером.

gtk_container_propagate_draw() позаботится о переводе начала cr и решении вопроса о необходимости отправки рисования дочернему элементу. Это удобный и оптимизированный способ получить тот же эффект, что и вызов gtk_widget_draw() непосредственно на дочернем элементе.

В большинстве случаев контейнер может просто унаследовать реализацию “draw” от GtkContainer или выполнить некоторое рисование, а затем перейти к реализации ::draw от GtkContainer.

gtk_container_get_focus_chain ()

gboolean
gtk_container_get_focus_chain (GtkContainer *container,
                               GList **focusable_widgets);

Возвращает цепочку фокуса контейнера, если она была явно задана. Если цепочка фокуса не была явно задана, GTK+ вычисляет цепочку фокуса на основе расположения дочерних элементов. В этом случае GTK+ сохраняет NULL в focusable_widgets и возвращает FALSE.

gtk_container_set_focus_chain ()

void
gtk_container_set_focus_chain (GtkContainer *container,
                               GList *focusable_widgets);

Устанавливает цепочку фокуса, переопределяя автоматически вычисляемую GTK+.

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

gtk_container_unset_focus_chain ()

void
gtk_container_unset_focus_chain (GtkContainer *container);

Удаляет цепочку фокуса, явно заданную с помощью gtk_container_set_focus_chain().

gtk_container_class_find_child_property ()

GParamSpec *
gtk_container_class_find_child_property
                               (GObjectClass *cclass,
                                const gchar *property_name);

Находит свойство дочернего элемента класса контейнера по имени.

gtk_container_class_install_child_property ()

void
gtk_container_class_install_child_property
                               (GtkContainerClass *cclass,
                                guint property_id,
                                GParamSpec *pspec);

Устанавливает дочернее свойство в классе контейнера.

gtk_container_class_install_child_properties ()

void
gtk_container_class_install_child_properties
                               (GtkContainerClass *cclass,
                                guint n_pspecs,
                                GParamSpec **pspecs);

Устанавливает свойства дочерних элементов в классе контейнера.

Since: 3.18

gtk_container_class_list_child_properties ()

GParamSpec **
gtk_container_class_list_child_properties
                               (GObjectClass *cclass,
                                guint *n_properties);

Возвращает все свойства дочерних элементов класса контейнера.

gtk_container_class_handle_border_width ()

void
gtk_container_class_handle_border_width
                               (GtkContainerClass *klass);

Изменяет подкласс GtkContainerClass для автоматического добавления и удаления настройки border-width в GtkContainer. Это позволяет подклассу игнорировать ширину границы в запросах размера и методах выделения. Цель состоит в том, чтобы подкласс вызывал это в функции class_init.

gtk_container_class_handle_border_width() необходим, так как было бы слишком сложно изменить API для этого поведения по умолчанию. Поэтому подклассы должны «подключиться» к обработке border_width родительским классом.