kompas3d-mcp/docs/Kompas3D_SDK/interfaces/ksmacro3ddefinition.md

title, type, api, domain, tags, sources

title	type	api	domain	tags	sources
Интерфейс макроэлемента (ksMacro3DDefinition, IMacro3DDefinition)	interface	api7	3d 2d	interface api7 3d 2d ksmacro3ddefinition	ksmacro3ddefinition.html

*API интерфейсов. Версия 5 > Документ-модель (Интерфейсы - ksDocument3D, IDocument3D )  > Компонент сборки (деталь или подсборка). Интерфейсы ksPart и IPart  > Объект модели (Интерфейсы ksEntity и IEntity)  > Интерфейсы ksEntity и iEntity - Интерфейс элемента модели (оси, плоскости, формообразующего элемента)  > Интерфейсы поверхностей *

Интерфейс макроэлемента (ksMacro3DDefinition, IMacro3DDefinition)

Интерфейс макроэлемента документа-модели.

ksMacro3DDefinition	- интерфейс Automation
IMacro3DDefinition	- интерфейс COM
Описание:
Является 3D объектом, объединяющим в себе другие 3D объекты, в том числе и другие макроэлементы 3D, с возможностью скрывать свой состав, сохранять дополнительные пользовательские параметры и редактировать данный объект через библиотеку (если задано имя файла, имя библиотеки и команда редактирования).
Последовательность создания макроэлементов через API.
Создание макроэлемента с последующим добавлением объектов в его состав.

1. Создание пустого макроэлемента: •Создание у компонента макроэлемента (ksPart::NewEntity соответствующего типа). •Установка свойств макроэлемента (Видимость состава StaffVisible). •Создание макро в модели ksEntity::Create. •Установка пользовательских параметров SetUserParam.
2. Добавление существующих объектов в создаваемый макроэлемент: •Добавление объектов в коллекцию объектов, входящих в макро ksFeatureCollection; при этом в модели ничего не происходит. •Обновление макроэлемента ksEntity::Update; все новые объекты будут перенесены в макро в модели, у самих объектов тоже будут вызваны методы Update,
3. Создание новых объектов и добавление в макро: •Создание нового объекта (NewEntity). •Задание свойств нового объекта. •Добавление объекта в коллекцию объектов, входящих в макро, при этом в модели ничего не происходит. •Обновление макро ksEntity::Update - все новые, не созданные объекты, создадутся; у них вызовется ksEntity::Create. Создание макроэлемента с одновременным наполнением его объектами. •Создание у компонента макроэлемента (NewEntity соответствующего типа). •Задание свойств макроэлемента. •Создание при необходимости новых объектов (NewEntity) и задание их свойства (Create не вызывать), иначе переход к следующему пункту, •Добавление объектов в коллекцию объектов, входящих в макро, в модели ничего не происходит, •Создание макро в модели (ksEntity::Create) - все новые объекты создадутся, у них вызовется метод ksEntity::Create. Существующие объекты будут обновлены, у них вызовется метод ksEntity::Update.
4. Данный интерфейс можно получить, используя метод интерфейса элемента модели ksEntity::GetDefinition или IEntity::GetDefinition.

Add - Добавить объект в состав макроэлемента

Синтаксис Automation:

BOOL Add (LPDISPATCH obj);

Синтаксис COM:

BOOL Add (LPUNKNOWN obj);
Входные параметры:
obj    - указатель на интерфейс объекта, добавляемого в макроэлемент.
Возвращаемое значение:
TRUE    - в случае успешного завершения,
FALSE    - в случае неудачи.

Примечание:

1. В качестве входного параметра могут быть переданы следующие интерфейсы: •ksFeature, •ksEntity, •ksPart, •ksMateConstraint.
2. Если объект еще не создан в модели, то он создастся после вызова методов ksEntity::Create или ksEntity::Update макроэлемента. Для существовавших объектов в этом случае будет вызван метод ksEntity::Update.
3. Добавляемый объект должен принадлежать тому же компоненту, что и сам макроэлемент. Он не должен принадлежать другому макроэлементу.
4. При добавлении тела в макроэлемент в макроэлемент добавляются все операции данного тела на момент создания макроэлемента. Само тело в макроэлемент не добавляется.

ClearAllObj - Удалить все вспомогательные объекты, сохраненные в макро

Синтаксис Automation:

BOOL ClearAllObj();

Синтаксис COM:

BOOL ClearAllObj();
Возвращаемое значение:
TRUE    - в случае успешного завершения.

