螢幕#

介紹 #

screen 類別衍生自 brain 基底類別。它控制 V5 Brain 如何在其觸控螢幕上顯示文字、數字和圖形，以及如何回應觸控輸入。

預設情況下，列印到大腦的字體是等寬小號，它有 12 行 48 列。

大腦的繪圖解析度為 480 x 240 像素。

V5 大腦螢幕，紅色網格線顯示了總共 12 行 48 列的佈局。像素尺寸為 479 寬 x 239 高。左上角起始於 0,0 像素，位於第 1 行第 1 列；右下角結束於 479, 239 像素，位於第 12 行第列。

使用權 #

可以透過以下方式存取 screen 類：

Brain.Screen

筆記 #

The screen object is provided by the Brain. It is not constructed directly.
項目使用單一全域 Brain 對象，因此螢幕函數使用 Brain.Screen呼叫。

例子 #

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

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

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

成員功能 #

screen 類別包含以下成員函數：

print — 將格式化的文字、數字或布林值列印到 Brain 畫面。
setCursor — 將文字遊標移到指定的行和列。
newLine — 清除目前行的剩餘內容並將遊標移至下一行。
clearLine — 清除目前行的剩餘部分或清除指定的行。
row — 傳回要列印文字的行。
column — 傳回要列印文字的列。
getStringHeight — 使用目前字體傳回字串的像素高度。
getStringWidth — 使用目前字體傳回字串的像素寬度。
printAt — 在 x, y 像素位置列印格式化文字。
clearScreen — 清除大腦螢幕上的所有圖形和文字。
setFont — 設定用於螢幕列印的字型。
setPenWidth — 設定繪製的線條和形狀輪廓的粗細。
setPenColor — 設定文字、像素、線條和形狀輪廓的顏色。
setFillColor — 設定繪製形狀和列印文字背景的填滿顏色。
setOrigin — 設定螢幕座標的原點。
setClipRegion — 將螢幕輸出限制在長方形區域內。
drawPixel — 在座標處繪製一個像素。
drawLine — 在兩點之間畫一條線。
drawRectangle — 在 x, y 位置繪製一個指定大小的矩形。
drawCircle — 在 x, y 位置繪製一個具有指定半徑的圓。
drawImageFromFile — 將 SD 卡檔案中的影像繪製到螢幕上。
render — 啟用雙緩衝或將後緩衝區渲染到螢幕。
pressing — 返回螢幕目前是否被按下。
xPosition — 傳回最近一次畫面按下的 x 座標。
yPosition — 傳回最近一次畫面按下的 y 座標。
pressed — 註冊一個在螢幕被按下時運行的回呼函數。
released — 註冊一個回呼函數，當螢幕被按下後釋放時運行。

在呼叫任何 screen 成員函數之前，必須建立一個 brain 實例，如下所示：

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

print #

在 V5 Brain 畫面上顯示文字、數字或布林值。

Available Functions

1 — 使用字串字面量或唯讀 C 風格字串列印格式化文字。
void print(
    const char* format,
    ... );

2 — 使用可修改的字元陣列列印格式化文字。
void print(
    char* format,
    ... );

Parameters

範圍	類型	描述
`format`	`const char*`	以字串字面量或唯讀 C 風格字串形式提供的格式字串（例如， `“Score: %d”`）。
`format`	`char*`	以可修改字元數組形式提供的格式字串。
`…`		插入到格式字串中的一個或多個附加值，以逗號分隔。

Return Values

此函數不傳回值。

Notes

Output begins at the current cursor position on the screen.
列印文字使用螢幕字體。
列印文字使用筆顏色。
使用 print 列印的文字始終帶有背景，背景顏色由目前填滿顏色決定。
使用格式字串時，傳遞的值的數量和類型必須與字串中的格式說明符相符。

Examples

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

V5 大腦的螢幕截圖，顯示螢幕左上角以白色文字列印著「Hello, Robot!」。

setCursor #

將遊標移到 V5 Brain 螢幕上的特定行和列。下一次 print 呼叫將從該位置開始列印。

Available Functions

void setCursor(
  int32_t row, 
  int32_t col );

Parameters

範圍	類型	描述
`row`	`int32_t`	要將遊標移到的行。
`col`	`int32_t`	要將遊標移到的列。

Return Values

此函數不傳回值。

Notes

影響使用 print 時後續文字輸出的起始位置。
行和列基於目前設定的螢幕字體。
預設字體（mono20）使用 12 行和 48 列。
呼叫 setCursor 只會影響後續文字輸出的位置。

Examples

