ENTRY
A box into which the user can type and edit (using the left/right/up/down arrow, Delete, Insert, and Backspace keys) text, or which can display text for the user to edit.
The user clicks inside of the box, and a cursor appears. (ie, The entry gets the focus). He can then type keys and text will be entered into the box.
For an ENTRY with the MULTI style, multiple lines of text can be typed into the entry, and the ENTER key creates a new line.
Uses
To obtain a line of text from the user, or present a line of text to be edited by the user. It could be used in the same way that a REXX PULL statement would be used, except that a window can contain many entries, so that the user can choose which ones he wants to interact with, and which he doesn't.
Styles
Shortcut | The Shortcut box lets you enter a keyboard shortcut that will automatically select this control whenever the user presses that shortcut. |
An ENTRY must be created with one of the following three styles:
Left | Aligns text flush left. |
Right | Aligns text flush right. |
Center | Centers text. |
An ENTRY may be created with one of the following 2 styles:
Number | Allows the user to enter only numbers. |
Password | Displays all characters as an asterisk (*) as they are typed into the control. Can't be used with the MULTI style. |
An ENTRY can also have the following styles (in addition to one of the above 3):
Lowercase | (LOWER) Converts all characters to lowercase as they are typed into the control. |
Uppercase | (UPPER) Converts all characters to uppercase as they are typed into the control. |
ReadOnly | Prevents the user from entering or editing text in the control. Note: You can set or clear READONLY mode by sending the entry a SETREADONLY message with a WParam arg of 1 to enable read-only or 0 to disable. |
Keep selection | (NOHIDE) Normally, an entry control hides the selection when the control loses the input focus and inverts the selection when the control receives the input focus. Specifying NOHIDE deletes this default action. |
Oem | Text entered in the entry control is converted from the ANSI character set to the OEM character set and then back to ANSI. This ensures proper character conversion when the application calls the AnsiToOem Windows function to convert an ANSI string in the control to OEM characters. This style is most useful for controls that contain filenames. |
Want return | (RETURN) Specifies that a carriage return be inserted when the user presses the ENTER key while entering text into a multiple-line control. Without this style, pressing the ENTER key has the same effect as pressing the default pushbutton. This style has no effect on a single-line control. |
No Sibling | (NOSIBLING) Prevents this control from drawing into any overlapping controls. |
Group | Marks this control as the first of a group of controls in which the user can move from one control to the next with the arrow keys. All subsequent controls (after this first control) belong to the same group up to the next control that has its GROUP flag set. (ie, One group ends where the next begins). |
Tabstop | The user can move to this control using the TAB key. |
Disabled | Control is initially disabled. You can later enable it with a call to GuiSetCtlPlacement. |
Hide | Control is hidden. You can later make it visible with a call to GuiSetCtlPlacement. |
Border | Has a border. |
An ENTRY can also have the following style (in addition to the above):
Multi | Allows multiple lines of text.
Note: You should not set a window's RESULT extra style if you're using a MULTI ENTRY in that window. Otherwise, the ENTRY will not be able to see the ENTER key. Also, if you want the TAB key to enter tab characters into the ENTRY (rather than switching focus to another control), then set the window's TAB extra style. |
If an ENTRY has the MULTI style, then it can also have any of the following styles:
Horz. Scroll | (HSCROLL) Adds a horizontal scroll bar to the ENTRY. The ENTRY manages its own scroll events. |
Vert. Scroll | (VSCROLL) Adds a vertical scroll bar to the ENTRY. The ENTRY manages its own scroll events. |
Auto H scroll | (H_AUTO) 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 0. If H_AUTO is not specified, then the ENTRY automatically wraps words to the beginning of the next line when necessary; a new line is also started if ENTER is pressed. The position of the wordwrap is determined by the window size. If the window size changes, the wordwrap position changes and the text is redisplayed. |
Auto V scroll | (V_AUTO) If this style is specified, then a MULTI entry shows as many lines as possible and scrolls lines vertically up one page when the user presses the ENTER key. If V_AUTO is not specified, the control shows as many lines as possible and beeps if ENTER is pressed when no more lines can be displayed. |
Extra styles
An ENTRY can have the following extra styles:
Quiet | Do not report any events for this control. |
Modal Frame | (MODALFRAME) Has a double border. |
Static Edge | (STATICEDGE) Has a three-dimensional border intended to be used for windows that do not accept user input. |
Client Edge | (CLIENTEDGE) Has a 3D look comprised of a border with a sunken edge. |
Accept files | (FILES) Accepts drag-and-drop files (ie, the DROPFILES event). |
Align text right | (RIGHT) Gives the control generic right-aligned properties (as opposed to the default of left-aligned properties). |
Read right-to-left | (RTLREADING) Displays the window text using right-to-left reading order properties (instead of the default of left-to-right). |
Left Scrollbar | (LEFTBAR) For a MULTI entry, the scroll bar is placed upon the left side of the entry (instead of the right side). |
Transparent | The control is to be transparent. Any controls that are beneath this one are not obscured. |
Events
An ENTRY generates the following events:
Event name When it occurs UPDATE The user is about to alter the text in the entry box. This event occurs before the ENTRY's text is redrawn with the new alteration. INPUT The user may have altered the text in the entry box. Unlike the UPDATE event, this event occurs after the entry's text is updated and redrawn with any alterations. MAXTEXT The current text insertion has exceeded the maximum number of characters for the entry control. The text insertion has been truncated. You can set the allowable maximum number of characters by sending the control a SETLIMITTEXT message. This event also occurs when an entry does not have the H_AUTO style and the number of characters to be inserted would exceed the width of the control.
This event also occurs when an entry does not have the V_AUTO style and the total number of lines resulting from a text insertion would exceed the height of the control.
VSCROLL The user has clicked the vertical scroll bar. This event occurs before the entry is scrolled. HSCROLL The user has clicked the horizontal scroll bar. This event occurs before the entry is scrolled. FOCUS The user has made the control activated, and therefore may be prepared to operate it. UNFOCUS The user has selected another control or some other window, and therefore the entry is deactivated. If the user presses the ENTER key in a single line ENTRY control, then it also causes an "UNFOCUS" event. So you can simply handle this event to catch an ENTER keypress, in lieu of using a PUSH button with the default style. ERROR The entry can't allocate enough memory to meet a specific request.
REXX Variable
An ENTRY must have a REXX variable associated with it. Before opening the window which contains the entry, you must set this variable's value to the text you want placed in the ENTRY box.
If the ENTRY has the MULT style, then the REXX Variable is considered to be a stem name. The total number of lines is stored in the variable name that consists of the stem, and a .0 tail. For example, if you have associated the variable name MyStem with an entry, then the number of lines you want placed in the entry will be in the variable MyStem.0, and the content of those lines will be in the variables MyStem.1 (first line), MyStem.2 (second line), MyStem.3 (third line), etc.
Dynamically add/remove an ENTRY
You can dynamically add an ENTRY to an already open window by calling GuiAddCtl. You must pass a line that describes the control. The format for this line is:
ENTRY X, Y, Width, Height, Styles, ExtraStyles, VariableName, Accelerator, InitialTextX and Y is the position of the top left corner of the control, relative to the window's top left corner.
Width and Height are the size of the control, in pixels.
Styles and ExtraStyles are those listed above, with each style separated by a | character.
VariableName is the variable name to be associated with the control.
Accelerator is the keyboard shortcut that causes the control to be selected for user input.
InitialText is any text you want initially shown in the ENTRY when the control is created. If you prefer, you can omit this, and set the associated variable's value to the desired text. If you choose to use the InitialText, then you should make sure the associated variable is not set to some value (ie, it is DROP'ed). You can use the two characters \t to represent a TAB character. You can also include multiple lines by using the characters \n to mark the end of a line (only if the MULTI style is used). If you want to put a \ character in the text, then you must double it up as \\.
Note: There is a limit of 255 characters for the InitialText field. If you need to set a longer string, then instead initialize the variable associated with the control.
For example, here we add an ENTRY at an X Y position of 10, 10, with a width and height of 100 and 20, with the style READONLY, extra styles of CLIENTEDGE and QUIET, and a REXX Variable name of MyEntry. We set its contents to the string Here is some text (by initializing its associated variable).
MyEntry = "Here is some text" error = GuiAddCtl("ENTRY 10,10,100,20, READONLY, CLIENTEDGE|QUIET, MyEntry")Note: If you wish the ENTRY to contain no text, then either DROP its associated variable, or set the variable to an empty string. For a MULTI entry, you can also set its line count to 0.
You can dynamically remove an ENTRY by calling GuiRemoveCtl. Here we remove the above control:
error = GuiRemoveCtl("MyEntry")
Selecting text
You can dynamically select an excerpt of text in an ENTRY by calling GuiSendMsg to send the entry a SETSEL message. For the third arg, pass the character number where the selection begins (where 0 is the first character). For the fourth arg, pass the character number where the selection ends.
Note: The cursor position will be automatically set to the end of the selected text.
To select all text, then pass 0 and -1:
error = GuiSendMsg("MyEntry", "SETSEL", 0, -1)To remove any selection (ie, unselect the text), then send the entry a SETSEL message with -1 and 0:
error = GuiSendMsg("MyEntry", "SETSEL", -1, 0)
Setting the cursor position
To set the cursor to a particular position, call GuiSendMsg to send the entry a SETSEL message. The third arg is the character number where the cursor should be set (where 0 is the first character), and pass the same number for the fourth arg.
Note that this unselects any text as well.
Change the contents of an ENTRY.
You can dynamically change an ENTRY's contents by calling GuiAddCtlText, GuiSetCtlValue, or GuiRemoveCtlText.
To empty out the previous contents, and set the ENTRY to some new text, you first set its associated REXX variable to the desired new text, and then call GuiSetCtlValue, passing that variable name. For example, here we set the above entry to the string New text:
MyEntry = "New text" error = GuiSetCtlValue("MyEntry")If the entry has the MULTI style, then you need to set the line count variable to the desired number of lines, and then set the variables for those lines. Assuming we created MyEntry with the MULTI style, here's how we would initialize it to contain two lines:
MyEntry.0 = 2 MyEntry.1 = "This is line 1." MyEntry.2 = "This is line 2." error = GuiSetCtlValue("MyEntry")To insert some text at the current cursor position (without overwriting any existing text), call GuiAddCtlText and pass the text to insert:
error = GuiAddCtlText("MyEntry", "This is inserted text")Note: If the entry has the MULTI style, then you can include line breaks in your text by using 'ODOA'X. For example, here we insert two lines at the current cursor position:
error = GuiAddCtlText("MyEntry", 'ODOA'X || "This is line 1." || 'ODOA'X || "This is line 2." || 'ODOA'X)To insert some text over any currently selected text (ie, replace the selected text with new text), call GuiRemoveCtlText and pass the new text:
error = GuiRemoveCtlText("MyEntry", "This text overwrites the current selection")To insert a blank line at the current cursor position (ie, break the current line in two), call GuiAddCtlText and pass an empty string:
error = GuiAddCtlText("MyEntry", "")Note: The above works only on an entry with the MULTI style.
To delete the currently selected text (without inserting any new text), call GuiRemoveCtlText and pass an empty string:
error = GuiRemoveCtlText("MyEntry", "")Note: The deleted text is not copied to the Windows clipboard. See below if you desire that behavior.
Copy/cut text to the clipboard
You can copy the selected text to the Windows clipboard by calling GuiSendMsg to send the entry a COPY message.
error = GuiSendMsg("MyEntry", "COPY")
Alternately, you can cut the selected text to the Windows clipboard by calling GuiRemoveCtlText and omitting the second arg. (The selected text is deleted after it is copied to the clipboard).
error = GuiRemoveCtlText("MyEntry")
Paste text from the clipboard
To insert the contents of the Windows clipboard over the currently selected text in the entry, call GuiAddCtlText and omit the second argument:error = GuiAddCtlText("MyEntry")Note: If you wish to paste the clipboard contents without overwriting any existing text in the ENTRY, then you should first send the ENTRY a SETSEL message to unselect any selected text.
Retrieve an ENTRY's contents
You can retrieve an ENTRY's contents by calling GuiGetCtlValue. This will set its associated REXX variable to the control's current contents. For example, here we query the above control's contents:
error = GuiGetCtlValue("MyEntry") IF error == "" THEN SAY MyEntryNote: If the entry has the MULTI style, then a series of compound variables are set. For example, assume the above entry was created with the MULTI style:
error = GuiGetCtlValue("MyEntry") IF error == "" THEN DO SAY "There are" MyEntry.0 "lines:" DO i = 1 TO MyEntry.0 SAY "Line" i || ":" MyEntry.i END ENDFor a MULTI control, you can query how many lines the user has entered by sending a GETLINECOUNT message. This sets the variable GuiSignal to the count of lines. You can then retrieve an individual line by calling GuiGetCtlValue and passing a second arg which is the desired line number (where 1 is the first line). For example, here we fetch the third line:
error = GuiGetCtlValue("MyEntry", 3)This sets the variable MyEntry to that particular line's contents.
Limit entered text
You can limit how many characters the user is allowed to type into an ENTRY's box. You do this by sending a LIMITTEXT message. For the third arg, pass the desired number to characters to limit. For example, here we limit the user to entering 16 characters at most:
error = GuiSendMsg("MyEntry", "LIMITTEXT", 16)