Using the KOMPAS-3D API → Lesson 10 → Special characters including the string

We already got acquainted with special characters in 4 lessons of our cycle. It showed their simplest use. It also said that if the ksTextItemParam interface sets both a special character and a string, then the line is located immediately after the special character. However, there are special characters that violate this rule. We will talk about them today.

Content of the cycle of lessons “Working with the API KOMPAS-3D”

1. The basics
2. Drawing design
3. Correct connection to COMPAS
4. Title block
5. Graphic primitives
6. Save the document in various formats
7. Introduction to the settings
8. More sophisticated writing methods
9. Reading the caption cells
10. Special characters including string

Special characters including string

A table of special characters is in Appendix V of the KOMPAS main reference.

Special characters with numbers 78-80 , 83 , 93-99 , 171 and 172 include a string in their composition. In this case, the string s of the ksTextItemParam interface is not located after the special character, but inside it. For example, the special character number 80 displays text in a box. Below is an example of a program that demonstrates working with such a special character.

//    TextItemParamPtr TextItemParam; TextItemParam=(TextItemParamPtr)kompas->GetParamStruct(ko_TextItemParam); //  TextItemParam->set_type(SPECIAL_SYMBOL); TextItemParam->set_iSNumb(98); BSTR str = SysAllocString(L""); TextItemParam->set_s(str); SysFreeString(str); //    StampPtr Stamp; Stamp=(StampPtr)Document2D->GetStamp(); //     Stamp->ksOpenStamp(); Stamp->ksColumnNumber(1); Stamp->ksTextLine(TextItemParam); //     Stamp->ksCloseStamp(); Stamp.Unbind(); TextItemParam.Unbind(); Document2D.Unbind(); //   kompas->Visible = true; kompas.Unbind(); 

For simplicity, in this example, the code responsible for the creation and execution of the document is omitted (this topic was covered in previous lessons of the cycle). The figure below shows the title block formed by this program.



For simplicity, we fill only one cell. Special character number 98 identifies the square root character. Note that the value of the s property of the ksTextItemParam interface is completely under the root sign. Other special characters that include the string work in the same way.

Special characters and ksTextLineParam

Special characters are not limited to the ksTextItemParam interface. Consider the example below.

 //     TextItemParamPtr TextItemParam; TextItemParam=(TextItemParamPtr)kompas->GetParamStruct(ko_TextItemParam); //     DynamicArrayPtr DynamicArray; DynamicArray=(DynamicArrayPtr)kompas->GetDynamicArray(TEXT_ITEM_ARR); //   TextItemParam->set_type(SPECIAL_SYMBOL); TextItemParam->set_iSNumb(98); BSTR str = SysAllocString(L"1 "); TextItemParam->set_s(str); SysFreeString(str); DynamicArray->ksAddArrayItem(-1, TextItemParam); //   TextItemParam->Init(); TextItemParam->set_type(SPECIAL_SYMBOL); TextItemParam->set_iSNumb(169); str = SysAllocString(L"2 "); TextItemParam->set_s(str); SysFreeString(str); DynamicArray->ksAddArrayItem(-1, TextItemParam); //   TextItemParam->Init(); TextItemParam->set_type(0); str = SysAllocString(L" 3"); TextItemParam->set_s(str); SysFreeString(str); DynamicArray->ksAddArrayItem(-1, TextItemParam); //   ksTextLineParam TextLineParamPtr TextLineParam; TextLineParam=(TextLineParamPtr)kompas->GetParamStruct(ko_TextLineParam); TextLineParam->SetTextItemArr(DynamicArray); //    StampPtr Stamp; Stamp=(StampPtr)Document2D->GetStamp(); //     Stamp->ksOpenStamp(); Stamp->ksColumnNumber(1); Stamp->ksTextLine(TextLineParam); //     Stamp->ksCloseStamp(); Stamp.Unbind(); TextItemParam.Unbind(); TextLineParam.Unbind(); DynamicArray->ksDeleteArray(); DynamicArray.Unbind(); Document2D.Unbind(); //   kompas->Visible = true; kompas.Unbind(); 

In this example, a line consisting of three components is entered into the main label. The first two contain a special character and a string. The third component contains only a string, without a special character. Let's look at the result of the program (the figure below shows only the generated line without the main inscription).



Please note that the second special character includes both the line “Page 2” and the line “Page 3” , which we planned to bring out without the special character. Moreover, both of these lines were included in the first special character (we also did not plan this). This example shows two important points:

