March 7, 2018 at 14:57Work with the KOMPAS-3D API → Lesson 7 → Introduction to Settings
- Tutorial
We continue the series of articles on working with the KOMPAS-3D CAD API Sergey Norseev, software engineer at VNII Signal JSC, author of the book "Application Development for KOMPAS in Delphi." The environment used is C ++ Builder. In this lesson we’ll talk about the settings of the COMPASS system.
To read the settings used method ksGetSysOptions interface KompasObject . The following is its prototype.
The optionsType parameter contains an integer that determines what kind of setting we want to get. The param parameter is a pointer to the interface into which the requested setting will be written. The type of this interface depends on what configuration we requested. The correspondence between optionsType and param is given in the table below.
Table 1. Correspondence between optionsType and param parameters
These constants are declared in the ldefin2d.h file .
If successful, the ksGetSysOptions method returns 1 , and in case of an error, returns zero .
In a number of places, the KOMPAS documentation indicates that the ksGetSysOptions method allows you to get one or another interface. However, it is not. This method allows you to fill out the interface, but not get it. Receive interface you have to do with the method GetParamStruct interface KompasObject . If you pass an unreceived interface to the ksGetSysOptions method , the method will return zero (error).
Looking at table 1, an assumption involuntarily arises that in order to get the SNAP_OPTIONS_EX setting , you must have an active document, and to get the SNAP_OPTIONS setting , a document is optional. This is actually not the case. As my experiments show, if you do not have an active document, the ksGetSysOptions method returns zero (error) for SNAP_OPTIONS , and not for SNAP_OPTIONS_EX . An error message is displayed on the screen.
Error message
Note also that if you encounter the error described above, then to fix it, you may need to restart KOMPAS. The fact is that all subsequent method callsksGetSysOptions , even if there is an active document, will fail.
A brief look at the ksSnapOptions interface . Its properties:
angSnap - whether the snap "angular snap" is enabled ( true - enabled, false - disabled);
angleStep - step of the angular snap ( in degrees );
commonOpt - a set of flags of common bindings (we will not consider);
grid - whether the snap "on the grid" is enabled ( true - enabled, false - disabled);
intersect - whether the intersection binding is enabled ( true - enabled, false- off);
localSnap - type of local binding;
nearestMiddle - whether the middle binding is enabled ( true - enabled, false - disabled);
nearestPoint - whether the “nearest point” binding is enabled ( true - enabled, false - disabled);
pointOnCurve - is the point-on-curve snap enabled ( true - enabled, false - disabled);
tangentToCurve - whether the “touch” binding is enabled ( true - enabled, false - disabled);
xyAlign - whether alignment binding is enabled ( true- on, false - off).
There are only three methods for the ksSnapOptions interface :
Init () - resets all properties; if successful, returns true ;
GetCommonOptValue and SetCommonOptValue - are designed to work with the commonOpt property .
The following is an example program that demonstrates how to use the ksSnapOptions interface .
In this example, we define the pitch of the corner snap. For example, on my home computer it was 45 ° (you may have a different one). Note that this is an extremely simplified example. It does not implement the correct connection to KOMPAS and omits error handling.
The sheet parameters in the settings context are described by the ksSheetOptions interface . This interface is similar to the ksSheetPar interface , which we examined in the second part of this series of articles. Consider the properties of the ksSheetOptions interface .
layoutName - the path to the design library.
sheetType - sheet type ( true - custom format, false - standard sheet);
shtType - type of title block from layoutName library.
The layoutName and shtType properties are similar to the ksSheetPar interface properties of the same name .
Interface MethodsThere are only two
ksSheetOptions : GetSheetParam - returns the sheet parameters interface ( ksStandartSheet for standard sheets and ksSheetSize for non-standard sheets). As a single parameter, it accepts a sheet format attribute ( true - non-standard sheet, false - standard sheet). Note that the parameter value must match the value of the sheetType property . Such duplication of information remained due to the need for compatibility with some old libraries.
Init () - resets all interface properties.
The following is an example of using this interface to determine the sheet format.
This example defines the parameters of a document sheet. If it has a non-standard size, then the line “Custom sheet” is displayed. If it has a standard format, a number indicating the format is displayed on the screen. For example, on my home computer the number 4 is displayed , which sets the sheet in A4 format (it may differ for you).
You have probably noticed that no document is created in the example. A reasonable question arises: what sheet format of the document we define in the program, if there is no document? The example defines the default format for the new document.
The KOMPAS documentation also mentions the constant SHEET_OPTIONS ( 3 ) as an analogue of the constant SHEET_OPTIONS_EX. However, the SHEET_OPTIONS constant is considered obsolete and is left for compatibility with some old libraries.
Background colors are described by the ksViewColorParam interface . Consider the properties of this interface.
BottomColor - lower transition color, available only for model documents.
Color - background color. If the value of this property is -1 , then the window color set in Windows is used.
TopColor - top transition color, available only for model documents.
UseGradient - sign of using gradient transition ( true - used, false - not used).
Although the KOMPAS API documentation does not explicitly state which color representation format is used, as in KOMPAS itself, the API uses the RGB format.
The method at the ksViewColorParam interface is only one.
Init () - reset the values of all interface properties. If successful, returns true .
The following is an example of using this interface.
In this example, the background color of the working field of the document is determined and displayed on the screen in the form of components of red, green and blue.
A variant is a variable that stores a value of some type. KOMPAS implements options using the ksLtVariant interface . It has a lot of properties and it is most convenient to consider them relative to the main property - valType . This property sets the type of value stored in the variant. Valid values for this property, as well as other properties of the ksLtVariant interface, are shown in the table below.
Table 2. ksLtVariant interface properties .
These constants are declared in the ldefin2d.h file .
For example, if the value of the valType property is ltv_Uint , then the value stored in the variant is in the uIntVal property. If the value of the valType property is ltv_Double , then the value stored in the variant is in the doubleVal property . There is only one
method for the ksLtVariant interface .
Init () - resets all interface properties. If successful, returns true .
According to Table 1, unit settings are requested using the LENGTHUNITS_OPTIONS constant . In this method ksGetSysOptions fills embodiment ksLtVariant type ltv_Short . The option records one of the valid values shown in the table below.
Table 3. Valid values for ksLtVariant of type ltv_Short
These constants are declared in the file ldefin2d.h .
Note that the unit for decimeters is not supported.
The following is an example program that demonstrates the definition of units.
This program determines the current unit of measurement and displays it on the screen.
In this example, we do not check the type of the variant, relying on the fact that it is of type ltv_Short . I did this to simplify the example. In real applications, you should always check the type of option.
To change the settings used method ksSetSysOptions interface KompasObject . The following is a prototype of this method.
It is easy to see that the prototype of this method is similar to the prototype of the ksGetSysOptions method . The relationship between the type of setting and the interface that describes it is also determined by Table 1. If successful, the ksSetSysOptions method returns 1 , and in case of an error, returns zero .
Note that the changed settings "exist" only during the current COMPASS session. After restarting it, all settings will return to their original value.
The following is an example program that demonstrates changing the background color of a document using the ksSetSysOptions method .
In this example, we set the background color to green.
Please note: COMPASS becomes visible almost immediately, before changing the setting. If KOMPAS is made visible after changing the setting, then it will not be changed, although the ksSetSysOptions method will return 1 .
Unfortunately, the ksSetSysOptions method does not allow you to change the format of the document sheet.
Interface ksDocument2D contains methods ksGetDocOptions and ksSetDocOptions , which are analogous to the methods ksGetSysOptions and ksSetSysOptions interface KompasObject . All these methods have the same prototype and allow you to read (change) any setting. The difference is that the ksDocument2D interface methods do not return (change) the settings of the entire system, but only one document.
The KompasObject interface also contains the ksGetDocOptions and ksSetDocOptions methods . They are similar to the ksDocument2D interface methods of the same name .and return (change) the settings of the current document.
The ksGetDocOptions method (of both interfaces) has one (undocumented) difference from the ksGetSysOptions method . It handles the SHEET_OPTIONS_EX setting a little differently . If the ksGetSysOptions method always returns 1 if successful , then this is not the case for the ksGetDocOptions method . The value returned by it depends on the type of document (standard or not). If successful, it returns lt_DocSheetStandart ( 1 ) for the standard document and lt_DocSheetUser ( 2 ) for the non-standard document.
Note that in the case of multi-sheet documents, the ksGetDocOptions methods return the SHEET_OPTIONS_EX settings only for the first sheet of the document. The format of subsequent sheets cannot be determined using API version 5 interfaces. To do this, you need to use the API interfaces 7 version.
The ksSetDocOptions method (of both interfaces), like the ksSetDocOptions method, does not allow you to change the document format.
Conclusion
In this article, we met with the properties. Unfortunately, within the framework of one article it is impossible to describe all of them in detail. In particular, we did not consider the settings for overlapping objects and the settings for sizes, but they are not very complicated.
To be continued, follow the news of the blog.
Sergey Norseev, author of the book "Application Development for COMPAS in Delphi."
The content of the lesson series “Working with the KOMPAS-3D API”
1. Basics
2. Drawing design
3. Correct connection to KOMPAS
4. Main label
5. Graphic primitives
6. Saving a document in various formats
7. Acquaintance with settings
8. More complex methods of writing to the main label
Reading settings
To read the settings used method ksGetSysOptions interface KompasObject . The following is its prototype.
long ksGetSysOptions (
long optionsType, //Тип настройки
LPDISPATCH param //Интерфейс настройки
);
The optionsType parameter contains an integer that determines what kind of setting we want to get. The param parameter is a pointer to the interface into which the requested setting will be written. The type of this interface depends on what configuration we requested. The correspondence between optionsType and param is given in the table below.
Table 1. Correspondence between optionsType and param parameters
These constants are declared in the ldefin2d.h file .
If successful, the ksGetSysOptions method returns 1 , and in case of an error, returns zero .
In a number of places, the KOMPAS documentation indicates that the ksGetSysOptions method allows you to get one or another interface. However, it is not. This method allows you to fill out the interface, but not get it. Receive interface you have to do with the method GetParamStruct interface KompasObject . If you pass an unreceived interface to the ksGetSysOptions method , the method will return zero (error).
Binding Settings
Looking at table 1, an assumption involuntarily arises that in order to get the SNAP_OPTIONS_EX setting , you must have an active document, and to get the SNAP_OPTIONS setting , a document is optional. This is actually not the case. As my experiments show, if you do not have an active document, the ksGetSysOptions method returns zero (error) for SNAP_OPTIONS , and not for SNAP_OPTIONS_EX . An error message is displayed on the screen.
Error message
Note also that if you encounter the error described above, then to fix it, you may need to restart KOMPAS. The fact is that all subsequent method callsksGetSysOptions , even if there is an active document, will fail.
A brief look at the ksSnapOptions interface . Its properties:
angSnap - whether the snap "angular snap" is enabled ( true - enabled, false - disabled);
angleStep - step of the angular snap ( in degrees );
commonOpt - a set of flags of common bindings (we will not consider);
grid - whether the snap "on the grid" is enabled ( true - enabled, false - disabled);
intersect - whether the intersection binding is enabled ( true - enabled, false- off);
localSnap - type of local binding;
nearestMiddle - whether the middle binding is enabled ( true - enabled, false - disabled);
nearestPoint - whether the “nearest point” binding is enabled ( true - enabled, false - disabled);
pointOnCurve - is the point-on-curve snap enabled ( true - enabled, false - disabled);
tangentToCurve - whether the “touch” binding is enabled ( true - enabled, false - disabled);
xyAlign - whether alignment binding is enabled ( true- on, false - off).
There are only three methods for the ksSnapOptions interface :
Init () - resets all properties; if successful, returns true ;
GetCommonOptValue and SetCommonOptValue - are designed to work with the commonOpt property .
The following is an example program that demonstrates how to use the ksSnapOptions interface .
//Подключаемся к КОМПАС
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();
In this example, we define the pitch of the corner snap. For example, on my home computer it was 45 ° (you may have a different one). Note that this is an extremely simplified example. It does not implement the correct connection to KOMPAS and omits error handling.
Sheet options
The sheet parameters in the settings context are described by the ksSheetOptions interface . This interface is similar to the ksSheetPar interface , which we examined in the second part of this series of articles. Consider the properties of the ksSheetOptions interface .
layoutName - the path to the design library.
sheetType - sheet type ( true - custom format, false - standard sheet);
shtType - type of title block from layoutName library.
The layoutName and shtType properties are similar to the ksSheetPar interface properties of the same name .
Interface MethodsThere are only two
ksSheetOptions : GetSheetParam - returns the sheet parameters interface ( ksStandartSheet for standard sheets and ksSheetSize for non-standard sheets). As a single parameter, it accepts a sheet format attribute ( true - non-standard sheet, false - standard sheet). Note that the parameter value must match the value of the sheetType property . Such duplication of information remained due to the need for compatibility with some old libraries.
Init () - resets all interface properties.
The following is an example of using this interface to determine the sheet format.
//Подключаемся к КОМПАС
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();
This example defines the parameters of a document sheet. If it has a non-standard size, then the line “Custom sheet” is displayed. If it has a standard format, a number indicating the format is displayed on the screen. For example, on my home computer the number 4 is displayed , which sets the sheet in A4 format (it may differ for you).
You have probably noticed that no document is created in the example. A reasonable question arises: what sheet format of the document we define in the program, if there is no document? The example defines the default format for the new document.
The KOMPAS documentation also mentions the constant SHEET_OPTIONS ( 3 ) as an analogue of the constant SHEET_OPTIONS_EX. However, the SHEET_OPTIONS constant is considered obsolete and is left for compatibility with some old libraries.
Background colors
Background colors are described by the ksViewColorParam interface . Consider the properties of this interface.
BottomColor - lower transition color, available only for model documents.
Color - background color. If the value of this property is -1 , then the window color set in Windows is used.
TopColor - top transition color, available only for model documents.
UseGradient - sign of using gradient transition ( true - used, false - not used).
Although the KOMPAS API documentation does not explicitly state which color representation format is used, as in KOMPAS itself, the API uses the RGB format.
The method at the ksViewColorParam interface is only one.
Init () - reset the values of all interface properties. If successful, returns true .
The following is an example of using this interface.
//Подключаемся к КОМПАС
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();
In this example, the background color of the working field of the document is determined and displayed on the screen in the form of components of red, green and blue.
Data Type Option
A variant is a variable that stores a value of some type. KOMPAS implements options using the ksLtVariant interface . It has a lot of properties and it is most convenient to consider them relative to the main property - valType . This property sets the type of value stored in the variant. Valid values for this property, as well as other properties of the ksLtVariant interface, are shown in the table below.
Table 2. ksLtVariant interface properties .
These constants are declared in the ldefin2d.h file .
For example, if the value of the valType property is ltv_Uint , then the value stored in the variant is in the uIntVal property. If the value of the valType property is ltv_Double , then the value stored in the variant is in the doubleVal property . There is only one
method for the ksLtVariant interface .
Init () - resets all interface properties. If successful, returns true .
Unit Settings
According to Table 1, unit settings are requested using the LENGTHUNITS_OPTIONS constant . In this method ksGetSysOptions fills embodiment ksLtVariant type ltv_Short . The option records one of the valid values shown in the table below.
Table 3. Valid values for ksLtVariant of type ltv_Short
These constants are declared in the file ldefin2d.h .
Note that the unit for decimeters is not supported.
The following is an example program that demonstrates the definition of units.
//Подключаемся к КОМПАС
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();
This program determines the current unit of measurement and displays it on the screen.
In this example, we do not check the type of the variant, relying on the fact that it is of type ltv_Short . I did this to simplify the example. In real applications, you should always check the type of option.
Change settings
To change the settings used method ksSetSysOptions interface KompasObject . The following is a prototype of this method.
long ksSetSysOptions (
long optionsType, //Тип настройки
LPDISPATCH param //Интерфейс параметров настройки
);
It is easy to see that the prototype of this method is similar to the prototype of the ksGetSysOptions method . The relationship between the type of setting and the interface that describes it is also determined by Table 1. If successful, the ksSetSysOptions method returns 1 , and in case of an error, returns zero .
Note that the changed settings "exist" only during the current COMPASS session. After restarting it, all settings will return to their original value.
The following is an example program that demonstrates changing the background color of a document using the ksSetSysOptions method .
//Подключаемся к КОМПАС
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();
In this example, we set the background color to green.
Please note: COMPASS becomes visible almost immediately, before changing the setting. If KOMPAS is made visible after changing the setting, then it will not be changed, although the ksSetSysOptions method will return 1 .
Unfortunately, the ksSetSysOptions method does not allow you to change the format of the document sheet.
KsGetDocOptions and ksSetDocOptions Methods
Interface ksDocument2D contains methods ksGetDocOptions and ksSetDocOptions , which are analogous to the methods ksGetSysOptions and ksSetSysOptions interface KompasObject . All these methods have the same prototype and allow you to read (change) any setting. The difference is that the ksDocument2D interface methods do not return (change) the settings of the entire system, but only one document.
The KompasObject interface also contains the ksGetDocOptions and ksSetDocOptions methods . They are similar to the ksDocument2D interface methods of the same name .and return (change) the settings of the current document.
The ksGetDocOptions method (of both interfaces) has one (undocumented) difference from the ksGetSysOptions method . It handles the SHEET_OPTIONS_EX setting a little differently . If the ksGetSysOptions method always returns 1 if successful , then this is not the case for the ksGetDocOptions method . The value returned by it depends on the type of document (standard or not). If successful, it returns lt_DocSheetStandart ( 1 ) for the standard document and lt_DocSheetUser ( 2 ) for the non-standard document.
Note that in the case of multi-sheet documents, the ksGetDocOptions methods return the SHEET_OPTIONS_EX settings only for the first sheet of the document. The format of subsequent sheets cannot be determined using API version 5 interfaces. To do this, you need to use the API interfaces 7 version.
The ksSetDocOptions method (of both interfaces), like the ksSetDocOptions method, does not allow you to change the document format.
Conclusion
In this article, we met with the properties. Unfortunately, within the framework of one article it is impossible to describe all of them in detail. In particular, we did not consider the settings for overlapping objects and the settings for sizes, but they are not very complicated.
To be continued, follow the news of the blog.
Sergey Norseev, author of the book "Application Development for COMPAS in Delphi."