Ввод и отображение текстовой информации

Цель лекции: Научиться применять компоненты ввода и отображения текстовой информации

В библиотеке Juce имеется немного компонентов, позволяющих отображать, вводить и редактировать текстовую информацию. Связано это с тем, что, во-первых, в отличие от других GUI toolkit'ов компоненты Juce обладают внушительным числом свойств и могут использоваться с различными целями: например, уже знакомый нам класс Label может использоваться не только для отображения текста, но и для пользовательского ввода; класс TextEditor, в зависимости от программных настроек, может выступать и как однострочное, и многострочное поле редактирования и т.п. Во-вторых, Juce обладает богатыми возможностями рисования, в том числе вывода текста (см. лекцию 7 ). Рисовать можно не только на любом визуальном компоненте, но и на полосе заголовка главного окна, что выгодно отличает Juce от других кроссплатформенных библиотек.

Ниже приведён перечень классов компонентов Juce, ориентированных на ввод и отображение текста с их краткими характеристиками:

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

Возможность редактирования надписи ярлыка задаётся методом void Label::setEditable(bool editOnSingleClick, bool editOnDoubleClick = false, bool lossOfFocusDiscardsChanges = false). В случае, если параметр lossOfFocusDiscardsChanges принимает значение true, то щелчок мышью где-либо во время редактирования ярлыка, отменяет внесённые в текст изменения.

Текст, отображаемый компонентом класса Label, имеет тип строки String и задаётся в конструкторе Label::Label(const String componentName = String::empty, const String labelText = String::empty), где componentName — название ярлыка, необходимое для нужд отладки, а labelText — отображаемая надпись. Кроме того, задать текст ярлыка можно с помощью функции void Label::setText(const String newText, bool broadcastChangeMessage), где newText — новый текст. Второй параметр необходим для генерации сообщения об измнении текста ярлыка (в том случае, если он принимает значение true), однако в большинстве случаев ему можно присвоить значение false.

Получить текущий текст ярлыка можно с помощью метода const String Label::getText(bool returnActiveEditorContents = false) const. Принимаемый параметр необходим лишь в том случае, если ярлык находится в стадии редактирования текста пользователем. Если параметр принимает значение true, функция возвращает текст, отображаемый ярлыком на момент её вызова. В том случае, если параметр принимает значение false, функция вернёт текст не раньше, чем пользователь закончит его набор и нажмёт клавишу <ENTER>. В том случае, если возможность редактирования надписи запрещена, принимаемый функцией параметр неважен.

Для ввода в ярлык смешанной информации, например, строк и цифр, необходимо воспользоваться оператором или методом склеивания (конкатенации) строк класса ):

Label* pWorkersLabel = new Label("WorkersLabel");
String sWorkers = String(T("Число рабочих: ")) += String(iWorkers);
pWorkersLabel->setText(sWorkers, false);

Каждый ярлык имеет следующие цветовые характеристики: цвет границы, цвет фона и цвет отображаемого текста. Тот или иной цвет задаётся методом, наследуемым классом Label от Component, void Component::setColour(int colourId, const Colour colour). Первый параметр, принимаемый функцией, показывает, какой именно цвет (границы, фона или текста) ярлыка следует изменить, а второй задаёт собственно этот цвет.

Значения ID цвета можно задавать с помощью элементов нумерованного списка, входящего в состав класса Label: enum ColourIds {backgroundColourId = 0x1000280, textColourId = 0x1000281, outlineColourId = 0x1000282} (цвет фона, текста и внешней границы надписи, соответственно).

Кроме того, оформление надписи можно изменить, задав характеристики шрифта, Font (см. лекцию 6 ). Новый шрифт ярлыка задаётся методом void Label::setFont(const Font newFont). Получить текущий шрифт надписи можно с помощью функции const Font Label::getFont() const throw().

Выравнивание текста надписи относительно границ компонента осуществляет его метод void Label::setJustificationType(const Justification justification). Характер выравнивания задаётся объектом класса Justification, который включает в себя нумерованный список

enum
{ 
  left = 1, right = 2, horizontallyCentred = 4, top = 8, 
  bottom = 16, verticallyCentred = 32, horizontallyJustified = 64, centred = 36, 
  centredLeft = 33, centredRight = 34, centredTop = 12, centredBottom = 20, 
  topLeft = 9, topRight = 10, bottomLeft = 17, bottomRight = 18 
}

Элементы списка — флаги выравнивания — могут комбинироваться между собой. Их значения приведены ниже:

Размещение ярлыка в компоненте-контейнере (обычно это компонент содержимого), определяется свойствами и методами, наследуемыми от класса Component (см. лекцию 3 ).

Класс TextEditor

В большинстве GUI framework-ов имеются отдельные компоненты или виджеты для создания однострочного и многострочного полей ввода (например, классы QLineEdit и QTextEdit в Qt). В библиотеке Juce для этих целей используется один и тот же класс, TextEditor, внешний вид и поведение экземпляров которого может значительно различаться, в зависимости от настроек, задаваемых программистом.

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

