Продолжаем цикл статей по работе с 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, но их вполне достаточно для работы с основной надписью. Тем не менее, нужно сделать ряд замечаний.
- Все ячейки основной надписи пронумерованы. В документации КОМПАС данных номеров нет, но есть отсылка к ГОСТам на основную надпись (ГОСТ 2.104-68 и ГОСТ 2.104-2006). Также нумерацию ячеек основной надписи можно посмотреть на странице. На рисунках ниже представлены номера ячеек основной надписи форм 2а и 2б, полученные экспериментальным путем.
Первый лист
Второй и последующие листы
- Метод ksTextLine — не единственный способ записи строк в основную надпись. Помимо него у интерфейса ksStamp есть метод ksSetStampColumnText, который делает то же самое. Единственное отличие состоит в том, что в нем устанавливаемая строка задается не в виде интерфейса ksTextItemParam, а в виде динамического массива ksDynamicArray. В данной статье мы не будем его рассматривать.
Редактирование основной надписи
Заполнение основной надписи состоит из нескольких последовательных этапов:
- Получить указатель на интерфейс ksTextItemParam. Для этого используется метод GetParamStruct интерфейса ksKompasObject. Интерфейс ksTextItemParam нужен для представления строк, записываемых в основную надпись.
- Получить указатель на интерфейс основной надписи ksStamp с помощью методов GetStamp или GetStampEx интерфейсов документа, спецификации.
- Вызвать метод ksOpenStamp() интерфейса ksStamp. Так мы входим в режим редактирования основной надписи.
- Подготовить строку, которая будет записана в ячейку основной надписи. Строка должна быть представлена в виде интерфейса ksTextItemParam.
- Выделить ячейку, в которую нужно записать строку. Для выделения ячейки используется метод ksColumnNumber интерфейса ksStamp.
- Вызвав метод ksTextLine интерфейса ksStamp, записать строку в выделенную ячейку.
- Повторить пункты 4-6 для всех строк, записываемых в основную надпись.
- Закрыть основную надпись методом 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();
В результате работы этой программы вы увидите основную надпись, показанную на рисунке ниже.
Основная надпись, полученная программно.
Сделаю два замечания по поводу приведенного выше фрагмента программы.
- В данном примере не приводится код, ответственный за подключение к КОМПАС и создание чертежа. Я убрал его для облегчения понимания кода. О том, как подключаться к КОМПАС и настраивать чертеж (в том числе выбирать формат основной надписи в нем), говорилось в предыдущих статьях цикла.
- Если внимательно посмотреть на приведенный выше код, то можно увидеть, что в одном случае строка устанавливалась в интерфейсе ksTextItemParam путем присвоения значения свойству s, а в другом — путем вызова метода set_s, про который я ничего не говорил. Дело в том, что в технологии COM все свойства представляются в виде методов (как правило, установки и чтения). Наименование этих методов формируется следующим образом:
get_<имя свойства>
set_<имя свойства>
В своих программах вы можете использовать любой из этих подходов (присвоение значения свойству или же вызов соответствующего метода).
Заключение
В данной статье мы научились заполнять основную надпись и познакомились с одним из интерфейсов для представления строк и спецсимволов. В последующих статьях цикла мы познакомимся и с другими интерфейсами.
Продолжение следует, следите за новостями блога.
Сергей Норсеев, автор книги «Разработка приложений под КОМПАС в Delphi».
Автор: kompas_3d
