チュートリアル: Androidのデータソース¶

このチュートリアルでは、Android用の Kanzi アプリケーションのデータソースを作成する方法を学びます。次のことを学びます。

Kanzi Java API を使用してデータソースを作成します。
Android APIを使用してデータソースをバックアップします。
Android APIが利用できない場合に、Kanzi Studio Preview との互換性を確保してください。

このビデオはチュートリアルの結果を示しています。

../../_images/android-data-source-complete.gif

このチュートリアルは、Androidアプリケーションの開発、Javaプログラミング言語に精通しており、Kanzi Studio の基本的な操作を理解していることを前提としています。Kanzi Studio に慣れるためのベストエントリーポイントは次のとおりです。

このチュートリアルを始める前に、Android用の Kanzi 開発環境がセットアップされていることを確認してください。Kanzi を使用した Android アプリケーション開発の要件を参照してください。

このチュートリアルで作成したアプリケーションをAndroid仮想デバイスで実行するには、仮想デバイスを設定します。

API レベルを29以上に設定
内部ストレージを少なくとも8GBに

チュートリアルを入手する¶

チュートリアルを入手するには、Kanzi Studio Quick Start ウィンドウで Projects をクリックし、Tutorials タブを選択します。Android data source チュートリアルの横にあるダウンロードをクリックします。

Kanzi Studio はチュートリアルを <KanziWorkspace>/Tutorials ディレクトリにダウンロードします。以下が含まれています。

<KanziWorkspace>/Tutorials/Android data source/Assets ディレクトリにある、チュートリアルのアセット。
<KanziWorkspace>/Tutorials/Android data source/Completed ディレクトリにある、完成したチュートリアル。

一方向データソースを作成する¶

このセクションでは、Kanzi アプリケーションから読み取ることができるデータソースを作成します。Android デバイスのバッテリーレベルを表示するウィジェットを作成します。

一方向データソースを作成するには:

Kanzi Studio でプロジェクトを作成します。Quick Start ウィンドウの New タブで:
- Project Name を Android data source に設定します
- Android application with Java plugin プロジェクトテンプレートを選択します
  
  このテンプレートを使用して、Kanzi Java API データソースの構築を開始します。
  
  Android application with Java plugin テンプレートは、Kanzi Studio プロジェクトと、Kanzi Engine Java プラグインを含む Kanzi Android フレームワークベースのアプリケーションを作成します。
  
  Androidプラットフォーム用のアプリケーションを作成し、Android APIやサービスを広範囲に使用する場合は、Kanzi Android framework (droidfw) を使用してください。
  
  Kanzi Android framework (droidfw) は、Android向けの Kanzi アプリケーションを開発するためのフレームワークです。Kanzi Java APIを公開しており、アプリケーションやプラグインのコードを完全にJavaまたはKotlinで記述することができます。C++やJNIコードを書く必要はありませんが、ネイティブの Kanzi プラグインを使用することは可能です。Kanzi Android framework (droidfw) は、複数の同時 Kanzi ベースのビューや Kanzi とAndroid UI要素の柔軟な構成を含む、Android UIとの強力な統合を提供します。Kanzi Android framework (droidfw) は、Android UIスレッドで Kanzi メインループタスクを実行するAndroid Choreographerと統合されています。これにより、ディスパッチャーメカニズムを必要とせずに、アプリケーションコードから Kanzi Java API を使用することができます。
Android Studio で:
1. Android data source/Application/configs/platforms/android_gradle プロジェクトを開きます。
2. androiddatasourceplugin > java > com.example.androiddatasourceplugin の JavaDataSource クラスで、次の操作を行います。
  1. バッテリーレベルデータオブジェクトの名前を定義する定数を追加します。
    static String BATTERY_LEVEL = "BatteryLevel";
  2. initialize() メソッドで、既存のデータソース設定を置き換えます。
    root.addChild(DataObjectInt.create(domain, "Integer value", 1).get()); root.addChild(DataObjectString.create(domain, "String value", "dummy value").get()); root.addChild(DataObjectReal.create(domain, "Real value", 0.5).get());
    以下に置き換えます。
    root.addChild(DataObjectReal.create(domain, BATTERY_LEVEL, 0.5f).get());
3. androiddatasource > androiddatasourceplugin > Tasks > kanzi の Gradle ツールウィンドウで、exportJarDebug または exportJarRelease を右クリックし、Run を選択します。
  
  exportJarDebug が表示されない場合は、Android Studio で Gradle プロジェクトを同期する必要があります。
  
  Android Studio は、Kanzi Studio で使用する Kanzi Engine データソースプラグイン JAR をビルドします。
