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

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

    [IStreamOut]
         ↑
      [ITerm]
         ↑
 [TWETerm_M5_Console]

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 定数

色設定以外の属性

文字色

背景色

本ライブラリのターミナル（コンソール）は、文字列ベースの画面を構成することを目的としてます。

以下に設計時の考慮事項を記載します。

• 固定幅の画面構成を行うこと

• 日本語の表示が可能であること

• ソースコード中に直接日本語文字列を含められるようにすること

  • UTF-8でソースコードを記述する前提とする

  • 内部処理をUnicodeとすること

  • UTF-8デコードが出来るようにすること

• 旧来のキャラクター型のインタフェースを実装できるよう、いくつかのエスケープシーケンスを実装しておくこと

  • ただしANSIエスケープシーケンスの完全な互換性を目的とはしない

• 文字色、背景色、太字といった表示属性に対応すること

• カーソルを表示・非表示にできること

• 画面の順方向のスクロールに対応すること

• カラム数を超えて文字列を出力した場合は、折り返しを行えること

  • 右端カラムへの文字出力を行った場合、その時点では折り返しを行わないようにすること

    • 上記を実装は、折り返し処理の実装より優先すること

• 複数のターミナル表示を画面上に同時に表示できること

• 毎回全画面書き換えといったような描画パフォーマンスの悪い実装でないこと

  • 変更がある行のみを書き換える行単位の描画を行うようにした

• フォントを選択できること

  • 配布可能なフォントをライブラリ内に同梱しておくこと

  • より大きな文字を表示するため、倍角表示に対応すること

本ライブラリのターミナルは、大まかに分けて２要素から構成されます。

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

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

メソッド

TWETerm_M5_Console - コンストラクタ

にdrawAreaと_M5のパラメータが追加されています。

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

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

例：

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

メソッド

refresh()

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

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

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

set_font()

フォントを指定します。

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

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

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

font_width(), font_height(), font_id()

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

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

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

set_color()

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

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

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

set_color_table()

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

例

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

ユーティリティ関数

color565()

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

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

メソッド

ITerm() - コンストラクタ

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

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

~ITrem() - デストラクタ

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

clear(), home(), clear_screen()

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

clear_line()

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

refresh(), force_refresh()

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

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

write()

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

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

get_height(), get_width()

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

move_cursor()

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

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

operator <<

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

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

フォントジェネレータ関数は、収録フォントごとに定義されています。関数パラメータは共通で、以下のようになります。

上記は東雲フォント16ドット版（常用漢字収録）のジェネレータの例です。

idは、ユーザが指定するフォントID。

line_spaceはフォントの行間スペースをピクセル数で指定します。

char_spaceは文字間スペースでピクセルで指定します。文字間スペースはシングル幅のフォントの指定です。ダブル幅のフォントの場合は倍になります。

u32Optは、フォントのオプションを指定します。オプションはU32_OPT_FONT_TATEBAIとU32_OPT_FONT_YOKOBAIがあり、論理和で指定します。

フォントジェネレータの戻り値はFontDef&になっています。この戻り値はライブラリ内部のフォント管理テーブルに生成されたオブジェクトへの参照です。既に登録済みのIDであるばあいは、そのIDに対して上書きを行います。登録できなかった場合は.is_default()メソッドがtrueになるデフォルトフォントが返されます。

フォントをスクリーン上に描画します。

以下の例では、Bボタンを押すたびに、事前に生成したフォントID=10のフォントを用いて固定の文字列を描画します。

関数定義

fontを用い、左上座標(x,y)に、文字色fg、背景色bg、オプションoptで文字を描画します。

uint16_t cをパラメターとして与えた場合は、Unicode c に対応する文字を１文字描画します。

const char *sをパラメータとして与えた場合は、sをUTF-8としてデコードし、文字列として出力します。

const uint16_t* sをパラメータとして与えた場合は、Unicode文字列として描画します。

optはオプションのビットマップです。以下の指定が可能です。

• 0x01 - 太字指定

• 0x02 - カーソルの描画

戻り値は、描画が行われればX(幅)方向に描画したピクセル数を返し、エラーなどが発生したときは0を返します。

実装について

実装時では以下のM5StackのAPIを利用しています。

• M5.Lcd.startWrite()

• M5.Lcd.setWindow()

• M5.Lcd.endWrite()

• tft_Write_16()

namespace TWEFONT には、フォントの定義やフォント描画のための手続きをまとめています。

フォントの生成