Ввод текста пользователем в виджете TextEditor может осуществляться как в одну строку, так и в несколько строк. Режим ввода задаётся методом void TextEditor::setMultiLine(bool shouldBeMultiLine, bool shouldWordWrap = true). Эту функцию необходимо вызвать сразу же после объявления объекта класса TextEditor (впрочем, если вы хотите получить однострочное поле ввода, то её можно не вызывать). Если первый из её параметров принимает значение false, то виджет принимает вид однострочного поля ввода, а если true, то появляется возможность вводить несколько строк. Если значение второго параметра равно true, то в виджете перенос строк будет осуществляться автоматически по достижении его края при наборе текста. В противном случае перенос строки будет осуществляться исключительно по нажатию клавиши <ENTER>.

Текст, находящийся в виджете, возвращает метод const String TextEditor::getText() const. Новый текст в нём задаёт функция void TextEditor::setText(const String newText, bool sendTextChangeMessage = true). Она очищает поле ввода и вставляет в виджет текст newText. В том случае, если параметр sendTextChangeMessage принимает значение true, то посылается сообщение об изменении текста всем слушателям (listeners) поля ввода.

Для помещения текста в область виджета, помимо метода setText, можно воспользоваться функцией void TextEditor::insertTextAtCaret(const String textToInsert), которая вставляет текст textToInsert на текущей позиции курсора. В случае, если какой-то участок текста был выделен, то при вызове функции он заменяется на строку-параметр. Этим можно воспользоваться для программного удаления какого-либо участка текста: вызвать вначале функцию-член void TextEditor::setHighlightedRegion(const Range< int > newSelection), чтобы выделить участок текста, а затем — метод insertTextAtCaret с путой строкой (String::empty) в качестве параметра.

Как правило, нажатие пользователем клавиши <ENTER> на клавиатуре означает завершение ввода строки и переход на новую. Однако в некоторых случаях требуется иная реакция на нажатие этой клавиши. С помощью функции void TextEditor::setReturnKeyStartsNewLine(bool shouldStartNewLine) можно изменить поведение текстового поля ввода на нажатие клавиши <ENTER>. Если параметр shouldStartNewLine принимает значение false, то нажатие на клавишу не приводит к переходу на новую строку, а сообщение об этом событии будет обработано в слушателе поля ввода (TextEditor::Listener). В случае, если поле ввода является однострочным, метод setReturnKeyStartsNewLine можно не вызывать.

Вызов метода void TextEditor::setReadOnly(bool shouldBeReadOnly) с параметром true устанавливает режим, который даёт возможность только просмотра текста, но не редактирования его пользователем. В случае необходимости изменить текст, его можно передать виджет программно, например, функцией setText.

В случае, если объект класса TextEditor используется как однострочное поле ввода, можно включить режим ввода пароля. Этот режим устанавливается в конструкторе компонента TextEditor::TextEditor(const String componentName = String::empty, juce_wchar passwordCharacter = 0). В случае, если второй параметр принимает значение, отличное от нуля, то все вводимые пользователем символы будут замещаться каким-либо другим. Параметр passwordCharacter, собственно, и содержит код замещающего символа. Подробнее с использованием TextEditor в качестве поля ввода пароля можно познакомиться на примере, приведённом ниже.

В случае, если вы используете объект класса TextEditor в качестве многострочного поля ввода, отображаемый текст может превышать размеры виджета. При этом просмотр текста возможен с помощью полос прокрутки. Для их автоматического отображения необходимо вызвать метод void TextEditor::setScrollbarsShown(bool shouldBeEnabled) с параметром true. Если толщина полос прокрутки по умолчанию вас по каким-либо причинам не устраивает, её можно задать программно вызовом функции void TextEditor::setScrollBarThickness(int newThicknessPixels), где параметр — толщина используемых полос прокрутки в пикселях.

Класс TextEditor включает ряд методов для работы с буфером обмена:

Зачастую возникает ситуация, когда необходимо разрешить пользователю ввод только определённого набора символов (шаблон или маска ввода). Задать маску ввода можно вызовом метода void TextEditor::setInputRestrictions(int maxTextLength, const String allowedCharacters = String::empty), где maxTextLength — максимально допустимая длина вводимого текста (в символах), а allowedCharacters — строка, содержащая допустимые символы. В случае, если первый параметр принимает значение 0, ограничений на длину ввода нет. Подробнее с использованием маски ввода можно познакомиться на примере, приведённом ниже.

Рассмотрим использование компонентов Label и TextEditor на примере программы, внешний вид которой показан на рисунке 8.1 .

Окно программы разделено на три секции. В качестве разделителей используются два объекта класса ).

