Using the KOMPAS-3D API → Lesson 4 → Title bar

We continue the cycle of articles on working with the CAD API KOMPAS-3D Sergey Norseev, an engineer-programmer of the All-Russian Scientific-Research Institute “Signal”, the author of the book “Development of applications for KOMPAS in Delphi”. C ++ Builder is used as the medium. In previous lessons on the API KOMPAS Basics and Drawing Design, we proceeded from the fact that KOMPAS was not running, and we started it ourselves using the CreateInstance method. In the next lesson, the Correct connection to KOMPAS, we checked the presence of an already running KOMPAS and connected to it. In this lesson we will analyze how to fill the main inscription of the drawing.



The main title in KOMPAS is described by the ksStamp interface. To get a pointer to it, use the GetStamp () and GetStampEx () methods of the ksDocument2D , ksSpcDocument and ksDocumentTxt interfaces .

The only parameter of the GetStampEx method is the sheet number for which the title block interface is queried. Sheet numbering starts from one . The GetStamp method has no parameters. It returns the title block interface for the first sheet of a drawing or specification.
')
Before moving on to the ksStamp interface, we ’ll have a quick look at the ksTextItemParam interface.

Row component

The ksTextItemParam interface sets a text string component. Under the "component" refers to a string or special character. You can get this interface using the KompasObject interface's GetParamStruct method . To do this, as a single parameter, this method needs to pass the constant ko_TextItemParam .
There are only three properties for the ksTextItemParam interface.

• iSNumb - special character code. Special symbols and their numbers are listed in the NumbSymb.frw file included with the COMPASS kit. It is located in the SDK subdirectory of the main KOMPAS program directory.
• s is a string. If the ksTextItemParam interface is used to describe a special character, then this string is output after the special character.
• type - specifies the purpose of the interface. If the value of this property is SPECIAL_SYMBOL , then the interface describes a special character and a string. In this case, the line is located immediately behind the special character. If the value of this property is different from SPECIAL_SYMBOL , then the value of the iSNumb property is ignored, and the interface describes only the string s . Note that in the header files of old versions of KOMPAS this property is called type_ (with an underscore), and the constant SPECIAL_SYMBOL is not defined. It is equal to 17 .

In the KOMPAS-3D v17 documentation, the ksTextItemParam interface is described under the heading "Text Document (ksDocumentTxt Interface) / ksDocumentTxt - Methods / Interfaces of text element parameters /" .


Interface descriptions of text element parameters in the SDK

But when describing the type property, the constant SPECIAL_SYMBOL is not mentioned. It is given (though without a numerical value) in the section “Parameters and Constant Structures / Text Parameters Structures / TextItemParam - Parameters Structure of a Text Component” .


Description of the parameter structure of the text string component in the SDK

There are three more possible values ​​of the type property (FONT_SYMBOL, FRACTION_TYPE, SUM_TYPE) , but I did not understand their purpose. Experiments have shown that the behavior of the ksTextItemParam interface with these constants is no different from the zero value of the type property. True, I tested in the context of the main inscription, it is possible that this imposes some limitations.
Now consider the interface methods ksTextItemParam .

• GetItemFont () - returns the ksTextItemFont font parameters interface.
• SetItemFont - sets a new ksTextItemFont font parameters interface. The settable interface is passed as the value of a single parameter. If successful, the method returns true .
• Init () - initializes the interface properties with zeros. Returns true if successful.

Title block

As mentioned above, the main label is described by the ksStamp interface. This interface has no interesting properties, so we immediately turn to the consideration of its methods.

• ksClearStamp - clears the main label or its separate cell. The only parameter of this method is the number of the cell being cleared. If its value is zero, then the entire title block is cleared. If successful, this method returns a one , and in case of error, it returns zero .
• ksCloseStamp () - close main title. This means exit editing the title block. If successful, returns one , and in case of error, returns zero .
• ksColumnNumber - makes the current specified cell. As the only parameter, the number of the cell that is made current is passed to this method. If successful, this method returns a one , and in case of error, it returns zero .
• ksOpenStamp () - open the main label. This means entering the main title editing mode. It has no input parameters, returns one if successful, and zero if an error occurs .
• ksTextLine - write a line to the current cell. The current cell must be set using the ksColumnNumber method. The only parameter of the ksTextLine method is the pointer to the ksTextItemParam interface, which I mentioned just above. If successful, the ksTextLine method returns a one , and in case of an error, it returns zero .

