@#
@# This is the source for the Adime readme, in Allegro's custom format. Read
@# allegro/docs/makedoc.c for a description of what is going on...
@#
@# And don't read this file; read readme.{txt|html|rtf|info|man} instead.
@#
@ignore_css
@multiplefiles
@multiwordheaders
@#locale=latin1
@document_title=Adime - API Reference
@html_footer=Back to Contents
@rtfh=Adime - Allegro Dialogs Made Easy
@# Note: this version number is patched by fixver.sh
@manh="version 2.2.1" "Adime" "Adime API Reference"
@mans=#include <adime.h>
@$\input texinfo
@$@setfilename adime.inf
@$@settitle Adime API Reference
@$@setchapternewpage odd
@$@paragraphindent 0
@$
@$@ifinfo
@$@direntry
@$* Adime: (adime). The Adime API Reference
@$@end direntry
@$This is the Info version of the Adime API Reference
@$
@$By Sven Sandberg
@$@end ifinfo
@$
@$@node Top, , (dir), (dir)
@<pre>
@!indent

                              _      _ _
                             /_\  __| (_)_ __  ___
                            / _ \/ _` | | '  \/ -_)
                           /_/ \_\__,_|_|_|_|_\___|

                           Allegro Dialogs Made Easy

                                 API Reference

                               by Sven Sandberg


@indent
@</pre>

@!text
@heading
Contents
@htmlindex License
@htmlindex Readme

@shortcontents



@text
@heading
Main Dialog Functions

@@int @adime_init(void);
@xref adime_exit
   Initializes the Adime system. Call it before using any other Adime
   functions and after calling `allegro_init()'. Returns zero on success and
   nonzero on error.

@@int @adime_exit(void);
@xref adime_init
   Shuts down the Adime system. You don't normally need to call this function
   since `adime_init()' will arrange for it to be called automatically when
   your program exits or `allegro_exit()' is called.

@@#define @ADIME_VERSION_MAJOR
@@#define @ADIME_VERSION_MINOR
@@#define @ADIME_VERSION_PATCH
@@#define @ADIME_DATE
   The version number (major.minor.patch) of your version of Adime, and the
   date when it was released in the form yyyymmdd.

@@int @adime_dialogf(const char *title, int x, y, w, const char *format, ...);
@xref adime_init
@xref adime_vdialogf
@xref Adime Colors, adime_bmp, adime_font
@xref adime_va_list
@#xref message_box
   Displays a dialog letting the user edit several different kinds of data.
   `title' specifies the caption of the dialog while `x' and `y' specify the
   top left corner of the dialog. Alternatively, either `x' or `y' or both
   can be set to `ADIME_ALIGN_CENTRE' or `ADIME_ALIGN_RIGHT', in which case
   the dialog will be centred respectively right aligned. `w' specifies the
   width of the input field. The total width of the dialog depends on this
   number, and on the length of the strings given to the dialog.

   The format string consists of one or more field descriptions, each
   followed be exactly one format specifier. The field description is a hint
   text used to help the user know what the field should contain. The format
   specifier is a percent sign, followed by an identifier, followed by a
   pair of square brackets (possibly with some extra options between (which
   I will refer to as "format modifier")) and can be any of the following:
<ul><li>
      %bool[]<br>
         A check box, which can be either on or off. Next argument should be
         an `int *', which will be set to 0 for off and 1 for on. Don't use
         other values!
<li>
      %greybool[]<br>
         A three-state greyable check box. Next argument should be an
         `int *', which will be set to 0 for off, 1 for on, or 2 for greyed.
         Don't use other values!
<li>
      %double[x,y], %float[x,y],<br>
      %int[x,y], %short[x,y], %char[x,y],<br>
      %uint[x,y], %ushort[x,y], %uchar[x,y],<br>
         A number in the given format (uchar, ushort and uint are unsigned).
         The number will be clamped to the interval `x' to `y', inclusive.
         You may omit `x' or `y' or both (but keep the comma!) to make it be
         the minimum respectively maximum for the data type. Next argument
         should be a pointer to the given data type.
<li>
      %pdouble[x,y], %pfloat[x,y],<br>
      %pint[x,y], %pshort[x,y], %pchar[x,y],<br>
      %puint[x,y], %pushort[x,y], %puchar[x,y],<br>
         "Plain" number formats: With the corresponding formats not prefixed
         by "p", the user can actually enter any mathematical expression,
         but these formats disable that feature so he can only enter
         numbers. Otherwise equal to their non-p-prefixed counterparts.
@# There is too much trouble with this. Maybe I'll implement it later.
@#<li>
@#    %longlong[x,y], %ulonglong[x,y],
@#    %plonglong[x,y], %pulonglong[x,y]
@#       Similar to %int[x,y], but for 64 bit numbers. These are only
@#       supported on platforms that have 64 bit numbers, so avoid using
@#       them if you want maximal portability. Next argument should be a
@#       pointer to a 64 bit number (you can use Allegro's macro LONG_LONG
@#       to refer to this in a platform-independent way, if the platform
@#       supports it).
<li>
      %string[bytes]<br>
         A string of length &lt= `bytes' (in bytes). Next argument should be
         a `char *' with room for at least the given number of characters.
         Remember that the number of characters that fit in the string will
         be less if you use Unicode. With UTF-8, a character may be as long
         as six bytes, and with Unicode they are always 2 bytes.
