acs-api快速入門(1) - ScriptCore

前面已經介紹過acs-api在系統中的角色了，這邊就直接切入程式的部分吧!

首先從package的分類開始看

PACKAGE	說明
acscriptcore	腳本核心
acscriptcore.period	週期控制
acscriptcore.inpcom	圖形輸入元件
acscriptcore.datactnr	資料容器
acscriptcore.dataset	資料集
acscriptcore.calc	統計運算
acscriptcore.layer	圖層類
acscriptcore.table	表格類
acscriptcore.gears	小工具

這些PACKAGE中約莫有50個類別，要都看一遍?實在很乏味...所以這一系列講api的文章，我盡量挑常用的講，用瀏覽的方式看過一遍即可，是你用得上的東西自然就會記住，暫時用不上的留個印象即可，往後會再拿腳本實例來說明如何使用，就比較會不感到艱澀，或硬要搞懂一些與自身無關的東西，浪費時間。



然而最詳細準確的asc-api內容架構仍請參考docs/acsapi/index.html


acscriptcore - 腳本核心
與腳本運作有最直接的關聯。

ScriptCore類別 : 一直不斷的提到core、核心、腳本核心一詞，好像有些抽象，具體說到底是什麼?其實就是一個讓腳本能夠正常運作的內部機制，而這個機制主要來自於繼承ScriptCore，所以每個腳本的MyScript類別都必須繼承ScriptCore，無論是透過CustomCore或CustomCorePersonal都會繼承到ScriptCore。


系統執行常數。腳本中用來參考得知以何設定執行，也就是說這些變數是拿來讀的，不能寫入。

型別	名稱	說明
int	_SETTING_KSCALE_PERIOD	週期類型(年、月、周、日、分、秒等...)
int	_SETTING_KSCALE_N	週期基數
int	_SETTING_KSCALE_PRECISE	資料源刻度
String	symbol	符號(代碼)
String	name	符號名稱

系統執行變數。

型別	名稱	說明
int	t	時間點。從0起算，每根K棒+1。
int	tickofbar	當下K棒執行(run)的次數，即報價(Tick)次數。
int	tickofday	當日執行(run)的次數。
int	barofday	當下K棒位於當日的第幾根K棒
int	barsofaday	前日的K棒數量
int	tradedays	當下經過的交易天數
boolean	isEOH	歷史報價結束
boolean	isRTQuote	即時報價開始
boolean	isNewMin	此次報價為新的1分鐘

報價變數。為一類似陣列的型態，後面會再提及。

型別	名稱	說明
MovinDate	date	日期
MovinNum	close	收盤價
MovinNum	open	開盤價
MovinNum	high	最高價
MovinNum	low	最低價
MovinNum	vol	成交量

紀錄參考變數。大致都是記錄前一次報價的狀況，方便在下一次做比較，例如是否創新高、報價的單量等都可推算。

型別	名稱	說明
Date	first_date	第一個執行的日期
Date	prev_date	前一個執行的日期
double	prev_tick	前一個執行的收盤價位
double	prev_high	前一個執行的高點價位(當下K棒)
double	prev_low	前一個執行的低點價位(當下K棒)
long	prev_vol	前一個執行的量(當下K棒)

可控制物件。

型別	名稱	說明
DbgWin	dbg	除錯視窗
Table	tbl	列表控制元件
QUOTE	ds	報價資料集合

新增動態數字陣列。

函數	說明
MovinNum addMovinNum()	新增動態數字陣列
MovinNum addMovinNum(Number value)	新增動態數字陣列並給予初始值
MovinNum joinMovinNum(MovinNum arr)	加入動態數字陣列。同addMovinNum，但自己宣告arr物件。
MovinNum addSyncMovinNum(MovinNum arr)	新增動態數字陣列，並指定該陣列尾端數據與arr同步。
MovinNum addSyncMovinNum(MovinNum arr, int sync_sft)	同上，但同步的位置加上位移。

這個部分會稍微有點混亂。所謂"動態數字陣列"就是一個隨著K棒數量增加的陣列，要得到一個這樣的物件除了將他宣告實體化出來以外，還必須透過add或join讓ScriptCore認識，ScriptCore就會適時的替它增加資料量。當然也可以選擇不要add或join，改採自己增加資料量的方式(push)，也就是讓這個"動態數字陣列"做為一個"異步資料"，意即資料量與ScriptCore不相當，沒辦法用系統t取到t時間的值。在資料容器中會有範例。

另外後兩項也提到"同步"(sync)，但這裡指的同步就不是資料量的同步，而是"值"的同步。


加入合作物件或子核心。

