PtText

Single-line text

Class hierarchy:

PtWidget --> PtBasic --> PtLabel --> PtText

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

PhAB icon:

Public header:

<photon/PtText.h>

Description:

The Photon text widgets let you type textual information into a text-entry box. Basic editing features are provided so you can alter text that has been entered. A point-and-click model of editing is also supported so that blocks of text can be operated on as a unit.

A PtText widget.

Photon provides two different text widgets:

• PtText - a small, simple widget that provides a single-line data-entry field. The attributes of the text in the field can't be changed - the same font and color are used throughout the text string.
• PtMultiText - a full-featured text editor that handles multiple lines of text. Blocks of text may be selected and assigned different text attributes (e.g. the text may be displayed in several different fonts and colors).

Interaction model

The text entered in the text widget is either inserted into or overwrites the existing text, depending on the insertion mode. The location where text is inserted or replaced is visually represented by a cursor.

In insert mode, the cursor appears as a vertical bar or pipe (|) between two characters. When you enter a character, it appears at the cursor location, and the cursor is moved to the right of that character.

In replace mode, the cursor appears as an underline (_) beneath a character. When you enter a new character, it replaces the character at the cursor location, and the cursor is moved to the next character in the text.

Selecting text

Clicking the mouse button once changes the cursor location to the character position nearest the pointer location. Dragging the pointer with the button pressed causes a range of text to be selected as the object of a subsequent operation. The selected range of text, which begins at the cursor position and ends at the pointer location, is highlighted by inverting the foreground and background colors used to display the text. Releasing the button completes the range selection.

The range of text selected can be extended by dragging with the Shift key pressed. The selected range of text is changed to the text between the current cursor position and the pointer location. The extension of the range of text is completed when the button is released.

Any character you type after a range of text has been selected replaces the selected range. A string specified by the application may also replace the selected range.

The widget's text

To modify the text widget's contents within a program, you must be able to access the text widget's internal storage. The primary means of access to this text is through the Pt_ARG_TEXT_STRING resource.

Setting text

You can set the widget's text using the Pt_ARG_TEXT_STRING resource. You must give this resource a null-terminated C string as a value.

The following short program creates a text widget whose initial contents are the string "hello, world...":

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

PhArea_t area = { {0, 0}, {200,40} };

main(int argc, char *argv[])
{
   PtAppContext_t app;
   int            nargs = 0;
   PtArg_t        args[4];
   PtWidget_t     window;

   PtSetArg(&args[nargs++], Pt_ARG_POS, &area.pos, 0);
   PtSetArg(&args[nargs++], Pt_ARG_DIM, &area.size, 0);
   PtSetArg(&args[nargs++], Pt_ARG_WINDOW_TITLE, "hello", 0);
   if ((window = PtAppInit(&app, &argc, argv, nargs,
                           args)) == NULL)
      exit(EXIT_FAILURE);

   nargs = 0;
   area.pos.y = 15;
   PtSetArg(&args[nargs++], Pt_ARG_POS, &area.pos, 0);
   PtSetArg(&args[nargs++], Pt_ARG_DIM, &area.size, 0);
   PtSetArg(&args[nargs++], Pt_ARG_TEXT_STRING,
            "hello, world...", 0);
   PtCreateWidget(PtText, window, nargs, args);

   PtRealizeWidget(window);
   PtMainLoop();
}

Getting text

The widget's text can also be retrieved as a null-terminated C string by getting the value of the Pt_ARG_TEXT_STRING resource with the PtGetResources() function.

For more information, see "Getting resources" in the Manipulating Resources in Application Code chapter of the Photon Programmer's Guide.

Getting the current selection

You can obtain the range of characters in the current selection by using the PtTextGetSelection() function. This function takes the widget as the first parameter and returns the start and end position in the remaining two parameters. The range may be passed to other convenience functions to modify the selected text.

Replacing text

Any block of text in the widget can be programmatically replaced by a string using the PtTextModifyText() function. The parameters to this function are:

widget

The text widget.

start_pos

The start position of the range of text to be replaced.

end_pos

The end position of the range of text to be replaced.

cur_insert

The position to place the cursor before the change.

text

The UTF-8 string to replace the block of text.

length

The number of multibyte characters in the string.

Text modification callbacks