<li>
      %filename[len,extension,title]<br>
         A filename of length &lt= `len'. Next argument should be a `char *'
         with room for at least the given number of bytes (this really is
         bytes, not characters, and a UTF-8 string can have characters that
         are 6 bytes long, so you should allocate six times as many bytes as
         you want characters!). The user will be able to enter the filename
         as a text or click a button to bring up a file selector. `extension'
         is a semicolon-separated list of file extensions (ie in the format
         "bmp;pcx;tga;foo") which will be accepted by the file selector. You
         may omit `extension' (but keep the commas!), meaning that all file
         formats will be accepted. `title' is the title of the file selector
         dialog. You may also omit `title' (but keep the commas!), meaning
         that the description text for this field will be used.
<li>
      %list[lines,list]<br>
         The user can select an element in a list of strings. `lines'
         specifies the height, in lines, of the list box (this can be
         omitted to let the function calculate the height for you). `list'
         is a semicolon-separated list of strings (if one or more strings
         needs to contain a semicolon (';') or an end bracket (']'), the
         character can be escaped by a percent sign ('%')). Next argument
         should be an `int *', which will be set to the index of the
         string.
<li>
      %vlist[lines]<br>
         The user can select an element in a list of strings. `lines'
         specifies the height, in lines, of the list box (this can be
         omitted to let the function calculate the height for you). Next
         argument should be an `int *', which will be set to the index of
         the selected string, and then a `char **' which specifies the
         strings to choose among, then an `int' which tells how many
         strings the list contains.
<li>
      %datafile[lines,types]<br>
         The user can select an element in an Allegro DATAFILE. You should
         pass first an `int *', which will be set to the index of the
         datafile that was selected, and then a `DATAFILE *', which should
         be the datafile to look in. `lines' specifies the height, in
         lines, of the list box (this can be omitted to let the function
         calculate the height for you). `types' is a semicolon-separated
         list of datafile types. You must include all four characters in
         each type, so it could for example look like this:
<pre>
            "%datafile[7,BMP ;RLE ;XCMP; CMP]"
</pre>
<li>
      %wlist[lines,title,list]<br>
      %wvlist[lines,title]<br>
      %wdatafile[lines,title,types]<br>
         Like %list[], %vlist[] and %datafile, but rather than having the
         list box in the window, a button will be displayed. When the user
         clicks the button, a new window with the actual list in (and with
         the given title) will be opened.
<li>
      %nothing[]<br>
         No input data. Will only display the preceding description text as
         usually. This can be used if you want a section of the dialog to
         have a special header.
<li>
      %line[]<br>
         No input data. Will only display the preceding description text (if
         there is any) as usually, and then a horizontal delimitor line.
         Like %nothing[], this can be used if you want a section of the
         dialog to be delimited from the rest of the dialog.
<li>
      %button[text]<br>
         A button (with the given text on) which calls your custom callback.
         Next argument should be a function pointer, pointing to a function
         of the type
<pre>
            int my_callback(DIALOG *d);
</pre>
         This will be called when the user clicks the button. It will be
         given the dialog object representing the button. Its return value is
         a bit special: If it is 0, then nothing happens. If it is
         ADIME_REDRAW (which is defined to be the smallest negative number),
         then the dialog will be redrawn. If it is any other positive number,
         then the dialog will exit with that return value not saving the
         results of the dialog (the usual behavior of a cancel button). If it
         is any other negative number, then the sign will be removed and the
         unsigned number returned, and the contents of the dialog will be
         saved (the usual behavior of the ok button).

         You are allowed to open a new dialog inside your callback, which may
         be a less messy and more flexible alternative to %dialogf[].
<li>
      %buttonrow[BUTTONS]<br>
         One or more buttons in a horizontal row. These are displayed the
         same way as the OK and Cancel buttons (actually, the OK and Cancel
         buttons are implemented by appending a %buttonrow[] to the end of
         the dialog). Next argument should be a function pointer, pointing to
         a function of the type:
<pre>
            int my_callback(DIALOG *d, int n);
</pre>
         This will be called with the dialog object for the clicked button
         as the first argument and the index of this button as the second
         (i.e., n=1 for the first button, n=2 for the second and so on). The
         return value works the same way as for %button[] (see above).

         The modifier (BUTTONS) is itself a format string, consisting of a
         comma-separated list of buttons. Each button begins with the text
         which will appear on the button. Then comes an optional
         semicolon-separated list of shortcuts to this button. An example may
         help to clarify:
<pre>
            %buttonrow[OK;CTRL+O;ENTER,Cancel;ESC,Help;F1;ALT+H]
</pre>
         This format will display four buttons: OK, Cancel and Help. The
         OK button has the shortcuts CTRL-O and ENTER. The Cancel button has
         the shortcut ESC. The Help button has the shortcuts F1 and ALT-H.
         Shortcuts are specified in uppercase, with the state of
         shift, ctrl, alt etc preceding the key to press. The key has the
         same name as the `KEY_*' macro defined by Allegro (i.e., "ENTER" for
         `KEY_ENTER', "3" for `KEY_3' and "NUMLOCK" for `KEY_NUMLOCK'). The
         state consists of zero or more key shift flags separated by plus
         signs. The names of these are the same as Allegro's `KB_*_FLAG'
         macros (i.e., "SHIFT" for `KB_SHIFT_FLAG' and "CAPSLOCK" for
         `KB_CAPSLOCK_FLAG'). If you write e.g. CTRL+O, it means that CTRL
         must be held down while pressing O in order to activate the
         shortcut, while it is optional to hold down other key modifiers,
         e.g., SHIFT. If you don't want the shortcut to be activated when
         SHIFT is down (for instance), then you can write CTRL+-SHIFT+O,
         i.e., you precede the forbidden key with a minus sign.
<li>
      %dialogf[buttontext]<br>
         A button which opens another adime_dialogf() sub-dialog. Next
         argument should be the title of the dialog as a `char *', followed
         by `x', `y', `edit_w' as `int's and then `format' as a `char *'.
         These arguments correspond to the arguments given to
         `adime_dialogf()'. Depending on what `format' contains, you then have
         to add more parameters which the sub-dialog will alter. `buttontext'
         is the text which will be displayed on the button which opens the
         sub-dialog. An example may help to clarify:
<pre>
         adime_dialogf("My dialog",
                       ADIME_ALIGN_CENTRE, ADIME_ALIGN_CENTRE, 200,
                       "Open sub-dialog:%dialog[Click me!]",
                       "My sub-dialog",
                       ADIME_ALIGN_CENTRE, ADIME_ALIGN_CENTRE, 200,
                       "Save in text format:%bool[]",
                       &text_format);
</pre>
<li>
      %vdialogf[buttontext]<br>
         This is like %dialogf[], except that the `...' arguments are given
         as an `adime_va_list' rather than being expanded into the same
         argument list. (see also `adime_va_list')
<li>
      %chain[]<br>
         This is like an "inline" version of %vdialogf[]: You should pass two
         arguments, first a format string and then an `adime_va_list'. The
         dialog defined by this format string and `adime_va_list' will be
         inserted directly into this dialog. (See exchain.c for an example.)
</ul>
   Any special characters mentioned here can be escaped by placing a percent
   sign ('%') before it, e.g. if you need a literal ']' character somewhere
   in the format string. The field description may contain newlines.

   Returns 1 if the user selected the OK button, and 2 if he selected the
   Cancel button. The `...' parameters will be left untouched if the user
   clicked Cancel but they will change to the new values if he clicked OK.
   The initial values of the parameters will be taken as default values in
   the dialog objects.

   The debug library is very useful when you use this function: It can
   detect almost all illegal format strings. If it finds one, it shuts down
   the program with a traceback and writes a description of the error to the
   file allegro.log.

   An example may help to clarify things (see also the programs in the
   examples directory):
<pre>
      char name_buffer[1024] = "";
      int age = 20;
      int shoe_size = 40;
      int married = 0;
      char filename_buffer[1024] = "";

      adime_dialogf("Fill in personal data",
                    ADIME_ALIGN_CENTRE, ADIME_ALIGN_CENTRE, 200,
                    "Name%string[1024]"
                    "Age (years)%int[0,150]"
                    "%line"
                    "Shoe size (Swedish units)%float[10,60]"
                    "Married%bool[]"
                    "Favourite text file%filename[1024,txt,Select a text file]",
                    name_buffer,
                    &age,
                    &shoe_size,
                    &married,
                    filename_buffer);
</pre>
@\int @adime_vdialogf(const char *title, int x, y, w, const char *format,
@@                   adime_va_list args);
@xref adime_dialogf, adime_va_list
   This is the same as `adime_dialogf()', but with an `adime_va_list' instead
   of variable number of arguments.

@\int @adime_lowlevel_dialogf(const char *title, int x, y, w,
@@                           const char *format, ...);
@xref adime_dialogf
   This is the same as `adime_dialogf()', except it doesn't include the
   default `OK' and `Cancel' buttons. You will normally want to call this
   function with the last format being "%buttonrow[]".

@\int @adime_lowlevel_vdialogf(const char *title, int x, y, w,
@@                            const char *format, adime_va_list args);
@xref adime_dialogf, adime_va_list
   This is the same as `adime_lowlevel_dialogf()', but with an
   `adime_va_list' instead of variable number of arguments.

@@typedef @adime_va_list;
@@void @adime_va_start(adime_va_list ap, first_arg);
@@TYPE @adime_va_arg(adime_va_list ap, TYPE);
@@void @adime_va_end(adime_va_list ap);
@xref adime_vdialogf, adime_dialogf, adime_lowlevel_vdialogf
   Because of weirdnesses in the C language, some things that Adime does with
   va_lists would not be portable if it used a va_list directly. Instead you
   always have to use this replacement API, which works exactly like the
   standard API for va_lists, but is more portable. Also, if you pass an
   `adime_va_list' to another function, which reads an argument with
   `adime_va_arg()', then the `adime_va_list' will have advanced to the same
   position in the calling function as in the called function. In particular,
   after calling `adime_vdialogf()', the `adime_va_list' will have advanced
   to after the last argument used by Adime.

   The following example shows how `adime_dialogf()' is implemented in terms
   of `adime_vdialogf()':
<pre>
      int adime_dialogf(char *title, int x, int y, int edit_w,
                        char *format, ...)
      {
         int ret;
         va_list ap;

         va_start(ap, format);
         ret = adime_vdialogf(title, x, y, edit_w, format, ap);
         va_end(ap);

         return ret;
      }
</pre>
   See documentation for the standard `va_list', `va_start()', `va_arg()' and
   `va_end()' for more information.
@#
@# Not yet implemented.
@#
@#@\int @message_box(const char *title, const char *buttons,
@#@@const char *text, ...);
@#@xref vmessage_box, adime_dialogf
@#@xref Adime Colors, adime_font, adime_bmp
@#   This is like Allegro's alert() function, but much more flexible. It takes
@#   a dialog title as first argument and a message in the usual printf format
@#   as last argument. The text will be word-wrapped automatically. You may
@#   force line breaks in it using '\n'. The `buttons' argument is a format
@#   string on the following form:
@#<pre>
@#    "&Yes;@&No;&Cancel[esc];&Help[f1]"
@#</pre>
@#   The button texts are separated by semicolons. The (optional) shortcut
@#   character is preceded by an ampersand (so pressing 'y' in the  example is
@#   the same as clicking the Yes button). The default button is preceded by
@#   an @ character. Any additional shortcuts are enclosed in [].
@#
@#   Returns the index of the button that was pressed, beginning with 1 for
@#   the first one.
@#
@#   Example:
@#<pre>
@#      message_box("Error", "&Try again;&Cancel",
@#                  "Invalid color depth: %d.\nYou bastard!", 17);
@#</pre>
@#@\int @vmessage_box(const char *title, const char *buttons,
@#@@                 const char *text, va_list args);
@#@xref message_box
@#   This is the same as `message_box()', but with a `va_list' instead of
@#   variable number of arguments.



@heading
Dialog Configuration Variables

By tweaking the variables in this section, you can change the general
appearance of Adime's dialogs.

@@BITMAP *@adime_bmp;
@xref adime_dialogf, adime_font
   If you want the dialog to be displayed on a certain video bitmap other
   than `screen', set this to point to that bitmap. This is particulary
   useful if you for some reason have scrolled away from the top left area
   of the video memory and want the dialog to be displayed on currently
   visible video memory rather than on the default location. If this is NULL
   (it is by default), `adime_dialogf()' & co will scroll to the top left
   corner of screen and use that part to display the dialog on.

@@FONT *@adime_font;
@@FONT *@adime_title_font;
@@FONT *@adime_button_font;
@xref adime_dialogf, adime_bmp
   The font used in general by Adime dialogs and objects, the font for the
   title of the dialogs and the font for the OK and Cancel buttons. If one
   of them is NULL (they all are by default), Allegro's `font' will be used.

@@int @adime_yield;
@xref adime_dialogf, adime_clean_screen
   Flag indicating whether or not Adime dialogs should call Allegro's
   function `yield_timeslice()' continuously when it has nothing better to
   do. Default is `TRUE'. This flag has no effect while the file selector is
   open: `yield_timeslice()' will always be called then.

@@int @adime_clean_screen;
@xref adime_dialogf, adime_yield, adime_window_visible
   Flag indicating whether or not Adime dialogs should restore the screen
   after they have been closed. Default is `TRUE', indicating that the screen
   should be restored.

@@int @adime_window_visible;
@xref adime_dialogf, adime_yield, adime_clean_screen
   Flag indicating whether the background window of Adime dialogs should be
   drawn. Default is `TRUE', indicating it should be drawn.

@@void (*@adime_callback)(DIALOG *d)
@xref adime_dialogf
   If you set this to something else than `NULL', then that function will be
   called continuously as long as a Adime dialog is open. The argument `d'
   will point to the first object of the current Adime dialog, or the first
   object of Allegro's file selector when it's open. See
   adime/examples/exanim.c for an example on how to use this to do animation
   while a dialog is open.

@hnode Adime Colors
@xref adime_dialogf
@#xref adime_message_box
extern RGB<ul>
   adime_text_rgb,<br>
   adime_disabled_text_rgb,<br>
   adime_error_text_rgb,<br>
   adime_border_rgb,<br>
   adime_background_rgb,<br>
   adime_edit_field_rgb,<br>
   adime_button_rgb,<br>
   adime_dark_shadow_rgb,<br>
   adime_shadow_rgb,<br>
   adime_highlight_rgb,<br>
   adime_light_highlight_rgb;<br>
   These variables specify the color of different parts of the dialog shown
   by `adime_dialogf()'. You may change them if you want other colors (the
   default is similar to the windows gray semi-3d look). Each r, g, and b
   component ranges from 0 to 255 no matter which the current color depth is.
   In 8 bit modes the closest entry in the palette is found, so it is your
   responsibility to make sure that the palette contains similar colors. As
   a special case, if you set the `filler' field of the RGB struct to 1
   rather than 0, then the `r' field will be used without searching the
   palette. (This can be useful if you depend on a certain palette index to
   be used.)

   Most of the variable names should be pretty self-explanatory.
   `adime_disabled_text_rgb' is very seldom used and is the color of text on
   buttons that can't be pressed. `adime_error_text_rgb' is the color of the
   result of an expression if the expression was invalid (e.g. contained
   mismatched parentheses). Hopefully you will understand the other names,
   but if you don't, they are common enough that you should be able to find
   out with some trial and error.
