チュートリアル4: カスタム動作を備えたスクロール･ホイールの作成

このチュートリアルでは、Custom Container（カスタム･コンテナ）とScroll Wheel（スクロール･ホイール）という2つのウィジェットの作成および設定方法について学びます。カスタム･コンテナは、他の複数のウィジェットを組み合わせることで新しいウィジェットを作成できるようにするウィジェットで、カスタム･コンテナ内のウィジェットには特定の動作を追加できます。スクロール･ホイールは、複数の選択可能なアイテムで構成されるスクロール可能なメニューを作成するために使用されるウィジェットです。このチュートリアルでは、ウィジェットの動作を変更するために、ユーザ･コードを作成する方法についても説明します。

今回はもっと大きなスクリーンを使用するので、解像度800 x 480ピクセルのボード（STM32F469 Discoveryなど）で新しいプロジェクトを開始するか、シミュレータをそのまま使用してください。

カスタム･コンテナとスクロール･ホイールの詳細については、「カスタム･コンテナ」ページと「Scroll Wheel（スクロール･ホイール）」ページを参照してください。

このチュートリアル用のグラフィックスは、このリンクからダウンロードできます。 assetsの下のimagesフォルダにあるファイルを解凍します。このチュートリアルで使用するプロジェクトでは、MyApplication2\assets\imagesにあるファイルを使用します。

ステップ1: カスタム･コンテナの作成

Similar to step 1 in tutorial 2, start by creating a new project with TouchGFX Designer. This time when the new project is ready, change from the screens tab in TouchGFX Designer to the Container tab (1).

Custom Containerメニューの選択

カスタム･コンテナを作成するタブは［Screens］タブと似ており、新しいカスタム･コンテナは新しいスクリーンと同じ方法で作成できます。カスタム･コンテナの作成後は、そこにウィジェットを追加し、カスタム･コンテナのサイズと名前を変更することもできます。

カスタム･コンテナのタブで、［+］ボタン（1）を使用して新しいカスタム･コンテナを作成し、名前を"MenuElement"（2）に変更して、幅を390、高さを70（3）に変更します。

カスタム･コンテナの作成とプロパティの設定

カスタム･コンテナにウィジェットを追加

カスタム･コンテナを作成してプロパティを設定したら、そのカスタム･コンテナにウィジェットを追加できます。このチュートリアルのカスタム･コンテナは、1つの画像と、ワイルドカードを含む1つのテキスト･エリアで構成することとします。

ウィジェット	プロパティ
Image	Name: icon Image: icon00.png Location: X: 34 Y: 17
TextArea	Name: text Location: X: 93、Y: 23 Text: Text: Menu Element <value> Wildcard 1: Initial Value: 00 Buffer size: 3 Use wildcard buffer: Yes Typography: 20px Alignment: Left Appearance: Color: #FFFFFFFF

カスタム･コンテナをスクリーンに追加

［Screens］タブに戻ると、［Custom Container］（1）の下のウィジェット･メニューで［MenuElement］が選択できるようになっています。キャンバス上で、バックグラウンドとして黒いボックスを配置し、作成したカスタム･コンテナをいくつか追加します。挿入したコンテナはスクリーン上で自由に移動できます。カスタム･コンテナは、左側のウィジェット･リスト（2）に1つの要素として表示されます。

カスタム･コンテナをウィジェットとしてスクリーンに挿入

ステップ2: スクロール･ホイールの作成

チュートリアル4のこのステップでは、ステップ1で作成したカスタム･コンテナ"MenuElement"を使用して、スクロール･ホイールを作成します。ステップ1で説明したように、スクロール･ホイールは、複数の選択可能なアイテムを含むスクロール可能なメニューを作成するために使用されます。ホイール内のアイテムはスクロール中に動的に更新され、アイテムが選択されると、そのアイテムがフォーカスされます。

