PtMultiText

Multiline stylized text

Class hierarchy:

PtWidget → PtBasic → PtContainer → PtCompound → PtMultiText

For more information, see the diagram of the widget hierarchy.

PhAB icon:

Public header:

<photon/PtMultiText.h>

Description:

The PtMultiText widget class lets you display and edit multilined stylized text.

A PtMultiText widget.

Lines can be automatically wrapped on character or word boundaries. Optional scrollbars are provided to make it easy to view wide or long documents. Multiple colors and fonts are supported on any line.

The text buffer of the PtMultiText widget is a zero-terminated string consisting of multibyte (UTF-8) characters. You can set attributes (such as font, color, or style) for any segment of text, but this information isn't embedded in the text buffer.

Features

The MultiText widget provides many features that make it ideal for multilined data entry fields or as the basis for an editor:

• optional line- and word- or character-wrapping
• support for multiple text fonts and colors
• support for “tagging” segments of text
• optional automatic scrollbars, both horizontal and vertical
• range selection
• cut, copy, and paste
• multiple tab stops
• tab expansion
• optional automatic indentation
• anchoring
• many useful callbacks
• cursor visibility, editable or read-only options
• overstrike and insert editing modes

You can control all these features via the widget's resources and convenience functions. For example, to force the widget to wrap long lines at word boundaries, set the Pt_EMT_WORD bit of the Pt_ARG_MULTITEXT_WRAP_FLAGS resource:

PtSetArg( &argt, Pt_ARG_MULTITEXT_WRAP_FLAGS, Pt_EMT_WORD,
          Pt_EMT_WORD );
PtSetResources( mtwidget, 1, &argt );

If you set both the word- and character-wrap flags, word wrapping is applied.

You can also control the amount of space left between lines of text using Pt_ARG_LINE_SPACING. The value of this resource is the number of pixels to leave between the descenders of one line of text and the ascenders of the next.

---

To display a horizontal scrollbar: Set the Pt_ARG_SCROLLBAR_X_DISPLAY to Pt_AS_REQUIRED or Pt_ALWAYS. Clear Pt_EMT_WORD and Pt_EMT_CHAR in the widget's Pt_ARG_MULTITEXT_WRAP_FLAGS resource.

---

Setting text

You can set the contents of the text buffer using the Pt_ARG_TEXT_STRING, Pt_ARG_TEXT_SUBSTRING, or Pt_ARG_MULTITEXT_SEGMENTS resources, or the PtTextModifyText() or PtMultiTextModifyText() convenience functions. The PtMultiText widget automatically wraps the text according to the wrap flags, and displays scrollbars if the Pt_ARG_SCROLLBAR_X_DISPLAY and/or Pt_ARG_SCROLLBAR_Y_DISPLAY resources allow for them.

If you set the text using the Pt_ARG_TEXT_STRING resource, the new text replaces the entire text buffer of the widget, and all the lines of text are drawn using the same attributes. The font is the one specified by the Pt_ARG_TEXT_FONT resource inherited from PtLabel. The text foreground and background colors are taken from the values of the Pt_ARG_COLOR and Pt_ARG_FILL_COLOR resources.

If you set the text using Pt_ARG_TEXT_SUBSTRING, only the specified portion of the text buffer is affected. Text can be deleted and/or inserted. The text inserted is drawn with the same attributes as the text at the insertion point.

Text attributes

You can control the following attributes of a range of text:

• font
• text color
• background color
• tag ( void * for your own use )

There are several methods for setting the attributes that affect a given range of text:

• Delete and/or insert ranges of text with attributes via the PtMultiTextModifyText() convenience function. Specify the attributes in the PtMultiTextAttributes_t structure that you pass to this function.
• Change the attributes of a range of text that's already there by filling in a PtMultiTextAttributes_t structure and using it to set the Pt_ARG_MULTITEXT_RANGE_ATTRIBUTES resource or, by calling the PtTextModifyText() convenience function.
• Define the ranges of text in advance (along with the associated set of attributes) and place them in the text buffer by setting the Pt_ARG_MULTITEXT_SEGMENTS resource. This is an easy way to initialize the PtMultiText widget with a catchy message.

  When setting the text and attributes via the Pt_ARG_MULTITEXT_SEGMENTS resource, you provide the resource with an array of PtMultiLines_t structures. Each element of the array has a text string and an associated set of attributes that are used when displaying the text.

