Screen#

Introduction#

The screen class is derived from the brain base class, which controls the IQ (1st gen) Brain’s screen, allowing your robot to show text, numbers, and graphics.

The IQ (1st gen) Brain screen supports up to 5 rows and 21 columns of text.

The VEX IQ (1st gen) Brain with a numbered grid overlay (columns 1–21 and rows 1–5). Red overlay lines highlight the grid structure, with arrows labeling Column 1, Column 21, Row 1, Row 2, and Row 5. The first row displays numbers 1 through 21 across the top.

Access#

The screen class can be accessed by:

Brain.Screen

Notes#

The screen object is provided by the Brain. It is not constructed directly.
Projects use a single global Brain object, so screen functions are called using Brain.Screen.

Example#

/* This constructor is required when using VS Code.
A Brain is generated automatically at the start of
VEXcode projects. */

// Create the Brain
brain Brain = brain();

// Print text to the Brain screen
Brain.Screen.print("Hello!");

Member Functions#

The screen class includes the following member functions:

print — Prints formatted text, numbers, or Boolean values to the Brain screen.
setCursor — Sets the text cursor to a specified row and column.
newLine — Clears the remainder of the current line and moves the cursor to the next line.
clearLine — Clears the remainder of the current line or clears a specified line.
row — Returns the current cursor row.
column — Returns the current cursor column.
getStringHeight — Returns the height of a string in pixels using the current font.
getStringWidth — Returns the width of a string in pixels using the current font.
printAt — Prints formatted text at an x, y pixel location (optionally opaque).
clearScreen — Clears the entire screen (optionally to a specified color).
setFont — Sets the font used for printing on the screen.
setPenWidth — Sets the width of lines and shape outlines.
setPenColor — Sets the color used for drawing and printed text.
setFillColor — Sets the fill color used for shapes and the background of printed text.
setOrigin — Sets the origin used for screen coordinates.
setClipRegion — Restricts screen output to a rectangular region.
drawPixel — Draws a single pixel at an x, y location.
drawLine — Draws a line between two points.
drawRectangle — Draws a rectangle at an x, y location with a specified size.
drawCircle — Draws a circle at an x, y location with a specified radius.
render — Enables double buffering or renders the back buffer to the screen.

Before calling any screen member functions, a brain instance must be created, as shown below:

// Create the Brain
brain Brain = brain();

print#

Displays text, numbers, or Boolean values on the IQ (1st gen) Brain screen.

Available Functions

1 — Prints formatted text using string literals or read-only C-style strings.
void print(
    const char* format,
    ... );

2 — Prints formatted text using modifiable character arrays.
void print(
    char* format,
    ... );

Parameters

Parameter	Type	Description
`format`	`const char*`	A format string provided as a string literal or read-only C-style string (for example, `“Score: %d”`).
`format`	`char*`	A format string provided as a modifiable character array.
`…`		One or more additional values that are inserted into the format string, separated by commas.

Return Values

This function does not return a value.

Notes

Output begins at the current cursor position on the screen.
Printed text uses the current screen font.
Printed text uses the current pen color.
Text printed with print is always printed with a background, and the background color is determined by the current fill color.
When using a format string, the number and types of values passed must match the format specifiers in the string.

Examples

// Display a message at the starting cursor
Brain.Screen.print("Hello, Robot!");

setCursor#

Sets the cursor position on the IQ (1st gen) Brain screen to the specified row and column.

Available Functions

void setCursor(
  int32_t row, 
  int32_t col );

Parameters

Parameter	Type	Description
`row`	`int32_t`	The row number where the cursor will be placed.
`col`	`int32_t`	The column number where the cursor will be placed.

Return Values

This function does not return a value.

Notes

Affects where subsequent text output begins when using print.
Rows and columns are based on the currently set screen font.
Calling setCursor affects the position of subsequent text output only.

Examples

// Print at row 3 column 7
Brain.Screen.setCursor(3, 7);
Brain.Screen.print("VEXcode!");

The IQ (1st gen) Brain screen displaying centered text reading “VEXcode!”.

newLine#

Moves the cursor to the beginning of the next row on the Brain screen.

Available Functions

void newLine();

Parameters

This function does not accept any parameters.

Return Values

This function does not return a value.

Notes

