Продолжаем цикл статей по работе с API САПР КОМПАС-3D Сергея Норсеева, инженера-программиста АО «ВНИИ «Сигнал», автора книги «Разработка приложений под КОМПАС в Delphi». В качестве среды используется C++ Builder. В предыдущих уроках по API КОМПАС Основы и Оформление чертежа мы исходили из того, что КОМПАС не запущен, и запускали его сами методом CreateInstance. В следующем уроке Корректное подключение к КОМПАС мы проверяли наличие уже запущенного КОМПАСа и подключались к нему. В этом уроке разберём, как заполнить основную надпись чертежа.
Основная надпись в КОМПАС описывается интерфейсом ksStamp. Для получения указателя на него используются методы GetStamp() и GetStampEx() интерфейсов ksDocument2D, ksSpcDocument и ksDocumentTxt.
Единственным параметром метода GetStampEx является номер листа, для которого запрашивается интерфейс основной надписи. Нумерация листов начинается с единицы. Метод GetStamp не имеет параметров. Он возвращает интерфейс основной надписи для первого листа чертежа или спецификации.
Прежде чем перейти к рассмотрению интерфейса ksStamp, бегло рассмотрим интерфейс ksTextItemParam.
Интерфейс ksTextItemParam задает компоненту строки текста. Под «компонентой» понимается строка или спецсимвол. Получить этот интерфейс можно с помощью метода GetParamStruct интерфейса KompasObject. Для этого в качестве единственного параметра данному методу нужно передать константу ko_TextItemParam.
Свойств у интерфейса ksTextItemParam всего три.
В документации КОМПАС-3D v17 интерфейс ksTextItemParam описан в рубрике «Текстовый документ (Интерфейс ksDocumentTxt) / ksDocumentTxt – методы / Интерфейсы параметров элементов текста /».
Описание интерфейсов параметров элементов текста в SDK
Но при описании свойства type константа SPECIAL_SYMBOL не упоминается. Она приводится (правда без числового значения) в разделе «Структуры параметров и константы / Структуры параметров текста / TextItemParam – структура параметров компоненты текста».
Описание структуры параметров компоненты строки текста в SDK
Там же приводятся еще три возможных значения свойства type (FONT_SYMBOL, FRACTION_TYPE, SUM_TYPE), но их назначение я так и не понял. Как показали эксперименты, поведение интерфейса ksTextItemParam при данных константах ничем не отличается от нулевого значения свойства type. Правда я тестировал в контексте основной надписи, возможно, что это накладывает какие-то свои ограничения.
Теперь рассмотрим методы интерфейса ksTextItemParam.
Как говорилось выше, основная надпись описывается интерфейсом ksStamp. У данного интерфейса нет интересных свойств, поэтому сразу переходим к рассмотрению его методов.
Это неполный перечень методов интерфейса ksStamp, но их вполне достаточно для работы с основной надписью. Тем не менее, нужно сделать ряд замечаний.
Заполнение основной надписи состоит из нескольких последовательных этапов:
Ниже приводится фрагмент программы, демонстрирующий работу с основной надписью.
В результате работы этой программы вы увидите основную надпись, показанную на рисунке ниже.
Основная надпись, полученная программно.
Сделаю два замечания по поводу приведенного выше фрагмента программы.
Заключение
В данной статье мы научились заполнять основную надпись и познакомились с одним из интерфейсов для представления строк и спецсимволов. В последующих статьях цикла мы познакомимся и с другими интерфейсами.
Продолжение следует, следите за новостями блога.
Сергей Норсеев, автор книги «Разработка приложений под КОМПАС в Delphi».
Основная надпись в КОМПАС описывается интерфейсом 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». Комментарии (14)
gdt
24.09.2017 08:47+1Спасибо за статью, для студентов самое то будет. Я уже несколько лет (тьфу-тьфу-тьфу) не занимался ничем, что связано с API Компас 3D, в связи с чем вопрос: за последние несколько лет не проводилась ли работа по унификации и стандартизации API? На тот момент, когда в университете писали плагины (2011-2012гг) это было чем-то похоже на PHP в этом плане. В одном месте enum в другом magic numbers, а API 2D и 3D лучше было вообще не сравнивать.
kompas_3d Автор
25.09.2017 11:23API в последнее время серьёзно не менялся — только дополнение новых команд.
sah4ez32
Блин, во время моего обучения такого не было. Была только книга автора и не полностью документированная sdk.
А вот для студента как раз такое изложение самое то, чтобы замотивировать.
А рассматривали вариант описания API на примере какого цельного проекта, где разные этапы реализации затрагивали разные аспекты API?
Автору за статью огромное спасибо! Жду продолжения.
PS
Когда был курсовой (где-то 2012 год) по написанию модуля для какой-то (на выбор) САПР, выбрали не КОМПАС, по причине слабой документации к API.
M_AJ
2.5 года назад я тоже не нашел толковой документации, а по всем вопросам предлагалось обратиться то ли на форум, то ли в группу в ВК. И такая "открытость" как я понял распространённая практика среди российских компаний.
sah4ez32
Соглашусь. И чуток добавлю.
Про работу с ПО других компаний, могу сказать что российские вендоры организовывали обучение по API распространяемым систем.
Кстати насколько мне известно, некоторые из ребят которые проходили такое обучение, были задействованы в разработке CAE системы, очень хорошего качества.
Но создается впечатление что "открытость" документации — это не сильно нужно разработчикам, так как количество людей, которые пишут внешние модули к CAD очень мало. Плюс причесать к нормальному виду API — это наверное проще будет написать "с нуля".
Ну и зачем отнимать хлеб у себя же, если на такой поддержке можно заработать. Это можно аргументировать закостенелостью бизнес-процессов или отсутствием развития бизнеса в этом направлении, но я не сильно сведущий в области ведения бизнеса по продаже и продвижению САПР всякого рода. Хотя как маркетинговый ход, я думаю это было бы классно.
А насчет популяризации, было бы классно видеть перед глазами структурную схему API, что к чему относиться и от чего зависит. Не знаю, есть ли сейчас такая вещь, но раньше ее не было. Встречался с такой штукой только у одного продукта, и то ее вроде потом закрыли или перестали поддерживать.
kompas_3d Автор
Да нет, мы не ставим цели заработать на поддержке. Нам как раз выгоднее, чтобы под КОМПАС писали больше сторонних приложений.
В каком формате это должно быть?
sah4ez32
Да хотя бы тот же самый UML. С описание классов, например
IDrawing— это за чертежку отвечает, реализует вот такие-то вещи. От него наследуются такие-то классы.Студентам не имеющих опыта в разработке порой тяжело понять это все по коду или через вызов методов в IDE.
Ну или сделать статью с общим описание API с иллюстрациями.
kompas_3d Автор
Нашли структурную схему API 7 от КОМПАС-3D V14. В формате Mind Map.
Закинул в обсуждения в ВК:
vk.com/topic-29994774_26653498?post=65042
Если не получится скачать — выложу ещё куда-нибудь.
sah4ez32
Шикарная штука! Вот такого мне в студенческие годы не хватало.
Вынесите такую штуку на сайте, и за одно еще в PNG сконвертируйте с хорошим разрешение.
ИМХО разослали бы по базе подписчиков/клиентской базе/CRM. Что у вас там, вам виднее. Популяризируйте свой API, делайте его более доступным и документированным. И будет вам счастье)
Кстати, что касается самой схемы, есть возможность описать методы у интерфейсов? Если это API, я как разработчик, хотел бы посмотреть что ваша система умеет, не заходя в сам SDK. Вот пример
И может вам подумать на системой к своему проекту, которая будет сама генерить документацию на API. В мире что-то типа javadoc в мире Java. Или какой-то скрипт натравить на исходную базу, чтобы сформировала описание, хотя бы без детального описания.
Плюс, если вы запилите сайт со схемой SDK и ссылочками на раздел онлайн документации — это будет просто БОМБА!
kompas_3d Автор
Для начала её актуализировать нужно. Её убрали из состава SDK, когда справка винды перестала поддерживать майнд-карты. А рядом почему-то не положили…
Появится возможность — сделаем.
kompas_3d Автор
На нашем форуме кстати довольно активный раздел, посвященный использованию API: forum.ascon.ru/index.php/board,4.0.html
У нас просто нет людей, которые бы могли написать достаточное количество документации. Это довольно сложно найти человека, умеющего хорошо программировать и умеющего грамотно и понятно всё описывать.
kompas_3d Автор
Идея хорошая, вопрос будут ли на это ресурсы. Всё что касается API могут писать только программисты, и для нас всегда очень серьёзный вопрос — посадить программиста писать что-то касающееся API или документации по нему или посадить его на написание нового кода. Пока мы можем себе позволить только привлечение сторонних авторов, как в данном случае Сергея.
sah4ez32
Ну тут тогда вопрос о финансировании такого процесса. Может есть смысл отдавать что-то на фриланс или создавать заказы. Мол за документирование с примерами мы готовы заплатить N-ю сумму денег, кто готов?
Как вариант, студенты (Брянский Государственный Технический Университет) должны были разбираться с документацией (хотя бы минимально) в рамках курсовых проектов, а если за это им будут доплачивать, я думаю желающих будет больше.
Я в студенческие годы писал на Delphi расчет редуктора, и под КОМПАС тоже. Если бы меня деньгами простимулировали, я думаю было бы законченный продукт уже.
kompas_3d Автор
Спасибо. Запомню идею.