Setting text using ranges

The following example shows how to create a multiline text widget with two ranges of text with different attributes:

#include <stdio.h>
#include <stdlib.h>
#include <Pt.h>
#include <Ph.h>

char Verdana24[MAX_FONT_TAG];

PtMultiLines_t hello[] = {
    { "Hello\n", Pt_DEFAULT_FONT, Pt_DEFAULT_COLOR,
      Pt_INHERIT_COLOR },
    { "World!", Pt_DEFAULT_FONT, Pg_BLUE, Pt_INHERIT_COLOR }
};

main() {
    PtWidget_t *window;
    PtArg_t args[2];
    int nargs = 0;
    PhDim_t dim = { 300, 150 };

    if (PtInit(NULL) == -1)
        PtExit(EXIT_FAILURE);

    if ((window = PtCreateWidget(PtWindow, Pt_NO_PARENT,
                                 0, NULL)) == NULL)
        PtExit( EXIT_FAILURE );

    if(PfGenerateFontName("Verdana", 0, 24,
                          Verdana24) == NULL) {
        perror("Unable to generate font name");
    } else {
      hello[1].font = Verdana24;
    }
    PtSetArg( &args[nargs++], Pt_ARG_DIM, &dim, 0 );
    PtSetArg( &args[nargs++], Pt_ARG_MULTITEXT_SEGMENTS,
        &hello, sizeof( hello )/sizeof(hello[0]) );
    PtCreateWidget( PtMultiText, Pt_DEFAULT_PARENT,
                    nargs, args );

    PtRealizeWidget( window );

    PtMainLoop();
}

Inserting text with assigned attributes

You can insert a new range of text into the text buffer and specify its attributes using the PtMultiTextModifyText() function. To delete and/or insert text such that it takes on the attributes in effect at the insertion point, use PtTextModifyText().

The following shows how our “Hello, world” example could be rewritten to insert text into the widget:

#include <stdio.h>
#include <stdlib.h>
#include <Pt.h>
#include <Ph.h>

main()
{
  PtWidget_t *window, *mtext;
  PtArg_t args[2];
  int nargs = 0;
  PhDim_t dim = { 300, 150 };
  PtMultiTextAttributes_t attr;
  char Verdana24[MAX_FONT_TAG];

  if (PtInit(NULL) == -1)
      PtExit(EXIT_FAILURE);

  if ((window = PtCreateWidget(PtWindow, Pt_NO_PARENT,
                                0, NULL)) == NULL)
      PtExit( EXIT_FAILURE );

  if(PfGenerateFontName("Verdana", 0, 24,
                        Verdana24) == NULL) {
      perror("Unable to generate font name");
      attr.font = Pt_DEFAULT_FONT;
  } else {
      attr.font = Verdana24;
  }

  PtSetArg( &args[nargs++], Pt_ARG_DIM, &dim, 0 );
  mtext = PtCreateWidget( PtMultiText, Pt_DEFAULT_PARENT,
                          nargs, args );
  PtTextModifyText( mtext, NULL, NULL, 0, "Hello, \n", 8 );
  PtMultiTextModifyText( mtext, NULL, NULL, -1,
      "World! \n", 8, attr, Pt_MT_FONT );

  PtRealizeWidget( window );

  PtMainLoop();
}

Changing the attributes of a range of text

With a WYSIWYG editor, you can select a range of text in the text widget and change the text attributes of that range. This requires the ability to modify the attributes of a range programmatically. Modifying the attributes of a range is also useful for marking blocks of text, as may be done to indicate the results of a search. You can modify the attributes of a range of text by using the PtMultiTextModifyAttributes() function or by setting the Pt_ARG_MULTITEXT_RANGE_ATTRIBUTES resource.

