Creating Text Objects (How to Create a Plug-In)

When implementing import filters or external commands, you will sometimes have to create complex objects that required more than simple geometrical data. The most common type of complex objects are texts. This chapter will show some examples on how to create these types of objects.

Text objects consist of three types of data: The text itself, a description of the font to be used, and the position of the text. First, let's create a standard text using the default parameters of the serving application:

C++ Source Code

// Variables required to create a text object.

bool              fResult;

MKI_TEXTSTANDARD  cData;

// Initialize the variables.

cData.Init();

// Create a standard text object.

MKI_ObjectOpen( MKI_OBJ_TEXTSTANDARD );

MKI_ObjectAddTextLong( L"This is an example!", false );

MKI_ObjectAddTextStandard( &cData );

// Insert the text object into the current drawing.

fResult = ( MKI_ObjectFastInsert() != nullptr );

This short code sequence will result in the text "This is an example" to be displayed in the page's center, using the default font (Arial) and size (5.0 mm).

For further information about the internal data block structure of the object MKI_OBJ_TEXTSTANDARD, see Object 35 "Standard Text".

Now, let's modify this code to allow the user to edit the text and select the font and size he wants to use (modified or added code sections will be displayed in red):

C++ Source Code

// Variables required to create a text object.

bool              fResult;

MKI_TEXTSTANDARD  cData;

MKI_STRLONGW      szText;

// Initialize the variables.

cData.Init();

MKI_InitW( szText );

// Display a dialog window to edit text and font.

MKI_DialogTextStandard( hGlobalWnd,

                        L"Edit Text", &cData, nullptr, szText );

// Create a standard text object.

MKI_ObjectOpen( MKI_OBJ_TEXTSTANDARD );

MKI_ObjectAddTextLong( szText, false );

MKI_ObjectAddTextStandard( &cData );

// Insert the text object into the current drawing.

fResult = ( MKI_ObjectFastInsert() != nullptr );

Still, the resulting text will be placed at the page's center. Usually, the plug-in wants to place the text at a known location in the drawing - either due to calculation or due to user entry. The text's position is determined by a matrix inside the text parameters. This matrix can be edited directly:

C++ Source Code

// Variables required to create a text object.

bool              fResult;

MKI_TEXTSTANDARD  cData;

MKI_STRLONGW      szText;

// Initialize the variables.

cData.Init();

MKI_InitW( szText );

// Display a dialog window to edit text and font.

MKI_DialogTextStandard( hGlobalWnd,

                        L"Edit Text", &cData, nullptr, szText );

// Create a standard text object.

cData.TextMatrix.m31 = -100.0;

cData.TextMatrix.m32 =   50.0;

MKI_ObjectOpen( MKI_OBJ_TEXTSTANDARD );

MKI_ObjectAddTextLong( szText, false );

MKI_ObjectAddTextStandard( &cData );

// Insert the text object into the current drawing.

fResult = ( MKI_ObjectFastInsert() != nullptr );

This modified code will result in a text placed at the coordinates (-100.0, 50.0), measured in millimeters relative to the page's center. Depending on the parameters the user chose during the MKI_DialogTextStandard command, the text will be rotated, distorted and/or stretched.

For creating a reference text, i.e. a text with a reference line and a frame surrounding the text, only a few more steps are necessary:

C++ Source Code

// Variables required to create a text object.

bool              fResult;

MKI_TEXTSTANDARD  cData;

MKI_TEXTREFERENCE cData2;

MKI_STRLONGW      szText;

// Initialize the variables.

cData.Init();

cData2.Init();

MKI_InitW( szText );

// Display a dialog window to edit text and font.

MKI_DialogTextStandard( hGlobalWnd,

                        L"Edit Text", &cData, &cData2, szText );

// Create a standard text object.

cData.TextMatrix.m31 = -100.0;

cData.TextMatrix.m32 =   50.0;

MKI_ObjectOpen( MKI_OBJ_TEXTREFERENCE );

MKI_ObjectAddTextLong( szText, false );

MKI_ObjectAddTextStandard( &cData );

MKI_ObjectAddTextReference( &cData2 );

// Insert the text object into the current drawing.

fResult = ( MKI_ObjectFastInsert() != nullptr );

This modified code will result in a reference text placed at the coordinates (-100.0, 50.0), measured in millimeters relative to the page's center. Depending on the parameters the user chose during the MKI_DialogTextStandard command, the text will be rotated, distorted and/or stretched. The reference point is located at the coordinates (-50.0, 0.0), so a reference line will be drawn between the text's coordinates (-100.0, 50.0) and the reference point (-50.0, 0.0).

Finally, let's create a frame text. This is a text whose position is not determined by an insertion point, but by a surrounding parallelogram. This allows two features that a standard text does not have. First, the text can be justified to the parallelogram's borders, and second, the text can flow oblique, i.e. the lines of text do not start at the same position:

For further information about the internal data block structure of the object MKI_OBJ_TEXTFRAME, see Object 36 "Frame Text".

The following code creates a frame text that has a similar form to the example shown above. Usually, the plug-in will let the user determine the shape of the surrounding frame, or calculate it based on other user input.

C++ Source Code

// Variables required to create a text object.

bool          fResult;

MKI_TEXTFRAME cData;

MKI_STRLONGW  szText;

// Initialize the variables.

cData.Init();

MKI_InitW( szText );

// Display a dialog window to edit text and font.

MKI_DialogTextFrame( hGlobalWnd,

                     L"Edit Text", &cData, szText );

// Create a frame text object.

MKI_ObjectOpen( MKI_OBJ_TEXTFRAME );

MKI_ObjectAddPoint( MKI_DB_POINT_ANY,  25.0, 100.0 );

MKI_ObjectAddPoint( MKI_DB_POINT_ANY, 125.0, 100.0 );

MKI_ObjectAddPoint( MKI_DB_POINT_ANY,   0.0,   0.0 );

MKI_ObjectAddTextLong( szText, false );

MKI_ObjectAddTextFrame( &cData );

// Insert the text object into the current drawing.

fResult = ( MKI_ObjectFastInsert() != nullptr );

For further information about the internal data block structure of the object MKI_OBJ_TEXTFRAME, see Object 36 "Text Frame".

Using the three types of text objects described above within your plug-ins will result in great drawings, allowing the user to use high-quality fonts and numerous text effects! So do not hesitate to use them...