This is an incomplete list of ksStamp interface methods , but they are quite enough to work with the title block . However, a number of comments need to be made.

1. All cells in the caption are numbered. There are no such numbers in the KOMPAS documentation, but there is a reference to the GOSTs on the main title (GOST 2.104-68 and GOST 2.104-2006). Also, the numbering of the cells of the main inscription can be viewed on the page . The figures below show the cell numbers of the main inscription of forms 2a and 2b, obtained experimentally.
   
   
   
   First sheet
   
   
   
   The second and subsequent sheets
   
2. The ksTextLine method is not the only way to write lines to the title block . Besides it, the ksStamp interface has a ksSetStampColumnText method that does the same. The only difference is that the string to be set in it is not set in the form of the ksTextItemParam interface, but in the form of the dynamic ksDynamicArray array. In this article we will not consider it.

Editing the title block

Filling the title block consists of several consecutive steps:

1. Get a pointer to the ksTextItemParam interface. To do this, use the GetParamStruct method of the ksKompasObject interface. The ksTextItemParam interface is needed to represent the lines written to the title block .
2. Get a pointer to the ksStamp title block interface using the GetStamp or GetStampEx methods of the document interfaces, specifications.
3. Call the ksOpenStamp () method of the ksStamp interface. So we enter the editing mode of the main label.
4. Prepare a string that will be written to the cell of the title block. The string must be represented as the ksTextItemParam interface.
5. Select the cell in which to write the string. To select a cell, use the ksColumnNumber method of the ksStamp interface.
6. Call the ksTextLine method of the ksStamp interface to write a line to the selected cell.
7. Repeat steps 4-6 for all lines written in the title block.
8. Close the main label with the ksCloseStamp method of the ksStamp interface.

Example

Below is a fragment of the program, demonstrating the work with the title block.

//    TextItemParamPtr TextItemParam; TextItemParam = (TextItemParamPtr)kompas->GetParamStruct(ko_TextItemParam); //    StampPtr Stamp; Stamp = (StampPtr)Document2D->GetStamp(); //   Stamp->ksOpenStamp(); Stamp->ksColumnNumber(1); TextItemParam->s = SysAllocString(L""); Stamp->ksTextLine(TextItemParam); Stamp->ksColumnNumber(3); TextItemParam->s = SysAllocString(L""); TextItemParam->type = SPECIAL_SYMBOL; TextItemParam->iSNumb = 51; Stamp->ksTextLine(TextItemParam); Stamp->ksColumnNumber(110); TextItemParam->set_s(SysAllocString(L" ..")); TextItemParam->type = 0; Stamp->ksTextLine(TextItemParam); //   Stamp->ksCloseStamp(); 

As a result of this program, you will see the title block shown in the figure below.


The main title, obtained by software.

I will make two comments on the above program fragment.

1. In this example, the code responsible for connecting to KOMPAS and creating a drawing is not given. I removed it to make the code easier to understand. How to connect to KOMPAS and customize the drawing (including choosing the format of the main inscription in it) was discussed in previous articles of the cycle.
2. If you look closely at the code above, you can see that in one case the line was set up in the ksTextItemParam interface by assigning a value to the s property, and in the other by calling the set_s method, about which I did not say anything. The fact is that in the COM technology all properties are represented as methods (as a rule, installation and reading). The name of these methods is formed as follows:
   get_ <property name>
   set_ <property name>
   In your programs, you can use any of these approaches (assigning a value to a property or calling a corresponding method).

Conclusion
In this article, we learned how to fill out the main title and met one of the interfaces for representing strings and special characters. In subsequent articles of the series, we will introduce other interfaces.

To be continued, stay tuned to the blog.

Sergey Norseev, author of the book “Development of applications for KOMPAS in Delphi”.