The following example shows how to change the font of the text selection to 14-point Helvetica, by using PtMultiTextModifyAttributes():

PtMultiTextAttributes_t attr;
int start, end;
char Helvetica_14[MAX_FONT_TAG];

if( PtTextGetSelection( text, &start, &end ) )
{
    if(PfGenerateFontName("Helvetica", 0, 14,
                          Helvetica_14) == NULL) {
        perror("Unable to generate font name");
    } else {
       attr.font = Helvetica_14;
       PtMultiTextModifyAttributes( text, &start, &end,
                                    &attr, Pt_MT_FONT );
    }
}

This code segment first determines the start and end of the text selection by calling PtTextGetSelection(). This gives the start and end positions to use in a subsequent call to PtMultiTextModifyAttributes().

The following example shows how to change the font of the text selection to 14-point Helvetica, by setting the Pt_ARG_MULTITEXT_RANGE_ATTRIBUTES resource:

PtMultiTextAttributes_t attr;
PtMultiTextControl_t mtc;
char Helvetica_14[MAX_FONT_TAG];

if( PtTextGetSelection( text, &mtc.tc.start, &mtc.tc.end ) )
{
    if(PfGenerateFontName("Helvetica", 0, 14,
                          Helvetica_14) == NULL) {
        perror("Unable to generate font name");
    } else {
        PtArg_t argt;
        attr.font = Helvetica_14;
        mtc.attributes = &attr;
        PtSetArg( &argt, Pt_ARG_MULTITEXT_RANGE_ATTRIBUTES,
                  &mtc, Pt_MT_FONT );
        PtSetResources( text, 1, &argt );
    }
}

The members of the PtMultiTextControl_t structure (also known as PtMultiTextCallback_t) used in the example are:

PtTextCallback_t tc

Text control structure used to control the modification of text. This is always present in the modification callbacks of PtText or PtMultiText widgets. The members of PtTextCallback_t (also known as PtTextControl_t) are:

int start_pos
int end_pos

The characters from start_pos up to but not including end_pos will be deleted.

int cur_insert

The position to insert characters if no deletion has occurred; otherwise, the new characters will be inserted at start_pos.

int new_insert

Useful only in modify callbacks, this member indicates the position the cursor will be in after the modification has occurred.

int length

The number of multibyte (UTF-8) characters to insert.

char *text

The multibyte string to insert.

int doit

Must be set to nonzero before changes to the content of the body of text will be permitted.

PtMultiTextAttributes_t *attributes

This structure describes a set of attributes. See PtMultiTextAttributes_t.

PtMultiTextSegment_t *seg

Valid only in callbacks from the PtMultiText widget. It points to the segment of text that's involved in the modification that caused the callback. See PtMultiTextSegment_t.

If you implement editing functions that allow operations that alter the attributes of fonts in text ranges, you should always obtain the current attributes in effect at the start of each range and make changes based on those.

Hyperlinks using cursor-motion callbacks

Since the cursor-motion callback notifies your application whenever the cursor is moved, the callback can also notify the application when the user presses the pointer button over a “hot-spot” used for a hypertext link.

You can store the data for a hypertext link itself on the pointer maintained in the tag for the text segment. The cursor-motion callback can then simply:

1. Check the tag's contents to determine if the cursor has been positioned on a hypertext link.
2. Check the event to see if the appropriate event type caused the callback to be invoked (i.e. a pointer-button press).
3. Take the action associated with the hypertext link.

You can refine this technique further by changing the callback so that it registers only an event handler that invokes the action associated with the hypertext link, then deregisters itself. This lets you define more complex behavior (e.g. proper “activate” behavior for the link). In this case, the link is followed only if the user releases the pointer button when the pointer is over the link.

When dealing with structured text such as hypertext, it's a good idea to break the text down into nodes. Define a data structure for these nodes, defining the type of node and any data associated with the node. Create a range of text for each node, attaching a pointer to the node as the Pt_MT_TAG attribute for the range, and add the range to the widget. The text's original structure can be obtained in callbacks by looking at the tag in the attributes member of the callback data structure.