• special characters can include other special characters;
• the special character applies to all components that are part of the ksTextLineParam interface.

A reasonable question arises - is there a way to limit the effect of a special character? Yes there is. But in order to understand it, you must first get acquainted with the interface ksTextItemFont .

Font Parameters Text Components ( ksTextItemFont )

According to the documentation, the ksTextItemFont interface describes the font parameters of the text component. But in fact, its capabilities exceed the simple description of the font used. This interface allows you to form multiple lines (about them - in the next cycle lessons).

You can get it in several ways. First, using the KompasObject interface's GetParamStruct method : for this, the constant ko_TextItemFont must be passed to this method as a single parameter. Secondly, using the GetItemFont method of the ksTextItemParam interface. This method has no input parameters and returns the ksTextItemFont interface already associated with the text component.

Consider the properties of the interface ksTextItemFont .
bitvector - a bit vector that defines the signs of the text (they will be discussed in detail in the next lessons of the cycle).
color - the color of characters in the format RGB.
fontName is the string with the font name.
height - the height of the font in millimeters.
ksu is the stretch ratio of the text.
There are only three methods for the ksTextItemFont interface.
Init () resets all interface properties. It has no input parameters. If successful, returns TRUE , and in case of error, returns FALSE .
GetBitVectorValue returns the value of a separate flag from the bitvector set. As a single parameter takes a flag whose value we want to determine. If it is set, the method returns TRUE ; if cleared, it is FALSE .
SetBitVectorValue changes the value of a single flag. The following is a prototype of this method:

 BOOL SetBitVectorValue ( long bitVector, //  BOOL state //   ); 

If the value of the state parameter is TRUE , then the bitVector flag is set , otherwise it is reset.
If successful, the SetBitVectorValue method returns TRUE , and in case of error, it returns FALSE .
The GetBitVectorValue and SetBitVectorValue methods allow you to work with the bitvector property without directly referring to it.

Restriction of the special character

To control special characters are two flags. They are listed in the table below.



We have already considered the SPECIAL_SYMBOL flag when describing the ksTextItemParam interface. It is needed to indicate that a special character is displayed. This same flag is duplicated in the bitVector property of the ksTextItemFont interface (as shown by my experiments, this duplication is optional).

The second flag ( SPECIAL_SYMBOL_END ) makes sense only for special characters that include the string. It cancels the special character. The lines displayed after this flag are not included in the special character.

The combined effect of both flags cancels the effect of the special character. In this case, the special character will not be displayed in the document.

Example

Below is the source code of the modified program. It uses the flags described above to implement the correct component output.

 //     TextItemParamPtr TextItemParam; TextItemParam=(TextItemParamPtr)kompas->GetParamStruct(ko_TextItemParam); //     DynamicArrayPtr DynamicArray; DynamicArray=(DynamicArrayPtr)kompas->GetDynamicArray(TEXT_ITEM_ARR); //   TextItemParam->set_type(SPECIAL_SYMBOL); TextItemParam->set_iSNumb(98); BSTR str = SysAllocString(L"1 "); TextItemParam->set_s(str); SysFreeString(str); DynamicArray->ksAddArrayItem(-1, TextItemParam); //   TextItemFontPtr TextItemFont; TextItemParam->Init(); TextItemFont=(TextItemFontPtr)TextItemParam->GetItemFont(); TextItemFont->set_bitVector(SPECIAL_SYMBOL_END); DynamicArray->ksAddArrayItem(-1, TextItemParam); TextItemFont->Init(); TextItemFont.Unbind(); //   TextItemParam->Init(); TextItemParam->set_type(SPECIAL_SYMBOL); TextItemParam->set_iSNumb(169); str = SysAllocString(L"2 "); TextItemParam->set_s(str); SysFreeString(str); DynamicArray->ksAddArrayItem(-1, TextItemParam); //      TextItemParam->Init(); TextItemFont=(TextItemFontPtr)TextItemParam->GetItemFont(); TextItemFont->set_bitVector(SPECIAL_SYMBOL_END); TextItemParam->set_type(0); str = SysAllocString(L"  3"); TextItemParam->set_s(str); SysFreeString(str); DynamicArray->ksAddArrayItem(-1, TextItemParam); TextItemFont.Unbind(); //   ksTextLineParam TextLineParamPtr TextLineParam; TextLineParam=(TextLineParamPtr)kompas->GetParamStruct(ko_TextLineParam); TextLineParam->SetTextItemArr(DynamicArray); //    StampPtr Stamp; Stamp=(StampPtr)Document2D->GetStamp(); //     Stamp->ksOpenStamp(); Stamp->ksColumnNumber(1); Stamp->ksTextLine(TextLineParam); //     Stamp->ksCloseStamp(); Stamp.Unbind(); TextItemParam.Unbind(); TextLineParam.Unbind(); DynamicArray->ksDeleteArray(); DynamicArray.Unbind(); Document2D.Unbind(); //   kompas->Visible = true; kompas.Unbind(); 

The only difference between this example and the previous one is that after each special character the component is displayed, for which the SPECIAL_SYMBOL_END flag is set in the ksTextItemFont interface. Its only purpose is to cancel the action of a special character. In the first case, it does not contain any data (except for the flag, of course). And in the second case contains the string "Page 3" .

Combining the SPECIAL_SYMBOL_END flag with the output of the second special character is impossible. As in this case, this flag will cancel the effect of both special characters. The line “Page 2” will be displayed without crossing it out.

The figure below shows the line displayed by this program in the title block.



As you can see, now the effect of special characters applies only to "its" component.

Enclosed special characters

The first example of our lesson today clearly shows that special characters can be invested in each other. The flag SPECIAL_SYMBOL_END cancels the effect of one (last) special character. This allows you to build complex strings with embedded special characters.

Below is the source code of a refined example in which the substring “Page 2” is also included in the expression under the square root sign.

 //     TextItemParamPtr TextItemParam; TextItemParam=(TextItemParamPtr)kompas->GetParamStruct(ko_TextItemParam); //     DynamicArrayPtr DynamicArray; DynamicArray=(DynamicArrayPtr)kompas->GetDynamicArray(TEXT_ITEM_ARR); //   TextItemParam->set_type(SPECIAL_SYMBOL); TextItemParam->set_iSNumb(98); BSTR str = SysAllocString(L"1 "); TextItemParam->set_s(str); SysFreeString(str); DynamicArray->ksAddArrayItem(-1, TextItemParam); //   TextItemParam->Init(); TextItemParam->set_type(SPECIAL_SYMBOL); TextItemParam->set_iSNumb(169); str = SysAllocString(L"2 "); TextItemParam->set_s(str); SysFreeString(str); DynamicArray->ksAddArrayItem(-1, TextItemParam); //   TextItemFontPtr TextItemFont; TextItemParam->Init(); TextItemFont=(TextItemFontPtr)TextItemParam->GetItemFont(); TextItemFont->set_bitVector(SPECIAL_SYMBOL_END); DynamicArray->ksAddArrayItem(-1, TextItemParam); //      TextItemParam->set_type(0); str = SysAllocString(L"  3"); TextItemParam->set_s(str); SysFreeString(str); DynamicArray->ksAddArrayItem(-1, TextItemParam); TextItemFont.Unbind(); //   ksTextLineParam TextLineParamPtr TextLineParam; TextLineParam=(TextLineParamPtr)kompas->GetParamStruct(ko_TextLineParam); TextLineParam->SetTextItemArr(DynamicArray); //    StampPtr Stamp; Stamp=(StampPtr)Document2D->GetStamp(); //     Stamp->ksOpenStamp(); Stamp->ksColumnNumber(1); Stamp->ksTextLine(TextLineParam); //     Stamp->ksCloseStamp(); Stamp.Unbind(); TextItemParam.Unbind(); TextLineParam.Unbind(); DynamicArray->ksDeleteArray(); DynamicArray.Unbind(); Document2D.Unbind(); //   kompas->Visible = true; kompas.Unbind(); 

Please note that after the output of the substring “Page 2” we twice output the component with the flag SPECIAL_SYMBOL_END (the first time is as part of an empty component, the second is together with the line “Page 3” ). This is necessary to cancel the special characters. The first time we cancel the special symbol 169 (strikethrough), the second time - 98 (square root). If we only deduced one component with the flag SPECIAL_SYMBOL_END , it would cancel only the special symbol 169 , but not 98 . In this case, the line “Page 3” would not be crossed out, but would be part of the expression under the root sign.
The figure below shows the result of this program.



Conclusion

As part of this lesson, we met with special characters that include a string. As you have seen, they are significantly different from simple special characters (for example, letters of the Greek alphabet). Although we showed them on the example of the main inscription, it should not confuse you. These characters can be used in other methods of text output. We will consider one of these methods in the next lesson.

To be continued, stay tuned to the blog.

Sergey Norseev, Ph.D., author of the book “Development of applications for COMPAS in Delphi”.