Get best of the week

Work with the KOMPAS-3D API → Lesson 17 → Text document

In the previous lessons of the cycle, we examined in detail various means of working with text. KOMPAS allows you to create text documents. They differ from files created by a standard Windows notepad by the appearance of various types of main labels.

In this lesson we will look at how to open an existing one, create a new one, close and save a text document in various formats. Unfortunately, the API of interfaces of version 5 does not allow working with the contents of text documents, only with the contents of their title block. Therefore, consideration of text documents is limited only to this lesson. And on the next, we will return to graphic documents.



The content of the lesson series “Working with the KOMPAS-3D API”


  1. The basics
  2. Drawing design
  3. Correct connection to COMPASS
  4. Main inscription
  5. Graphic primitives
  10. ,

ksDocumentTxt


A text document is described by the ksDocumentTxt interface . It can be prepared by two methods: a method DocumentTxt () interface KompasObject and by the method ActiveDocumentTxt () of the same interface. Both of these methods have no input parameters and, if successful, return the ksDocumentTxt interface , and in case of an error, return NULL .

The only difference between them is that the ActiveDocumentTxt () method returns the interface of the currently active text document, and the DocumentTxt () method is an interface that is not yet bound to any document. Having received the interface, you can open an existing document or create a new one.

Opening an existing document


To open an existing text document using the method ksOpenDocument interface ksDocumentTxt . The following is its prototype

BOOL ksOpenDocument (
BSTR nameDoc,	//    
BOOL regim	//
);

The regim parameter sets the document editing mode. Its acceptable values ​​are given below:

0 - visible mode (the document is displayed on the screen);
1 - invisible mode (the document does not appear on the screen).
Invisible mode is used when you want to change the document so that the user does not see your actions.

If successful, the ksOpenDocument method returns true , and in case of an error, returns false .

Note: note that if the document you are opening is already open in KOMPAS, then the ksOpenDocument method will return true . In this case, you will work with a previously open document.

The following is an example program that demonstrates opening an existing text document.

//     
WideString wideStr = WideString(ExtractFileDir(Application->ExeName));
wideStr += L"\\TextDocument.kdw";
BSTR filePath = SysAllocString(wideStr.c_bstr());

// 
DocumentTxtPtr documentTxt;
documentTxt = static_cast<DocumentTxtPtr>(kompas->DocumentTxt());
documentTxt->ksOpenDocument(filePath, 0);

// 
documentTxt.Unbind();

This example opens the document "TextDocument.kdw" located in the application directory.

Text document options ( ksTextDocumentParam ).

Text document options are described by the ksTextDocumentParam interface .
It can be obtained using the method GetParamStruct interface KompasObject . To do this, you need to pass the constant ko_TextDocumentParam as the only parameter to this method . Consider the properties of this interface:

author - a string with the name of the author of the document;
comment - a string containing a comment on the document;
fileName- The full path to the file with a raster image;
mode - document editing mode. Valid values ​​are listed below:
0 - visible mode (the document is displayed on the screen and visible to the user);
1 - “blind” mode (the document is not visible to the user). This mode is usually used for covert work with multiple documents.
type - the integer type of the document. Its valid values ​​are shown in the table below.



Now consider the methods of the ksTextDocumentParam interface .

Init () - initializes the interface properties. It has no input parameters. In case of success, returns true , and in case of error - false .
GetSheetParam () - returns the sheet parameters interface. It has no input parameters. If the text document has sheets of standard size ( type == lt_DocTxtStandart ), then the method returns the ksStandartSheet interface . If the document has sheets of a non-standard size ( type == ls_DocTxtUser ), the ksSheetSize interface is returned . Both of these interfaces were covered in lesson 2 of the cycle.

The other methods of the ksTextDocumentParam interface are related to the design of the document. Since they do not allow you to change the design of the document (just read it), we will not consider them.

Document creation


To create a new text document using the method ksCreateDocument interface ksDocumentTxt . The following is its prototype.

BOOL ksCreateDocument (
LPDISPATCH par
);

The only parameter of this method is the ksTextDocumentParam interface , which sets the parameters of the created document. If successful, the method returns true , and in case of an error, false .