The following illustrates a simple node structure, allowing either plain text or a hypertext link:

typedef enum text_node_enum { tnText, tnHyperlink }
   TextNodeType_t;
typedef text_node_str {
   TextNodeType_t type;
   void *data;
} TextNode_t;

The following code illustrates how a hypertext link can be activated within a multiline text widget:

struct line_str {
   TextNode_t node;
   char *text;
} lines[] = {
   { {tnText, NULL}, "Click " },
   { {tnHyper, (void *)"file.html#id"}, "here" },
   { {tnText, NULL}, " to follow a hypertext link"}
};

int
follow_link(PtWidget_t *widget, void *client_data,
            PtCallbackInfo_t *info)
{
   PtMultiTextCallback_t *cbs =
      (PtTextCallback_t *)info->cbdata;

   if (info->reason == Pt_CB_MOTION_VERIFY &&
       info->event != NULL &&
       (info->event->type & Ph_EV_BUT_PRESS))
   {
      TextNode_t *node =
        (TextNode_t *)cbs->attributes->tag;
      printf("URL referenced: %s\n", node->data);
   }
   return (Pt_CONTINUE);
}

void
init_text(PtWidget_t *text)
{
   PtMultiTextAttributes_t reg, hyper;
   int nlines;

   PtMultiTextCreateAttributes(&reg);
   PtMultiTextCreateAttributes(&hyper);
   hyper.text_color = Pg_DGREEN;
   for (nlines = 0; nlines < sizeof(lines)/
        sizeof(lines[0]); nlines++)
   {
      PtMultiTextAttributes_t *attr =
        lines[nlines].node.type == tnHyper ? &hyper
          : &reg;

      PtMultiTextModifyText (text, 0, 0, -1,
         lines[nlines].text,
         &lines[nlines].node,
         attr,
         Pt_MT_TAG|Pt_MT_FOREGROUND);
   }
   PtAddCallback(text, Pt_CB_MOTION_VERIFY, follow_link,
                 NULL);
}

The data member of a hyperlink node is assumed to be a string indicating what action to take. In this case, it refers to another document to load by a URL of the form used by the Photon Helpviewer.

Widget dimensions

As for all widgets, Pt_ARG_DIM holds the dimensions of a PtMultiText widget. For example, suppose you have a multitext widget that can show four lines of text. If you type more than four lines, say six lines, the widget displays a scrollbar to let you know there are more lines. Querying Pt_ARG_DIM gives the dimensions of the four lines of text.

If you need to determine the dimensions of the entire text — the six lines in our example — you'll need to calculate it as described below:

Use the Pt_ARG_MULTITEXT_QUERY_LINE resource to query the first line (line 1). This gives you information in the form of a PtMultiTextQuery_t structure, which contains a pointer to a PtMultiTextLine_t structure. The PtMultiTextLine_t structure contains a PhRect_t structure (see the Photon Library Reference) that specifies the extent for that line. Calculate the dimensions of the line as:

height = extent.lr.y - extent.ul.y + 1;
width  = extent.lr.x - extent.ul.x + 1;

The lines are organized as a linked list, using the next and previous pointers in the PtMultiTextLine_t structure. Traverse all the lines until the next pointer is NULL, calculating:

• the sum of the heights
• the maximum width

When you've examined all the lines, you'll have the “virtual dimensions” of the text input area (i.e. the area that the text would occupy if it had enough room to do so)

If you have only one font in the PtMultiText widget, the method of finding the dimensions can be simplified. For example, to find the virtual height, calculate the height of the first line and multiply it by the number of lines.

Drag and Drop

If you select some text and hold down the Ctrl key, you can drag the selected text to a PtText, PtMultiText, PtTerminal, or PtTty widget.

New resources:

---

The convenience functions can make it easier for you to use the complex resources. For more information, see “Convenience functions,” below.

