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

---
title: "Интерфейс макроэлемента (ksMacro3DDefinition, IMacro3DDefinition)"
type: interface
api: [api7]
domain: [3d, 2d]
tags: [interface, api7, 3d, 2d, ksmacro3ddefinition]
sources:
  - 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    - состав недоступен для просмотра.
```
Примечание:
Свойство позволяет управлять видимостью состава макроэлемента.