Примечания: Объект - это вспомогательная информация, и визуально никак не отображается. Например, если создать болт как макро относительно какого-нибудь объекта (например отверстие - цилиндрическая поверхность), и запомнить это отверстие в макро болта, то при следующем редактирование можно получить сохранённый указатель на отверстие.

Destroy - Разрушить макроэлемент

Синтаксис Automation:

BOOL Destroy();

Синтаксис COM:

BOOL Destroy();
Возвращаемое значение:
TRUE    - в случае успешного завершения,
FALSE    - в случае неудачи.

Примечание: После вызова этого метода макроэлемент будет разрушен, а все объекты, входившие в его состав, станут самостоятельными.

DoubleClickEditOff - Получить признак внешнего редактирования детали

Тип данных: BOOL Синтаксис Automation:

off = iObj.DoubleClickEditOff    Получить свойство (* )
iObj.DoubleClickEditOff = off    Установить свойство(* )
off = iObj.GetDoubleClickEditOff()    Получить свойство (**)
iObj.SetDoubleClickEditOff (off)    Установить свойство (**)

Примечание: Свойство позволяет для библиотечных элементов, имеющих макропараметры, оставить стандартное поведение компонента и объектов, входящих в состав компонента. Для этого нужно установить значение свойства равным TRUE.

FeatureCollection - Получить массив объектов, входящих в макроэлемент

Синтаксис Automation:

LPDISPATCH FeatureCollection();

Синтаксис COM:

LPFEATURECOLLECTION FeatureCollection();
Возвращаемое значение:
- указатель на интерфейс ksFeatureCollection или IFeatureCollection

Примечание:

1. Через данную коллекцию можно добавлять только уже созданные объекты. Добавление новых (несозданных) объектов осуществляется при помощи метода ksMacro3DDefinition::Add.
2. Метод ksFeatureCollection::Refresh наполняет содержимое коллекции объектами, входящими в макроэлемент. Все изменения, сделанные в коллекции, после вызова этого метода будут потеряны.
3. При добавлении объектов в коллекцию добавляемый объект должен принадлежать тому же компоненту, что и сам макроэлемент; он не должен принадлежать другому макроэлементу.

GetCountObj - Получить количество вспомогательных объектов, сохраненных в макро

Синтаксис Automation:

long GetCountObj();

Синтаксис COM:

long GetCountObj();
Возвращаемое значение:
- Количество вспомогательных объектов, сохранённых в макро.

Примечания: Объект - это вспомогательная информация и визуально никак не отображается. Например, если создать болт как макро относительно какого-нибудь объекта (например отверстие - цилиндрическая поверхность), и запомнить это отверстие в макро болта, то при следующем редактирование можно получить сохранённый указатель на отверстие.

GetObject - Получить указатель на вспомогательный объект, сохраненный в макро по индексу

Синтаксис Automation:

LPDISPATCH GetObject (long index);

Синтаксис COM:

LPUNKNOWN GetObject (long index);
Входные параметры:
index    - номер объекта.
Возвращаемое значение:
- Указатель на интерфейс IDispatch или IUnknown сохранённого объекта.

Примечания: Объект - это вспомогательная информация, и визуально никак не отображается. Например, если создать болт как макро относительно какого-нибудь объекта (например отверстие - цилиндрическая поверхность), и запомнить это отверстие в макро болта, то при следующем редактирование можно получить сохранённый указатель на отверстие. См. также: IMacro3DDefinition::SetObject

GetUserLibraryCommand - Получить номер команды пользовательской библиотеки, при помощи которой можно редактировать макроэлемент

Интерфейс. Аналог данного метода при использовании Automation - ksUserParam::number. Пример... Синтаксис COM:

long GetUserLibraryCommand();
Возвращаемое значение:
Номер библиотечной команды    - в случае успешного завершения,
-1    - если библиотеки нет.

GetUserLibraryFileName - Получить имя файла пользовательской библиотеки, при помощи которой можно редактировать макроэлемент

Аналог данного метода при использовании Automation - ksUserParam::fileName. Пример... Синтаксис COM:

LPOLESTR GetUserLibraryFileName();
Возвращаемое значение:
Имя файла пользовательской библиотеки    - в случае успешного завершения,
NULL    - если имя файла библиотеки не задано.

GetUserLibraryName - Получить имя пользовательской библиотеки, при помощи которой можно редактировать макроэлемент

Аналог данного метода при использовании Automation - ksUserParam::libName. Пример.... Синтаксис COM:

LPOLESTR GetUserLibraryName();
Возвращаемое значение:
Имя пользовательской библиотеки    - в случае успешного завершения,
NULL    - если имя библиотеки не задано.