函數	說明
void addCorePartner(CorePartner listener)	加入與Core合作的物件
removeCorePartner(CorePartner listener)	移除與Core合作的物件
boolean addInnerCore(ScriptCore inner_core, String symbol, Date from_date, Date end_date, int kscale_n, int kscale_period, int kscale_precise, boolean exec_inside)	加入另一個core(子核心)與當下的core時間同步執行
boolean isInnerCore()	判斷是否為子核心
void removeInnerCore(ScriptCore inner_core)	移除同步執行的core

CorePartner是一個介面類別(Interface)，所謂介面類別就像是一個模型外觀，只要仿造這個外觀再實做(implements)內容，就可以符合規範與特定api接合，就像是手機充電孔一樣，只要接頭符合就插得進去，不一定只能充電。
也就是說只要你有一個物件符合CorePartner的介面就可以加入核心，與核心同步執行，詳細的介面內容後面會再介紹。
而InnerCore(子核心)，有"內插"的意涵，作用就是可以在一個腳本核心裡面再建立核心，變成一個主核心+N個子核心的應用，就能夠一併分析或整合更多的資訊。


外觀控制。

函數	說明
void changeView(ScriptCore core)	切換當下圖格顯示的腳本核心
void changeView(String chart_name, ScriptCore core)	切換特定圖格顯示的腳本核心
void assignChartsSymbol(String symbol)	模擬類似在列表上點擊標的物的動作
void moveChartToFrom(Date date)	移動圖格起始日期
void moveChartToEnd(Date date)	移動圖格結束日期
void moveChartToRange(Date date1, Date date2)	移動圖格到區間日期
boolean saveChartImage(int width, int height, File file)	將圖格存成圖檔

資料或報價查詢。

函數	說明
Quote queryPrice(String symbol, Date date, int precise)	查詢標的物特定時間的報價
Object[] queryData(String symbol, Date date, String fmtID)	查詢標的物特定時間的資料

類別建構子	說明
PriceFlow(String symbol, int precise)	報價流。報價內容將隨著主腳本的時間自動更新。
DataFlow(String symbol, String fmtID)	資料流。資料內容將隨著主腳本的時間自動更新。

其他...

函數	說明
Layer addLayer(Layer master, int z_order, String params)	新增圖層
void updateTitle(String text)	更新圖格資訊標題(TitleBar)。使用HTML。
void updateInput(String text)	更新輸入面板。使用HTML。
void stop()	終止腳本執行。在列表腳本中若非即時盤應用，都需在最後加上stop()，避免佔用記憶體。
void restart()	重新執行腳本

參數實體。

函數	說明
void addParamIns(ParamIns obj)	加入參數實體
void removeParamIns(ParamIns ins)	移除參數實體
void clearParamIns(ParamIns ins)	清除參數實體的所有參數紀錄
boolean isParamRecored(ParamIns ins, String vname)	檢查某"參數實體"的參數是否已記錄
Args getInsParams(ParamIns ins, Class cls)	取得某"參數實體"的全部已記錄參數
boolean recParam(ParamIns ins, String vname)	記錄某"參數實體"的特定參數
InpComponent getInpComp(ParamIns ins, String vname)	取得屬於某特定參數實體的某項輸入元件

參數實體(ParamIns)指的是一個變數可以被記錄的物件，所以某個物件只要實做ParamIns的介面就可以擁有變數被記錄的特性。舉例說我們一直在用的MyScript就是一個ParamIns，因為MyScript繼承了ScriptCore，而ScriptCore裡實做(implements)了ParamIns的介面，如果你自己做的物件也需要這樣的功能，那就實做ParamIns介面吧。
這個部分與"輸入元件"是相關聯的，因為輸入元件的調整的參數就是對應到ParamIns中的變數。


面板元件。

類別	說明
class AcPanel	AC中用來取代JPanel
class AcTabbedPane	AC中用來取代JTabbedPane
class HtmlPanel	HTML面板
class AcTable	表格類別

AcPanel與AcTabbedPane主要用於圖格的側邊選單，能夠記錄前次操作停留的位置。HtmlPanel主要用來顯示"輸入元件"，所有的輸入元件都是轉成HTML碼顯示。


輸入元件。

類別	說明
class InpNum	數字
class InpDate	日期
class InpSlt	選項1(Spinner)
class InpSlt2	選項2(ComboBox)
class InpMenu	選單(matrix)
class InpText	字串欄
class InpBtn	按鈕
class InpChk	勾選元件-True/False
class InpChk_S	勾選元件-多選一
class InpColor	顏色選擇
class InpLab	文字標籤(類似InpBtn)

acscriptcore.inpcom - 圖形輸入元件
這個部分其實只剩下類別介面(Interface)與輸入元件的父類別，真正會被實體化的輸入元件都直接宣告在ScriptCore裡了(InpNum、InpDate...)，所以這個部分沒什麼好看的了，後續再看看輸入元件的使用範例即可。

---

沒想到簡短的整理出來還是這麼一長串，但應該還是比直接看文件有系統性。接著挑戰吧!