</ul>
@hnode Adime Metrics
@xref adime_dialogf
@#xref adime_message_box
extern int<ul>
   adime_window_border_thickness,<br>
   adime_window_title_spacing,<br>
   adime_window_button_spacing,<br>
   adime_window_between_button_spacing,<br>
   adime_window_description_spacing,<br>
   adime_window_line_spacing,<br>
   adime_window_button_w,<br>
   adime_window_button_h,<br>
   adime_window_title_border_thickness,<br>
   adime_window_title_internal_border_thickness;<br>
   These variables specify the size and spacing of different parts of Adime
   dialogs. `border_thickness' is the spacing from the border to the
   contents of the dialog; `title_spacing' is the spacing between the title
   and the first object; `button_spacing' is the spacing above the OK and
   Cancel buttons; `between_button_spacing' is the spacing between the
   buttons; `description_spacing' is the horizontal spacing between the
   description text and the input field; `line_spacing' is the vertical
   spacing between two objects in the dialog; `button_w' and `button_h'
   specify the size of the OK and Cancel buttons; `title_border_thickness' is
   the space between the dialog title and the edge of the dialog;
   `title_internal_border_thickness' is the space inside the title from the
   edge to the text.

   Of these variables, only the `adime_window_title_*' ones affect the file
   selector.
</ul>


@heading
Other GUI Functions

NOTE: Many, maybe all, of these functions may soon move to another library,
and their API may change at that point. So they may not be forwards
compatible.

@\int @adime_file_select(const char *message, char *path, const char *ext,
@@                      int size, int w, int h);
@xref adime_dialogf, Adime Metrics
   Like Allegro's `file_select_ex()', but with Adime's 3d look and feel. It
   is not affected by all `adime_window_*' variables though, only the ones
   beginning with `adime_window_title_*'. Also, it has the extra feature of
   not changing `path' if it gets cancelled.

@@int @adime_d_double_calc_edit_proc(int msg, DIALOG *d, int c);
@xref adime_d_calc_edit_result_proc
@xref adime_d_int_calc_edit_proc
   Gui proc for an edit box accepting a mathematical expression whose result
   is a floating point number. The result is calculated and displayed on a
   separate gui object as the user types. The edit box has a 3d-ish look.<br>
   The dp2 field points to a `struct ADIME_EDIT_NUMBER *' which holds some
   information about the behavior of the edit box:
