2.42 :setformat()

boolean :setformat
(
  { integer  Start := 1  input,
    integer  End   := -1 input, }
    enum     Type  input,
    anyvalue Value input
)

Parameters

integer Start := 1 input
integer End := -1 input

These optional parameters define the range that shall be formatted. If these parameters are missing, the range from .startsel to .endsel (selection or cursor position) is formatted.

Which range will actually be formatted depends on the kind of formatting:

• Character formats affect exactly the specified range.
• Paragraph formats affect all paragraphs that are contained completely or partly in the specified range.

The formatting kind is listed in the table below.

The value range of Start and End goes from 0 to the number of characters in the displayed text, with every character that can be included in a selection counting. Line break characters therefore count as well.

-1 can be specified for End to format the remaining text from the start position.

Start and End – similar to .startsel and .endsel – refer to positions in the formatted text. They cannot be used to infer positions in the content string of the RTF edittext, since this also contains formatting instructions. If the Start or End parameters are greater than the text length, then the text length is used for the RTF edittext.

enum Type input

This parameter defines the type of formatting to be applied. The enum values for the formatting types are listed in the table below.

anyvalue Value input

This parameter contains a value that determines the characteristics of the formatting type defined in Type. The data types for the formatting types are listed in the table below.

Return value

true

The text range has been formatted.

false

Error: The formatting could not be applied (e.g. due to incorrect arguments).

Formatting Kinds, enum Values and Data Types of the Formatting Types

Depending on the font, it may happen that formatting instructions or formatting attributes set with :setformat() are ignored by the Windows object that the IDM uses for the RTF edittext. On Windows 7, this happens, for example, with text_bold if no font is set explicitly and therefore the System font is used implicitly.

Unit of Measure for Sizes and Positions

Sizes and positions are specified in twips – as usual in Windows programming. A twip is equivalent to 1/20 point, that is 1/1440 inch or 1/567 cm.

Explanations on Particular Formattings

• The value for text_indent_right is an absolute specification of the indentation from the right margin.
• In contrast, text_indent_left is a relative specification that can be used several times. The indents from the left margin are accumulated, but can never extend beyond the margin. The value can be negative and then means that a paragraph is shifted to the left, while positive values mean a shift to the right.
• The value of text_indent_offset determines how far all lines of a paragraph except the first are shifted to the right (positive value) or to the left (negative value).

• With text_font

  • a string with a font name,
  • a string with size and font name in the form <size>.<font name>, similar to font resources on Microsoft Windows, or
  • a font resource

  may be specified. :setformat() extracts information such as font name and size from a font resource and applies the appropriate formatting.

  If the font name is correct, formatting will be performed regardless of whether the font is installed on the system. However, if the font is not installed, you will not see any effect. But you would see it when the RTF text is displayed on a system where the font is installed.

  Specifications in the form <size>.<font name> are supported as of IDM version A.05.02.l. Size and font name are evaluated and set.

• Foreground color (text_fgc) and background color (text_bgc) can be passed as integer values, which are treated as RGB values, or as color resources.

Objects with this method

edittext with .options[opt_rtf] = true