Programming with Text Box Controls
This topic describes how to complete the following tasks programmatically.
- Binding to a DataSocket source
- Creating text box controls and adding text
- Deleting text
- Determining how many lines of text exist
- Finding the line number at a byte offset
- Getting the number of bytes of text
- Obtaining a line of text
- Obtaining the entire contents of a text box
- Replacing text
- Setting a limit on characters entered
- Setting the height of the text box
- Setting the number of visible lines
- Setting the text box to be not editable
- Setting the wrap mode
- Setting whether <Enter> causes a new line
- Specifying the number of lines to retain off-screen
Creating Text Box Controls and Adding Text
Use NewCtrl to create a text box control. The SetCtrlVal function specifies that "Hello, World" display in the text box.
int panelHandle;
int textBoxCtrl;
textBoxCtrl = NewCtrl (panelHandle, CTRL_NUMERIC, "Numeric Control", 25, 25);
SetCtrlVal (panelHandle, textBoxCtrl, "Hello,\nWorld!");
Deleting Text
To delete a single, specific line of text, call the DeleteTextBoxLine function.
// Delete the first line from the text box.
DeleteTextBoxLine (panelHandle, textBoxCtrl, 0);
// Deletes the last line from the text box.
int totalLines;
GetNumTextBoxLines (panelHandle, textBoxCtrl, &totalLines);
DeleteTextBoxLine (panelHandle, textBoxCtrl, totalLines - 1);
To delete the entire contents of the text box, call DeleteTextBoxLines.
DeleteTextBoxLines (panelHandle, textBoxCtrl, 0, -1);
Replacing Text
The following example replaces the contents with text you specify.
char text[128];
GetCtrlVal (panelHandle, PANEL_TEXTBOX, text);
ReplaceTextBoxLine (panelHandle, textBoxCtrl, 0, text);
Determining How Many Lines of Text Exist
int numLines;
SetCtrlVal (panelHandle, textBoxCtrl,
"Text box controls,\nhandle more information\n
than string controls\n and can feature line,\nword,
and character wrap modes.");
GetNumTextBoxLines (panelHandle, textBoxCtrl, &numLines);
SetCtrlVal (panelHandle, PANEL_NUMLINES, numLines);
Obtaining a Line of Text
GetTextBoxLine appends a NUL byte to the end of the text string, so you must make the buffer 1 byte larger than the value returned by GetTextBoxLineLength.
char *lineText = NULL;
int length;
GetTextBoxLineLength (panelHandle, textBoxCtrl, 0, &length);
lineText = malloc(sizeof(char) * (length + 1));
GetTextBoxLine (panelHandle, textBoxCtrl, 0, lineText);
Obtaining the Entire Contents of a Text Box
GetCtrlVal appends a NUL byte to the end of the text string, so you must make the buffer 1 byte larger than the value returned by GetCtrlAttribute.
GetCtrlAttribute (panelHandle, textBoxCtrl, ATTR_STRING_TEXT_LENGTH, &textLength);
textBox = malloc (sizeof(char) * (textLength + 1));
GetCtrlVal (panelHandle, textBoxCtrl, textBox);
Getting the Number of Bytes of Text
int totalLen, selLen;
/* Get the total number of bytes in the text box control. */
GetCtrlAttribute (panelHandle, textBoxCtrlLine, ATTR_STRING_TEXT_LENGTH, &totalLen);
/* Get the number of bytes of selected text. */
GetCtrlAttribute (panelHandle, textBoxCtrlLine, ATTR_TEXT_SELECTION_LENGTH, &selLen);
SetCtrlVal (panelHandle, PANEL_TOTAL, totalLen);
SetCtrlVal (panelHandle, PANEL_SELECTED, selLen);
Setting the Height of the Text Box
Call SetTextCtrlHeight to specify the height of the text box control based on the specified width. To leave the width unchanged, pass -1 as the width.
SetTextCtrlHeight (panelHandle, textBoxCtrlLine, -1);
Finding the Line Number at a Byte Offset
You can obtain the line number index if you have a specified byte offset using the GetTextBoxLineIndexFromOffset function.
int lineNum, byteOffset;
GetCtrlVal (panelHandle, PANEL_BYTEOFFSET, &byteOffset);
GetTextBoxLineIndexFromOffset (panelHandle, PANEL_TEXTBOXOFF, byteOffset, &lineNum);
SetCtrlVal (panelHandle, PANEL_NUMOFFSETLINE, lineNum);
Setting the Wrap Mode
Text boxes can wrap by character, by word, or by line.
int textBoxCtrl, textBoxCtrlWord, textBoxCtrlLine;
textBoxCtrl = NewCtrl (panelHandle, CTRL_TEXT_BOX_LS, "Character Wrapping", 35, 45);
SetCtrlVal (panelHandle, textBoxCtrl,
"Text box controls,\nhandle more
information\nthan string controls\n
and can feature line,\nword, and
character wrap modes.");
SetCtrlAttribute (panelHandle, textBoxCtrl, ATTR_WRAP_MODE, VAL_CHAR_WRAP);
textBoxCtrlWord = NewCtrl (panelHandle, CTRL_TEXT_BOX_LS, "Word Wrapping", 35, 140);
SetCtrlVal (panelHandle, textBoxCtrlWord,
"Text box controls,\nhandle more
information\n than string controls\n
and can feature line,\nword, and
character wrap modes.");
SetCtrlAttribute (panelHandle, textBoxCtrlWord, ATTR_WRAP_MODE, VAL_WORD_WRAP);
textBoxCtrlLine = NewCtrl (panelHandle, CTRL_TEXT_BOX_LS, "Line Wrapping", 35, 230);
SetCtrlVal (panelHandle, textBoxCtrlLine,
"Text box controls,\nhandle more
information\nthan string controls\n
and can feature line,\nword, and
character wrap modes.");
SetCtrlAttribute (panelHandle, textBoxCtrlLine, ATTR_WRAP_MODE, VAL_LINE_WRAP);
Setting the Number of Visible Lines
Set the text box to display all lines. Call GetNumTextBoxLines first to get the lines in the text box.
int numLines;
GetNumTextBoxLines (panelHandle, textBoxCtrl, &numLines);
SetCtrlAttribute (panelHandle, textBoxCtrl, ATTR_VISIBLE_LINES, numLines);
Setting Whether <Enter> Causes a New Line
By default, you must press <Ctrl-Enter> to insert a new line in the text box.
SetCtrlAttribute (panelHandle, textBoxCtrl, ATTR_ENTER_IS_NEWLINE, 1);
Specifying the Number of Lines to Retain Off-Screen
By default, the text box retains all of the lines in a text box. Note that when all of the lines are not visible, you can scroll and view all of the lines. Use the ATTR_EXTR_LINES attribute to limit the number of lines to retain off-screen.
SetCtrlAttribute (panelHandle, PANEL_TEXTBOX, ATTR_EXTRA_LINES, 4);
Setting a Limit on Characters Entered
SetCtrlAttribute (panelHandle, textBoxCtrl, ATTR_MAX_ENTRY_CHARS, 250);
Setting the Text Box to be Not Editable
SetCtrlAttribute (panelHandle, textBoxCtrl, ATTR_NO_EDIT_TEXT, 1);
Binding to a DataSocket Source
(Linux) Data binding is not supported.
Controls can have only one DataSocket connection. You must specify whether the access mode is READ mode or WRITE mode:
- READ mode—The control gets data from the DataSocket source. In READ mode, the value of the text box control is updated automatically when the value changes at the source.
- WRITE mode—The control transfers data to the DataSocket source. In WRITE mode, the value at the DataSocket source is updated automatically when the value of the text box control changes.
You must enable the DataSocket option in the Edit Installer dialog box Drivers & ComponentsDrivers & Components tab if your applications use data binding.
Binding to a DataSocket Source in the User Interface Editor
Complete the following steps to bind a network variable to a text box control.
- In the Edit Text Box dialog box, click the DataSocket Binding button.
- Click the browse button to the right of the Server text box in the DataSocket Binding dialog box.
- Select the network variable you want to bind and click the OK button.
- Select whether you want to read or write data in the Connection Type option.
- Click the OK button.
Binding to a DataSocket Source Programmatically
Use DSBindCtrl to bind a text box control to a DataSocket source. The DataSocket source must hold text data.
HRESULT dsError;
static DSHandle dsHandle;
DSBindCtrl (panelHandle, textBoxCtrl, "opc://localhost/National Instruments.OPCDemo/MotorRPMSensor", VAL_DS_READ, &dsHandle, &dsError);
Use DSUnbind to disconnect the text box control from the DataSocket source.
DSUnbind (panelHandle, textBoxCtrl, &dsError);