======================================
============ GUI routines ============
======================================

Allegro contains an object-oriented dialog manager, which was originally 
based on the Atari GEM system (form_do(), objc_draw(), etc: old ST 
programmers will know what I'm talking about :-) You can use the GUI as-is 
to knock out simple interfaces for things like the test program and grabber 
utility, or you can use it as a basis for more complicated systems of your 
own. Allegro lets you define your own object types by writing new dialog 
procedures, so you can take complete control over the visual aspects of the 
interface while still using Allegro to handle input from the mouse, 
keyboard, joystick, etc.




===================================
========== Using MDK      =========
===================================

**      What is MDK:
   
   MDK is a "what you see is what you get" Gui-editor for Allegro. 
   Allegro v3.0 comes with a couple of gui objects for making user dialogs. The
   main problem of designing is that you cann't see your programmed 
   dialog before compiling, and compiling takes a little while 
   (at least this is the reason why I wrote this program).

** Basics:
  
 - Output Files

   MDK writes its data into a file with the .MDK extension, this file is ASCII.
   Also MDK produces a C-File. This file is mainly adapted to C users, but C++ 
   works, too - MDK sources are C++ (sorry, my C++ is not the best)

 - MDK Desktop
 
   The MDK desktop constists of the horizontal bar which has the File-, Draw -, 
   Edit-, Menu -, Setup and Help menu.
   With the Draw menu you can easily draw/make your gui objects.
   If you click right mouse on the Gui Drawing Area (GDA) you'll get a menu for 
   handling the most useful functions of MDK. The size of GDA is set up with the Setup menu,
   but you can change it also directly in the file "CONFIG.CFG" in the dir where 
   MDK is.
 
 - Selecting objects
   
   You can select objects in 3 ways:
     1. Select all (CRTL+S)
     2. Select a special Area (CRTL+A): Here you can draw a rect on the screen, 
	all objects inside of it are selected.
     3. Select a singel object: Double click on it. If there are more than 
	one objects on a particular spot, the object on the top is selected, e.g.
	if you have a text-proc over a box, the text is selected first.


 - Setup 
  
   MDK generates a MDK.CFG file, which is ASCII formatted. You can modify 
   the number of objects, the colordepth, the resolution etc. directly in this file.
   Each time MDK is started it reads this file. If there is no config-file 
   (e.g. first start) MDK will ask you for your own defaults.


 - Plans for future releases

   Well, I wanted to make a multilanguage support, which I started right after the
   release of mdk, but it's not finished yet. You can see the first efforts if you
   look at IDS.H in the sources.
   
   Also I'll have to rearrange the templates and use STL instead. 

   Also I want to get rid of the *.MDK file or make at least an import filter for C
   source files...

   Also I encourage you to mail to me for wishes, comments etc. 
   If you want to donate something, well, perhaps you start with Shawn and then DJ 
   (or vice versa) and then you can give me also something :))))))))

   OR BUY A CD (see "More" dialog in about dialog) 


 - Bug report/Contact/Critics:
  
   Tell me:
   Schuster@eev.e-technik.uni-erlangen.de


 - CREDITS
   
   Greetings & Thanks to DJ and Shawn.
   
   The Allegro grabber is part of the ALLEGRO 3.0 distribution. I've made only a few
   changes to the source to integrate it to MDK 3.01.

   Gruesse auch an Jutta,Sonnie, Hannes, Frank,Bello & Vera, Fraid L., Herby & Birthe, Volker und seine Weiber
   und den Rest der Gang.
 



===================================
======== Using Dialog =============
===================================

A GUI dialog is stored as an array of DIALOG objects, each one containing 
the fields:

typedef struct DIALOG
{
   int (*proc)(int, DIALOG *, int); - dialog procedure (message handler)
   int x, y, w, h;                  - position and size of the object
   int fg, bg;                      - foreground and background colors
   int key;                         - ASCII keyboard shortcut
   int flags;                       - flags about the status of the object
   int d1, d2;                      - whatever you want to use them for
   void *dp, *dp2, *dp3;            - pointers to more object-specific data
} DIALOG;

The array should end with an object which has the proc pointer set to NULL.

The flags field may contain any combination of the bit flags:
   D_EXIT          - this object should close the dialog when it is clicked
   D_SELECTED      - this object is selected
   D_GOTFOCUS      - this object has got the input focus
   D_GOTMOUSE      - the mouse is currently on top of this object
   D_HIDDEN        - this object is hidden and inactive
   D_DISABLED      - this object is greyed-out and inactive
   D_INTERNAL      - don't use this! It is for internal use by the library...
   D_USER          - any powers of two above this are free for your own use

