The Edline and Direct Edline types
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:
- The normal edline has to be "indicated" (i.e. hit/done) first to start
editing the string. While the string is being edited, the pointer cannot be
used in the window.
- There is also a direct edline. This variant uses the keypress catching
mechanism. To make sure that you can move the cursor, a direct edline will
make sure that PW('CURSOR_SEPARATE') is TRUE. A direct
edline doesn't have to be indicated to start typing, but it has to be
selected in some way as current catch object. If there is no catch object
when a direct edline is created, then that direct edline will designate
itself as such.
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 :
- PW('EDLINE_ACTION_DO') does not exist for a direct edline (it is not
indicated).
- For PW('TYPE_DIRECT_EDLINE') all parameters to PW('EDLINE_EDLINE_xxx')
have to be DIRECT_EDLINE objects !
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)