GtkLabel

CSS-узлы

GtkLabel имеет единственный CSS-узел с именем label. К меткам можно применять множество стилей, таких как .title, .subtitle, .dim-label и т. д. В GtkShortcutsWindow метки используются со стилем .keycap.

Если у метки есть выделение, у неё есть дочерний узел с именем selection.

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

GtkLabel как GtkBuildable

Реализация GtkLabel интерфейса GtkBuildable поддерживает пользовательский элемент <attributes>, который поддерживает любое количество элементов <attribute>. Элемент <attribute> имеет атрибуты с именами “name“, “value“, “start“ и “end“ и позволяет задавать значения PangoAttribute для этой метки.

Пример фрагмента определения интерфейса с указанием атрибутов Pango:

Атрибуты start и end задают диапазон символов, к которому применяется атрибут Pango. Если start и end не указаны, атрибут применяется ко всему тексту. Обратите внимание, что указание диапазонов не имеет большого смысла с переводимыми атрибутами. Вместо этого используйте разметку, встроенную в переводимое содержимое.

Доступность

GtkLabel использует роль GTK_ACCESSIBLE_ROLE_LABEL.

Мемоники

Метки могут содержать «мемоники». Мемоники — это подчеркнутые символы в метке, используемые для навигации с клавиатуры. Мемоники создаются путём предоставления строки с подчёркиванием перед символом мемоника, например "_File", в функции gtk_label_new_with_mnemonic() или gtk_label_set_text_with_mnemonic().

Мемоники автоматически активируют любой активируемый виджет, в котором находится метка, например, GtkButton; если метка не находится внутри виджета-мишени мемоники, вам необходимо указать виджет-мишень метке с помощью gtk_label_set_mnemonic_widget(). Вот простой пример, где метка находится внутри кнопки:

Есть удобная функция для создания кнопок с меткой-мемоникой уже внутри:

Чтобы создать мемоник для виджета рядом с меткой, например GtkEntry, вам нужно указать метку на поле ввода с помощью gtk_label_set_mnemonic_widget():

Разметка (стилизованный текст)

Чтобы упростить форматирование текста в метке (изменение цвета, шрифтов и т. д.), текст метки может быть предоставлен в простом формате разметки.

Вот как создать метку с небольшим шрифтом:

(См. полную документацию по доступным тегам в руководстве Pango.)

Разметка, переданная в gtk_label_set_markup(), должна быть валидной; например, символы <, > и & должны быть экранированы как <, > и &. Если вы передаёте текст, полученный от пользователя, из файла или сети в gtk_label_set_markup(), вам нужно экранировать его с помощью g_markup_escape_text() или g_markup_printf_escaped().

Строки разметки — это просто удобный способ установки PangoAttrList в метке; gtk_label_set_attributes() в некоторых случаях может быть более простым способом задания атрибутов. Однако будьте осторожны; PangoAttrList может создавать проблемы с локализациями, если вы не применяете атрибуты ко всей строке (т. е. если вы не устанавливаете диапазон каждого атрибута в [0, G_MAXINT)). Причина в том, что указание start_index и end_index для PangoAttribute требует знания точной отображаемой строки, поэтому переводы могут вызвать проблемы.

Выделяемые метки

Метки можно сделать выделяемыми с помощью gtk_label_set_selectable(). Выделяемые метки позволяют пользователю копировать содержимое метки в буфер обмена. Следует делать выделяемыми только метки, содержащие информацию, которую полезно копировать, например, сообщения об ошибках.

Форматирование текста

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

Метки могут автоматически переносить текст, если вы вызовете gtk_label_set_wrap().

gtk_label_set_justify() определяет, как строки в метке выравниваются друг с другом. Если вы хотите установить, как метка в целом выравнивается в доступном пространстве, см. свойства “halign” и “valign”.

Свойства “width-chars” и “max-width-chars” могут использоваться для управления размещением размеров эллиптированных или переносящихся меток. Для эллиптических меток, если указано значение (и оно меньше фактического размера текста), оно используется как минимальная ширина, а фактический размер текста используется как естественная ширина метки. Для переносящихся меток, width-chars используется как минимальная ширина, если указана, а max-width-chars используется как естественная ширина. Даже если указан max-width-chars, переносящиеся метки будут переноситься повторно, чтобы использовать всю доступную ширину.

