Работа с API КОМПАС-3D → Урок 4 → Основная надпись

Продолжаем цикл статей по работе с API САПР КОМПАС-3D Сергея Норсеева, инженера-программиста АО «ВНИИ «Сигнал», автора книги «Разработка приложений под КОМПАС в Delphi». В качестве среды используется C++ Builder. В предыдущих уроках по API КОМПАС Основы и Оформление чертежа мы исходили из того, что КОМПАС не запущен, и запускали его сами методом CreateInstance. В следующем уроке Корректное подключение к КОМПАС мы проверяли наличие уже запущенного КОМПАСа и подключались к нему. В этом уроке разберём, как заполнить основную надпись чертежа.



Основная надпись в КОМПАС описывается интерфейсом ksStamp. Для получения указателя на него используются методы GetStamp() и GetStampEx() интерфейсов ksDocument2D, ksSpcDocument и ksDocumentTxt.

Единственным параметром метода GetStampEx является номер листа, для которого запрашивается интерфейс основной надписи. Нумерация листов начинается с единицы. Метод GetStamp не имеет параметров. Он возвращает интерфейс основной надписи для первого листа чертежа или спецификации.

Прежде чем перейти к рассмотрению интерфейса ksStamp, бегло рассмотрим интерфейс ksTextItemParam.

Компонента строки

Интерфейс ksTextItemParam задает компоненту строки текста. Под «компонентой» понимается строка или спецсимвол. Получить этот интерфейс можно с помощью метода GetParamStruct интерфейса KompasObject. Для этого в качестве единственного параметра данному методу нужно передать константу ko_TextItemParam.
Свойств у интерфейса ksTextItemParam всего три.

• iSNumb – код спецсимвола. Спецсимволы и их номера приведены в файле NumbSymb.frw, входящем в комплект поставки КОМПАС. Он расположен в подкаталоге SDK основного каталога программы КОМПАС.
• s – строка. Если интерфейс ksTextItemParam используется для описания спецсимвола, то данная строка выводится после спецсимвола.
• type – задает назначение интерфейса. Если значение этого свойства равно SPECIAL_SYMBOL, то интерфейс описывает спецсимвол и строку. При этом строка располагается сразу за спецсимволом. Если же значение этого свойства отлично от SPECIAL_SYMBOL, то значение свойства iSNumb игнорируется, а интерфейс описывает только строку s. Учтите, что в заголовочных файлах старых версий КОМПАС данное свойство называется type_ (со знаком подчеркивания), а константа SPECIAL_SYMBOL не определена. Она равна 17.

В документации КОМПАС-3D v17 интерфейс ksTextItemParam описан в рубрике «Текстовый документ (Интерфейс ksDocumentTxt) / ksDocumentTxt – методы / Интерфейсы параметров элементов текста /».


Описание интерфейсов параметров элементов текста в SDK

Но при описании свойства type константа SPECIAL_SYMBOL не упоминается. Она приводится (правда без числового значения) в разделе «Структуры параметров и константы / Структуры параметров текста / TextItemParam – структура параметров компоненты текста».


Описание структуры параметров компоненты строки текста в SDK

Там же приводятся еще три возможных значения свойства type (FONT_SYMBOL, FRACTION_TYPE, SUM_TYPE), но их назначение я так и не понял. Как показали эксперименты, поведение интерфейса ksTextItemParam при данных константах ничем не отличается от нулевого значения свойства type. Правда я тестировал в контексте основной надписи, возможно, что это накладывает какие-то свои ограничения.
Теперь рассмотрим методы интерфейса ksTextItemParam.

• GetItemFont() – возвращает интерфейс параметров шрифта ksTextItemFont.
• SetItemFont – устанавливает новый интерфейс параметров шрифта ksTextItemFont. Устанавливаемый интерфейс передается в качестве значения единственного параметра. В случае успеха метод возвращает значение true.
• Init() – инициализирует нулями свойства интерфейса. В случае успеха возвращает значение true.

Основная надпись

Как говорилось выше, основная надпись описывается интерфейсом ksStamp. У данного интерфейса нет интересных свойств, поэтому сразу переходим к рассмотрению его методов.

• ksClearStamp – очищает основную надпись или ее отдельную ячейку. Единственным параметром данного метода является номер очищаемой ячейки. Если его значение равно нулю, то очищается вся основная надпись. В случае успеха данный метод возвращает единицу, а в случае ошибки — нуль.
• ksCloseStamp() – закрыть основную надпись. Это означает выйти из режима редактирования основной надписи. В случае успеха возвращает единицу, а в случае ошибки – нуль.
• ksColumnNumber – делает текущей заданную ячейку. В качестве единственного параметра в данный метод передается номер ячейки, которая делается текущей. В случае успеха данный метод возвращает единицу, а в случае ошибки — нуль.
• ksOpenStamp() – открыть основную надпись. Это означает войти в режим редактирования основной надписи. Не имеет входных параметров, в случае успеха возвращает единицу, а в случае ошибки — нуль.
• ksTextLine – записать строку в текущую ячейку. Текущая ячейка должна быть установлена методом ksColumnNumber. Единственным параметром метода ksTextLine является указатель на интерфейс ksTextItemParam, о котором я говорил чуть выше. В случае успеха метод ksTextLine возвращает единицу, а в случае ошибки — нуль.

