Programmers Quick Guide to MCs Menu Maker v0.8
----------------------------------------------

Ok,so its not that quick a guide!,but there should be enough information here to
allow use of the menus/windows without any further documentation.
A list of all the functions that are necessary in order to create and maintain
a menu and/or window structure are listed below.Example code to illustrate each
call is also included,with a full working skeleton at the end of this
documentation.Note:If a window is linked to a menu then on being displayed it
will use its defaults however,if the window is displayed using window_show the
gadget values are taken from the windows work area and therefore must be set
first with win_set_item.Bascially if you *always* require the default values to
be used then link the window to a menu otherwise you have to manage the window
work area yourself (a demonstration of this in included at the end).
Cursor keys allow up/down movement on the menus while tab allows input to
circle around all a windows options.


void menu_clear(int 1)
----------------------

Parameter 1 is a number representing the main background screen colour to be
used.This function must be called first before any others as it contains code
to initialize the menu/window system.

Example:
--------

menu_clear(1);

Menu/window system will be initialized and main background colour will be 1,
standard EGA/VGA 16 colour scheme is used (see documentation for list).


void menu_declare(char *1)
--------------------------

This call allows each possible selection on a menu to be declared.To link a
particular option to a window the window number is contained in curly brackets
before the option.Window and menu numbers are assigned depending on the order of
declaration e.g. the first defined menu is menu 0 the second menu 1 etc, the
same applies to windows.

Example:
--------

menu_declare("A menu,{3}This option opens a window");

A menu will be defined,its number is dependant on if any other menus were
created before it (as the above is an example of the first menu declaration its
number will be 0).The first option in the menu will be the text "A menu" it has
no direct link to a window,on selection it will set the global variables
menu_option and menu_number,in this example both would equal 0 - for menu 0,
option 0 selected.The second option would insert the text "This option opens a
window",on selection window 3 would be openned and input would now be into this
window.Note,no menus are actually displayed until a menu_display is issued.


void window_declare(char *1,int 2,int 3,int 4,int 5,char *6)
------------------------------------------------------------

