
History
    98/09/29 First version
    99/09/30 English version

Title  List of onHand/Ruputer rupmenu commands

Heaader file name
    rupmenu.h

  In the following, we made input menu functions:

         #### Input ####
            A   >> No
            B   >  Yes

  We provide input means shown in the above examples.
  We also prepared customize extension functions.
 
  If you wish to use rupmenu library, add rupmenu.h to a header file.

Table of Contens
    1.INPUTITEM Structure
    2.Input Menu Functions

--------------------------------------------------------------------------------
1.INPUTITEM Structure     ...  A set value of each item of the menu is set.
typedef struct {
    int  myid;          /* ID                        */
    char *myname;       /* Title name                */
    int  ydot;          /* Display dot:y             */
    int  xdir;          /* <<>>Direction display     */
    int  chmode;        /* Display mode            0:Input 1:PlainMenu 2:InputEx       */
                        /*                         3:Time  4:TimeZone  5:Date          */
                        /*                         6:....user extention                */
    int  dspmode;       /* Selection display mode  0: Flash 1:Invert                   */
    int  disable;       /* Valid/Invalid           0:Valid 1:invalid                   */
    int  xlistL;        /* List left coordinate                                        */
    int  xlistR;        /* List right coordinate                                       */
    char *list;         /* Head address of list data                                   */
    int  listnum;       /* Number of lists                                             */
    int  listlen;       /* List character length                                       */
    int  listval;       /* List selection value                                        */
    int  listtgl;       /* List change method 0:Non-toggle          1:Toggle           */
                        /*                    2:Inverted non-toggle 3:Inverted toggle  */
    int  (*listEx)(int,int,int);
                        /* List display customize functions                            */
    void (*listcallback)(int,int);
                        /* Event back functions at the time of list manipulation       */
    int  (*menu)(void); /* Menu functions                                              */
    int  nextflg;       /* Right edge of menu >Display 0:OFF,1:ON                      */

    char *extinfo;      /* General arrangement/address for storing structure data      */
} INPUTITEM;


--------------------------------------------------------------------------------
2.Input Menu Functions

initInputTable   ...   Initialize input menu functions.

	***** Syntax *****  
        void initInputTable(char* title,INPUTITEM *item){}

            Function value:  none

            Parameters:
                char      *title  Speficy a menu title.
                INPUTITEM *item   INPUTITEM Structure

	***** Function ***** 
        Reserve memory for input menu processing and store a menu title shown with str. 
        Then, until endInputTable() is called, the following acquisition/set functions are valid.

        In addition, you can next 10 times (continuously invoking initInputTable()). When entryItemMenu() is used.

	***** Note *****  
        Make sure to execute endInputTable() every time you exit from a menu.
        Reserve necessary memory during execution, depending on an item.

       Example  a series of menu functions.

            /* Reserve INPUTITEM memory */
            INPUTITEM Item[2];

            /* Initialize menu. */
            initInputTable("input",Item);

            /* Register menu */
            id = entryItem("  a  ",dataa,5);    /* to be described later */
            setItemListVal(id,1);               /* to be described later */
            id = entryItem("  B  ",dataB,5);    /* to be described later */

            /* Start menu operation */
            ret=runInputProc();

            /* Update/Cancel judgement */
            if (ret==-3) {
                /* Update processing */
            }

            /* Release memory */
            endInputTable();

       Example of Display
        #### Input ####
           A   >> No
           B   >  Yes




endInputTable   ...   Release input memory.

	***** Syntax *****  
        void endInputTable(void){}

            Function Value:  None

	***** Function *****   
        Release memory used by initInputTable();. 



