独自のインターフェースを備えたXBMC用のプラグインの作成：パートI-理論と最も単純な例

エントリー

これは、独自のインターフェースを備えたXBMCのプラグインの作成に関する一連の記事の第1部です。 プラグインインターフェイスの作成に関する基本的な情報と、簡単な例を示します。

パートIIでは、もう少し理論と少し複雑な例を示します。

パートIIIでは、インターフェイスのレイアウトを簡素化するマイクロフレームワークを紹介します。



私の最初の記事「 単純なXBMCプラグインの詳細な構造」 では、XBMCのプラグインの構造を可能な限り詳細に説明しようとしました。 さらに、プラグインのコンテンツソースとプラグインスクリプトがどのように異なるかを説明しようとしました。 忘れてしまった方のために、addDirectoryItem（）関数を使用して、コンテンツソースプラグインがコンテンツのマルチレベルリスト（ディレクトリ）を形成することを思い出させてください。 つまり、リストアイテムの機能を順次「フィード」し、残りのすべて（リストの表示、リストアイテムの選択時のイベントの処理など）がXBMCで実行されます。 同様に、プラグインスクリプトはそのような特権を奪われており、その中で言及されているすべてのタスクは開発者が負担します。 また、ソースプラグインのように、指定されたコンテンツでいくつかのタスクを実行する場合、「ビデオ」、「音楽」、および/または「写真」セクションにスクリプトを表示できること、またはこれらは汎用スクリプトプラグインです。 さらに、スクリプトプラグインは、字幕をダウンロードしたり、バックグラウンドサービスとして動作したりすることもできます。プラグインの機能は、プラグインに関するすべての情報を含むAddon.xmlファイル内のタグによって決定されます。



残念ながら、独創的なアイデアは私を訪問していないので、これらの記事の例は本質的にやや抽象的で理論的です。 役に立つ何かを書くためにこの情報を使用することはあなたに任せます。



これらの記事を理解するには、OOPの原則とPython（以下-Python）でのGUIアプリケーションの作成の原則に関する十分な知識が必要です。

一般的な情報

XBMC Python APIの一部であるxbmcguiモジュールは、インターフェースの操作を担当します。 このモジュールには、一般的なコンテナクラスと、さまざまなインターフェイス要素を担当するクラスが含まれています。 残念ながら、インターフェースを担当するAPIの部分は、GUIの従来のPythonライブラリよりも便利ではなく、ドキュメントも不正確です。 以前の記事で書いたスタブモジュールの使用をお勧めします 。 開発の利便性に加えて、クラス、メソッド、関数のセット、およびそれらの使用（ドックストリング）の両方に関する関連情報も含まれています。

プラグインインターフェイスコンポーネント

プラグインインターフェイスを作成するために、xbmcguiモジュールはさまざまなコンポーネントを提供します。

-コンテナクラス（Windowクラスとその子孫）;

-ウィジェット、またはXBMC用語では、さまざまなインターフェイス要素（コントロールの下位クラス）を担当するコントロール。

-情報を表示し、ユーザーと対話するために使用されるダイアログ（Dialogクラスなどのメソッド）。



最初の2つのポイントをより詳細に検討してください。

WindowXMLおよびWindowXMLDialogクラス

名前が示すように、これらのコンテナクラスは、XBMCスキンと同様の構造を持つXMLスケルトンインターフェイススケルトンを使用します。 つまり、実際には、これらのクラスに基づいたインターフェイスには独自のミニスキンがあります。 私はスキンライティングのジャングル（私はほとんど知らないことを認めます）を掘り下げたくないので、これらのクラスにこだわることはありません。

WindowおよびWindowDialogクラス

WindowおよびWindowDialogクラスは、他のインターフェイス要素（コントロール）をホストする親コンテナーです。 コントロールを配置するために、これらのクラスは画面の左上隅から始まる座標グリッドを提供します。 デフォルトでは、グリッドの表示領域の解像度は1280 x 720ピクセルです。 この解像度は変更できますが、個人的にはあまり意味がありませんので、例では可視領域の標準解像度を使用します。 「可視領域」という用語を使用したのは何の理由でもありません。 コントロールの座標は、負の値を含む任意の値を持つことができますが、画面に表示されるのは表示領域に収まるものだけです。 これは、たとえば、明らかに可視領域を超える座標（たとえば、-5000、-5000）を設定することにより、ある種のコントロールを一時的に隠すために使用できます。