Your application can monitor and control changes made to the widget's text using the text modification callbacks. These callbacks are invoked when you type new text. If the widget has the Pt_CALLBACKS_ACTIVE bit set in its Pt_ARG_FLAGS resource, these callbacks are also invoked when the text is changed by a call to PtSetResources() or to a text widget function such as PtTextModifyText(). There are two text modification callbacks:

Pt_CB_MODIFY_VERIFY

Called before any changes are made to the text.

Pt_CB_MODIFY_NOTIFY (also known as Pt_CB_TEXT_CHANGED)

Called after a change.

Validation

The Pt_CB_MODIFY_VERIFY callback is useful for validating changes before they're made to the widget. You can use this callback to alter the text modification or prevent it entirely.

This callback can manipulate the text modification via the cbdata member of the PtCallbackInfo_t structure passed to it. The cbdata member is a pointer to a text-callback structure. This is a PtTextCallback_t structure if the widget is a PtText, and a PtMultiTextCallback_t structure if the widget is a PtMultiText widget.

The following example shows how the text member of the above structure can be modified to alter the text inserted into the widget. The example uses the allcaps() callback function to convert any lowercase characters to uppercase before they're inserted into the widget.

#include <Pt.h>
#include <stdlib.h>
#include <ctype.h>

int allcaps(PtWidget_t *, void *, PtCallbackInfo_t *);

main(int argc, char *argv[])
{
  PtAppContext_t app;
  PhRect_t       extent;
  PhPoint_t      pos;
  PhPoint_t      dim;
  PtArg_t        args[6];
  int            nargs;
  PtWidget_t     *window, *text, *label;
  /* Labels work with UTF-8 (multibyte character) strings.
     International characters can be entered only from an
     editor that supports UTF-8 */
  nargs = 0;
  PtSetArg(&args[nargs], Pt_ARG_MARGIN_HEIGHT, 4, 0);
  nargs++;
  if ((window = PtAppInit(&app, &argc, argv, nargs,
                          args)) == NULL)
    exit(EXIT_FAILURE);

  nargs = 0;
  PtSetArg(&args[nargs], Pt_ARG_TEXT_STRING, "Enter Text:", 0);
  nargs++;
  label = PtCreateWidget(PtLabel, window, nargs, args);

  PtWidgetExtent(label, &extent);
  pos = extent.lr; 
  pos.x += 4;
 
  nargs = 0;
  PtSetArg(&args[nargs], Pt_ARG_COLUMNS, 20, 0); nargs++;
  PtSetArg(&args[nargs], Pt_ARG_POS, &pos, 0); nargs++;
  text = PtCreateWidget(PtText, window, nargs, args);
  PtAddCallback(text, Pt_CB_MODIFY_VERIFY, allcaps, NULL);

  PtRealizeWidget(window);

  PtMainLoop();
}

int allcaps( PtWidget_t *w, void *client_data,
             PtCallbackInfo_t *info)
{
   int len;
   PtTextCallback_t *cbs = (PtTextCallback_t
                            *)info->cbdata;

   if (cbs->text == NULL)
      return Pt_CONTINUE;

   for ( len = 0; len < cbs->length; len++ )
      if (islower(cbs->text[len]))
         cbs->text[len] = toupper(cbs->text[len]);

   return Pt_CONTINUE;
}

Preventing the modification

You can prevent the text from being added to the widget by setting the doit member of the PtTextCallback_t structure to zero or by setting the length member to zero.

Setting the length to 0 stops the widget from inserting the text; it doesn't prevent any deletion included in the modification.

Handling deletions

You can determine if a modification is replacing or deleting a block of text by checking start_pos and end_pos. If these values differ, then a block of text is being removed from the widget and may potentially be replaced by new text contained in the text member.

Be sure to handle backspaces correctly. As well as checking for a different start and end position, an application can determine which of Backspace or Delete was pressed by checking the length, cur_insert, and new_insert:

• If length is zero, then no text replaces the deleted range-the user most likely pressed the Delete key or the destructive backspace key.
• If new_insert is less than cur_insert, the user pressed the destructive backspace key.
• If new_insert equals cur_insert, the user pressed the Delete key.

The following simple example of accepting a password as input illustrates how to handle all editing operations (including pasting) correctly:

/* This program creates two text widgets for entering 
   a password:
     - one offscreen to collect the password
     - one onscreen in which to type.

   All characters are displayed as stars in the onscreen 
   widget but are saved in the offscreen widget. This is
   done by making the displayed widget's callbacks 
   manipulate the offscreen widget's text.
*/

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