Это неполный перечень методов интерфейса ksStamp, но их вполне достаточно для работы с основной надписью. Тем не менее, нужно сделать ряд замечаний.

1. Все ячейки основной надписи пронумерованы. В документации КОМПАС данных номеров нет, но есть отсылка к ГОСТам на основную надпись (ГОСТ 2.104-68 и ГОСТ 2.104-2006). Также нумерацию ячеек основной надписи можно посмотреть на странице. На рисунках ниже представлены номера ячеек основной надписи форм 2а и 2б, полученные экспериментальным путем.
   
   
   
   Первый лист
   
   
   
   Второй и последующие листы
   
2. Метод ksTextLine — не единственный способ записи строк в основную надпись. Помимо него у интерфейса ksStamp есть метод ksSetStampColumnText, который делает то же самое. Единственное отличие состоит в том, что в нем устанавливаемая строка задается не в виде интерфейса ksTextItemParam, а в виде динамического массива ksDynamicArray. В данной статье мы не будем его рассматривать.

Редактирование основной надписи

Заполнение основной надписи состоит из нескольких последовательных этапов:

1. Получить указатель на интерфейс ksTextItemParam. Для этого используется метод GetParamStruct интерфейса ksKompasObject. Интерфейс ksTextItemParam нужен для представления строк, записываемых в основную надпись.
2. Получить указатель на интерфейс основной надписи ksStamp с помощью методов GetStamp или GetStampEx интерфейсов документа, спецификации.
3. Вызвать метод ksOpenStamp() интерфейса ksStamp. Так мы входим в режим редактирования основной надписи.
4. Подготовить строку, которая будет записана в ячейку основной надписи. Строка должна быть представлена в виде интерфейса ksTextItemParam.
5. Выделить ячейку, в которую нужно записать строку. Для выделения ячейки используется метод ksColumnNumber интерфейса ksStamp.
6. Вызвав метод ksTextLine интерфейса ksStamp, записать строку в выделенную ячейку.
7. Повторить пункты 4-6 для всех строк, записываемых в основную надпись.
8. Закрыть основную надпись методом ksCloseStamp интерфейса ksStamp.

Пример

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

//Получаем интерфейс представления строк
TextItemParamPtr TextItemParam;
TextItemParam = (TextItemParamPtr)kompas->GetParamStruct(ko_TextItemParam);

//Получаем интерфейс основной надписи
StampPtr Stamp;
Stamp = (StampPtr)Document2D->GetStamp();
//Открываем основную надпись
Stamp->ksOpenStamp();

Stamp->ksColumnNumber(1);
TextItemParam->s = SysAllocString(L"Деталь");
Stamp->ksTextLine(TextItemParam);

Stamp->ksColumnNumber(3);
TextItemParam->s = SysAllocString(L"");
TextItemParam->type = SPECIAL_SYMBOL;
TextItemParam->iSNumb = 51;
Stamp->ksTextLine(TextItemParam);

Stamp->ksColumnNumber(110);
TextItemParam->set_s(SysAllocString(L"Норсеев С.А."));
TextItemParam->type = 0;
Stamp->ksTextLine(TextItemParam);

//Закрываем основную надпись
Stamp->ksCloseStamp();

В результате работы этой программы вы увидите основную надпись, показанную на рисунке ниже.


Основная надпись, полученная программно.

Сделаю два замечания по поводу приведенного выше фрагмента программы.

1. В данном примере не приводится код, ответственный за подключение к КОМПАС и создание чертежа. Я убрал его для облегчения понимания кода. О том, как подключаться к КОМПАС и настраивать чертеж (в том числе выбирать формат основной надписи в нем), говорилось в предыдущих статьях цикла.
2. Если внимательно посмотреть на приведенный выше код, то можно увидеть, что в одном случае строка устанавливалась в интерфейсе ksTextItemParam путем присвоения значения свойству s, а в другом — путем вызова метода set_s, про который я ничего не говорил. Дело в том, что в технологии COM все свойства представляются в виде методов (как правило, установки и чтения). Наименование этих методов формируется следующим образом:
   get_<имя свойства>
   set_<имя свойства>
   В своих программах вы можете использовать любой из этих подходов (присвоение значения свойству или же вызов соответствующего метода).

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

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

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