注意：座標グリッドの可視領域の解像度と画面解像度を混同しないでください。 表示領域は、実際の画面解像度と同じ解像度を持っているため、実際の解像度に関係なく、インターフェイス要素は常に同じ縮尺を持ちます。



WindowクラスとWindowDialogクラスの違いは、Windowクラスの背景が黒く不透明であり、ビデオ再生ウィンドウまたは音楽視覚化ウィンドウの下で非表示にできることです。 WindowDialogの背景は透明になり、そのコントロールは常にXBMCインターフェイスの他の要素の上に表示されます。 したがって、プラグインがビデオを再生し、音楽を再生する場合、そのためにWindowクラスを使用することをお勧めします。他の場合、クラスの選択はプラグインの個人的な好みとタスクに依存します。



インターフェイスイベントを処理するために、両方のクラスにonAction（）およびonControl（）メソッドがあります。 1つ目はキーボードコマンドをインターセプトし、2つ目はアクティブ化されたコントロールです。 したがって、ユーザーとの対話を保証するために、これらのメソッドは、適切なイベントハンドラを記述して、プラグインのインターフェイスを実装する子クラスで定義する必要があります。

注意！ デフォルトでは、onActionメソッドはBACKSPACEおよびESCキーに対応するキーボードコマンドを「キャッチ」し、closeメソッドを呼び出します（プラグインを終了します）。 したがって、このメソッドが子クラスでオーバーライドされる場合、このクラスのプラグインを終了するためのコマンドを少なくとも登録する必要があります。 それ以外の場合、XBMCを強制的に停止（「強制終了」）することによってのみプラグインを終了できます。これは、組み込みシステム（OpenELECなど）で問題になる可能性があります。

コントロール

次に、コントロールについて詳しく説明します。 すべてのコントロールについては説明しませんが、私が個人的に研究したものについてのみ説明しますが、ほとんどのタスクには十分だと思います。 コントロールは、プラグインのインターフェース要素（ウィジェット）です。 ただし、汎用GUIフレームワーク（Tkinter、PyQt）のウィジェットとは異なり、コントロールはインターフェイス要素の「スケルトン」のようなものです。 ビジュアルデザインのコントロールには、画像（テクスチャ）を含むグラフィックファイルが必要です。



フォトジャックグラフィックプログラムに精通している人は自分でテクスチャを描画でき、他のプラグインはXBMCスキンリソースに必要なテクスチャファイルを取り込むことができます。 残念ながら、完成したスキンでは、テクスチャが特別な形式でパックされているため、スキンのソースコードが必要です。 画像を含む標準のXBMCスキン、Confluenceのソースは、 ここにあります 。

注：一部のコントロール（ボタンなど）は、現在のスキンの必要なテクスチャを自動的に使用できますが、この動作に依存することはできません。 第一に、すべてのコントロールがこれを実行できるわけではありません。第二に、別のスキンに切り替えると、プラグインの外観に違反する可能性があります。 したがって、コントロールのテクスチャファイルを明示的に指定することをお勧めします。



上記から推測できるように、独自のインターフェイスでプラグインを作成する場合、2つのアプローチを使用できます：シンプル、プラグインの外観がすべてのスキンで同じ外観を持つ、および複雑な、ウィジェットのテクスチャファイルが現在のスキンに応じて選択される、プラグインインターフェイスがスキンと同じスタイルでスタイル設定されるようにします。 広大さを把握できないことは明らかなので、2番目のアプローチでは、いくつかの人気のあるスキンに制限し、残りの部分にはデフォルトのレイアウトを使用する必要があります。



以下は、主要なインターフェイスコントロールの簡単な説明です。

コントロールラベル

背景が透明なシンプルな碑文。 テクスチャは使用しません。 これは、TkinterのLabelクラスまたはPyQtのQLabelの完全な類似物です。 テキストの配置は、次の数値定数のいずれかで指定されます。

ALIGN_LEFT = 0 ALIGN_RIGHT = 1 ALIGN_CENTER_X = 2 ALIGN_CENTER_Y = 4 ALIGN_CENTER = 6 ALIGN_TRUNCATED = 8 ALIGN_JUSTIFY = 10
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