// Display text starting at Row 3 Column 12
Brain.Screen.setCursor(3, 12);
Brain.Screen.print("Row 3, Column 12");

V5 Brain 的螢幕截圖，顯示螢幕上方靠近中心位置列印的第 3 行第 12 列。

newLine #

將遊標移到大腦螢幕上下一行的開頭。

Available Functions

void newLine();

Parameters

此函數不接受任何參數。

Return Values

此函數不傳回值。

Notes

如果遊標位於句子的中間，則 newLine 將清除遊標之後的行的其餘部分，然後再移至下一行。
呼叫 newLine後，遊標位於下一行的第一列。
使用 setCursor 設定遊標位置和行號。

Examples

// Display two lines of text
Brain.Screen.print("Line 1");
Brain.Screen.newLine();
Brain.Screen.print("Line 2");

V5 Brain 螢幕的截圖，顯示左上角有兩行白色文字。上面一行是“第 1 行”，緊鄰它的第二行是“第 2 行”。

clearLine #

清除 V5 Brain 螢幕上某一行的文字。

Available Functions

1 — 清除遊標位置的目前行剩餘內容。
void clearLine();

2 — 使用目前配置的填滿顏色清除指定的行。
void clearLine(
    int number );

3 — 使用預先定義或自訂顏色物件清除指定的行。
void clearLine(
    int          number,
    const color& color );

4 — 使用十六進位顏色值清除指定的行。
void clearLine(
    int         number,
    const char* color );

5 — 使用色調值清除指定的行。
void clearLine(
    int number,
    int hue );

Parameters

範圍	類型	描述
`number`	`int`	要清除的行號。行號從 `1`開始。
`color`	`const color&`	使用 `color` 对象清除行。预定义颜色包括： `black` `white` `red` `green` `blue` `yellow` `orange` `purple` `cyan` `transparent` 这也可以使用自定义颜色对象。
`color`	`const char*`	使用十六進位顏色值清除行（例如， `“#000000”`）。
`hue`	`int`	使用 `0`–`359`範圍內的整數色調值清除行，表示色輪上的度數。

Return Values

此函數不傳回值。

Notes

清除一行不會改變目前遊標位置。
使用 setCursor 設定遊標位置和行號。
hue 參數值基於圓形色輪，如下圖所示，其中值表示色輪上的度數（例如，紅色接近 0°，綠色接近 120°，藍色接近 240°）。

一個色輪，顯示從 0 到 359 的顏色範圍，其中紅色為 0，綠色為 120，藍色為 240。

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 #

傳回將在 V5 Brain 螢幕上列印文字的行。

Available Functions

int32_t row();

Parameters

此函數不接受任何參數。

Return Values

傳回 int32_t ，表示要列印文字的行。

行號從1開始。

Notes

遊標位置基於螢幕字體。
返回值指示下一個列印輸出將顯示在哪裡。
當列印文字或呼叫 setCursor 時，行值會改變。

Examples

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

V5 Brain 螢幕的螢幕截圖，顯示螢幕左上角第 3 行第 12 列位置的白色文字「3」。

column #

傳回將在 V5 Brain 畫面上列印文字的列。

Available Functions

int32_t column();

Parameters

此函數不接受任何參數。

Return Values

傳回 int32_t ，表示要列印文字的列。

列編號從 1 開始。

Notes

遊標位置基於螢幕字體。
返回值指示下一個列印輸出將顯示在哪裡。
當列印文字或呼叫 setCursor 時，列值會發生變化。

Examples

// Display the cursor's current column
Brain.Screen.setCursor(5, 15);
Brain.Screen.print(Brain.Screen.column());

V5 Brain 螢幕的螢幕截圖，顯示螢幕左上角第 3 行第 15 列位置的白色文字「15」。

getStringHeight #

傳回字串在 V5 Brain 螢幕上渲染時的高度（以像素為單位）。

Available Functions

int32_t getStringHeight( 
    const char* cstr );

Parameters

範圍	類型	描述
`cstr`	`const char*`	要測量的文本，以 C 風格字串的形式提供（例如， `“Hello”`）。

Return Values

傳回 int32_t ，表示字串在 Brain 螢幕上渲染時的像素高度。

Notes

返回的高度取決於目前選定的螢幕。
此函數測量字串的長度，但不將其繪製到螢幕上。
傳回的高度反映了字串列印時的外觀。

getStringWidth #

傳回字串在 V5 Brain 螢幕上渲染時的寬度（以像素為單位）。

Available Functions

int32_t getStringWidth( 
    const char* cstr );

Parameters