entryItem   ...   Register list input item of input memory.

	***** Syntax *****  
        int entryItem(char* str,char *list,int num){}

            Function value:            -1:Not possible to register
                            Other than -1:Register item ID value

            Parameters:
                char    *str  Specify an item title name (left side).
                char    *list Specify a list arrangement (right side).
                int     num   Specify the number of list arrangements.

	***** Function *****  
        you can register one item by entryItem(). If you continue to execute entryItem(), addition is made to a next line.
        If you succeed in registering, that ID value will be returned.  Using this ID value, you can set/obtain a list value. 
        That item will be retained till endInputTable(). 
        Menu operates with manipulation of buttons, as shown below:
 
        When the cursor is positioned on the item title side (on the left side): 
            Enter button: You can exit from runInputProc() processing.
                          A returned value will be -3. Exeucte update operation.
            Menu button: Return to the top menu.
                          A returned value will be 0, -1 and -4.

        When the cursor is positioned on the list side (on the right side):
            Enter button: A list selection value is updated and you will return to an item title name (left side)
            Menu button:  A list selection value is cancelled, and you will return to an item title name (left side).


      Example  Register menu.
          char dataA[][7]={
                " Yes ",
                " No  "
            };
            char dataB[][7]={
                " Yes     ",
                " Stop    ",
                " Suspend ",
            };

            /* Reserve INPUTITEM memory */
            INPUTITEM Item[2];

            /* Initialize menu */
            initInputTable("Input",Item);

            /* Register menu */
            entryItem("  A  ",data1,2);
            entryItem("  B  ",data2,3);

            /* Start menu operation */
            ret = runInputProc();

            /* Update/cancel judgement */
            if (ret==-3) {
                /* Update operation */
            }

            /* Release memory */
            endInputTable();




runInputProc   ...   Execute input menu.

	***** Syntax *****  
        int runInputProc(void){}

                Function value:  0: Cancel
	                            -1: Cancel
	                            -2: Forced end of application
	                            -3: Update 
	                            -4: Cancel

                Parameters 		  : None

	***** Function ***** 
        Execute input operation on a registered item.
        Press MENU button, and cancel 0 will be returned. 
        Press ENTER button, and update -3 will be returned. 
        For actual update operation, each user should do by himself after confirming a termination code. 

       Example  Register Menu
            /* Initialize menu */
            initInputTable("input",Item);

            /* Register menu */
            id = entryItem("  A  ",dataA,5);   /* To be described later. */
            setItemListVal(id,1);              /* To be described later. */
            id = entryItem("  B  ",dataB,5);   /* To be described later. */

            /* Start menu operation. */
            ret=runInputProc();

            /* Update/cancel judgement */
            if (ret==-3) {
                /* Update operation */
                id = getItemId("  A  ");       /* To be described later. */
                A  =getItemListVal(id);        /* To be described later. */
                    :
            }

            /* Release memory. */
            endInputTable();




setItemListVal     ...  Change a list selection value of registered item.

	***** Syntax *****  
        int setItemListVal(int id,int val){}

            Function Value:  -1: Abnormal end
		                      0: Normal end

            Parmeters:
                int     id   Registered item ID value
                int     val  List No.

	***** Function *****  
        change a selection value of list of an item registered by entryItem to val.
        A default value is 0th on the list. 



getItemListVal     ...  Obtain a list selection value of a registered item.   

	***** Syntax *****  
        int getItemListVal(int id){}

            Function Value:           -1:Abnormal end
                           Other than -1:Selected value

            Parameters:
                int     id   Registered item ID value

	***** Function *****  
        Return a selected value of an item registered with entryItem. 




arrangeItemListX     ...  Align the X coordinate of > list display (right side) of English font. 

	***** Syntax *****
        void arrangeItemListX(int id0,int id1){}

            Function Value:  None

            Parameters:
                int     id0  Head itemID
                int     id1  Last itemID

	***** Function *****  
        Align X coordinate of list display (on the right side) goig off in English font (width variable) to the rightmost between id0 to id1. 




setItemListToggle   ...  Set the list update operation (toggle/non-toggle) of the registered item.

	***** Syntax *****  
        int setItemListToggle(int id,int val){}

            Function value:  -1: Abnormal end
                              0: Normal end

            Parameters:
                int     id   Registered item ID Value
                int     val  1:Toggle (default)                0:Non-toggle
                             3:Toggle(Inverted arrangement)    2:Non-toggle(Inverted arrangement)

	***** Function *****  
        Set a method of updating a selection value of a list of an item registered with entryItem.  Default value is toggle operation. 

       Example
            char dataB[][7]={
                " A ",
                " B ",
                " C ",
            };

         In case of toggle operation
           Operation of up(^) button   "A"<-"B"<-"C"<-"A"
           Operation of down(v) buton  "A"->"B"->"C"->"A"

         IN case of non-toggle operation
           Operation of up(^)  button   "A"<-"A"<-"B"<-"C"
           Operation of down(v)  button "A"->"B"->"C"->"C"




