公式なドキュメントはRhomobile社のサイトをご覧ください。
また、この文書は2010/6/16(JST)の情報がもとになっています。
この日本語の翻訳について問題・質問などがある場合、コメントを残してください。それ以外については、本ドキュメント内にある問い合わせ先にお願いします。
The following document (a translation of the English original into Japanese) is published with Rhomobile permission.
If you need official documents, please visit Rhomobile site.
In addition, the following document is based on 2010/June/17 (JST) information.
If you have any question, problem about the Japanese translation, please leave your comment. Except for that, refer contacts in the document.
Rhodesは、GPS、PIM、カメラ、ビデオプレーヤー、加速度計、近接検出器さらにはネイティブUIエレメントのようなデバイス特定の機能にアクセスする手段を提供します。以下は、デバイスのオペレーティングシステムごとに、どのリリースがどのデバイス機能をサポートしているかを示すデバイスのサポートマトリックスです。
| 機能 | iPhone | Windows Mobile | BlackBerry | Symbian | Android |
|---|---|---|---|---|---|
| GeoLocation | 0.3 | 0.3 | 0.3 | 1.1 | 1.0 |
| PIM Contacts | 0.3 | 0.3 | 0.3 | 1.0 | 1.0 |
| カメラ | 1.0 | 1.0 | 1.0 | 1.1 | 1.0 |
| 日付/時刻ピッカー | 1.2.2 | 2.0 | 1.2 | 2.3 | 1.2 |
| ネイティブメニュー | 1.2.2 | 2.0 | 1.2 | 2.3. | 1.5 |
| タブバー | 1.2.2 | 2.2 | n/a | 2.3 | 1.5 |
| ナビゲーションバー | 1.2.0 | 2.2 | n/a | 2.2 | 2.1 |
| オーディオ/ビデオキャプチャ | 2.0 | 2.0 | 2.1 | 2.3 | 2.0 |
| Bluetooth | 2.2 | 2.2 | 2.2 | 2.3 | 2.2 |
| プッシュ/ SMS | 1.2 | 2.2 | 1.2 | 2.3 | 2.2 |
| 横向き | 2.0 | 2.0 | 2.1 | 2.3 | 2.0 |
| ネイティブマップ | 1.4 | 2.0 | 1.4 | 2.3 | 1.5 |
| アラート/オーディオファイルの再生 | 1.2 | 1.5 | 1.2 | 2.3 | 1.2 |
目次 |
GPS
位置情報は2つの方法で利用可能です：予め定義したローカルURLをAjaxを通した非同期サービス、もしくはコントローラでGeoLocationクラスをRubyを使って呼び出す方法です。
Rhodes2.0から、アプリケーションの'GPS'機能が有効になっていなければなりません。これを行うにbuild.ymlに次の行を追加します：
capabilities:
- gps
詳細は機能セクションを見てください。
GPS受信機はエネルギーを大量消費するため、デバイスのバッテリ寿命を維持するためにほとんどの時間でオフにする必要があります。位置情報を取得するいかなる呼び出しもGPS受信機を起動することになります。また、通常、デバイスの現在の位置を取得するには時間がかかることに注意してください。いくつかのケースでは、それは数分かかることがありますしすべての屋内で動作することはできません。
非同期のAjaxの呼び出し
Rhodesフレームワークは、位置情報へのアクセスするための単純なHTMLタグを提供します。それを使用するには、ページ上に適切なJavaScriptライブラリを含めます：
iPhone, Android, Symbian: /public/js/jquery-1.2.6.min.js と /public/js/rhogeolocation.js
Windows Mobile: /public/js/rhogeolocation-wm.js
BlackBerry: 未サポート。BlackBerry webview controlはAjaxをサポートしていません。
そして、HTMLの適切な場所に以下のタグのどれかを配置します：<geolocation/>、<geolatitude/>または<geolongitude/>。これらのjavascriptは定義済みのURLを照会し、位置情報をこれらのタグをに埋め込みます。
<geolocation/> - returns a string in the form [formatted position];[latitude];[longitude].
For example: 37.3317° North, 122.0307° West;37.331689;-122.030731
<geolatitude/> - returns just the latitude
<geolongitude/> - returns just the longitude
ジオロケーションクラス
GeoLocation.latitude #=> returns current latitude
GeoLocation.longitude #=> returns current longitude
GeoLocation.known_position? #=> returns true if the location system is up and has acquired position
GeoLocation.set_notification(callback, callback_params="") #=> set callback to track location changes
# it gets called only once. to have it called again, you need to call set_notification again
# callback params: known_position, latitude, longitude, available, status('error', 'ok'), error_code(from RhoError)
GeoLocation.haversine_distance (latitude1, longitude1, latitude2, longitude2) #=> returns the distance
# between two points in miles
RhoController.set_geoview_notification(
callback,
callback_params="",
update_timeout_sec
) #=> set callback to track location changes on current view, this can be used instead of Ajax call
利用シナリオ
- アプリケーションの起動時に場所を必要とする：
class AppApplication < Rho::RhoApplication
def on_activate_app
#start geolocation
GeoLocation.set_notification("/app/Settings/geo_callback", "")
end
end
class SettingsController < Rho::RhoController
def geo_callback
puts "geo_callback : #{@params}"
end
end
- 特定のビューのみで場所を必要とする：
def show_location
if !GeoLocation.known_position?
GeoLocation.set_notification( url_for(:action => :geo_callback), "", 2)
redirect wait
else
render
end
end
def geo_callback
WebView.navigate show_location if @params['known_position'].to_i != 0 && @params['status'] =='ok'
WebView.navigate show_location_error if @params['available'].to_i == 0 || @params['status'] !='ok'
#do nothing, still waiting for location
end
- Ajaxを使用せずに（たとえば、BlackBerryはAjaxをサポートしていません)特定のビュー上で場所を追跡する。現在のビューがアクティブな間は、コールバックは関連してていることに注意してください。ビューを離れた場合、コールバックは削除されます。
def show_location
set_geoview_notification( url_for(:action => :geo_viewcallback), "", 2) if System::get_property('platform') == 'Blackberry'
render
end
def geo_viewcallback
WebView.refresh if @params['known_position'].to_i != 0 && @params['status'] =='ok'
end
例
さらなる情報はSystem API Samples applicationの/app/GeoLocationフォルダのコントローラとビューを参照してください。
- WM6エミュレータ上でのテスト
- WMエミュレータでアプリケーションを開発する場合、FakeGPSのユーティリティが便利でしょう。
- BBシミュレータでテスト
- BBのシミュレータ上では、Simulate->GPS Locationをメニューで選びます。
- Android上の擬似的LocationDataの提供には
メールの送信と、番号URLのコール
- mailto
- <a href="mailto:@?subject=testing123">Mailto</a>
- 注：空のアドレスでも、@記号を追加しなければなりません。
- 電話
- <a href="tel:1-555-531-3255!8335033#!#!9582#">Tel</a>
- <a href="wtai://wp/mc;5195551212" title="Call">Working Tel</a>
- <a href="wtai://wp/mc;5195551213" title="Call">Home Tel</a>
- 注：WMLの電話の説明はここで見つけることができます。
- SMS：
- <a href="sms:+3581234567">Send SMS to us</a>
PIM
電話帳/連絡先
Rhodesは、RubyクラスのRhoContactを介して、デバイスの電話帳や格納されている連絡先へアクセスする手段を提供します。
RhoContactのクラスで以下のメソッドが利用可能です：
Rho::RhoContact.find(:all) #=> return hash of hashes of all contacts stored in the phonebook. (index)
Rho::RhoContact.find(@params['id']) #=> return hash of all properties of the contact identified by the provided id. (show)
Rho::RhoContact.create!(@params['contact']) #=> create new contact in the phonebook, set properties of the contact
# from passed as parameter hash, and save created phonebook record. (create)
Rho::RhoContact.update_attributes(@params['contact']) #=> find contact record in the phonebook, update record properties
# from the has passed as parameter and save updated record. Contact id passed in the hash. (update)
Rho::RhoContact.destroy(@params['id']) #=> remove contact identified by the provided id from the phonebook. (delete)
すべてのデバイスにおいて、現在サポートされるプロパティは：
"id"、"first_name"、"last_name"、"mobile_number"、"home_number"、"business_number"、"email_address"、"company_name"です。
iPhoneでは、追加の連絡先のプロパティがサポートされます。それは以下のようなものです:
- 一般:
- "prefix", "first_name", "middle_name", "last_name", "suffix", "nickname""
- "birthday", "anniversary", "created", "updated"
- これらのプロパティは、日付はYYYY - MM - DDの形式を期待
- "company_name", "job_title", "assistant_name", "assistant_number"
- "spouse_name"、"person_note"
- 住所
- "street_address_1", "city_1", "state_1", "zip_1", "country_1"
- "street_address_2", "city_2", "state_2", "zip_2", "country_2"
- "street_address_3", "city_3", "state_3", "zip_3", "country_3"
- （address1は"work"、2は"ホーム"に、3は"その他"にマッピングされます
- メールアドレス：
- "email_address", "home_email_address", "other_email_address"
- （"email_address"は"work"にマッピングされてます)
- 電話番号：
- "business_number"、"home_number"、"mobile_number"、"main_number"、"pager_number"、"home_fax"、"work_fax"
- ホームページ：
- "home_page"
例
このクラスで提供されるAPIの使い方の例はSystem API Samples applicationの/app/Conttactsフォルダのビューとコントローラを見てください。
カメラ
カメラのAPIは、次の機能を提供します：
- デバイスがカメラを持っているかチェック：
-
System::get_property('has_camera')
-
- 写真を撮る：
-
Camera::take_picture('/app/model/camera_callback')
-
- アルバムから画像を選択：
-
Camera::choose_picture('/app/model/camera_callback')
-
いったんユーザーが写真を撮影もしくは選択すると、指定したコールバックURLが呼ばれます。コールバックはPOSTメッセージで、メッセージのbodyは'return status'とimage_uriが含まれます。
- statusは'ok'、'cancel'、または'error'
- image_urlは/public/db-filesフォルダに格納された撮影/選択したイメージを指しています。このイメージファイルは自動生成された名前になります。
例
より詳細は、System API Samples applicationの/app/Cameraフォルダのコントローラとビューを見てください。
着メロマネージャー
着メロマネージャAPIはインストールされた着信音を表示/再生するアクセス手段を提供します。
- すべての利用可能な着メロを取得
-
@ringtones = RingtoneManager::get_all_ringtones
- get_all_ringtonesによって返される変数は、key/valueのペアを含むハッシュで、keyは着メロのユーザーフレンドリな名前で、valueはその完全なファイル名です。
-
- 指定された着信音を再生
-
RingtoneManager::play @ringtones['My Ringtone']
- 別の着信音の再生中に'play'が呼ばれてると、再生中の着信音が止まり、指定された着信音の再生が開始します。
-
- 着メロの再生停止
-
RingtoneManager::stop
- 着メロを再生していなくても、安全に呼び出すことができます。
-
注：現在、AndroidとBlackBerry向けのみ実装。BlackBerryでは、ユーザがインストールした着信音のみがアクセス可能です。システムプレインストールされた着信音は、BlackBerryの制限によりアクセスできません。
例
より詳細は、System API Samples applicationの/app/RIngtonesフォルダのコントローラとビューを参照してください。
プッシュ通知
プッシュ通知はBlackBerryとiPhoneで利用可能です。
BlackBerry
BBへの通知にはBES/MDSサーバを介して、PAP2.0のメッセージを使って送信されます。
デバイスの電源投入し、常時バックグラウンドでリスナースレッドを実行させると、BBアプリケーションで着信メッセージのリッスンが始まります。クライアントがプッシュメッセージをリッスンするポートを、rhoconfig.txtの"push_port"オプションに指定します。ポートが指定されていない場合、デフォルトは100になります。
iPhone
iPhoneプッシュのサポートは、iPhone SDK 3.0で導入されたApple Push Notoficationサービスを使用します。
ペイロード
1つのメッセージで1つ以上のオペレーションを組み合わせることが可能です。
必須なオペレーションはありません。また、デフォルトの操作は - オペレーションが指定されないならば、なんのデフォルト・オペレーションも実行されません。これはデフォルトの動作です。
BlackBerryの場合、バックグラウンドでアプリケーションが動作しているならば、show_popupオペレーションはアプリケーションを前面に表示しますが、その他のオペレーションでは行われません。iPhoneの場合は、オペレーションに関係なく、アプリケーションが動作していないなら、アプリケーションをアクティブにするオプションが表示されます。
プッシュメッセージを受け取るように、ペイロードはクライアントが実行する以下のオペレーションを含むます：
- do_sync
do_sync = http://source-url/1/
これは、仕様で指定された同期ソースの同期を行います。すべてのソースを同期するには"all"を使います。
- show_popup
show_popup = "Some message"
これはアプリを前面に出して指定されたメッセージを表示します。
- vibrate
vibrate = duration in milliseconds
これは、ミリ秒単位で指定された間、振動します。durationの最大値は25500で、0または指定がない場合2500ミリ秒間振動します。
- play_file
play_file = file-name.ext, [media-type]
これは、メディアタイプがデバイスでサポートされているなら、指定されたファイルを再生します。iPhoneでは、メディアタイプのパラメータを無視します。
ファイルは、アプリケーションバンドルに含まれる必要があります。
BlackBerryの場合、ファイルはpublicフォルダ内にある場合は、ファイル名は/apps/public/test-file.mp3のようになり、メディアタイプは明示的に指定するか、ファイル拡張子から認識されます。既知のファイル拡張子は：.mp3 - audio/mpeg; .wav - audio/x-wav
iPhoneの場合は、オーディオファイルは、/public/alertsフォルダに置き、buildスクリプトはそれをアプリケーションのメイン・バンドルのルートにコピーします（iPhoneは他の場所からは再生しません）。
プッシュ コールバック
アプリケーションはRhoSyncサーバなしでプッシュを使用できます。デバイスIDを取得するには：
System.get_property('device_id')アプリケーションは、サーバーからの任意のコマンドを処理するためにプッシュコールバック設定することができます：
System.set_push_notification("/app/Settings/push_notify", '')コールバックパラメータ：
- message - サーバープッシュメッセージの本文を含む
コールバックの戻り値：
- 空の文字列 - rhoプッシュ処理を実行しない
- "rho_push" - Rhodesのプッシュコマンド処理を実行
def push_notify
puts 'push_notify: ' + @params.inspect
"rho_push"
end
アラート
コントローラで、ポップアップを表示、振動もしくはオーディオファイルを再生するシステム・アラート・メソッドを呼び出すことができます。
- show_popup
Alert.show_popup "Some message"
これは、アプリを前面に出し、指定されたメッセージを表示します。
2.0からは、ポップアップウィンドウのタイトル、アイコン、ボタンをカスタマイズし、ボタンをクリックして呼び出すコールバックを指定することができます：
Alert.show_popup {:message => 'Some message', :title => 'Custom title', :icon => '/public/images/icon.png',
:buttons => ["Yes", "No", {:id => 'cancel', :title => 'Cancel all'}],
:callback => url_for(:action => :on_dissmiss_popup) }ポップアップウィンドウは、いずれかのボタンをクリックした後、常に閉じます。
- message - ポップアップウィンドウに表示するテキスト
- title - ポップアップウィンドウのタイトル
- icon - ポップアップウィンドウに表示される画像。これは、定義済みの値またはイメージファイルへのパスを指定できます。定義済みの値：
:alert - '!' icon
:question - '?' icon
:info - informational icon
- buttons - ポップアップウィンドウのボタンの配列です。各ボタンのIDとタイトルで定義されています。ボタンは、:id、:titleもしくは単に文字列ハッシュで指定することができます - この場合、idとtitleがこの値に設定されます。
- callback - ボタンがクリックされると呼ばれるURL。このcallbackには、3つのキー:button_id、:button_titleと:button_indexを含む@paramsハッシュが渡されます。
例:
def on_dismiss_popup
id = @params[:button_id]
title = @params[:button_title]
index = @params[:button_index]
if id == 'Yes'
# Handle 'Yes' button
elsif id == 'No'
# Handle 'No' button
elsif id == 'cancel'
# Handle 'Cancel all' button
end
end
- 振動
Alert.vibrate(duration_in_milliseconds)
これは、ミリ秒単位で指定された間、振動します。durationの最大値は25500で、0または指定がない場合2500ミリ秒間振動します。
- play_file
Alert.play_file(file_name.ext, media_type)
これは、メディア・タイプがデバイスでサポートされている場合、指定されたファイルを再生します。ファイルがアプリケーションに含まれる必要があります。ファイルがpublicフォルダ内にあるなら、ファイル名は/apps/public/test-file.mp3となります。メディアタイプは明示的に指定するか、ファイル拡張子から認識されることがあります。既知のファイル拡張子は：.mp3 - audio/mpeg; .wav - audio/x-wav
例
より詳細は、system API sample applicationの/app/Alertフォルダのコントローラとビューを参照してください。
MapView
MapViewクラスは地図アプリケーションが提供するのと同様な埋め込み可能なマップのインターフェイスを提供します。次のコードをコントローラ置くと、ページ全体に地図が表示されます。
注：Android上で使用するには、ここで説明するようにGoogle Add-on APIをインストールしてGoogle Map API keyを取得する必要があります。
map_params = {
:settings => {:map_type => "hybrid",:region => [@params['latitude'], @params['longitude'], 0.2, 0.2],
:zoom_enabled => true,:scroll_enabled => true,:shows_user_location => false,
:api_key => 'Google Maps API Key'},
:annotations => [{:latitude => @params['latitude'], :longitude => @params['longitude'], :title => "Current location", :subtitle => ""},
{:street_address => "Cupertino, CA 95014", :title => "Cupertino", :subtitle => "zip: 95014",
:url => "/app/GeoLocation/show?city=Cupertino"},
{:street_address => "Santa Clara, CA 95051", :title => "Santa Clara", :subtitle => "zip: 95051",
:url => "/app/GeoLocation/show?city=Santa%20Clara"}]
}
MapView.create map_params地図の設定：
- map_type - ウィジェットは3種類の地図を表示することができます：標準、衛星、ハイブリッド
- region - [latitude, longitude, latitudeDelta、longitudeDelta]。エリアはマップビューで実際に表示されます。regionは、latitudeとlongitudeの双方を持ち、地図の中央となり表示を合わせるスパンになります。スパンの値は暗黙的な地図のズーム値を提供します。より広いエリアを表示するには、低いズーム量を指定します。同様に、表示エリアを小さくするには、大きいズーム量を指定します。
- latitude,longitude - 地図は、領域の中心に合わせます
- latitudeDelta - 地図上で表示される南北の距離の量（単位度）。latitudeに基づき変化するlongitudinalとは異なり、latitudeの1度は常に約111キロ（69マイル）です。
- longitudeDelta - 地図上で表示される東西距離の量（単位度）。現在のlatitudeに基づき変化するlongitude範囲によってスパンされるキロメータ量です。たとえば、赤道付近でのlongitudeの1度は約111キロ（69マイル）ですが、北極南極では0キロに縮小します。
- zoom_enabled - 地図のズームが有効なときture
- scroll_enabled - 地図のスクロールが有効なときtrue
- shows_user_location - 現在のユーザーの位置が地図上に表示される場合、true
- api_key - Google Maps APIのキー（ここでサインアップ： http://code.google.com/apis/maps/signup.html ）
Annotations - 地図の注釈オブジェクト（地図上のピンのリスト)。Annotation
- latitude,longitude - 注釈の地図上の座標
- street_address - 地図の座標が指定されていない場合、フレームワークはGoogle geo-codingサービスから指定された住所を使って、座標の取得を試みます。
- タイトル - 注釈吹き出しのタイトル
- サブタイトル - 注釈吹き出しのサブタイトル
- url - ユーザーがボタンをクリックしたときに追従するURL
例
MapViewクラスの使い方のいくつかの例は、system API sample applicationのGeoLocation/controller.rbを参照してください。
ファイルシステムへのアクセス
Rhodesクライアントのファイルシステムの構造
<rhodes root> #system-dependent path
apps #Rho::RhoApplication::get_base_app_path
app #Rho::RhoApplication::get_app_path('app') - contain models
model1 #Rho::RhoApplication::get_model_path('app','model1')
public #contains files from application public folder
db #contains schema and data files
db-files #contains files stored in database(blobs)
# for file paths from camera callback etc: Rho::RhoApplication::get_blob_path(relative_file_path);
# to create file path for blob: Rho::RhoApplication::get_blob_folder()
lib #contains rho framework library files. Blackberry does not has this folder, library files are stored in jar
RhoLog.txt #application log
read/writeファイルの例
fileName = File.join(Rho::RhoApplication::get_base_app_path(), 'myfile.txt')
File.open(fileName).each do |line|
end
fileNameW = File.join(Rho::RhoApplication::get_base_app_path(), 'tempfile.txt')
f = File.new(fileNameW)
f.write('test')
f.close
プラットフォーム別の注意
BlackBerry
- Readのみのファイルは1.4リリースでサポートされてされています。
- シミュレータファイルのフォルダ（4.6以降) - <sdk root>/components/simulator/sdcard/rho/<appname>
- デバイスファイルのフォルダはMedia/Exploreを使って見つけることができます。Media/Exploreはhttp://wiki.rhomobile.com/index.php/Building_Rhodes_Apps_on_Supported_Platforms#Application_log_on_the_device.
iPhone
- シミュレータ・ファイルのフォルダ - デバイスのルートのRhoLog.txtから探してください。ファイルは、シミュレータフォルダ内に置かれます。
Windows Mobile
- デバイス/シミュレータファイルのルートフォルダ - Program Files/<app name>/rho
デスクトップwin32のシミュレータ
- HTTPプロクシでクライアントを使う場合には、最初のコマンドラインの最初の引数にそのURLを指定します -http_proxy_url=http://<login>:<password>@<host>:<port>
またはそれをrhoconfig.txtに追加します。
アプリケーションのアクセス許可（機能）
特定の機能を有効にするには、以下のようにアプリケーションのbuild.ymlを編集します：
capabilities:
- camera
- gps
android:
capabilities:
- network_state
Rhodesは、一般的なそしてプラットフォーム固有の機能をサポートします。それはビルド時に1つのリストで、最終的にマージされます。
今現在Androidでのみサポート。
サポート機能の一覧：
- camera ：ハードウェアカメラの使用許可
- GPS ：GeoLocationサービスの使用許可
- network_stateは ：デバイスのネットワーク状態(接続/切断)の読み取り許可
- 電話 ：電話をかけたり、状態を読み取ったりする許可
- PIM ：個人情報や連絡先を読んだり/変更したりする許可
- 振動 ：ハードウェア振動メカニズムを使用する許可
- プッシュ ：デバイスのプッシュを使用する許可
シャットダウンフック
Rubyで書かれた他のアプリケーションのように、Rhodesはシャットダウンフックを登録することができます。シャットダウンフックはプログラムが終了するときに、実行される登録ルーチンです。これは終了時のクリーンアップ、プログラムの状態を保存などのに便利です。独自のシャットダウンフックを作成するには、ファイルapplication.rbにat_exitブロックを追加してください。たとえば、以下のようになります。
at_exit do
#delete all temporary files
...
...
end
メディアサポート
[2.0で・・・]
投稿
0 件のコメント:
コメントを投稿