PtMultiTextInfo()

Get character or line information from a PtMultiText widget

Synopsis:

int PtMultiTextInfo( PtWidget_t *widget,
                     int query_type,
                     int *char_offset,
                     int *line_num,
                     PtMultiTextLine_t *line,
                     int *start,
                     int *end,
                     int *length,
                     PtMultiTextSegment_t *seg,
                     PtMultiTextAttributes_t *attrs);

Description:

This function gets information about a character or line within a PtMultiText widget.

Using the information returned in the provided integers and in the PtMultiTextLine_t, PtMultiTextSegment_t, and PtMultiTextAttributes_t structures, you can determine:

• which line a character is on
• the start and end offsets of a given line
• the segment and attributes that exist at the beginning of a line
• the segment and attributes that exist at a given character offset.

Any argument representing information that you don't require can be set to NULL. Any argument representing information you do require must point to an instance of the integers or structures of the appropriate type. The data returned is copied from the widget's internal structures into the structures provided.

The returned data may not remain valid for very long, so you should use it immediately!

If you set query_type to Pt_MT_QUERY_LINE, then:

• line_num must point to an instance of an int that specifies the line number on which information will be collected (the widget's first line is line 1, its second is line 2, and so on)
• line_num will be set to the last line if the widget has fewer than line_num lines
• char_offset, if provided, will be set to the offset of the first character of the line
• attrs, if provided, will be filled in with the attributes in effect at the beginning of the line

If you set query_type to Pt_MT_QUERY_CHAR, then:

• char_offset must point to an instance of an int that contains a character offset (the widget's first character is 0, its second is 1, and so on)
• char_offset will be set to the last character if the widget has fewer than char_offset characters
• attrs, if provided, will be filled in with the attributes in effect at the given char_offset

Here's what the function will return when you provide a pointer to any of the following parameters:

line_num

The number of the line found by the query.

line

The line structure for that line.

start

The character offset of the first character in the line.

end

The character offset of the last character in the line.

Both start and end are 0-based. So, for example, if start returns as 0, it indicates the first character in the widget's text buffer.

length

The number of characters in the line.

seg

The segment that contains char_offset.

You could use this function to scroll to a specific line. For example, if you set Pt_ARG_CURSOR_POS to the offset of a character on line 35, the widget will scroll to line 35. (The PtMultiText widget will scroll as necessary, horizontally and vertically, to make the cursor visible).

Returns:

0

Success.

1

The provided widget is NULL or isn't a PtMultiText widget.

Classification:

Photon

See also:

PtTextGetSelection(), PtTextModifyText(), PtTextSetSelection(), PtMultiTextAttributes_t