This section explains how to use the advantages of ugBASIC for handling written text. You may want to remind yourself of the visible character set for the given target by running this simple routine:

 FOR c = 32 TO 255
    PRINT CHR$(c);" = CODE ";
    PRINT ASC(CHR$(c))
    WAIT 10 TICKS
 NEXT

The PRINT instruction is one of the most familiar command words in most Basic languages. Items are printed on the screen, 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 printing text only.

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 screen, 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"

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

For example:

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

The 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 screen, the pre-set pen colour is automatically assigned to it. The format of the string returned by 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 0 and 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$ function, PAPER$ returns a character string that automatically sets the background colour when the string is printed on the screen.

For example:

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

For even more flexibility in presenting your text on screen, you can select the way it is combined with other screen data. The WRITING command is used to control how the subsequent text interacts with what is already on the screen, and it can be followed by either one or two values.

The first value selects one of five writing modes:

• REPLACE (0) – new text replaces any existing screen data;
• OR (1) – merge new text with screen data, using logical OR;
• XOR (2) – combine new text with screen data, using XOR;
• AND (3) – Combine new text and screen data, using logical AND;
• IGNORE (4) – ignore all subsequent printing instructions.

A number set as the optional second value selects which parts of the text are to be printed on the screen, as follows:

• NORMAL (3) – Print text and background together;
• PAPER or PAPER ONLY (1) – paper only the background to be drawn on screen;
• PEN or PEN ONLY (2) – ignore paper colour and print text on actual background.

The default value for both of the WRITING parameters is three, giving normal printed output.

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 screen positions are measured in “text coordinates”, which are measured in units of one printed character on screen, with the x-coordinate controlling the horizontal position and the y- coordinate referring to the vertical. So, the top left-hand corner of the screen has coordinates of 0,0 whereas text coordinates of 15,10 refer to a position 15 characters from the left-hand edge of the screen and 10 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 “window”. All coordinate measurements are taken using text coordinates relative to the current window. If you try and print something outside of these limits, an error will be generated. Windows are dealt with in the next Section, but the current screen is automatically treated as a window, so there is no need to “open” one 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$ 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 screen, 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$ function (or the same 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 screen, 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$ 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. This simple command specifies the number of characters that the text cursor will move to the right when the next 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 s 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$.

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$:

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

The CLINE command is used to clear the line currently occupied by the text cursor. If CLINE is followed by a number, then that number of characters get cleared, starting from the current cursor position and leaving the cursor exactly where it is. For example:

  CLS
  LOCATE 0,1
  PRINT "TESTING TESTING TESTING";
  LOCATE 0,3
  PRINT "TESTING TESTING TESTING";
  CMOVE -7,
  CLINE 7
  LOCATE 0,1
  CLINE

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 screen 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.

The HSCROLL command scrolls all text in the current open window horizontally, by a single character position. The following numbers can be used:

• LEFT (1) – scroll current line to the left;
• SCREEN LEFT (2) – scroll entire screen to the left;
• RIGHT (3) – scroll current line to the right;
• SCREEN RIGHT (4) – scroll entire screen to the right.

Similarly to HSCROLL, the values given to the VSCROLL result in different vertical scrolling effects, one character at a time:

• SCREEN DOWN (1) – scroll down text on and below current cursor line;
• SCREEN UP (3) – scroll up text from top of screen to current cursor line only;

Note that blank lines are inserted to fill any gaps left by these scrolling operations.