Kanzi Studio で、Android Studioで定義したデータソースの値を表示するコンテンツを作成します。
1. Node Tree で、Viewport 2D ノードを削除します。
  
  このチュートリアルでは3Dコンテンツを作成しないため、Viewport 2D ノードを削除できます。
2. RootNode に Flow Layout 2D ノードを作成し、Controls という名前を付けます。
3. Properties で、Horizontal Alignment と Vertical Alignment プロパティを Center に追加して設定します。
4. Controls ノードの Node Tree で、Empty Node 2D ノードを作成し、Battery Widget と名付けます。Properties で、追加して設定します:
  - Layout Width から 150 へ
  - Layout Height から 200 へ
5. Asset Packages > Factory Content から、Progress Indicator を Node Tree の Battery Widget ノードにドラッグします。
6. Node Tree で、Progress Indicator プレハブプレースホルダを選択します。Properties で、追加して設定します。
  - Layout Width から 150 へ
  - Layout Height から 150 へ
  - Ring Thickness から 0.3 へ
7. Node Tree の Battery Widget ノードで、Text Block 2D ノードを作成します。Properties で、追加して設定します:
  - Horizontal Alignment から Center へ
  - Vertical Alignment から Bottom へ
  - Text から Battery へ
Kanzi Studio で、データソースを作成し、使用します。
1. Library > Kanzi Engine Plugins で Android_data_source プラグインを右クリックし、Update Kanzi Engine Plugin を選択します。
  
  この方法で、Android Studio プラグインプロジェクトで行った変更を含むプラグインをロードして更新します。
2. プラグインの変更を反映するには、Preview を再起動してください。
3. Window メインメニューで、Data Sources を選択します。
  
  Data Sources ウィンドウを使用して、プロジェクト内のデータソースを作成、設定、削除し、データソースからデータオブジェクトをプロジェクト内のノードやリソースに接続します。
4. Data Sources ウィンドウで、Create Data Source をクリックし、次の設定でデータソースを作成します。
  - Name から Android data source へ
  - Data Source Type から JavaDataSource へ
  Data Sources ウィンドウでは、Android Studio で定義した BatteryLevel データオブジェクトを確認できます。
5. Node Tree で RootNode ノードを選択します。Properties で Data Context > Data Context プロパティを追加し、Android data source に設定します。
  
  Data Context プロパティを設定することで、アプリケーションがどのデータソースからデータを受け取るかを指定します。ノードに Data Context プロパティを設定すると、そのノードのすべての子ノードは Data Context プロパティの値を継承します。子ノードの1つに異なるデータコンテキストを使用したい場合は、そのノードに Data Context プロパティを追加し、使用したいデータコンテキストに設定します。
6. Node Tree で、Progress Indicator ノードを選択します。Properties で、+ Add Binding をクリックし、Binding Editor で設定します。
  - Property から Progress へ
  - Expression へ
```
{DataContext.BatteryLevel} * 100
```
  Save をクリックします。
Kanzi Studio で、File > Export > Export KZB を選択します。
データソースを更新して、AndroidシステムAPIからバッテリーレベルを取得します。

Android APIを使用するデータソースは、Android APIが利用できないため、Windows上で Kanzi Studio Preview を終了させます。このチュートリアルのアプローチでは、Android上でAndroid APIを使用しつつ、Kanzi Studio Preview でプラグインを使用する際にデータソースがプレースホルダーデータを返すことを可能にする方法を示します。
1. Android Studioで、DataProvider という名前のインターフェースを作成します。
```
package com.example.androiddatasourceplugin;

interface DataProvider
{
   float getBatteryLevel();
}
```
2. インターフェースのプレースホルダ実装を非Androidプラットフォームで使用するために、DummyDataProvider という名前のクラスを作成します。
```
package com.example.androiddatasourceplugin;

class DummyDataProvider implements DataProvider
{
    @Override
    public float getBatteryLevel()
    {
        return 0.5f;
    }
}
```
3. アプリケーションがAndroidデバイス上で実行されているときに使用するインターフェースのAndroid実装を作成するには、AndroidDataProvider という名前のクラスを作成します。
```
package com.example.androiddatasourceplugin;

import android.content.Context;
import android.os.BatteryManager;

class AndroidDataProvider implements DataProvider
{
    private final BatteryManager mBatteryManager;

    public AndroidDataProvider(Object context)
    {
        Context androidContext = (Context) context;

        mBatteryManager = (BatteryManager) androidContext.getSystemService(Context.BATTERY_SERVICE);
    }

    @Override
    public float getBatteryLevel()
    {
        int batLevel = mBatteryManager.getIntProperty(BatteryManager.BATTERY_PROPERTY_CAPACITY);
        return ((float) batLevel) / 100.0f;
    }
}
```
4. 新しいプロバイダーを使用するように JavaDataSource を更新します。
  - 作成したいコンテンツの機能を提供する Kanzi クラスをインポートします。
    import com.rightware.kanzi.Platform;
  - データプロバイダーのためのデータメンバーを追加します。
    private DataProvider mDataProvider;
  - initialize() メソッド内で、super.initialize(); の直後に次のコードを追加して、データプロバイダを選択します:
    // Construct the proper DataProvider for the current platform. if (Platform.isAndroid()) { mDataProvider = new AndroidDataProvider(getDomain().getPlatformContext()); } else { mDataProvider = new DummyDataProvider(); }
  - バッテリーレベルデータオブジェクトの定義を更新して、インターフェースから値を取得します。
    root.addChild(DataObjectReal.create(domain, BATTERY_LEVEL, mDataProvider.getBatteryLevel()).get());