Обратите внимание, что интерпретация “width-chars” и “max-width-chars” немного изменилась с появлением управления геометрией ширины относительно высоты.

Ссылки

GTK поддерживает разметку для нажимаемых гиперссылок в дополнение к обычной разметке Pango. Разметка для ссылок заимствована из HTML, используя элемент <a> с атрибутами “href”, “title” и “class”. GTK отображает ссылки так же, как они отображаются в веб-браузерах, с цветным, подчеркнутым текстом. Атрибут “title” отображается как всплывающая подсказка для ссылки. Атрибут “class” используется как класс стиля для CSS-узла ссылки.

Пример выглядит следующим образом:

Можно реализовать пользовательскую обработку ссылок и их всплывающих подсказок с помощью сигнала “activate-link” и функции gtk_label_get_current_uri().

GtkLabel

typedef struct _GtkLabel GtkLabel;

Свойство “attributes”

  “attributes”               PangoAttrList *

Список атрибутов стиля, применяемых к тексту метки.

Владелец: GtkLabel

Флаги: Чтение / Запись

Свойство “ellipsize”

  “ellipsize”                PangoEllipsizeMode

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

Обратите внимание, что установка этого свойства на значение, отличное от PANGO_ELLIPSIZE_NONE, влечет за собой побочный эффект: метка запрашивает только необходимое пространство для отображения многоточия «…». В частности, это означает, что обрезка меток плохо работает во вкладках записных книжек, если свойство расширения вкладки GtkNotebook не установлено в TRUE. Другие способы установки ширины метки — gtk_widget_set_size_request() и gtk_label_set_width_chars().

Владелец: GtkLabel

Флаги: Чтение / Запись

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

Свойство “extra-menu”

  “extra-menu”               GMenuModel *

Модель меню, содержимое которого будет добавлено в контекстное меню.

Владелец: GtkLabel

Флаги: Чтение / Запись

Свойство “justify”

  “justify”                  GtkJustification

Выравнивание строк в тексте метки относительно друг друга. Это НЕ влияет на выравнивание метки в её выделенной области. См. GtkLabel:xalign для этого.

Владелец: GtkLabel

Флаги: Чтение / Запись

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

Свойство “label”

  “label”                    char *

Содержание метки.

Если строка содержит разметку Pango XML, вам необходимо установить свойство “use-markup” в значение TRUE, чтобы метка отобразила атрибуты разметки. См. также gtk_label_set_markup() для удобной функции, которая одновременно устанавливает это свойство и свойство “use-markup”.

Если строка содержит подчеркивания, действующие как мнемоники, вам необходимо установить свойство “use-underline” в значение TRUE, чтобы метка отобразила их.

Владелец: GtkLabel

Флаги: Чтение / Запись

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

Свойство “lines”

  “lines”                    int

Количество строк, до которых должна быть ограничена обрезка и перенос строк для метки. Это свойство не имеет эффекта, если метка не переносит строки или не обрезает их. Установите это свойство в -1, если вы не хотите ограничивать количество строк.

Владелец: GtkLabel

Флаги: Чтение / Запись

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

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

Свойство “max-width-chars”

  “max-width-chars”          int

Желаемая максимальная ширина метки в символах. Если это свойство установлено в -1, ширина будет вычисляться автоматически.

См. раздел по расположению текста для получения подробной информации о том, как “width-chars” и “max-width-chars” определяют ширину обрезки и переноса строк меток.

Владелец: GtkLabel

Флаги: Чтение / Запись

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

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

Свойство “mnemonic-keyval”

  “mnemonic-keyval”          guint

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

Владелец: GtkLabel

Флаги: Чтение

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

Свойство “mnemonic-widget”

  “mnemonic-widget”          GtkWidget *

Виджет, который будет активирован при нажатии мнемонической клавиши метки.

Владелец: GtkLabel

Флаги: Чтение / Запись

Свойство “selectable”

  “selectable”               gboolean

Возможность выделения текста метки с помощью мыши.

Владелец: GtkLabel