If the cursor is in the middle of a sentence, newLine will clear the rest of the row after the cursor before moving to the next row.
After calling newLine, the cursor is positioned at the first column of the next line.
The cursor position and row numbering are set using setCursor.

Examples

// Display two lines of text
Brain.Screen.print("First message");
Brain.Screen.newLine();
Brain.Screen.print("Second message");

The IQ (1st gen) Brain screen displaying “First Message” and “Second Message,” displayed on separate lines.

clearLine#

Clears text from a row on the IQ (1st gen) Brain screen.

Available Functions

1 — Clears the rest of the current line from the cursor position.
void clearLine();

2 — Clears the specified row using the currently configured fill color.
void clearLine(
    int number );

3 — Clears the specified row using a predefined or custom color object.
void clearLine(
    int          number,
    const color& color );

4 — Clears the specified row using a hexadecimal color value.
void clearLine(
    int         number,
    const char* color );

5 — Clears the specified row using a hue value.
void clearLine(
    int number,
    int hue );

Parameters

Parameter	Type	Description
`number`	`int`	The row number to clear. Row numbering starts at `1`.
`color`	`const color&`	Clears the row using a `color` object. Predefined colors include: `black` `white` `red` `green` `blue` `yellow` `orange` `purple` `cyan` `transparent` This can also use a custom color object.
`color`	`const char*`	Clears the row using a hexadecimal color value (for example, `“#000000”`).
`hue`	`int`	Clears the row using an integer hue value in the range `0`–`359`, representing degrees around a color wheel.

Return Values

This function does not return a value.

Notes

Clearing a line does not change the current cursor position.
The cursor position and row numbering are set using setCursor.
The IQ (1st gen) Brain screen is a monochrome display, so specified colors will not appear on the screen.

Examples

// Display text on two rows
Brain.Screen.print("This text stays");
Brain.Screen.newLine();
Brain.Screen.print("This disappears");

// Wait 3 seconds before clearing row 2
wait(3, seconds);
Brain.Screen.clearLine(2);

row#

Returns the current cursor row position on the IQ (1st gen) Brain screen.

Available Functions

int32_t row();

Parameters

This function does not accept any parameters.

Return Values

Returns an int32_t representing the current cursor row position.

Row numbering starts at 1.

Notes

The cursor position is based on the current screen font.
The returned value indicates where the next printed output will appear.
The row value changes when text is printed or when setCursor is called.

Examples

// Display the cursor's current row
Brain.Screen.setCursor(3, 12);
Brain.Screen.print("row: ", Brain.Screen.row());

column#

Returns the current cursor column position on the IQ (1st gen) Brain screen.

Available Functions

int32_t column();

Parameters

This function does not accept any parameters.

Return Values

Returns an int32_t representing the current cursor column position.

Column numbering starts at 1.

Notes

The cursor position is based on the current screen font.
The returned value indicates where the next printed output will appear.
The column value changes when text is printed or when setCursor is called.

Examples

// Display the cursor's current column
Brain.Screen.print("column: ", Brain.Screen.column());

getStringHeight#

Returns the height, in pixels, of a string when rendered on the IQ (1st gen) Brain screen.

Available Functions

int32_t getStringHeight( 
    const char* cstr );

Parameters

Parameter	Type	Description
`cstr`	`const char*`	The text to be measured, provided as a C-style string (for example, `“Hello”`).

Return Values

Returns an int32_t representing the height of the string in pixels when rendered on the Brain screen.

Notes

The returned height depends on the currently selected screen font.
This function measures the string without drawing it to the screen.
The returned height reflects how the string would appear when printed.

getStringWidth#

Returns the width, in pixels, of a string when rendered on the IQ (1st gen) Brain screen.

Available Functions

int32_t getStringWidth( 
    const char* cstr );

Parameters

Parameter	Type	Description
`cstr`	`const char*`	The text to be measured, provided as a C-style string (for example, `“Hello”`).

Return Values

Returns an int32_t representing the width of the string in pixels when rendered on the Brain screen.

Notes

The returned width depends on the currently selected screen font.
This function measures the string without drawing it to the screen.
The returned width reflects how the string would appear when printed.

printAt#

Prints text, numbers, or Boolean values at a specific coordinate on the IQ (1st gen) Brain screen.