entryItemMenu   ...   Register a menu item of input menu.

	***** Syntax *****  
        int entryItemMenu(char* str,int *menu){}

            Function Value:           -1:Not possible to register
                           Other than -1:Registered item ID value

            Parameters:
                char    *str  Specify a menu name.
                int     *Menu Menu name > Function to be executed by (right click)

	***** Function ***** 
        You can execute a specified function with one menu item display and right click.
        You can set right click execution with setItemMenuNext() function.
        Inverted display is default. However, if you use it with entryItem(), change to flash display with setItemSelectMode().

        You can register up to 30 items including entryItem().


        Menu execution functions will be defined as shown below:
            int menu(void)
                Function value:  Refer to the following.

                Menu operation will be as shown below, depending on a returned value of menu functions:                 
                 0: Remain unchanged.
                -1: Return to the top menu as Rupsys Function setBackMenu().
                -2: Application termination code as Rupsys function setExitMenu()
                -3: Exit from runInputProc() processing.
                     Returned value will be -3.  Execute update operation.
                -4: Exit from runInputProc() processing.
                     Returned value will be -4. Execute cancel operation.

       Example  Register menu.
            int ret_0(void).{return  0;}
            int ret_1(void).{return -1;}
            int ret_3(void).{return -3;}
            int ret_4(void).{return -4;}
            static MENU SubList[] = {
                { setBackMenu,      "Return                        ",0,0},
                { ret_0,            " 0 Return(cancel)             ",0,0},
                { ret_1,            "-1 return(update)             ",0,0},
                { ret_3,            "-3 return(update)             ",0,0},
                { ret_4,            "-4 return(cancel)             ",0,0},
                { setExitMenu,      "-2 termination of application ",0,0},
            };

            INPUTITEM Item[6];

            /* Initialize menu */
            initInputTable("Inverted menu",Item);

            /* Register menu */
            for (i=0;i<6;i++) {
                id =entryItemMenu((char*)List[i].str,(int*)List[i].func);
                setItemDisable(id,List[i].disable);
                setItemMenuNext(id,List[i].moveR);
            }

            /* Start menu operation */
            ret = runInputProc();

            if (ret==-3) {  /* Obtain item id selected last. */
                selected = getLastItemId();
            }

            /* Release memory */
            endInputTable();



setItemMenuNext   ...  Display menu item ">" of input menu and operate with right click.

	***** Syntax *****  
        int setItemMenuNext(int id,int flg){}

            Function Value:  -1: Abnormal end
                              0: Normal end

            Parameter:
                int     id    Registered item ID value
                int     flg   1:Right click valid 0:Invalid (default)

	***** Function ***** 
        Display ">" At the right edge of menu item registered with entryItemMenu, and, with right click, specify whether to execute a specified function. 




setItemSelectMode   ...  Invert an item or set flash display.

	***** Syntax *****  
        int setItemSelectMode(int id,int val){}

            Function value:  -1: Abnormal end
                              0: Normal end

            Parameters:
                int     id    Registered item ID value
                int     val   0:Flash 1:Inverted

	***** Function ***** 
        Specify a method of display when an item is selected. at present, you cannot use flash and inverted display together.      




