На предыдущих уроках цикла мы научились выводить текст в основную надпись. Сегодня поговорим о том, как выводить текст в сам документ. Мы рассмотрим простейшие примеры, а более сложные приемы покажем на следующих уроках.
Текст в КОМПАСе всегда выводится относительно некоторой точки, которую называют точкой привязки. Текст может по-разному располагаться относительно нее. Для того, чтобы узнать расположение текста относительно точки привязки, используется метод ksGetTextAlign интерфейса ksDocument2D. Ниже приводится его прототип.
В качестве единственного параметра он принимает целочисленный указатель на объект «текст». Метод возвращает тип привязки, или -1 в случае ошибки. Допустимые типы привязок приведены в таблице ниже.
Таблица допустимых типов привязок
Для изменения привязки текста используется метод ksSetTextAlign интерфейса ksDocument2D. Ниже приводится его прототип.
В случае успеха данный метод возвращает значение 1, а в случае ошибки – ноль.
Для простого вывода текста используется метод ksText интерфейса ksDocument2D. Ниже приводится прототип данного метода.
Разберем параметры метода ksText. Точку привязки мы обсуждали в предыдущем разделе.
Параметр ang задает угол в градусах между строкой текста и горизонтальной линией. Угол отсчитывается против часовой стрелки. На рисунке ниже показана строка, выведенная под углом 45°.
Строка, выведенная под углом 45°
Параметр hStr задает размер символов строки в миллиметрах. Если значение этого параметра равно нулю, то используется размер по умолчанию.
Параметр ksuStr задает растяжение (сужение) текста. На рисунке ниже приведено несколько строк с различным значением параметра ksuStr.
Несколько строк с различным значением растяжения
Из этого рисунка можно увидеть, что «растяжение 0» эквивалентно «растяжению 1», то есть отсутствию какого-либо растяжения.
Параметр bitVector содержит набор флагов, определяющих начертание символов. Допустимые флаги перечислены в таблице ниже.
Таблица флагов, определяющих начертание символов
На самом деле, существуют и другие допустимые флаги, но их работа проявляется только при конструировании сложных составных строк. Часть из них мы рассмотрим на следующем уроке.
Помните – выводимая строка не должна содержать символы @, $, &, ~, ^ и #, так как они являются управляющими символами. О работе с ними мы поговорим на следующих уроках нашего цикла.
В случае успеха метод ksText возвращает целочисленный указатель на текст. Этот указатель может быть передан, например, в метод ksSetTextAlign для изменения расположения текста относительно точки привязки. В случае ошибки метод ksText возвращает ноль.
Ниже приводится пример программы, демонстрирующей вывод строки с использованием метода ksText.
Для простоты в данном примере опущен код, ответственный за создание и оформление документа. В результате работы этой программы в документ выводится текстовая надпись «Строка».
При выводе текста в документ полезно знать, сколько места он занимает. Высота текста задается параметром hStr метода ksText. А вот его длина напрямую зависит от выводимой строки.
Для ее определения используется метод ksGetTextLengthFromReference интерфейса ksDocument2D. У этого метода всего один параметр – целочисленный указатель на текст. Он возвращает длину текста в миллиметрах.
Метод ksGetTextLengthFromReference неудобен тем, что он не позволяет определить длину строки до ее вывода в документ. Для определения длины строки, которая еще не выведена в документ, нужно использовать метод ksGetTextLength. Но прежде чем рассматривать его, поговорим о стилях.
Система КОМПАС предопределяет несколько стилей для текстов, выводимых в документах. Каждому стилю соответствует целое число. Наиболее часто используемые стили – в таблице ниже.
Наиболее часто используемые стили текста
В данной таблице приведены не все стили: только их часть. С полным перечнем доступных констант можно ознакомиться на странице «Структуры параметров и константы\Константы\Константы текста\Системные стили текста» документации КОМПАС.
Метод ksGetTextLength интерфейса ksDocument2D позволяет определить длину строки до ее вывода в документ. Ниже – прототип этого метода.
Метод возвращает длину строки в миллиметрах. Обратите внимание: метод в качестве параметра принимает саму строку, а не указатель на объект «текст». Это позволяет оценивать размер строки до того, как она будет выведена в документ.
Рассмотрим пример использования метода ksGetTextLength. Допустим, у нас есть строка и ее нужно разместить в прямоугольнике определенной длины (данная задача гораздо проще решается с помощью параграфов, но о них – в следующих уроках). Если строка умещается в нём, то она выводится полностью. Если нет, то она обрезается и в конце нее ставится многоточие. Ниже приводится исходный код программы, решающий такую задачу.
Исходная строка задается в константе FULLSTR. Переменная maxSize задает длину прямоугольника, в который нужно вписать строку. Позже это значение уточняется, из него вычитается размер многоточия, который сохраняется в переменной size_dots. Если строка не умещается, от нее отсекается по одному символу до тех пор, пока она не уместится в прямоугольнике заданного размера. Это происходит в цикле while.
Обратите внимание на очень важный момент: при выводе строки все параметры метода ksText (кроме координат точки привязки) имеют нулевое значение. Дело в том, что метод ksGetTextLength ничего не знает об этих параметрах, поэтому не может учитывать их при расчете длины строки. Таким образом, если при выводе строки используются ненулевые значения параметров метода ksText, то результирующая длина строки может отличаться от той, что была получена методом ksGetTextLength.
Заключение
На этом уроке мы научились выводить простые текстовые надписи с помощью метода ksText. Это не единственный способ вывода текста, но, пожалуй, самый простой. На следующем уроке мы рассмотрим, как с помощью этого метода можно выводить сложные составные строки. А на последующих рассмотрим и более сложные методы вывода текста.
Продолжение следует, следите за новостями блога.
Сергей Норсеев, к.т.н., автор книги «Разработка приложений под КОМПАС в Delphi».
Содержание цикла уроков «Работа с API КОМПАС-3D»
Точка привязки текста
Текст в КОМПАСе всегда выводится относительно некоторой точки, которую называют точкой привязки. Текст может по-разному располагаться относительно нее. Для того, чтобы узнать расположение текста относительно точки привязки, используется метод ksGetTextAlign интерфейса ksDocument2D. Ниже приводится его прототип.
long ksGetTextAlign (
long pText //Указатель на текст
);
В качестве единственного параметра он принимает целочисленный указатель на объект «текст». Метод возвращает тип привязки, или -1 в случае ошибки. Допустимые типы привязок приведены в таблице ниже.
Таблица допустимых типов привязок
Для изменения привязки текста используется метод ksSetTextAlign интерфейса ksDocument2D. Ниже приводится его прототип.
long ksSetTextAlign (
long pText, //Указатель на объект «текст»
long align //Тип привязки
);
В случае успеха данный метод возвращает значение 1, а в случае ошибки – ноль.
Вывод текста
Для простого вывода текста используется метод ksText интерфейса ksDocument2D. Ниже приводится прототип данного метода.
long ksText (
double x, //Координаты точки привязки
double y,
double ang, //Угол наклона текста
double hStr, //Высота символов в миллиметрах
double ksuStr, //Растяжение текста
long bitVector, //Признаки начертания
BSTR s //Выводимая строка
);
Разберем параметры метода ksText. Точку привязки мы обсуждали в предыдущем разделе.
Параметр ang задает угол в градусах между строкой текста и горизонтальной линией. Угол отсчитывается против часовой стрелки. На рисунке ниже показана строка, выведенная под углом 45°.
Строка, выведенная под углом 45°
Параметр hStr задает размер символов строки в миллиметрах. Если значение этого параметра равно нулю, то используется размер по умолчанию.
Параметр ksuStr задает растяжение (сужение) текста. На рисунке ниже приведено несколько строк с различным значением параметра ksuStr.
Несколько строк с различным значением растяжения
Из этого рисунка можно увидеть, что «растяжение 0» эквивалентно «растяжению 1», то есть отсутствию какого-либо растяжения.
Параметр bitVector содержит набор флагов, определяющих начертание символов. Допустимые флаги перечислены в таблице ниже.
Таблица флагов, определяющих начертание символов
На самом деле, существуют и другие допустимые флаги, но их работа проявляется только при конструировании сложных составных строк. Часть из них мы рассмотрим на следующем уроке.
Помните – выводимая строка не должна содержать символы @, $, &, ~, ^ и #, так как они являются управляющими символами. О работе с ними мы поговорим на следующих уроках нашего цикла.
В случае успеха метод ksText возвращает целочисленный указатель на текст. Этот указатель может быть передан, например, в метод ksSetTextAlign для изменения расположения текста относительно точки привязки. В случае ошибки метод ksText возвращает ноль.
Пример
Ниже приводится пример программы, демонстрирующей вывод строки с использованием метода ksText.
//Выводим строку
BSTR str = SysAllocString(L"Строка");
long itext;
itext = Document2D->ksText(100, 100, //Точка привязки
0, //Угол наклона
11, //Высота символов
0, //Растяжение
0, //Признак начертания
str);
SysFreeString(str);
//Маняем расположение точки привязки
Document2D->ksSetTextAlign(itext, txta_Left);
Document2D.Unbind();
//Делаем КОМПАС видимым
kompas->Visible = true;
kompas.Unbind();
Для простоты в данном примере опущен код, ответственный за создание и оформление документа. В результате работы этой программы в документ выводится текстовая надпись «Строка».
Размер текста
При выводе текста в документ полезно знать, сколько места он занимает. Высота текста задается параметром hStr метода ksText. А вот его длина напрямую зависит от выводимой строки.
Для ее определения используется метод ksGetTextLengthFromReference интерфейса ksDocument2D. У этого метода всего один параметр – целочисленный указатель на текст. Он возвращает длину текста в миллиметрах.
Метод ksGetTextLengthFromReference неудобен тем, что он не позволяет определить длину строки до ее вывода в документ. Для определения длины строки, которая еще не выведена в документ, нужно использовать метод ksGetTextLength. Но прежде чем рассматривать его, поговорим о стилях.
Стили текста
Система КОМПАС предопределяет несколько стилей для текстов, выводимых в документах. Каждому стилю соответствует целое число. Наиболее часто используемые стили – в таблице ниже.
Наиболее часто используемые стили текста
В данной таблице приведены не все стили: только их часть. С полным перечнем доступных констант можно ознакомиться на странице «Структуры параметров и константы\Константы\Константы текста\Системные стили текста» документации КОМПАС.
Метод ksGetTextLength
Метод ksGetTextLength интерфейса ksDocument2D позволяет определить длину строки до ее вывода в документ. Ниже – прототип этого метода.
double ksGetTextLength (
BSTR text, //Строка
long style //Стиль текста
);
Метод возвращает длину строки в миллиметрах. Обратите внимание: метод в качестве параметра принимает саму строку, а не указатель на объект «текст». Это позволяет оценивать размер строки до того, как она будет выведена в документ.
Пример
Рассмотрим пример использования метода ksGetTextLength. Допустим, у нас есть строка и ее нужно разместить в прямоугольнике определенной длины (данная задача гораздо проще решается с помощью параграфов, но о них – в следующих уроках). Если строка умещается в нём, то она выводится полностью. Если нет, то она обрезается и в конце нее ставится многоточие. Ниже приводится исходный код программы, решающий такую задачу.
const wchar_t FULLSTR[] = L"Очень длинная строка! Очень длинная строка! Очень длинная строка!";
const wchar_t DOTS[] = L"...";
const long STYLE = 1;
double maxSize = 100.0;
BSTR str = SysAllocString(FULLSTR);
if(Document2D->ksGetTextLength(str, STYLE) > maxSize)
{
//Определяем размер многоточия
BSTR str_dots = SysAllocString(DOTS);
double size_dots = Document2D->ksGetTextLength(str_dots, STYLE);
SysFreeString(str_dots);
//Пересчитываем максимальный размер без многоточия
maxSize -= size_dots;
SysReAllocStringLen(&str, str, SysStringLen(str) - 4);
//Обрезаем строку, пока она не уместится
while(Document2D->ksGetTextLength(str, STYLE) > maxSize)
SysReAllocStringLen(&str, str, SysStringLen(str) - 1);
//Определяем количество уместившихся символов
size_t len = SysStringLen(str);
SysFreeString(str);
//Формируем итоговую строку с многоточием
wchar_t *p = new wchar_t[len + wcslen(DOTS) + 1];
wcsncpy(p, FULLSTR, len);
p[len] = L'\0';
wcscat(p, DOTS);
str = SysAllocString(p);
delete [] p;
}
//Выводим строку в документ
Document2D->ksText(100, 100, //Точка привязки
0, //Угол наклона
0, //Высота символов
0, //Растяжение
0, //Признак начертания
str);
//Освобождаем ресурсы
SysFreeString(str);
Document2D.Unbind();
//Делаем КОМПАС видимым
kompas->Visible = true;
kompas.Unbind();
Исходная строка задается в константе FULLSTR. Переменная maxSize задает длину прямоугольника, в который нужно вписать строку. Позже это значение уточняется, из него вычитается размер многоточия, который сохраняется в переменной size_dots. Если строка не умещается, от нее отсекается по одному символу до тех пор, пока она не уместится в прямоугольнике заданного размера. Это происходит в цикле while.
Обратите внимание на очень важный момент: при выводе строки все параметры метода ksText (кроме координат точки привязки) имеют нулевое значение. Дело в том, что метод ksGetTextLength ничего не знает об этих параметрах, поэтому не может учитывать их при расчете длины строки. Таким образом, если при выводе строки используются ненулевые значения параметров метода ksText, то результирующая длина строки может отличаться от той, что была получена методом ksGetTextLength.
Заключение
На этом уроке мы научились выводить простые текстовые надписи с помощью метода ksText. Это не единственный способ вывода текста, но, пожалуй, самый простой. На следующем уроке мы рассмотрим, как с помощью этого метода можно выводить сложные составные строки. А на последующих рассмотрим и более сложные методы вывода текста.
Продолжение следует, следите за новостями блога.
Сергей Норсеев, к.т.н., автор книги «Разработка приложений под КОМПАС в Delphi».