Android Studioで、app をビルドして実行します。

アプリケーションをAndroidデバイスで実行すると、バッテリーウィジェットがそのデバイスの現在のバッテリーレベルを表示します。

双方向データソースを作成する¶

このセクションでは、Android デバイスのサイレントモードを制御するために使用できるウィジェットを作成します。

双方向データソースを作成するには：

Android Studio で、サイレントモードに関連する情報を含めるようにデータソースを更新します:

DataProvider インターフェースに、以下を追加します。
```
boolean isSilentMode();
void setSilentMode(boolean enabled);
```

DummyDataProvider クラスに、次を追加します。

private boolean mSilentMode = false;

@Override
public boolean isSilentMode()
{
   return mSilentMode;
}

@Override
public void setSilentMode(boolean enabled)
{
   mSilentMode = enabled;
}

AndroidDataProvider クラス内で：

作成したいコンテンツの機能を提供するAndroidクラスをインポートします。

import android.app.NotificationManager;
import android.media.AudioManager;
import android.provider.Settings;

次のメンバーを追加します:

private final AudioManager mAudioManager;

コンストラクターに次のコードを追加して、オーディオマネージャーを初期化し、通知ポリシーへのアクセスを要求します:

// Request notification policy access if not granted.
// This is required to change ringer mode when Do Not Disturb is active.
NotificationManager notificationManager = (NotificationManager) androidContext.getSystemService(Context.NOTIFICATION_SERVICE);
if (!notificationManager.isNotificationPolicyAccessGranted())
{
   Intent intent = new Intent(Settings.ACTION_NOTIFICATION_POLICY_ACCESS_SETTINGS);
   intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
   androidContext.startActivity(intent);
}

mAudioManager = (AudioManager) androidContext.getSystemService(Context.AUDIO_SERVICE);

これらのメソッドを追加します。

@Override
public void setSilentMode(boolean enabled)
{
   if (enabled)
   {
      mAudioManager.setRingerMode(AudioManager.RINGER_MODE_VIBRATE);
   }
   else
   {
      mAudioManager.setRingerMode(AudioManager.RINGER_MODE_NORMAL);
   }
}

@Override
public boolean isSilentMode()
{
   int ringerMode = mAudioManager.getRingerMode();
   return ringerMode == AudioManager.RINGER_MODE_VIBRATE || ringerMode == AudioManager.RINGER_MODE_SILENT;
}

JavaDataSource クラスで、次の操作を行います。

作成したいコンテンツの機能を提供する Kanzi クラスをインポートします。
```
import com.rightware.kanzi.DataObjectBool;
```

次のメンバーを追加します:

static String SILENT_MODE = "SilentMode";

initialize() 関数でデータソースを更新します。

ObjectRef<DataObjectBool> silentModeRef =
    DataObjectBool.create(domain, SILENT_MODE, mDataProvider.isSilentMode());
root.addChild(silentModeRef.get());

// Register a Notification handler to update silent mode when Data Source changes.
DataObjectBool silentMode = silentModeRef.get();
silentMode.addModifiedNotificationHandler(new ModifiedSubscriptionFunction() {
    @Override
    public void handle()
    {
        mDataProvider.setSilentMode(silentMode.getValue());
    }
});

androiddatasourceplugin > manifests > AndroidManifest.xml および app > manifests > AndroidManifest.xml ファイルに、これらの権限を追加します。