---

Pt_ARG_MULTITEXT_BOTTOM_LINE (write-only)

Set the bottom line (top line + number of visible lines -1).

Pt_ARG_MULTITEXT_FLAGS

Flags that affect the appearance and behavior of the widget. The valid bits are:

Pt_EMT_AUTOINDENT

Automatically indent a new line (when you press Enter) to match the previous line, by duplicating any leading whitespace characters.

Pt_EMT_FULL_LINES

Draw a line of text only if there's enough room for its ascenders and descenders.

Pt_EMT_FORCED_SCROLL

Scroll down automatically if there's a blank space at the bottom of the widget and lines of text above the top of it.

Pt_EMT_SCROLL_TO_CURSOR

Enable cursor tracking.

Pt_ARG_MULTITEXT_NUM_LINES (read-only)

The line number of the last line in the buffer. The first line is line 1, not 0.

Pt_ARG_MULTITEXT_NUM_LINES_VISIBLE (read-only)

The number of lines that are currently visible.

Pt_ARG_MULTITEXT_QUERY_CHARACTER (read-only)

Use this resource to get information about a certain character. This resource is a complex one, so it needs special handling. When getting, set the arguments to PtSetArg() as follows:

value

A pointer to an instance of a PtMultiTextQuery_t structure.

len

The index of the character you want to be query. The index of the first character is 0.

Pt_ARG_MULTITEXT_QUERY_LINE (read-only)

Use this resource to get information about a certain line. This resource is a complex one, so it needs special handling. When getting, set the arguments to PtSetArg() as follows:

value

A pointer to an instance of a PtMultiTextQuery_t structure.

len

The index of the line to be queried. The index of the first line is 1.

Pt_ARG_MULTITEXT_RANGE_ATTRIBUTES

This resource modifies/queries the attributes of a specified range. This resource is a complex one, so it needs special handling.

When setting this resource, set the arguments to PtSetArg() as follows:

value

A pointer to an instance of a PtMultiTextControl_t structure.

len

A bitmask indicating which attributes to affect in the range. The valid bits for this mask are:

• Pt_MT_FONT
• Pt_MT_FOREGROUND
• Pt_MT_TEXT_COLOR
• Pt_MT_BACKGROUND
• Pt_MT_BACKGROUND_COLOR
• Pt_MT_TAG
• Pt_MT_FLAGS

When getting the value of this resource, set the arguments to PtSetArg() as follows:

value

The address of a pointer to a PtMultiTextInfo_t structure, which is the same as PtMultiTextControl_t.

len

A pointer to an instance of a PtTextCallback_t structure that defines the range you want to query.

Pt_ARG_MULTITEXT_ROWS (write-only)

Specifies the number of rows. Setting this resource sets the widget's height dimension based on the height of the current font and number of rows specified. There's no default value for this resource because the widget initially uses its dimension to determine the number of rows.

---

This is a “one-shot” resource; it changes the size of the widget when you set it, based on the widget's current settings. If you later change the font, the value of Pt_ARG_MULTITEXT_ROWS isn't used to recalculate the height of the widget.

---

Pt_ARG_MULTITEXT_SEGMENTS (write-only)

This resource provides an easy way for you to define a multisegment message. (A segment is a set of contiguous characters that share common attributes, such as font, color, and so on.)

All the text provided in the PtMultiLines_t array is concatenated and used to replace the text in the Pt_ARG_TEXT_STRING resource. The rest of the information in the array is used to build up an index of segments into the text. The array itself isn't preserved within the widget. Consequently, you should treat Pt_ARG_MULTITEXT_SEGMENTS as a write-only resource. To retrieve the text, use the Pt_ARG_TEXT_STRING resource.

Pt_ARG_MULTITEXT_TABS

Provides a means of specifying tab stops to the multitext widget. The array provided is an array of integers, each of which is a tab spacing, in pixels, relative to the last tab position. The last tab spacing is repeated; for example, a tab array of {10,20,10} produces tab stops at 10, 30, 40, 50, 60, ... pixels.