Available Functions

1 — Prints formatted output at the specified pixel location.
void printAt(
    int32_t    x,
    int32_t    y,
    const char* format,
    ... );

2 — Prints formatted output at the specified pixel location and sets whether the text background is opaque or transparent.
void printAt(
    int32_t    x,
    int32_t    y,
    bool       bOpaque,
    const char* format,
    ... );

Parameters

Parameter	Type	Description
`x`	`int32_t`	The x-position to print at, referenced to the screen origin.
`y`	`int32_t`	The y-position to print at, referenced to the screen origin.
`bOpaque`	`bool`	Controls whether the printed text is drawn opaquely or transparently: `true` — The background of the printed text is filled using the current fill color. `false` — The text is drawn transparently and the background is not filled.
`format`	`const char*`	A format string that controls what is printed on the screen (for example, `“Score: %d”`).
`…`		One or more additional values that are inserted into the format string, separated by commas.

Return Values

This function does not return a value.

Notes

The x and y coordinates are relative to the current screen origin, which can be changed using setOrigin.
Printed text uses the current screen font.
Printed text uses the current pen color.
When using a format string, the number and types of values passed must match the format specifiers in the string.

Examples

// Print the number 1 at pixel (100, 40)
Brain.Screen.printAt(100, 40, 1);

clearScreen#

Erases all drawings and text from the Brain’s screen.

Available Functions

1 — Clears the screen to black.
void clearScreen();

2 — Clears the screen using a predefined or custom color object.
void clearScreen(
    const color& color );

3 — Clears the screen using a hexadecimal color value.
void clearScreen(
    const char* color );

4 — Clears the screen using a hue value.
void clearScreen(
    int hue );

Parameters

Parameter	Type	Description
`color`	`const color&`	Clears the screen using a `color` object. Predefined colors include: `black` `white` `red` `green` `blue` `yellow` `orange` `purple` `cyan` `transparent` This can also use a custom color object.
`color`	`const char`	Clears the screen using a hexadecimal color value represented as a string (for example, `“#000000”`).
`hue`	`int`	Clears the screen using an integer hue value in the range `0`–`359`, representing degrees around a color wheel.

Parameter

Type

Description

color

const color&

Clears the screen using a color object. Predefined colors include:

black
white
red
green
blue
yellow
orange
purple
cyan
transparent

This can also use a custom color object.

color

const char

