Продолжаем цикл статей по работе с API САПР КОМПАС-3D Сергея Норсеева, инженера-программиста АО «ВНИИ «Сигнал», автора книги «Разработка приложений под КОМПАС в Delphi». В качестве среды используется C++ Builder. Мы уже рассматривали работу с основной надписью в четвертой части нашего цикла статей. В этой статье я хотел бы рассмотреть более сложные приемы записи в основную надпись. Но вначале нам нужно познакомиться с рядом новых интерфейсов.
Динамический массив в системе КОМПАС описывается интерфейсом ksDynamicArray. Получить его можно с помощью метода GetDynamicArray интерфейса KompasObject. В качестве единственного параметра он принимает целочисленный тип массива, который определяет, элементы какого типа хранятся в массиве. Как правило, в нем хранятся другие интерфейсы. Я не буду приводить все возможные типы массивов, так как их очень много.
У интерфейса ksDynamicArray всего одно свойство. reference –указатель на интерфейс. Рассмотрим методы интерфейса.
ksAddArrayItem – добавить элемент в массив. Ниже приводится прототип данного метода.
Параметр index задает порядковый номер элемента, перед которым нужно вставить новый элемент. Нумерация элементов ведется с нуля. Если значение этого параметра равно -1, то новый элемент вставляется в конец массива.
В случае успеха данный метод возвращает значение 1, а в случае ошибки – ноль.
ksClearArray() – удаляет все элементы массива, но не сам массив. Не имеет входных параметров. В случае успеха возвращает значение 1, а в случае ошибки – ноль.
ksDeleteArray() – удаляет массив. Если массив непустой, то автоматически удаляются все его элементы. Не имеет входных параметров. В случае успеха возвращает значение 1, а в случае ошибки – ноль.
ksExcludeArrayItem – удаляет элемент массива. В качестве единственного параметра принимает индекс удаляемого элемента. В случае успеха возвращает единицу, а в случае ошибки – ноль.
ksGetArrayCount() – возвращает количество элементов в массиве.
ksGetArrayItem – возвращает заданный элемент массива. Ниже приводится прототип данного метода.
Параметр index задает порядковый номер запрашиваемого элемента массива (нумерация ведется с нуля).
Параметр item содержит интерфейс, в который записывается читаемый элемент массива. Тип этого интерфейса зависит от типа массива.
В случае успеха метод ksGetArrayItem возвращает значение 1, а в случае ошибки – ноль. Обратите внимание: запрашиваемый элемент возвращается в параметре item.
ksGetArrayType() – возвращает тип массива.
ksSetArrayItem – изменяет заданный элемент массива. Ниже приводится прототип данного метода.
Параметр item содержит интерфейс, записываемый на место элемента с порядковым номером index (нумерация ведется с нуля). Тип этого интерфейса зависит от типа массива.
В случае успеха метод ksSetArrayItem возвращает значение 1, а в случае ошибки – ноль.
Интерфейс ksTextLineParam описывает строку текста. Получить его можно с помощью метода GetParamStruct интерфейса KompasObject. Для этого в качестве единственного параметра данному методу нужно передать константу ko_TextLineParam (29). У интерфейса ksTextLineParam всего одно свойство
style – стиль текста (будут рассмотрены в следующих статьях цикла).
Рассмотрим методы интерфейса ksTextLineParam. Их всего три.
GetTextItemArr() – возвращает динамический массив (ksDynamicArray) интерфейсов ksTextItemParam. Данный массив имеет тип TEXT_ITEM_ARR (4).
Init() – обнуляет все свойства интерфейса. В случае успеха возвращает значение true.
SetTextItemArr – устанавливает динамический массив интерфейсов ksTextItemParam. В качестве единственного параметра принимает устанавливаемый массив (интерфейс ksDynamicArray). В случае успеха возвращает значение true, а в случае ошибки – false.
Из этого описания легко видеть, что интерфейс ksTextLineParam по сути является обёрткой над динамическим массивом интерфейсов ksTextItemParam.
Ниже приводится пример программы, демонстрирующей заполнение основной надписи с использованием интерфейса ksTextLineParam.
Для упрощения в данном примере опущен код ответственный за подключение к КОМПАС, создание и оформление документа, освобождение ресурсов (эти вопросы рассматривались в предыдущих статьях цикла). На рисунке ниже показана основная надпись, сформированная данной программой.
1. В примере мы получаем интерфейс ksDynamicArray от интерфейса KompasObject. Но ничто не мешает нам получать его от интерфейса ksTextLineParam. Причем, если бы интерфейс ksDynamicArray был бы получен методом GetTextItemArray(), то мы могли бы не вызывать метод SetTextItemArray, так как массив уже был бы связан с интерфейсом ksTextLineParam.
2. Для обозначения номеров ячеек мы используем константы ksStPartNumber и ksStMaterial. Данные константы введены КОМПАС для наиболее часто используемых ячеек. Ознакомиться с ними можно в разделе «Структуры параметров и константы/Константы/Константы объектов оформления/ksStampEnum – Идентификаторы ячеек штампа» документации КОМПАС.
3. Для записи строк в основную надпись мы используем метод ksTextLine интерфейса ksStamp. Этот же метод использовался в четвертой части цикла, где мы рассматривали интерфейс ksTextItemParam. Данный метод в качестве параметра может принимать как интерфейс ksTextLineParam, так и более простой ksTextItemParam.
4. В основную надпись заносится две строки. Первая строка простая и состоит всего из одной компоненты. Вторая строка состоит из трех компонент. На рисунке ниже они разделены вертикальными красными линиями. В принципе последние две компоненты можно было объединить в одну. Но я специально использовал три компоненты, чтобы более наглядно показать принцип работы интерфейса ksTextLineParam.
Метод ksSetStampColumnText интерфейса ksStamp устанавливает текст в заданной ячейке основной надписи. Ниже приводится прототип данного метода.
Устанавливаемый текст задается в виде динамического массива ksDynamicArray. В случае успеха метод ksSetStampColumnText возвращает значение 1, а в случае ошибки – ноль.
Учтите, метод ksSetStampColumnText используется только в режиме редактирования основной надписи. То есть после вызова метода ksOpenStamp(), но до вызова метода ksCloseStamp() интерфейса ksStamp.
Массив textArr имеет тип TEXT_LINE_ARR (3). Это значит, что элементами массива являются интерфейсы ksTextLineParam, каждый из которых так же содержит динамический массив, но уже интерфейсов ksTextItemParam. На рисунке ниже приведена схема строения параметра textArr.
Хотя на рисунке выше количество элементов массивов равно трём, в реальности оно может быть любым. Если массив textArr состоит из нескольких элементов, то все строки ksTextLineParam склеиваются и выводятся в ячейку numb.
Ниже приводится пример программы, демонстрирующей заполнение основной надписи с помощью метода ksSetStampColumnText.
Результат работы данной программы аналогичен результату работы предыдущего примера.
Обратите внимание: поскольку в метод ksSetStampColumnText уже передается номер ячейки, в которую записывается строка, то вызывать метод ksColumnNumber не нужно.
Заключение
Мы рассмотрели три способа записи строк в ячейки основной надписи: на основе интерфейса ksTextItemParam (рассматривался в 4 части цикла статей), на основе интерфейса ksTextLineParam и с использованием метода ksSetStampColumnText.
Первый способ самый простой. Он не требует работы с динамическими массивами. Он идеально подходит для записи строк. С помощью него также можно формировать сложные строки. Для этого используются управляющие символы, которые будут рассмотрены в следующих статьях цикла.
Второй способ (интерфейс ksTextLineParam) не намного сложнее первого. Интерфейс ksTextLineParam также используется в третьем способе. Поэтому его нужно понимать для понимания третьего способа.
Третий способ (метод ksSetStampColumnText) самый сложный в реализации. Единственное реальное его преимущество перед первыми двумя способами состоит в отсутствии необходимости вызывать метод ksColumnNumber. Однако подход, применяемый в этом методе, используется при чтении содержимого ячеек основной надписи (об этом в следующей статье цикла).
Вы можете пользоваться любым из этих методов. Лично я, как правило, пользуюсь первым.
Продолжение следует, следите за новостями блога.
Сергей Норсеев, автор книги «Разработка приложений под КОМПАС в Delphi».
Содержание цикла уроков «Работа с API КОМПАС-3D»
1. Основы
2. Оформление чертежа
3. Корректное подключение к КОМПАС
4. Основная надпись
5. Графические примитивы
6. Сохранение документа в различные форматы
7. Знакомство с настройками
8. Более сложные методы записи в основную надпись
Динамический массив (ksDynamicArray)
Динамический массив в системе КОМПАС описывается интерфейсом ksDynamicArray. Получить его можно с помощью метода GetDynamicArray интерфейса KompasObject. В качестве единственного параметра он принимает целочисленный тип массива, который определяет, элементы какого типа хранятся в массиве. Как правило, в нем хранятся другие интерфейсы. Я не буду приводить все возможные типы массивов, так как их очень много.
У интерфейса ksDynamicArray всего одно свойство. reference –указатель на интерфейс. Рассмотрим методы интерфейса.
ksAddArrayItem – добавить элемент в массив. Ниже приводится прототип данного метода.
long ksAddArrayItem (
long index, //Порядковый номер элемента
LPDISPATCH item //Добавляемый элемент
);
Параметр index задает порядковый номер элемента, перед которым нужно вставить новый элемент. Нумерация элементов ведется с нуля. Если значение этого параметра равно -1, то новый элемент вставляется в конец массива.
В случае успеха данный метод возвращает значение 1, а в случае ошибки – ноль.
ksClearArray() – удаляет все элементы массива, но не сам массив. Не имеет входных параметров. В случае успеха возвращает значение 1, а в случае ошибки – ноль.
ksDeleteArray() – удаляет массив. Если массив непустой, то автоматически удаляются все его элементы. Не имеет входных параметров. В случае успеха возвращает значение 1, а в случае ошибки – ноль.
ksExcludeArrayItem – удаляет элемент массива. В качестве единственного параметра принимает индекс удаляемого элемента. В случае успеха возвращает единицу, а в случае ошибки – ноль.
ksGetArrayCount() – возвращает количество элементов в массиве.
ksGetArrayItem – возвращает заданный элемент массива. Ниже приводится прототип данного метода.
long ksGetArrayItem (
long index, //Порядковый номер элемента
LPDISPATCH item //Интерфейс элемента
);
Параметр index задает порядковый номер запрашиваемого элемента массива (нумерация ведется с нуля).
Параметр item содержит интерфейс, в который записывается читаемый элемент массива. Тип этого интерфейса зависит от типа массива.
В случае успеха метод ksGetArrayItem возвращает значение 1, а в случае ошибки – ноль. Обратите внимание: запрашиваемый элемент возвращается в параметре item.
ksGetArrayType() – возвращает тип массива.
ksSetArrayItem – изменяет заданный элемент массива. Ниже приводится прототип данного метода.
long ksSetArrayItem(
long index, //Порядковый номер элемента
LPDISPATCH item //Интерфейс элемента
);
Параметр item содержит интерфейс, записываемый на место элемента с порядковым номером index (нумерация ведется с нуля). Тип этого интерфейса зависит от типа массива.
В случае успеха метод ksSetArrayItem возвращает значение 1, а в случае ошибки – ноль.
Параметры строки (ksTextLineParam)
Интерфейс ksTextLineParam описывает строку текста. Получить его можно с помощью метода GetParamStruct интерфейса KompasObject. Для этого в качестве единственного параметра данному методу нужно передать константу ko_TextLineParam (29). У интерфейса ksTextLineParam всего одно свойство
style – стиль текста (будут рассмотрены в следующих статьях цикла).
Рассмотрим методы интерфейса ksTextLineParam. Их всего три.
GetTextItemArr() – возвращает динамический массив (ksDynamicArray) интерфейсов ksTextItemParam. Данный массив имеет тип TEXT_ITEM_ARR (4).
Init() – обнуляет все свойства интерфейса. В случае успеха возвращает значение true.
SetTextItemArr – устанавливает динамический массив интерфейсов ksTextItemParam. В качестве единственного параметра принимает устанавливаемый массив (интерфейс ksDynamicArray). В случае успеха возвращает значение true, а в случае ошибки – false.
Из этого описания легко видеть, что интерфейс ksTextLineParam по сути является обёрткой над динамическим массивом интерфейсов ksTextItemParam.
Пример 1
Ниже приводится пример программы, демонстрирующей заполнение основной надписи с использованием интерфейса ksTextLineParam.
//Получаем интерфейсы строки и компоненты
TextItemParamPtr TextItemParam;
TextItemParam = (TextItemParamPtr)kompas->GetParamStruct(ko_TextItemParam);
TextLineParamPtr TextLineParam;
TextLineParam = (TextLineParamPtr)kompas->GetParamStruct(ko_TextLineParam);
//Получаем интерфейс динамического массива
DynamicArrayPtr DynamicArray;
DynamicArray = (DynamicArrayPtr)kompas->GetDynamicArray(TEXT_ITEM_ARR);
//Получаем интерфейс основной надписи
StampPtr Stamp;
Stamp = (StampPtr)Document2D->GetStamp();
//Открываем режим редактирования основной надписи
Stamp->ksOpenStamp();
//Формируем первую строку
TextItemParam->set_s(SysAllocString(L"Деталь"));
DynamicArray->ksAddArrayItem(-1, TextItemParam);
TextLineParam->SetTextItemArr(DynamicArray);
//Выводим ее в основную надпись
Stamp->ksColumnNumber(ksStPartNumber);
Stamp->ksTextLine(TextLineParam);
//Очищаем массив для новой строки
DynamicArray->ksClearArray();
//Формируем первую компоненту второй строки
TextItemParam->set_s(SysAllocString(L"До "));
DynamicArray->ksAddArrayItem(-1, TextItemParam);
//Формируем вторую компоненту второй строки
TextItemParam->Init();
TextItemParam->set_type(SPECIAL_SYMBOL);
TextItemParam->set_iSNumb(51);
DynamicArray->ksAddArrayItem(-1, TextItemParam);
//Формируем третью компоненту второй строки
TextItemParam->set_type(0);;
TextItemParam->set_s(SysAllocString(L" После"));
DynamicArray->ksAddArrayItem(-1, TextItemParam);
//Выводим вторую строку в основную надпись
TextLineParam->SetTextItemArr(DynamicArray);
Stamp->ksColumnNumber(ksStMaterial);
Stamp->ksTextLine(TextLineParam);
//Закрываем режим редактирования основной надписи
Stamp->ksCloseStamp();
Для упрощения в данном примере опущен код ответственный за подключение к КОМПАС, создание и оформление документа, освобождение ресурсов (эти вопросы рассматривались в предыдущих статьях цикла). На рисунке ниже показана основная надпись, сформированная данной программой.
Обратите внимание на несколько моментов
1. В примере мы получаем интерфейс ksDynamicArray от интерфейса KompasObject. Но ничто не мешает нам получать его от интерфейса ksTextLineParam. Причем, если бы интерфейс ksDynamicArray был бы получен методом GetTextItemArray(), то мы могли бы не вызывать метод SetTextItemArray, так как массив уже был бы связан с интерфейсом ksTextLineParam.
2. Для обозначения номеров ячеек мы используем константы ksStPartNumber и ksStMaterial. Данные константы введены КОМПАС для наиболее часто используемых ячеек. Ознакомиться с ними можно в разделе «Структуры параметров и константы/Константы/Константы объектов оформления/ksStampEnum – Идентификаторы ячеек штампа» документации КОМПАС.
3. Для записи строк в основную надпись мы используем метод ksTextLine интерфейса ksStamp. Этот же метод использовался в четвертой части цикла, где мы рассматривали интерфейс ksTextItemParam. Данный метод в качестве параметра может принимать как интерфейс ksTextLineParam, так и более простой ksTextItemParam.
4. В основную надпись заносится две строки. Первая строка простая и состоит всего из одной компоненты. Вторая строка состоит из трех компонент. На рисунке ниже они разделены вертикальными красными линиями. В принципе последние две компоненты можно было объединить в одну. Но я специально использовал три компоненты, чтобы более наглядно показать принцип работы интерфейса ksTextLineParam.
Метод ksSetStampColumnText
Метод ksSetStampColumnText интерфейса ksStamp устанавливает текст в заданной ячейке основной надписи. Ниже приводится прототип данного метода.
long ksSetStampColumnText (
long numb, //Номер ячейки
LPDISPATCH textArr //Устанавливаемый текст
);
Устанавливаемый текст задается в виде динамического массива ksDynamicArray. В случае успеха метод ksSetStampColumnText возвращает значение 1, а в случае ошибки – ноль.
Учтите, метод ksSetStampColumnText используется только в режиме редактирования основной надписи. То есть после вызова метода ksOpenStamp(), но до вызова метода ksCloseStamp() интерфейса ksStamp.
Массив textArr имеет тип TEXT_LINE_ARR (3). Это значит, что элементами массива являются интерфейсы ksTextLineParam, каждый из которых так же содержит динамический массив, но уже интерфейсов ksTextItemParam. На рисунке ниже приведена схема строения параметра textArr.
Хотя на рисунке выше количество элементов массивов равно трём, в реальности оно может быть любым. Если массив textArr состоит из нескольких элементов, то все строки ksTextLineParam склеиваются и выводятся в ячейку numb.
Пример 2
Ниже приводится пример программы, демонстрирующей заполнение основной надписи с помощью метода ksSetStampColumnText.
//Получаем интерфейсы строки и компоненты
TextItemParamPtr TextItemParam;
TextItemParam = (TextItemParamPtr)kompas->GetParamStruct(ko_TextItemParam);
TextLineParamPtr TextLineParam;
TextLineParam = (TextLineParamPtr)kompas->GetParamStruct(ko_TextLineParam);
//Получаем динамический массив интерфейсов ksTextItemParam
DynamicArrayPtr DynamicArrayItems;
DynamicArrayItems = (DynamicArrayPtr)kompas->GetDynamicArray(TEXT_ITEM_ARR);
DynamicArrayItems->ksClearArray();
//Получаем динамический массив интерфейсов ksTextLineParam
DynamicArrayPtr DynamicArrayLines;
DynamicArrayLines = (DynamicArrayPtr)kompas->GetDynamicArray(TEXT_LINE_ARR);
DynamicArrayLines->ksClearArray();
//Получаем интерфейс основной надписи
StampPtr Stamp;
Stamp = (StampPtr)Document2D->GetStamp();
//Открываем режим редактирования основной надписи
Stamp->ksOpenStamp();
//Формируем первую строку
TextItemParam->set_s(SysAllocString(L"Деталь"));
DynamicArrayItems->ksAddArrayItem(-1, TextItemParam);
TextLineParam->SetTextItemArr(DynamicArrayItems);
//Добавляем ее в массив строк
DynamicArrayLines->ksAddArrayItem(-1, TextLineParam);
//Выводим ее в основную надпись
Stamp->ksSetStampColumnText(ksStPartNumber, DynamicArrayLines);
//Очищаем массивы для новой строки
DynamicArrayLines->ksClearArray();
DynamicArrayItems->ksClearArray();
//Формируем первую компоненту второй строки
TextItemParam->set_s(SysAllocString(L"До "));
DynamicArrayItems->ksAddArrayItem(-1, TextItemParam);
//Формируем вторую компоненту второй строки
TextItemParam->Init();
TextItemParam->set_type(SPECIAL_SYMBOL);
TextItemParam->set_iSNumb(51);
DynamicArrayItems->ksAddArrayItem(-1, TextItemParam);
//Формируем третью компоненту второй строки
TextItemParam->set_type(0);
TextItemParam->set_s(SysAllocString(L" После"));
DynamicArrayItems->ksAddArrayItem(-1, TextItemParam);
//Добавляем строку в массив
TextLineParam->SetTextItemArr(DynamicArrayItems);
DynamicArrayLines->ksAddArrayItem(-1, TextLineParam);
//Выводим вторую строку в основную надпись
Stamp->ksSetStampColumnText(ksStMaterial, DynamicArrayLines);
//Закрываем режим редактирования основной надписи
Stamp->ksCloseStamp();
Результат работы данной программы аналогичен результату работы предыдущего примера.
Обратите внимание: поскольку в метод ksSetStampColumnText уже передается номер ячейки, в которую записывается строка, то вызывать метод ksColumnNumber не нужно.
Заключение
Мы рассмотрели три способа записи строк в ячейки основной надписи: на основе интерфейса ksTextItemParam (рассматривался в 4 части цикла статей), на основе интерфейса ksTextLineParam и с использованием метода ksSetStampColumnText.
Первый способ самый простой. Он не требует работы с динамическими массивами. Он идеально подходит для записи строк. С помощью него также можно формировать сложные строки. Для этого используются управляющие символы, которые будут рассмотрены в следующих статьях цикла.
Второй способ (интерфейс ksTextLineParam) не намного сложнее первого. Интерфейс ksTextLineParam также используется в третьем способе. Поэтому его нужно понимать для понимания третьего способа.
Третий способ (метод ksSetStampColumnText) самый сложный в реализации. Единственное реальное его преимущество перед первыми двумя способами состоит в отсутствии необходимости вызывать метод ksColumnNumber. Однако подход, применяемый в этом методе, используется при чтении содержимого ячеек основной надписи (об этом в следующей статье цикла).
Вы можете пользоваться любым из этих методов. Лично я, как правило, пользуюсь первым.
Продолжение следует, следите за новостями блога.
Сергей Норсеев, автор книги «Разработка приложений под КОМПАС в Delphi».