CLS: Difference between revisions
Jump to navigation
Jump to search
Navigation:
Main Page with Articles and Tutorials
Keyword Reference - Alphabetical
Keyword Reference - By usage
Report a broken link
No edit summary |
No edit summary |
||
| (7 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
The | The '''CLS''' statement clears the [[_DEST|current write page]] or the designated image. | ||
{{PageSyntax}} | {{PageSyntax}} | ||
: [[CLS]] [{{Parameter|method%}}] [, {{Parameter|bgColor&}}] | : [[CLS]] [{{Parameter|method%}}] [, {{Parameter|bgColor&}}] [, {{Parameter|imageHandle&}}] | ||
{{ | {{PageParameters}} | ||
* {{Parameter|method%}} specifies which parts of the page to clear, and can have one of the following values: | * {{Parameter|method%}} specifies which parts of the page to clear, and can have one of the following values: | ||
** CLS - clears the active graphics or text viewport or the entire text screen and refreshes bottom function [[KEY LIST|KEY ON]] line. | ** '''CLS''' - clears the active graphics or text viewport or the entire text screen and refreshes bottom function [[KEY LIST|KEY ON]] line. | ||
** CLS 0 - Clears the entire page of text and graphics. Print cursor is moved to row 1 at column 1. | ** '''CLS''' 0 - Clears the entire page of text and graphics. Print cursor is moved to row 1 at column 1. | ||
** CLS 1 - Clears only the graphics view port. Has no effect for text mode. | ** '''CLS''' 1 - Clears only the graphics view port. Has no effect for text mode. | ||
** CLS 2 - Clears only the text view port. The print cursor is moved to the top row of the text view port at column 1. | ** '''CLS''' 2 - Clears only the text view port. The print cursor is moved to the top row of the text view port at column 1. | ||
* The {{Parameter|bgColor&}} specifies the color attribute or palette index to use when clearing the screen in '''QB64'''. | * The {{Parameter|bgColor&}} specifies the color attribute or palette index to use when clearing the screen in '''QB64'''. | ||
* {{Parameter|imageHandle&}} specifies an image handle to clear. If it is not specified, then '''CLS''' clears the [[_DEST|current write page]]. | |||
{{PageDescription}} | {{PageDescription}} | ||
* In legacy [[SCREEN]] modes {{Parameter|bgColor&}} specifies the color attribute of the background. | * In legacy [[SCREEN]] modes {{Parameter|bgColor&}} specifies the color attribute of the background. | ||
* For 32-bit graphics mode, {{Parameter|bgColor&}} specifies the [[ | * For 32-bit graphics mode, {{Parameter|bgColor&}} specifies the [[_RGB32]] or [[_RGBA32]] color to use. | ||
* '''32-bit screen surface backgrounds (black) have zero [[_ALPHA]] so that they are transparent when placed over other surfaces.''' | * '''32-bit screen surface backgrounds (black) have zero [[_ALPHA]] so that they are transparent when placed over other surfaces.''' | ||
** Use | ** Use '''CLS''' or [[_DONTBLEND]] to make a new surface background [[_ALPHA]] 255 or opaque. | ||
* If not specified, {{Parameter|bgColor&}} is assumed to be the current background color. 32-bit backgrounds will change to opaque. | * If not specified, {{Parameter|bgColor&}} is assumed to be the current background color. 32-bit backgrounds will change to opaque. | ||
* If {{Parameter|bgColor&}} is not a valid attribute, an [[ERROR Codes|illegal function call]] error will occur. | * If {{Parameter|bgColor&}} is not a valid attribute, an [[ERROR Codes|illegal function call]] error will occur. | ||
* Use [[_PRINTMODE]] to allow the background colors to be visible through the text or the text background. | * Use [[_PRINTMODE]] to allow the background colors to be visible through the text or the text background. | ||
{{PageAvailability}} | |||
<!-- QB64 = a version or none, QBPE = a version or all, Platforms = yes or no --> | |||
<gallery widths="48px" heights="48px" mode="nolines"> | |||
File:Qb64.png|'''v0.610''' | |||
File:Qbpe.png|'''all''' | |||
File:Apix.png | |||
File:Win.png|'''yes''' | |||
File:Lnx.png|'''yes''' | |||
File:Osx.png|'''yes''' | |||
</gallery> | |||
<!-- additional availability notes go below here --> | |||
* In '''QB64-PE v3.10.0''' support for clearing images was added. | |||
{{PageExamples}} | {{PageExamples}} | ||
''Example 1:'' Printing black text on a white background in QB64. | ''Example 1:'' Printing black text on a white background in QB64. | ||
{{CodeStart}} | {{CodeStart}} | ||
{{Cl|SCREEN}} 12 | {{Cl|SCREEN}} 12 | ||
{{Cl|CLS}} , 15 | {{Cl|CLS}} , 15 | ||
| Line 38: | Line 53: | ||
''Example 2:'' You don't need to do anything special to use a .PNG image with alpha/transparency. Here's a simple example: | ''Example 2:'' You don't need to do anything special to use a .PNG image with alpha/transparency. Here's a simple example: | ||
{{CodeStart}} | {{CodeStart}} | ||
{{Cl|SCREEN}} {{Cl|_NEWIMAGE}}(640, 480, 32) | {{Cl|SCREEN}} {{Cl|_NEWIMAGE}}(640, 480, 32) | ||
{{Cl|CLS}} , {{Cl|_RGB}}(0, 255, 0) | {{Cl|CLS}} , {{Cl|_RGB}}(0, 255, 0) | ||
i = {{Cl|_LOADIMAGE}}('''"qb64_trans.png"''') 'see note below examples to get the image | i = {{Cl|_LOADIMAGE}}('''"qb64_trans.png"''') 'see note below examples to get the image | ||
{{Cl|_PUTIMAGE}} (0, 0), i 'places image at upper left corner of window w/o stretching it | {{Cl|_PUTIMAGE}} (0, 0), i 'places image at upper left corner of window w/o stretching it | ||
{{CodeEnd}} | {{CodeEnd}} | ||
Latest revision as of 11:42, 13 December 2023
The CLS statement clears the current write page or the designated image.
Syntax
- CLS [method%] [, bgColor&] [, imageHandle&]
Parameters
- method% specifies which parts of the page to clear, and can have one of the following values:
- CLS - clears the active graphics or text viewport or the entire text screen and refreshes bottom function KEY ON line.
- CLS 0 - Clears the entire page of text and graphics. Print cursor is moved to row 1 at column 1.
- CLS 1 - Clears only the graphics view port. Has no effect for text mode.
- CLS 2 - Clears only the text view port. The print cursor is moved to the top row of the text view port at column 1.
- The bgColor& specifies the color attribute or palette index to use when clearing the screen in QB64.
- imageHandle& specifies an image handle to clear. If it is not specified, then CLS clears the current write page.
Description
- In legacy SCREEN modes bgColor& specifies the color attribute of the background.
- For 32-bit graphics mode, bgColor& specifies the _RGB32 or _RGBA32 color to use.
- 32-bit screen surface backgrounds (black) have zero _ALPHA so that they are transparent when placed over other surfaces.
- Use CLS or _DONTBLEND to make a new surface background _ALPHA 255 or opaque.
- If not specified, bgColor& is assumed to be the current background color. 32-bit backgrounds will change to opaque.
- If bgColor& is not a valid attribute, an illegal function call error will occur.
- Use _PRINTMODE to allow the background colors to be visible through the text or the text background.
Availability
v0.610
all
yes
yes
yes
- In QB64-PE v3.10.0 support for clearing images was added.
Examples
Example 1: Printing black text on a white background in QB64.
SCREEN 12 CLS , 15 _PRINTMODE _KEEPBACKGROUND 'keeps the text background visible COLOR 0: PRINT "This is black text on a white background!" K$ = INPUT$(1 |
- Explanation: _PRINTMODE can be used with PRINT or _PRINTSTRING to make the text or the text background transparent.
Example 2: You don't need to do anything special to use a .PNG image with alpha/transparency. Here's a simple example:
SCREEN _NEWIMAGE(640, 480, 32) CLS , _RGB(0, 255, 0) i = _LOADIMAGE("qb64_trans.png") 'see note below examples to get the image _PUTIMAGE (0, 0), i 'places image at upper left corner of window w/o stretching it |
- Explanation: When QB64 loads a .PNG file containing a transparent color, that color will be properly treated as transparent when _PUTIMAGE is used to put it onto another image. You can use a .PNG file containing transparency information in a 256-color screen mode in QB64. CLS sets the _CLEARCOLOR setting using _RGB.
See also