namesace TWETERMはターミナル（コンソール）画面を実装するためのクラスや関数などをまとめています。

基本的なクラス構造は以下のようになっています。クラスITermではターミナルの文字列バッファとその処理、TWETerm_M5_ConsoleクラスはITermの文字列描画部分を実装したものです。IStreamOutはITerm派生クラスオブジェクトが文字列をターミナルに投入するための基本的な手続きを提供しています。

    [IStreamOut]
         ↑
      [ITerm]
         ↑
 [TWETerm_M5_Console]

M5Stack の 320x240 LCD 用のターミナルの実装です。ITermを実装しています。

本クラスはnamespace TWEARD内に定義されます。

メソッド

TWETerm_M5_Console - コンストラクタ

TWETerm_M5_Console(
			uint8_t u8c, uint8_t u8l,
			Rect drawArea, M5Stack& _M5)

TWETerm_M5_Console(
			uint8_t u8c, uint8_t u8l,
			TWETERM::SimpBuf_GChar* pAryLines, TWETERM::GChar* pBuff,
			Rect drawArea, M5Stack& _M5)

ITermのコンストラクタにdrawAreaと_M5のパラメータが追加されています。

drawAreaは、LCD内のターミナル描画エリアを決めます。Rect構造体で指定しx,y,w,hを指定します。(x,y)は領域の左上の座標、(w,h)は領域の幅と高さです。

_M5は、M5Stackのグローバルインスタンス M5を指定します。

例：

TWETerm_M5_Console the_screen(64, 20, { 0, 16, 320, 192 }, M5);

カラム最大値を64、行数の最大値を20、左上座標を (0, 16)、領域サイズを (320, 192) として the_screen オブジェクトを構築します。

メソッド

refresh()

ITerm::refresh()の実装です。この関数により画面の描画を行います。loop()関数内で定期的に呼び出します。

本実装では、パフォーマンスの向上のため、原則として描画変更の必要にある行のみを上書きします。画面全領域を再描画したい場合はforce_refresh()メソッドを呼び出します。

以下の例では32msごとに描画を行います。

void loop() {
		static uint32_t u32mills;

		uint32_t u32now = millis();
		if (u32now - u32mills > 32) {
			the_screen.refresh();

			u32mills = u32now;
		}
}

set_font()

void set_font(uint8_t u8id, uint8_t u8col_request = 0, uint8_t u8row_request = 0)

フォントを指定します。

u8idはフォントIDを指定します。

u8col_requestは、設定したいカラム数を指定します。指定した数値が領域サイズに対して大きい場合は指定領域に入るように値が丸められます。0を指定した場合は、領域サイズから計算できる最大のカラム数に設定されます。

u8row_requestは、設定したい行数を指定します。指定した数値が領域サイズに対して大きい場合は指定領域に入るように値が丸められます。0を指定した場合は、領域サイズから計算できる最大の行数に設定されます。

font_width(), font_height(), font_id()

uint8_t font_id()
uint8_t font_width()
uint8_t font_height()

font_id()は、指定したフォントのIDを返します。

font_width()は、指定したフォントの幅をピクセル数で返します。ダブル幅のピクセル数は、この値の２倍になります。

font_height()は、指定したフォントの高さをピクセル数で返します。

set_color()

void set_color(uint16_t color, uint16_t bgcolor = 0)

ターミナルの文字色と背景色を指定します。

colorは文字色を指定します。

bgcolorは背景色を指定します。

uint16_t c = color565(255, 127, 0); // R:255, G:127, B:0

set_color_table()

void set_color_table(const uint16_t* ptbl)

ターミナルで使用できる８色のテーブルを指定します。ptblはuint16_t型の配列で８つの要素が必要です。

例

static const uint16_t COLTBL_MAIN[8] = {
	BLACK,
	RED,
	GREEN,
	YELLOW,
	color565(127, 127, 255), // BLUE,
	color565(255, 0, 142), // MAGENTA,
	CYAN,
	ALMOST_WHITE
};

the_screen.set_color_table(COLTBL_MAIN);

上記の例では青とマゼンダの色調を変えたテーブルを指定し、ターミナルオブジェクト the_screenに指定しています。

ユーティリティ関数

color565()

constexpr uint16_t color565(uint8_t r, uint8_t g, uint8_t b)

r, g, b を指定して、565形式の色コードを生成します。

ITerm型のターミナルオブジェクトに対して、<<演算子を用いてターミナル属性を指定するヘルパークラス。

void putmsg(ITerm& trm, const char *msg) {
    trm << TermAttr(TERM_COLOR_FG_RED | TERM_BOLD);
    trm << msg;
    trm << TermAttr(TERM_ATTR_OFF);
}

