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 of lines later on - if this tag is not given, the edline only has one line... The parameter is the number of lines, starting at 1 (i.e. if you set 2, you have two lines, line 0 and line 1).

If you have an edline with several lines, then there is a current line. This is either line 1, if nothing has been done with the edline, or the last line that was set/gotten or edited by the user (this makes it easy to get/set the last line edited by the user).

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, starting at 0 (i.e. to set line 0, use 0). 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.

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 line 0. 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. This tag does not change the current line.
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 (starting at 0). 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. 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 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 as the next one, which can be reached by pressing TAB. 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_PREV')
This tag is the other side of the previous one and allows you to set the edline which should be edited as the previous one, which can be reached by pressing SHIFT TAB. 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_UP')
Some navigation is possible with edlines. Several edline objects can be linked together so that you can edit several items and keep your hands at the keyboard. This tag allows you to set the edline which should be edited as the above one, which can be reached by pressing the UP cursor key. 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_DOWN')
Same as the previous tag, but this is the edline below this one.
PW('EDLINE_ACTION_TEST')
. There are a certain number of routines which can be used by the edline object to check whether the input given by the user is valid. Whilst in 'C' it would be possible to write one's own routine to do that, in SBasic you can use the following routines:
PW('EDLINE_ACTION_TEST_NATURAL')
. This makes sure that only natural numbers can be input.
PW('EDLINE_ACTION_TEST_INTEGER')
. This makes sure that only integers can be input (same as natural, but including sign).
PW('EDLINE_ACTION_TEST_FLOAT')
). As you may have guessed, this is for floating point numbers.
The way to pass these tags is to pass, first, the tag PW('EDLINE_ACTION_TEST') and then any of the above three tags.
PW_EDLINE_PRINT_ESCAPE
This tag allows you to specify whether any escape code in the string has to be displayed in full (TRUE) or whether they should be displayed as the character they represent (FALSE). On parameter is needed, the new status. The default is FALSE.
The query tags There are no query tags for this object.

PROGS, Professional & Graphical Software
last edited 1997 Jan 17 (wl)