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, свойства дочерних элементов также могут быть помечены как переводимые с использованием тех же атрибутов «переводимый», «комментарии» и «контекст», которые используются для обычных свойств.

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

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

staticvoid
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 forthis 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() вызовами.

Большинству приложений следует использовать 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);

Устанавливает или сбрасывает (если child равен NULL) дочерний элемент с фокусом для container.

Эта функция излучает сигнал 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);

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

С: 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 родительским классом.