// Создание ярлыка, надпись которого содержит пустую строку
pSeparator = new Label("Separator", String::empty);
// Запрет на редактирование
pSeparator->setEditable(false, false, false);
// Задаём цвет контура ярлыка
pSeparator->setColour(Label::backgroundColourId, Colour(0x3d000000));
addAndMakeVisible(pSeparator);

// Реализация метода TCentralComponent::resize();
// Высота виджета — 1 пиксель
pSeparator->setBounds(8, 136, 704, 1);

Первая секция нашей программы будет содержать многострочное поле ввода без возможности непосредственного редактирования текста пользователем (только чтение), TextEditor* pTextEditor; однострочное поле, TextEditor* pAppendTextEdit, для ввода пользователем текста, который будет добавляться в TextEditor после нажатия на кнопку, а также сами кнопки:

#include "TCentralComponent.h"
//----------------------------------------------------
#define tr(s) String::fromUTF8(s)
//----------------------------------------------------
TCentralComponent::TCentralComponent() : Component("Central Component"),
            pTextEditor(0),
            pAppendTextEdit(0),
            pFontSelectionBox(0),
            pClearButton(0),
            pAppendTextButton(0),
            pSetTextButton(0),
            pSeparator(0),
            pLabel(0),
            pLabelGroup(0),
            pReadOnlyButton(0),
            pEditByOneClickButton(0),
            pEditByDoubleClickButton(0),
            pSeparator1(0)
{
  // Создаём новое поле ввода (текстовый редактор)
  pTextEditor = new TextEditor("TextEditor");
  // Разрешаем ввод более одной строки
  // и разрешаем автоматический перенос строк
  pTextEditor->setMultiLine(true, true);
  // Запрет на редактирование
  pTextEditor->setReadOnly(true);
  // Показываем полосы прокрутки
  pTextEditor->setScrollbarsShown(true);
  addAndMakeVisible(pTextEditor);

  // Шрифт для ранее созданного поля ввода
  Font TextEditorFont;
  // Гарнитура - шрифт Sans-Serif по умолчанию
  TextEditorFont.setTypefaceName(Font::getDefaultSerifFontName());
  TextEditorFont.setHeight(20);
  // Устанавливаем шрифт TextEditorFont в качестве
  // шрифта поля ввода
  pTextEditor->setFont(TextEditorFont);
  pTextEditor->setTextToShowWhenEmpty("Text Editor", Colours::grey);

  // Создаём поле ввода для текста, добавляемого
  // в многострочное поле pTextEditor
  pAppendTextEdit = new TextEditor("AppendTextEdit");
  // Ввод текста - в одну строку
  pAppendTextEdit->setMultiLine(false);
  // Разрешаем ввод текста
  pAppendTextEdit->setReadOnly(false);
  // Показываем полосы прокрутки
  pAppendTextEdit->setScrollbarsShown(false);
  // Делаем видимым курсор
  pAppendTextEdit->setCaretVisible(true);
  // Разрешаем стандартное контекстное меню
  pAppendTextEdit->setPopupMenuEnabled(true);
  // Текст поля - пустая строка
  pAppendTextEdit->setText(String::empty);
  addAndMakeVisible(pAppendTextEdit);

  // Выпадающий список выбора шрифта
  pFontSelectionBox = new ComboBox("FontSelectionBox");
  pFontSelectionBox->setEditableText(false);
  pFontSelectionBox->setJustificationType(Justification::centredLeft);
  pFontSelectionBox->setTextWhenNothingSelected(tr("Выбрать"));
  // Устанавливаем в качестве слушателя выпадающего списка
  // сам компонент-контейнер
  pFontSelectionBox->addListener(this);
  addAndMakeVisible(pFontSelectionBox);

  // Получаем имена системных шрифтов, сохраняем их 
  // в строковом массиве...
  StringArray sSystemFonts = Font::findAllTypefaceNames();
  // и добавляем в выпадающий список
  for(int i = 0; i < sSystemFonts.size(); i++)
  {
    pFontSelectionBox->addItem(sSystemFonts[i], i + 1);
  }

  // Кнопка, очищающая поле pTextEditor
  pClearButton = new TextButton("ClearButton");
  pClearButton->setButtonText(tr("Очистить"));
  // Устанавливаем в качестве слушателя кнопки
  // сам компонент-контейнер
  pClearButton->addListener(this);
  addAndMakeVisible(pClearButton);

  // Кнопка, добавляющая текст в поле pTextEditor
  pAppendTextButton = new TextButton("AppendTextButton");
  pAppendTextButton->setButtonText(tr("Добавить текст"));
  pAppendTextButton->addListener(this);
  addAndMakeVisible(pAppendTextButton);

  // Кнопка, замещающая текст в поле pTextEditor
  pSetTextButton = new TextButton("SetTextButton");
  pSetTextButton->setButtonText(tr("Заменить текст"));
  pSetTextButton->addListener(this);
  addAndMakeVisible(pSetTextButton);