Each object is controlled by a dialog procedure, which is stored in the proc 
pointer. This will be called by the dialog manager whenever any action 
concerning the object is required, or you can call it directly with the 
SEND_MESSAGE macro. The dialog procedure should follow the form:

   int foo(int msg, DIALOG *d, int c);

It will be passed a flag (msg) indicating what action it should perform, a 
pointer to the object concerned (d), and if msg is MSG_CHAR or MSG_XCHAR, 
the key that was pressed (c). Note that d is a pointer to a specific object, 
and not to the entire dialog.

The dialog procedure should return one of the values:
   D_O_K          - normal return status
   D_CLOSE        - tells the dialog manager to close the dialog
   D_REDRAW       - tells the dialog manager to redraw the entire dialog
   D_WANTFOCUS    - requests that the input focus be given to this object
   D_USED_CHAR    - MSG_CHAR and MSG_XCHAR return this if they used the key

Dialog procedures may be called with any of the messages:

MSG_START:
   Tells the object to initialise itself. The dialog manager sends this to 
   all the objects in a dialog just before it displays the dialog.

MSG_END:
   Sent to all objects when closing a dialog, allowing them to perform 
   whatever cleanup operations they require.

MSG_DRAW:
   Tells the object to draw itself onto the screen. The mouse pointer will 
   be turned off when this message is sent, so the drawing code does not 
   need to worry about it.

MSG_CLICK:
   Informs the object that a mouse button has been clicked while the mouse 
   was on top of the object. Typically an object will perform its own mouse 
   tracking as long as the button is held down, and only return from this 
   message handler when it is released.

MSG_DCLICK:
   Sent when the user double-clicks on an object. A MSG_CLICK will be sent 
   when the button is first pressed, then MSG_DCLICK if it is released and 
   pressed again within a short space of time.

MSG_KEY:
   Sent when the keyboard shortcut for the object is pressed, or if enter, 
   space, or a joystick button is pressed while it has the input focus.

MSG_CHAR:
   When a key is pressed, this message is sent to the object that has the 
   input focus. If the object deals with the keypress it should return 
   D_USED_CHAR, otherwise it should return D_O_K to allow the default 
   keyboard interface to operate.

MSG_XCHAR:
   When a key is pressed, Allegro will send a MSG_CHAR to the object with 
   the input focus. If this object doesn't process the key (ie. it returns 
   D_O_K rather than D_USED_CHAR), the dialog manager will look for an 
   object with a matching keyboard shortcut in the key field, and send it a 
   MSG_KEY. If this fails, it broadcasts a MSG_XCHAR to all objects in the 
   dialog, allowing them to respond to special keypresses even when they 
   don't have the input focus. Normally you should ignore this message 
   (return D_O_K rather than D_USED_CHAR), in which case Allegro will 
   perform default actions such as moving the focus in response to the arrow 
   keys and closing the dialog if ESC is pressed.

MSG_WANTFOCUS:
   Queries whether an object is willing to accept the input focus. It should 
   return D_WANTFOCUS if it does, or D_O_K if it isn't interested in getting 
   user input.

MSG_GOTFOCUS:
MSG_LOSTFOCUS:
   Sent whenever an object gains or loses the input focus. These messages 
   will always be followed by a MSG_DRAW, to let objects display themselves 
   differently when they have the input focus. If you return D_WANTFOCUS in 
   response to a MSG_LOSTFOCUS event, this will prevent your object from 
   losing the focus when the mouse moves off it onto the screen background 
   or some inert object, so it will only lose the input focus when some 
   other object is ready to take over the focus (this trick is used by the 
   d_edit_proc() object).

MSG_GOTMOUSE:
MSG_LOSTMOUSE:
   Sent when the mouse moves on top of or away from an object. Unlike the 
   focus messages, these are not followed by a MSG_DRAW, so if the object is 
   displayed differently when the mouse is on top of it, it is responsible 
   for redrawing itself in response to these messages.

MSG_IDLE:
   Sent whenever the dialog manager has nothing better to do.

MSG_RADIO:
   Sent by radio button objects to deselect other buttons in the same group 
   when they are clicked. The group number is passed in the c message 
   parameter.

MSG_USER:
   The first free message value. Any numbers from here on (MSG_USER, 
   MSG_USER+1, MSG_USER+2, ... MSG_USER+n) are free to use for whatever you 
   like.