int check_passwd(PtWidget_t *, void *, PtCallbackInfo_t *);
int update_passwd(PtWidget_t *, void *, PtCallbackInfo_t *);

PtWidget_t *displayed_text, *offscreen_text;

main(int argc, char *argv[])
{
  PhRect_t     extent;
  PhPoint_t    pos;
  PtArg_t      args[2];
  int          nargs;
  PtWidget_t   *window, *label;

  nargs = 0;
  PtSetArg(&args[nargs++], Pt_ARG_MARGIN_HEIGHT, 4, 0);
  if ((window = PtAppInit(NULL, &argc, argv, nargs,
                          args)) == NULL)
    exit(EXIT_FAILURE);

  nargs = 0;
  PtSetArg( &args[nargs++], Pt_ARG_TEXT_STRING,
            "Enter Text:", 0);
  label = PtCreateWidget(PtLabel, NULL, nargs, args);

  PtExtentWidget(label);
  PtWidgetExtent(label, &extent);
  pos = extent.lr;
  pos.x += 4;
  pos.y = 0;

  // Create the displayed text widget:

  nargs = 0;
  PtSetArg(&args[nargs++], Pt_ARG_POS, &pos, 0);
  PtSetArg(&args[nargs++], Pt_ARG_COLUMNS, 20, 0);
  displayed_text = PtCreateWidget(PtText, NULL, nargs, args);
  PtAddCallback(displayed_text, Pt_CB_MODIFY_VERIFY,
                update_passwd, NULL);
  PtAddCallback(displayed_text, Pt_CB_ACTIVATE,
                check_passwd, NULL);

  // Create an offscreen text widget:

  pos.x = -1000;
  nargs = 0;
  PtSetArg(&args[nargs++], Pt_ARG_POS, &pos, 0);
  offscreen_text = PtCreateWidget(PtText, NULL, nargs, args);

  PtRealizeWidget(window);

  PtMainLoop();
}

int check_passwd( PtWidget_t *widget, void *client_data,
                  PtCallbackInfo_t *info )
{

   // This callback gets the password out of the offscreen
   // widget. It's invoked when you activate the displayed
   // widget (e.g. by pressing Enter).

   PtTextCallback_t *cbs = (PtTextCallback_t 
                            *)info->cbdata;
   char *passwd;
   PtArg_t args[1];

   PtSetArg (&args[0], Pt_ARG_TEXT_STRING, &passwd, 0 );
   PtGetResources ( offscreen_text, 1, args );
   if (info->reason_subtype == Pt_EDIT_ACTIVATE)
      printf("Password: %s\n", passwd);

   return Pt_CONTINUE;
}

int update_passwd( PtWidget_t *widget, void *client_data,
                   PtCallbackInfo_t *info )
{

   // This callback is invoked when you type in the displayed
   // widget, but it passes the typing to the offscreen widget.
   // The characters are replaced by stars in the displayed
   // widget.

   PtTextCallback_t *tcb = (PtTextCallback_t *)info->cbdata;
   static const char stars[] = "********************";
   PtArg_t args[1];

   PtSetArg( &args[0], Pt_ARG_TEXT_SUBSTRING, tcb, 0 );
   PtSetResources( offscreen_text, 1, args );
   tcb->text = stars;

   return Pt_CONTINUE;
}

String changes

After the user has entered the new text into the widget, the Pt_CB_TEXT_CHANGED or Pt_CB_MODIFY_NOTIFY callback list is invoked. You can use this callback to keep track of changes after they've been made. This is useful in form-filling applications and text editors to determine if the contents of the text buffer are "dirty" (i.e. they've been modified by the user).

This callback uses the same text modification callback structure as the Pt_CB_MODIFY_VERIFY callback. The text member of this structure contains a UTF-8 string indicating the current contents of the text widget (i.e. the entire text buffer).

An example of using this callback in form-filling applications is to provide a visual cue to the user to indicate that one or more fields within the form have changed. The user then knows that the pending changes won't take effect until they're applied - usually by pressing an Apply or OK button.

To use this callback in this way:

1. Create the form, including the Apply and Cancel buttons. The Apply button should have the Pt_GHOST and Pt_BLOCKED bits set in its Pt_ARG_FLAGS resource to give it an inactive or disabled appearance.
2. Attach a callback function to the Pt_CB_TEXT_CHANGED callback list. Make sure this callback turns off the Pt_GHOST and Pt_BLOCKED bits for the Apply button.

