TextField Widget Programmer's Reference


Viewing this document

This programmer's reference for the ListTree widget uses HTML3 tables, support for which is becoming very common among WWW browsers. Both Netscape and Mosaic (the most common browsers) support tables, and support for tables in Chimera (my browser of choice) will be included in version 2.0.


Usage

To use the TextField widget in an application, include the three source code files TextField.c, TextField.h, and TextFieldP.h with the rest of the source code for the application. Include the object TextField.o in the Makefile rule that compiles the application.

In source code that uses the TextField widget, include the following two header files before references to the plot widget:

 #include <X11/Intrinsic.h>
 #include "TextField.h"

To create the TextField widget, use the following code as an example:

  text = XtVaCreateManagedWidget("text",textfieldWidgetClass,parent,
                NULL);

This example creates a default size empty TextField widget as the child of some container widget named parent. See Public Functions below for descriptions of all of the convenience functions.


New Resources

The TextField widget defines the following new resources:
NameClassTypeDefault
XtNallowSelectionXtCBooleanBooleanTrue
XtNdisplayCaretXtCBooleanBooleanTrue
XtNechoXtCBooleanBooleanTrue
XtNeditableXtCBooleanBooleanTrue
XtNfontXtCFontXFontStruct *XtDefaultFont
XtNforegroundXtCForegroundPixelXtDefaultForeground
XtNinsertPositionXtCInsertPositionint0
XtNlengthXtCLengthint0
XtNmarginXtCMarginDimension2
XtNpendingDeleteXtCBooleanBooleanTrue
XtNstringXtCStringchar *NULL

XtNallowSelection
Allow the user to highlight selections (and paste selections) in the widget.

XtNdisplayCaret
Display the insertion cursor.

XtNecho
Echoes the user's input to the widget's window. If set to False, this resource disables all displays to the window except the insertion cursor, which moves as normal. (See XtNdisplayCaret for that function.) Note that all actions, including highlighting and selections, are still performed, but none of the text is visible.

XtNeditable
Allow the user to type in the widget. (Note the difference between this and XtNallowSelection.)

XtNfont
Font to use for items.

XtNforeground
Foreground color for text. Also used for the bitmap color, if any of the Pixmap resources is defined instead as a bitmap.

XtNinsertPosition
Character position (not pixel position) of the insertion cursor

XtNlength
Maximum length of editable string, or 0 if unlimited

XtNmargin
Pixel spacing between the border of the widget and the text.

XtNpendingDelete
Controls the Motif-like pending delete mode. If true, a highlighted text selection will be replaced with the next keyboard input from the user. If false, any text selection is ignored, the highlight cleared, and the user input is placed at the cursor.

XtNstring
The string that the widget is currently using.


Callbacks

Callback Resources

The TextField widget defines the following callback resources:

XtNactivateCallback
Called when the Return key is pressed in the widget.

Activate Callback

This callback is called whenever an item is opened, or if an item is explicitly closed. The following structure is sent to the callback.

 typedef struct _TextFieldReturnStruct {
   int     reason;         /* Motif compatibility */
   XEvent  *event;
   char    *string;
 } TextFieldReturnStruct;

reason
For future Motif compatibility. Currently unused.

event
The XEvent that triggered the action.

string
The current string in the text widget. This is a pointer to the actual string, so don't do anything funny like free()ing the text or changing its contents.


Translations

The text translations used in TextField are a similar to the translations available in both the Motif and Athena widgets.

EventAction
<Key>Rightforward-char()
<Key>Leftbackward-char()
<Key>Deletedelete-next-char()
<Key>BackSpacedelete-previous-char()
<Key>Returnactivate()
Shift<Btn1Down>extend-start()
<Btn1Down>select-start()
<Btn1Motion>extend-adjust()
<Btn1Up>extend-end()
<Btn2Down>insert-selection()
<Btn3Down>extend-start()
<Btn3Motion>extend-adjust()
<Btn3Up>extend-end()


Action Routines

This is a very limited subset of the actions available in either the Motif or Athena text widgets. I don't find that I use many of the fancy translations for a single line widget, so maybe you won't either.

Currently, none of the action routines take parameters.

activate()
Calls the XtNactivateCallback

backward-char()
Moves cursor back one character

delete-next-char()
Deletes character after the cursor

delete-previous-char()
Deletes character before the cursor

extend-adjust()
Extends the current text selection

extend-end()
Ends the text selection and copies it into the cut buffer

extend-start()
Extends an existing selection

forward-char()
Moves cursor forward one character

insert-selection()
Pastes a selection at the cursor

select-start()
Begins a text selection


Public Functions

These convenience functions mimic the functionality of the Motif XmTextField widget.

Boolean TextFieldGetEditable (Widget w)
Returns the XtNeditable state of the widget

int TextFieldGetInsertionPosition (Widget w)
Returns the current character position of the insertion cursor. Note that character positions start at zero.

char *TextFieldGetString (Widget w)
Returns a copy of the current text string. Due to Motif compatibility, the user must free() this pointer.

void TextFieldInsert (Widget w, int pos, char *str)
Inserts the string pointed to by str at the insertion posititon pos.

void TextFieldReplace (Widget w, int first, int last, char *str)
Replaces the text from positions first to last with str. If first == last, this function performs identically to TextFieldInsert().

void TextFieldSetEditable (Widget w, Boolean editable)
Sets the editable state of the widget.

void TextFieldSetInsertionPosition (Widget w, int pos)
Sets the insertion cursor position to pos.

void TextFieldSetSelection (Widget w, int start, int end, Time time)
Highlights the range start to end.

void TextFieldSetString (Widget w, char *str)
Sets the text in the widget to str and unhighlights and previous selection.

About the author | Send me E-mail | TextField home page | Top of page