<pre>
   typedef struct ADIME_EDIT_NUMBER
   {
      int is_signed;          /* Set for integer formats if it is signed. */
      int is_float;           /* Set if we only have float, not double. */
      double min_val, max_val;/* Range for numbers. */
      DIALOG *result_object;  /* DIALOG object to display result in. */
   } ADIME_EDIT_NUMBER;
</pre>
   The `result_object' will be used to display the result of the expression.
   There is an `adime_d_calc_edit_result_proc' object type which is designed
   to be used as `result_object', but you may of course write your own object
   to take care of this. Whenever the user changes the text in the
   `adime_d_double_calc_edit_proc', the result is printed to the `dp' field of
   `result_object'; hence you must have set the dp field of `result_object'
   to a text buffer with enough space (256 bytes is safe). The
   `result_object' will then be sent a `MSG_DRAW' message with the `c'
   parameter set to 2 if there is an error in the expression or 1 if it is
   ok.

@@int @adime_d_int_calc_edit_proc(int msg, DIALOG *d, int c);
@xref adime_d_double_calc_edit_proc
@xref adime_d_calc_edit_result_proc
   Like `adime_d_double_calc_edit_proc()', but displaying the result as an
   integer. If the user tries to enter a floating point value, it will be
   rounded.

@@int @adime_d_calc_edit_result_proc(int msg, DIALOG *d, int c);
@xref adime_d_int_calc_edit_proc
@xref adime_d_double_calc_edit_proc
   Dialog proc for the result of a calculator edit box. The difference
   between this and Allegro's `d_text_proc()' is that it uses the c parameter
   to find the color to draw with (see `d_double_calc_edit_proc()'), and it
   also erases its whole area even if the text doesn't fill it.

@@int @adime_d_line_proc(int msg, DIALOG *d, int c);
   A simple dialog object which draws a 3d-ish horizontal or vertical line
   (depending on whether its `w' field is greater or less than its `h'
   field).

