============================================================================= pfterm - piaip's flat terminal system also as the "Perfect Term" API Manual 函式說明手冊 VERSION 1.1 最後更新: 2007/12/24 18:00 piaip ============================================================================= pfterm 是為了解決 non-ANSI based terminal 處理日漸困難的問題而誕生的。 舊有的系統 (screen.c) 假設輸出的資料全是單純的 ASCII 文字， 所以在處理 DBCS以及 ANSI 碼的時候非常容易誤判或輸出不足的資料。 另外緩衝區字串大小 (ANSILINELEN) 造成的浪費也是個問題。 pfterm 的螢幕處理方式是自為一個虛擬的 DBCS-aware ANSI Terminal， 在更新時才即時產生最佳化的輸出。 ============================================================================= pfterm API 是以 ncurses-like 為基礎。 以 fterm_* 為開頭的 API, 多半是 pfterm 內部使用的函式； 而跟 ncurses 同名或相近的 API 則是一般程式使用的部份。 ============================================================================= //// common ncurse-like library interface //// ncurse 相容部份 // initialization 初始化 void initscr (void); 初始系統 int resizeterm (int rows, int cols); 調整視窗大小為(rows,col) int endwin (void); 結束系統 // cursor 游標 void getyx (int *y, int *x); 取得目前游標位置 void move (int y, int x); 移動游標 // clear 清除畫面 void clear (void); 清除螢幕並回到原點(0,0) void clrtoeol (void); 清至行尾 void clrtobot (void); 清至螢幕底部 // clear (non-ncurses) 清除(非標準，不建議使用) void clrtoln (int ln); 從目前行往下清至(不包含)ln行:[y,ln) void clrcurln (void); 清除目前行, 相當於 clrtoln(y+1) void clrtobeg (void); 清至行首 void clrtohome (void); 清至螢幕原點(0,0) void clrscr (void); 清除螢幕但不回到原點 void clrregion (int r1, int r2); 清除[r1,r2]或[r2,r1]的範圍 (雙向) // flushing 更新畫面 void doupdate (void); 更新畫面 (只送出改變的部份) void refresh (void); 更新畫面 (若有輸入按鍵則不更新) void redrawwin (void); 強制下次更新全部畫面(仍需 refresh) // scrolling 捲動 void scroll (void); 向上捲動一行 void rscroll (void); 向下捲動一行 void scrl (int rows); 捲動 rows 行 (正值往上負值往下) // scrolling (non-ncurses) 捲動(非標準，不建議使用) void region_scroll_up(int top, int bot); 上捲一行 [top,bot] 的內容 // attributes 顏色與屬性 ftattr attrget (void); 讀取目前屬性 void attrset (ftattr attr); 設定屬性 void attrsetfg (ftattr attr); 設定前景色 (0-7) void attrsetbg (ftattr attr); 設定背景色 (0-7) // output (non-ncurses) 輸出 (非 ncurses 風格) void outc (unsigned char c); 輸出字元 (可含 ANSI 控制碼) void outs (const char *s); 輸出字串 (可含 ANSI 控制碼) void outstr (const char *str); 輸出完整字串 (可含ANSI控制碼) P.S: 差異在於， outstr() 會先計算所需的空間，並把該處正確清除掉， outstr() 內建 DBCS 的辨識能力，所以不會蓋字只蓋到一半變亂碼。 outc/outs 則是無視舊內容直接覆蓋。 但注意 outstr 目前並不會去考慮 str 本身是否真為完整 DBCS 字串。 // readback 讀取螢幕上的文字 int instr (char *str); 把游標處的字串讀回到 str 處 int innstr (char *str, int n); 把游標處最多 n 個字元讀回 str int inansistr (char *str, int n); 讀回有 ANSI 控制碼格式的字串。 P.S: 注意 inansistr 通常需要比較長的空間 (建議使用 ANSILINELEN) 結尾會設回標準的屬性 (ESC[m)，若空間不足則中間會掉字。 in*str 傳回的是所讀到的字元數。 // restore 回存 void scr_dump (void *psb); 將目前畫面存入 psb void scr_restore (void *psb); 由 psb 讀出畫面並釋放資源 目前的 psb 接受的是 screen_backup_t*, dump 前不需初始 dump 會為它配置記憶體，restore 則會釋放， 所以一定要成對。 // grayout Grayout 淡入淡出系統 void grayout (int y, int end, int level); 將區間 [y, end] 的內容作淡出或淡入的處理。 level 控制色彩: GRAYOUT_DARK: 轉為暗色字 GRAYOUT_BOLD: 轉為亮色字 GRAYOUT_NORM: 轉為無色彩的普通字 // deprecated 建議停用部份 void standout (void); 屬性設為反白 void standend (void); 重設屬性 註: pfterm 目前並未真的支援 stand 屬性，所以只是假的反白效果。 move() 至該位置再畫字則屬性會改變。 ============================================================================= //// flat-term internal processor //// pfterm 內部函式 要將 pfterm 接上某個底層 (網路/BBS/檔案/...) 只要定義好幾個 轉接函式即可快速移植: int fterm_inbuf (void); // raw input adapter 鍵盤輸入的轉接函式，傳回是否仍有未讀取的輸入。 (最佳化 refresh 用) void fterm_rawc (int c); // raw output adapter 輸出的基本轉接函式，輸出一個字元到底層系統。 void fterm_rawnewline(void); // raw output adapter 輸出的基本轉接函式，輸出一個換行符號到底層系統。 void fterm_rawflush (void); // raw output adapter 輸出的基本轉接函式，送出所有已輸出的內容到底層系統。 ------------------------------------------------------------------------------ 下面是呼叫轉接函式的基本命令: void fterm_raws (const char *s); 輸出字串 void fterm_rawnc (int c, int n); 輸出 n 個重複的字元 c void fterm_rawnum (int arg); 輸出數字 void fterm_rawcmd (int arg, int defval, char c); 輸出 ANSI 命令 void fterm_rawcmd2 (int arg1, int arg2, int defval, char c); rawcmd/rawcmd2 會輸出 ESC_CHR '[' arg ';' arg2 c 的命令 若 arg/arg2 與 defval 相等則該參數會忽略不印 void fterm_rawattr (ftattr attr); 改變底層輸出屬性與色彩 void fterm_rawclear (void); 輸出清除全部畫面(不移動)的命令 void fterm_rawclreol (void); 輸出清至行尾的命令 void fterm_rawhome (void); 輸出移至原點(0,0)的命令 void fterm_rawscroll (int dy); 捲動螢幕 dy 行，正往上負往下 void fterm_rawcursor (void); 更新底層游標的位置與屬性 void fterm_rawmove (int y, int x); 移動底層游標到指定的位置 void fterm_rawmove_opt(int y, int x); 最佳化移動游標 void fterm_rawmove_rel(int dy, int dx); 移動底層游標到指定的相對位置 int fterm_chattr (char *s, 將屬性從 oattr 轉為 nattr 所需的 ftattr oattr, ftattr nattr); ANSI 控制碼輸出至 s 處。 注意s要夠長(起碼要 FTATTR_MINCMD=16 字元), 考慮相容性建議 32 以上。 下面是內部函式，不建議直接使用: void fterm_markdirty (void); 標記目前畫面需要更新 void fterm_exec (void); (內部用)執行已收集到的 ANSI 命令 void fterm_flippage (void); (內部用)切頁 (pfterm 為 dual buffer) void fterm_dupe2bk (void); (內部用)同步背景頁 int fterm_prepare_str(int len); (內部用)安全清除長度為 len 的空間 ============================================================================= // vim:expandtab:sw=4:ts=4