念のため、実際のプラグインでは、この情報およびテキスト情報を表示する他のコントロールのテキスト文字列は、Addon.getLocalizedString（）メソッドを使用して言語ファイルから取得するのが最適であり、プラグインのインターフェースが現在のXBMC言語設定と一致することを思い出させてください。

ControlFadeLabel

ControlLabelの類似物で、唯一の違いは、長すぎる行が自動的にスクロールすることです。

ControlTextBox

自動改行付きの長いテキストを含む可能性のあるテストウィンドウ。 スクロールは行われず、テキストボックスに収まらないテキストはトリミングされます。

ControlImage

写真。 メインの画像ファイル形式がサポートされています（jpg、png、gif）。 pngおよびgifファイルは、透明度とアニメーション（ある場合）をサポートします。 デフォルトでは、画像は指定された場所に収まり、比率がゆがみますが、その方法は設定できます。 残念なことに、次に画像を変更するときには、適合オプションは機能しません。

コントロールボタン

ボタン。 ボタンクリックハンドラは、コンテナクラスのonControl（）メソッドに登録されます。

ControlRadioButtonおよびControlCheckMark

ラジオボタンとチェックボックス（「チェックマーク」）。 機能的に完全に類似しており、外観のみが異なります。 2状態スイッチとして使用されます。 テクスチャが必要です。

コントロール編集

テキストを入力するためのフィールド。 選択すると、画面上のキーボードが開き、目的のテキストを入力できます。 パラメーターisPassword = Trueを指定すると、入力したテキストはアスタリスクに置き換えられます。

制御リスト

リスト。 単純なテキスト文字列をリストに追加できますが、実際には、リスト内の各アイテムはListItemクラスのインスタンスです。 プラグインコンテンツソースのリストは同じ要素で構成されていることを思い出させてください。 ただし、ソースプラグインとは異なり、ControlListのリストアイテムの機能は制限されています。 実際、テキストラベルと小さなアイコン（thumbnailImage）のみがサポートされています。 リストアイテムを選択するときのアクションなど、残りのロジックはすべて、自分で実装する必要があります。 リストをスタイルするには、コントロールにテクスチャが必要です。



すべてのリスト項目が指定されたスペースに収まらない場合、リストがスクロールします。

コントロールスライダー

スケール付きのスライダー。 パラメータのスムーズな調整に役立ちます。 明示的なテクスチャが必要です。



Confluenceのスキンテクスチャを使用して設計されたコントロールの例は、以下のスクリーンショットで見ることができます。







ControlButton、ControlRadioButton、ControlEdit、ControlList、およびControlSliderは、選択すると外観が変化するインタラクティブな要素です。 理論的には、ControlLabelなどの任意のコントロールを選択できますが、視覚的なフィードバックはありません。



キーボードまたはリモコンの矢印キーを使用してプラグインインターフェイスをナビゲートするには、対応する矢印キーを押したときにフォーカスが移動するネイバーを各コントロールに割り当てる必要があります。 これを行うには、setNavigationメソッド、およびControlから継承されたcontrolUp、controlDown、controlLeft、controlRightを使用します。

また、ナビゲーションを機能させるには、インターフェイスの初期表示中に、いずれかのコントロールにフォーカスを設定することを忘れないでください。



コントロールは、コンテナクラスのaddControlメソッドを使用して追加されます。 同時に、後で追加されたコントロールは、以前に追加されたコントロールの上に表示されます。 たとえば、背景として機能する画像を最初に表示し、他のすべてのコントロールをその上に配置できます。



注意：ほとんどすべてのコントロールには、プラグインの実行中にプロパティ（テキスト、画像など）を変更できるメソッドがあります。 したがって、addControlメソッドを使用してこのコントロールをコンテナクラスに追加した後は、常にコントロールプロパティ（たとえば、setLabel（ 'Some Text'）を使用してControlLabel碑文を変更します。「非バインド」コントロールのプロパティを変更しようとしても、何も起こりません。 、最悪の場合、XBMCインターフェースのあらゆる種類の興味深い不具合が発生する可能性があります。



それでは、実際の例に移りましょう。 もちろん、古典的な「Hello、World！」、またはロシア語版の「Hello、world！」から始めましょう。

プラグイン「Hello world！」

最初の記事で述べたように、プラグインごとに必要なユーティリティファイルaddon.xmlが必要です。