フォントはFontDefクラスにより管理されます。フォントごとに用意されるFontDefクラスオブジェクトのジェネレータ関数により生成され、ライブラリ内部で生成時に指定したフォントIDと紐づけて管理されます。フォントは最大７つまで定義できます。フォント作成時に字間・行間・倍角を指定することができます。同じフォントに対して複数のフォントIDの登録が可能です。

下記の例では、フォントID 10 に16ドットの東雲フォント（縦倍角・横倍角指定）を、フォントIDを11に同じフォントですが倍角指定なし、行間を１ピクセルとしたフォント定義を行います。

コンパイル時に、ジェネレータ関数createFont???()を呼び出されたフォントのデータがリンクされます。

フォントデータについて

本ライブラリには、作者が事実上パブリックドメイン（著作権等取扱はソースヘッダに含まれるクレジットを参照ください）を宣言しているフォントをいくつか含めています。

本ライブラリに含めるにあたって、以下の調整を行っています。

• 大本がBDF形式を変換し、描画ルーチンに適したデータ構造とした

• これらフォントをUnicodeとして取り扱うための参照テーブルを用意した

• latin1補助文字 U+00A0～u+00FFについて、フォント定義があるものについては収録した

• JIS X201 半角カナ U+FF61～U+FF9F について、フォント定義があるものについては収録した

• 常用漢字（2645 文字）のフォントデータと、全収録（東雲フォントのみ、一部未収録字形があります）を用意した

日本語フォントのジェネレータ

ジェネレータ関数createFont???()には収録文字数に応じて３種類のジェネレータを用意しています。文字セットの生成は{MWM5ライブラリ}/fontsフォルダにあるスクリプトによって行います。

東雲フォント (12,14,16ドット)

12,14,16ドット版をライブラリに含めています。

常用漢字のみのジェネレータ (createFontShinonome12???(), createFontShinonome14???() , createFontShinonome16???())を呼び出します。

MP+フォント (10ドット, 12ドット)

ジェネレータ createFontMP10???()または createFontMP12???() を呼び出します。

8x6 LCD フォント

ジェネレータ createFontLcd8x6() を呼び出します。

latin拡張文字や日本語フォントは含まれません。

このフォントはいずれかのジェネレータ関数createFont???()が呼び出されたときに、デフォルトとしてフォントID=0に登録されます。

フォントIDについて

フォントIDは作成したフォントごとに割り当てられます。

IDは 0..32 の値を指定可能ですが、ユーザが登録できるのは 1..32 で最大７フォント登録できます。

ID=0 のフォントは 8x6 LCD フォントに割り当てられます。

フォント情報の取得

ターミナルでの使用

フォントの描画について

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

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

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

フォント定義と関連する手続きをまとめたクラスです。

このクラスオブジェクトはフォントジェネレータによりライブラリ内部で生成・管理され、ユーザがコンストラクタを用いて直接オブジェクトを生成することはありません。

メソッド（ユーザ利用）

get_width()

パラメータを省略した場合は、フォントのシングル幅文字の幅を返します。この値にはフォント生成時に指定した文字間スペースも含まれます。

wcを指定した場合は、Unicode wcに対応するフォントの幅を返します。日本語などダブル幅のフォントの場合は、シングル幅の２倍の値が戻ります。

get_height()

フォントの高さを返します。この値にはフォント生成時に指定した行間スペースも含まれます。

is_default()

デフォルトフォントのオブジェクトである場合 true を返します。

get_font_code()

フォントIDを取得します。

メソッド（内部利用）

find_font_index()

Unicode c に対応する、ダブル幅フォント定義配列インデックスを検索します。

戻り値は、字形データが存在する場合は、インデックス配列のインデックス（データ配列のインデックスが計算できる）、存在しない場合は-1を返します。

フォント定義は、インデックス配列、データ配列の２つから構成されます。インデックス配列の各値は昇順に並んだ Unicode になっていて、データ配列のインデックスに対応しています。

以下の例ではインデックス配列の IDX=829 が U+5a2f で "娯" という文字です。データ配列の対応する番地を参照すれば、この字形データが格納されています。

インデックス配列内の値は昇順に並ぶよう構成した目的は、本関数で実装されている二分探索を利用するためです。

createFont???() によりフォント生成したクラスオブジェクトを参照します。

関数定義

const FontDef& queryFont(uint8_t id)

idにはフォント生成時に指定したフォントIDを指定します。

戻り値は FontDef& で、ライブラリ内のフォント管理配列内に格納されたオブジェクトへの参照です。

idに0を指定すると、フォントID=0のデフォルトフォントを戻します。存在しないIDを指定した場合も、どうようにデフォルトフォントを戻します。FontDefオブジェクトがデフォルトフォントかどうかはメソッド.is_default()により判定できます。