The Edline and Direct Edline types

Purpose

The edline object is designed to allow the user to edit a line of text (a string). The maximum length of the string can be set when you create the edline (or a default maximum length will be used). As an edline can not reasonably determine its width, that also can be given (or a default will be used).

Edlines are available in two variants:

An edline can have an action which has to be executed when the user stops editing (presses <enter>). Also the programmer can set some objects which can be navigated to (using <tab>, <shift tab>, <up>, <down> or <enter>). In the case of a normal edline, the other objects to navigate to also have to be edlines. For direct edlines, any object which can be a catch object will suffice.

Edline objects can cope with the edited text being larger than the object can show (thanks to PROforma). They will also always try to assure that the cursor is visible with its surrounding characters. The cursor will therefore never hit the right end of the object, and the left end will only be touched when the cursor is at the start of the string.

Although you can choose between normal and direct edlines, it is possible for the user to configure his/her setup to use a direct edline always. Consequently, as a programmer you should make sure that it is always possible to navigate to all the other edline objects in the window without using the mouse.

The Type Words

When creating these types of object, the type parameters are:

PW('TYPE_EDLINE') for a normal edline, and

PW('TYPE_DIRECT_EDLINE') for a direct edline.

The tags

Here are the tags for these objects. As usual, change tags are also used when creating the object, but query tags are only used for queries. There are also two tags that can only be used during creation.

All the tags which are valid for edline objects, can als be applied to direct edline (dedline) objects. With the following differences :

The creation tag: use only during creation

There is one tag that can be used only when creating the object, not when changing it:

PW('EDLINE_MAXLENGTH')
Set the maximum length of the string which can be edited in an edline object. The parameter is a number.
PW('EDLINE_VISIBLE_LINES')
An edline can have several lines. They are independent of each other (i.e. there is no word warp) and you can get to/from each line with the up/down cursor keys. This tag determines how many lines there are in the edline. They are normally all visible in the window. Beware, you cannot change the number if lines later on - if this tag is not given, the edline only has one line... The parameter is the number of lines.
The change (and creation) tags: use during creation and/or change
PW('EDLINE_SET_LINE')
Set the string which should be presented for editing in any line of the edline object. The parameters are the string to set and the line to set it to. If the string is longer than the maximum length, then as much as possible will be used. It is a normal string and can be a direct string since it is copied to a safe place.
PW('EDLINE_SET')
Set the string which should be presented for editing in the edline object, in the current line. For a one-line object, this is always the only line that exists, else it is the line last edited by the user, or line 1. If the string is longer than the maximum length, then as much as possible will be used. It is a normal string and can be a direct string since it is copied to a safe place.
PW('EDLINE_SET_ARRAY')
This uses an array to fill in the strings for the edline, starting at the first line. There are three parameters: the number of lines to fill in (which should be the number of elements in the array), the maximum length of each string in the array (don't forget how this is calculated in Basic: second dimension of the two-dimensional string array + 2 for the length word + 1 if the second dimension of the array was uneven), and the array itself. The type makes sure that no overflow can occur if there are more lines in the array than in the edline, or if the length of each line in the edline is less than that of each element in the array.
PW('EDLINE_GET_LINE')
Get the string which is contained in a line of the edline. Three parameters are needed, the length of the fixstring, the fixstring itself and the line which must be obtained. If the text in the object is larger than the length of the fixstring, the fixstring will be filled as much as possible. The string returned should then be treated with MKLEN or MKLEN0 to obtain a normal SBasic string.
PW('EDLINE_GET')
Get the string which is contained in the current line of the edline. For a one-line object, the current line is always the only line that exists, else it is the line last edited by the user, or the first line if no editing has been done yet. This way, you can easily get the last line edited by a user in case of a multi-line edline. Two parameters are needed, the length of the fixstring, and the fixstring itself. If the text in the object is larger than the length of the fixstring, the fixstring will be filled as much as possible. The string returned should then be treated with MKLEN or MKLEN0 to obtain a normal SBasic string.
PW('EDLINE_SET_ARRAY')
This fills in an array with the lines from the edline, but must not be used from Basic (it doesn't fill in the length word of the elements, and MKLEN doesn't work on Basic array elements if their initial length was 0). To fill in an array with the lines, you should use the following code:


    maxlen%=DIMN(array$,2)        
         rem max length of one element
    number_of_element%=DIMN(array$,1)
    string$=FILL$(' ',maxlen%)    
         rem make sure there is that much space
    FOR lp%=0 to number_of_elements%
         PWCHANGE edline,string$,maxlen%
         MKLEN string$
         array$(lp%)=string$
    END FOR lp%

PW('EDLINE_WIDTH')
Set the size of the edline object, one parameter, a PROforma number.
PW('EDLINE_WIDTH_PIX')
Set the size of the edline object, one parameter, a number in pixels.
PW('EDLINE_WIDTH_FS')
Set the size of the edline object, one parameter, a PROFORMA number. The window size is calculated as the parameter times the fontsize used for the text in the object. You should remember, though, that since ProWesS uses proportional fonts, this does NOT indicate the exact number of charcaters that will fit inside the window.
PW('EDLINE_KEYPRESS')
Attach a keypress to the edline. The pressing of the key will be equivalent to a HIT on the item, so the item can be edited. The parameter is the primary keypress, which is of type CODE(character$).
PW('EDLINE_ACTIVATE')
This allows you to activate the edline at any time. Normally, edlines (apart from direct edlines) are only activated (i.e. the user can edit the text in them) when they are indicated (hit/done). With this, you can activate the edline whenever you want, notably in reponse to user input in another part of the window.

This MUST not be used during creation, only when PWchanging the edline. IT IS ALSO IMPORTANT THAT, IF YOU HAVE AN EDLINE THAT IS ACTIVATED IN THIS MANNER, YOU DO NOT HAVE AN "ACTION_AFTER" ROUTINE (SEE BELOW) FOR THIS EDLINE. Once the user finished editing the text, your program will continue after the line doing the PWchange that activated the edline, so you can get at the text immediately, anyway. It should be alright to include an action_after routine for such an edline in SBasic, but in a compiled program you will have the problem that QLiberator complains that it doesn't have enough stack left, even if you increase the stack to a very high number. You have been warned.

PW('EDLINE_ACTION_AFTER')
Set the routine which should be called when the user finished editing the edline (when the user pressed ENTER), as a post processing routine. The parameter should be HIT_ROUTINE. This can be used to modify some part of the system according to the data entered.
PW('EDLINE_ACTION_DO')
Set the routine which should be called when the user indicates the edline with a PW('EVENT_DO'). If such a routine exists, then this routine will be called, and the item in the edline cannot be edited (!!!!!!). If there is no ACTION_DO routine, then a DO is treated the same as a HIT. The parameter should be DO_ROUTINE. This can be used to modify some part of the system according to the data entered.
PW('EDLINE_EDLINE_AFTER')
Some navigation is possible with edlines. Several edline objects can be linked together so that you can edit several items and keep your hands on the keyboard. This tag allows you to set the edline which should be edited once the user finished with this one (when pressing ENTER). The parameter is an object already created and has to be an edline object ! Of course, the ACTION_AFTER routine is called before moving to the next object.
PW('EDLINE_EDLINE_NEXT')
Some navigation is pos