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. The widgets provide basic editing features, so you can alter text that's entered. They also support a point-and-click model of editing, so that you can operate on blocks of text 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. You can't change the attributes of the text in the field — the same font and color are used throughout the text string.
• PtMultiText — a full-featured text editor that handles multiple lines of text. You can select blocks of text and assign to them different text attributes (e.g. you can display the text in several different fonts and colors).

Interaction model

The text that you enter 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. Double-clicking selects the text under the pointer, using space characters as the selection delimiter. Dragging the pointer with the button pressed selects a range of text 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.

You can extend the range of text selected 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. Alternately, you can extend the range by Shift-clicking at a new position.

Any character you type after selecting a range of text replaces the selected range. Your application can also specify a string to replace the selected range.

You can delete selected text by pressing Delete or Backspace. Pressing Ctrl-Backspace deletes all the text to the left of the cursor up to the first space character. Ctrl-Delete deletes the text to the right of the cursor up to the first space character.

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 (inherited from PtLabel).

Setting text

When you set the widget's text using Pt_ARG_TEXT_STRING, you must give 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>

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;

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

   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 = PtCreateWidget(PtWindow, Pt_NO_PARENT,
                                nargs, args)) == NULL)
      PtExit(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

You can retrieve the widget's text 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. You can pass the range to other convenience functions to modify the selected text.

Replacing text

Your application can change any block of text in the widget by calling PtTextModifyText(). The arguments are:

widget

A pointer to 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 your application changes the text is changed by calling PtSetResource(), PtSetResources(), or a convenience function such as PtTextModifyText(). The text-modification callbacks are:

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;

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

  /* 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 = PtCreateWidget(PtWindow, Pt_NO_PARENT,
                               nargs, args)) == NULL)
      PtExit(EXIT_FAILURE);

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

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

  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—you most likely pressed the Delete key or the destructive backspace key.
• If new_insert is less than cur_insert, you pressed the destructive backspace key.
• If new_insert equals cur_insert, you pressed the Delete key.

Example: entering a password

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;

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

  nargs = 0;
  PtSetArg(&args[nargs++], Pt_ARG_MARGIN_HEIGHT, 4, 0);

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

  nargs = 0;
  PtSetArg( &args[nargs++], Pt_ARG_TEXT_STRING,
            "Enter Text:", 0);
  label = PtCreateWidget( PtLabel, Pt_DEFAULT_PARENT,
                          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, Pt_DEFAULT_PARENT,
                                   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, Pt_DEFAULT_PARENT,
                                   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;
   PtGetResource( offscreen_text, Pt_ARG_TEXT_STRING,
                  &passwd, 0 );
   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 the same number of stars
      in the displayed widget.

      You need as many stars in the string below as characters
      that you allow in the password. */

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

   PtSetResource( offscreen_text, Pt_ARG_TEXT_SUBSTRING, tcb, 0 );
   tcb->text = stars;

   return Pt_CONTINUE;
}

String changes

After you've 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. the user modified them).

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

As an example, you can use this callback in form-filling applications to provide a visual cue 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 (see PtWidget) 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 inherits callbacks from PtBasic that tell your 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 widget into this one.

When the text widget obtains the focus by either of these two means, any callbacks defined in its Pt_CB_GOT_FOCUS callback list are called. This is useful if your 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 or clicking within another widget. You can use this callback 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 checking any syntax in the fields within a form.

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:

• You move the cursor by using the arrow keys.

  Or:

• You click the SELECT pointer button.

  Or:

• Your 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 (see the Photon Library Reference) that describes the user's 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. Your application can set the doit member to zero to prevent the cursor movement from taking place.

Activate callback

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

• You press the Enter key within the widget. This signals that any changes to the field are complete and your 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.

• You click 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.
• You modified the text, moved focus to another widget, and Pt_CHANGE_ACTIVATE is set in the text 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, typing 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 lets you specify a pattern for the text entered into the text field. Any characters that you type must conform to this pattern or they're rejected.

---

Edit masks can be difficult to use and aren't very flexible; use a Pt_CB_MODIFY_VERIFY callback instead.

---

The string entered into a data-entry field often conforms to some format. The text widget can use an edit mask to ensure that the information is in the correct format.

You can provide a single edit mask 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 that you type must match the corresponding character in the edit mask.

Here are the characters that you can specify 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 you've typed enough characters to reach that position, the character is automatically inserted. After that, you can't delete or alter it.

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 you type and automatically adds the space character.