上記の例では、出力ターミナルをtrmに対して、文字色を赤で太字にしてmsgを出力し、属性をクリアします。

TermAttr() - コンストラクタ

TermAttr(GChar::tAttr attr = 0)

attrをパラメータとします。attrは後述のGChar::tAttr 定数一覧で指定します。

指定は以下の組み合わせになります。

• TERM_ATTR_OFF (すべての属性のクリア)

• 以下の論理和

  • TERM_BOLD

  • TERM_REVERSE

  • 文字色のいずれか

  • 背景色のいずれか

GChar::tAttr 定数

色設定以外の属性

文字色

背景色

ターミナル（コンソール）の基底クラスで、画面上の文字列を管理する。このクラスは、実際の画面描画についての手続きは含まれず、このクラスを継承したサブクラスによって画面描画を実装します。

メソッド

ITerm() - コンストラクタ

ITerm(uint8_t u8c, uint8_t u8l)
ITerm(uint8_t u8c, uint8_t u8l, SimpBuf_GChar* pAryLines, GChar* pBuff)

カラム数u8cと行数u8lを指定して、ターミナルを構築する。カラム数と行数はターミナルで管理できる最大の値を指定する。ターミナルのサイズ変更を行った場合でも各々の最大の値を超える変更は行われない。

pAryLinesとpBuffを指定する場合は、ITerm内でのメモリ確保は行われず、外部で確保済みの配列を利用する。

// 静的メモリ確保例
const uint8_t U8COL = 64;
const uint8_t U8LINE = 20;
static TWETERM::GChar screen_buf[U8COL * U8LINE];   // pBuff
static TWETERM::SimpBuf_GChar screen_lines[U8LINE]; // pAryLines

~ITrem() - デストラクタ

virtual ~ITerm()

動的にメモリを確保した場合は、そのメモリ領域を破棄します。

clear(), home(), clear_screen()

void clear()
void home()
void clear_screen()

clear()は画面バッファのクリア、home()はカーソル位置をホームポジションに移動、clear_screen()は両者を実行します。

clear_line()

void clear_line(uint8_t line, bool fill_blank = false)

指定行をクリアする。fill_blankをtrueにすると指定行を空白で埋める。

refresh(), force_refresh()

virtual void refresh() = 0
void force_refresh()

サブクラスにより実装される画面更新描画のためのメソッドです。描画方法は２種類あり、メンバー変数u32Dirtyに定義されるビットマスクに対応した行のみを再描画するものと、force_refresh()メソッドによる画面全体を再描画するものがあります。

画面全体の再描画では、いったん背景を背景色で塗りつぶしてから再描画します。初回の描画ではforce_refresh()を行うようにしてください。

write()

ITerm& write(wchar_t c)
ITerm& write(char_t c)

ターミナルに１文字書き出します。カーソル位置に文字を書き出します。16bit wchar_t型のUnicodeを渡します。

char_t (char) 型のパラメータを渡した場合は、入力をUTF-8として取り扱います。例えば0x7F までのASCII文字はそのままwrite(wchar_t)が呼び出され、３バイトのUTF-8エンコードされた日本語文字は、連続して３バイトを投入した時点でwrite(wchar_t)が呼び出されます。

get_height(), get_width()

uint8_t get_height() // 行数
uint8_t get_width()  // カラム数

ターミナルの行数、カラム数を返す。

move_cursor()

ITerm& move_cursor(uint8_t cols, uint8_t lines)
ITerm& operator ()(int cols, int lines)

//例
the_screen(1, 3) << "HELLO"; // 2カラム目、4行目に移動して HELLO を出力

カーソル位置を指定場所に移動する。

戻り値はITerm&（自身）で続けて出力メソッドなどを記述できる。

operator <<

ITerm& operator << (const char *s)
TWE::IStreamOut& operator << (TWE::IStreamSpecial& sc)
TWE::IStreamOut& operator << (ITerm& t, char_t c)
TWE::IStreamOut& operator << (ITerm& t, wchar_t c)
TWE::IStreamOut& operator << (ITerm& t, int i)
TWE::IStreamOut& operator << (ITerm& t, TermAttr a)
TWE::IStreamOut& operator << (TWE::IStreamOut& t, TermAttr a)

<<演算子を用いてターミナルに文字列を書き出します。

メソッド (サブクラス実装用)

エスケープシーケンスは ESC 文字 '\033' で始まり何文字かで完結する制御コードです。

本ライブラリが動作するプログラム上や、シリアルポートの先にあるマイコンから制御文字をターミナルに投入することで、様々な画面制御（画面のクリア、カーソルの移動、色などの表示属性の変更）を行うことが出来ます。

以下に対応するエスケープシーケンスを記述します。表中の ESC はエスケープ文字 '\033'、イタリックの n や m は数字の入力です。