行動 AIR 應用程式專屬的 ActionScript API

下列 API 只能用於行動裝置上的 AIR 應用程式。它們目前無法在 Flash Player 或 AIR 的桌上型電腦版本上運作。

螢幕方向 API

螢幕方向 API 可讓您操作舞台和 iPhone 的方向：

• Stage.autoOrients ：應用程式是否設定成允許舞台在裝置旋轉時，自動調整方向。在 Flash Professional CS5「iPhone 設定」對話方塊中選取「自動方向」選項時，此屬性會設定成 true (您也可以在應用程式描述器檔案中，將 autoOrients 元素設定成 true )。請參閱 iPhone 應用程式設定 。替 Stage 物件新增 orientationChanging 事件偵聽程式，就可以取消自動方向調整。呼叫此事件物件的 preventDefault() 方法會取消自動方向調整。

  使用自動方向時，如果要得到最佳結果，請將舞台的 align 屬性設定成以下項目：

  stage.align = StageAlign.TOP_LEFT; 
  stage.scaleMode = StageScaleMode.NO_SCALE;

• Stage.deviceOrientation ：裝置的實際方向。StageOrientation 類別會定義此屬性的值。

• Stage.orientation ：舞台目前的方向。StageOrientation 類別會定義此屬性的值。

• Stage.supportsOrientationChange ：在 iPhone 設定為 true ，而在 AIR 應用程式設定為 false 。

• Stage.setOrientation() ：設定舞台的方向。此方法有一個參數，該參數是定義新舞台方向的字串。StageOrientation 類別的常數會定義該參數的可能值。

• StageOrientation：定義舞台方向值。例如， StageOrientation.ROTATED_RIGHT 表示舞台會以裝置的預設方向為基準向右旋轉。

• StageOrientationEvent：定義螢幕方向變更後，Stage 要傳送的事件。當使用者旋轉 iPhone 時即會發生此事件。目前有兩種類型的事件。當裝置旋轉時，Stage 會傳送 orientationChanging 事件。若要禁止舞台重新轉向，請呼叫 orientationChanging 事件物件的 preventDefault() 方法。當舞台重新轉向後，Stage 會傳送 orientationChange 事件。

目前，螢幕方向 API 只能用於行動裝置的 AIR 應用程式。如果行動裝置 AIR 應用程式與桌上型電腦 AIR 應用程式共享原始碼，請使用 Stage.supportsOrientationChange 屬性檢查是否支援此 API。

以下範例顯示使用者旋轉裝置時將產生的回應：

stage.addEventListener(StageOrientationEvent.ORIENTATION_CHANGE, 
            onOrientationChange); 
 