Allegro provides several standard dialog procedures. You can use these as 
they are to provide simple user interface objects, or you can call them from 
within your own dialog procedures, resulting in a kind of OOP inheritance. 
For instance, you could make an object which calls d_button_proc to draw 
itself, but handles the click message in a different way, or an object which 
calls d_button_proc for everything except drawing itself, so it would behave 
like a normal button but could look completely different.



===================================
========== Clear procs   ==========
===================================



int d_clear_proc(int msg, DIALOG *d, int c);
   This just clears the screen when it is drawn. Useful as the first object 
   in a dialog.

	As this object is invisible you wouldn't see it. Therefore MDK draws a rect
	to make it visible


===================================
==========  Box procs    ==========
===================================



int d_box_proc(int msg, DIALOG *d, int c);

This draws a simple box onto the screen.


===================================
==========  Shadow procs ==========
===================================

int d_shadow_box_proc(int msg, DIALOG *d, int c);

This draws a shadowed box onto the screen.




===================================
==========  Bitmap procs ==========
===================================

int d_bitmap_proc(int msg, DIALOG *d, int c);
   This draws a bitmap onto the screen, which should be pointed to by the 
   dp field.

The MDK dialog handles Bitmap-procs:

	You can grab the bitmap from a file in two ways.
   
     1. Fill in the filename of the Allegro "*.dat"- file, 
	Fill in the position in the file of the bitmap in your .dat - file

     2. Select the bitmap with the built in Allegro - Grabber. 
	(see further help "built in Allegro-Grabber")
	



===================================
==========   Text procs  ==========
===================================

int d_text_proc(int msg, DIALOG *d, int c);

   This draws text onto the screen. The dp field should point to the string 
   to display. 
   Any '&' characters in the string will be replaced with lines underneath 
   the following character, for displaying keyboard shortcuts (as in MS 
   Windows). To display a single ampersand, put "&&".

MDK dialog for handling text-procs:

 The dp field of a text proc points to a char*. Therefore you can declare
 text procs as :


   DIALOG textdialog= 
     { d_text_proc,x,y,w,h, flags,key,d1,d2, "My Text" }
 
 Often, I realized, it's better do declare a char*, so that the text-proc
 syntax is:

   char[256] MyTextchar="Default Text";
   DIALOG textdialog=
    { d_text_proc,x,y,w,h, flags,key,d1,d2, MyTextchar };
 
Choose these properties with the radio button

  -"Dp points to ASCII" to do the first
  -"Dp points to Identifier" means the second syntax. Here you can have an default
   initializer "Default Text"


===================================
==========  CText  procs ==========
===================================




int d_ctext_proc(int msg, DIALOG *d, int c);
   
   This draws text onto the screen. The dp field should point to the string 
   to display. d_ctext_proc() centers the string around the x coordinate.
   Any '&' characters in the string will be replaced with lines underneath 
   the following character, for displaying keyboard shortcuts (as in MS 
   Windows). To display a single ampersand, put "&&".

MDK dialog for text-procs:

   The dp field of a text proc points to a char*. Therefore you can declare
   text procs as :
      
      DIALOG textdialog= 
      {     d_text_proc,x,y,w,h, flags,key,d1,d2, "My Text" }
 
   Often, I realized, it's better do define a char*, so that the text-proc
   syntax is:

     char[256] MyTextchar="Default Text";
     DIALOG textdialog=
     { d_text_proc,x,y,w,h, flags,key,d1,d2, MyTextchar };
 
   This is what you can choose with the radio button
 
    -"Dp points to ASCII" means the first,
    -"Dp points to Identifier" means the second syntax. Here you can have an default
     initializer "Default Text"



===================================
==========  Button procs ==========
===================================

int d_button_proc(int msg, DIALOG *d, int c);
   A button object (the dp field points to the text string). This object can 
   be selected by clicking on it with the mouse or by pressing its keyboard 
   shortcut. If the D_EXIT flag is set, selecting it will close the dialog, 
   otherwise it will toggle on and off. Like d_text_proc(), ampersands can 
   be used to display the keyboard shortcut of the button.

MDK allows you declaring a string variable for the dp field. 
	Therefore your C output will be

	     DIALOG buttondialog= 
	   {     d_button_proc,x,y,w,h, flags,key,d1,d2, "MyButtonText" }
    

    if you click on "dp points to ASCII" or 

	 
	     char[256] ButtonText="MyButtonText";
	  DIALOG buttondialog= 
		{d_button_proc,x,y,w,h, flags,key,d1,d2,ButtonText }
    
    
   if you click on "dp points to Identifier"


===================================
==========  Check  procs ==========
===================================

