====== ugBASIC User Manual ======

===== TEXTS =====

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

==== Printing on the screen ====

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"

==== Setting text options ====

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$

==== Changing the text mode ====

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.

==== 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 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

==== Erasing text ====

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
  
==== 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 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.
==== Advanced text commands ====

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.