Работа с API КОМПАС-3D → Урок 7 → Знакомство с настройками
Продолжаем цикл статей по работе с API САПР КОМПАС-3D Сергея Норсеева, инженера-программиста АО «ВНИИ «Сигнал», автора книги «Разработка приложений под КОМПАС в Delphi». В качестве среды используется C++ Builder. В этом уроке поговорим о настройках системы КОМПАС.
Содержание цикла уроков «Работа с API КОМПАС-3D»
1. Основы
2. Оформление чертежа
3. Корректное подключение к КОМПАС
4. Основная надпись
5. Графические примитивы
6. Сохранение документа в различные форматы
7. Знакомство с настройками
8. Более сложные методы записи в основную надпись
Чтение настроек
Для чтения настроек используется метод ksGetSysOptions интерфейса KompasObject. Ниже приводится его прототип.
long ksGetSysOptions (
long optionsType, //Тип настройки
LPDISPATCH param //Интерфейс настройки
);
Параметр optionsType содержит целое число, определяющее, какую именно настройку мы хотим получить. Параметр param представляет собой указатель на интерфейс, в который будет записана запрошенная настройка. Тип этого интерфейса зависит от того, какую настройку мы запросили. Соответствие между параметрами optionsType и param приводится в таблице ниже.
Таблица 1. Соответствие между параметрами optionsType и param
Данные константы объявлены в файле ldefin2d.h.
В случае успеха метод ksGetSysOptions возвращает значение 1, а в случае ошибки — значение ноль.
В ряде мест в документации КОМПАС указывается, что метод ksGetSysOptions позволяет получить тот или иной интерфейс. Однако это не так. Данный метод позволяет заполнить интерфейс, но не получить его. Получать интерфейс вы должны сами с помощью метода GetParamStruct интерфейса KompasObject. Если в метод ksGetSysOptions передать неполученный интерфейс, то метод вернет ноль (ошибка).
Настройки привязок
Глядя на таблицу 1, невольно возникает предположение, что для получения настройки SNAP_OPTIONS_EX нужно обязательно иметь активный документ, а для получения настройки SNAP_OPTIONS документ не обязателен. На самом деле это не так. Как показывают мои эксперименты, в случае если у вас нет активного документа, метод ksGetSysOptions возвращает значение ноль (ошибка) для SNAP_OPTIONS, а не для SNAP_OPTIONS_EX. При этом на экран выводится сообщение об ошибке.
Сообщение об ошибке
Учтите так же, что если у вас возникла описанная выше ошибка, то для ее исправления может понадобиться перезапуск КОМПАС. Дело в том, что все последующие вызовы метода ksGetSysOptions, даже при наличии активного документа, будут завершаться ошибкой.
Кратко рассмотрим интерфейс ksSnapOptions. Его свойства:
angSnap — включена ли привязка «угловая привязка» (true — включена, false — выключена);
angleStep –шаг угловой привязки (в градусах);
commonOpt — набор флагов общих привязок (рассматривать не будем);
grid — включена ли привязка «по сетке» (true — включена, false — выключена);
intersect — включена ли привязка «пересечение» (true — включена, false — выключена);
localSnap — тип локальной привязки;
nearestMiddle — включена ли привязка «середина» (true — включена, false — выключена);
nearestPoint — включена ли привязка «ближайшая точка» (true — включена, false — выключена);
pointOnCurve — включена ли привязка «точка на кривой» (true — включена, false — выключена);
tangentToCurve — включена ли привязка «касание» (true — включена, false — выключена);
xyAlign — включена ли привязка «выравнивание» (true — включена, false — выключена).
Методов у интерфейса ksSnapOptions всего три:
Init () — сбрасывает все свойства, в случае успеха возвращает значение true;
GetCommonOptValue и SetCommonOptValue — предназначены для работы со свойством commonOpt.
Ниже приводится пример программы, демонстрирующей работу с интерфейсом ksSnapOptions.
//Подключаемся к КОМПАС
KompasObjectPtr kompas;
kompas.CreateInstance(L"KOMPAS.Application.5");
//Подготавливаем параметры документа
DocumentParamPtr DocumentParam;
DocumentParam=(DocumentParamPtr)kompas->GetParamStruct(ko_DocumentParam);
DocumentParam->Init();
DocumentParam->type= lt_DocSheetStandart;//Чертеж на стандартном листе
//Создаем документ
Document2DPtr Document2D;
Document2D = (Document2DPtr)kompas->Document2D();
Document2D->ksCreateDocument(DocumentParam);
//Читаем настройки привязок
ksSnapOptionsPtr SnapOptions;
SnapOptions = (ksSnapOptionsPtr)kompas->GetParamStruct(ko_SnapOptions);
kompas->ksGetSysOptions(SNAP_OPTIONS, SnapOptions);
ShowMessage(FloatToStr(SnapOptions->get_angleStep()));
//Освобождаем интерфейсы
DocumentParam.Unbind();
Document2D.Unbind();
SnapOptions.Unbind();
kompas->set_Visible(true);
kompas.Unbind();
В данном примере мы определяем шаг угловой привязки. Например, на моем домашнем компьютере он составил 45° (у вас может быть другим). Учтите, что это крайне упрощенный пример. В нем не реализовано корректное подключение к КОМПАС и опущена обработка ошибок.
Параметры листа
Параметры листа в контексте настроек описываются интерфейсом ksSheetOptions. Данный интерфейс похож на интерфейс ksSheetPar, который мы рассматривали во второй части данного цикла статей. Рассмотрим свойства интерфейса ksSheetOptions.
layoutName — путь к библиотеке оформления.
sheetType — тип листа (true — пользовательский формат, false — стандартный лист);
shtType — тип основной надписи из библиотеки layoutName.
Свойства layoutName и shtType аналогичны одноименным свойствам интерфейса ksSheetPar.
Методов у интерфейса ksSheetOptions всего два:
GetSheetParam — возвращает интерфейс параметров листа (ksStandartSheet для стандартных листов и ksSheetSize для нестандартных листов). В качестве единственного параметра принимает признак формата листа (true — нестандартный лист, false — стандартный лист). Учтите, что значение параметра должно совпадать со значением свойства sheetType. Такое дублирование информации осталось из-за необходимости совместимости с некоторыми старыми библиотеками.
Init () — сбрасывает значения всех свойств интерфейса.
Ниже приводится пример использования данного интерфейса для определения формата листа.
//Подключаемся к КОМПАС
KompasObjectPtr kompas;
kompas.CreateInstance(L"KOMPAS.Application.5");
//Получаем интерфейс параметров листа
SheetOptionsPtr SheetOptions;
SheetOptions = (ksSheetOptionsPtr)kompas->GetParamStruct(ko_SheetOptions);
//Читаем настройку
kompas->ksGetSysOptions(SHEET_OPTIONS_EX, SheetOptions);
if(SheetOptions->get_sheetType())
ShowMessage("Нестандартный формат");
else
{
//Стандартный лист
ksStandartSheetPtr StandartSheet;
StandartSheet = (ksStandartSheetPtr)SheetOptions->GetSheetParam(false);
ShowMessage(IntToStr(StandartSheet->get_format()));
StandartSheet.Unbind();
}
//Освобождаем интерфейсы
SheetOptions.Unbind();
kompas->set_Visible(true);
kompas.Unbind();
В данном примере определяются параметры листа документа. Если он имеет нестандартный размер, то на экран выводится строка «Нестандартный лист». Если же он имеет стандартный формат, то на экран выводится число, задающее формат. Например, на моём домашнем компьютере выводится число 4, которое задает лист формата А4 (у вас оно может отличаться).
Вы наверняка заметили, что в примере не создается никакого документа. Резонно возникает вопрос: формат листа какого документа мы определяем в программе, если никакого документа нет? В примере определяется формат нового документа по умолчанию.
В документации КОМПАС также упоминается константа SHEET_OPTIONS (3) как аналог константы SHEET_OPTIONS_EX. Однако константа SHEET_OPTIONS считается устаревшей и оставлена для совместимости с некоторыми старыми библиотеками.
Цвета фона
Цвета фона описываются интерфейсом ksViewColorParam. Рассмотрим свойства этого интерфейса.
BottomColor — нижний цвет перехода, доступно только для документов-моделей.
Color — цвет фона. Если значение этого свойства равно -1, то используется цвет окна, установленный в системе Windows.
TopColor — верхний цвет перехода, доступно только для документов моделей.
UseGradient — признак использования градиентного перехода (true — используется, false — не используется).
Хотя в документации по API КОМПАС явно не говорится о том, какой формат представления цвета используется, как и в самом КОМПАСе, в API используется формат RGB.
Метод у интерфейса ksViewColorParam всего один.
Init () — сбросить значения всех свойств интерфейса. В случае успеха возвращает значение true.
Ниже приводится пример использования данного интерфейса.
//Подключаемся к КОМПАС
KompasObjectPtr kompas;
kompas.CreateInstance(L"KOMPAS.Application.5");
//Читаем параметры цвета фона
ksViewColorParamPtr ViewColor;
ViewColor = (ksViewColorParamPtr)kompas->GetParamStruct(ko_ViewColorParam);
kompas->ksGetSysOptions(VIEWCOLOR_OPTIONS, ViewColor);
DWORD color;
color = ViewColor->get_color();
AnsiString str;
str = "(0x"+IntToHex(GetRValue(color),2)
+ ";0x"+IntToHex(GetGValue(color),2)
+ ";0x"+IntToHex(GetBValue(color),2) + ")";
ShowMessage(str);
//Освобождаем интерфейсы
ViewColor.Unbind();
kompas->set_Visible(true);
kompas.Unbind();
В данном примере определяется цвет фона рабочего поля документа и выводится на экран в виде компонент красного, зеленого и синего цветов.
Тип данных Вариант
Вариант — это переменная, хранящая в себе значение некоторого типа. КОМПАС реализует варианты с помощью интерфейса ksLtVariant. У него достаточно много свойств и их удобнее всего рассматривать относительно главного свойства — valType. Данное свойство задает тип значения, хранящегося в варианте. Допустимые значения этого свойства, а также другие свойства интерфейса ksLtVariant приведены в таблице ниже.
Таблица 2. свойства интерфейса ksLtVariant
Данные константы объявлены в файле ldefin2d.h.
Например, если значение свойства valType равно ltv_Uint, то значение, хранящееся в варианте, находится в свойстве uIntVal. Если же значение свойства valType равно ltv_Double, то значение, хранящееся в варианте, находится в свойстве doubleVal.
Метод у интерфейса ksLtVariant всего один.
Init () — сбрасывает значения всех свойств интерфейса. В случае успеха возвращает значение true.
Настройки единиц измерения
Согласно таблице 1 настройки единиц измерения запрашиваются с помощью константы LENGTHUNITS_OPTIONS. При этом метод ksGetSysOptions заполняет вариант ksLtVariant типа ltv_Short. В вариант записывается одно из допустимых значений, приведенных в таблице ниже.
Таблица 3. Допустимые значения ksLtVariant типа ltv_Short
Данные константы объявлены в файле ldefin2d.h.
Учтите, что единица измерения дециметры не поддерживается.
Ниже приводится пример программы, демонстрирующей определение единиц измерения.
//Подключаемся к КОМПАС
KompasObjectPtr kompas;
kompas.CreateInstance(L"KOMPAS.Application.5");
//Читаем настройку единицы измерения
ksLtVariantPtr Variant;
Variant = (ksLtVariantPtr)kompas->GetParamStruct(ko_LtVariant);
kompas->ksGetSysOptions(LENGTHUNITS_OPTIONS, Variant);
AnsiString str;
switch(Variant->get_shortVal())
{
case ST_MIX_MM: str = "миллиметры"; break;
case ST_MIX_SM: str = "сантиметры"; break;
case ST_MIX_DM: str = "дециметры" ; break;
case ST_MIX_M : str = "метры" ; break;
default: str = "ошибка";
}
ShowMessage(str);
//Освобождаем интерфейсы
Variant.Unbind();
kompas->set_Visible(true);
kompas.Unbind();
Данная программа определяет текущую единицу измерения и выводит ее на экран.
В этом примере мы не проверяем тип варианта, полагаясь на то, что он имеет тип ltv_Short. Я сделал это для упрощения примера. В реальных приложениях вы всегда должны проверять тип варианта.
Изменение настроек
Для изменения настроек используется метод ksSetSysOptions интерфейса KompasObject. Ниже приводится прототип данного метода.
long ksSetSysOptions (
long optionsType, //Тип настройки
LPDISPATCH param //Интерфейс параметров настройки
);
Легко видеть, что прототип данного метода аналогичен прототипу метода ksGetSysOptions. Соотношение между типом настройки и интерфейсом, ее описывающим также определяется по таблице 1. В случае успеха метод ksSetSysOptions возвращает значение 1, а в случае ошибки — ноль.
Учтите, что измененные настройки «существуют» только в течение текущего сеанса КОМПАС. После его перезапуска все настройки вернутся в свое первоначальное значение.
Ниже приводится пример программы, демонстрирующей изменение цвета фона документа с помощью метода ksSetSysOptions.
//Подключаемся к КОМПАС
KompasObjectPtr kompas;
kompas.CreateInstance(L"KOMPAS.Application.5");
//Делаем КОМПАС видимым
kompas->set_Visible(true);
//Подготавливаем параметры документа
DocumentParamPtr DocumentParam;
DocumentParam=(DocumentParamPtr)kompas->GetParamStruct(ko_DocumentParam);
DocumentParam->Init();
DocumentParam->type= lt_DocSheetStandart;//Чертеж на стандартном листе
//Создаем документ
Document2DPtr Document2D;
Document2D = (Document2DPtr)kompas->Document2D();
Document2D->ksCreateDocument(DocumentParam);
//Получаем интерфейс параметров цвета фона
ViewColorParamPtr ViewColorParam;
ViewColorParam = (ViewColorParamPtr)kompas->GetParamStruct(ko_ViewColorParam);
ViewColorParam->set_color(RGB(0,0xFF,0));
//Меняем цвет фона
kompas->ksSetSysOptions(VIEWCOLOR_OPTIONS, ViewColorParam);
//Освобождаем интерфейсы
ViewColorParam.Unbind();
DocumentParam.Unbind();
Document2D.Unbind();
kompas.Unbind();
В данном примере мы устанавливаем зеленый цвет фона.
Обратите внимание: КОМПАС делается видимым практически сразу, до изменения настройки. Если КОМПАС сделать видимым после изменения настройки, то она не будет изменена, хотя метод ksSetSysOptions вернет значение 1.
К сожалению метод ksSetSysOptions не позволяет изменять формат листа документа.
Методы ksGetDocOptions и ksSetDocOptions
Интерфейс ksDocument2D содержит методы ksGetDocOptions и ksSetDocOptions, которые являются аналогами методов ksGetSysOptions и ksSetSysOptions интерфейса KompasObject. Все эти методы имеют один и тот же прототип и позволяют читать (изменять) какую-либо настройку. Разница в том, что методы интерфейса ksDocument2D возвращают (изменяют) настройки не всей системы, а только одного документа.
Интерфейс KompasObject также содержит методы ksGetDocOptions и ksSetDocOptions. Они аналогичны одноименным методам интерфейса ksDocument2D и возвращают (изменяют) настройки текущего документа.
Метод ksGetDocOptions (обоих интерфейсов) имеет одно (недокументированное) отличие от метода ksGetSysOptions. Он несколько иначе обрабатывает настройку SHEET_OPTIONS_EX. Если метод ksGetSysOptions в случае успеха всегда возвращает единицу, то для метода ksGetDocOptions это не так. Возвращаемое им значение зависит от типа документа (стандартный или нет). В случае успеха он возвращает значение lt_DocSheetStandart(1) для стандартного документа и lt_DocSheetUser(2) для нестандартного документа.
Учтите, в случае многолистовых документов методы ksGetDocOptions возвращают настройки SHEET_OPTIONS_EX только для первого листа документа. Определить формат последующих листов средствами API интерфейсов версии 5 нельзя. Для этого нужно использовать API интерфейсов 7 версии.
Метод ksSetDocOptions (обоих интерфейсов) так же как и метод ksSetDocOptions не позволяет изменить формат документа.
Заключение
В данной статье мы познакомились со свойствами. К сожалению, в рамках одной статьи невозможно подробно описать их все. Мы не рассмотрели в частности настройки перекрывающихся объектов и настройки размеров, но они не очень сложны.
Продолжение следует, следите за новостями блога.
Сергей Норсеев, автор книги «Разработка приложений под КОМПАС в Delphi».
