Using the KOMPAS-3D API → Lesson 14 → Multiline Text

  • Tutorial
In the previous lesson, we looked at how to display multi-line text using a paragraph. The described method requires manual traversal of the array of output strings. In this lesson we will consider an alternative method, devoid of this disadvantage. It is based on the ksTextParam interface and the ksTextEx method .



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


  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. Getting to know the settings
  8. More sophisticated writing methods
  9. Reading the caption cells
  10. Special characters including string
  11. Simple text lettering
  12. Compound strings
  13. Paragraphs
  14. Multiline text

Text Parameters ( ksTextParam )


The ksTextParam interface is an add-on to the ksParagraphParam interface and an array of output strings. To get it, you need to call the KompasObject interface's GetParamStruct method with the constant ko_TextParam . There are no properties
for the ksTextParam interface , so we immediately proceed to consider its methods.
GetParagraphParam () - returns the parameter interface of the ksParagraphParam paragraph. It has no input parameters.
GetTextLineArr () - returns a dynamic ksDynamicArray array of output lines. It has no input parameters.
Init ()- resets text options. It has no input parameters. Returns true if successful.
SetParagraphParam - sets the parameters of a paragraph. As a single parameter, it accepts the ksParagraphParam interface , which contains the parameters to be set. Returns true if successful , false if error returns .
SetTextLineArr - sets an array of output lines. As the only parameter, it takes the ksDynamicArray interface , which contains output strings. Returns true if successful , false if error returns .
The dynamic array returned by the methodGetTextLineArr () and set by the SetTextLineArr method is of type TEXT_LINE_ARR . This means that the elements of the array are the ksTextLineParam interfaces .

KsTextEx method


To display multi-line text, use the ksDocument2D interface ksTextEx method . Below is its prototype:

long ksTextEx (
LPDISPATCH txtParam,	// Интерфейс ksTextParam
long align		// Выравнивание текста
);

The table below shows the valid values ​​for the align parameter .



If successful, the ksTextEx method returns an integer pointer to the generated text. And in case of an error - zero .

Example


Below is a fragment of a program that demonstrates the output of multi-line text using the ksTextEx method.
//Подготавливаем массивы
DynamicArrayPtr items;
items = static_cast<DynamicArrayPtr>(kompas->GetDynamicArray(TEXT_ITEM_ARR));
items->ksClearArray();
DynamicArrayPtr lines;
lines = static_cast<DynamicArrayPtr>(kompas->GetDynamicArray(TEXT_LINE_ARR));
lines->ksClearArray();
//Подготлавиваем другие интерфейсы
TextLineParamPtr lineParam;
lineParam = static_cast<TextLineParamPtr>(kompas->GetParamStruct(ko_TextLineParam));
lineParam->Init();
TextItemParamPtr itemParam;
itemParam = static_cast<TextItemParamPtr>(kompas->GetParamStruct(ko_TextItemParam));
itemParam->Init();
TextItemFontPtr itemFont = static_cast<TextItemFontPtr>(itemParam->GetItemFont());
//Наполняем массив строк
BSTR str = SysAllocString(OLESTR("Обычный текст"));
itemParam->set_s(str);
items->ksAddArrayItem(-1, itemParam);
lineParam->SetTextItemArr(items);
lines->ksAddArrayItem(-1, lineParam);
lineParam->Init();
SysFreeString(str);
str = NULL;
itemFont->set_bitVector(NEW_LINE | ITALIC_OFF);
str = SysAllocString(OLESTR("Текст без наклона"));
itemParam->set_s(str);
items->ksAddArrayItem(-1, itemParam);
lineParam->SetTextItemArr(items);
lines->ksAddArrayItem(-1, lineParam);
lineParam->Init();
SysFreeString(str);
str = NULL;
itemFont->set_bitVector(NEW_LINE | ITALIC_ON | BOLD_ON);
str = SysAllocString(OLESTR("Полужирный текст"));
itemParam->set_s(str);
items->ksAddArrayItem(-1, itemParam);
lineParam->SetTextItemArr(items);
lines->ksAddArrayItem(-1, lineParam);
lineParam->Init();
SysFreeString(str);
str = NULL;
itemFont->set_bitVector(NEW_LINE | BOLD_OFF | UNDERLINE_ON);
str = SysAllocString(OLESTR("Подчеркнутый текст"));
itemParam->set_s(str);
items->ksAddArrayItem(-1, itemParam);
lineParam->SetTextItemArr(items);
lines->ksAddArrayItem(-1, lineParam);
lineParam->Init();
SysFreeString(str);
str = NULL;
itemParam.Unbind();
lineParam.Unbind();
itemFont.Unbind();
items.Unbind();
//Подготавливаем интерфейс параметров параграфа
ParagraphParamPtr paragraphParam;
paragraphParam= static_cast<ParagraphParamPtr>(kompas->GetParamStruct(ko_ParagraphParam));
paragraphParam->Init();
paragraphParam->set_x(100.0);
paragraphParam->set_y(100.0);
paragraphParam->set_width(60.0);
paragraphParam->set_hFormat(2);
//Подготавливаем интерфейс параметров текста
TextParamPtr textParam = static_cast<TextParamPtr>(kompas->GetParamStruct(ko_TextParam));
textParam->SetParagraphParam(paragraphParam);
textParam->SetTextLineArr(lines);
//Выводим текст
Document2D->ksTextEx(textParam, 1);
lines->ksDeleteArray();
lines.Unbind();
paragraphParam.Unbind();
textParam.Unbind();
//Делаем КОМПАС видимым
kompas->set_Visible(true);
kompas.Unbind();


In this example, we do not bypass the array, but once we call the desired method. He finds the NEW_LINE flags and interprets them correctly. Please note: each new line with this flag is drawn up in a separate ksTextLineParam interface . If you arrange them in one ksTextLineParam , COMPASS will ignore the NEW_LINE flag . The figure below shows the result of this program. Conclusion In this lesson we looked at an alternative version of the output of multi-line text. It is somewhat more complicated than what we considered earlier, but does not require manual traversal of the array of strings. Which of them to use is up to you.







In the next lesson, we will again return to the subject of compound lines and consider the documented way to create them using paragraphs.

To be continued, stay tuned to the blog.

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

Also popular now: