Texts

Printing on the console

The PRINT instruction is one of the most familiar command words in most BASIC languages. Items are printed on the console (normally all the screen, but can be limited, see below), starting from the current cursor position, and they may include the characters in any group of variables or constants. The PRINT command is also used to display graphics and information on screen, as is demonstrated throughout this manual. This section will deal with just printing texts.

The PRINT statements can occupy their own lines, but if more than one element to be printed is written as a single line of your program, each element must be separated from the next by either a semi-colon character (;) or a comma (,)). An element to be printed can be a string, a variable or a constant, and is placed inside a pair of quotation marks.

A semi-colon (;) is used to print elements immediately after one another, like this:

PRINT "FOLLOW";"ON"

A comma (,) moves the cursor to the next "TAB" position on the console, as follows:

PRINT "NEXT","TAB"

A TAB is an automatic marker that sets up a location for printing, and is often used to lay out columns of figures, or to make indentations in text, and setting TAB positions is explained later. Normally, the cursor is advanced downwards by one line after every PRINT command, but by using the semi-colon or comma, the rule can be changed.

Here is an example:
PRINT "UGBASIC"
PRINT "COMPILER"
PRINT "UG";
PRINT "BAS",
PRINT "IC"

Setting text options

The PEN command sets the colour of the text displayed on the console, when followed by the colour of your choice. The default setting of the pen colour is DEFAULT PEN, and alternative colours may be selected from one of up to PEN COLORS choices, depending on the current video mode.

For example:

FOR index=0 TO 15
   PEN index
   PRINT "PEN NUMBER ";index
NEXT

The PEN/PEN$ function returns a special control sequence that changes the pen colour inside a string. This means that, whenever the string is printed on the console, the pre-set pen colour is automatically assigned to it. The format of the string returned by PEN/PEN$ is not specific for the target.

Here is an example:
p$ = PEN$(WHITE)+"WELL ALL WHITE, "+PEN$(YELLOW)+" I STILL GOT THE YELLOW"
PRINT p$
PEN RED
PRINT "IN THE RED"

To select a background colour on which your text is to be printed, you can use the PAPER command. The command is followed by a colour index number between up to PAPER COLORS, depending on the graphics mode in use, in exactly the same way as PEN. The normal default colour index number is DEFAULT PAPER.

Run the following simple example:

PEN DEFAULT PEN
FOR index = 0 TO PAPER COLORS
   PAPER index
   PRINT "PAPER NUMBER ";index;SPACE(23)
NEXT

Similarly to the PEN/PEN$ function, PAPER/PAPER$ returns a character string that automatically sets the background colour when the string is printed on the console.

For example:

PEN BLACK
b$=PAPER$(RED)+"FLASH RED"+PAPER(BLACK)+"THE INVISIBLE MAN"
PRINT b$

Positioning the text cursor

Characters are always printed at the current position of the text cursor, and the ugBASIC programmer is offered several methods of controlling the cursor in order to make text look more orderly, attractive or eye-catching.

The first command is LOCATE, that moves the text cursor to the coordinates of your choice, and this new location sets the start position for all subsequent text printing until you command otherwise. All console positions are measured in "text coordinates", which are measured in units of one printed character on console, with the x-coordinate controlling the horizontal position and the y- coordinate referring to the vertical. So, the top left-hand corner of the console has coordinates of 0,0 whereas text coordinates of 15,10 refer to a position 16 characters from the left-hand edge of the console and 11 characters from the top.

The range of these coordinates will depend on the size of your character set and the dimensions of the display area allocated, known as a "console". All coordinate measurements are taken using text coordinates relative to the current console. To have a measure of the console size, you can use the COLUMNS and ROWS commands. If you try and print something outside of these limits, the console will scroll in order to have more space.

Console are dealt with in the next section, but the current screen is automatically treated as a console, so there is no need to define the console to test the following examples:

PRINT "0,0": LOCATE 10, : PRINT "STAY ON CURRENT LINE"
LOCATE ,5: PRINT "SIX FROM TOP"
LOCATE 10,10: PRINT "TEN DOWN AND TEN ACROSS"

Whenever you need to move the text cursor back to the top left-hand corner of the screen in a hurry, simply tell it to go HOME and it will automatically be relocated to coordinates 0,0 like this:

CLS: LOCATE 10,10: PRINT "MOVING..."
WAIT 1000 MS: HOME: PRINT "... TO HOME!"

It is also possible to move the text cursor a pre-set distance away from its current position, which can come in useful if you need to show speech bubbles or shunt your text to one side temporarily. The CMOVE command is followed by a pair of variables that represent the width and height of the required offset, and these values are added to the current cursor coordinates. Like LOCATE, either of the coordinates can be omitted, as long as the comma is positioned correctly. An additional technique is to use negative values as well as positive offsets. For example:

CLS : PRINT "ICELAND"
CMOVE 5,5: PRINT "SCOTLAND"
CMOVE ,-3: PRINT "NORWAY"
CMOVE 10,14: PRINT "FRANCE"

Characters can be printed relative to the current cursor position by setting up a string using the CMOVE/CMOVE$ function. The following example prints a string at coordinates 10,10 from the current text cursor:

a=CMOVE$(10,10)
a=a+"UGBASIC"
PRINT a

You may also change the position of the text cursor directly from inside a character string. This is ideal for positioning text once and for all on console, no matter what happens in the program, because the text cursor can be set during the program's initialisation phase. The string that is returned takes the standard format. So whenever this string is printed, the text cursor will be moved to the text coordinates held by x and y. For example:

a="A"+AT$(10,10)+"OF"+AT$(2,4)+"STRING"+AT$(20,20)+"DIGITS"
PRINT a
Imagine a hiscore positioned like this:

score=999
LOCATE 12,10
PRINT "HI SCORE ";score

By using the AT/AT$ function (or the same LOCATE/LOCATE$), the score can be moved by editing a single string, no matter how many times it is used in the program, like this:

hiscore=AT$(12,10)+"HI SCORE"
score=999
PRINT hiscore;score

Programmers often need to position text in the centre of the console, and to save you the effort of calculating the text coordinates in order to achieve this, the CENTRE command takes a string of characters and prints it in the middle of the line currently occupied by the cursor. For example:

LOCATE 0,1
CENTRE "ABOVE"
CMOVE ,3
CENTRE "SUSPICION"

The TAB/TAB$ function returns a special control character called "TAB", which carries the ASCII code of 9. When this character is printed, the text cursor is automatically moved to the next tabulated column setting (tab) to the right. The default setting for this is four characters, which can be changed using SET TAB command. This simple command specifies the number of characters that the text cursor will move to the right when the next TAB/TAB$ is printed.

For example:

CLS : PRINT "HOME"
PRINT TAB$;"AND"
SET TAB 10
PRINT TAB$;"AWAY"

By using the CDOWN command you can force the text cursor down a single line, like this:

CLS : PRINT "OVER" : CDOWN : PRINT "THE MOON"

The effect of summoning up the special control character exactly the same as printing after a CDOWN command. The advantage of this alternative is that several text cursor movements can be combined in a single string, using CDOWN/CDOWN$ keyword.

For example:

c$="GOING DOWN"+CDOWN$
FOR a=0 TO 20
PRINT c$
NEXT

There are also a set of other commands that move the cursor:

CUP : move text cursor one line up
CRIGHT : move text cursor one character right
CLEFT : move text cursor one character left

These commands are self-explanatory, and work in exactly the same way as CDOWN. Their equivalent functions are listed below, and work in the same way as CDOWN/CDOWN$:

CUP/CUP$ : return control character to move text cursor one line up
CRIGHT/CRIGHT$ : return control character to move text cursor one character right
CLEFT/CLEFT$ : return control character to move text cursor one character left

Tracking the text cursor

To track down the exact position of the text cursor, the following pair of functions may be used:

XCURS - return the x-coordinate of the text cursor;
YCURS - return the y-coordinate of the text cursor.

In this way, a variable is created that holds the relevant coordinate of the cursor, in text format, and these two functions may be used independently or together. For example:

LOCATE 5, 10: PRINT XCURS; : PRINT YCURS

The MEMORIZE commands store the current position of the x or y text cursor, so that you can print any text on the console without destroying the original cursor coordinates. These may be reloaded using the REMEMBER commands.

CLS
LOCATE 10,10
PRINT "10,10"
MEMORIZE
LOCATE 12,12
PRINT "12,12"
REMEMBER
PRINT " > REMEMBERED 1"
REMEMBER
PRINT " > REMEMBERED 2"

So you can use the REMEMBER to position the text cursor at the coordinates saved by a previous MEMORIZE command. If MEMORIZE has not been used, the relevant coordinate will automatically be set to zero.

Defining a console

Up to this point, we have spoken generically about console, making it correspond by default to the screen. However, ugBASIC allows you to define a limited area of the screen as the "console".

Once defined, this area will be the only one available to print and position texts, and scrolling will take place only on the console thus defined.

To define a console, use the CONSOLE command.

CONSOLE 1,1 TO 9, 9: REM create a console of 8 lines of 8 columns

Any pair of coordinates can be indicated, as long as the console is within the screen. In other words, the sum between the abscissa and the width of the console must be less than the width of the screen; at the same time, the sum of the ordinate and the height of the console must be less than the height of the screen.

As soon as the function is called, the cursor is placed in the upper left corner. Once defined, all absolute positions (that is, those given with the LOCATE and AT commands) will be referred to the top left corner of the console, while the relative ones will remain so. The size of the console can be retrieved by using the COLUMNS and ROWS instruction. The entire size of the screen can be retrieved by using the SCREEN COLUMNS and SCREEN ROWS.

To disable console, you can use the CONSOLE OFF command. It is equivalent to the command CONSOLE 0, 0 TO SCREEN COLUMNS - 1, SCREEN ROWS - 1.
The ugBASIC language also allows you to define multiple consoles, each characterized by a different constraint. Each console must be defined in a similar way to what has already been described, but then it must be assigned to one of the virtual ones.

To assign a console, use the CONSOLE SAVE command:

CONSOLE SAVE 1

To recover a console, use the CONSOLE RESTORE or CONSOLE USE command (they are synonymous).

CONSOLE USE 1

Note that changing the console causes the cursor position to be saved in the console you leave, and the cursor position to be restored in the console you arrive at. It follows that each console has a cursor independent of the others.

ugBASIC User Manual

Printing on the console

Setting text options

Positioning the text cursor

Erasing text

Tracking the text cursor

Defining a console

Any problem?