int d_check_proc(int msg, DIALOG *d, int c);
   This is an example of how you can derive objects from other objects. Most 
   of the functionality comes from d_button_proc(), but it displays itself 
   as a check box.


MDK allows you declaring a string variable for the dp field. 
Therefore your C output will be

    DIALOG checkdialog= 
	   {     d_check_proc,x,y,w,h, flags,key,d1,d2, "MyCheckText" }
    

    if you click on "dp points to ASCII" or 

     char[256] CheckText="MyCheckText";
     DIALOG buttondialog= 
	{d_check_proc,x,y,w,h, flags,key,d1,d2,CheckText }
    
    if you click on "dp points to Identifier"


===================================
==========  Radio  procs ==========
===================================

int d_radio_proc(int msg, DIALOG *d, int c);
   A radio button object. A dialog can contain any number of radio button 
   groups: selecting a radio button causes other buttons within the same 
   group to be deselected. The dp field points to the text string, d1 
   specifies the group number, and d2 is the button style (0=circle, 
   1=square).

MDK allows you declaring a string variable for the dp field. 
   Therefore your C output will be

   DIALOG radiodialog= 
	   {d_radio_proc,x,y,w,h, flags,key,d1,d2, "MyRadioText" }
    
   if you click on "dp points to ASCII" or 

   char[256] RadioText="MyCheckText";
   DIALOG radiodialog= 
	{d_radio_proc,x,y,w,h, flags,key,d1,d2,RadioText }
    
    
   if you click on "dp points to Identifier"





===================================
===========  Icon procs ===========
===================================

int d_icon_proc(int msg, DIALOG *d, int c);
   A bitmap button. The fg color is used for the dotted line showing focus, 
   and the bg color for the shadow used to fill in the top and left sides of 
   the button when "pressed". d1 is the "push depth", ie. the number of 
   pixels the icon will be shifted to the right and down when selected 
   (default 2) if there is no "selected" image. d2 is the distance by which 
   the dotted line showing focus is indented (default 2). dp points to a 
   bitmap for the icon, while dp2 and dp3 are the selected and disabled 
   images respectively (optional, may be NULL).

The MDK Dialog for handling icon dialogs shows the three dp - fields for this dialog.
   Each Bitmap can be loaded from seperate files. The path to these files can be 
   filled in directly or by invoking the Grabber. Also the position in the 
   selected *.dat file can be directly manipulated or by the selection made 
   with the grabber.

If you double click on an icon object, you can also determine if you want to
   select it, or want to see the icon/selected/disabled bitmap
   

===================================
=========  Keyboard procs =========
===================================

int d_keyboard_proc(int msg, DIALOG *d, int c);
   This is an invisible object for implementing keyboard shortcuts. You can 
   put an ASCII code in the key field of the dialog object (a character such 
   as 'a' to respond to a simple keypress, or a number 1-26 to respond to a 
   control key a-z), or you can put a keyboard scancode in the d1 and/or d2 
   fields. When one of these keys is pressed, the object will call the 
   function pointed to by dp. This should return an int, which will be 
   passed back to the dialog manager, so it can return D_O_K, D_REDRAW, 
   D_CLOSE, etc.

If you invoke the keyboard shortcuts for the first time, you see an empty list. 
If you click on "new" you'll see the dialog for customizing a single keyboard proc.
If you want an ASCII - keyboard shortcut, choose Select via ASCII control,
or select via Scancode if you prefer this.


===================================
==========  Edit  procs ===========
===================================

int d_edit_proc(int msg, DIALOG *d, int c);
   An editable text object (the dp field points to the string). When it has 
   the input focus (obtained by clicking on it with the mouse), text can be 
   typed into this object. The d1 field specifies the maximum number of 
   characters that it will accept, and d2 is the text cursor position within 
   the string.



===================================
===========  List procs ===========
===================================

int d_list_proc(int msg, DIALOG *d, int c);
   A list box object. This will allow the user to scroll through a list of 
   items and to select one by clicking or with the arrow keys. If the D_EXIT 
   flag is set, double clicking on a list item will close the dialog. The 
   index of the selected item is held in the d1 field, and d2 is used to 
   store how far it has scrolled through the list. The dp field points to a 
   function which will be called to obtain information about the contents of 
   the list. This should follow the form:

      char *foobar(int index, int *list_size);

   If index is zero or positive, the function should return a pointer to the 
   string which is to be displayed at position index in the list. If index 
   is negative, it should return NULL and list_size should be set to the 
   number of items in the list. 

   To create a multiple selection listbox, set the dp2 field to an array of 
   byte flags indicating the selection state of each list item (non-zero for 
   selected entries). This table must be at least as big as the number of 
   objects in the list!