entryItemEx   ...   Register a list display customize registration of an input menu.

	***** Syntax *****  
        int entryItemEx(char* str,int *func){}

            Function value:           -1:Possible to register.
                           Other than -1:Registered item ID value

            Parameters:
                char    *str  Specify an item title name (left side).
                int     *func Display routine


	***** Function ***** 
        Execute a specified function at the timing to display a menu item. 
        This time, draw contents of what you wish to display in the list. 

        An item display function is defined as follows:
            int func(x,y,val)
                Function values:  Refer to the following.
	                Func Menu operation differs depending on a returned value of a function:
	                >=0: Update ItemListVal value.
	                 -1: Return to the top menu as Rupsys function setBackMenu().
	                 -2: Application termination code as Rupsys function setExitMenu()
	                 -3: Exit from runInputProc() processing.
	                    A returned value will be -3, and execute update operation. 
	                 -4: Exit from runInputProc() processing.
	                     A returned value will be -4, and execute cancel operation.

                Parameters:
	                int     x   display position x coordinate
	                int     y   display position y coordinate
	                int     val current item value through key manipulation( >=0 )
	                            Request for drawing ( -1 )




setItemDisable   ...  Set invalidation of an item (shading).

	***** Syntax *****  
        int setItemDisable(int id,int val){}

            Function Value:  -1: Abnormal end
                              0: Normal end

            Parameters:
                int     id    Registered item ID value
                int     val   0:Valid 1:Invalid (shading)

	***** Function *****  
        You can disable selection of items.
        If selection is disabled, an item is displayed in shading.



setItemCallBack   ...  Set a list update callback function.      

	***** Syntax *****  
        int setItemCallBack(int id,void *func){}

            Function Value:  -1: Abnormal end
                              0: Normal end

            Parameters:
                int     id    Regisered item ID value
                void    *func a function to be invoked when a list display is updated. 

	***** Function *****  
        To be called when a list display is updated.  Then, you can invalidate (shading) other item from a set value.   Callback functions are defined as follows:       
            void func(int key, int val)
                Function value:  None

                Parameters:
                    int   key   A button value when depressed (Initial display key=0)
                    int   val   List value

       Example  Callback

            void callback(int key,int val).
            {
                if (val==0) {
                    setItemDisable(2,1);
                } else {
                    setItemDisable(2,0);
                }
                setItemListVal(2,val);
                dispItemRW(2);  /* Redisplay id=2. */
            }


            /* Register menu. */
                :
            id = entryItem("  B  ",dataB,5);
            setItemCallBack(id,(int*)callback);
            /* Menu operation starts. */
            ret = runInputProc();
                :




dispItemRW   ...  Redisplay specified item ID.

	***** Syntax *****  
        int dispItemRW(int id){}

            Function value:  -1: Abnormal end
                              0: Normal end

            Parameters:
                int     id   Redisplayed item ID value

	***** Function *****  
        Call when it becomes necessary to redisplay with list update callback function, etc.




getItemId     ...  Obtain a registered item ID from input item name.      

	***** Syntax *****  
        int getItemId(char *str){}

            Function value:           -1: Abnormal end
                           Other than -1: Registered item ID value

            Parameters:
                char*   str   Specify an item title name (left side). 
	***** Function ***** 
        Obtain a registered item ID from an item name registered with entryItem,entryItemEx,entryItemMenu.




getItemListStr    ...  Obtain a list string (right side) from list numbers of specified item IDs. 

	***** Syntax *****  
        char *getItemListStr(int id,int val){}

            Function Value:                  -1: Abnormal end
                           Other than except -1: Item lisstring

            Parameters:
                int     id   Registered item ID
                int     val  List number you wish to obtain




setInitialItemId     ...  Set a selection item ID. 

	***** Syntax *****  
        int setInitialItemId(int id,int val){}

            Function value:  -1: Abnormal end
                              0: Normal end

            Parameters:
                int     id   Selection item ID value
                int     val  List number

	***** Function *****  
        Set an item ID that enters selection state immediately after executing runInputProc(). 
        A default value is 0.




getLastItemId     ...  Obtain an item ID value selected last time.

	***** Syntax *****  
        int getLastItemId(void){}

            Function value:  -1:	        Abnormal end
                      		 Other than -1: Registered item ID value

            Parameter:  None

	***** Function *****
        For any item registered with entryItem,entryItemEx,entryItemMenu, return an item ID value selected last time when runInputProc operation ends. 


       Example  Obtain last ID.
                :
            /* Menu operation starts. */
            ret=runInputProc();

            if (ret==-3) {
                if (getLastItemId()==getItemId("Terminatin of application"))
                    return -1;

                /* Update operation */
                id = getItemId("  A  ");       /* To be described later. */
                A  =getItemListVal(id);        /* To be described later. */
                    :
            }




