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

Большинству приложений следует использовать 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 и о принятии решения о необходимости отправки вызова draw ребёнку. Это удобный и оптимизированный способ получить тот же эффект, что и при вызове 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 родительским классом.