Another possibility is to create a check button beside each field in the form when the user alters the field's contents. Activating the check button causes the new value to take effect.

Focus callbacks

The text widget provides callbacks that tell the application either that the text widget has gained or lost focus.

The text widget gains focus when the user either clicks on the text widget or presses the Tab key to move from another text field into this one.

When the text widget obtains the focus by either of these two means, any callbacks defined in the Pt_CB_GOT_FOCUS callback list for the widget are called. This is useful if the application wishes to alter the appearance of a text widget that the user is entering text into, or to trigger the update of a status field providing hints to a user using a "novice" mode of the interface.

The Pt_CB_LOST_FOCUS callback is invoked any time the user switches focus away from the text widget, either by tabbing to the next field or by clicking within another widget. This callback can be used to undo any change in the text widget's appearance that the application made to indicate that the widget had focus. The callback can also be useful in performing any syntax checking done on the fields within a form.

Text cursor movement callbacks

You can track changes to the text cursor position representing the current insertion point by adding a cursor movement callback to the Pt_CB_MOTION_VERIFY callback list. The callback is invoked every time:

• The user moves the cursor by using the arrow keys.

  Or:

• The user clicks the SELECT pointer button.

  Or:

• The application calls a widget convenience function that modifies the text buffer, causing the cursor to be moved.

The reason member given in the callback info for this callback is Pt_CB_MOTION_VERIFY. The event member indicates the type of action that caused the callback to be invoked.

You can determine the type of action that caused the callback to be invoked by making a comparison on the event member. If it's set to NULL, the callback was invoked as a result of an application function call. Otherwise, the callback was invoked as a result of a user action (such as a pointer button press or keypress event).

The event member is a pointer to a PhEvent_t structure describing the user action. To differentiate between a pointer event and a keypress event, look at the type of that event.

The cbdata member of info is a pointer to the same type of text modification callback structure used by the other text widget callbacks. This callback uses the cur_insert, new_insert, and doit members of the structure. The doit member can be set to zero to prevent the cursor movement from taking place.

Activate callback

The PtText widget provides an activate callback, Pt_CB_ACTIVATE, that's invoked when one of the following occurs:

• The user presses the Enter key within the widget. This signals that any changes to the field are complete and the application can use the new value.

  The reason_subtype in the callback information is Pt_EDIT_ACTIVATE. The callback data is a pointer to the same text-modification callback structure as used by the text-modification callbacks. The text member of that structure contains a UTF-8 string indicating the contents of the buffer.

• The user clicks on the widget and Pt_SELECTABLE is set in its Pt_ARG_FLAGS.

  In this case, the reason_subtype in the callback information is 0, and the callback is as described for PtBasic.

• The text was modified, the widget has lost focus, and Pt_CHANGE_ACTIVATE is set in the widget's Pt_ARG_TEXT_FLAGS.

  The reason_subtype in the callback information is Pt_CHANGE_ACTIVATE. The callback data is a pointer to the same text-modification callback structure as used by the text-modification callbacks. The text member of that structure contains a UTF-8 string indicating the contents of the buffer.

The reason code in the callback information is always Pt_CB_ACTIVATE.

When only one text field is contained within a container widget (e.g. a dialog), the activate callback is often chained to the activate action on the dialog. In other words, for a prompt dialog, entering a new value in the text field and pressing the Enter key has the same effect as pressing the dialog's OK button after entering the new value.

Edit masks

The PtText widget provides an edit mask that allows a pattern to be specified for the text entered into the text field. Any characters the user enters must conform to this pattern or they'll be rejected.

Edit masks can be difficult to use and aren't very flexible. It's better to use a Pt_CB_MODIFY_VERIFY callback than an edit mask to constrain input.

The string entered into a data-entry field often conforms to some format. Edit masks are provided within the text widget to enforce the entry of the information in the correct format.

A single edit mask may be provided for the text widget by setting the Pt_ARG_EDIT_MASK resource. This resource is a null-terminated text string that acts as a template for text entered in the text field. Each character the user enters must match the corresponding character in the edit mask.

Here are the characters that may be specified in the edit mask, along with the characters they match:

Any other character that appears in the edit mask is assumed to be a constant character that must appear at that position in the text field. When the user has entered enough characters to reach that position, the character is automatically inserted. After that, the character may not be deleted or altered by the user.

As an example, Canadian postal codes must consist of uppercase alphabetic characters and numbers in the following order: character, digit, character, space, digit, character, digit. For example, QNX Software System's postal code is K2M 1W8. So, a text field for entering a postal code might specify C#C #C# as the edit mask. The text field widget enforces the constraints on the characters the user enters and automatically adds the space character.

Mouse actions

Keyboard actions

New resources:

Pt_ARG_COLUMNS

The number of "M" characters that fit in the field horizontally. The widget uses this resource only if the width component of the Pt_ARG_DIM resource is 0.

Pt_ARG_CURSOR_POSITION

The cursor position. A value of 0 indicates that the cursor is placed before the first character, 1 before the second character, and so on.

Pt_ARG_EDIT_MASK

A string that serves as an input filter for the text field. Each character in the string determines the acceptable input for the corresponding character position in the text field. The edit mask can contain the following:

X

Any character.

A

Alphabetic characters only.

#

Numeric characters only.

d

Alphanumeric characters.

N

Alphanumeric characters. All alphabetic characters are converted to uppercase.

n

Alphanumeric characters. All alphabetic characters are converted to lowercase.

C

Alphabetic characters only. All alphabetic characters are converted to uppercase.

c

Alphabetic characters only. All alphabetic characters are converted to lowercase.

anything else

Treated as a place holder, and appears as is, without alteration, in the text field. The cursor "steps over" place holders.

Edit masks can be difficult to use and aren't very flexible. It's better to use a Pt_CB_MODIFY_VERIFY callback than an edit mask to verify input.

Pt_ARG_MAX_LENGTH

The maximum text length the widget accepts.

Pt_ARG_SELECTION_RANGE

This resource can be used to select a range of text or determine what text is currently selected. This resource is complex, and requires special handling:

When setting...

The value is a pointer to an instance of a PtTextControl_t structure. The start_pos and end_pos members of the structure indicate the range of text to be highlighted (selected). When you set the resource, if end_pos is -1 or beyond the end of the string, it's set to the last character position of the widget's text. The doit member is always set to 1.

When getting...

The value is an address of a PtTextControl_t pointer. The start_pos and end_pos members hold the currently highlighted selected range. If no range is currently selected, start_pos is -1. Don't free() this structure.

The len isn't used when setting or getting this resource.

You can call PtTextGetSelection() or PtTextSetSelection() instead of using this resource.

Pt_ARG_TEXT_CURSOR_WIDTH

The width, in pixels, of the cursor.

Pt_ARG_TEXT_FLAGS

Valid flags:

Pt_CHANGE_ACTIVATE

If the text is changed and the widget loses focus, invoke the Pt_CB_ACTIVATE callback with the Pt_CHANGE_ACTIVATE subtype. For more information, see the description of Pt_CB_ACTIVATE in "Inherited resources," below.

Pt_CURSOR_VISIBLE

Display the cursor. Default is on.

Pt_EDITABLE

Make the text editable. Default is on.

Pt_INSERT_MODE

Toggle insert/replace mode. Default is insert (on).

Pt_TEXT_AUTO_HIGHLIGHT

Highlight the text when the widget is given focus. Default is off.

Pt_ARG_TEXT_HIGHLIGHT_BACKGROUND_COLOR

The background color for highlighting. If this is Pt_DEFAULT_COLOR, the default background color is used.

Pt_ARG_TEXT_HIGHLIGHT_TEXT_COLOR

The text color for highlighting. If this is Pt_DEFAULT_COLOR, the default text color is used.

Pt_ARG_TEXT_SUBSTRING

This resource can be used to get or set a substring of the widget's text. It's a complex resource, so it needs special handling:

When setting...

The value is a pointer to an instance of a PtTextControl_t structure that defines which characters are to be deleted and which are to be inserted. The following members are used:

• start_pos - the beginning of the range to delete, or -1 if no text is being deleted.
• end_pos - the end of the range to delete, or -1 if no text is being deleted.
• cur_insert - the position at which to insert the new text.
• length - the number of multibyte characters to add.
• text - a pointer to the text to add.

Instead of setting this resource, you can call PtTextModifyText().

When getting...