範圍	類型	描述
`cstr`	`const char*`	要測量的文本，以 C 風格字串的形式提供（例如， `“Hello”`）。

Return Values

傳回 int32_t ，表示字串在 Brain 螢幕上渲染時的像素寬度。

Notes

傳回的取決於目前選定的螢幕字體。
此函數測量字串的長度，但不將其繪製到螢幕上。
傳回的寬度反映了字串列印時的顯示方式。

printAt #

在 V5 腦螢幕上的特定座標處列印文字、數字或布林值。

Available Functions

1 — 在指定的像素位置列印格式化的輸出。
void printAt(
    int32_t    x,
    int32_t    y,
    const char* format,
    ... );

2 — 在指定的像素位置列印格式化的輸出，並設定文字背景是不透明還是透明。
void printAt(
    int32_t    x,
    int32_t    y,
    bool       bOpaque,
    const char* format,
    ... );

Parameters

範圍	類型	描述
`x`	`int32_t`	列印位置的 x 座標，以螢幕原點為參考。
`y`	`int32_t`	列印位置的 y 座標，以螢幕原點為參考。
`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*`	控制螢幕上列印內容的格式字串（例如， `“Score: %d”`）。
`…`		插入到格式字串中的一個或多個附加值，以逗號分隔。

Return Values

此函數不傳回值。

Notes

x 和 y 座標是相對於目前螢幕原點的，可以使用 setOrigin 進行更改。
列印文字使用螢幕字體。
列印文字使用筆顏色。
使用格式字串時，傳遞的值的數量和類型必須與字串中的格式說明符相符。

Examples

// Print "Center" at the center of the screen
Brain.Screen.printAt(220, 120, "Center");

V5 Brain 螢幕的截圖，螢幕中央有白色文字「Center」。

clearScreen #

清除大腦螢幕上的所有圖形和文本，並將遊標位置重設為第 1 行第 1 列。

Available Functions

1 — 將螢幕清空至黑色。
void clearScreen();

2 — 使用預先定義或自訂顏色物件清除螢幕。
void clearScreen(
    const color& color );

3 — 使用十六進位顏色值清除螢幕。
void clearScreen(
    const char* color );

4 — 使用色調值清除螢幕。
void clearScreen(
    int hue );

Parameters

範圍	類型	描述
`color`	`const color&`	使用 `color` 对象清除屏幕。预定义颜色包括： `black` `white` `red` `green` `blue` `yellow` `orange` `purple` `cyan` `transparent` 也可以使用自定义颜色对象。
`color`	`const char*`	使用以字串形式表示的十六進位顏色值清除螢幕（例如， `“#000000”`）。
`hue`	`int`	使用 `0`–`359`範圍內的整數色調值清除螢幕，表示色輪上的度數。

範圍

類型

描述

color

const color&

使用 color 对象清除屏幕。预定义颜色包括：

black
white
red
green
blue
yellow
orange
purple
cyan
transparent

也可以使用自定义颜色对象。

color

const char*

使用以字串形式表示的十六進位顏色值清除螢幕（例如， “#000000”）。

hue

int

使用 0–359範圍內的整數色調值清除螢幕，表示色輪上的度數。

Return Values

此函數不傳回值。

Notes

hue 參數值基於圓形色輪，如下圖所示，其中值表示色輪上的度數（例如，紅色接近 0°，綠色接近 120°，藍色接近 240°）。

一個色輪，顯示從 0 到 359 的顏色範圍，其中紅色為 0，綠色為 120，藍色為 240。

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(blue);

V5 Brain 螢幕的截圖，其中整個可列印區域呈現亮藍色。

setFont #

設定 V5 Brain 螢幕上顯示的文字所使用的字型。

這控制在使用螢幕文字功能（例如 print）時應用於後續文字輸出的字體。

Available Functions

void setFont(
  fontType font );

Parameters

範圍	類型	描述
`font`	`fontType`	Sets the font to one of the following: `mono12` `mono15` `mono20` `mono30` `mono40` `mono60` `prop20` `prop30` `prop40` `prop60` `fontType::cjk16` — Can print Chinese, Japanese, and Korean characters. Simplified Chinese — Can be seen up to column 28. Traditional Chinese — Can be seen up to column 28. Japanese (Kanji) — Can be seen up to column 28. Korean (Hangul) — Can be seen up to column 30. These options are shown below.

範圍

類型

描述

font

fontType

Sets the font to one of the following:

mono12
mono15
mono20
mono30
mono40
mono60
prop20
prop30
prop40
prop60
fontType::cjk16 — Can print Chinese, Japanese, and Korean characters.
- Simplified Chinese — Can be seen up to column 28.
- Traditional Chinese — Can be seen up to column 28.
- Japanese (Kanji) — Can be seen up to column 28.
- Korean (Hangul) — Can be seen up to column 30.

These options are shown below.

`mono12`	`mono15`	`mono20`
`mono30`	`mono40`	`mono60`
`prop20`	`prop30`	`prop40`
`prop60`	`fontType::cjk16`

Return Values

此函數不傳回值。

Examples

// Print larger text
Brain.Screen.setFont(mono40);
Brain.Screen.print("VEX");

V5 Brain 螢幕的截圖，顯示左上角有白色文字，字體比預設字體大，內容為 VEX。

// Print in Chinese
Brain.Screen.setFont(fontType::cjk16);
Brain.Screen.print("VEX机器人");

V5 大腦螢幕的截圖，左上角顯示中文「VEX 機器人」字樣。

setPenWidth #

設定繪製線條和形狀輪廓的粗細。

Available Functions

void setPenWidth(
  uint32_t width );

Parameters

範圍	類型	描述
`width`	`uint32_t`	筆的寬度，以像素為單位，範圍從 0 到 32。

Return Values

此函數不傳回值。

Notes

筆寬適用於諸如 drawLine、drawRectangle 和 drawCircle 之類的繪圖函數。

Examples

// Draw a rectangle with a pen width of 10
Brain.Screen.setPenWidth(10);
Brain.Screen.drawRectangle(50, 50, 130, 60);

V5 Brain 螢幕的螢幕截圖，顯示螢幕左上角印著一個帶有粗邊框的矩形。

setPenColor #

設定文字、像素、線條和形狀輪廓的顏色。

Available Functions

1 — 使用預先定義或自訂顏色物件設定畫筆顏色。
void setPenColor(
    const color& color );

2 — 使用十六進位顏色值設定畫筆顏色。
void setPenColor(
    const char* color );

3 — 使用色調值設定畫筆顏色。
void setPenColor(
    int hue );

Parameters

範圍	類型	描述
`color`	`const color&`	使用 `color` 对象设置画笔颜色。预定义颜色包括： `black` `white` `red` `green` `blue` `yellow` `orange` `purple` `cyan` `transparent`
`color`	`const char*`	使用以字串形式表示的十六進位顏色值來設定畫筆顏色（例如， `“#FF0000”`）。
`hue`	`int`	使用 `0`–`359`範圍內的整數色調值設定畫筆顏色，表示色輪上的度數（例如， `0` 為紅色， `120` 為綠色， `240` 為藍色）。

範圍

類型

描述

color

const color&

使用 color 对象设置画笔颜色。预定义颜色包括：

black
white
red
green
blue
yellow
orange
purple
cyan
transparent

color

const char*

使用以字串形式表示的十六進位顏色值來設定畫筆顏色（例如， “#FF0000”）。

hue

int

使用 0–359範圍內的整數色調值設定畫筆顏色，表示色輪上的度數（例如， 0 為紅色， 120 為綠色， 240 為藍色）。

Return Values

此函數不傳回值。

Notes

項目開始時的預設畫筆顏色為 white。
笔的颜色用于绘制形状的轮廓（例如使用 drawCircle 或 drawRectangle），文本和数字输出（使用 print 和 printAt），以及使用 drawPixel 绘制的单个像素。
hue 參數值基於圓形色輪，如下圖所示，其中值表示色輪上的度數（例如，紅色接近 0°，綠色接近 120°，藍色接近 240°）。

一個色輪，顯示從 0 到 359 的顏色範圍，其中紅色為 0，綠色為 120，藍色為 240。

Examples

// Draw a rectangle with orange borders
Brain.Screen.setPenColor(orange);
Brain.Screen.drawRectangle(50, 50, 130, 60);

V5 Brain 螢幕的截圖，顯示螢幕左上角繪製了一個橘色矩形。

setFillColor #

設定繪製形狀時所使用的填滿顏色。

Available Functions

1 — 使用預先定義或自訂顏色物件設定填滿顏色。
void setFillColor(
    const color& color );

2 — 使用十六進位顏色值設定填滿顏色。
void setFillColor(
    const char* color );

3 — 使用色調值設定填滿顏色。
void setFillColor(
    int hue );

Parameters

範圍	類型	描述
`color`	`const color&`	使用 `color` 对象设置填充颜色。预定义颜色包括： `black` `white` `red` `green` `blue` `yellow` `orange` `purple` `cyan` `transparent`
`color`	`const char*`	使用以字串形式表示的十六進位顏色值設定填滿顏色（例如， `“#00FF00”`）。
`hue`	`int`	使用 `0`–`359`範圍內的整數色調值設定填滿顏色，表示色輪上的度數（例如， `0` 為紅色， `120` 為綠色， `240` 為藍色）。

範圍

類型

描述

color

const color&

使用 color 对象设置填充颜色。预定义颜色包括：

black
white
red
green
blue
yellow
orange
purple
cyan
transparent

color

const char*

使用以字串形式表示的十六進位顏色值設定填滿顏色（例如， “#00FF00”）。

hue

int

使用 0–359範圍內的整數色調值設定填滿顏色，表示色輪上的度數（例如， 0 為紅色， 120 為綠色， 240 為藍色）。

Return Values

此函數不傳回值。

Notes

項目開始時的預設填滿顏色為 black。
填滿顏色用於形狀的內部（例如使用 drawCircle 或 drawRectangle）。
填滿顏色用作列印文字的背景顏色（例如使用 print 和 printAt）。
- 如果 transparent 與印刷文字一起使用，則背景將為 black。
hue 參數值基於圓形色輪，如下圖所示，其中值表示色輪上的度數（例如，紅色接近 0°，綠色接近 120°，藍色接近 240°）。

一個色輪，顯示從 0 到 359 的顏色範圍，其中紅色為 0，綠色為 120，藍色為 240。

Examples

// Draw a rectangle filled with purple
  Brain.Screen.setFillColor(purple);
  Brain.Screen.drawRectangle(50, 100, 130, 60);

V5 Brain 螢幕的截圖，顯示螢幕左下角有一個填滿紫色的長方形。

setOrigin #

設定大腦螢幕上用於繪圖和基於座標的列印的原點。

Available Functions

void setOrigin(
  int32_t x,
  int32_t y );

Parameters

範圍	類型	描述
`x`	`int32_t`	原點相對於大腦螢幕左上角的 x 座標，取值範圍為 0 到 479。
`y`	`int32_t`	原點相對於大腦螢幕左上角的 y 座標，範圍從 0 到 239。

Return Values

此函數不傳回值。

Notes

預設原點位於螢幕左上角座標 (0, 0)。
原點適用於座標函數，例如 drawLine、drawRectangle、drawCircle 和 printAt。
此原點設定將一直有效，直到再次變更或項目重設為止。

setClipRegion #

在螢幕上定義一個矩形區域，所有圖形和文字都將限制在該區域內。該區域以外的任何內容都不會顯示。

Available Functions

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

Parameters

範圍	類型	描述
`x`	`int`	剪輯區域左上角的 x 座標，取值範圍為 0 到 479 的整數。
`y`	`int`	剪輯區域左上角的 y 座標，取值範圍為 0 到 239 的整數。
`width`	`int`	裁切區域的寬度（以像素為單位），取值範圍為 0 到 479 的整數。
`height`	`int`	裁切區域的高度（以像素為單位），取值範圍為 0 到 239 的整數。

Return Values

此函數不傳回值。

Notes

即使繪圖函數超出裁切區域，它們仍然會執行，但只有區域內的部分是可見的。
x 和 y 座標是相對於目前螢幕原點的，可以使用 setOrigin 進行更改。
剪輯區域僅適用於目前執行緒。
設定新的剪輯區域會取代目前執行緒之前設定的任何剪輯區域。

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!");

V5 大腦螢幕的截圖，白色文字顯示“Cut of”，左上角象限下方有一個實心紅色方塊，反映了剪輯區域內打印的內容。

drawPixel #

在 V5 Brain 螢幕上選定的 x 和 y 像素位置繪製一個像素。

Available Functions

void drawPixel(
  int x,
  int y );

Parameters

範圍	類型	描述
`x`	`int`	像素繪製位置的 x 座標，取值範圍為 0 到 479 之間的整數。
`y`	`int`	像素將被繪製的 y 座標，取值範圍為 0 到 239 的整數。

Return Values

此函數不傳回值。

Notes

使用 setPenColor 設定目前畫筆顏色來繪製像素。
x 和 y 座標是相對於目前螢幕原點的，可以使用 setOrigin 進行設定。
如果指定的像素位置在螢幕邊界之外，則不會繪製該像素。

Examples

// Draw the pixels marking the corners of a square
Brain.Screen.drawPixel(250, 100);
Brain.Screen.drawPixel(275, 100);
Brain.Screen.drawPixel(250, 125);
Brain.Screen.drawPixel(275, 125);

drawLine #