MDK allows you to declare the listfunction with its contents. Your objects 
must be placed in the "Object in List"-box by double - clicking on an "EMPTY"
string.



===================================
========= Textbox procs ===========
===================================

 int d_textbox_proc(int msg, DIALOG *d, int c);
   A text box object. The dp field points to the text which is to be 
   displayed in the box. If the text is long, there will be a vertical 
   scrollbar on the right hand side of the object which can be used to 
   scroll through the text. The default is to print the text with word 
   wrapping, but if the D_SELECTED flag is set, the text will be printed 
   with character wrapping. The d1 field is used internally to store the 
   number of lines of text, and d2 is used to store how far it has scrolled 
   through the text.

MDK dialog for handling textbox-procs:

 The dp field of a textbox proc points to a char*. Therefore you can declare
 text procs as :

  Therefore your C output will be

     DIALOG textboxdialog= 
	   {     d_textbox_proc,x,y,w,h, flags,key,d1,d2, "My Textbox Text" }
    
    if you click on "dp points to ASCII" or 

    char[256] TextboxText="My Textbox Text";
    DIALOG textboxdialog= 
      {d_textbox_proc,x,y,w,h, flags,key,d1,d2,TextboxText }
    
   if you click on "dp points to Identifier". Notice, the char* mustnot exceed
   256 character.




===================================
==========  Slider procs ==========
===================================

int d_slider_proc(int msg, DIALOG *d, int c);
   A slider control object. This object holds a value in d2, in the range 
   from 0 to d1. It will display as a vertical slider if h is greater than 
   or equal to w, otherwise it will display as a horizontal slider. The dp 
   field can contain an optional bitmap to use for the slider handle, and 
   dp2 can contain an optional callback function, which is called each time 
   d2 changes. The callback function should have the following prototype:

      int function(void *dp3, int d2);

   The d_slider_proc object will return the value of the callback function.

MDK again allows you invoking the grabber for handling the Bitmap.



===================================
===========  Menu procs ===========
===================================




int d_menu_proc(int msg, DIALOG *d, int c);
   This object is a menu bar which will drop down child menus when it is 
   clicked or if an alt+key corresponding to one of the shortcuts in the 
   menu is pressed. It ignores a lot of the fields in the dialog structure, 
   in particular the color is taken from the gui_*_color variables, and the 
   width and height are calculated automatically. The dp field points to an 
   array of menu structures: see do_menu() for more information. The top 
   level menu will be displayed as a horizontal bar, but when child menus 
   drop down from it they will be in the normal vertical format used by 
   do_menu(). When a menu item is selected, the return value from the menu 
   callback function is passed back to the dialog manager, so your callbacks 
   should return D_O_K, D_REDRAW, or D_CLOSE.


The menu procs has perhaps the worst MDK support, so I plan to improve this
in the next version of MDK.

If you invoke the dialog you see the Menu-Tree. You can create different menus,
which have different dependencies to each other. The Main level- that is that
menu which has an horizontal bar (such as File,Edit...) - is the base Menu, which
is called by the Allegro-DIALOG. Therefore there is a tree of menus which are 
connected to each other, but there is the "base" menu of all. If you click on 
"next level" you'll get the next level in this tree. 

The menu-items can be generated/modified by click on an "Add new"
E.g. double click on it and fill in "&File" for adding a "File"-item.
Then you can connect this "File" item to either a function or an other menu in the 
tree by double clicking on your "File" item.  

===================================
========== Dialog Manager =========
===================================


The behavior of the dialog manager can be controlled by the variables:

extern int gui_mouse_focus;
   If set, the input focus follows the mouse pointer around the dialog, 
   otherwise a click is required to move it.

extern int gui_fg_color, gui_bg_color;
   The foreground and background colors for the standard dialogs (alerts, 
   menus, and the file selector). They default to 255 and 0.

extern int gui_mg_color;
   The color used for displaying greyed-out dialog objects (with the 
   D_DISABLED flag set). Defaults to 8.

extern int gui_font_baseline;
   If set to a non-zero value, adjusts the keyboard shortcut underscores to 
   account for the height of the descenders in your font.

You can change the global 'font' pointer to make the GUI objects use 
something other than the standard 8x8 font. The standard dialog procedures, 
menus, and alert boxes, will work with fonts of any size, but the 
file_select() and gfx_mode_select() dialogs will look wrong with anything 
other than 8x8 fonts.

