ファイルピッカーAPI概要

ファイルピッカー（ContentsManagerの利用）について

ContentsManager（以下CM)とは、実機に保存されているプリセットデータ、および、SDカード挿入時にはSDカード内のデータを管理するAPIです。
アプリケーションで、保存されている各種データを取り扱いたい場合、CMを起動してファイル情報を取得することが可能です。

CMの起動方法について

CMは明示的起動と、暗黙的起動の2種類の起動方法があります。

○明示的起動
ファイルのカテゴリ、種類、一覧にした際のソート順、ファイルの選択方法など、CMの表示仕様を詳細に指定して起動することが可能です。
指定パラメータおよび、起動方法については詳細を参照してください。
(2.外部アプリからのContentsManager起動仕様)

○暗黙的起動
アプリケーションが取り扱うファイルのMIMEtypeを指定し、このファイルを取り扱うことができる全てのアプリケーションを呼び出す起動方法です。
CM以外に使用可能なアプリケーションがある場合、どのアプリケーションを起動するか選択するダイアログが開きます。
CM以外に使用可能なアプリケーションがない場合、直接CMが起動します。
指定パラメータおよび、起動方法については詳細を参照してください。
(2.外部アプリからのContentsManager起動仕様)

CMからのファイル取得について

CM上でファイルを選択すると、選択したファイルのURIが返却されます。
呼び出し元のアプリでは、このURIをもとにContentProvider経由でファイルの詳細情報を取得します。

複数選択の場合、CMは選択された全てのファイルのURIを一時ファイルとして書き出し、Intentにそのファイルパスを付随させて呼び出し元へ返却します。
呼び出し元のアプリでは、ファイルパスから一時ファイルを取得し、書き込まれたURIを1行ずつ読み出すことで読み込んだURIを元にContentProvider経由で、選択したファイルの詳細情報を取得することができます。

このAPIを使用するには

SDKへadd-onsを追加する必要があります。
また、Android4.4(KK/API Lv15）以降の端末では、microSD、ストレージに保存されたデータを取得する際、データを読み込むためのパーミッションを記述する必要があります。

CMの起動

CMの起動および、CMからの戻り値の取り扱いについては、2.外部アプリからのContentsManager起動仕様 と 3.データ仕様書 コンテンツ種別タブ-ファイル対応表 を参照してください。

起動したCMについて

CMを起動している間は、CMの操作法に従ってファイルを選択してください。

CM画面構成

CMの画面は、大きく「タブエリア」、「コンテンツ表示エリア」、「タイトルエリア」に分けられます。
「コンテンツ表示エリア」については、リストビュー形式とグリッドビュー形式の表示切替が可能です。

タブエリアについて

タブエリアには対象になっているコンテンツのカテゴリが表示されます。
端末（microSDを含む）に存在するコンテンツを、カテゴリ（コンテンツ種別）に分類して表示することで、ユーザにとって検索・選択しやすい環境を提供します。

タブエリアに表示されるコンテンツは、CM起動時に設定したカテゴリです。
それ以外のタブはグレーアウトになります。
何も指定しない場合、TVタブを除く全てのカテゴリのタブがグレーアウトにならずに表示されます。

最初に表示するカテゴリのタブは、MIMEtypeを指定することで設定可能です。
未指定の場合は初期値としてフォトを表示します。
また、カテゴリ指定とMIMEタイプ指定が異なっている場合は、カテゴリ指定を優先して表示します。

コンテンツ表示エリアについて

コンテンツ表示エリアは、「リストビュー」、「グリッドビュー」の2種類の表示形式が存在します。
表示形式は「MENU」－「グリッド/リスト切り替え」から切り替えが可能です。

コンテンツ表示エリアにはタブエリアで選択中のカテゴリーに属するファイルを、検索条件エリアで選択している条件に従って表示されます。

保存場所の切り替えについて

コンテンツの保存場所を指定することができます。
保存場所は、microSD、プリセットのうち、起動時に指定したものから選択可能です。
何も指定しない場合、microSDのみが対象となり、切り替えは出来ません。

Android4.4以降が搭載された端末向けに作成する際に、microSD、本体ストレージにあるデータを参照させたい場合、AndroidManifest.xmlにで、android.permission.READ_EXTERNAL_STORAGE を追加してください。
※uses-permissionの記載例については、2.外部アプリからのContentsManager起動仕様 にあるサンプルコードを参照

検索画面について

タブ毎に分類されたコンテンツを、さらに細かい条件で絞り込むことを目的とする画面です。
共通検索条件（タイトルで絞り込む、最近1週間のファイル、保存時期で絞り込む）は、全タブ共通にするかどうかを選択できます。
ディスプレイ（サブエリア）のタッチキーの内、一番右の虫眼鏡アイコンをタップすることで検索画面が起動します。

タイトルで絞り込む

入力した「文字列」から、タイトル名（タブによってはタイトル以外もある）に合致するコンテンツを絞り込み（部分一致）ます。
検索時の文字数制限は、100byteまでとされ、100byteを超えた入力はできません。

テキストエリアに入力不可な文字は「絵文字」「改行」です。

検索文字にて検索を行うコンテンツの情報は下記の通りです。

タブ名称	検索を行うコンテンツの情報
ピクチャ	タイトル名
ムービー	タイトル名
ミュージック	タイトル名 / アーティスト名 (※)
ドキュメント	タイトル名
その他	タイトル名

※1つでも検索条件でマッチすれば表示されます。

最近1週間のファイル

コンテンツのタイムスタンプ（保存日時）にて、コンテンツの検索を行います。
項目を選択した日の１週間前の日（同一曜日）の0時以降に保存されたコンテンツを表示する。

保存時期で絞り込む

コンテンツのタイムスタンプ（保存日時）にて、コンテンツの検索を行います。
開始/終了年月日を選択するダイアログを表示して、年月日を選択する。

表示内容のソートについて

オプションメニューからソート条件を選択できる機能を提供します。
ソート条件を選択すると、検索条件が変更されたとして検索を再実行されます。

ソート条件として以下の項目を一つだけ選択することができます。
　1) ファイルサイズ 昇順
　2) ファイルサイズ 降順
　3) 保存日時 昇順
　4) 保存日時 降順
　5) タイトル 昇順
　6) タイトル 降順
何も指定しない場合、保存日時昇順となります。

ファイルの選択方法について

起動したCMでは、一覧表示中のファイルに対し、1件選択もしくは複数選択を行うことが可能です。
CM起動パラメータの選択モードを指定することで、ファイルの選択方法を決定します。
デフォルトは1件選択となっており、選択モードを何も指定しない場合は1件選択で起動されます。

○1件選択
任意のファイルを1件選択し、そのURIを起動元アプリケーションへ返却します。

○複数選択
任意のファイルを複数件選択し、そのURIを書き込んだ一次ファイルのURIを起動元アプリケーションへ返却します。

複数選択を起動し、1件しか選択しなかった場合、一次ファイルは作成されず、1件選択時と同様にURIが返却されます。

複数選択時に、選択できる最大に達すると、CMはこれ以上選択できないことを通知します。

【サンプルコードへ】
　【公開API一覧へ】