在 V5 Brain 螢幕上繪製連接兩點的直線。

Available Functions

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

Parameters

範圍	類型	描述
`x1`	`int`	直線的起始 x 座標，取值範圍為 0 到 479 的整數。
`y1`	`int`	直線的起始 y 座標，取值範圍為 0 到 239 的整數。
`x2`	`int`	直線的終點 x 座標，取值範圍為 0 到 479 的整數。
`y2`	`int`	直線的終點 y 座標，取值範圍為 0 到 239 的整數。

Return Values

此函數不傳回值。

Notes

使用 setPenColor 設定目前畫筆顏色來繪製線條。
線條的寬度由目前筆寬決定，該筆寬透過 setPenWidth 設定。
x 和 y 座標是相對於目前螢幕原點的，可以使用 setOrigin 進行設定。
如果線條的任何部分超出螢幕邊界，則只繪製可見部分。

Examples

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

V5 Brain 螢幕的截圖顯示，螢幕中心有一條細斜線，從左上角延伸到右下角。

drawRectangle #

在 V5 Brain 螢幕上指定位置和大小繪製矩形。

Available Functions

1 — 使用目前配置的填滿顏色繪製並填滿矩形。
void drawRectangle(
    int x,
    int y,
    int width,
    int height );

2 — 使用預先定義或自訂顏色物件繪製並填滿矩形。
void drawRectangle(
    int           x,
    int           y,
    int           width,
    int           height,
    const color&  color );

3 — 使用十六進位顏色值繪製並填滿矩形。

void drawRectangle(
    int           x,
    int           y,
    int           width,
    int           height,
    const char*   color );

4 — 使用色調值繪製並填滿矩形。
void drawRectangle(
    int x,
    int y,
    int width,
    int height,
    int hue );

Parameters

範圍	類型	描述
`x`	`int`	矩形左上角的 x 座標，取值範圍為 0 到 479 的整數。
`y`	`int`	矩形左上角的 y 座標，取值範圍為 0 到 239 的整數。
`width`	`int`	矩形的寬度，取值範圍為 0 到 479 之間的整數。
`height`	`int`	矩形的高度，取值範圍為 0 到 239 的整數。
`color`	`const color&`	使用 `color` 对象填充矩形。预定义颜色包括： `black` `white` `red` `green` `blue` `yellow` `orange` `purple` `cyan` `transparent` 也可以使用自定义颜色对象。
`color`	`const char*`	使用十六進位顏色值填滿矩形（例如， `“#FF0000”`）。
`hue`	`int`	使用 `0`–`359`範圍內的色調值填滿矩形。

Return Values

此函數不傳回值。

Notes

使用 setPenColor 設定目前畫筆顏色來繪製矩形輪廓。
輪廓粗細由目前筆寬決定，該筆寬透過 setPenWidth 設定。
當未提供 color 參數時，矩形內部將使用 setFillColor 設定的目前填滿顏色進行填滿。
x 和 y 座標是相對於目前螢幕原點的，可以使用 setOrigin 進行更改。
如果矩形的任何部分位於螢幕邊界之外，則只繪製可見部分。
hue 參數值基於圓形色輪，如下圖所示，其中值表示色輪上的度數（例如，紅色接近 0°，綠色接近 120°，藍色接近 240°）。

一個色輪，顯示從 0 到 359 的顏色範圍，其中紅色為 0，綠色為 120，藍色為 240。

Examples

// Draw a rectangle on the screen
Brain.Screen.drawRectangle(50, 50, 130, 60);

V5 大腦螢幕的截圖顯示，左上象限印著一個帶有細白邊框的矩形。

drawCircle #

在 V5 Brain 畫面上，於指定位置和半徑處繪製一個圓。

Available Functions

1 — 使用目前配置的填滿顏色繪製並填入圓形。
void drawCircle(
    int x,
    int y,
    int radius );

2 — 使用預先定義或自訂顏色物件繪製並填入圓形。
void drawCircle(
    int           x,
    int           y,
    int           radius,
    const color&  color );

3 — 使用十六進位顏色值繪製並填滿一個圓。
void drawCircle(
    int           x,
    int           y,
    int           radius,
    const char*   color );

4 — 使用色相值繪製並填滿圓形。
void drawCircle(
    int x,
    int y,
    int radius,
    int hue );

Parameters