getLastKeyState     ...  Obtain the last key state.

	***** Syntax *****
        int getLastKeyState(void){}

            Function value:  key:    key value

            Parameter: None

	***** Function *****
        Return a value of the key pushed last time when runInputProcoperation ends. 




getInputItemNow     ...  Return to a pointer to INPUTITEM structure being selected. 

	***** Syntax *****
        INPUTITEM *getInputItemNow(void){}

            Function value:  this:    Pointer to INPUTITEM being currently selected.

            Parameter:  None

	***** Function *****
        You can obtain a pointer to INPUTITEM being currently selected in call back routines, etc., during runInputProc operation. 




setInputFont         ...  Set a font.

	***** Syntax *****
        void setInputFont(int font){}

            Function value:  None

            Parameter:
                int     font   Specify a size code.

	***** Function *****
        You can switch fonts by specifying a size code.
             font=0:Fixed font
             font=5:Proportional font(default)

	***** Note *****
        Set prior to itentryItem() after initInputTable(). 




setChfiler           ...  Set a mini Filer transition mode.

	***** Syntax *****
        void setChfiler(int flg){}

            Function value:  None

            Parameter:
                int     flg    0:No transition 1:There is a transition.

	***** Function *****
        By setting flg=1, you can call a mini filer from a menu.

	***** Remarks *****
		You can control more elaborately.  Refer to the following.
		    flg =   -1: Default(Set 0 or 1 with runInputProc.)
                     0: filer disabled      Not possible to recover saver.
                     1: filer transition    Possible to recover saver. 
                     2: menu end            Possible to recover saver. 
                    -2: filer transition    Not possible to recover saver.



--------------------------------------------------------------------------------
retToggle   ...   Toggle operation (0<=val<=max)

	***** Syntax *****
        int retToggle(int val,int max){}

            Function value:       0    : val>max
                                 max   : val<0
                            Other than : val

            Parameter:
                int     val		Updated value
                int     max 	Maximum value

	***** Function *****
        A val value toggles at a minimu value of 0 and maximum value of max. 


       Example Maximum value 5
           When val is incremented by 1.
            0->1->2->3->4->5->0->1->2

           When val is decremented by 1.
            2->1->0->5->4->3->2->1->0


retToggleBoth   ...   Toggle operation(min<=val<=max)

	***** Syntax *****
        int retToggleBoth(int val,int min,int max){}

            Function value:      min  : val>max
                                 max  : val<min
                            Other than: val

            Parameter:
                int     val		updated value
                int     min		minimum value
                int     max		maximum value

	***** Function *****
        A val value toggles at a minimu value of min and maximum value of max. 



retNonToggle   ...   Non-toggle operation (0<=val<=max)

	***** Syntax *****
        int retNonToggle(int val,int max){}

           Function value:     max   : val>max
                                0    : val<0
                           Other than: val

           Parameter:
                int     val 	updated value
                int     max 	maximum value

     ***** Function *****
         A val value does not toggle at minimum value of 0 and maximum value of max. 

       Example  Maximum value 5
           When val is incremented by 1.
            0->1->2->3->4->5->5->5->5

           When val is decremented by 1.
            2->1->0->0->0


retNonToggleBoth   ...   Non-toggle operation (min<=val<=max)

	***** Syntax *****
        int retNonToggleBoth(int val,int min,int max){}

            Function value:     max   : val>max
                                min   : val<min
                           Other than : val

            Parameter:
                int     val 	updated value
                int     min 	minimum value
                int     max 	maximum value

	***** Function *****
        A val value does not toggle at a minimum value of min and maximum value of max. 

===============================================================================
 Copyright (c) 1998-1999.  Seiko Instruments Inc.  All rights reserved. 
===============================================================================
