|
Purpose |
Add a text box control to a dialog. A text box is very similar to a
conventional edit control, and it is used to enter text into an application.
Text boxes support single-line and multiple-line input. |
|
Syntax |
CONTROL ADD TEXTBOX, hDlg,
id&, txt$,
x, y,
xx, yy
[, [style&] [, [exstyle&]]]
[[,] CALL callback] |
|
hDlg |
of the dialog in which the text box will be created. The dialog will become
the
of the control. |
|
id& |
Unique
for the control in the range 1 to 65535, frequently specified with numeric equates for clarity of the code.
For example, the equate %CustomerName
is more informative than a literal
value such as 497. Best practice suggests identifiers should start at
100 to avoid conflict with any of the standard predefined identifiers. |
|
txt$ |
Default text to be displayed in text box. txt$ may be a
string, string equate, or string
expression. txt$ can be empty
if there is no default text. |
|
x, y |
Integer expressions,
variables, or numeric
literal values, specifying the location of the control inside the
dialog .
x is the horizontal position,
and y is the vertical position.
0,0 refers to the upper left corner of the dialog box client area. Coordinates
are specified in the same terms (pixels or )
as the parent dialog. |
|
xx |
Integer expression, variable, or numeric literal value, specifying the
width of the control. The width is given in the same terms (pixels or
dialog units) as the parent dialog. The most common value used in the
Microsoft Dialog Editor and Visual Studio is 100 dialog units. |
|
yy |
Integer expression, variable, or numeric literal value, specifying the
height of the control. The height is given in the same terms (pixels or
dialog units) as the parent dialog. The most common value used in the
Microsoft Dialog Editor and Visual Studio is 12 dialog units. |
|
style& |
Primary style of the text box control.
The default text box style comprises %WS_TABSTOP, %WS_BORDER, %ES_LEFT,
and %ES_AUTOHSCROLL. The default style is used if both the primary and
extended style parameters are omitted from the statement. For example:
CONTROL ADD TEXTBOX, hDlg, id&, txt$, 100, 100,
150, 200, , , _
CALL
EditControlCallback() ' Use default styles
Custom style values replace the default values. That is, they are not
additional to the default style values - your code must specify all necessary
primary and extended style parameters.
The primary text box style value can be a combination of any values
below, combined together with the OR operator
to form a bitmask:
|
%ES_AUTOHSCROLL |
Automatically scroll text
to the right by 10 characters when the user types a character at the end
of the line. When the user presses the ENTER key, scroll all text back
to position zero. Also see %WS_AUTOHSCROLL. |
|
%ES_AUTOVSCROLL |
Automatically scroll text
up one page when the user presses the ENTER key on the last line. This
must be combined with the %ES_WANTRETURN and %ES_MULTILINE styles. Also
see %WS_VSCROLL. |
|
%ES_CENTER |
Center text in a multi-line
edit control. |
|
%ES_LEFT |
Left-aligns text. (default) |
|
%ES_LOWERCASE |
Convert all characters
to lowercase as they are typed into the edit control. |
|
%ES_MULTILINE |
Allow the control to accept
multiple lines of input. By default, the ENTER key activates the default
button on the dialog. To use the ENTER key as a carriage return in the
text box control, include the %ES_WANTRETURN style.
If the %ES_AUTOHSCROLL
style is included, the control automatically scrolls horizontally when
the caret goes past the right edge of the control. Otherwise, the control
automatically wraps words to the beginning of the next line when necessary.
The control size determines the position of the word wrap. |
|
%ES_NOHIDESEL |
Negate the default behavior
for a text box. The default behavior hides the selection when the control
loses the input ,
and inverts the selection when the control receives the input focus. If
you specify %ES_NOHIDESEL, the selected text is inverted, even if the
control does not have the focus. |
|
%ES_NUMBER |
Allow only digits ("0123456789")
instead of characters. Although Windows does not consider the negation
symbol (-) or period symbol (.) to be digits,
a TextBox that does not use %ES_NUMBER and rejecting "unwanted"
keystrokes is common practice among advanced programmers). |
|
%ES_OEMCONVERT |
Text is converted from
the windows character set to OEM, then back to Windows, as it is entered. |
|
%ES_PASSWORD |
Display an asterisk (*)
for each character typed into the control in order to obscure the password. |
|
%ES_READONLY |
Prevent the user from typing
or editing text in the control. Text can still be selected and copied
from the control to the clipboard with the mouse. |
|
%ES_RIGHT |
Right-align text in a multi-line
text box. |
|
%ES_UPPERCASE |
Convert all characters
to uppercase as they are typed into the control. |
|
%ES_WANTRETURN |
Allow the ENTER key to
insert a carriage return in a multi-line text box. Otherwise, the ENTER
key works as the dialog box's default push button. This style has no effect
on a single-line text box. |
|
%WS_BORDER |
Add a thin line border
around the text box control. |
|
%WS_HSCROLL |
Add a horizontal scroll
bar to the edit control, when used in conjunction to the %ES_AUTOHSCROLL
style. |
|
%WS_GROUP |
Define the start of a group
of controls. The first control in each group should also use %WS_TABSTOP
style. The next %WS_GROUP control in the tab order defines the end of
this group and the start of a new group. |
|
%WS_TABSTOP |
Allow the textbox control
to receive keyboard focus when the user presses the TAB and SHIFT+TAB
keys. The TAB key shifts keyboard focus to the next control with the %WS_TABSTOP
style, and SHIFT+TAB shifts focus to the previous control with %WS_TABSTOP.
(default) |
|
%WS_VSCROLL |
Add a vertical scroll bar
to the edit control. This style should be used in conjunction to the %ES_MULTILINE
and %ES_AUTOVSCROLL styles. |
|
|
exstyle& |
Extended style of the text box control. The default extended text box
style comprises %WS_EX_CLIENTEDGE with %WS_EX_LEFT. The default extended
style is used if both the primary and extended parameters are omitted
from the CONTROL ADD TEXTBOX statement, in the same manner as style&
above.
The extended text box style value can be a combination of any values
below, combined together with the OR operator to form a bitmask:
|
%WS_EX_CLIENTEDGE |
Apply a sunken edge border
to the control. |
|
%WS_EX_LEFT |
The control has generic
"left-aligned" properties. (default) |
|
%WS_EX_RIGHT |
The control has generic
"right-aligned" properties. This style has an effect only if
the shell language is Hebrew, Arabic, or another language that supports
reading order alignment; otherwise, the style is ignored. |
|
%WS_EX_STATICEDGE |
Apply a three-dimensional
border style to the control (intended to be used for items that do not
accept user input). |
|
%WS_EX_TRANSPARENT |
Controls/windows beneath
the control are drawn before the control is drawn. The control is deemed
transparent because elements behind the control have already been painted
- the control itself is not drawn differently. True transparency is achieved
by using Regions - see MSDN for
more information. |
|
%WS_EX_WINDOWEDGE |
Apply a raised edge border
to the control. |
|
|
callback |
Optional name of a Callback Function to
handle all %WM_COMMAND
for the text box. If a callback for the control is not designated, you
must create a Callback Function for the dialog to process notification
messages.
If the Callback Function processes a message, it should return TRUE
(non-zero) to prevent the message being passed unnecessarily to the dialog
callback (if one exists). The dialog callback should also return TRUE
if the notification message is processed by that Callback Function. Otherwise,
the DDT engine processes unhandled
messages. |
|
Remarks |
If you specify the %ES_AUTOHSCROLL style, the control automatically
scrolls horizontally when the caret goes past the right edge of the control.
To start a new line, the user must press the ENTER key.
If you do not specify %ES_AUTOHSCROLL, the control automatically wraps
words to the beginning of the next line when necessary. A new line is
also started if the user presses the ENTER key. The control size determines
the position of the word wrap.
The following notifications are sent to the Callback Function:
|
%EN_CHANGE |
Sent when the user has
taken an action that may have altered text in the text box. Unlike the
%EN_UPDATE notification, this message is sent after Windows updates the
screen. Programmatically changing the text in a control also triggers
this message. |
|
%EN_ERRSPACE |
Sent when the text box
cannot allocate enough memory to meet a specific request. |
|
%EN_HSCROLL |
Sent when the user clicks
a multi-line text box's horizontal scroll bar. The callback is notified
before the screen is updated. |
|
%EN_KILLFOCUS |
Sent when an edit control
loses the keyboard focus. |
|
%EN_MAXTEXT |
Sent when the current text
insertion has exceeded the specified number of characters for the text
box. The text insertion is truncated. |
|
%EN_SETFOCUS |
Sent when an edit control
receives the keyboard focus. |
|
%EN_UPDATE |
Sent when a text box is
about to display altered text. This notification message is sent after
the control has formatted the text, but before it displays the text. Also
see %EN_CHANGE. |
|
%EN_VSCROLL |
Sent when the user clicks
a text box's vertical scroll bar. The callback is notified before the
screen is updated. |
When a Callback Function receives a %WM_COMMAND message, it should explicitly
test the value of CBCTL and CBCTLMSG
to guarantee it is responding appropriately to the notification message.
Use CONTROL GET TEXT to
retrieve the text from a text box control, and use CONTROL SET TEXT
to change the text in a text box control. Changing the text in a text
box control (in response to a %EN_CHANGE or %EN_UPDATE message) will trigger
a second set of %EN_CHANGE and %EN_UPDATE messages. Unless this is compensated
for, these notifications can unwittingly cause an endless loop.
For example, the following is potentially fatal:
CALLBACK FUNCTION EditControlCallback()
IF
CBCTL = %ID_EDITBOX1 AND CBCTLMSG = %EN_CHANGE THEN
CONTROL
SET TEXT CBHNDL, CBCTL, "New Text"
EXIT
FUNCTION
END
IF
...
As CONTROL SET TEXT is a "blocking" statement (that is, the
statement does not complete until the text has been changed), it is a
simple matter to block the endless loop effect:
CALLBACK FUNCTION EditControlCallback()
STATIC
EditBusy&
IF
CBCTL = %ID_EDITBOX1 AND CBCTLMSG = %EN_CHANGE THEN
IF
EditBusy& THEN EXIT FUNCTION
EditBusy&
= -1
CONTROL
SET TEXT CBHNDL, CBCTL, "New Text"
RESET
EditBusy&
EXIT
FUNCTION
END
IF
... |
|
See also |
Dynamic Dialog Tools,
CONTROL GET TEXT, CONTROL SET TEXT |