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

  • Tutorial
Продолжаем цикл статей по работе с 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».
АСКОН 73,66
Крупнейший российский разработчик инженерного ПО
Поделиться публикацией
Комментарии 14
  • +1

    Блин, во время моего обучения такого не было. Была только книга автора и не полностью документированная sdk.


    А вот для студента как раз такое изложение самое то, чтобы замотивировать.


    А рассматривали вариант описания API на примере какого цельного проекта, где разные этапы реализации затрагивали разные аспекты API?


    Автору за статью огромное спасибо! Жду продолжения.


    PS
    Когда был курсовой (где-то 2012 год) по написанию модуля для какой-то (на выбор) САПР, выбрали не КОМПАС, по причине слабой документации к API.

    • 0

      2.5 года назад я тоже не нашел толковой документации, а по всем вопросам предлагалось обратиться то ли на форум, то ли в группу в ВК. И такая "открытость" как я понял распространённая практика среди российских компаний.

      • 0
        И такая "открытость" как я понял распространённая практика среди российских компаний

        Соглашусь. И чуток добавлю.


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


        Но создается впечатление что "открытость" документации — это не сильно нужно разработчикам, так как количество людей, которые пишут внешние модули к CAD очень мало. Плюс причесать к нормальному виду API — это наверное проще будет написать "с нуля".


        Ну и зачем отнимать хлеб у себя же, если на такой поддержке можно заработать. Это можно аргументировать закостенелостью бизнес-процессов или отсутствием развития бизнеса в этом направлении, но я не сильно сведущий в области ведения бизнеса по продаже и продвижению САПР всякого рода. Хотя как маркетинговый ход, я думаю это было бы классно.


        А насчет популяризации, было бы классно видеть перед глазами структурную схему API, что к чему относиться и от чего зависит. Не знаю, есть ли сейчас такая вещь, но раньше ее не было. Встречался с такой штукой только у одного продукта, и то ее вроде потом закрыли или перестали поддерживать.

        • 0
          Ну и зачем отнимать хлеб у себя же, если на такой поддержке можно заработать.

          Да нет, мы не ставим цели заработать на поддержке. Нам как раз выгоднее, чтобы под КОМПАС писали больше сторонних приложений.
          А насчет популяризации, было бы классно видеть перед глазами структурную схему API, что к чему относиться и от чего зависит. Не знаю, есть ли сейчас такая вещь, но раньше ее не было.

          В каком формате это должно быть?
          • 0
            В каком формате это должно быть?

            Да хотя бы тот же самый UML. С описание классов, например IDrawing — это за чертежку отвечает, реализует вот такие-то вещи. От него наследуются такие-то классы.


            Студентам не имеющих опыта в разработке порой тяжело понять это все по коду или через вызов методов в IDE.


            Ну или сделать статью с общим описание API с иллюстрациями.

            • 0
              Нашли структурную схему API 7 от КОМПАС-3D V14. В формате Mind Map.
              Закинул в обсуждения в ВК:
              vk.com/topic-29994774_26653498?post=65042
              Если не получится скачать — выложу ещё куда-нибудь.
              • 0

                Шикарная штука! Вот такого мне в студенческие годы не хватало.
                Вынесите такую штуку на сайте, и за одно еще в PNG сконвертируйте с хорошим разрешение.


                Да нет, мы не ставим цели заработать на поддержке. Нам как раз выгоднее, чтобы под КОМПАС писали больше сторонних приложений.

                ИМХО разослали бы по базе подписчиков/клиентской базе/CRM. Что у вас там, вам виднее. Популяризируйте свой API, делайте его более доступным и документированным. И будет вам счастье)


                Кстати, что касается самой схемы, есть возможность описать методы у интерфейсов? Если это API, я как разработчик, хотел бы посмотреть что ваша система умеет, не заходя в сам SDK. Вот пример
                И может вам подумать на системой к своему проекту, которая будет сама генерить документацию на API. В мире что-то типа javadoc в мире Java. Или какой-то скрипт натравить на исходную базу, чтобы сформировала описание, хотя бы без детального описания.


                Плюс, если вы запилите сайт со схемой SDK и ссылочками на раздел онлайн документации — это будет просто БОМБА!

                • 0
                  ИМХО разослали бы по базе подписчиков/клиентской базе/CRM. Что у вас там, вам виднее. Популяризируйте свой API, делайте его более доступным и документированным. И будет вам счастье)

                  Для начала её актуализировать нужно. Её убрали из состава SDK, когда справка винды перестала поддерживать майнд-карты. А рядом почему-то не положили…

                  Плюс, если вы запилите сайт со схемой SDK и ссылочками на раздел онлайн документации — это будет просто БОМБА!

                  Появится возможность — сделаем.
        • 0
          по всем вопросам предлагалось обратиться то ли на форум, то ли в группу в ВК.

          На нашем форуме кстати довольно активный раздел, посвященный использованию API: forum.ascon.ru/index.php/board,4.0.html

          такая «открытость» как я понял распространённая практика среди российских компаний.

          У нас просто нет людей, которые бы могли написать достаточное количество документации. Это довольно сложно найти человека, умеющего хорошо программировать и умеющего грамотно и понятно всё описывать.
        • 0
          А рассматривали вариант описания API на примере какого цельного проекта, где разные этапы реализации затрагивали разные аспекты API?

          Идея хорошая, вопрос будут ли на это ресурсы. Всё что касается API могут писать только программисты, и для нас всегда очень серьёзный вопрос — посадить программиста писать что-то касающееся API или документации по нему или посадить его на написание нового кода. Пока мы можем себе позволить только привлечение сторонних авторов, как в данном случае Сергея.
          • +1

            Ну тут тогда вопрос о финансировании такого процесса. Может есть смысл отдавать что-то на фриланс или создавать заказы. Мол за документирование с примерами мы готовы заплатить N-ю сумму денег, кто готов?
            Как вариант, студенты (Брянский Государственный Технический Университет) должны были разбираться с документацией (хотя бы минимально) в рамках курсовых проектов, а если за это им будут доплачивать, я думаю желающих будет больше.
            Я в студенческие годы писал на Delphi расчет редуктора, и под КОМПАС тоже. Если бы меня деньгами простимулировали, я думаю было бы законченный продукт уже.

      • +1
        Спасибо за статью, для студентов самое то будет. Я уже несколько лет (тьфу-тьфу-тьфу) не занимался ничем, что связано с API Компас 3D, в связи с чем вопрос: за последние несколько лет не проводилась ли работа по унификации и стандартизации API? На тот момент, когда в университете писали плагины (2011-2012гг) это было чем-то похоже на PHP в этом плане. В одном месте enum в другом magic numbers, а API 2D и 3D лучше было вообще не сравнивать.
        • 0
          API в последнее время серьёзно не менялся — только дополнение новых команд.

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

        Самое читаемое