@@int @adime_d_check_proc(int msg, DIALOG *d, int c)
@xref adime_d_greyable_check_proc
   Like Allegro's `d_check_box()', but with 3d-ish style.

@@int @adime_d_greyable_check_proc(int msg, DIALOG *d, int c)
@xref adime_d_check_proc
   A three-state greyable version of `adime_d_check_box()'. Unlike
   `adime_d_check_proc()', this does not use the (flags & D_SELECTED) flag
   to determine the state of the check box. Instead, the d1 field is 0 for
   off, 1 for on, and 2 for greyed.

@@int @adime_d_list_proc(int msg, DIALOG *d, int c)
   Like Allegro's `d_list_proc()', but with 3d-ish style.

@@int @adime_d_text_list_proc(int msg, DIALOG *d, int c)
   Like Allegro's `d_text_list_proc()', but with 3d-ish style.

@@int @adime_d_edit_proc(int msg, DIALOG *d, int c)
   Like Allegro's `d_edit_proc()', but with 3d-ish style. Note that the 3d
   border is three pixels wide, so you have to add those pixels to the size
   of the edit box. It also adds an extra feature: The `d->d1' field, if
   positive, is the maximal number of characters, just like with
   d_edit_proc(). But you may also set it to be negative, meaning that (after
   removing the sign) it is the maximal number of bytes occupied by the
   string, including the trailing zero. (This may be different from the
   number of characters when you use Unicode.)

@@int @adime_d_button_proc(int msg, DIALOG *d, int c)
   Similar to Allegro's `d_button_proc()', but with 3d-ish style. It also has
   a slightly different behaviour: Unlike `d_button_proc()', the D_EXIT flag
   has no effect. Instead you need to set the `d1' field to one of the three
   constants:
