Работа с API КОМПАС-3D → Урок 14 → Многострочный текст

На предыдущем уроке мы рассмотрели, как выводить многострочный текст с помощью параграфа. Описанный способ требует ручного обхода массива выводимых строк. На данном уроке мы рассмотрим альтернативный способ, лишенный этого недостатка. В его основе лежит интерфейс ksTextParam и метод ksTextEx.

Содержание цикла уроков «Работа с API КОМПАС-3D»

1. Основы
2. Оформление чертежа
3. Корректное подключение к КОМПАС
4. Основная надпись
5. Графические примитивы
6. Сохранение документа в различные форматы
7. Знакомство с настройками
8. Более сложные методы записи в основную надпись
9. Чтение ячеек основной надписи
10. Спецсимволы, включающие строку
11. Простые текстовые надписи
12. Составные строки
13. Параграфы
14. Многострочный текст

Параметры текста (ksTextParam)

Интерфейс ksTextParam представляет собой надстройку над интерфейсом ksParagraphParam и массивом выводимых строк. Для его получения нужно вызвать метод GetParamStruct интерфейса KompasObject с константой ko_TextParam.
Свойств у интерфейса ksTextParam нет, поэтому сразу переходим к рассмотрению его методов.
GetParagraphParam() – возвращает интерфейс параметров параграфа ksParagraphParam. Не имеет входных параметров.
GetTextLineArr() – возвращает динамический массив ksDynamicArray выводимых строк. Не имеет входных параметров.
Init() – сбрасывает параметры текста. Не имеет входных параметров. В случае успеха возвращает значение true.
SetParagraphParam – устанавливает параметры параграфа. В качестве единственного параметра принимает интерфейс ksParagraphParam, содержащий устанавливаемые параметры. В случае успеха возвращает значение true, а в случае ошибки – false.
SetTextLineArr – устанавливает массив выводимых строк. В качестве единственного параметра принимает интерфейс ksDynamicArray, содержащий выводимые строки. В случае успеха возвращает значение true, а в случае ошибки – false.
Динамический массив, возвращаемый методом GetTextLineArr() и устанавливаемый методом SetTextLineArr, имеет тип TEXT_LINE_ARR. Это значит, что элементами массива являются интерфейсы ksTextLineParam.

Метод ksTextEx

Для вывода многострочного текста используется метод ksTextEx интерфейса ksDocument2D. Ниже представлен его прототип:

long ksTextEx (
LPDISPATCH txtParam,	// Интерфейс ksTextParam
long align		// Выравнивание текста
);

В таблице ниже представлены допустимые значения параметра align.



В случае успеха метод ksTextEx возвращает целочисленный указатель на созданный текст. А в случае ошибки – ноль.

Пример

Ниже приводится фрагмент программы, демонстрирующей вывод многострочного текста с помощью метода ksTextEx.

//Подготавливаем массивы
DynamicArrayPtr items;
items = static_cast<DynamicArrayPtr>(kompas->GetDynamicArray(TEXT_ITEM_ARR));
items->ksClearArray();
DynamicArrayPtr lines;
lines = static_cast<DynamicArrayPtr>(kompas->GetDynamicArray(TEXT_LINE_ARR));
lines->ksClearArray();

//Подготлавиваем другие интерфейсы
TextLineParamPtr lineParam;
lineParam = static_cast<TextLineParamPtr>(kompas->GetParamStruct(ko_TextLineParam));
lineParam->Init();

TextItemParamPtr itemParam;
itemParam = static_cast<TextItemParamPtr>(kompas->GetParamStruct(ko_TextItemParam));
itemParam->Init();

TextItemFontPtr itemFont = static_cast<TextItemFontPtr>(itemParam->GetItemFont());

//Наполняем массив строк
BSTR str = SysAllocString(OLESTR("Обычный текст"));
itemParam->set_s(str);
items->ksAddArrayItem(-1, itemParam);
lineParam->SetTextItemArr(items);
lines->ksAddArrayItem(-1, lineParam);
lineParam->Init();
SysFreeString(str);
str = NULL;

itemFont->set_bitVector(NEW_LINE | ITALIC_OFF);
str = SysAllocString(OLESTR("Текст без наклона"));
itemParam->set_s(str);
items->ksAddArrayItem(-1, itemParam);
lineParam->SetTextItemArr(items);
lines->ksAddArrayItem(-1, lineParam);
lineParam->Init();
SysFreeString(str);
str = NULL;

itemFont->set_bitVector(NEW_LINE | ITALIC_ON | BOLD_ON);
str = SysAllocString(OLESTR("Полужирный текст"));
itemParam->set_s(str);
items->ksAddArrayItem(-1, itemParam);
lineParam->SetTextItemArr(items);
lines->ksAddArrayItem(-1, lineParam);
lineParam->Init();
SysFreeString(str);
str = NULL;

itemFont->set_bitVector(NEW_LINE | BOLD_OFF | UNDERLINE_ON);
str = SysAllocString(OLESTR("Подчеркнутый текст"));
itemParam->set_s(str);
items->ksAddArrayItem(-1, itemParam);
lineParam->SetTextItemArr(items);
lines->ksAddArrayItem(-1, lineParam);
lineParam->Init();
SysFreeString(str);
str = NULL;

itemParam.Unbind();
lineParam.Unbind();
itemFont.Unbind();
items.Unbind();

//Подготавливаем интерфейс параметров параграфа
ParagraphParamPtr paragraphParam;
paragraphParam= static_cast<ParagraphParamPtr>(kompas->GetParamStruct(ko_ParagraphParam));

paragraphParam->Init();
paragraphParam->set_x(100.0);
paragraphParam->set_y(100.0);
paragraphParam->set_width(60.0);
paragraphParam->set_hFormat(2);

//Подготавливаем интерфейс параметров текста
TextParamPtr textParam = static_cast<TextParamPtr>(kompas->GetParamStruct(ko_TextParam));
textParam->SetParagraphParam(paragraphParam);
textParam->SetTextLineArr(lines);

//Выводим текст
Document2D->ksTextEx(textParam, 1);

lines->ksDeleteArray();
lines.Unbind();
paragraphParam.Unbind();
textParam.Unbind();

//Делаем КОМПАС видимым
kompas->set_Visible(true);
kompas.Unbind();

В данном примере мы не обходим массив, а однократно вызываем нужный метод. Он сам находит флаги NEW_LINE и правильно интерпретирует их. Обратите внимание: каждая новая строка с этим флагом оформляется в отдельный интерфейс ksTextLineParam. Если оформить их в одном ksTextLineParam, то КОМПАС проигнорирует флаг NEW_LINE. На рисунке ниже показан результат работы этой программы.



Заключение

На этом уроке мы рассмотрели альтернативный вариант вывода многострочного текста. Он несколько сложнее того, что мы рассмотрели ранее, но не требует ручного обхода массива строк. Каким из них пользоваться – решать вам.

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

Продолжение следует, следите за новостями блога.

Сергей Норсеев, к.т.н., автор книги «Разработка приложений под КОМПАС в Delphi».