Allows a window to be defined.The order of declaration will define the window
number.All window declarations must end in a curly bracketed 0.Parameter 1
allows for an automatically centered window title to be displayed,if this is
left as a null ("") then no title will be displayed.Parameters 2 and 3 are the
windows size in characters (x,y).Parameters 4 and 5 determine the x,y coordinate
to place the window at,if both are 0 then the window is placed below and
slightly to the right (where ever possible) of the menu option that selected it.
If either value is not 0 then the window is placed directly at these coordinates
(origin top left 0,0).The final parameter 6 contains the window gadget types
required,currently supported types are listed below.Note all x,y coordinates
are relative to the windows origin.

        type 1 text (x,y,col,string)
        Parameters x,y are the coordinates to place the text at.Col is the
        colour to use to display text and finally string is the actual text
        itself.

        Example:
        --------

        "{1}{10}{9}{15}Some text"

        The text "Some text" will be displayed at coordinates 10,9 in colour
        15.


        type 2 switcher (x,y,num,def)
        Parameters x,y are the coordinates to place the first switch at.Num is
        the total number of switches displayed.Finally def is the number of the
        default switch to be highlighted.

        Example:
        --------

        "{2}{3}{4}{4}{2}"

        4 switches will be displayed starting at coordinates 3,4,switch 2 is
        the default hence highlighted one.


        type 3 number (x,y,min,max,def)
        Parameters x,y are the coordinates to place the input box.Min and Max
        define the minimum and maximum value to accept.Def is the default
        value.

        Example:
        --------

        "{3}{10}{11}{5}{10}{6}"

        An input box will displayed at coordinates 10,11,it will accept only
        values between 5 and 10 inclusive.The default value is 6.


        type 4 boolean (x,y,def)
        Parameters x,y are the coordinates to place the alternator at.Def is
        the default selection (1=Yes,0=No).

        Example:
        --------

        "{4}{7}{4}{1}"

        A boolean alternator will be displayed at coordinates 7,4.Its default
        will be YES.


        type 5 file (x,y,height,type)
        Parameters x,y are the coordinates to place the start of the file box
        at.Height is the height of the box in characters.Type defines what
        action to take on a selection,(0=exit on selection of file to calling
        program,1=don't,this allows for just directory selection).The current
        directory will be used.

        Example:
        --------

        "{5}{6}{7}{10}{0}"

        A file selection box will be displayed at coordinates 6,7.Its height
        will be 10 characters.On a file selection control will return to the
        calling enviroment.


        type 6 char (x,y,len,type,def)
        Parameters x,y are the coordinates to place the start of the input box
        at.Len is the maximum length of input string to accept.Type defines
        what action to take on <return> being pressed,(0=normal, string is
        stored but no action taken,1=exit on entry to calling program).Def is
        the default string to be displayed.

        Example:
        --------

        "{6}{17}{8}{10}{0}"

        An input box will be displayed at coordinates 17,8.Maximum input length
        of string will be 10 characters.On <return> no action will result,apart
        from storage of the string.


        type 7 accept (x,y,text)
        Parameters x,y are the coordinates to place the icon at.Text is the
        actual icon text to display.

        Example:
        --------

        "{7}{6}{22}OK"

        An icon will be displayed at coordinates 6,22.Its text will be "OK".


Full Example:
-------------

window_declare("A window",50,20,0,0,"{1}{2}{2}{9}Hi,{3}{2}{5}{2}{10}{5},{0}");

A window with title "A window" of size 50,20 will be declared.When displayed
it will appear one character down and one character to the right of the menu
option that selected it if possible.The text string "Hi" will be displayed in
colour 9 at coordinates 2,2.A number input box will be displayed at coordinates
2,5 it will accept a value between 2 and 10 inclusive,with the default displayed
value being 5.Note the {0} terminator.


int window_show(int 1,int 2,int 3)
----------------------------------

Window with the number parameter 1 will be displayed at coordinates parameter
2,parameter 3.This allows windows to be used without a menu selection being
made or without any menus at all.The returned value is either the ASCII code
of a 'non-window' key or a status value (see documentation).Note:default gadget
values are overwrote as any values are read from the gadgets work space.

Example:
--------

key=window_show(5,10,10);

Display window 5 at coordinates 10,10.


void window_help_declare(int 1,int 2,char *3)
---------------------------------------------

A window option must have a help string attached to it (null for none).
Parameter 1 defines which window the help is attached to.Parameter 2 defines
which gadget within that window the help is attached to.Parameter 3 is the
help string to be displayed.Note a text gadget has no help string.

Example:
--------

window_declare("",10,10,0,0,"{2}{1}{1}{2}{1},{5}{2}{4}{4}{1},{0}");
window_help_declare(0,1,"Please select a file to load");

The window declaration defines a window with no title of size 10,10 and
displayed slightly offset from its menu selection.A switcher is displayed at
coordinates 1,1 with 2 switches and switch 1 the default.A file selector is also
displayed at coordinates 2,4,its height is 4 characters.On any file selection no
action is taken.The window_help_declare defines a help string for window 0
(assuming the window defined above was the first),item 1 (the file selector) and
finally the actual help text to appear.


void menu_help_declare(int 1,int 2,char *3)
-------------------------------------------

A menu option must have help text attached to it ("" for none).Parameter 1 
defines which menu will have the help.Parameter 2 defines which option within 
the menu will recieve the help.Parameter 3 is the actual help text.

Example:
--------

menu_declare("{0}About,How to register");
menu_help_declare(0,0,"All about this program");
menu_help_declare(0,1,"");

The menu declaration defines a menu with two options,"About" links to window 0
on selection and "How to register" has no link or help.The menu_help_declare 
defines a help string for menu 0 (assuming the menu defined above was the 
first),item 0 (the "About" string) and finally the help text for that option.


void win_set_item(int 1,int 2,long int 3)
-----------------------------------------

This allows a window gadgets value to be set.Parameter 1 specifies the window
number.Parameter 2 specifies which item within that window.Parameter 3 is the
value to set it to,int long is used so that the setting of addresses can be
allowed.Settings would be thus:

        type 1 text
        No setable parameters.

        type 2 switcher
        A value indicating which switch is active.

        type 3 number
        A value indicating the value to be displayed.

        type 4 boolean
        A value indicating whether the setting is YES(1) or NO(0).

        type 5 file
        The value here is an address to where the file selected is stored
        (accessed with win_get_item),therefore this value should not be altered.
        But the contents of its address will be the first character of the file
        selected (0 terminated).

        type 6 char
        The value here is an address to where the string is stored (accessed
        with win_get_item),therefore this value should not be altered.But the
        contents of its address will be the first character of the entered
        string (0 terminated).

        type 7 accept
        The value here is either a 1(icon selected) or a 0(not selected).Its the
        user programs resposibility to reset an icon once its selection has been
        dealt with.This is not necessary with only one icon in a window,but with
        more all must be reset after a selection otherwise next time the window
        is openned it will not be possible to determine which icon was selected.


void menu_heading(void)
-----------------------

This displays the menu heading which must have been previously defined with
menu_bar_options.

Example:
--------

menu_heading();

The menu headings are displayed.


void menu_display(int 1)
------------------------

Parameter 1 defines which menu to display.This call is only of real use on a
menu driven application being first executed i.e. forcing the user straight into
a menu selection.

Example:
--------

menu_display(3);

Display menu 3 on screen.


int long win_get_item(int 1,int 2)
----------------------------------

The window numbered parameter 1,item parameter 2 returns a value (possibly an
address) as a long integer.

Example:
--------

value=win_get_item(5,3);

Value would contain the value of item 3 in window 5.


int menu_poll(void)
-------------------

Begins polling of the menus.The returned value is a 'non window' key.

Example:
--------

key=menu_poll();

Polling of menus begins.Polling will be left when either a 'non window' key is
pressed or a window gadgets type is such that it needs to return directly to the
users program.


void menu_kill(void)
--------------------

This call must be issued once the application using the menus/windows ends,as
any allocated memory during use is now released.

Example:
--------

menu_kill();

All menu/window workspace memory is released.


Useful Global Variables
-----------------------

int menu_position          This always contains the currently selected menu

int menu_option            Contains the currently selected menu option

int menu_fore_color        The menu/window foreground color

int menu_back_color        The menu/window background color

int menu_highlight_color   The menu/window color for highlighted options/gadgets

char *menu_bar_options     The menu bar headings

int menu_help_color        Color for menu/window help text

int win_accept             Number of the currently active window

char menu_buffer1[4096]    Buffer to save screen behind menu

int win_out                User can set to 1,in order to leave menu poll loop



Example skeleton code
---------------------

To use the OBJ file include it in a project file along with your C source
code plus of course any other object/source files.MCs Menu Maker uses far
pointers therefore it will not work in tiny/small/medium memory models.
The example below is very simple but illustrates how to use the various
menu/window calls.The portion of code which displays the menu position and
menu option may appear wrong after a selection is made and a different menu
option highlighted,this is due to the way the screen updates and will not
effect your own program.

#include "mcs_menu.h"                       //Include MCs Menu header

int menu_position=0;
int menu_option=0;
int menu_fore_color=15;                     //Foreground colour
int menu_back_color=1;                        //Background colour
int menu_highlight_color=4;                 //Highlight colour
char menu_buffer1[4096];
char menu_buffer2[4096];
int menu_titles=0;
char *menu_bar_options;
int menu_menus=0;
int window_windows=0;
int window_x=0;
int window_y=0;
int win_attr=0;
int win_out=0;
char unsigned far *win_text_screen;
int window_open=0;
int window_item=0;
int menu_help_color=14;
int win_accept=0;
int win_default=0;
struct menu_help_def *startmh=NULL;
struct menu_help_def *endmh=NULL;
struct window_help_def *startwh=NULL;
struct window_help_def *endwh=NULL;
struct menu_def *start=NULL;
struct menu_def *end=NULL;
struct window_def *startw=NULL;
struct window_def *endw=NULL;

void main (void)
{
int key,quit=0;

menu_clear(3);                              //Clear screen,get menu system ready

					    //Declare menu
menu_declare("{0}Menu option 0,{1}Menu option 1,Menu option 2 has no window");

menu_help_declare(0,0,"This is a menu option");     //Declare help for this
menu_help_declare(0,1,"");                          //menus options
menu_help_declare(0,2,"This option has no window"); //

					    //Declare menu
menu_declare("{0}Option 1,Option 2,Option 3,Option 4,EXIT");

menu_help_declare(1,0,"");                          //
menu_help_declare(1,1,"");                          //Declare help for this
menu_help_declare(1,2,"");                          //menus options
menu_help_declare(1,3,"");                          //
menu_help_declare(1,4,"Exit to DOS");               //

                                            //Declare windows
window_declare(" A Sample Window ",74,12,0,0,"{1}{15}{2}{14}Some text,{2}{2}{1}{11}{4},{5}{8}{4}{6}{1},{0}");
window_declare(" Another Window ",40,15,5,5,"{6}{3}{4}{15}{0}A text string,{3}{3}{8}{1}{10}{5},{1}{2}{7}{7}Enter a value between 1 and 10,{0}");

                                            //Menu heading titles
menu_bar_options=" Menu-1         Menu-2 ";

menu_heading();                             //Display titles

gettext(1,1,80,25,menu_buffer1);            //Get background

menu_display(0);                            //Display a starting menu

do {


  key=menu_poll();                          //Start polling the menus

  if (key==28)                              //BIOS code for 'Return' key
  {
   if (menu_position==1)                    //
     if (menu_option==4)                    //If this option,exit
       quit=1;                              //
  }

gotoxy(10,20);                              //
cprintf("menu selected: %d",menu_position); //
gotoxy(10,21);                              //Display menu/option selected
cprintf("menu option  : %d",menu_option);   //
gotoxy(10,23);                              //

} while (quit==0);                          //Do until this flag is 1


puttext(1,1,80,25,menu_buffer1);            //Put background back

}



Example of managing a window work area
--------------------------------------

Assuming a window (number 6) has been declared and contains a switch as item 4
and a char (input string) gadget as item 6,the following would set them, i.e.
overriding any default.

char *addr;
char p;

win_set_item(6,4,2);                        //Turn on switch 2

addr=(char *)win_get_item(6,6);             //Get the address where the type
                                            //chars workspace is

for(p=0;p!=3;p++)                           //Although a rough example,this
   *(addr+p)=p+65;                          //would fill the char workspace
                                            //with A,B,C,D in succession



How to crash your PC!
---------------------

Its assumed that C programmers are reasonably intelligent (!),therefore doing
things such as trying to create a window larger than the screen,trying to place
a gadget at x coordinate 1 million,declaring a char gadget of length 6 and
attempting to store a 500K file in it and such things are virtually guranteed to
crash your system.Also declaring a window without a {0} terminator and a window
or menu with a gadget type (e.g. {1} for text) and then the wrong number of
corrosponding parameters will send your PC into a mild epiletic fit!!!.Failure
to allocate memory and "simple" errors should be trapped by the menu system and
return a useful error message.Remember its not perfect but it does work!,have
fun.


END: - 26/08/92 - Mark Hula -
Compuserve id: 100047,110