GetUserParam - Получить параметры пользователя

Синтаксис Automation:

BOOL GetUserParam (LPDISPATCH userPars);
Выходные параметры:
userPars    - указатель на интерфейс пользовательских параметров ksUserParam.

Синтаксис COM:

BOOL GetUserParam (void *value,
unsigned int size);
Входные параметры:
value    - указатель на пользовательскую структуру параметров,
size    - размер структуры параметров.
Возвращаемое значение:
TRUE    - в случае успешного завершения,
FALSE    - в случае неудачи.

Примечание: Способ получения пользовательских данных (userPars) должен совпадать со способом их сохранения (void*, SAFEARRAY, или DynamicArray) через ksMacro3DDefinition::SetUserParam. – Если пользовательские данные были сохранены через SAFEARRAY (userPars), то перед их получением нужно создать SAFEARRAY соответствующего размера (размер данных можно определить при помощи ksMacro3DDefinition::GetUserParamSize). – Если пользовательские данные были сохранены через ksUserParam::SetUserArray, то перед их получением нужно создать UserArray, аналогичный по структуре используемому при сохранении, и передать его в ksUserParam::SetUserArray.

GetUserParamSize - Получить размер структуры параметров пользователя, хранимых в макроэлементе

Синтаксис Automation:

long GetUserParamSize();

Синтаксис COM:

long GetUserParamSize();
Возвращаемое значение:
- Размер структуры параметров пользователя, хранимых в макроэлементе в байтах.

PropertyObjectEditable - Поддерживается интерфейс внешних свойств объекта

Тип данных: BOOL Синтаксис Automation:

PropertyObjectEditable = Object.PropertyObjectEditable    Получить свойство (* )
Object.PropertyObjectEditable = PropertyObjectEditable    Установить свойство(* )
PropertyObjectEditable = Object.GetPropertyObjectEditable()    Получить свойство (**)
Object.SetPropertyObjectEditable( PropertyObjectEditable )    Установить свойство (**)

SetObject - Сохранить указатель на объект в макро по индексу

Синтаксис Automation:

BOOL SetObject(long index, LPDISPATCH obj);

Синтаксис COM:

BOOL SetObject(long index, LPUNKNOWN obj);
Входные параметры:
index    - номер объекта,
obj    - указатель на интерфейс объекта.
Возвращаемое значение:
TRUE    - в случае успешного завершения,
FALSE    - в случае неудачи.

Примечания: Объект - это вспомогательная информация, и визуально никак не отображается. Например, если создать болт как макро относительно какого-нибудь объекта (например отверстие - цилиндрическая поверхность), и запомнить это отверстие в макро болта, то при следующем редактирование можно получить сохранённый указатель на отверстие. См. также: IMacro3DDefinition::GetObject

SetUserParam - Установить параметры пользователя

Синтаксис Automation:

BOOL SetUserParam (LPDISPATCH userPars);
Входные параметры:
userPars    - указатель на интерфейс пользовательских параметров ksUserParam.

Синтаксис COM:

BOOL SetUserParam (void *value,
unsigned int size,
LPOLESTR nameFile,
LPOLESTR nameLib,
int number );
Входные параметры:
value    - указатель на пользовательскую структуру параметров,
size    - размер структуры параметров,
nameFile    - имя файла прикладной библиотеки для последующего редактирования через библиотеку (0 - запоминается текущая библиотека),
nameLib    - имя прикладной библиотеки для последующего редактирования через библиотеку (0 - запоминается текущая библиотека),
number    - номер команды в прикладной библиотеке для последующего редактирования через библиотеку (-1 - запоминается текущая команда).
Возвращаемое значение:
TRUE    - в случае успешного завершения,
FALSE    - в случае неудачи.

Примечания: Данный метод позволяет сохранить параметры пользователя для последующего редактирования с помощью библиотеки.

StaffVisible - Управление видимостью состава

Тип данных: BOOL Синтаксис Automation:

staffVisible = iObject.StaffVisible    Получить свойство (* )
iObject.StaffVisible = staffVisible    Установить свойство(* )
staffVisible = iObject.GetStaffVisible()    Получить свойство (**)
iObject.SetStaffVisible (staffVisible)    Установить свойство (**)

Синтаксис COM:

staffVisible = iObject->GetStaffVisible()    Получить свойство
iObject->SetStaffVisible (&StaffVisible)    Установить свойство
Значение свойства:
TRUE    - состав объекта можно посмотреть в Дереве построения,
FALSE    - состав недоступен для просмотра.

Примечание: Свойство позволяет управлять видимостью состава макроэлемента.