events.lua で利用できる API の説明

テーマを構成する events.lua について説明する。

events.lua は、以下の関数を提供しなければならない。
これらの関数は、アプリ側から呼び出される。

• initialize_theme()
  • テーマ読み込み後に１度だけ呼び出される。
• restart_theme()
  • 入力などでテーマがクリアされた後、再びテーマが実行するときに呼び出される。
  • initialize_theme() の後に、テーマがクリアされなければ、この関数は呼び出されない。
    • 必要ならば initialize_theme() から restart_theme() を呼び出すこと。
• window_rects_changed()
  • ウィンドウ情報に変更があれば呼び出される。
• add_actor(actor, args)
  • actor が作成されたときに呼び出される。
• remove_actor(actor)
  • actor が削除されるときに呼び出される。
• update_actor(actor)
  • false を返すと、この actor は削除される。
    • 削除時には remove_actor() が呼び出される。
    • actor を削除しない場合には true を返すこと。
  • 現状では 25 ms 毎に呼び出される。
  • 基本的に、ms 単位の時間を要する処理を行ってはならない。

また、上記の Lua の関数内では、以下の関数を利用できる。

• RectF クラス
  • rect = RectF:new(x, y, width, height)
    • x, y, width, height を登録した rect オブジェクトを返す。
  • x = rect:x()
  • y = rect:y()
  • w = rect:width()
  • h = rect:height()
    
    
• PointF クラス
  • point = PointF:new(x, y)
    • x, y を登録した point オブジェクトを返す。
  • x = rect:x()
  • y = rect:y()
    
    
• actor のメソッド
  • actor:id()
    • actor 毎に一意の値を返す。
  • actor:set_data(key, value)
  • actor:data(key)
    • key 文字列に対応した value 文字列を登録できる。
    • value に数値を登録するには actor:set_data(key, "" .. value) と書ける。
      • 登録した数値を読み出すには actor(key) + 0 と書ける。
  • actor:set_cell(cell_name)
    • resource.yaml に登録してあるセル名の描画を指示する。
    • 空文字("")を渡すと、背景画像のみ描画します。
  • actor:set_cell_degree(degree)
    • 描画中のセルの角度を degree 単位系で指定する。
  • actor:set_position(x, y)
    • セルの描画位置を指定する。
      • セルの左上のスクリーン位置を x, y で指定する。
      • 画面の左上が (0, 0) であり、右側と下側が正の方向とする。
  • actor:raise_cell()
    • セルを最前面に配置する。
  • actor:set_message_from_position(x, y)
    • セリフの吹き出し元を配置する位置を Actor の位置との相対座標で指定する。
  • actor:set_message_from(from)
    • セリフの吹き出し元どこに配置するかを指定する。
    • from には Theme_widget.From_bottom, Theme_widget.From_right, Theme_widget.From_left が指定できる。
  • actor:set_message(message, sec)
    • メッセージを表示する。
      • message には UTF-8 文字列が指定できる。
      • sec には、表示する秒数を指定する。
  • actor:set_stay_on_top()
    • セルを常に最前面に描画したい場合に呼び出す。
  • actor:set_balloon_stay_on_top()
    • メッセージの表示を常に最前面に描画したい場合に呼び出す。
  • actor:remove()
    • actor を削除したい場合に呼び出す。
      
      
• os_name()
  • OS に応じて "Windows", "Linux", "Mac", "unknown" の文字列を返す。
• rect = window_root_rect()
  • ルートスクリーン情報を RectF で返す。
• n = window_rects_size()
  • ウィンドウの数を返す。
  • 透明なウィンドウや、最前面に表示するよう指示されているウィンドウは含まれない。
• rect = window_rect(index)
  • 前面から index 番目にあるウィンドウの情報を RectF で返す。
• rect = window_rect_focused()
  • フォーカスのあるウィンドウの情報を RectF で返す。
• point = cursor_position()
  • カーソル位置を PointF で返す
• id = create_actor(is_counted, args)
  • アクターの作成を指示する
  • is_counted は「描画するマスコット数」に含める actor を作成する場合は true, それ以外の場合には false を指定すること。
  • args には add_actor(actor, args) に渡される args を登録できる。
• actor = actor_by_id(id)
  • id で指定された actor を返す。
  • 存在しない場合には nil が返される。
• n = max(a, b)
  • a, b の大きい方の値を返す。
• n = min(a, b)
  • a, b の小さい方の値を返す。
• set_data(actor, key, value)
  • value に数値を渡せるようにした actor:set_data(key, value) と等価。
• visible_ground_lines(rects)
  • 可視であるウィンドウ上端の直線を返す。
  • 直線は { x, y, length } のキーを持つテーブルで返され、左側の x, y 座標と長さで表現される。
• option_set_mascot_size_enabled(enable)
  • 設定フォームの「デスクトップに描画するマスコット数」の enable / disable を指定できる。