int gui_textout(BITMAP *bmp, unsigned char *s, int x, y, color, centre);
   Helper function for use by the GUI routines. Draws a text string onto the 
   screen, interpreting the '&' character as an underbar for displaying 
   keyboard shortcuts. Returns the width of the output string in pixels.

int gui_strlen(unsigned char *s);
   Helper function for use by the GUI routines. Returns the length of a 
   string in pixels, ignoring '&' characters.

void centre_dialog(DIALOG *dialog);
   Moves an array of dialog objects so that it is centered in the screen.

void set_dialog_color(DIALOG *dialog, int fg, int bg);
   Sets the foreground and background colors of an array of dialog objects.

int find_dialog_focus(DIALOG *dialog);
   Searches the dialog for the object which has the input focus, returning 
   an index or -1 if the focus is not set. This is useful if you are calling 
   do_dialog() several times in a row and want to leave the focus in the 
   same place it was when the dialog was last displayed, as you can call 
   do_dialog(dlg, find_dialog_focus(dlg));

int dialog_message(DIALOG *dialog, int msg, int c, int *obj);
   Sends a message to all the objects in an array. If any of the dialog 
   procedures return values other than D_O_K, it returns the value and sets 
   obj to the index of the object which produced it.

int broadcast_dialog_message(int msg, int c);
   Broadcasts a message to all the objects in the active dialog. If any of 
   the dialog procedures return values other than D_O_K, it returns that 
   value.

int do_dialog(DIALOG *dialog, int focus_obj);
   The basic dialog manager function. This displays a dialog (an array of 
   dialog objects, terminated by one with a NULL dialog procedure), and sets 
   the input focus to the focus_obj (-1 if you don't want anything to have 
   the focus). It interprets user input and dispatches messages as they are 
   required, until one of the dialog procedures tells it to close the 
   dialog, at which point it returns the index of the object that caused it 
   to exit.

int popup_dialog(DIALOG *dialog, int focus_obj);
   Like do_dialog(), but it stores the data on the screen before drawing the 
   dialog and restores it when the dialog is closed. The screen area to be 
   stored is calculated from the dimensions of the first object in the 
   dialog, so all the other objects should lie within this one.

DIALOG_PLAYER *init_dialog(DIALOG *dialog, int focus_obj);
   This function provides lower level access to the same functionality as 
   do_dialog(), but allows you to combine a dialog box with your own program 
   control structures. It initializes a dialog, returning a pointer to a 
   player object that can be used with update_dialog() and 
   shutdown_dialog(). With these functions, you could implement your own 
   version of do_dialog() with the lines:

      void *player = init_dialog(dialog, focus_obj);

      while (update_dialog(player))
	 ;

      return shutdown_dialog(player);

int update_dialog(DIALOG_PLAYER *player);
   Updates the status of a dialog object returned by init_dialog(). Returns 
   TRUE if the dialog is still active, or FALSE if it has terminated. Upon a 
   return value of FALSE, it is up to you whether to call shutdown_dialog() 
   or to continue execution. The object that requested the exit can be 
   determined from the player->obj field.

int shutdown_dialog(DIALOG_PLAYER *player);
   Destroys a dialog player object returned by init_dialog(), returning the 
   object that caused it to exit (this is the same as the return value from 
   do_dialog()).

extern DIALOG *active_dialog;
   Global pointer to the most recent activated dialog. This may be useful if 
   an object needs to iterate through a list of all its siblings.

Popup or pulldown menus are created as an array of the structures:

typedef struct MENU
{
   char *text;                   - the text to display for the menu item
   int (*proc)();                - called when the menu item is clicked
   struct MENU *child;           - nested child menu
   int flags;                    - disabled or checked state
   void *dp;                     - pointer to any data you need
} MENU;

Each menu item contains a text string. This can use the '&' character to 
indicate keyboard shortcuts, or can be an zero-length string to display the 
item as a non-selectable splitter bar. If the string contains a "\t" tab 
character, any text after this will be right-justified, eg. for displaying 
keyboard shortcut information. The proc pointer is a function which will be 
called when the menu item is selected, and child points to another menu, 
allowing you to create nested menus. Both proc and child may be NULL. The 
proc function returns an integer which is ignored if the menu was brought up 
by calling do_menu(), but which is passed back to the dialog manager if it 
was created by a d_menu_proc() object. The array of menu items is terminated 
by an entry with a NULL text pointer.