スクロール･ホイールにアイテムを追加するには、"Item Template"として使用するカスタム･コンテナを選択します。 "Item Template"のコンセプトは、カスタム･コンテナ内のウィジェットをスクロール･ホイールのアイテムのベースとして使用することで機能し、ユーザ･コードを使用して、実行時にアイテム内のウィジェットを更新します。

スクロール･ホイールの作成

スクロール･ホイールを作成する前に、スクリーンにすでに挿入済みのカスタム･コンテナを削除して、バックグラウンドとして黒色のボックスを残すのみにします。［Containers］セクション（1）の下のウィジェット･メニューにある［Scroll Wheel］を選択します。スクロール･ホイールを作成して、［Location］プロパティをX = 208、Y = 45、H = 390に設定し、名前を"scrollWheel"に変更します。

スクロール･ホイールを挿入して、名前と位置のプロパティを設定

スクロール･ホイールへのアイテムの追加

ステップ1で作成した"MenuElement"を"Item Template"として選択します。このために、［Scroll Wheel］プロパティ［Item Template］（1）の下に表示されるドロップダウン･リストを使用します。スクロール･ホイール内のアイテム数も［Item Template］で設定します。アイテム数は20に設定します。スクロール･ホイールは、選択したアイテムがフォーカスされることで機能するので、プロパティ［List Apperance］（2）の下の［Selected Item Offset］を設定して、選択したアイテムがUIのどこに配置されるのかを設定します。ここでは、選択したアイテムを、スクロール･ホイールの真ん中に配置したいので、［Selected Item Offset］を、(390-70)/2 = 160に設定します。

スクロール･ホイールにカスタム･コンテナを追加して、プロパティを調整

"scrollWheel"の領域をハイライト表示するには、ステップ1でダウンロードした.zipファイルにあるbackground.pngとoverlay.pngという2つの画像を使用し、これらをImageウィジェットとしてアプリケーションに追加します。この2つの画像は、"scrollWheel"の領域をハイライトするバックグラウンドと、"scrollWheel"内のアイテムが"scrollWheel"の端に移動したときに、それらを非表示にするためのオーバーレイです。

background.pngの画像は、X = 205、Y = 45の位置で"scrollWheel"の背後に配置されるので、"scrollWheel"内のアイテムはバックグラウンド上に描画されます。 overlay.pngは、"scrollWheel"上のX = 0、Y = 0に位置に配置されます。つまりアイテムはoverlay.pngの下に描画されることになり、overlay.pngが透明でなければアイテムは非表示になります。

ウィジェット･リスト内のウィジェットは、Ctrl +FキーおよびCtrl +Bキーを押すことで前および後に移動できます。

スクロール･ホイールでスクリーンに追加されたグラフィックス

ここまでに調整したのは"scrollWheel"の静的プロパティのみなので、ロジックはまだ追加されていません。このため、アプリケーションを実行すると、すべてが同じように表示される20個のアイテムで構成されるスクロール可能なメニューが表示されます。次のステップでは、実行時にホイール内のアイテムを更新するユーザ･コードを使用して、"scrollWheel"にロジックを追加します。

ステップ3: スクロール･ホイールへのユーザ･コードの追加

With the Scroll Wheel, "scrollWheel", created and configured in TouchGFX Designer, this step will create the logic, via user code, that updates the items in "scrollWheel", so they display different graphics based on the position of the item in the wheel. したがってこのステップでは、Designerによって生成されるコードとユーザ･コードの統合を行います。 Designerによるコードとユーザ･コードの統合の詳細については、「コード構造」ページを参照してください。

MenuElement内の画像とテキストの変更

Scroll Wheel内のアイテムは、ステップ1で作成したカスタム･コンテナ"MenuElement"に基づいているので、アイコンの変更およびワイルドカード更新のためのユーザ･コードを"MenuElement"に追加する必要があります。 When a Custom Container is created in TouchGFX Designer it generates a .hpp and .cpp file with the same name as the Custom Container. ユーザ･コードを、これらのファイルに統合する必要があります。このアプリケーション例で、"MenuElement"用に生成されるファイルは次の場所に配置されます。

