PtText

Single-line text

Class hierarchy:

PtWidgetPtBasicPtLabelPtText

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

PhAB icon:

PtText button in PhAB

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.


Example of PtText


A PtText widget.

Photon provides two different text widgets:

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.


Note: 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:

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:

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:

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.


Note: 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:

This character: Matches:
# Any single numeric digit
X Any character (don't care)
A Any alphabetic character (the letters A-Z)
n Any alphanumeric character (the letters A-Z or any numeric digit). All alphabetic characters are converted to lowercase.
N Any alphanumeric character (the letters A-Z or any numeric digit). All alphabetic characters are converted to uppercase.
c Any alphabetic character (the letters A-Z). All characters are converted to lowercase.
C Any alphabetic character (the letters A-Z). All characters are converted to uppercase.
d Any alphanumeric character (the letters A-Z or any numeric digit), but without case conversion.

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

If you: The widget:
Press the mouse button Gets input focus
Press the mouse button and drag the mouse Extends the text selection
Release the mouse button Ends the text selection

Keyboard actions

If you press: The widget:
Any character Inserts the typed character
Moves the cursor to the right
Moves the cursor to the left
Home Moves the cursor to the beginning of the line
End Moves the cursor to the end of the line
Shift- Extends the text selection to the right
Shift- Extends the text selection to the left
Shift-Home Extends the text selection to the beginning of the line
Shift-End Extends the text selection to the end of the line
Backspace Deletes the previous character
Delete Deletes the current character
Enter Processes the text
Tab Moves the cursor to the next text field
Shift-Tab Moves the cursor to the previous text field
Ctrl- Moves the cursor to the next word
Ctrl- Moves the cursor to the previous word
Ins Toggles between insert and replace modes

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:

Resource C type Pt type Default
Pt_ARG_COLUMNS short Scalar 0
Pt_ARG_CURSOR_POSITION int Scalar -1
Pt_ARG_EDIT_MASK char * String NULL
Pt_ARG_MAX_LENGTH signed int Scalar SHRT_MAX
Pt_ARG_SELECTION_RANGE See below Complex See below
Pt_ARG_TEXT_CURSOR_WIDTH char Scalar 1
Pt_ARG_TEXT_FLAGS unsigned long Flag Pt_CURSOR_VISIBLE | Pt_EDITABLE | Pt_INSERT_MODE | Pt_TEXT_BLINKING_CURSOR
Pt_ARG_TEXT_HIGHLIGHT_BACKGROUND_COLOR PgColor_t Scalar Pt_DEFAULT_COLOR
Pt_ARG_TEXT_HIGHLIGHT_TEXT_COLOR PgColor_t Scalar Pt_DEFAULT_COLOR
Pt_ARG_TEXT_SUBSTRING See below Complex See below
Pt_CB_MODIFY_NOTIFY PtCallback_t * Link NULL
Pt_CB_MODIFY_VERIFY PtCallback_t * Link NULL
Pt_CB_MOTION_NOTIFY PtCallback_t * Link NULL
Pt_CB_MOTION_VERIFY PtCallback_t * Link NULL
Pt_CB_TEXT_CHANGED PtCallback_t * Link NULL

Pt_ARG_COLUMNS

C type Pt type Default
short Scalar 0

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

C type Pt type Default
int Scalar -1

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

C type Pt type Default
char * String NULL

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.


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

Pt_ARG_MAX_LENGTH

C type Pt type Default
signed int Scalar SHRT_MAX

The maximum text length that the widget accepts.

Pt_ARG_SELECTION_RANGE

C type Pt type Default
See below Complex See below

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:

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

C type Pt type Default
char Scalar 1

The width, in pixels, of the cursor.

Pt_ARG_TEXT_FLAGS

C type Pt type Default
unsigned long Flag Pt_CURSOR_VISIBLE | Pt_EDITABLE | Pt_INSERT_MODE | Pt_TEXT_BLINKING_CURSOR

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

C type Pt type Default
PgColor_t Scalar Pt_DEFAULT_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

C type Pt type Default
PgColor_t Scalar Pt_DEFAULT_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

C type Pt type Default
See below Complex See below

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:

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

Pt_CB_MODIFY_NOTIFY or Pt_CB_TEXT_CHANGED

C type Pt type Default
PtCallback_t * Link NULL

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


Note: 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

C type Pt type Default
PtCallback_t * Link NULL

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

C type Pt type Default
PtCallback_t * Link NULL

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

C type Pt type Default
PtCallback_t * Link NULL

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.

Resource Inherited from Default override
Pt_ARG_ACCEL_KEY PtLabel Not used by this class.
Pt_ARG_ANCHOR_FLAGS PtWidget
Pt_ARG_ANCHOR_OFFSETS PtWidget
Pt_ARG_AREA PtWidget
Pt_ARG_BALLOON_COLOR PtLabel
Pt_ARG_BALLOON_FILL_COLOR PtLabel
Pt_ARG_BALLOON_POSITION PtLabel
Pt_ARG_BALLOON_TEXT PtLabel
Pt_ARG_BANDWIDTH_THRESHOLD PtBasic Not used by this class.
Pt_ARG_BASIC_FLAGS PtBasic
Pt_ARG_BEVEL_WIDTH PtWidget 0
Pt_ARG_BITMAP_CURSOR PtWidget
Pt_ARG_BEVEL_COLOR PtBasic
Pt_ARG_BEVEL_CONTRAST PtBasic
Pt_ARG_COLOR PtBasic
Pt_ARG_CONTRAST PtBasic
Pt_ARG_CURSOR_COLOR PtWidget
Pt_ARG_CURSOR_TYPE PtWidget Ph_CURSOR_INSERT
Pt_ARG_DARK_BEVEL_COLOR PtBasic
Pt_ARG_DARK_FILL_COLOR PtBasic
Pt_ARG_DATA PtWidget
Pt_ARG_DIM PtWidget
Pt_ARG_EFLAGS PtWidget |= Pt_CONSUME_EVENTS
Pt_ARG_EXTENT PtWidget
Pt_ARG_FILL_COLOR PtBasic Pg_GRAY
Pt_ARG_FILL_PATTERN PtBasic
Pt_ARG_FLAGS PtWidget |=Pt_SET|
Pt_HIGHLIGHTED|
Pt_GETS_FOCUS
Pt_ARG_GRID_LAYOUT_DATA PtWidget
Pt_ARG_HEIGHT PtWidget
Pt_ARG_HELP_TOPIC PtWidget
Pt_ARG_HIGHLIGHT_ROUNDNESS PtBasic
Pt_ARG_HORIZONTAL_ALIGNMENT PtLabel
Pt_ARG_INLINE_COLOR PtBasic
Pt_ARG_LABEL_BALLOON PtLabel
Pt_ARG_LABEL_FLAGS PtLabel &=~Pt_LABEL_SELECT_SHIFT
Pt_ARG_LABEL_IMAGE PtLabel Not used by this class.
Pt_ARG_LABEL_TYPE PtLabel Not used by this class.
Pt_ARG_LAYOUT_DATA PtWidget
Pt_ARG_LIGHT_BEVEL_COLOR PtBasic
Pt_ARG_LIGHT_FILL_COLOR PtBasic
Pt_ARG_LINE_SPACING PtLabel Not used by this class.
Pt_ARG_MARGIN_BOTTOM PtLabel
Pt_ARG_MARGIN_HEIGHT PtBasic
Pt_ARG_MARGIN_LEFT PtLabel
Pt_ARG_MARGIN_RIGHT PtLabel
Pt_ARG_MARGIN_TOP PtLabel
Pt_ARG_MARGIN_WIDTH PtBasic
Pt_ARG_MAXIMUM_DIM PtWidget
Pt_ARG_MINIMUM_DIM PtWidget
Pt_ARG_OUTLINE_COLOR PtBasic
Pt_ARG_POINTER PtWidget
Pt_ARG_POS PtWidget
Pt_ARG_RESIZE_FLAGS PtWidget Pt_RESIZE_Y_AS_REQUIRED|
Pt_RESIZE_Y_INITIAL
Pt_ARG_ROW_LAYOUT_DATA PtWidget
Pt_ARG_SECONDARY_H_ALIGN PtLabel
Pt_ARG_SECONDARY_V_ALIGN PtLabel
Pt_ARG_STYLE PtBasic
Pt_ARG_TEXT_FONT PtLabel
Pt_ARG_TEXT_IMAGE_SPACING PtLabel
Pt_ARG_TEXT_STRING PtLabel
Pt_ARG_TRANS_PATTERN PtBasic
Pt_ARG_UNDERLINE_TYPE PtLabel Not used by this class.
Pt_ARG_UNDERLINE1 PtLabel Not used by this class.
Pt_ARG_UNDERLINE2 PtLabel Not used by this class.
Pt_ARG_USER_DATA PtWidget
Pt_ARG_VERTICAL_ALIGNMENT PtLabel Pt_CENTER
Pt_ARG_WIDTH PtWidget
Pt_CB_ACTIVATE PtBasic See below.
Pt_CB_ARM PtBasic
Pt_CB_BLOCKED PtWidget
Pt_CB_DESTROYED PtWidget
Pt_CB_DISARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_FILTER PtWidget
Pt_CB_GOT_FOCUS PtBasic See below.
Pt_CB_HOTKEY PtWidget
Pt_CB_IS_DESTROYED PtWidget
Pt_CB_LOST_FOCUS PtBasic See below.
Pt_CB_MENU PtBasic
Pt_CB_OUTBOUND PtWidget
Pt_CB_RAW PtWidget
Pt_CB_REALIZED PtWidget
Pt_CB_REPEAT PtBasic
Pt_CB_UNREALIZED PtWidget

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

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:

The Pt_CB_GOT_FOCUS callbacks should return Pt_CONTINUE.

The Pt_CB_LOST_FOCUS callbacks should return:

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.