The value is an address of a pointer to a PtTextControl_t structure. Set the start_pos and end_pos to the beginning and end of the substring you want. When you get the resource, the length member is the number of multibyte characters in the substring, and text points to the range in the widget's internal memory.

The len isn't used when setting or getting this resource.

Pt_CB_MODIFY_NOTIFY / Pt_CB_TEXT_CHANGED

A list of callbacks that the widget invokes after the value of the text string changes.

It doesn't matter which name you use for this resource.

If the widget has the Pt_CALLBACKS_ACTIVE bit set in its Pt_ARG_FLAGS resource, this callback is also invoked when the text is changed by a call to PtSetResources() or to a text widget function such as PtTextModifyText().

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

reason

Pt_CB_MODIFY_NOTIFY

reason_subtype

0 (not used).

cbdata

A pointer to a PtTextCallback_t structure that contains at least 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 text string.

int length;

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

These callbacks should return Pt_CONTINUE.

Pt_CB_MODIFY_VERIFY

A list of callbacks that the widget invokes before the value of the text string changes. To alter the input to the widget, you can modify the members of the callback structure.

If the widget has the Pt_CALLBACKS_ACTIVE bit set in its Pt_ARG_FLAGS resource, this callback is also invoked when the text is changed by a call to PtSetResources() or to a text widget function such as PtTextModifyText().

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

reason

Pt_CB_MODIFY_VERIFY

reason_subtype

0 (not used).

cbdata

A pointer to a PtTextCallback_t structure that contains at least the following members:

unsigned int start_pos;
unsigned int end_pos;

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

int cur_insert;

The position at which text is being inserted. A value of 0 indicates that the text is being 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.

char *text;

The text to be inserted at cur_insert.

int length;

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

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().

These callbacks should return Pt_CONTINUE.

Pt_CB_MOTION_NOTIFY

A list of callbacks that the widget invokes after the cursor is repositioned.

If the widget has the Pt_CALLBACKS_ACTIVE bit set in its Pt_ARG_FLAGS resource, this callback is also invoked when the cursor is repositioned by a call to PtSetResources().

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

reason

Pt_CB_MOTION_NOTIFY

reason_subtype

0 (not used).

cbdata

A pointer to a PtTextCallback_t structure.

Pt_CB_MOTION_VERIFY

A list of callbacks that the widget invokes before the cursor is repositioned. Using this callback resource, you can modify or even disallow cursor repositioning.

If the widget has the Pt_CALLBACKS_ACTIVE bit set in its Pt_ARG_FLAGS resource, this callback is also invoked when the cursor is repositioned by a call to PtSetResources().

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

reason

Pt_CB_MOTION_VERIFY

reason_subtype

0 (not used).

cbdata

A pointer to a PtTextCallback_t structure that contains at least 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;

All these indicate the destination of the cursor. 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.

These callbacks should return Pt_CONTINUE.

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.

Pt_CB_ACTIVATE

Pt_CB_ACTIVATE is inherited from PtBasic, but its behavior is different for a PtText 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 - the user clicked on the widget and it has Pt_SELECTABLE set in its Pt_ARG_FLAGS.
• Pt_EDIT_ACTIVATE - the user pressed Enter in the text field.
• Pt_CHANGE_ACTIVATE - the text was modified, the widget lost focus, and Pt_CHANGE_ACTIVATE is set in the widget's Pt_ARG_TEXT_FLAGS.

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 PtTextCallback_t structure that contains at least the following members:

• int cur_insert - the position of the cursor along the string at the time the user pressed Enter. 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 text string.
• int length - the length of the text string (not including the \0).

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 callback data is different for a PtText widget. Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

The name of the callback resource (for example, Pt_CB_GOT_FOCUS) that caused this callback to be invoked.

reason_subtype

0 (not used).

cbdata

A pointer to a PtTextCallback_t structure that contains at least the following members:

• int cur_insert - the position of the cursor along the string at the time the user pressed Enter. 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 text string.
• int length - the length of the text string (not including the \0).

These callbacks should return Pt_CONTINUE.

Convenience functions:

The PtText 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:

PtTextCallback_t, PtTextControl_t, PtTextControlInfo_t

Information passed to PtText callbacks

PtTextGetSelection()

Gets the selected range from a PtText widget.

PtTextModifyText()

Modifies the contents of a PtText widget.

PtTextSetSelection()

Sets the selected range for a PtText widget.