Флаги: Чтение / Запись

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

Свойство “single-line-mode”

  “single-line-mode”         gboolean

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

Владелец: GtkLabel

Флаги: Чтение / Запись

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

Свойство “use-markup”

  “use-markup”               gboolean

Текст метки содержит разметку XML. См. pango_parse_markup().

Владелец: GtkLabel

Флаги: Чтение / Запись

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

Свойство “use-underline”

  “use-underline”            gboolean

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

Владелец: GtkLabel

Флаги: Чтение / Запись

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

Свойство “width-chars”

  “width-chars”              int

Желаемая ширина метки в символах. Если это свойство установлено в -1, ширина будет вычисляться автоматически.

См. раздел по расположению текста для получения подробной информации о том, как “width-chars” и “max-width-chars” определяют ширину обрезки и переноса строк меток.

Владелец: GtkLabel

Флаги: Чтение / Запись

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

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

Свойство “wrap”

  “wrap”                     gboolean

Если установлено, строки переносятся, если текст становится слишком широким.

Владелец: GtkLabel

Флаги: Чтение / Запись

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

Свойство “wrap-mode”

  “wrap-mode”                PangoWrapMode

Если перенос строк включен (см. свойство “wrap”), это свойство управляет способом переноса строк. Значение по умолчанию — PANGO_WRAP_WORD, что означает перенос по границам слов.

Владелец: GtkLabel

Флаги: Чтение / Запись

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

Свойство “xalign”

  “xalign”                   float

Свойство xalign определяет горизонтальное выравнивание текста метки внутри выделенной области метки. Сравните это с “halign”, которое определяет, как выделенная область метки позиционируется в доступном для метки пространстве.

Владелец: GtkLabel

Флаги: Чтение / Запись

Допустимые значения: [0,1]

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

Свойство “yalign”

  “yalign”                   float

Свойство yalign определяет вертикальное выравнивание текста метки внутри выделенной области метки. Сравните это с “valign”, которое определяет, как выделенная область метки позиционируется в доступном для метки пространстве.

Владелец: GtkLabel

Флаги: Чтение / Запись

Допустимые значения: [0,1]

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

Сигнал “activate-current-link”

void
user_function (GtkLabel *self,
               gpointer  user_data)

Сигнал сочетания клавиш, который генерируется при активации ссылки в метке.

Приложения также могут генерировать этот сигнал с g_signal_emit_by_name(), если им нужно программно управлять активацией URI.

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

Флаги: Действие

Сигнал “activate-link”

gboolean
user_function (GtkLabel *self,
               char     *uri,
               gpointer  user_data)

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

Флаги: Выполнение последним

Сигнал “copy-clipboard”

void
user_function (GtkLabel *self,
               gpointer  user_data)

Сигнал ::copy-clipboard — это сигнал сочетания клавиш, который генерируется для копирования выделения в буфер обмена.

По умолчанию для этого сигнала используется сочетание Ctrl-c.

Флаги: Действие

Сигнал “move-cursor”

void
user_function (GtkLabel       *entry,
               GtkMovementStep step,
               int             count,
               gboolean        extend_selection,
               gpointer        user_data)

Сигнал ::move-cursor — это сигнал сочетания клавиш, который генерируется при начале перемещения курсора. Если курсор не отображается в entry, этот сигнал вызывает перемещение области просмотра.

Приложения не должны подключаться к нему, но могут генерировать его с g_signal_emit_by_name(), если им нужно программно управлять курсором.

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

Флаги: Действие

Действие “link.copy”

Копирует ссылку в буфер обмена при активации ссылки в метке.

Действие “link.open”

Открывает ссылку при активации ссылки в метке.

Действие “selection.select-all”

Выделяет весь текст, если метка позволяет выделение.

Действие “selection.delete”

Ничего не делает, так как текст в метках нельзя удалить.

Действие “clipboard.paste”

Ничего не делает, так как текст в метках нельзя редактировать.

Действие “clipboard.copy”

Копирует текст в буфер обмена.

Действие “clipboard.cut”

Ничего не делает, так как текст в метках нельзя удалить.

Действие “menu.popup”

Открывает контекстное меню.