=============================================================================

    pfterm - piaip's flat terminal system
    also as the "Perfect Term"

    API Manual
    �禡������U

    VERSION 1.1
    �̫��s: 2007/12/24 18:00   piaip

=============================================================================

    pfterm �O���F�ѨM non-ANSI based terminal �B�z�麥�x�������D�ӽϥͪ��C 
    �¦����t�� (screen.c) ���]��X����ƥ��O��ª� ASCII ��r�A
    �ҥH�b�B�z DBCS�H�� ANSI �X���ɭԫD�`�e���~�P�ο�X��������ơC
    �t�~�w�İϦr��j�p (ANSILINELEN) �y�������O�]�O�Ӱ��D�C

    pfterm ���ù��B�z�覡�O�۬��@�ӵ����� DBCS-aware ANSI Terminal�A
    �b��s�ɤ~�Y�ɲ��ͳ̨Τƪ���X�C

=============================================================================

    pfterm API �O�H ncurses-like ����¦�C
    �H fterm_* ���}�Y�� API, �h�b�O pfterm �����ϥΪ��禡�F
    �Ӹ� ncurses �P�W�ά۪� API �h�O�@��{���ϥΪ������C

=============================================================================

//// common ncurse-like library interface   
//// ncurse �ۮe����

// initialization   ��l��
void    initscr     (void);                 ��l�t��
int     resizeterm  (int rows, int cols);   �վ�����j�p��(rows,col)
int     endwin      (void);                 �����t��

// cursor           ���
void    getyx       (int *y, int *x);       ���o�ثe��Ц�m
void    move        (int y, int x);         ���ʴ��

// clear            �M���e��
void    clear       (void);                 �M���ù��æ^����I(0,0)
void    clrtoeol    (void);                 �M�ܦ��
void    clrtobot    (void);                 �M�ܿù�����

// clear (non-ncurses)  �M��(�D�зǡA����ij�ϥ�)
void    clrtoln     (int ln);               �q�ثe�橹�U�M��(���]�t)ln��:[y,ln)
void    clrcurln    (void);                 �M���ثe��, �۷��� clrtoln(y+1)
void    clrtobeg    (void);                 �M�ܦ歺
void    clrtohome   (void);                 �M�ܿù����I(0,0)
void    clrscr      (void);                 �M���ù������^����I
void    clrregion   (int r1, int r2);       �M��[r1,r2]��[r2,r1]���d�� (���V)

// flushing         ��s�e��
void    refresh     (void);                 ��s�e�� (�u�e�X���ܪ�����)
void    redrawwin   (void);                 �j��U����s�����e��(���� refresh)

// scrolling        ����
void    scroll      (void);                 �V�W���ʤ@��
void    rscroll     (void);                 �V�U���ʤ@��
void    scrl        (int rows);             ���� rows �� (���ȩ��W�t�ȩ��U)

// scrolling (non-ncurses) ����(�D�зǡA����ij�ϥ�)
void    region_scroll_up(int top, int bot); �W���@�� [top,bot] �����e

// attributes       �C��P�ݩ�
ftattr  attrget     (void);                 Ū���ثe�ݩ�
void    attrset     (ftattr attr);          �]�w�ݩ�
void    attrsetfg   (ftattr attr);          �]�w�e���� (0-7)
void    attrsetbg   (ftattr attr);          �]�w�I���� (0-7)

// output (non-ncurses) ��X (�D ncurses ����)
void    outc        (unsigned char c);      ��X�r�� (�i�t ANSI ����X)
void    outs        (const char *s);        ��X�r�� (�i�t ANSI ����X)
void    outstr      (const char *str);      ��X����r�� (�i�tANSI����X)

            P.S: �t���b��A outstr() �|���p��һݪ��Ŷ��A�ç�ӳB���T�M�����A
            outstr() ���� DBCS �����ѯ�O�A�ҥH���|�\�r�u�\��@�b�ܶýX�C
            outc/outs �h�O�L���¤��e�����л\�C
            ���`�N outstr �ثe�ä��|�h�Ҽ{ str �����O�_�u������ DBCS �r��C

// readback         Ū���ù��W����r
int     instr       (char *str);            ���гB���r��Ū�^�� str �B
int     innstr      (char *str, int n);     ���гB�̦h n �Ӧr��Ū�^ str 
int     inansistr   (char *str, int n);     Ū�^�� ANSI ����X�榡���r��C

            P.S: �`�N inansistr �q�`�ݭn��������Ŷ� (��ij�ϥ� ANSILINELEN)
            �����|�]�^�зǪ��ݩ� (ESC[m)�A�Y�Ŷ������h�����|���r�C
            in*str �Ǧ^���O��Ū�쪺�r���ơC

// restore          �^�s
void    scr_dump    (void *psb);            �N�ثe�e���s�J psb
void    scr_restore (void *psb);            �� psb Ū�X�e��������귽

            �ثe�� psb �������O screen_backup_t*, dump �e���ݪ�l
            dump �|�����t�m�O����Arestore �h�|����A
            �ҥH�@�w�n����C

// grayout          Grayout �H�J�H�X�t��
void    grayout     (int y, int end, int level);

            �N�϶� [y, end] �����e�@�H�X�βH�J���B�z�C level �����m:
            GRAYOUT_DARK:   �ର�t��r
            GRAYOUT_BOLD:   �ର�G��r
            GRAYOUT_NORM:   �ର�L��m�����q�r

// deprecated       ��ij�����
void    standout    (void);                 �ݩʳ]���ϥ�
void    standend    (void);                 ���]�ݩ�

            ��: pfterm �ثe�å��u���䴩 stand �ݩʡA�ҥH�u�O�����ϥծĪG�C
            move() �ܸӦ�m�A�e�r�h�ݩʷ|���ܡC

