Click above to get retro games delivered to your door ever month!

 menupromptnew()     Add a new prompt to a menu
------------------------------------------------------------------------------
 Declaration
   menu.hdr

 Syntax
   func int menupromptnew extern
   param value _MENU   pMenu, ;
         value uint    uRow, ;
         value uint    uCol, ;
         const char    cPrompt, ;
         value int     iId, ;
         value logical lActive, ;
         value logical lDisplay

 Arguments
   pMenu    is the pointer to a previously created menu system. If 0, the
            default menu will be used.
   uRow     is the screen row where the prompt will be displayed.
   uCol     is the leftmost screen column where the prompt will be displayed.
   cPrompt  is the Text to be displayed for the prompt.
   iId      is the id number to be assigned to the prompt. If -1, the next
            available id will be assigned to the prompt.
   lActive  defines if the prompt shall be selectable (.t.), or not (.f.).
   lDisplay controls if the prompt shall be displayed by this function (.t.),
            or not (.f.).

 Return
   The assigned prompt id, or -1 if the prompt could not be created.

 Description
   This function adds a new prompt item to a menu system. If the pMenu
   argument is 0, the internal default menu system will be used. If this
   function is called the first time with pMenu == 0, the default menu
   system will be created automatically.

   The menu handlers included in the menu function set make use of a "hot-
   key" (if this feature is turned on) to allow the user to select a prompt
   by simply typing in the corresponding character. When the prompts are
   displayed, the hot-keys are shown in a different color attribute.

   By default, the first non-white character in a prompt is considered to be
   the "hot-key" character.

   Place an ampersand (&) left of any other prompt character to mark it as
   "hot-key" instead of the first one.

   For example, in

     "  Hello  "

   'H' is the "hot-key", i.e. the prompt will be displayed similar to

       Hello  

   but in

     "  Hell&o  "

   'O' would be the hot-key, and the prompt will be displayed similar to

       Hello  

   Note that "hot-keys" are not case-sensitive, and that the ampersand
   character does not increase the length of the displayed prompt message as
   it is not visible.

   To maintain compatibility to former Force versions, the hot-key handling
   is turned off by default. Use the menusethot() procedure to activate it.

 Example
   #define EXAMPLE_MENU
   #include example.hdr

   proc Test_menupromptnew
   vardef
      _MENU pMenu
      int   iChoice, iTest
      uint  uKey
   enddef
   
   clear
   cursor( .f. )
   
   menuseterror( .f. )
   pMenu = menunew()
   
   if pMenu == 0
      ? "Could not create the menu !"
      quit
   else
      iTest := 0
      iTest += menupromptnew( pMenu, 5, 10, " 1st prompt ", 1, .t., .t. )
      iTest += menupromptnew( pMenu, 6, 10, " 2nd prompt ", 2, .t., .t. )
      iTest += menupromptnew( pMenu, 7, 10, " 3rd prompt ", 3, .t., .t. )
      iTest += menupromptnew( pMenu, 8, 10, " 4th prompt ", 4, .t., .t. )
      if iTest != 10
         ? "Could not create the menu items !"
         quit
      endif
   
      do while .t.
         uKey := getkey()
         do case
         case uKey == K_UP
            menusetprev( pMenu )
         case uKey == K_DOWN
            menusetnext( pMenu )
         case uKey == K_ENTER
            iChoice := menucurrentid( pMenu )
            exit
         case uKey == K_ESC
            iChoice := 0
            exit
         endcase
      enddo
   
      @ 10, 0 ?? "The selection is:", iChoice
      menuclear( pMenu )
   endif
   cursor( .t. )
   
   endproc

   proc main
   Test_menupromptnew()
   endproc