Menu items can be disabled (greyed-out) by setting the D_DISABLED bit in the 
flags field, and a check mark can be displayed next to them by setting the 
D_SELECTED bit. With the default alignment and font this will usually 
overlap the menu text, so if you are going to use checked menu items it 
would be a good idea to prefix all your options with a space or two, to 
ensure there is room for the check.

int do_menu(MENU *menu, int x, int y)
   Displays and animates a popup menu at the specified screen coordinates 
   (these will be adjusted if the menu does not entirely fit on the screen). 
   Returns the index of the menu item that was selected, or -1 if the menu 
   was cancelled. Note that the return value cannot indicate selection from 
   child menus, so you will have to use the callback functions if you want 
   multi-level menus.

extern MENU *active_menu;
   When a menu callback procedure is triggered, this will be set to the menu 
   item that was selected, so your routine can determine where it was called 
   from.

int alert(char *s1, *s2, *s3, char *b1, *b2, int c1, c2);
   Displays a popup alert box, containing three lines of text (s1-s3), and 
   with either one or two buttons. The text for these buttons is passed in 
   b1 and b2 (b2 may be NULL), and the keyboard shortcuts in c1 and c2. 
   Returns 1 or 2 depending on which button was clicked. If the alert is 
   dismissed by pressing ESC when ESC is not one of the keyboard shortcuts, 
   it treats it as a click on the second button (this is consistent with the 
   common "Ok", "Cancel" alert).

int alert3(char *s1, *s2, *s3, char *b1, *b2, *b3, int c1, c2, c3);
   Like alert(), but with three buttons. Returns 1, 2, or 3.

int file_select(char *message, char *path, char *ext);
   Displays the Allegro file selector, with the message as caption. The path 
   parameter contains the initial filename to display (this can be used to 
   set the starting directory, or to provide a default filename for a 
   save-as operation). The user selection is returned by altering path, so 
   it should have room for at least 80 characters. The list of files is 
   filtered according to the file extensions in ext. Passing NULL includes 
   all files, "PCX;BMP" includes only files with .PCX or .BMP extensions. 
   Returns zero if it was closed with the Cancel button, non-zero if it was 
   OK'd.

int gfx_mode_select(int *card, int *w, int *h);
   Displays the Allegro graphics mode selection dialog, which allows the 
   user to select a screen mode and graphics card. Stores the selection in 
   the three variables, and returns zero if it was closed with the Cancel 
   button or non-zero if it was OK'd.

int gfx_mode_select_ex(int *card, int *w, int *h, int *color_depth);
   Extended version of the graphics mode selection dialog, which allows the 
   user to select the color depth as well as the resolution and hardware 
   driver. This version of the function reads the initial values from the 
   parameters when it activates, so you can specify the default values.




===================================
===== MDK's Color Dialog  ========
===================================



You can see the ID of the color in the upper right box. If you want to change it click 
on "Select with mouse" and then select it in the shown palette and press ok.

The new Palette-Dialog is not fully finished, though. You perhaps have discovered
that the silders in the Color do already their job, but you can't change the palette. 
Well, you'll have to wait...



===================================
===== MDK's C-output:colors   =====
===================================



MDK3.01 comes with fully 32 bit color support. The program itself can be executed in
all different color modes done by Allegro v3.0 .

The palette MDK uses is stored in "PALL.DAT". If you change the palette you can work 
with different colors.

A problem will occur once you work with a certain palette in 16 bit or higher mode: 
A 8 bit color like this in MDK's PALL.DAT has a number from 0 to 255. Once you save 
this color with its number in the palette and start the program with your DIALOG 
inside you'll see the DIALOG as you want to- but only if you are in 8 bit color mode.
In order to make the color independent from graphic mode, Shawn added an palette_color[]-
array. Here from Alegro.Txt:

 extern int palette_color[256];
   Table mapping palette index colors (0-255) into whatever pixel format is 
   being used by the current display mode. In a 256 color mode this just 
   maps onto the array index. In truecolor modes it looks up the specified 
   entry in the current palette, and converts that RGB value into the 
   appropriate packed pixel format.

So you have write 

 DIALOG Example=
  {d_button_proc ,124 ,198 ,150 ,42 ,251 ,46 ,0 ,D_EXIT ,0 ,0 , "Button" }
  
  and then init the color somewhere in your code with
   
 void MdkInitColor32(void) 
     {   
	  Example[0].fg=palette_color[251];
	  Example[0].bg=palette_color[46];
   }


 (In some cases you can directly write 
  DIALOG Example=
  {d_button_proc ,124 ,198 ,150 ,42 ,palette_color[251],palette_color[46] ,0 ,D_EXIT ,0 ,0 , "Button" }

  depending on writing C++ or C and static or not. But in any case
  void MdkInitColor32(void) works)


 Also, you have to init your palette in your code, so that you have to write:

   void MdkSetupColor(void) 
      {
	 DATAFILE *pal;
    colordepth=16;
	 pal=load_datafile("PALL.DAT");
	 set_palette(pal[0].dat);
	 MdkInitColor32(); 
	}

 