MyApplication2\gui\include\gui\containers\MenuElement.hpp

MyApplication2\gui\src\containers\MenuElement.cpp

"scrollWheel"内のアイテムのテキストやアイコンを変更するには、setNumber(int no)関数を"MenuElement"に追加します。この関数は、変数noを使用して、Imageウィジェットで表示するアイコンを決定し、Text Areaウィジェット内のワイルドカードをnoの値に変更します。

TextAreaでは0～9の数字を使用するので、Defaultタイポグラフィの［Wildcard Ranges］に範囲"0-9"を追加する必要もあります。

Press F4 to have the files generated by TouchGFX Designer.

以下に示すMenuElement.hppで、setNumber(int no)の宣言と実装が行われます。

TouchGFX/gui/include/gui/containers/MenuElement.hpp

#ifndef MENUELEMENT_HPP
#define MENUELEMENT_HPP

#include <gui_generated/containers/MenuElementBase.hpp>
#include <images/BitmapDatabase.hpp>

class MenuElement : public MenuElementBase
{
public:
    MenuElement();
    virtual ~MenuElement() {}

    virtual void initialize();

    void setNumber(int no)
    {
        Unicode::itoa(no, textBuffer, TEXT_SIZE, 10);
        switch (no % 7)
        {
        case 0:
        icon.setBitmap(Bitmap(BITMAP_ICON00_ID));
            break;
        case 1:
        icon.setBitmap(Bitmap(BITMAP_ICON01_ID));
            break;
        case 2:
        icon.setBitmap(Bitmap(BITMAP_ICON02_ID));
            break;
        case 3:
        icon.setBitmap(Bitmap(BITMAP_ICON03_ID));
            break;
        case 4:
        icon.setBitmap(Bitmap(BITMAP_ICON04_ID));
            break;
        case 5:
        icon.setBitmap(Bitmap(BITMAP_ICON05_ID));
            break;
        case 6:
        icon.setBitmap(Bitmap(BITMAP_ICON06_ID));
            break;
        }
    }
protected:
};

#endif // MENUELEMENT_HPP

このコードは、プロジェクト内の画像を参照するために、BITMAP定義を使用しています。これらを使用可能にするには、上で実行されているように"images/BitmapDatabase.hpp"をincludeする必要があります。

MenuElementのコンテンツを更新するためのコードが追加されたので、次にやるべきことは、スクロール･ホイール内のアイテムを更新するコードの追加です。

スクロール･ホイール内のアイテムの更新

When creating a Scroll Wheel, TouchGFX Designer generates a virtual function in the Screen base class which is called each time a new item in the Scroll Wheel becomes visible. ユーザ･コードでこの関数をオーバーライドすると、コードがスクロール･ホイール内のアイテムとやり取りできるようになります。

この関数の名前は、Scroll Wheelの名前にUpdatedItemが付加されたものになります。このチュートリアルでは、scrollWheelUpdateItem(MenuElement& item, int16_t itemIndex)という関数になります。

パラメータitemIndexは、現在更新されているアイテムを知らせるインデックス値で、itemは、スクロール･ホイールで現在表示されているMenuElementのインスタンスへの参照です。 itemIndexが更新中のアイテムを知らせると、そのアイテムに対するsetNumber()が呼び出され、itemIndexの値に基づいて更新されるアイテムの内容が変更されます。スクロール･ホイールのアイテムの更新に使用されるコードは以下のとおりです。

Screen1View.hpp

#ifndef SCREEN1VIEW_HPP
#define SCREEN1VIEW_HPP

#include <gui_generated/screen1_screen/Screen1ViewBase.hpp>
#include <gui/screen1_screen/Screen1Presenter.hpp>

