Q(uick)BASIC Statement: CLS

Quick View

CLS

A device I/O statement that clears the display screen

Worth knowing

Useful and cross-version information about the programming environments of QBasic and QuickBasic.

Syntax
  • CLS [{0 | 1 | 2}]
Description/Parameter(s)
CLS Clears either the text or graphics viewport. If a graphics viewport has been set (using VIEW), clears only the graphics viewport. Otherwise, clears the text viewport or entire screen.
CLS 0 Clears the screen of all text and graphics.
CLS 1 Clears the graphics viewport or the entire screen if no graphics viewport has been set.
CLS 2 Clears the text viewport.
Syntax
  • CLS [{0|1|2}]
Description/Parameter(s)
CLS 0 Clears the screen of all text and graphics.
CLS 1 Clears only the graphics viewport if a VIEW statement has been executed. Otherwise, CLS 1 clears the entire screen.
CLS 2 Clears only the text viewport, leaving the bottom screen line (line 25, 30, 43, or 60 depending on the screen mode) unchanged.
CLS Clears either the graphics viewport or the text viewport. If the graphics viewport is active, then CLS with no argument clears only the viewport. If the graphics viewport is inactive, then CLS clears the text viewport and refreshes the function key display line (the bottom screen line).

The CLS statement also returns the cursor to the home position in the top left corner of the screen.

Example

The following program draws random circles in a graphics viewport and prints in a text viewport. The graphics viewport is cleared after 30 circles have been drawn. The program clears the text viewport after printing to it 45 times.

RANDOMIZE TIMER SCREEN 1 ' Set up a graphics viewport with a border. VIEW (5,5)-(100,80),3,1 ' Set up a text viewport. VIEW PRINT 12 TO 24 ' Print a message on the screen outside the text viewport. LOCATE 25,1 : PRINT "Press any key to stop." Count=0 DO ' Draw a circle with a random radius. CIRCLE (50,40),INT((35-4)*RND+5),(Count MOD 4) ' Clear the graphics viewport every 30 times. IF (Count MOD 30)=0 THEN CLS 1 PRINT "Hello. "; ' Clear the text viewport every 45 times. IF (Count MOD 45)=0 THEN CLS 2 Count=Count+1 LOOP UNTIL INKEY$ <> ""
Syntax
  • CLS [{0 | 1 | 2}]
Description/Parameter(s)
0 Clears the screen of all text and graphics, except the bottom line of text; returns the cursor to the home position.
1 Clears the graphics viewport; may or may not clear the bottom line of text or return the cursor to home.
2 Clears the text viewport; leaves the bottom screen line unchanged and returns the cursor to home.
If no argument is used:
  • If the screen mode is 0, then clears the text viewport, except the bottom line of text, and returns the cursor to home.
  • In any other screen mode, the graphics viewport will be cleared; may or may not clear the bottom line of text or return the cursor to home.

Usage Notes

  • The CLS statement can be used to:
    • Clear the entire screen (except the bottom line of text), the text viewport, or the graphics viewport
    • Regenerate the bottom line of text
    • Return the cursor to the home position (the upper-left corner of the screen).
  • The behavior of a particular CLS statement depends on:
    • The CLS statement argument: 0, 1, 2, or none.
    • The current screen mode.
    • Whether or not a VIEW statement has been executed which has changed the graphics viewport from the default of the entire screen.
    • Whether or not a VIEW PRINT statement has been executed which established a user-defined text viewport.
    • Whether or not a KEY ON statement has been executed, which established the bottom text line as a list of function-key assignments. The bottom line on the screen may be 25, 30, 43, or 60, depending upon the current screen mode.
  • The following fundamentals about the graphics and text viewports determine how the CLS statement works:
    • SCREEN mode 0 has only a text viewport. All other screen modes have both a text and graphics viewport.
    • The default graphics viewport is the entire screen.
    • The default text viewport is the entire screen, except for the bottom line of text.
    • After a user-defined graphics viewport (or "clipping region") has been established by execution of a VIEW statement, it is reset to the default by execution of any of these statements:
      • VIEW without arguments;
      • CLEAR;
      • any SCREEN statement that changes the screen resolution.
    • After a user-defined text viewport has been established by execution of a VIEW PRINT statement, it is reset to the default by execution of any of these statements:
      • VIEW PRINT without arguments,
      • any text-oriented statement, such as WIDTH, that changes the number of text columns or text lines on the screen.
    • If the KEY ON statement has been executed, the CLS statement regenerates the bottom screen line as the function key assignment list or as a line of blank characters.
  • Following is a table that summarizes how the CLS statement works:
Statement Condition Operations Performed
CLS 0 Any screen mode, any combination of user-defined viewports
  1. Clear entire screen of all text and graphics, except bottom text line.
  2. Clear graphics viewport.
  3. Regenerate bottom text line.
  4. Return the cursor to home.
CLS 1 Graphics screen mode with no user-defined graphics viewport
  1. Clear default graphics viewport.
  2. Do not clear text viewport.
  3. Regenerate bottom text line.
  4. Return the cursor to home.
CLS 1 Graphics screen mode with user-defined graphics viewport
  1. Clear user-defined graphics viewport.
  2. Do not clear text viewport
  3. Do not regenerate bottom text line.
  4. Do not return the cursor to home.
CLS 1 In SCREEN mode 0 (text mode)
  • Has no effect.
CLS 2 Any screen mode
  1. Clear the text viewport.
  2. Do not clear the graphics viewport.
  3. Do not regenerate the bottom text line.
Note: The bottom line of text will not be cleared even if it is included in the user-defined text viewport.
CLS Graphics-screen mode with no user-defined
  1. Clear default graphics viewport.
  2. Regenerate bottom text line.
  3. Return the cursor to home.
CLS Graphics-screen mode with user-defined graphics viewport
  1. Clear user-defined graphics viewport.
  2. Do not regenerate bottom text line.
  3. Do not return the cursor to home.
CLS In SCREEN mode 0 (text mode)
  1. Clear text viewport.
  2. Regenerate bottom text line.
  3. Return the cursor to home.
Example

This example uses the VIEW PRINT statement to set up graphics and text viewports. The CLS statement is used to clear the graphics viewport after 30 circles have been drawn and the text viewport after "Hello" has been printed 45 times.

RANDOMIZE TIMER SCREEN 1 'Set up a graphics viewport with a border. VIEW (5, 5)-(100, 80), 3, 1 'Set up a text viewport. VIEW PRINT 12 TO 24 'Print a message on the screen outside the text viewport. LOCATE 25, 1: PRINT "Press any key to stop." Count = 0 DO 'Draw a circle with a random radius. CIRCLE (50, 40), INT((35 - 4) * RND + 5), (Count MOD 4) 'Clear the graphics viewport every 30 times. IF (Count MOD 30) = 0 THEN CLS 1 PRINT "Hello. "; 'Clear the text viewport every 45 times. IF (Count MOD 45) = 0 THEN CLS 2 Count = Count + 1 LOOP UNTIL INKEY$ <> ""