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

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

6bb7ca4780ae4e6296b450fe2481aef6.png

Основная надпись в КОМПАС описывается интерфейсом 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 — методы / Интерфейсы параметров элементов текста /».

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

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

aa9538e111d34ebb9d2376fb9823cd4c.png
Описание структуры параметров компоненты строки текста в 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 б, полученные экспериментальным путем.

    b06f3290baa54be48175a6310291ae8c.png

    Первый лист

    39a43c4fc07d43a7b748525e261c0d7d.png

    Второй и последующие листы

  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();


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

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

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

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


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

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

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

© Habrahabr.ru