# Cls()

Clears the screen of all text within the current bounds and fills it with the prevailing background colour, see #HMI SetColours(). Locates the text cursor to the top lefthand corner based on the current font, see #HMI SetFont(). Has no effect on buttons or any image.

Function prototype

# Cls()

(This instruction has no parameters).

Description

You can typically use #HMI Print() to draw over existing text.  The text that was there previously will be erased by each new character.  However, if the length of text differs, then some old characters will remain.  In this case, first call Cls() erase text before printing new text in its place.

If you want to erase a specific region rather than the whole screen, call #HMI SetBounds() first.

Examples

This example follows HMI best practice in that it sets all required items before calling Cls():

   #HMI  SetFont( "large.fon" )           ;first ensure the correct font is selected
   #HMI  SetBounds( x:3, y:3, w:10, h:1 ) ;now set the bounds using the large.fon dimensions
   #HMI  SetColours( f:HUEkLightGrey, b:HUEkTransparent ) ; set the colours (a transparent background will allow the image to show)
   #HMI  Cls()                            ;erase the bounded area, move the cursor to top left of the bounds
   #HMI  Print( "\CHello world" )         ;print text centred within the bounded area
   #HMI  SetBounds()                      ;clear the bounds (back to whole screen)

A few notes about this code:

• As we are using character coordinates in the call to SetBounds(), we must ensure the font is set FIRST.
• The colours have been equated as follows:
  HUEkLightGrey #EQU 'FFC0C0C0
HUEkTransparent #EQU '00000000
• A transparent background will allow either the background image or background colour to be used to erase the text.
• It's good practice to clear the bounds as soon as you're finihsed with it, hence the #HMI SetBounds() at the end.  Doing this will save troubleshooting when you try to figure why text isn't being displayed