MDK creates these functions for your in the output file:
MdkInitColor32() is generated if you select "Save 32 bit colors" in the "write c File" Dialog,
MdkSetupColor() is generated if you select "Write Initfunction for 32 bit color dialogs".



===================================
===== MDK's C-output:comments =====
===================================


Often it is really nice to know the number of an item of your Allegro's DIALOG. 
Look at this output of MDK 


	// Allegro - C- code done with MichisDialogkiste
	//                   MDK 3.0
	#define _MDK30_DIALOG_BUTTON 0

	DIALOG MDK30_Dialog[]= { 
	/* 0 */ {d_button_proc ,124 ,198 ,150 ,42 ,251 ,46 ,0 ,D_EXIT ,0 ,0 , "Button" },
	/* 1 */ {d_text_proc ,118 ,168 ,90 ,18 ,251 ,46 ,0 ,0 , 0 ,0 , "TEXT" },
	 { NULL,0,0,0, 0,0,0,0,0,0,0,NULL}
	 };


In your code you'll perhaps write 
  
	if (MDK30_Dialog[0].flags==D_DCLICK) do_something();

MDK makes the comments for you, so that you easily can see the number of the button-"BUTTON".
This is useful if you have bigger dialogs with 10 or more items. 
You have to click "write numbered dialog objects (comments)" in the "Write C-File" to make 
MDK do so.

Also you might find even it more useful if your code is 

	if (MDK30_Dialog[_MDK30_DIALOG_BUTTON].flags==D_DCLICK) do_something();

This means your code need not to be changed once you rearrange your DIALOG.
MDK writes a #define including the name of your dialog plus the ASCII code of the dp field 
in uppercase. This is done for all D_EXIT objects in your DIALOG. 

Be careful if you have more than one OK buttons, MDK then will write same defines for each button, 
so that you will get an error... (still to be improved).

You have to click "write defines for D_EXIT objects " in the "Write C-File".



=======================================================
===== MDK's C-output:chars* and Global functions  =====
=======================================================


Many text-orientated gui-objects allow both direct ASCII's and Strings. 

That is e.g. 

  *ASCII:
	DIALOG textboxdialog= 
      {     d_textbox_proc,x,y,w,h, flags,key,d1,d2, "My Textbox Text" }

  *String:
	DIALOG radiodialog= 
	{d_textbox_proc,x,y,w,h, flags,key,d1,d2,Text }
   where also 
    char* Text has to be defined.
   
MDK stores the char* separately if you choose "Write char* inits"
 

Also if you want to init all functions MDK made for you and want easily 
to invoke them, MDK writes a global init function for all of your objects, such 
as bitmaps, callbacks, etc. This function is MdkSetupGlobal()

Assume you have an made a DIALOG with MDK and wrote it to a file called "MyDLG.C"
Then you can easily init the DIALOG:


include <allegro.h>
#include "pall.h"
#include "test.c"
void main()
{
   allegro_init();
   install_keyboard();
   install_timer();
   install_mouse();
 
   MdkInitGlobal();
   do_dialog(MDK30_Dialog, -1);
   exit(0);
  }

This should make things easier.

==========================================
===== MDK's new features since v2.71 =====
==========================================


New since v2.71:

+ Handles *all* Allegro GUI-objects

+ Allegro grabber (v3.0) is integrated into MDK for optimized handling of
  bitmap objects

+ 32bit color support (also for C-output)

+ C-output highly improved (added initialisation functions)

+ keyboard - proc completely rearranged

+ Placing of objects enabled (e.g. placing an object to the top of all others)

+ Optimzed blitting technique for the desktop

+ Added shortcuts for desktop operations (e.g. CTRK + C for copy)

+ Added help system (same as Allegro Grabber by Doug Eleveld / Shawn Hargreaves)

+ Added start-up menu

+ Added different mouse-styles 

+ Added new user setup



Changes from v3.0 to v3.01:

+ Cleared a bug in Setup menus (some values weren't editable)

+ Cleared a bug occured when copying sliders (NULL pointer)

+ Cleared a bug in the color Dialog (mouse range)

+ Added a viewer for mouse position

