Using Edit Controls

About edit controls

An edit control is a rectangular control window typically used in a dialog box to permit the user to enter and edit text from the keyboard. Edit controls are single font, single text color controls. If you need more advanced word processing features see the documentation on rich edit controls.

Creating the control

Edit controls are created either through the dialog editor or manually with the CONTROL statement.

Edit control styles

The following edit style flags can be specified in the CONTROL statement or by ticking the corresponding check box in the control properties of the dialog editor:

@CTEDITLEFT

Text is left justified in the edit control

@CTEDITRIGHT

Text is right justified in the edit control

@CTEDITMULTI

Designates a multiline edit control. The default is single-line edit control. When the multiline edit control is in a dialog box, the default response to pressing the ENTER key is to activate the default button. To use the ENTER key as a carriage return, use the @CTEDITRETURN style. When the multiline edit control is not in a dialog box and the @CTEDITAUTOV style is specified, the edit control shows as many lines as possible and scrolls vertically when the user presses the ENTER key. If you do not specify @CTEDITAUTOV, the edit control shows as many lines as possible and beeps if the user presses the ENTER key when no more lines can be displayed. If you specify the @CTEDITAUTOH style, the multiline edit 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 @CTEDITAUTOH, 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 window size determines the position of the word wrap. If the window size changes, the word wrapping position changes and the text is redisplayed. Multiline edit controls can have scroll bars. An edit control with scroll bars processes its own scroll bar messages. Note that edit controls without scroll bars scroll as described in the previous paragraphs and process any scroll messages sent by the parent window.

@CTEDITPASS

Displays an asterisk (*) for each character typed into the edit control.

@CTEDITCENTER

Text is centered within the edit control

@CTEDITRO

The edit control is read only and text can be displayed but not entered

@CTEDITAUTOH

Automatically scrolls 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, the control scrolls all text back to position zero.

@CTEDITAUTOV

Automatically scrolls text up one page when the user presses the ENTER key on the last line.

@CTEDITRETURN

Specifies that a carriage return be inserted when the user presses the ENTER key while entering text into a multiline edit control in a dialog box. If you do not specify this style, pressing the ENTER key has the same effect as pressing the dialog box’s default push button. This style has no effect on a single-line edit control.

@CTEDITNUMBER

Restricts text entered in a single line edit control to numerals only (0 - 9)

In addition to the edit styles the following window styles can also be specified:

@TABSTOP

Moves the input focus between controls if controls are in a dialog. This style has no effect for controls created in a window.

@GROUP

Specifies the first control of a group of controls in which the user can move from one control to the next with the arrow keys. All controls defined without the @GROUP style  after the first control belong to the same group. The next control with the @GROUP style starts the next group (that is, one group ends where the next begins)

@HSCROLL

The control has a horizontal scroll bar

@VSCROLL

The control has a vertical scrollbar

Edit control functions and statements

The following EBASIC functions and statements are used to communicate with the edit control.

SETCONTROLTEXT window | dialog, ID, text$

Changes the text in the edit control. Any text previously in the control will be replaced.

text$ = GETCONTROLTEXT (window | dialog, ID)

Retrieves the text in the edit control.

SETCONTROLCOLOR window|dialog, ID, fg, bg

Sets the text color and background color of the edit control. The edit control can only have a single text color.

return = CONTROLEXISTS (window | dialog, ID)

Returns 1 if the control with ID exists in the window or dialog.

ENABLECONTROL window | dialog, ID, 0 | 1

Disables or enables the edit control. If the edit control is disabled no text can be entered and the control will not receive input focus when clicked on. A disabled control will also not accept any new text with the SETCONTROLTEXT statement.

SETFOCUS window | dialog, ID

Gives the control the input focus. The edit control shows the caret.

SENDMESSAGE window | dialog, msg, wparam, lparam ,ID

Sends a message to the control for advanced functionality.

SHOWWINDOW window, flags, ID

Changes the visibility state of the control. Use @SWHIDE to hide the control and @SWRESTORE to show the control

SETSIZE dialog|window, L, T, W, H ,ID

Changes the size of the control. The edit control is redrawn and the text will be formatted to match the new size of the control. The dimensions include the borders of the control.

Clipboard operations

CONTROLCMD window | dialog, ID, @EDCUT

Use this command to delete (cut) the current selection (if any) in the edit control and copy the deleted text to the Clipboard.

CONTROLCMD window | dialog, ID, @EDCOPY

Use this command to copy the current selection (if any) in the edit control to the Clipboard.

CONTROLCMD window | dialog, ID, @EDPASTE

Use this command to insert the data from the Clipboard into the edit control at the insertion point, the location of the caret. Data is inserted only if the Clipboard contains data in text format.

Line operations

count = CONTROLCMD ( window | dialog, ID, @EDGETLINECOUNT)

Use this function to retrieve the number of lines in the edit control

CONTROLCMD ( window | dialog, ID, @EDGETLINE, linenum, line$ {,cchLine} )

Use this function to retrieve a line of text from the edit control.