Mouse actions

Keyboard actions

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:

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.

See “Edit masks,” above.

---

Edit masks can be difficult to use and aren't very flexible; use a Pt_CB_MODIFY_VERIFY callback instead.

---

Pt_ARG_MAX_LENGTH

The maximum text length that the widget accepts.

Pt_ARG_SELECTION_RANGE

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

• When setting, set the value argument to PtSetArg() to the address of a PtTextControl_t structure. Use the start_pos and end_pos members of the structure to indicate the range of text to be highlighted (selected). If end_pos is -1 or beyond the end of the string, the widget sets the end of the range to the last character position of its text. Always set the doit member to 1.
• When getting, set the value to the address of a pointer to a PtTextControl_t structure. The widget sets the start_pos and end_pos members to 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_NO_DRAG_SELECTION

Disable text selection by dragging. Text selection using the keyboard is still enabled. This option is useful for optimizing applications running on touchscreen devices. Default is off.

Pt_TEXT_AUTO_HIGHLIGHT

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

Pt_TEXT_BLINKING_CURSOR

Set the cursor to blink when the widget has focus. Default is on.

Pt_ARG_TEXT_HIGHLIGHT_BACKGROUND_COLOR

The background color for highlighting. See PgColor_t in the Photon Library Reference.

If you set this resource to Pt_DEFAULT_COLOR, the widget uses the default background color.

Pt_ARG_TEXT_HIGHLIGHT_TEXT_COLOR

The text color for highlighting. See PgColor_t in the Photon Library Reference.

If you set this resource to Pt_DEFAULT_COLOR, the widget uses the default text color.

Pt_ARG_TEXT_SUBSTRING

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

• When setting, set the value argument to PtSetArg() to the address of an instance of a PtTextControl_t structure that defines which characters are to be deleted and which are to be inserted. Set the members as follows:
  • start_pos — the beginning of the range to delete, or -1 if you don't want delete any text.
  • end_pos — the end of the range to delete, or -1 if you don't want delete any text.
  • 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, set the value to the address of 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 cur_insert is set to the current insert position of the widget.

You don't use the len argument to PtSetArg() when setting or getting this resource.

Pt_CB_MODIFY_NOTIFY or Pt_CB_TEXT_CHANGED

A list of PtCallback_t structures that define the 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 you've set the Pt_CALLBACKS_ACTIVE bit in the widget's Pt_ARG_FLAGS resource, these callbacks are also invoked when your application changes the text is changed by calling PtSetResource(), PtSetResources(), or a convenience 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).

event

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

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

For more information, see “Text-modification callbacks,” above.

These callbacks should return Pt_CONTINUE.

Pt_CB_MODIFY_VERIFY

A list of PtCallback_t structures that define the 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 you've set the Pt_CALLBACKS_ACTIVE bit set in the widget's Pt_ARG_FLAGS resource, these callbacks are also invoked when your application changes the text is changed by calling PtSetResource(), PtSetResources(), or a convenience 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).

event

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

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 PtCallback_t structures that define the callbacks that the widget invokes after it repositions the cursor.

If you've set the Pt_CALLBACKS_ACTIVE bit set in the widget's Pt_ARG_FLAGS resource, these callbacks are also invoked when your application repositions the cursor by calling PtSetResource() or 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).

event

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

cbdata

A pointer to a PtTextCallback_t structure.

Pt_CB_MOTION_VERIFY

A list of PtCallback_t structures that define the callbacks that the widget invokes before it repositions the cursor. You can use this callback resource to modify or even disallow cursor repositioning.

If you've set the Pt_CALLBACKS_ACTIVE bit set in the widget's Pt_ARG_FLAGS resource, these callbacks are also invoked when your application repositions the cursor by calling PtSetResource() or 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).

event

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

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 — 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 widget's Pt_ARG_TEXT_FLAGS.

event

A pointer to a PhEvent_t structure that describes the event that caused the callback to be invoked, or NULL if there's no 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 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

Pt_CB_GOT_FOCUS or Pt_CB_LOST_FOCUS

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

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 the user has to type something in a text widget).

Convenience functions:

The PtText widget defines the following convenience functions and data structures that make it easier to use the widget once it's been created:

PtTextCallback_t, PtTextControl_t, PtTextControlInfo_t

Information passed to PtText callbacks

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.