WwText Function

Creates a text widget that can be used for both single-line text entry or as a full text editor. In addition, this function can create a static text label.

Usage

text = WwText(parent, verifyCallback)

Input Parameters

parent — The widget ID of the parent widget.

verifyCallback — (Optional) A string containing the name of a callback routine that is executed when the contents of the text field changes.

Returned Value

text — The text widget ID.

Keywords

Cols — Specifies the number of columns in the text field (in characters).

File — Specifies a name of a file containing text.

HScroll — (Windows only) If nonzero, multiline text windows are created with a horizontal scroll bar.

Label — If nonzero, the widget is a label (static text). The value of the label is set using the Text keyword. If Label is nonzero and Text is not used, the function looks for a label in a resource specification (see Discussion).

If the Label keyword is set to a string value, the text field (single line) widget or text edit (multi-line) widget is preceded by this string.

Layout_name — A string containing the name of the Form widget created when Form is specified and both Text and Label are specified as strings. The Layout_name specified is part of the resource specification. (Default: caption)

Name — Specifies the name of the Label and/or Text widgets. The Name specified is part of the resource specification containing the label or text widget names. The default for Name depends on other keywords being specified and how they are specified in the WwText usage.

If both Label and Text are specified as null strings, Name is a two-element string array naming the Text widget and the Label widget (in that order). (Default: *caption.text.value; and
*caption.label.labelString, respectively)

Pixmap — Specifies a filename containing a pixmap or bitmap file to be displayed as a label. This keyword is used in conjunction with the Label keyword.

Position — If the text widget is to be placed in a bulletin board layout, use this keyword to specify the x, y coordinates of the text widget within the bulletin board.

Read — If present and nonzero, the text widget is read only.

Rows — Specifies the number of rows in the text field.

Tab_WinOff — (Windows only) If this keyword is present and nonzero, the tab navigation feature is turned off for this widget. For text widgets, if the tab navigation attribute is set to 1, the Tab key works as an action, and does not introduce a tab character into the text box. If the tab navigation attribute is set to 0, the Tab key press places a tab into the text box.

Text — Specifies a label for the text field. If Text is not defined or is defined as a null string, the function looks for the text field label in a resource specification (see Discussion).

VScroll — (Windows only) If nonzero, multiline text windows are created with a vertical scroll bar.

Wrap — (Windows only) Causes text in a multi-line Wwtext box to word wrap at the widget boundary. This keyword is ignored if the HScroll keyword is also set.

Color/Font Keywords

Background — Specifies the background color name.

Font — Specifies the name of the font used for text.

MSFont — Adds support for Windows fonts.

Foreground — Specifies the foreground color name.

Attachment Keywords

Bottom — If a widget ID is specified (for example, Bottom=wid), then the bottom of the text widget is attached to the top of the specified widget. If no widget ID is specified (for example, /Bottom), then the bottom of the text widget is attached to the bottom of the parent widget.

Left — If a widget ID is specified (for example, Left=wid), then the left side of the text widget is attached to the right side of the specified widget. If no widget ID is specified (for example, /Left), then the left side of the text widget is attached to the left side of the parent widget.

Right — If a widget ID is specified (for example, Right=wid), then the right side of the text widget is attached to the left side of the specified widget. If no widget ID is specified (for example, /Right), then the right side of the text widget is attached to the right side of the parent widget.

Top — If a widget ID is specified (for example, Top=wid), then the top of the text widget is attached to the bottom of the specified widget. If no widget ID is specified (for example, /Top), then the top of the text widget is attached to the top of the parent widget.

Get/Set Value

getvalue — A string containing the displayed text.

setvalue — A string containing the displayed text.

Callback Parameters

Text widget callback procedures must have the following two parameters:

wid — Text widget ID.

parent — Parent widget ID.

Discussion

If the Label keyword is set to a null string and Name is not used, the function looks in *caption.label.labelString for the label resource. The text resource can also be specified using the Name keyword if the Text keyword is specified as a null string. The text resource default is *caption.text.labelString.

Note:

By default, if the linelength or number of lines of text in the widget exceeds the size of the widget, horizontal and/or vertical scroll bars are attached to the widget automatically. To force the attachment of scroll bars to a text widget, use the HScroll and/or VScroll keywords. When these keywords are used, scroll bars will not dynamically appear or disappear once the text widget is created. The Label and Text keywords provide a method for “hard-coding” labels and text field labels (respectively) in the application. For greater flexibility, define a resource file containing the label or text by using WtResource, and use the Name keyword in the WwText calling sequence to access the resources.

Example 1: Single-line Text Field and Label

This example creates a layout widget containing a single-line text field and a label. The callback is executed when the user enters text in the text field and presses <Return>.

Enter the callback procedure into a file, and compile the procedure with the .RUN command. Then, enter the widget commands at the WAVE> prompt (or enter them in a command file and run it with the @ command). To dismiss the button box, select the appropriate function (such as Close) from the window manager menu.

Callback Procedure

PRO TextCB, wid, data

   PRINT, 'Text done'

   value = WwGetValue(wid)

   PRINT, value

END

Widget Commands

; Initialize WAVE Widgets and create the form layout widget.

top=WwInit('ww_ex35', 'Examples', layout, /Form)

; Create the label widget.

label = WwText(layout, /Label, Text='This is Label')

; Create the single-line text field widget, attaching it to the 

; right edge of the label widget.

text = WwText(layout, 'TextCB', Cols=40, left=label)

status = WwSetValue(top, /Display)

WwLoop

END

Example 2: Multi-line Text Window

This example creates a multi-line text window. Because the Read keyword is used, the text is read-only.

Callback Procedure

PRO TextCB, wid, data

   PRINT, 'Text done'

   value = WwGetValue(wid)

   PRINT, value

END

Widget Commands

top = WwInit('ww_ex36', 'Examples', layout)

filename = GETENV('WAVE_DIR')+'/Tips'

text = WwText(layout, 'TextCB', /Read, $

   File=filename, Cols=40, Rows=20)

status = WwSetValue(top, /Display)

WwLoop

END

Example 3: Initializing with a Multi-Line String

This example shows how to initialize a text widget with a multi-line string, and it prints the contents of the text widget each time it is changed.

Callback Procedure

PRO TextCB, w, p

    PM, ' '

    PM, WwGetValue(w) 

END

Widget Commands

t = WwInit( 'a', 'a', w )

e = WwText( w, 'TextCB', Rows=15, Cols=20 )

s = WwSetValue( t, /Display )

IF STRMID(GETPLATFORM(),0,3) EQ 'win' THEN BEGIN

    a = 'a' + STRING(13b) + STRING(10b) + 'a'

    PRINT, BYTE(a)

ENDIF ELSE BEGIN

    a = 'a' + STRING(10b) + 'a'

    PRINT, BYTE(a)

ENDELSE

s = WwSetValue(e,a)

PRINT, BYTE(a)

WwLoop

END

See Also

WgTextTool Procedure

For detailed information on GUI development, refer to the PV‑WAVE Application Developer’s Guide.

For more information about how to write an application program based on PV‑WAVE Widgets, refer to Using Wave Widgets in the PV‑WAVE Application Developer’s Guide.

For additional information on the color and font keywords, see "Setting Colors and Fonts" in the PV‑WAVE Application Developer’s Guide.

For additional information on attachment keywords, see "Form Layout: Attachments" in the PV‑WAVE Application Developer’s Guide.

For information on Get and Set values, see "Setting and Getting Widget Values" in the PV‑WAVE Application Developer’s Guide.