Skip to content

Latest commit

 

History

History
179 lines (129 loc) · 5.1 KB

reference.md

File metadata and controls

179 lines (129 loc) · 5.1 KB

M5HtmlViewer Reference

M5HtmlViewerは、M5Stack/M5GFXの画面へ小さなHTMLサブセットを描画するArduinoライブラリです。ブラウザ互換のHTMLエンジンではなく、設定画面、ヘルプ、端末内ドキュメント、短い説明文を軽く表示するためのViewerです。

Include

#include <M5Unified.h>
#include <M5HtmlViewer.h>

Basic Usage

M5HtmlViewer viewer(M5.Display);

void setup() {
  auto cfg = M5.config();
  M5.begin(cfg);
  M5.Display.setRotation(1);

  viewer.setViewport(0, 0, M5.Display.width(), M5.Display.height());
  viewer.setPadding(8);
  viewer.render("<h1>Hello</h1><p>HTML subset rendering on M5Stack.</p>");
}

スクロールしたい場合は、スクロール量を更新してから再描画します。

scrollY += 20;
viewer.setScrollY(scrollY);
viewer.render(html);

Class

M5HtmlViewer(M5GFX& display)

描画先のM5GFXインスタンスを渡してViewerを作ります。M5Unifiedを使う場合は通常 M5.Display を渡します。

M5HtmlViewer viewer(M5.Display);

void setViewport(int16_t x, int16_t y, int16_t width, int16_t height)

描画領域を指定します。指定した矩形内を背景色で塗り、その内側にHTMLを描画します。

viewer.setViewport(0, 0, M5.Display.width(), M5.Display.height());

void setTheme(const M5HtmlViewerTheme& theme)

背景色、本文色、見出し色、リンク色などをまとめて指定します。

M5HtmlViewerTheme theme;
theme.background = TFT_BLACK;
theme.text = TFT_WHITE;
theme.heading = TFT_YELLOW;
theme.link = TFT_CYAN;
viewer.setTheme(theme);

void setPadding(uint8_t padding)

viewport内側の余白をピクセル単位で指定します。初期値は 4 です。

viewer.setPadding(8);

void setBaseTextSize(uint8_t size)

本文の基準テキストサイズを指定します。1 未満は 1 に丸められます。見出しはこの値を基準に大きく描画されます。

viewer.setBaseTextSize(1);

void setLineGap(uint8_t gap)

行間をピクセル単位で指定します。初期値は 3 です。

viewer.setLineGap(4);

void setScrollY(int16_t scrollY)

縦方向のスクロール量を指定します。負の値は 0 に丸められます。スクロール位置を変えたあとは render() を呼んで再描画してください。

viewer.setScrollY(40);
viewer.render(html);

int16_t contentHeight() const

最後に描画したHTMLコンテンツのおおよその高さを返します。スクロール上限の計算に使えます。

if (scrollY > viewer.contentHeight()) {
  scrollY = viewer.contentHeight();
}

void render(const char* html)

HTML文字列を描画します。描画前にviewport全体が背景色で塗り直されます。

viewer.render("<h1>Status</h1><p>Ready</p>");

void render(const String& html)

Arduino String を受け取るオーバーロードです。

String html = "<p>Hello</p>";
viewer.render(html);

Theme

M5HtmlViewerTheme は描画色をまとめた構造体です。

Field Default Use
background TFT_BLACK viewportの背景色
text TFT_WHITE 通常テキスト色
muted TFT_DARKGREY <small> の文字色
heading TFT_WHITE 見出し色
link TFT_CYAN <a> の文字色と下線色
rule TFT_DARKGREY <hr> の線色

Supported Tags

Tag Behavior
<h1> 大きな太字見出し
<h2> 中くらいの太字見出し
<h3> 中くらいの見出し
<p> 段落。前後に余白を入れる
<div> ブロック。段落に近い扱い
<section>, <article> ブロック。段落に近い扱い
<br> 改行
<hr> 横罫線
<b>, <strong> 太字風に描画
<i>, <em> 現時点ではスタイル状態のみ保持。見た目の変化は未実装
<small> 小さめ、控えめな色で描画
<a> リンク色と下線で描画。クリックイベントは未実装
<ul>, <ol> リストブロック。<ol> も現時点では箇条書きと同じ扱い
<li> 箇条書きの黒丸とインデント

Supported Entities

以下のHTMLエンティティをデコードします。

Entity Output
&amp; &
&lt; <
&gt; >
&quot; "
&apos; '
&nbsp; space

Current Limitations

  • CSSとJavaScriptは今後も対応しません。このライブラリは表示用HTMLサブセットのみを扱います。
  • 画像、テーブル、フォームは未対応です。
  • DOMは構築せず、入力文字列を読みながら描画します。
  • HTML属性は基本的に無視されます。href もクリック可能なリンクとしては扱いません。
  • 長い単語は単語単位で折り返すため、viewport幅を超えることがあります。
  • UTF-8文字列の表示可否はM5GFX側のフォント設定に依存します。