["FloatWindow API"]
# Float Window API
Float Window是基於HTML的iframe功能，他允許使用者拖拽，放大縮小，隨意開啟關閉視窗。因為本功能屬於Function Bar的一部份，因此本名稱為"Float Window API"。
Float Window的API可以經ao_module存取，以下是部份基本功能的簡介和範例。
## Float Window 原理
Floa Window原理就是將iframe嵌入div內，使所有WebApp可以提供互動功能。以下是需注意的事項。
1.每個FloatWindow都有唯一的UID。**如果使用同一個UID啟動FloatWindow，則原floatWindow將會被新的floatWindow取代**
2. FloatWindow可以停在屏幕的左或右。但如果以“固定大小模式”啟動，該floatWindow將無法靠左或右。
3. 按兩下floatWindow可最大化窗口。
## 引用ao_module
引用ao_module需要在````部分中包含下面的代碼。 由於ao_module需要jquery，因此請先引用**jquery。***
```
```
##建立Float Window
可以透過ao_module來建立Float Window，啟動方式如下：
###方法1：使用FloatWindow.php建立Float Window
以Float Window模式啟動Module時，部份WebApp可能會有不同的顯示方式。
請使用以下代碼以於Float Window啟動Module。
```
ao_module_launchModule(module_name);
//Example
ao_module_launchModule("Audio");
```
###方法2：使用newfw建立Float Window
這可以用於所有頁面，包括WebApp內外的html，php或任何瀏覽器支援的格式。 newfw使得FloatWindow可顯示任何的網絡資源。請使用以下代碼以於Float Window啟動Module。
```
ao_module_newfw(src,windowname,icon,uid,sizex = undefined,sizey = undefined,posx = undefined,posy = undefined,fixsize = undefined,glassEffect = undefined,parentUID=null, callbackFunct=null)
Example 1: opening the Memo index with the following code:
ao_module_newfw('Memo/index.php','Memo','sticky note outline','memoEmbedded',475,700);
Example 2: opening the Memo index with minimal parameter:
ao_module_newfw('Memo/index.php','Memo','sticky note outline','memoEmbedded');
Example 3: opening a sub-module and tell the sub-module the parent's window id that is not yourself:
ao_module_newfw('Memo/index.php','Memo','sticky note outline','memoEmbedded',undefined,undefined,undefined,undefined,undefined,undefined,"someoneElseUID");
Example 4: opening a sub-module and ask for a callback: (Default parentUID is set to this module's WindowID and hence, the call back will be called to this content window)
ao_module_newfw('Memo/index.php','Memo','sticky note outline','memoEmbedded',undefined,undefined,undefined,undefined,undefined,undefined,undefined,"callBackFunctionName");
```
##Float window屬性
###檢查Float window是否已啟用
要檢查是否啟用了Float window，可以檢查全域變數"ao_module_virtualDesktop"的boolean。以下代碼是示範如何偵測。
```
if (ao_module_virtualDesktop){
//Running in float window mode
}else{
//Running in default mode, might be pwa or just launched as a normal webapp
}
```
### FloatWindow ID、父級和子級
每個FloatWindow都應該要有唯一的ID。在大多數情況下，這可以通過```ao_module_utils.getRandomUID();```取得。每個浮動視窗可能具有父視窗和子視窗，但實際取決於是那一個模組以"newfw()"啟動FloatWindow。JS可以從全域變數中取得這些參數。
```
//Get the float window ID
ao_module_windowID
//Get the caller ID or parent ID
ao_module_parentID
//Get the callback function name from the parent iframe (String, require eval)
ao_module_callback
```
*在不支援浮動視窗的模組，上述所有代碼將會回傳false*
### Float Window CSS 屬性
你亦可以使用下列代碼取得CSS屬性。
```
//Get the float window width
ao_module_getWidth();
//Get the float window height
ao_module_getHeight();
//Get the float window on screen left position
ao_module_getLeft();
//Get the float window on screen top position
ao_module_getTop();
```
## 自訂Float Window
本API可以調整大部份的Float Window設定。例如，開發人員可以使用VDI啟動其 WebApp，並在頁面載入後調整屬性。因此，開發人員可以使用提供的有關的函數調整 iframe 本身的屬性。
下面是一些常用的功能示範。
```
//Set the icon to the given icon class (without "icon"), see Tocas UI > icon for more information.
ao_module_setWindowIcon(icon);
//Change the float window title
ao_module_setWindowTitle(title);
//Enable glassEffect mode on this float window
ao_module_setGlassEffectMode();
//Force float window to be non-resizable
ao_module_setFixedWindowSize();
//Set float window size with the given width and height
//cache: Remember the window size from last launch. Set this to true to allow browser to restore the same window size on launch.
//exact: Require exact URL. Set this to true if you want index.php?var1 and index.php?var2 to have different window size to be remembered by the browser.
ao_module_setWindowSize(width,height,cache,exact);
//Close the current float window
ao_module_close();
```
## 聚焦至特定Float Window
要聚焦至該Float Window，你可以使用下面的參數將該Window聚焦。
```
ao_module_focus();
```
Float Window最多支援 50 個視窗同是運行。所有浮動視窗的 z-index 必須是 100 的偶數和最小要為2。每個浮動Float Window都己經預設阻擋無關的滑鼠事件。
**建議Float Window不要嘗試修改 Z-INDEX**
## 關閉Float Window
如有需要，請使用```ao_module_close();```。按下關閉按鈕的動作事件如下表所列。
使用ao_module
on_close
True
使ao_module函數:ao_module_close()
False
從主頁面移除有關float Window
如要自定關閉時的動作，可以在ao_module中覆蓋"ao_module_close()"函數後另行建立。下面是例子。
```
```
## Float window父和子回傳
可以使用自訂的 pid 和函數名稱調用有關Float window。這功能在需要與父模組進行資料通信的浮動視窗中特別有用。下面是有關範例。
```
//These two meta data will be found on the float window panel
puid //The parent float window UID
callback //The function in parent where the call back should be made in String data type.
```
您可以將一個對象寫進ao_module_parent 的回傳內。 數據將轉換為json並傳遞到接收的Float Window。 這是回傳和關閉子模組的示例。
```
//Assume you are building a file selector
selectedFiles = {"filename":"test.txt","filepath":"/demo/text_files/test.txt"};
if (ao_module_virtualDesktop){
var returnvalue = ao_module_parentCallback(selectedFiles);
if (returnvalue == false){
//Unable to call to parent. Maybe parent is dead or function is not found.
}else{
//Parameter pass through succeed
ao_module_close();
}
}
```
## 系統設置導航功能
文件選擇器目前提供對浮動窗口API的部分支持。在這種情況下，通過php加載的任何頁面在要求`` ao_module_virtualDesktop``是都將會以``true``回傳。 要檢查這是否於導航界面而非FloatWindow，請檢查以下參數（如果要製作的頁面允許從系統設置和浮動窗口模式啟動）。
```
/Return true if this is running under navi.php
parent.underNaviEnv
//Example for using the parameter
if (ao_module_virtualDesktop && parent.underNaviEnv){
//Launch inside System Setting interface
}else if (ao_module_virtualDesktop){
//Launch inside float window mode
}else{
//Otherwise
}
```