<ul><li>
      ADIME_BUTTON_TOGGLE<br>
         The button behaves like a check box, i.e. when clicked it toggles
         between being in and being out.
<li>
      ADIME_BUTTON_EXIT<br>
         The button exits the dialog when clicked.
<li>
      ADIME_BUTTON_CALLBACK<br>
         If you provide a callback function in the dp2 field, then it will
         be called whenever the button is clicked. This callback should have
         the form `int my_callback(DIALOG *d)', and its return value will be
         passed back to the dialog manager.
</ul>
@@int @adime_d_multiline_text_proc(int msg, DIALOG *d, int c)
   Like Allegro's `d_text_proc()', but supports newlines ('\n') in the
   string.

@@int @adime_d_window_proc(int msg, DIALOG *d, int c)
   Gui proc that draws a window. The `dp' field should be the caption of
   the dialog, as a string. All fields except x, y, w, h are ignored. Note
   that this object is purely cosmetical: you can't move or resize the
   window.

@\void @adime_draw_empty_button(BITMAP *bmp, int x1, int y1, int x2, int y2,
@\                             int face_color, int xlight, int light,
@@                             int dark, int xdark)
@xref adime_draw_text_button, adime_draw_picture_button
   Draws an empty button on the given position of the bitmap, using the
   given colors.

@\void @adime_draw_text_button(BITMAP *bmp, int x1, int y1, int x2, int y2,
@\                            int face_color, int text_color,
@\                            int xlight, int light, int dark, int xdark,
@@                            const FONT *f, const char *text)
@xref adime_draw_text_button_down, adime_draw_empty_button
@xref adime_draw_picture_button
   Draws a button with a text on it, at the given position of the bitmap and
   using the given colors and font.

@\void @adime_draw_text_button_down(BITMAP *bmp,
@\                                 int x1, int y1, int x2, int y2,
@\                                 int face_color, int text_color,
@\                                 int xlight, int light, int dark, int xdark,
@@                                 const FONT *f, const char *text)
@xref adime_draw_text_button
   Like `adime_draw_text_button()', but draws the button pressed down.

@\void @adime_draw_picture_button(BITMAP *bmp, int x1, int y1, int x2, int y2,
@\                               int face,int xlight, int light, int dark, int xdark,
@@                               BITMAP *sprite)
@xref adime_draw_picture_button_down, adime_draw_empty_button
@xref adime_draw_text_button
   Draws a button with a sprite on it at the given position of the bitmap
   and using the given colors and sprite.

@\void @adime_draw_picture_button_down(BITMAP *bmp,
@\                                    int x1, int y1, int x2, int y2,
@\                                    int face, int xlight, int light,
@\                                    int dark, int xdark,
@@                                    BITMAP *sprite)
@xref adime_draw_picture_button
   Like `adime_draw_picture_button()', but draws the button pressed down.

@\void @adime_fill_textout(BITMAP *bmp, const FONT *f, const char *text,
@@                        int x, int y, int w, int fg, int bg)
   Like Allegro's `textout()', but erases the whole area of width `w' if the
   text doesn't cover it. If the text is longer than `w' it will be clipped.



