HomePowerBuilderAppeon Documentation Center

InsertDocument

Description

Inserts a rich text format or plain text file into a RichTextEdit control, DataWindow control, or DataStore object. The new content is added in one of two ways:

  • The new content can be inserted at the insertion point.

  • The new content can replace all existing content.

Applies to

RichTextEdit controls, DataWindow controls, and DataStore objects

Syntax

rtename.InsertDocument ( filename, clearflag { , filetype,{ encoding } } )

Argument

Description

rtename

The name of the RichTextEdit control, DataWindow control, or DataStore object in which you want to display the file. The DataWindow object in the DataWindow control (or DataStore) must be a RichTextEdit DataWindow.

filename

A string whose value is the name of the file you want to display in the RichTextEdit control. Filename can include the file's path.

clearflag

A boolean value specifying whether the new file will replace the current contents of the control. Values are:

  • true -- Replace the current contents with the file

  • false -- Insert the file into the existing contents at the insertion point

filetype

(optional)

A value of the FileType enumerated datatype specifying the type of file being opened. Values are:

  • FileTypeRichText! -- (Default) The file being opened is in rich text format (RTF)

  • FileTypeText! -- The file being opened is plain ASCII text (TXT)

  • FileTypeHTML! -- The file being opened is in HTML format (HTM or HTML)

  • FileTypeDoc! -- The file being opened is in Microsoft Word format (DOC)

  • FileTypeXLSX! -- The file being opened is in Microsoft Excel format (XLSX)

If filetype is not specified, PowerBuilder uses the filename extension to decide whether to read the file as rich text or plain text. If the extension is not one of the supported file type extensions, PowerBuilder attempts to read the file as rich text. To insert files with extensions such as INI, LOG, or SQL, you must specify FileTypeText!.

encoding

(optional)

Character encoding of the inserted document. This parameter only applies to text files.

You can specify the encoding of the inserted document. If the encoding is not specified, it will be automatically read from the BOM header. If there is no BOM header in the file, the encoding will be set as ANSI format by default. Values are:

  • EncodingANSI! (default)

  • EncodingUTF8!

  • EncodingUTF16LE!

  • EncodingUTF16BE!

Return value

Integer. Returns 1 if it succeeds and -1 if an error occurs. If any argument's value is null, InsertDocument returns null.

Usage

You cannot insert a document into a rich text control when the control's DisplayOnly property is set to true. If you try to do this, PowerBuilder displays a runtime error message.

When the control supports headers and footers (the HeaderFooter property is set to true), inserting a document can replace, but not add to, existing header and footer text. You must set clearflag to true to replace the existing header and footer text with header and footer text from the inserted document.

Not all RTF formatting is supported. PowerBuilder supports version 1.2 of the RTF standard, except for the following:

  • No support for formatted tables

  • No drawing objects

Any unsupported formatting is ignored.

Examples

This example inserts a document into rte_1 and reports the return value in a StaticText control: 

integer rtn
rtn = rte_1.InsertDocument("c:\pb\test.rtf", &
    TRUE, FileTypeRichText!)
st_status.Text = String(rtn)

See also

InputFieldInsert

InsertPicture

DataSource

Prev  Up  Next
InsertData  Home  InsertFile