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.
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.
The TextField widget defines the following new resources:
Name | Class | Type | Default
|
---|
XtNallowSelection | XtCBoolean | Boolean | True
|
XtNdisplayCaret | XtCBoolean | BooleanTrue
|
XtNecho | XtCBoolean | Boolean | True
|
XtNeditable | XtCBoolean | Boolean | True
|
XtNfont | XtCFont | XFontStruct * | XtDefaultFont
|
XtNforeground | XtCForeground | Pixel | XtDefaultForeground
|
XtNinsertPosition | XtCInsertPosition | int | 0
|
XtNlength | XtCLength | int | 0
|
XtNmargin | XtCMargin | Dimension | 2
|
XtNpendingDelete | XtCBoolean | Boolean | True
|
XtNstring | XtCString | char * | 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.
The TextField widget defines the following callback resources:
- XtNactivateCallback
- Called when the Return key is pressed in the widget.
- XtNvalueChangedCallback
- Called after the value in the text widget changes.
- XtNfocusCallback
- Called when the widget receives keyboard focus.
- XtNlosingFocusCallback
- Called when the widget loses keyboard focus.
- XtNgainPrimaryCallback
- Caleld when the widget obtains the primary selection.
- XtNlosePrimaryCallback
- Caleld when the widget loses the primary selection.
- XtNmodifyVerifyCallback
- Called before user modifies text.
- XtNmotionVerifyCallback
- Called before user moves cursor.
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; /* TF_ACTIVATE */
XEvent *event; /* event which activated the widget */
char *string; /* new value */
} TextFieldReturnStruct;
- reason
- Always set to TF_ACTIVATE.
- 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.
This callback is called whenever the widget contents are
changed. The following structure is sent to the callback.
typedef struct _TextFieldReturnStruct {
int reason; /* TF_ACTIVATE */
XEvent *event; /* event which changed the widget */
char *string; /* new value */
} TextFieldReturnStruct;
- reason
- Always set to TF_VALUE_CHANGED.
- event
- The XEvent that caused the change.
- 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.
This callback is called whenever the widget receives keyboard
focus. The following structure is sent to the callback.
typedef struct _TextFieldReturnStruct {
int reason; /* TF_FOCUS */
XEvent *event; /* focus event */
char *string; /* current value */
} TextFieldReturnStruct;
- reason
- Always set to TF_FOCUS.
- event
- The XEvent that triggered the action.
- string
- The current string in the text widget.
This callback is called whenever the widget loses focus.
The following structure is sent to the callback.
typedef struct _TextFieldVerifyStruct {
int reason ; /* TF_LOSING_FOCUS */
XEvent *event ;
Boolean doit ;
int curInsert, newInsert ;
int startPos, endPos ;
TextFieldBlock text ;
} TextFieldVerifyStruct ;
- reason
- Always set to TF_LOSING_FOCUS.
- event
- The XEvent that triggered the action.
- curInsert, newInsert
- The current cursor position.
Other fields should be ignored.
This callback is called whenever the widget obtains the
primary selection.
The following structure is sent to the callback.
typedef struct _TextFieldReturnStruct {
int reason; /* TF_GAIN_PRIMARY */
XEvent *event; /* event which activated the widget */
char *string; /* current value */
} TextFieldReturnStruct;
- reason
- Always set to TF_GAIN_PRIMARY.
- event
- The XEvent that triggered the action.
- string
- The current string in the text widget.
This callback is called whenever the widget loses the
primary selection. The following structure is sent to the callback.
typedef struct _TextFieldReturnStruct {
int reason; /* TF_LOSE_PRIMARY */
XEvent *event; /* NULL */
char *string; /* current value */
} TextFieldReturnStruct;
- reason
- Always set to TF_LOSE_PRIMARY.
- event
- NULL.
- string
- The current string in the text widget.
This callback is called before the widget contents
are modified. The callback proc has the opportunity to inspect the
change to be made, and to veto if desired. If text is being inserted,
the callback proc may replace it with text of its own choosing.
typedef struct _TextFieldVerifyStruct {
int reason ; /* TF_MODIFYING_TEXT_VALUE */
XEvent *event ;
Boolean doit ;
int curInsert, newInsert ;
int startPos, endPos ;
TextFieldBlock text ;
} TextFieldVerifyStruct ;
typedef struct {
char *ptr ;
int length ;
int format ; /* reserved; Motif compatibility */
} TextFieldBlockRec, *TextFieldBlock ;
- reason
- Always set to TF_MODIFYING_TEXT_VALUE.
- event
- The XEvent that triggered the action.
- doit
- Set this value to False to abort the modification.
- curInsert
- Current insert position.
- newInsert
- New insert position. The cursor will be set to this position
after text is deleted (if any) and new text is inserted.
- startPos
- Start of text to be deleted. -1 if no delete.
- endPos
- End of text to be deleted. -1 if no delete.
- text
- Pointer to text block. May be NULL for delete-only.
- ptr
- Pointer to text to be inserted.
- length
- Number of characters in text block.
- format
- Reserved; currently not used.
When the text field is Non-NULL, it points to text
which will be inserted. This buffer may be modified in-place
by the callback proc, provided that the buffer is not extended.
If you need to extend the text, replace ptr with a
pointer to the new text to be inserted.
This callback is called before the widget cursor is moved
to a new position. Callback proc may veto the change.
typedef struct _TextFieldVerifyStruct {
int reason ; /* TF_MODIFYING_TEXT_VALUE */
XEvent *event ;
Boolean doit ;
int curInsert, newInsert ;
int startPos, endPos ;
TextFieldBlock text ;
} TextFieldVerifyStruct ;
typedef struct {
char *ptr ;
int length ;
int format ; /* reserved; Motif compatibility */
} TextFieldBlockRec, *TextFieldBlock ;
- reason
- Always set to TF_MOVING_INSERT_CURSOR.
- event
- The XEvent that triggered the action.
- doit
- Set this value to False to abort the modification.
- curInsert
- Current insert position.
- newInsert
- New insert position. The cursor will be set to this position
after all callbacks are called.
- startPos, endPos
- Not used.
- text
- Not used.
The text translations used in TextField are a similar to the translations
available in both the Motif and Athena widgets.
Event | Action
|
---|
<Key>Right | forward-char()
|
<Key>Left | backward-char()
|
<Key>Delete | delete-next-char()
|
<Key>BackSpace | delete-previous-char()
|
<Key>Return | activate()
|
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()
|
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
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