@# I'll finish adding gui stuff for these before making them official.
@# The api may change later because edit() may want one unicode key argument,
@# one scancode argument and one key_shifts argument along with the `EDITBOX'
@# argument.
@#
@#@heading
@#Edit box functions
@#
@#Adime provides some functions for handling edit boxes in a more advanced way
@#than Allegro does. You can type text, move the cursor using the arrow keys,
@#delete text, select text and use clipboard. In the current version, the
@#functions can only change the string and move the cursor, not for drawing the
@#edit box or inserting it into a gui. I'll add this to a later version if I
@#get time, if I need it badly or if someone does it for me. See the help for
@#`edit()' for more information on how you can use the functions already. There
@#are also some (mostly internal) functions for handling clipboard.
@#
@#@@int @edit(EDITBOX *ed, int key, int shifts)
@#@xref create_edit, destroy_edit, EDITBOX
@#   Top-level function for handling keypresses in an EDITBOX. Pass it the
@#   return value from `readkey()' as second parameter, and a copy of Allegro's
@#   variable `key_shifts' as third.<br>
@#   To use edit box functions you should:<br>
@#    1. Declare an `EDITBOX *' variable.<br>
@#    2. Initialize it using `create_edit()'.<br>
@#    3. Call `edit()' each time the user presses a key.<br>
@#    4. Draw the edit box using your own routines.<br>
@#    5. Repeat step 3 and 4 until you're happy with the text in the edit box.<br>
@#    6. Free the memory used by the edit box by calling `destroy_edit()'.<br>
@#
@#@@typedef struct @EDITBOX {
@#   char *text;<br>
@#   int pos;<br>
@#   int selstart, sellength;<br>
@#   EDITBOX_OPTIONS *options;<br>
@#} EDITBOX;<br>
@#@xref EDITBOX_OPTIONS, create_edit, edit
@#   Holds information about an edit box. `text' is the text and `pos' is the
@#   current cursor position. If there is a selection, `selstart' tells where
@#   the selection starts, and `sellength' tells the length of the selection.<br>
@#   There are some more fields in the struct as well, but only such that are
@#   used internally.<br>
@#
@#@@typedef struct @EDITBOX_OPTIONS {
@#   int max_length;<br>
@#   int max_bytes;<br>
@#   int max_pixel_width;<br>
@#   FONT *font;<br>
@#   int write_protected;<br>
@#   int dynamic;<br>
@#   int free_text_on_destroy;<br>
@#   int clipboard_functions;<br>
@#} EDITBOX_OPTIONS;<br>
@#@xref EDITBOX, create_edit
@#   Short description:<br><ul>
@#      The logical difference between the `EDITBOX_OPTIONS' struct and the
@#      `EDITBOX' struct is as follows: `EDITBOX' holds information that
@#      changes while the user is typing, like the text and cursor position.
@#      `EDITBOX_OPTIONS' holds information about the behaviour of the edit
@#      box, like font and limitations on text length. These properties must
@#      not be changed after the `EDITBOX' is created.<br></ul>
@#   Long description:<ul><br>
@#      max_length<ul>
@#         Limits the length of the text in an edit box, measured in number of
@#         characters. If you set it to -1, the length will be unlimited.
@#      </ul>
@#      max_bytes<ul>
@#         Limits the number of bytes that the text in an edit box may occupy.
@#         This might be different from the length in characters if you are
@#         using Unicode. If you set it to -1, the length will be unlimited.
@#      </ul>
@#      max_pixel_width<ul>
@#         Limits the width in pixels of the text. If you set it to -1, the
@#         width will be unlimited.
@#      </ul>
@#      font<ul>
@#         The font used by the edit box.
@#      </ul>
@#      write_protected<ul>
@#         If set, the user will only be able to move the cursor, select text
@#         and copy text to clipboard, but not change the text.
@#      </ul>
@#      dynamic<ul>
@#         If set, the text will be realloced as needed when typing.
@#      </ul>
@#      free_text_on_destroy<ul>
@#         If set, the text field will be freed when you call `destroy_edit()'.
@#         This might be useful if you want the text field in the `EDITBOX'
@#         struct to be a static buffer.
@#      </ul>
@#      clipboard_functions<ul>
@#         Should be set to one of the three values:<br><ul>
@#            EDIT_CLIPBOARD - Full clipboard and selection functionality.<br>
@#            EDIT_SELECT    - You can select, but not use clipboard.<br>
@#            EDIT_NOSELECT  - Neither selections or clipboard is supported.<br></ul>
@#         If you are too lazy to write a function that draws selected text, it
@#         may be a good idea to turn of selections.
@#      </ul>
@#      There are some more fields here too, but either they are only for
@#      internal use, or not implemented yet, or you just shouldn't care about
@#      them :-)</ul>
@#
@#@@EDITBOX *@create_edit(EDITBOX_OPTIONS *eo, const char *text)
@#@xref destroy_edit, edit, EDITBOX, EDITBOX_OPTIONS
@#   Creates a new edit box and returns it. You should normally pass it the
@#   address of the predefined variable `_normal_edit', which defines an edit
@#   box with unlimited text length, dynamically realloced text, full clipboard
@#   functionality and which uses Allegro's font. If these default options
@#   don't suit your program, change them before you call `create_edit()'. The
@#   second parameter is the text to edit. Be aware that it won't be
@#   duplicated, so if the dynamic flag in the `EDITBOX_OPTIONS' is set, you
@#   must make sure the memory is actually dynamically allocated.
@#
@#@@void @destroy_edit(EDITBOX *ed)
@#@xref create_edit, EDITBOX
@#   Destroys an edit box when you are finished with it. If the
@#   `free_text_on_destroy'-flag in the `EDITBOX_OPTIONS' struct is set, the
@#   text will be freed.
@#
@#@@int @edit_set_text(EDITBOX *ed, const char *text)
@#@xref edit_set_pos
@#   Copies the specified text to the edit box. You should normally use this
@#   function rather than explicitly patching in the `text' field in the
@#   `EDITBOX' struct.
@#
@#@@int @edit_set_pos(EDITBOX *ed, int pos)
@#@xref edit_select_to_pos, edit_select_all, edit_select_word_at_pos
@#@xref edit_set_text
@#   Places the cursor at the position `pos' in the edit box. If text was
@#   selected, this function will unselect it.
@#
@#@@int @edit_select_to_pos(EDITBOX *ed, int pos)
@#@xref edit_set_pos, edit_select_all, edit_select_word_at_pos
@#   Extends the selection of the edit box so that the current position is
@#   `pos'. In most windows editors this is what happens when you hold down
@#   shift and click with the mouse at position `pos'.
@#
@#@@int @edit_select_all(EDITBOX *ed)
@#@xref edit_set_pos, edit_select_to_pos, edit_select_word_at_pos
@#   Selects the whole text in the edit box.
@#
@#@@int @edit_select_word_at_pos(EDITBOX *ed, int pos)
@#@xref edit_set_pos, edit_select_to_pos, edit_select_all
@#   Selects one word at the position `pos' in the edit box.
@#
@#@@int @edit_delete_sel(EDITBOX *ed)
@#@xref edit_cut
@#   Deletes the text in the selection. (Does nothing if there is no
@#   selection.)
@#
@#@@int @edit_cut(EDITBOX *ed)
@#@xref edit_delete_sel, edit_copy, edit_paste
@#   Cuts text from the edit box into clipboard (if there is a selection).
@#
@#@@int @edit_copy(EDITBOX *ed)
@#@xref edit_cut, edit_paste
@#   Copies text into clipboard (if there is a selection).
@#
@#@@int @edit_paste(EDITBOX *ed)
@#@xref edit_cut, edit_copy
@#   Pastes text from clipboard (unless clipboard is empty).
@#
@#
@#
@heading
Other Functions