Pt_ARG_MULTITEXT_TOP_LINE

Set or get the top line or vertical scroll position, in lines (where the first line is line 1).

Pt_ARG_MULTITEXT_WRAP_FLAGS

This resource controls how the multitext widget wraps. The possible values are:

Pt_EMT_WORD

Wrap on word breaks.

Pt_EMT_CHAR

Wrap at the end of the line.

Pt_EMT_NEWLINE

Wrap on carriage returns.

If both the word and character wrap flags are on, word wrapping is applied.

Pt_ARG_MULTITEXT_X_SCROLL_POS

The horizontal scroll position (in pixels).

Pt_ARG_MULTITEXT_Y_SCROLL_POS

Set or get the top line or vertical scroll position in lines, where the first line is line 1. This resource is the same as Pt_ARG_MULTITEXT_TOP_LINE.

Pt_ARG_SCROLLBAR_X_DISPLAY

This resource indicates when to display the horizontal scrollbar. The possible values are:

• Pt_NEVER (default)
• Pt_AS_REQUIRED
• Pt_ALWAYS

---

In order to display a horizontal scrollbar, you need to clear Pt_EMT_WORD and Pt_EMT_CHAR in the widget's Pt_ARG_MULTITEXT_WRAP_FLAGS resource.

---

Pt_ARG_SCROLLBAR_X_HEIGHT

The height of the horizontal scrollbar. If you set this resource to 0, widget uses the default size of 15.

Pt_ARG_SCROLLBAR_Y_DISPLAY

This resource indicates when to display the vertical scrollbar. The possible values are:

• Pt_NEVER (default)
• Pt_AS_REQUIRED
• Pt_ALWAYS

Pt_ARG_SCROLLBAR_Y_WIDTH

The width of the vertical scrollbar. If you set this resource to 0, widget uses the default size of 15.

Inherited resources:

If the widget modifies an inherited resource, the “Default override” column indicates the new value. This modification affects any subclasses of the widget.

---

By default, this widget has the bit Pt_TEXT_BLINKING_CURSOR in Pt_ARG_TEXT_FLAGS set to on.

---

Pt_CB_ACTIVATE

Pt_CB_ACTIVATE is inherited from PtBasic, but its behavior is different for a PtMultiText widget. Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_ACTIVATE

reason_subtype

Indicates why the callback was invoked:

• 0 — you clicked on the widget and it has Pt_SELECTABLE set in its Pt_ARG_FLAGS.
• Pt_EDIT_ACTIVATE — you pressed Enter in the text field.
• Pt_CHANGE_ACTIVATE — you modified the text, gave focus to another widget, and Pt_CHANGE_ACTIVATE is set in the text widget's Pt_ARG_TEXT_FLAGS (inherited from PtText).

event

A pointer to a PhEvent_t structure that describes the event that caused the callback to be invoked, or NULL if there isn't an event.

cbdata

If reason_subtype is 0, the callback data is as described for the Pt_CB_ACTIVATE resource for PtBasic.

If reason_subtype is Pt_EDIT_ACTIVATE or Pt_CHANGE_ACTIVATE, cbdata points to a PtMultiTextCallback_t structure that contains at least the following members:

PtTextCallback_t tc;
PtMultiTextAttributes_t const *attributes;
PtMultiTextSegment_t *seg;
void *extended_data;
    

• The PtTextCallback_t tc structure has the following members:

  int start_pos;
  int end_pos;

  All characters starting at start_pos up to but not including end_pos are to be deleted. If start_pos and end_pos are equal, no characters are to be deleted.

  int cur_insert;

  The position at which text will be inserted. A value of 0 indicates that the text will be inserted to the left of the first character, 1 to the right of the first character, and so on.

  int new_insert;

  Where the cursor will be after the changes are applied.

  int length;

  The number of characters to be inserted. If length is zero, no text is being inserted, so the text field is invalid.

  char *text;

  The text to be inserted at cur_insert.

  Before using text, check the length field to make sure text contains valid data. In addition, note that text might not be zero-terminated.

  int doit;

  Indicates whether or not this modification will be applied to the widget. If doit is zero, the widget discards the modification. If doit is nonzero, the widget uses the contents of the callback structure to modify itself.

  For more information, see PtTextModifyText() or PtMultiTextModifyText().

