tooltip

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

XML-элемент

tooltip

Java-класс

Tooltip

Основы

ДЕМО

tooltip — вложенный элемент практически всех компонентов и макетов.

Чтобы добавить вложенный tooltip в Jmix Studio, выберите элемент пользовательского интерфейса в XML-дескрипторе экрана или на панели структуры Jmix UI и нажмите кнопку Add→Tooltip на панели инспектора Jmix UI.

Пример определения textField с tooltip:

<textField label="Field with tooltip">
    <tooltip text="Tooltip text"/>
</textField>

Программное определение

Компонент tooltip можно определить программно в коде вашего приложения. Вот пример того, как вы можете программно определить и использовать всплывающую подсказку для компонента textField:

@ViewComponent
private TypedTextField<String> programmaticField;

@Subscribe
public void onInit(final InitEvent event) {
    programmaticField.setTooltipText("This is a tooltip")
            .setPosition(Tooltip.TooltipPosition.START);
}

Настройка расположения

ДЕМО

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

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

Вы можете задать атрибут position с помощью метода setPosition() в вашем коде:

@ViewComponent
protected JmixSelect<Tooltip.TooltipPosition> position;
protected void initPositionItems() {
    ComponentUtils.setItemsMap(position, getPositionItemsMap());
    position.setValue(Tooltip.TooltipPosition.TOP);
}
@Subscribe("position")
protected void onPositionChange(
        ComponentValueChangeEvent<JmixSelect<Tooltip.TooltipPosition>, Tooltip.TooltipPosition> event) {
    customTooltipField.getTooltip().setPosition(event.getValue());
}
protected Map<Tooltip.TooltipPosition, String> getPositionItemsMap() {
    return Arrays.stream(Tooltip.TooltipPosition.values())
            .collect(Collectors.toMap(Function.identity(),mode -> mode.name().replace('_', ' ')));
}

В XML-дескрипторе экрана вы можете указать атрибут position:

<select id="position" label="Position"/>

Управление задержками

ДЕМО

tooltip позволяет настроить задержки появления и исчезновения всплывающей подсказки.

Задержка фокусировки

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

В этом примере всплывающая подсказка появится после 500-миллисекундной задержки, когда курсор мыши наводится на текстовое поле:

@Subscribe("focusDelay")
protected void onFocusDelayChange(ComponentValueChangeEvent<IntegerField, Integer> event) {
    Integer value = event.getValue();

    if (value != null && value > 0 && value <= 5000) {
        customTooltipField.getTooltip().setFocusDelay(value);
    } else {
        customTooltipField.getTooltip().setFocusDelay(0);
    }
}

Задержка скрытия

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

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

@Subscribe("hideDelay")
protected void onHideDelayChange(ComponentValueChangeEvent<IntegerField, Integer> event) {
    Integer value = event.getValue();

    if (value != null && value > 0 && value <= 5000) {
        customTooltipField.getTooltip().setHideDelay(value);
    } else {
        customTooltipField.getTooltip().setHideDelay(0);
    }
}

Задержка наведения

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

В этом примере всплывающая подсказка появится после 500-миллисекундной задержки, когда курсор мыши наводится на текстовое поле:

@Subscribe("hoverDelay")
protected void onHoverDelayChange(ComponentValueChangeEvent<IntegerField, Integer> event) {
    Integer value = event.getValue();

    if (value != null && value > 0 && value <= 5000) {
        customTooltipField.getTooltip().setHoverDelay(value);
    } else {
        customTooltipField.getTooltip().setHoverDelay(0);
    }
}

Принудительное отображение

ДЕМО

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

  • Вам необходимо отобразить всплывающую подсказку на основе определённых условий или взаимодействий пользователя.

  • Содержимое всплывающей подсказки должно генерироваться или обновляться динамически.

В XML-дескрипторе экрана установите атрибут manual в значение true. Это означает, что всплывающая подсказка не будет отображаться автоматически и требует ручного управления.

<textField id="manualTooltipField" label="Manual tooltip">
    <tooltip text="Tooltip text" manual="true" position="END_BOTTOM"/>
</textField>

Затем настройте всплывающую подсказку в контроллере экрана.

@ViewComponent
protected TypedTextField<String> manualTooltipField;
@Autowired
protected UiComponents uiComponents;
@Subscribe
protected void onInit(InitEvent event) {
    initManualTooltip();
    initPositionItems();
}
protected void initManualTooltip() {
    JmixButton helperButton = createHelperButton();
    Tooltip tooltip = manualTooltipField.getTooltip();
    helperButton.addClickListener(e -> tooltip.setOpened(!tooltip.isOpened()));

    manualTooltipField.setSuffixComponent(helperButton);
}
protected JmixButton createHelperButton() {
    JmixButton helperButton = uiComponents.create(JmixButton.class);
    helperButton.setIcon(VaadinIcon.QUESTION_CIRCLE.create());
    helperButton.addThemeVariants(ButtonVariant.LUMO_ICON);
    helperButton.addClassName(StyleUtility.Button.LINK_BUTTON);

    return helperButton;
}

Атрибут opened определяет, видна ли всплывающая подсказка в данный момент. Это логическое значение: true указывает, что всплывающая подсказка открыта, а false — что она закрыта.

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

Атрибуты

Ниже представлены атрибуты, специфичные для tooltip:

Имя Описание По умолчанию

focusDelay

Определяет задержку в миллисекундах перед открытием всплывающей подсказки при фокусе клавиатуры, если не в ручном режиме. См. Задержка фокусировки.

0

hideDelay

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

0

hoverDelay

Определяет задержку в миллисекундах перед открытием всплывающей подсказки при наведении курсора, если не в ручном режиме. См. Задержка при наведении.

0

manual

При true подсказка управляется программно, а не реагирует на события фокуса и мыши. См. Запуск вручную.

false

opened

При true всплывающая подсказка открывается программно. Работает только в том случае, если для manual установлено значение true. См. Запуск вручную.

false

position

Определяет положение всплывающей подсказки относительно цели. См. Позиционирование.

—

text

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

—

Смотрите также