Linenum is the 0 based index of the line to retrieve, cchLine is the size of the line$ STRING variable, defaults at 255.

line = CONTROLCMD ( window | dialog, ID, @EDGETFIRSTLINE)

Use this function to retrieve the zero-based index of the uppermost visible line.

line = CONTROLCMD ( window | dialog, ID, @EDLINEFROMCHAR, index)

Use this function to retrieve the line number of the line that contains the specified character index.

Index is the number of characters from the beginning of the edit control.

char_index = CONTROLCMD ( window | dialog, ID, @EDCHARFROMLINE, linenum)

Use this function to retrieve the character index of the first character of the specified line.

length = CONTROLCMD ( window | dialog, ID, @EDGETLINELENGTH, index)

Use this function to retrieve the length of a line in a edit control. When @RTGETLINELENGTH is called for a multiple-line edit control, the return value is the length (in bytes) of the line specified by index. When @RTGETLINELENGTH is called for a single-line edit control, the return value is the length (in bytes) of the text in the edit control.

Index specifies the character index of a character in the line whose length is to be retrieved. If this parameter is –1, the length of the current line (the line that contains the caret) is returned

Selection operations

CONTROLCMD window | dialog, ID, @EDGETSELECTION, varStart, varEnd

Use this command to retrieve the current selection of the edit control.

varStart and varEnd must be of type INT. The zero-based index of the first and last characters selected are copied into the two variables. The selection includes everything if varStart =0 and varEnd = -1.

CONTROLCMD window | dialog, ID, @EDDELETESEL

Use this statement to delete the current selection. The deletion performed by @EDDELETESEL can be undone by using @EDUNDO

CONTROLCMD window | dialog, ID, @EDSETSELECTION, start, end

Use this statement to set the current selection in the edit control

start and end are the zero-based character indexes of the selection. If start = 0 and end = -1 then all of the text is selected.

CONTROLCMD window | dialog, ID, @EDREPLACESEL, text$

Use this statement to replace the current selection text

Editing operations

CONTROLCMD window | dialog, ID, @EDUNDO

Use this statement to undo the last editing operation. An undo operation can also be undone. For example, you can restore deleted text with the first call to Undo. As long as there is no intervening edit operation, you can remove the text again with a second call to Undo.

return = CONTROLCMD (window | dialog, ID, @EDCANUNDO)

Use this function to determine if the last editing operation can be undone. Returns 0 if the last operation cannot be undone.

CONTROLCMD window | dialog, ID, @EDEMPTYUNDO

Use this statement to reset (clear) the undo flag of this edit control. The control will now be unable to undo the last editing operation. The undo flag is set whenever an operation within the rich edit control can be undone.

General operations

return = CONTROLCMD (window | dialog, ID, @EDGETMODIFIED)

Use this function to determine if the contents of the edit control have changed. Returns 1 if the contents have been modified, 0 otherwise.

CONTROLCMD window | dialog, ID, @EDSETMODIFIED, mod

Sets the modified flag of the edit control.

Mod can be 0 to reset the flag or 1 to set it.

length = CONTROLCMD (window | dialog, ID, @EDGETLIMITTEXT)

Use this function to get the text limit for this edit control. The text limit is the maximum amount of text, in bytes, the edit control can accept either through pasting or typing.

CONTROLCMD window | dialog, ID, @EDSETLIMITTEXT, length

Use this function to set the text limit for this edit control. The text limit is the maximum amount of text, in bytes, the edit control can accept either through pasting or typing. The default limit is 32767 bytes for multi line controls.

CONTROLCMD window | dialog, ID, @EDSETMARGINS, left, right

Use this statement to set the visible left and right margins of the edit control.

Left and right are specified in pixels.

Notification messages

An edit control sends notification messages to the parent window or dialog in the @NOTIFYCODE variable. The ID of the control is found in @CONTROLID. The following notification messages are supported:

@ENKILLFOCUS

Control has lost input focus

@ENSETFOCUS

Control has been given the input focus

@ENERRSPACE

Control could not complete an operation because there was not enough memory available

@ENMAXTEXT

While inserting text, the user has exceeded the specified number of characters for the edit control. Insertion has been truncated. This message is also sent either when an edit control does not have the @CTEDITAUTOH style and the number of characters to be inserted exceeds the width of the edit control or when an edit control does not have the @CTEDITAUTOV style and the total number of lines to be inserted exceeds the height of the edit control.

@ENUPDATE

The contents of the control are about to change

@ENCHANGE

The contents of the control have changed.

@ENHSCROLL

The user has clicked the edit control’s horizontal scroll bar. Windows sends this message before updating the control.

@ENVSCROLL

The user has clicked the edit control’s vertical scroll bar. Windows sends this message before updating the control.

@ENTABKEY

The user has pressed the TAB key while the control has input focus. Only sent if enabled by the SETCONTROLNOTIFY command.

@ENENTERKEY

The user has pressed the ENTER key while the control has input focus. Only sent if enabled by the SETCONTROLNOTIFY command.