範圍	類型	描述
`x`	`int`	圓心的 x 座標，取值範圍為 0 到 479 之間的整數。
`y`	`int`	圓心的 y 座標，取值範圍為 0 到 239 的整數。
`radius`	`int`	圓的半徑，取值範圍為 0 到 239 像素的整數。
`color`	`const color&`	使用 `color` 对象填充圆圈。预定义颜色包括： `black` `white` `red` `green` `blue` `yellow` `orange` `purple` `cyan` `transparent` 也可以使用自定义颜色对象。
`color`	`const char*`	使用十六進位顏色值填滿圓圈（例如， `“#FF0000”`）。
`hue`	`int`	使用 `0`–`359`範圍內的色調值填滿圓形。

Return Values

此函數不傳回值。

Notes

使用 setPenColor 設定目前畫筆顏色來繪製圓形的輪廓。
輪廓粗細由目前筆寬決定，該筆寬透過 setPenWidth 設定。
當未提供 color 參數時，圓的內部將使用 setFillColor 設定的目前填滿顏色進行填滿。
x 和 y 座標是相對於目前螢幕原點的，可以使用 setOrigin 進行更改。
hue 參數值基於圓形色輪，如下圖所示，其中值表示色輪上的度數（例如，紅色接近 0°，綠色接近 120°，藍色接近 240°）。

一個色輪，顯示從 0 到 359 的顏色範圍，其中紅色為 0，綠色為 120，藍色為 240。

Examples

// Draw a circle on the screen
Brain.Screen.drawCircle(240, 120, 40);

V5 Brain 螢幕的截圖顯示，中心畫有一個帶有細白邊框的圓圈。

drawImageFromFile #

使用儲存在 SD 卡中的影像檔案在 V5 Brain 螢幕上繪製影像。

Available Functions

bool drawImageFromFile(
  const char* name,
  int x,
  int y );

Parameters

範圍	類型	描述
`name`	`const char*`	SD卡上影像的檔案名稱。檔案必須具有 `.bmp` 或 `.png` 副檔名。
`x`	`int`	影像左邊緣的繪製位置的 x 座標，以像素為單位，範圍從 0 到 479。
`y`	`int`	影像頂部邊緣的繪製位置的 y 座標，以像素為 0 到 239 為單位。

Return Values

傳回布林值指示影像是否成功繪製：

true — 影像已成功載入並繪製到螢幕上。 4
false — 影像無法繪製（例如，檔案不存在或無效）

Notes

支援的圖像格式有： .bmp 和 .png。
影像檔案大小不得超過 512 KB。
- 建議使用 8 位元 RLE 編碼以最小化檔案大小。
支援的最大影像尺寸為 Brain 螢幕尺寸（約 479 x 239 像素）。
x 和 y 座標是相對於目前螢幕原點的，可以使用 setOrigin 進行更改。

Examples

// Draw a bmp file on the Brain's screen at coordinate 0, 0
Brain.Screen.drawImageFromFile("test_image.bmp", 0, 0);

render #

啟用大腦螢幕的雙緩衝功能。呼叫後，任何繪圖功能（例如文字、形狀或圖像）在專案剩餘時間內都不會立即顯示。相反，更新內容僅在再次使用渲染 render 才會顯示。這可以實現更流暢、更可控的螢幕更新，但意味著在 render 之前，螢幕內容將不可見。

Available Functions

1 — 啟用雙緩衝或將後緩衝區渲染到螢幕。
bool render();

2 — 將後緩衝區渲染到螢幕上，並可控制垂直同步行為和可選的調度程序執行。
bool render(
    bool bVsyncWait,
    bool bRunScheduler = true );

Parameters

範圍	類型	描述
`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`	可選 `true` （預設）— 允許在等待渲染時執行後台任務。 4 `false` — 不允許在等待渲染時執行後台任務。

範圍

類型

描述

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

可選

true （預設）— 允許在等待渲染時執行後台任務。 4
false — 不允許在等待渲染時執行後台任務。

Return Values

傳回布林值指示緩衝區中儲存的圖形是否已成功渲染到螢幕上：

true — 圖形已成功渲染到螢幕上。 4
false — 圖形無法渲染到螢幕上

Notes

調用 render 將需要 render 用於專案的其餘部分。

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();

pressing #

報告 V5 Brain 螢幕目前是否被按下。

Available Functions

bool pressing();

Parameters

此函數不接受任何參數。

Return Values

傳回布林值，指示螢幕目前的按下狀態：true — 螢幕目前被按下。或 false — 螢幕未按下。

Examples

// Change the screen's color after it's pressed
while (Brain.Screen.pressing() == false) {
  wait(5, msec);
}

Brain.Screen.setFillColor(green);
Brain.Screen.drawRectangle(0, 0, 479, 239);