The following is the source code for a program demonstrating the creation of a new text document.

//  
TextDocumentParamPtr textDocumentParam;
textDocumentParam=static_cast<TextDocumentParamPtr>(kompas->GetParamStruct(ko_TextDocumentParam));
textDocumentParam->Init();
textDocumentParam->set_type(lt_DocTxtStandart);

//  
StandartSheetPtr standartSheet;
standartSheet = static_cast<StandartSheetPtr>(textDocumentParam->GetSheetParam());
standartSheet->set_format(ksFormatA4);

// 
DocumentTxtPtr documentTxt;
documentTxt = static_cast<DocumentTxtPtr>(kompas->DocumentTxt());
documentTxt->ksCreateDocument(textDocumentParam);

// 
standartSheet.Unbind();
textDocumentParam.Unbind();
documentTxt.Unbind();



As a result of the work of this program, a new text document will be created in KOMPAS. It may seem that KOMPAS did not create any design for it, but this is not so. It is necessary to click on the button “Display Design” on the COMPASS toolbar, as the main inscription appears. The figure below shows a fragment of the KOMPAS window with the “Display Appearance” button and the created text document.



Number of sheets and title block


Method ksGetDocumentPagesCount () interface ksDocumentTxt returns the number of pages in the document. It has no input parameters. If no document (open or created) is associated with the ksDocumentTxt interface , then the method returns zero .

Method GetStamp () interface ksDocumentTxt returns the interface ksStamp , describing the title block (considered at the 4 and 8 lessons). The method has no input parameters. The resulting ksStamp interface describes the title block of the first sheet of the document. GetStampEx

Methodallows you to get the title block of any sheet of the document. As the only parameter, it takes the sheet number, the title block interface ( ksStamp ) of which we want to get. Numbering of sheets is from 1 (per unit).

Document closing


To close a text document using the method ksCloseDocument () interface ksDocumentTxt . It has no input parameters and, if successful, returns true, and in case of an error, false . Note that the ksCloseDocument () method does not save the document.

Saving a document


Several methods are provided for saving a document in the ksDocumentTxt interface .

The ksSaveDocument method saves the document at the specified path. As the only parameter, it takes a string containing the full path to the file to which the document should be saved. If successful, it returns true , and in case of an error, false . The file is saved in the version of the used KOMPAS.

The ksSaveDocumentExEx method allows you to choose in which version to save the document. The following is a prototype of this method.

BOOL ksSaveDocumentEx (
BSTR fileName,	//   
long saveMode	//  
);

In contrast to the method ksSaveDocument here to add a parameter saveMode . Its valid values ​​are shown in the table below.



If successful, the ksSaveDocumentExEx method returns true , and in case of an error, false .

The SaveAsToRasterFormat method saves the document in raster format. The following is its prototype:

BOOL SaveAsToRasterFormat (
BSTR fileName,		//   
LPDISPATCH rasterPar	//    
);

Saving parameters in raster format are set using the ksRasterFormatParam interface (discussed in lesson 6 of the cycle). If successful, the SaveAsToRasterFormat method returns true , and in case of an error, false .

For interface ksRasterFormatParam need to use the method RasterFormatParam () interface ksDocumentTxt . This method has no input parameters and returns the interface of the save parameters in a raster format. In case of an error, it returns NULL . SaveAsToUncompressedRasterFormat

Methodsaves the document in raster format without compression. It has the same prototype as the SaveAsToRasterFormat method . If successful, the SaveAsToUncompressedRasterFormat method returns true , and in case of an error, false .

Document Filling


Unfortunately, the version 5 interface API discussed in our article series does not contain the means to populate a text document. To do this, you need to use the APIs of version 7 interfaces.

Conclusion

In this lesson we got acquainted with text documents. API version 5 allows you to open, create and save text documents, but not edit their contents. In subsequent tutorials in the series, we will no longer return to text documents.

To be continued, follow the news of the blog.

Sergey Norseev, Ph.D., author of the book "Application Development for COMPAS in Delphi."

More articles:


All Articles