行

 <extension point="xbmc.python.script" library="default.py"> <provides>executable</provides> </extension>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

彼らは、これが「プログラム」セクションで利用できるソフトウェアプラグインスクリプトであることを私たち（およびXBMC）に伝えます。



プラグインのコードを直接：





さらに簡単な分析。主要な点はすでにコードへのコメントで示されているため。 行番号を表示するには、メモ帳++などの適切な機能を備えたテキストエディターを使用します。



行8、9：ここでは、XBMCで使用されるキーボードイベントの数値コードに対応する定数を設定します。 キーボードイベントの完全なリストは、 XBMCソースコードにあります 。 キーボードイベントとキーボード、リモートコントロール、またはその他のコントロールのキーの対応は、 keyboard.xml構成ファイルで設定されます。



13-25：インターフェースを実装するクラスを記述します。 この場合、クラスはWindowを継承します。 インターフェースには、対応する碑文を持つControlLabelという単一のコントロールが含まれています。 コントロールの最初の4つのパラメーターは、座標グリッドの幅と高さの座標と寸法（ピクセル単位）であることに注意してください。 これらのパラメーターは必須です。 必要に応じて、座標と寸法を後で変更できます。 コントロールを作成するが、その表示を延期する場合、架空の座標やサイズを指定し、コントロールが表示された後に実際のパラメーターを設定できます。

親クラスのaddControl（）メソッドは、コンテナにコントロールを追加する役割を果たします。



onActionメソッドでは、プラグインを終了できるようにするために、ESCキーとBackspaceキーに対応するキーボードイベントをインターセプトします。 繰り返しになりますが、onActionメソッドが子クラスでオーバーライドされる場合、プラグインには、タスクマネージャーなどの過激な手段に頼らずに終了できるコードが必要です。

注：整数との比較にもかかわらず、actionパラメーターは実際にはActionユーティリティークラスのインスタンスです。



32：doModal（）メソッドは、作成したインターフェースを画面に表示します。 このメソッドは、Tkinter.Tkのmainloop（）またはQDialogのexec_（）に似ています。 インターフェイスは、close（）メソッドが呼び出されるまで表示されます。

doModal（）に加えて、show（）を使用できます。 この場合、プラグインの実行中またはclose（）が呼び出されるまで、インターフェイスが表示されます。 show（）を使用する場合、イベントループの構成は完全にプログラマーに委ねられます。



34：仕事の終わりにクラスインスタンスを削除する理由は正直なところわかりません。 これは公式のWiKiの例で見ました。



すべてが正しく行われている場合は、表示されるはずです





同意しますが、あまり魅力的な光景ではありません。 前述のように、Windowクラスには黒い不透明な背景があります。 そのため、次の例では、いくつかのインタラクティブな要素を追加するだけでなく、インターフェイスをわずかに装飾しようとします。



好奇心のために、WindowDialogから継承してみてください。 このオプションを使用すると、ラベルがXBMCインターフェイスの上部に表示されます。



Readyプラグイン「Hello world！」は、こちらからダウンロードできます 。 メニュー「システム」>「アドオン」>「ZIPファイルからインストール」からプラグインをインストールできることを思い出させてください。 すべての新しいプラグインは、ユーザー設定フォルダーの\アドオンフォルダーにインストールされます。 Windowsでは、これは通常％AppData％\ XBMC、Linuxでは$ HOME / .xbmcです。

おわりに

独自のインターフェースを備えたXBMCのプラグインの作成に専念する記事のパートIでは、プラグインインターフェースの基本的な要素を検討し、簡単な例を示しました。

次のパートでは、ダイアログについて説明し、もう少し複雑な例を挙げて、画像を使用してインターフェイスを装飾し、インタラクティブな要素を作成する例を示します。



少し先に走りたい人は、上記のコントロールを示すこのプラグインをダウンロードできます。 上記のコントロールの例とともにスクリーンショットが撮られたのは彼からでした。 プラグインは、私が書いたマイクロフレームワークを使用します。これについてはパートIIIで説明する予定ですが、経験豊富な栄養士は簡単に理解できると思います。



PSいくつかのマイナーな修正と追加を行いました。

PPS onCloseメソッドに関する情報を修正しました。

継続

独自のインターフェースを備えたXBMC用のプラグインを作成しています：パートII-ダイアログと装飾 。