:getformat()

2.18 :getformat()

The :getformat() method can be used to query the formatting of a text range in an RTF edittext. :getformat() returns a value that reflects the specification of the provided formatting type (e.g. font, font color, text alignment).

Definition

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

Parameters

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

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

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 get the formatting of 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.

If no characters are selected on invocation (.startsel = .endsel) or Start = End, the format left of the specified position will be returned.

enum Type input

This parameter specifies the type of formatting whose value shall be queried. The enum values for the formatting types are listed in the table below.

Return value

anyvalue

A value for the specification of the given formatting type.

If the range for which the formatting is queried contains multiple formattings of the specified type, nothing is returned.

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

Formatting Type	Formatting Kind	enum Value	Data Type
typeface, font	character format	text_font	string
font size	character format	text_size	integer
foreground color, text color	character format	text_fgc	integer
background color	character format	text_bgc	integer
bold	character format	text_bold	boolean
italic	character format	text_italic	boolean
underlined	character format	text_underline	boolean
left indentation	paragraph format	text_indent_left	integer
right indentation	paragraph format	text_indent_right	integer
indentation of continuation lines in a paragraph	paragraph format	text_indent_offset	integer
text alignment	paragraph format	text_align	enum [align_left, align_right, align_center, align_justify]

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).
For text_font :getformat() returns a string with the font name.
For foreground color (text_fgc) and background color (text_bgc) integer values are returned which should be interpreted as RGB values.

Reliability of Return Values

:getformat() can only work properly if the RTF edittext is visible (.visible = true), because the underlying Windows object performs some formatting calculations only in visible state. For example, the font information cannot be queried in the invisible state.

Objects with this method

edittext with .options[opt_rtf] = true