• PtMultiTextSegment_t *seg is the text segment that contains the character indicated by cur_insert. See PtMultiTextSegment_t.
• PtMultiTextAttributes_t *attributes are the attributes associated with seg. See PtMultiTextAttributes_t.

These callbacks should return Pt_CONTINUE.

Pt_CB_GOT_FOCUS, Pt_CB_LOST_FOCUS

Pt_CB_GOT_FOCUS and Pt_CB_LOST_FOCUS are inherited from PtBasic, but the cbdata member of the callback information is different for a PtMultiText widget.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

The name of the callback resource that caused this callback to be invoked.

reason_subtype

0 (not used).

event

A pointer to a PhEvent_t structure that describes the event that caused the callback to be invoked.

cbdata

A pointer to a PtMultiTextCallback_t structure.

The members of the PtMultiTextCallback_t structure are used as follows:

• The PtTextCallback_t tc structure has the following members:

  int cur_insert;

  The position of the cursor along the string. A value of 0 indicates that the cursor is to the left of the first character, 1 to the right of the first character, and so on.

  char *text;

  The beginning of the text string.

  int length;

  The length of the text string (not including the NULL).

• PtMultiTextSegment_t *seg is the text segment that contains the character indicated by cur_insert. See PtMultiTextSegment_t.
• PtMultiTextAttributes_t *attributes are the attributes associated with seg. See PtMultiTextAttributes_t.

The Pt_CB_GOT_FOCUS callbacks should return Pt_CONTINUE.

The Pt_CB_LOST_FOCUS callbacks should return:

• Pt_CONTINUE to relinquish focus

  Or:

• Pt_END to keep it (for example, if you have to type something in the text widget).

Pt_CB_TEXT_CHANGED, Pt_CB_MODIFY_NOTIFY, Pt_CB_MOTION_NOTIFY

Pt_CB_TEXT_CHANGED (Pt_CB_MODIFY_NOTIFY), and Pt_CB_MOTION_NOTIFY are inherited from PtText but the cbdata member of the callback information is different for a PtMultiText widget.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

The name of the callback resource that caused this callback to be invoked.

reason_subtype

0 (not used).

event

A pointer to a PhEvent_t structure that describes the event that caused the callback to be invoked, or NULL if there isn't an event.

cbdata

A pointer to a PtMultiTextCallback_t structure.

The members of the PtMultiTextCallback_t structure are used as follows:

• The PtTextCallback_t tc structure has the following members:

  int cur_insert;

  The position of the cursor along the string. A value of 0 indicates that the cursor is to the left of the first character, 1 to the right of the first character, and so on.

  char *text;

  The beginning of the text string.

  int length;

  The length of the text string (not including the NULL).

• PtMultiTextSegment_t *seg is the text segment that contains the character indicated by cur_insert. See PtMultiTextSegment_t.
• PtMultiTextAttributes_t *attributes are the attributes associated with seg. See PtMultiTextAttributes_t.

These callbacks should return Pt_CONTINUE.

Pt_CB_MODIFY_VERIFY

Pt_CB_MODIFY_VERIFY is inherited from PtText, but the cbdata member of the callback information is different for a PtMultiText widget.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

The name of the callback resource that caused this callback to be invoked.

reason_subtype

0 (not used).

event

A pointer to a PhEvent_t structure that describes the event that caused the callback to be invoked, or NULL if there isn't an event.

cbdata

A pointer to a PtMultiTextCallback_t structure.

The members of the PtMultiTextCallback_t structure are used as follows:

• The PtTextCallback_t tc structure has the following members:

  int start_pos;
  int end_pos;

  All characters starting at start_pos up to but not including end_pos are to be deleted. If start_pos and end_pos are equal, no characters are to be deleted.

  int cur_insert;

  The position at which text will be inserted. A value of 0 indicates that the text will be inserted to the left of the first character, 1 to the right of the first character, and so on.

  int new_insert;

  Where the cursor will be after the changes are applied.

  int length;

  The number of characters to be inserted. If length is zero, no text is being inserted, so the text field is invalid.

  char *text;

  The text to be inserted at cur_insert.

  Before using text, check the length field to make sure text contains valid data. In addition, note that text might not be zero-terminated.

  int doit;

  Indicates whether or not this modification will be applied to the widget. If doit is zero, the widget discards the modification. If doit is nonzero, the widget uses the contents of the callback structure to modify itself.

  For more information, see PtTextModifyText() or PtMultiTextModifyText().

• PtMultiTextSegment_t *seg is the text segment that contains the character indicated by cur_insert. See PtMultiTextSegment_t.
• PtMultiTextAttributes_t *attributes are the attributes associated with seg. See PtMultiTextAttributes_t.

These callbacks should return Pt_CONTINUE.

Pt_CB_MOTION_VERIFY

Pt_CB_MOTION_VERIFY (Pt_CB_MODIFY_NOTIFY), is inherited from PtText, but the cbdata member of the callback information is different for a PtMultiText widget.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

The name of the callback resource that caused this callback to be invoked.

reason_subtype

0 (not used).

event

A pointer to a PhEvent_t structure that describes the event that caused the callback to be invoked, or NULL if there isn't an event.

cbdata

A pointer to a PtMultiTextCallback_t structure.

• The PtTextCallback_t tc structure has the following members:

  int cur_insert;

  The current position of the cursor. A value of 0 indicates that the cursor is to the left of the first character, 1 to the right of the first character, and so on.

  int start_pos;
  int end_pos;
  int new_insert;

  These all indicate the destination of the cursor at the time the callback is invoked. A value of 0 indicates that the cursor will be to the left of the first character, 1 to the right of the first character, and so on.

  char *text;

  The string beginning at cur_insert.

  int length;

  The number of characters from the selected character to the end of the segment.

  int doit;

  Indicates whether or not this modification will be applied to the widget. If doit is zero, the cursor remains at cur_insert. If doit is nonzero, the cursor will be repositioned at new_insert.

• PtMultiTextSegment_t *seg is the text segment that contains the character indicated by cur_insert. See PtMultiTextSegment_t.
• PtMultiTextAttributes_t *attributes are the attributes associated with seg. See PtMultiTextAttributes_t.

If cbinfo->event is NULL, the cursor motion occurred because:

• Your application set a resource on this widget that affects the cursor position.

  Or:

• The application called a function that repositioned the cursor.

These callbacks should return Pt_CONTINUE.

Convenience functions:

The PtMultiText widget defines several convenience functions and data structures that make it easier to use the widget once it's been created. Here's a brief overview:

PtMultiLines_t

Structure for setting multiline text and attributes

PtMultiTextAttributes_t

Attributes for multiline text

PtMultiTextCallback_t, PtMultiTextControl_t

Information passed to PtMultiText callbacks

PtMultiTextCreateAttributes()

Initialize a multitext attribute structure.

PtMultiTextGetAttributes()

Get the attributes of a PtMultiText widget.

PtMultiTextInfo()

Get character/line information from a PtMultiText widget.

PtMultiTextInfo_t

Information passed to PtMultiText callbacks

PtMultiTextLine_t

Information about a line of text in a PtMultiText

PtMultiTextModifyAttributes()

Modify the attributes of a PtMultiText widget.

PtMultiTextModifyText()

Modify the contents of a PtMultiText widget.

PtMultiTextQuery_t

Structure for getting information about a line or character

PtMultiTextSegment_t

Information about a segment of text in a PtMultiText

PtTextGetSelection()

Get the selected range from a PtText widget.

PtTextModifyText()

Modify the contents of a PtText widget.

PtTextSetSelection()

Set the selected range for a PtText widget.