<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS"/>
<uses-permission android:name="android.permission.ACCESS_NOTIFICATION_POLICY"/>

androiddatasource > androiddatasourceplugin > Tasks > kanzi の Gradle ツールウィンドウで、exportJarDebug または exportJarRelease を右クリックし、Run を選択します。

Android Studio は、Kanzi Studio で使用する Kanzi Engine データソースプラグイン JAR をビルドします。

Kanzi Studio で、プラグインを更新します。
1. Library > Kanzi Engine Plugins で、AndroidDataSource プラグインを右クリックし、Update Kanzi Engine Plugin を選択します。
  
  この方法で、Android Studio プラグインプロジェクトで行った変更を含むプラグインを更新してロードします。
2. プラグインの変更を反映するには、Preview を再起動してください。
Data Sources ウィンドウの Kanzi Studio で、Refresh ボタンをクリックして、プラグインから更新されたデータソースの内容を読み込みます。
Kanzi Studio で、サイレントモードウィジェットのユーザーインターフェイスを作成します:
1. Node Tree で Controls ノードを Alt を押しながら右クリックして Empty Node 2D ノードを作成し、Silent Mode Widget という名前を付けます。Properties で、以下を追加して設定します:
  - Layout Width から 150 へ
  - Layout Height から 200 へ
  - Layout.Item > Horizontal Margin プロパティ Left プロパティフィールドを 40 に
2. Node Tree で Silent Mode Widget ノードを Alt を押しながら右クリックして Image ノードを作成し、Icon Silent On という名前を付けます。Properties で、以下を追加して設定します:
  - Image を + Import Image... に設定し、<KanziWorkspace>/Tutorials/Android data source/Assets/bell-off.png を選択します
  - Layout Width から 150 へ
  - Layout Height から 150 へ
3. Properties で、バインディングを追加し、次を設定します。
  - Property から Visible へ
  - Expression へ
    BOOL({DataContext.SilentMode})
  Save をクリックします。
  
  このバインディングにより、SilentMode データオブジェクトの値が true のときに Icon Silent On イメージを表示します。
4. Node Tree で Icon Silent On ノードを複製し、名前を Icon Silent Off に変更します。
5. Node Tree で Icon Silent Off ノードを選択します。Properties で:
  - バインディングをクリックし、Binding Editor でバインディング式の先頭に ! を追加します。
    
    Save をクリックします。
    
    このバインディングにより、SilentMode データオブジェクトの値が false のときに Icon Silent Off イメージを表示します。
  - Image プロパティを + Import Image... に設定し、<KanziWorkspace>/Tutorials/Android data source/Assets/bell.png を選択します。
6. Asset Packages > Factory Content から Toggle Button を Node Tree にドラッグし、Silent Mode Widget にドロップします。
  
  このトグルボタンを使用してサイレントモードを操作します。
7. Node Tree で、Toggle Button ノードを選択します。Properties で：
  - バインディングを作成して設定します:
    - Binding Mode から Two way へ
    - Property から Toggle State へ
    - Expression へ
      {DataContext.SilentMode}
    Save をクリックします。
    
    このバインディングを使用すると、Toggle Button ノードのトグルステートと SilentMode データオブジェクトの間に双方向の接続を作成します。
  - Vertical Alignment プロパティを追加し、Bottom に設定します。
Kanzi Studio で、File > Export > Export KZB を選択します。
Android Studioで、app をビルドして実行します。

アプリケーションをAndroidデバイスで実行すると、サイレントモードウィジェットがそのデバイスのサイレントモードの状態を示すアイコンを表示します。

外部の変更に基づいてデータソースをアップデートする (Update data sources based on external changes)¶

前のセクションでは、アプリケーションの起動時にAndroidデバイスから定数データを読み取る機能を追加しました。このセクションでは、データソースがAndroidのコールバックに応答し、サイレントモードまたはバッテリーレベルが変化したときにデータソースを更新するように設定します。

外部の変更に基づいてデータソースを更新するには:

DataChangeListener という名前のインターフェースを作成します。

このインターフェースは、データの変更が発生したときにそれを受け入れます。

package com.example.androiddatasourceplugin;

interface DataChangeListener {
    void updateBatteryLevel(float batteryLevel);
    void updateSilentMode(boolean isSilent);
}

AndroidDataProvider クラスを修正して、Androidから更新されたデータを受け取るようにします。

作成したいコンテンツの機能を提供するAndroidクラスをインポートします。

import android.content.BroadcastReceiver;
import android.content.Intent;
import android.content.IntentFilter;