@\double @adime_evaluate(const char *equation, int *error,
@@                      double (*var)(const char *name));
@xref adime_uevaluate
   Helper function for evaluating arithmetic expressions, which may be
   useful in your programs even though it isn't really logically connected
   to the other functions (i.e. it's not a gui function). It evaluates the
   provided equation, returning the result, and storing a nonzero value in
   `error' if anything goes wrong. If the `var' function is not NULL, this
   will be called whenever a variable is encountered in the expression,
   allowing you to look up and return a suitable value for it. For more
   information on the expressions, see expressi.txt

@\double @adime_uevaluate(const char *equation, int *error,
@@                       double (*var)(const char *name));
@xref adime_evaluate
   Like `adime_evaluate()', but tweaked to fit Adime's purposes better: It
   silently accepts an empty string without error (being equivalent to "0"),
   it supports Unicode and it gives an error if the result is NaN.

@@void @adime_double2string(double x, char *buf);
@xref adime_udouble2string
   Function for pretty-printing floating point numbers: The number gets at
   most 10 digits to the left of the decimal point, at most 9 to the right
   of it, and at most 10 totally. If the absolute value of the number is
   &gt= 10000000000 or &lt 0.000001, it is written in exponential form
   instead. Exponential form has at most 6 digits in the mantissa, so that
   the total number of digits never exceeds 9. Does not support Unicode.

@@void @adime_udouble2string(double val, char *buf)
@xref adime_double2string
   Unicode-aware version of `adime_double2string()'.

@@char *@adime_scancode_to_short_name(int scancode, char *buf)
@xref adime_scancode_to_pretty_name, adime_short_name_to_scancode
   Converts a keyboard scancode to a string. The string is exactly the text
   after `KEY_' in the macro name for the key (so the function returns
   "DELETE" if you feed it with KEY_DELETE). Returns the buffer, or NULL if
   the scancode didn't match any known key.

@@char *@adime_scancode_to_pretty_name(int scancode, char *buf)
@xref adime_scancode_to_short_name, adime_short_name_to_scancode
   The result from `adime_scancode_to_short_name()' is sometimes an
   abbreviation and may contain underscores. You may want to use this
   function instead if you are going to display the result for the user: it
   returns more user-friendly strings.

@@int @adime_short_name_to_scancode(const char *short_name)
@xref adime_scancode_to_short_name, adime_scancode_to_pretty_name
   Given the name for a key as a string (in the format given by
   `adime_scancode_to_short_name()'), this function returns the scancode for
   the key, or -1 if the string doesn't represent any known scancode.



@headingnocontent
Reducing the Executable Size

If you don't use all the adime_dialogf() formats, then you can declare a list
of all formats that you use so that the others don't get linked into the
executable. This will only save up to about 10 KB, but see Allegro's
documentation (the "Reducing your executable size" section) for more hints
on how to get rid of much more size. The list of formats should look like
this:
<pre>
   ADIME_BEGIN_FORMAT_LIST
      format1
      format2
      etc...
   ADIME_END_FORMAT_LIST
</pre>
where format1, format2 etc are any of the macros:
<pre>
   ADIME_FORMAT_BOOL
   ADIME_FORMAT_BUTTON
   ADIME_FORMAT_STRING
   ADIME_FORMAT_FILENAME
   ADIME_FORMAT_VLIST
   ADIME_FORMAT_LIST
   ADIME_FORMAT_DATAFILE
   ADIME_FORMAT_WVLIST
   ADIME_FORMAT_WLIST
   ADIME_FORMAT_WDATAFILE
   ADIME_FORMAT_DIALOGF
   ADIME_FORMAT_VDIALOGF
   ADIME_FORMAT_INT
   ADIME_FORMAT_PINT
   ADIME_FORMAT_UINT
   ADIME_FORMAT_PUINT
   ADIME_FORMAT_SHORT
   ADIME_FORMAT_PSHORT
   ADIME_FORMAT_USHORT
   ADIME_FORMAT_PUSHORT
   ADIME_FORMAT_CHAR
   ADIME_FORMAT_PCHAR
   ADIME_FORMAT_UCHAR
   ADIME_FORMAT_PUCHAR
   ADIME_FORMAT_DOUBLE
   ADIME_FORMAT_PDOUBLE
   ADIME_FORMAT_FLOAT
   ADIME_FORMAT_PFLOAT
   ADIME_FORMAT_LINE
   ADIME_FORMAT_NOTHING
   ADIME_FORMAT_BUTTONROW
   ADIME_FORMAT_CHAIN
</pre>
Like in Allegro, this will only work for the statically linked library.
Note that ADIME_FORMAT_BUTTONROW and ADIME_FORMAT_CHAIN are used internally,
so you shouldn't remove them unless you are sure that you know what you are
doing.



@htmlindex Internal
@htmlindex Expressi
@htmlindex Changes
@htmlindex Thanks
@htmlindex Wishlist