// Display different messages after the screen is pressed
while (!Brain.Screen.pressing()) {
  wait(5, msec);
}
Brain.Screen.print("First message!");
Brain.Screen.newLine();

// Lift finger to press the screen again
while (Brain.Screen.pressing()) {
  wait(5, msec);
}
while (Brain.Screen.pressing() == false) {
  wait(5, msec);
}
Brain.Screen.print("Second message!");
Brain.Screen.newLine();

xPosition #

返回 V5 Brain 螢幕上最後一次按下按鈕的 x 座標。

Available Functions

int32_t xPosition();

Parameters

此函數不接受任何參數。

Return Values

傳回一個 int32_t 表示上次畫面按下的 x 座標，以像素為單位，範圍從 0 到 479。

Examples

// Display a circle where the screen is pressed
while (Brain.Screen.pressing() == false) {
  wait(5, msec);
}

Brain.Screen.drawCircle(Brain.Screen.xPosition(), Brain.Screen.yPosition(), 20, white);

yPosition #

返回 V5 Brain 螢幕上最後一次按下按鈕的 y 座標。

Available Functions

int32_t yPosition();

Parameters

此函數不接受任何參數。

Return Values

傳回一個 int32_t 表示上次畫面按下的 y 座標，以像素為 0 到 239 為單位。

Examples

// Display a circle where the screen is pressed
while (Brain.Screen.pressing() == false) {
  wait(5, msec);
}

Brain.Screen.drawCircle(Brain.Screen.xPosition(), Brain.Screen.yPosition(), 20, white);

pressed #

註冊一個在按下 V5 Brain 畫面時要呼叫的函數。

Available Functions

1 — 按下螢幕時呼叫函數。
void pressed(
    void (*callback)(void)
);

2 — 當螢幕被按下時呼叫函數，並將使用者定義的參數傳遞給回呼函數。
void pressed(
    void (*callback)(void*),
    void* arg );

Parameters

範圍	類型	描述
`callback`	`void (*)(void)`	螢幕按下時呼叫的函數。
`callback`	`void ()(void)`	螢幕按下時呼叫的函數，接收使用者定義的參數。
`arg`	`void*`	使用者定義的值，在螢幕被按下時傳遞給回調函數。

Return Values

此函數不傳回值。

Notes

每次按下大腦螢幕時，都會執行回調函數。
一次只能註冊一個回呼函數；呼叫 pressed 會替換之前的回呼函數。
回呼函數必須傳回 void。

Examples

定義回呼函數（在 int main()之外）

// Tracks how many times the screen is pressed.
void onScreenPressed(void* arg) {
  int* count = (int*)arg;
  (*count)++;

  Brain.Screen.clearScreen();
  Brain.Screen.setCursor(1, 1);
  Brain.Screen.print("Pressed %d times", *count);
}

在 int main()中註冊回呼函數

int main() {
  int pressCount = 0;

  // Register the callback and pass a value to update.
  Brain.Screen.pressed(onScreenPressed, &pressCount);

  while (true) {
    wait(20, msec);
  }
}

released #

註冊一個函數，當按下 V5 Brain 畫面後放開時，該函數將被呼叫。

Available Functions

1 — 按下螢幕後放開時呼叫函數。
void released(
    void (*callback)(void)
);

2 — 按下螢幕後放開時呼叫函數，並將使用者定義的參數傳遞給回呼函數。
void released(
    void (*callback)(void*),
    void* arg );

Parameters

範圍	類型	描述
`callback`	`void (*)(void)`	按下螢幕後放開時調用的函數。
`callback`	`void ()(void)`	螢幕按下後放開時呼叫的函數，接收使用者定義的參數。
`arg`	`void*`	使用者定義的值，在按下螢幕後釋放螢幕時傳遞給回呼函數。

Return Values

此函數不傳回值。

Notes

每次按下 Brain 螢幕後放開時，都會執行回呼函數。
一次只能註冊一個回呼函數；再次呼叫 released 會取代先前的回呼函數。
回呼函數必須傳回 void。

Examples

定義回呼函數（在 int main()之外）

// Tracks how many times the screen is released.
void onScreenReleased(void* arg) {
  int* count = (int*)arg;
  (*count)++;

  Brain.Screen.clearScreen();
  Brain.Screen.setCursor(1, 1);
  Brain.Screen.print("Released %d times", *count);
}

在 int main()中註冊回呼函數

int main() {
  int releaseCount = 0;

  // Register the callback and pass a value to update.
  Brain.Screen.released(onScreenReleased, &releaseCount);

  while (true) {
    wait(20, msec);
  }
}