=============================================================================

//// flat-term internal processor
//// pfterm �����禡

        �n�N pfterm ���W�Y�ө��h (����/BBS/�ɮ�/...) �u�n�w�q�n�X��
        �౵�禡�Y�i�ֳt����:

int     fterm_inbuf     (void);         // raw input  adapter
            ��L��J���౵�禡�A�Ǧ^�O�_������Ū������J�C (�̨Τ� refresh ��)

void    fterm_rawc      (int c);        // raw output adapter
            ��X�����౵�禡�A��X�@�Ӧr���쩳�h�t�ΡC

void    fterm_rawnewline(void);         // raw output adapter
            ��X�����౵�禡�A��X�@�Ӵ���Ÿ��쩳�h�t�ΡC

void    fterm_rawflush  (void);         // raw output adapter
            ��X�����౵�禡�A�e�X�Ҧ��w��X�����e�쩳�h�t�ΡC

------------------------------------------------------------------------------

        �U���O�I�s�౵�禡���򥻩R�O:

void    fterm_raws      (const char *s);                ��X�r��
void    fterm_rawnc     (int c, int n);                 ��X n �ӭ��ƪ��r�� c
void    fterm_rawnum    (int arg);                      ��X�Ʀr

void    fterm_rawcmd    (int arg, int defval, char c);  ��X ANSI �R�O
void    fterm_rawcmd2   (int arg1, int arg2, int defval, char c);

            rawcmd/rawcmd2 �|��X ESC_CHR '[' arg ';' arg2 c ���R�O
            �Y arg/arg2 �P defval �۵��h�ӰѼƷ|�������L

void    fterm_rawattr   (ftattr attr);      ���ܩ��h��X�ݩʻP��m
void    fterm_rawclear  (void);             ��X�M�������e��(������)���R�O
void    fterm_rawclreol (void);             ��X�M�ܦ�����R�O
void    fterm_rawhome   (void);             ��X���ܭ��I(0,0)���R�O
void    fterm_rawscroll (int dy);           ���ʿù� dy ��A�����W�t���U
void    fterm_rawcursor (void);             ��s���h��Ъ���m�P�ݩ�
void    fterm_rawmove   (int y, int x);     ���ʩ��h��Ш���w����m
void    fterm_rawmove_opt(int y, int x);    �̨ΤƲ��ʴ��
void    fterm_rawmove_rel(int dy, int dx);  ���ʩ��h��Ш���w���۹��m

int     fterm_chattr    (char *s,           �N�ݩʱq oattr �ର nattr �һݪ� 
            ftattr oattr, ftattr nattr);    ANSI ����X��X�� s �B�C
                                            �`�Ns�n����(�_�X�n FTATTR_MINCMD=16 
                                            �r��), �Ҽ{�ۮe�ʫ�ij 32 �H�W�C

        �U���O�����禡�A����ij�����ϥ�:

void    fterm_markdirty (void);             �аO�ثe�e���ݭn��s
void    fterm_exec      (void);             (������)����w�����쪺 ANSI �R�O
void    fterm_flippage  (void);             (������)���� (pfterm �� dual buffer)
void    fterm_dupe2bk   (void);             (������)�P�B�I����
int     fterm_prepare_str(int len);         (������)�w���M�����׬� len ���Ŷ�

=============================================================================
// vim:expandtab:sw=4:ts=4