class Screen1View : public Screen1ViewBase
{
public:
    Screen1View();
    virtual ~Screen1View() {}
    virtual void setupScreen();
    virtual void tearDownScreen();
    virtual void scrollWheelUpdateItem(MenuElement& item, int16_t itemIndex)
    {
        item.setNumber(itemIndex);
    }
protected:
};

#endif // SCREEN1VIEW_HPP

アプリケーションに対してシミュレータを実行すると、アイテムのテキストにそのインデックスの値が含まれることがわかり、表示されるアイテムに基づいてアイコンが変化する様子が示されます。下の画像は、実装されたコードで実行されているシミュレータの例を示しています。

シミュレータを実行

ステップ4: スクロール･ホイールへのカスタム動作の追加

チュートリアル4の最後のステップでは、スクロール･ホイールにカスタム動作を追加します。これにより、アイテムをスクロールするときに、円を描くように動かすと、ダイアルに似た動きを見せるようになります。

MenuElementへのカスタム動作の追加

スクロール･ホイールがダイアルのようなパターンで動くようにするには、スクロール･ホイールに表示される各アイテムのImageおよびTextウィジェットの水平位置をシフトさせます。このためには、MenuElement.hppで、"MenuElement"に対するsetY()関数をオーバーライドします。 setY()関数は、カスタム･コンテナが垂直方向に移動するたびに呼び出され、カスタム･コンテナを新しい位置に再描画するために使用されます。 setY()をオーバーライドすることで、スクロール･ホイールがスクロールされるたびに、コンテナ内でImageおよびTextウィジェットを水平方向に移動することもできます。下の画像は、MenuElement.hppで、新しいsetY()関数を実装し、2つのウィジェットをシフトする方法を示しています。 math.hをインクルードする必要があることに注意してください。

MenuElement.hpp

#ifndef MENUELEMENT_HPP
#define MENUELEMENT_HPP

#include <gui_generated/containers/MenuElementBase.hpp>
#include <images/BitmapDatabase.hpp>
#include <math.h>

class MenuElement : public MenuElementBase
{
public:
    MenuElement();
    virtual ~MenuElement() {}

    virtual void initialize();

    //Adjusts the position of the text and the icon, based in the calculated offset(x)
    void offset(int16_t x)
    {
        icon.setX(30 + x);
        text.setX(80 + x);
    }

    //The new declaration and implementation of the setY() function
    virtual void setY(int16_t y)
    {
        //set Y as normal
        MenuElementBase::setY(y);

        const int circleRadius = 250;

        //center around middle of background
        y = y + getHeight() / 2 - 390 /2;

        //calculate x
        float x_f = circleRadius - sqrtf((float)((circleRadius * circleRadius) - (y * y)));
        int16_t x = (int16_t)(x_f + 0.5f);

        offset(x);
    }

    ...

新しいsetY()関数が実装されたので、シミュレータを実行すると、今度はスクロール･ホイールがオーバーレイによる曲線に沿ってダイアル状に動くようになります。

シミュレータを実行

これでチュートリアル4は終了です。

Further reading
このチュートリアルで使用した概念を詳しく学ぶため、以下の章ではここで取り組んだいくつかの概念を取り上げています。[「Scroll Wheel（スクロール･ホイール）」ページ]（../../docs/development/ui-development/ui-components/containers/scroll-wheel）では、TouchGFX Designerでスクロール･ホイールを作成および設定する方法と、ユーザ･コードでロジックを作成する方法について説明しています。
[「カスタム･コンテナ」ページ]（../../docs/development/ui-development/touchgfx-engine-features/custom-containers）では、カスタム･コンテナの概念と使用方法について説明しています。

ステップ1: カスタム･コンテナの作成​

カスタム･コンテナにウィジェットを追加​

Further reading

カスタム･コンテナをスクリーンに追加​

ステップ2: スクロール･ホイールの作成​

スクロール･ホイールの作成​

スクロール･ホイールへのアイテムの追加​

ステップ3: スクロール･ホイールへのユーザ･コードの追加​

MenuElement内の画像とテキストの変更​