function onOrientationChange(event:StageOrientationEvent):void 
{ 
    switch (event.afterOrientation) { 
        case StageOrientation.DEFAULT: 
            // re-orient display objects based on 
            // the default (right-side up) orientation. 
            break; 
        case StageOrientation.ROTATED_RIGHT: 
            // Re-orient display objects based on 
            // right-hand orientation. 
            break; 
        case StageOrientation.ROTATED_LEFT: 
            // Re-orient display objects based on 
            // left-hand orientation. 
            break; 
        case StageOrientation.UPSIDE_DOWN: 
            // Re-orient display objects based on 
            // upside-down orientation. 
            break; 
}

在此範例中，我們將針對不同的舞台方向提供註解 (並非功能程式碼)。

您可以呼叫 Stage 物件的 setOrientation() 方法來變更舞台方向。設定方向是一項非同步作業。您可以偵聽 orientationChange 事件，檢查方向轉換何時完成。以下的程式碼顯示如何將舞台設定成向右轉：

stage.addEventListener(StageOrientationEvent.ORIENTATION_CHANGE, 
            onOrientationChange); 
stage.setOrientation(StageOrientation.ROTATED_RIGHT); 
 
function onOrientationChange(event:StageOrientationEvent):void 
{ 
    // Code to handle the new Stage orientation 
}

當 Stage 旋轉時即會調整大小，而 Stage 物件會傳送 resize 事件。您可以在 Stage 調整並重新放置顯示物件，以回應 resize 事件。

NativeApplication.systemIdleMode 與 SystemIdleMode

NativeApplication.systemIdleMode 屬性可防止 iPhone 進入閒置模式。根據預設，若一段時間沒有使用觸控螢幕，iPhone 便會進入閒置模式。閒置模式不但會讓螢幕變暗，也會讓 iPhone 進入鎖定模式。此屬性可設定為下列其中一個值：

僅支援在行動裝置上使用此功能。不支援在桌上型電腦作業系統上執行的 AIR 應用程式。在桌上型電腦上執行的應用程式中，設定 NativeApplication.systemIdleMode 屬性不會有任何作用。

以下程式碼顯示如何停用 iPhone 閒置模式：

NativeApplication.nativeApplication.systemIdleMode = SystemIdleMode.KEEP_AWAKE;

CameraRoll

CameraRoll 類別可讓您在 iPhone「相機膠捲」中新增影像。 addBitmapData() 方法可新增影像到 iPhone「相機膠捲」。此方法含參數 bitmapData 。此參數為 BitmapData 物件，其中包含要新增到「相機膠捲」的影像。

僅支援在行動裝置上使用「相機膠捲」功能。不支援在桌上型電腦作業系統上執行的 AIR 應用程式。若要在執行階段時，檢查應用程式是否支援 CamerRoll 功能，請檢查靜態 CameraRoll.supportsAddBitmapData 屬性。

呼叫 addBitmapData() 方法後，CameraRoll 物件會傳送下列其中一個事件：

下列程式碼會將舞台的影像 (螢幕擷取) 新增到「相機膠捲」：

if (CameraRoll.supportsAddBitmapData) 
{ 
    var cameraRoll:CameraRoll = new CameraRoll(); 
    cameraRoll.addEventListener(ErrorEvent.ERROR, onCrError); 
    cameraRoll.addEventListener(Event.COMPLETE, onCrComplete); 
    var bitmapData:BitmapData = new BitmapData(stage.stageWidth, stage.stageHeight); 
    bitmapData.draw(stage); 
    cameraRoll.addBitmapData(bitmapData); 
} 
else 
{ 
    trace("not supported."); 
} 
 
function onCrError(event:ErrorEvent):void 
{ 
    // Notify user. 
} 
 
function onCrComplete(event:Event):void 
{ 
    // Notify user. 
}

DisplayObject.cacheAsBitmapMatrix

cacheAsBitmapMatrix 屬性為 Matrix 物件，定義當 cacheAsBitmap 設定為 true 時，該如何呈現顯示物件。當您要呈現顯示物件的點陣圖版本時，應用程式會使用此矩陣做為變形矩陣。

設定 cacheAsBitmapMatrix 後，應用程式會使用該矩陣 (而不是顯示矩陣) 來取得顯示的快取點陣圖影像。(顯示矩陣為顯示物件的 transform.concatenatedMatrix 值)。如果此矩陣與顯示矩陣不符，則點陣圖會視需要加以縮放或旋轉。

設定 cacheAsBitmapMatrix 的顯示物件，只會在 cacheAsBitmapMatrix 值變更時顯示。點陣圖會適當縮放或旋轉以符合顯示矩陣。

CPU 和 GPU 顯示都同時受益於使用 cacheAsBitmapMatrix 屬性，但一般而言 GPU 顯示受益較多。

例如，下列程式碼使用顯示物件的未變形點陣圖形式：

matrix:Matrix = new Matrix(); // creates an identity matrix 
mySprite.cacheAsBitmapMatrix = matrix; 
mySprite.cacheAsBitmap = true;

下列程式碼使用符合目前顯示方式的點陣圖形式：

mySprite.cacheAsBitmapMatrix = mySprite.transform.concatenatedMatrix; 
mySprite.cacheAsBitmap = true;

一般而言，使用單位矩陣 ( new Matrix() ) 或 transform.concatenatedMatrix 就已足夠。但您可以使用其他矩陣 (例如縮小矩陣) 將不同的點陣圖上傳至 GPU。例如，下列範例套用將 x 和 y 軸縮小為 0.5 倍的 cacheAsBitmapMatrix 矩陣。GPU 使用的點陣圖物件雖然較小，但 GPU 會調整大小以符合顯示物件的 transform.matrix 屬性：

matrix:Matrix = new Matrix(); // creates an identity matrix 
matrix.scale(0.5, 0.5); // scales the matrix 
mySprite.cacheAsBitmapMatrix = matrix; 
mySprite.cacheAsBitmap = true;

一般而言，您所選擇的矩陣必須會將顯示物件變形為應用程式中顯示的大小。例如，如果應用程式顯示縮小一半的 Sprite 點陣圖版本，請使用會縮小一半的矩陣。如果應用程式將顯示大於目前尺寸的 Sprite，請使用會放大比率的矩陣。

設定 cacheAsBitmapMatrix 屬性的顯示物件大小是有限制的。限制為 1020 x 1020 像素。設定 cacheAsBitmapMatrix 屬性的所有顯示物件像素總數是有限制的。限制大約為四百萬像素。

使用 cacheAsBitmapMatrix 與硬體加速時需考量多項因素。您必須知道哪些顯示物件需要設定屬性，而哪些不需要。如需使用此屬性的重要資訊，請參閱 硬體加速 。

您可以使用 GPU 顯示診斷功能，診斷應用程式除錯版本的 GPU 使用量。如需詳細資訊，請參閱 iPhone 應用程式除錯 。

網路注意事項

使用以下的 URL 配置加上 nativigateToURL() 函數，可在外部的應用程式中開啟文件：

str = "mailto:test@example.com"; 
var urlReq:URLReq = new URLRequest(str); 
navigateToURL(urlReq);

str = "sms:1-415-555-1212"; 
var urlReq:URLReq = new URLRequest(str); 
navigateToURL(urlReq);

str = "tel:1-415-555-1212"; 
var urlReq:URLReq = new URLRequest(str); 
navigateToURL(urlReq);

iPhone 應用程式在安全交易時 (例如 https 要求)，會依賴安裝的自我簽署根憑證來進行伺服器驗證。伺服器不應只傳送分葉憑證，而是必須將所有中繼憑證鏈結傳送至根憑證。