DataChangeListener への参照を保持するメンバーを追加します。
```
private final DataChangeListener mDataChangeListener;
```
AndroidDataProvider のコンストラクタを修正して、DataChangeListener を受け取り、保存するようにします。
```
public AndroidDataProvider(Object context, DataChangeListener listener)
{
   mDataChangeListener = listener;
```

サイレントモードとバッテリーレベルのリスナーコールバックを追加します。

// Battery level listener
private final BroadcastReceiver mBatteryReceiver = new BroadcastReceiver() {
    @Override
    public void onReceive(Context context, Intent intent)
    {
        int level = intent.getIntExtra(BatteryManager.EXTRA_LEVEL, -1);
        int scale = intent.getIntExtra(BatteryManager.EXTRA_SCALE, -1);
        float batteryLevel = level / (float) scale;

        mDataChangeListener.updateBatteryLevel(batteryLevel);
    }
};

// Ringer mode listener that indicates whether silent mode is enabled.
private final BroadcastReceiver mRingerModeReceiver = new BroadcastReceiver() {
    @Override
    public void onReceive(Context context, Intent intent)
    {
        int ringerMode = intent.getIntExtra(AudioManager.EXTRA_RINGER_MODE, AudioManager.RINGER_MODE_NORMAL);
        boolean isSilent = ringerMode == AudioManager.RINGER_MODE_VIBRATE || ringerMode == AudioManager.RINGER_MODE_SILENT;
        mDataChangeListener.updateSilentMode(isSilent);
    }
};

Androidにコールバックを登録するには、このコードを AndroidDataProvider のコンストラクタに追加してください。

// To get battery changes, register the battery receiver.
androidContext.registerReceiver(mBatteryReceiver, new IntentFilter(Intent.ACTION_BATTERY_CHANGED));

// To get ringer mode changes, register the ringer mode receiver.
androidContext.registerReceiver(mRingerModeReceiver, new IntentFilter(AudioManager.RINGER_MODE_CHANGED_ACTION));

データの更新を処理するように JavaDataSource クラスを変更します。

クラスを変更して、DataChangeListener インターフェースを実装します。
```
public class JavaDataSource extends DataSource implements DataChangeListener {
```

DataChangeListener インターフェースの実装を追加します。

private boolean mUpdateInProgress = false;

@Override
public void updateBatteryLevel(float batteryLevel)
{
    DataObjectReal batteryObject =
        (DataObjectReal) mRoot.get().lookupDataContext(BATTERY_LEVEL);
    if (batteryObject != null)
    {
        mUpdateInProgress = true;
        batteryObject.setValue(batteryLevel);
        mUpdateInProgress = false;
    }
}

@Override
public void updateSilentMode(boolean isSilent)
{
    DataObjectBool silentModeObject =
        (DataObjectBool) mRoot.get().lookupDataContext(SILENT_MODE);
    if (silentModeObject != null)
    {
        mUpdateInProgress = true;
        silentModeObject.setValue(isSilent);
        mUpdateInProgress = false;
    }
}

initialize() メソッドで、this を AndroidDataProvider コンストラクタの引数として追加します。
```
mDataProvider = new AndroidDataProvider(getDomain().getPlatformContext(), this);
```

initialize() メソッドでは、再帰的な更新を防ぐために、既存の通知ハンドラーを修正して mUpdateInProgress 変数を追加します。

silentMode.addModifiedNotificationHandler(new ModifiedSubscriptionFunction() {
    @Override
    public void handle()
    {
        if (!mUpdateInProgress)
        {
            mDataProvider.setSilentMode(silentMode.getValue());
        }
    }
});

Android Studioで、app をビルドして実行します。

アプリケーションをAndroidデバイスで実行すると、着信音モードが変化したときにサイレントモードウィジェットが更新されます。これをテストするには、デバイスのユーザーインターフェイスでサイレントモードを有効または無効にするか、サイレントモードウィジェットのトグルボタンを使用します。

注釈

おやすみモード (Do Not Disturb) が有効なときに着信音モードを変更するには、アプリケーションに通知ポリシーへのアクセス権限が必要です。初回起動時に、アプリケーションがこの権限を付与するよう求めます。

次の作業¶

このチュートリアルでは、次の方法を学びました:

Kanzi Java API を使用してデータソースを作成します。
Android APIを使用してデータソースをバックアップします。
Android APIが利用できない場合に、Kanzi Studio Preview との互換性を確保してください。

Kanzi Android framework (droidfw) とJava APIの使用方法の詳細については、次を参照してください。