Clears the screen using a hexadecimal color value represented as a string (for example, “#000000”).

hue

int

Clears the screen using an integer hue value in the range 0–359, representing degrees around a color wheel.

Return Values

This function does not return a value.

Notes

The IQ (1st gen) Brain screen is a monochrome display, so specified colors will not appear on the screen.

Examples

// Clear screen after 2 seconds
Brain.Screen.print("VEXcode");
wait(2, seconds);
Brain.Screen.clearScreen();

// Clear screen to blue after 2 seconds
Brain.Screen.print("VEXcode");
wait(2, seconds);
Brain.Screen.clearScreen(red);

setFont#

Sets the font used for text displayed on the IQ (1st gen) Brain screen.

This controls the font applied to subsequent text output when using screen text functions such as print.

Available Functions

void setFont(
  fontType font );

Parameters

Parameter	Type	Description
`font`	`fontType`	Sets the font to one of the following: `mono12` `mono15` `mono20` `mono30` `mono40` `mono60` `prop20` `prop30` `prop40` `prop60` These options are shown below.

Parameter

Type

Description

font

fontType

Sets the font to one of the following:

mono12
mono15
mono20
mono30
mono40
mono60
prop20
prop30
prop40
prop60

These options are shown below.

Return Values

This function does not return a value.

Examples

// Display two different fonts on 
// two separate lines
Brain.Screen.setFont(mono20);
Brain.Screen.print("Mono Medium");
Brain.Screen.newLine();
Brain.Screen.setFont(prop20);
Brain.Screen.print("Prop Medium");

setPenWidth#

Sets the pen width used for drawing lines and shapes.

Available Functions

void setPenWidth(
  uint32_t width );

Parameters

Parameter	Type	Description
`width`	`uint32_t`	The pen width in pixels as a range from 0 to 32.

Return Values

This function does not return a value.

Notes

The pen width applies to drawing functions such as drawLine, drawRectangle, and drawCircle.

Examples

// Draw a circle with a pen width of 5
Brain.Screen.drawCircle(40, 70, 20);
Brain.Screen.setPenWidth(5);
Brain.Screen.drawCircle(100, 70, 20);

setPenColor#

Sets the pen color used for drawing lines, shapes, and text.

Available Functions

1 — Sets the pen color using a predefined or custom color object.
void setPenColor(
    const color& color );

2 — Sets the pen color using a hexadecimal color value.
void setPenColor(
    const char* color );

3 — Sets the pen color using a hue value.
void setPenColor(
    int hue );

Parameters

Parameter	Type	Description
`color`	`const color&`	Sets the pen color using a `color` object. Predefined colors include: `black` `white` `red` `green` `blue` `yellow` `orange` `purple` `cyan` `transparent`
`color`	`const char*`	Sets the pen color using a hexadecimal color value represented as a string (for example, `“#FF0000”`).
`hue`	`int`	Sets the pen color using an integer hue value in the range `0`–`359`, representing degrees around a color wheel (for example, `0` is red, `120` is green, and `240` is blue).

Parameter

Type

Description

color

const color&

Sets the pen color using a color object. Predefined colors include:

black
white
red
green
blue
yellow
orange
purple
cyan
transparent

color

const char*

Sets the pen color using a hexadecimal color value represented as a string (for example, “#FF0000”).

hue

int

Sets the pen color using an integer hue value in the range 0–359, representing degrees around a color wheel (for example, 0 is red, 120 is green, and 240 is blue).

Return Values

This function does not return a value.

Notes

The IQ (1st gen) Brain screen is a monochrome display, so specified colors will not appear on the screen.

Examples

```cpp
Brain.Screen.drawRectangle(100, 50, 10, 20);
Brain.Screen.setPenColor(blue);
Brain.Screen.drawRectangle(50, 50, 10, 20);

setFillColor#

Sets the fill color used when shapes are drawn.

Available Functions

1 — Sets the fill color using a predefined or custom color object.
void setFillColor(
    const color& color );

2 — Sets the fill color using a hexadecimal color value.
void setFillColor(
    const char* color );

3 — Sets the fill color using a hue value.
void setFillColor(
    int hue );

Parameters

Parameter	Type	Description
`color`	`const color&`	Sets the fill color using a `color` object. Predefined colors include: `black` `white` `red` `green` `blue` `yellow` `orange` `purple` `cyan` `transparent`
`color`	`const char`	Sets the fill color using a hexadecimal color value represented as a string (for example, `“#00FF00”`).
`hue`	`int`	Sets the fill color using an integer hue value in the range `0`–`359`, representing degrees around a color wheel (for example, `0` is red, `120` is green, and `240` is blue).

Parameter

Type

Description

color

const color&

Sets the fill color using a color object. Predefined colors include:

black
white
red
green
blue
yellow
orange
purple
cyan
transparent

color

const char

Sets the fill color using a hexadecimal color value represented as a string (for example, “#00FF00”).

hue

int

Sets the fill color using an integer hue value in the range 0–359, representing degrees around a color wheel (for example, 0 is red, 120 is green, and 240 is blue).

Return Values

This function does not return a value.

Notes

The IQ (1st gen) Brain screen is a monochrome display, so specified colors will not appear on the screen.

Examples

// Draw a circle filled with yellow
Brain.Screen.setFillColor(yellow);
Brain.Screen.drawCircle(50, 50, 20);

setOrigin#

Sets the origin used for drawing graphics on the Brain’s screen.

Available Functions

void setOrigin(
  int32_t x,
  int32_t y );

Parameters

Parameter	Type	Description
`x`	`int32_t`	The origin’s x-position relative to top left corner of the Brain’s screen from 0 to 160.
`y`	`int32_t`	The origin’s y-position relative to top left corner of the Brain’s screen from 0 to 108.

Return Values

This function does not return a value.

Notes

The default origin is the top-left corner of the screen at coordinate (0, 0).
The origin applies to coordinate functions such as drawLine, drawRectangle, drawCircle, and printAt.
The origin remains in effect until changed again or the project is reset.

setClipRegion#

Defines a rectangular area on the screen where all drawings and text will be confined. Any content outside this region will not be displayed.

Available Functions

void setClipRegion(
  int x,
  int y,
  int width,
  int height );

Parameters

Parameter	Type	Description
`x`	`int`	The x-coordinate of the top-left corner of the clip region, given as an integer from 0 to 160.
`y`	`int`	The y-coordinate of the top-left corner of the clip region, given as an integer from 0 to 108.
`width`	`int`	The width of the clip region in pixels, given as an integer from 0 to 160.
`height`	`int`	The height of the clip region in pixels, given as an integer from 0 to 108.

Return Values

This function does not return a value.

Notes

Drawing functions are still executed even if they fall outside the clip region, but only the portion inside the region is visible.
The x and y coordinates are relative to the current screen origin, which can be changed using setOrigin.
The clip region applies only to the current thread.
Setting a new clip region replaces any previously set clip region for the current thread.

Examples

// Restrict text and drawings to a specific region
Brain.Screen.setClipRegion(0, 0, 120, 120);
Brain.Screen.drawRectangle(60, 60, 100, 100, red);
Brain.Screen.printAt(60, 60, "Cut off!");

drawPixel#

Draws a single pixel on the IQ (1st gen) Brain screen at the specified x and y pixel location.

Available Functions

void drawPixel(
  int x,
  int y );

Parameters

Parameter	Type	Description
`x`	`int`	The x-coordinate where the pixel will be drawn, given as an integer from 0 to 160.
`y`	`int`	The y-coordinate where the pixel will be drawn, given as an integer from 0 to 108.

Return Values

This function does not return a value.

Notes

The IQ (1st gen) Brain screen is a monochrome display, so specified colors will not appear on the screen.
The x and y coordinates are relative to the current screen origin, which can be set using setOrigin.
If the specified pixel location is outside the screen bounds, the pixel is not drawn.

Examples

// Draw one pixel at the center 
// of the screen
Brain.Screen.drawPixel(80, 50);

drawLine#

Draws a straight line connecting two points on the IQ (1st gen) Brain screen.

Available Functions

void drawLine(
  int x1,
  int y1,
  int x2,
  int y2 );

Parameters

Parameter	Type	Description
`x1`	`int`	The starting x-coordinate of the line, given as an integer from 0 to 160.
`y1`	`int`	The starting y-coordinate of the line, given as an integer from 0 to 108.
`x2`	`int`	The ending x-coordinate of the line, given as an integer from 0 to 160.
`y2`	`int`	The ending y-coordinate of the line, given as an integer from 0 to 108.

Return Values

This function does not return a value.

Notes

The IQ (1st gen) Brain screen is a monochrome display, so specified colors will not appear on the screen.
The width of the line is determined by the current pen width set with setPenWidth.
The x and y coordinates are relative to the current screen origin, which can be set using setOrigin.
If any portion of the line lies outside the screen bounds, only the visible portion is drawn.

Examples

// Draw a line from the top left to 
// bottom right of the screen
Brain.Screen.drawLine(0, 0, 159, 107);

drawRectangle#

Draws a rectangle on the IQ (1st gen) Brain screen at the specified position and size.

Available Functions

1 — Draws and fills a rectangle using the currently configured fill color.
void drawRectangle(
    int x,
    int y,
    int width,
    int height );

2 — Draws and fills a rectangle using a predefined or custom color object.
void drawRectangle(
    int           x,
    int           y,
    int           width,
    int           height,
    const color&  color );

3 — Draws and fills a rectangle using a hexadecimal color value.
void drawRectangle(
    int           x,
    int           y,
    int           width,
    int           height,
    const char*   color );

4 — Draws and fills a rectangle using a hue value.
void drawRectangle(
    int x,
    int y,
    int width,
    int height,
    int hue );

Parameters

Parameter	Type	Description
`x`	`int`	The x-coordinate of the top-left corner of the rectangle, given as an integer from 0 to 160.
`y`	`int`	The y-coordinate of the top-left corner of the rectangle, given as an integer from 0 to 108.
`width`	`int`	The width of the rectangle, given as an integer from 0 to 160.
`height`	`int`	The height of the rectangle, given as an integer from 0 to 108.
`color`	`const color&`	Fills the rectangle using a `color` object. Predefined colors include: `black` `white` `red` `green` `blue` `yellow` `orange` `purple` `cyan` `transparent` This can also use a custom color object.
`color`	`const char*`	Fills the rectangle using a hexadecimal color value (for example, `“#FF0000”`).
`hue`	`int`	Fills the rectangle using a hue value in the range `0`–`359`.

Return Values

This function does not return a value.

Notes

The IQ (1st gen) Brain screen is a monochrome display, so specified colors will not appear on the screen.
The outline thickness is determined by the current pen width set with setPenWidth.
The x and y coordinates are relative to the current screen origin, which can be changed using setOrigin.
If any portion of the rectangle lies outside the screen bounds, only the visible portion is drawn.

Examples

// Draw a red rectangle on the screen
Brain.Screen.drawRectangle(25, 25, 100, 50, red);

drawCircle#

Draws a circle on the IQ (1st gen) Brain screen at the specified position and radius.

Available Functions

1 — Draws and fills a circle using the currently configured fill color.
void drawCircle(
    int x,
    int y,
    int radius );

2 — Draws and fills a circle using a predefined or custom color object.
void drawCircle(
    int           x,
    int           y,
    int           radius,
    const color&  color );

3 — Draws and fills a circle using a hexadecimal color value.
void drawCircle(
    int           x,
    int           y,
    int           radius,
    const char*   color );

4 — Draws and fills a circle using a hue value.
void drawCircle(
    int x,
    int y,
    int radius,
    int hue );

Parameters

Parameter	Type	Description
`x`	`int`	The x-coordinate of the center of the circle, given as an integer from 0 to 160.
`y`	`int`	The y-coordinate of the center of the circle, given as an integer from 0 to 108.
`radius`	`int`	The radius of the circle, given as an integer from 0 to 108 pixels.
`color`	`const color&`	Fills the circle using a `color` object. Predefined colors include: `black` `white` `red` `green` `blue` `yellow` `orange` `purple` `cyan` `transparent` This can also use a custom color object.
`color`	`const char*`	Fills the circle using a hexadecimal color value (for example, `“#FF0000”`).
`hue`	`int`	Fills the circle using a hue value in the range `0`–`359`.

Return Values

This function does not return a value.

Notes

The IQ (1st gen) Brain screen is a monochrome display, so specified colors will not appear on the screen.
The outline thickness is determined by the current pen width set with setPenWidth.
The x and y coordinates are relative to the current screen origin, which can be changed using setOrigin.

Examples

// Draw a green circle on the screen
Brain.Screen.drawCircle(80, 50, 20, green);

render#

Enables double buffering for the Brain’s screen. Once called, any drawing functions (like text or shapes) will no longer appear immediately for the rest of the project. Instead, updates will only be shown when render is used again. This allows for smoother and more controlled screen updates, but means nothing will be visible until render is used.

Available Functions

1 — Enables double buffering or renders the back buffer to the screen.
bool render();

2 — Renders the back buffer to the screen with control over vertical sync behavior and optional scheduler execution.
bool render(
    bool bVsyncWait,
    bool bRunScheduler = true );

Parameters

Parameter	Type	Description
`bVsyncWait`	`bool`	`true` — Wait for the screen’s vertical refresh before rendering to reduce visual tearing. `false` — Do not wait for the screen’s vertical refresh before rendering.
`bRunScheduler`	`bool`	Optional. `true` (default) — Allow background tasks to run while waiting to render. `false` — Do not allow background tasks to run while waiting to render.

Parameter

Type

Description

bVsyncWait

bool

true — Wait for the screen’s vertical refresh before rendering to reduce visual tearing.
false — Do not wait for the screen’s vertical refresh before rendering.

bRunScheduler

bool

Optional.

true (default) — Allow background tasks to run while waiting to render.
false — Do not allow background tasks to run while waiting to render.

Return Values

Returns a Boolean indicating whether the saved drawings in the buffer were successfully rendered to the screen:

true — The drawings were successfully rendered on the screen.
false — The drawings could not be rendered on the screen.

Notes

Calling render will require render to be used for the rest of the project.

Examples

Brain.Screen.render();

// Draw text to the back buffer
Brain.Screen.print("Render later...");

// Wait for a screen press to render drawings
while (!Brain.Screen.pressing()) {
  wait(20, msec);
}
Brain.Screen.render();