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

                               Dialogs Made Easy
                                  version 1.2b

                                  Readme File

                          http://dime.sourceforge.net/

                               by Sven Sandberg

Introduction
Licence
Requirements
Installation
Usage
Common Problems
Changes
Wish List
Authors
Thanks
Contact Info

Introduction

Dime is a library with functions for constructing Allegro gui dialogs in a simple way similar to scanf(), but much nicer for the user of course. You only need one line of code to create a dialog where the user can input eg two integers and one string, and select one file. This way it becomes a lot easier to open certain kinds of dialogs.

The following platforms are supported: DOS/DJGPP, DOS/Watcom, Linux, Windows/Mingw32 and Windows/MSVC.

This documentation is compiled the same way as Allegro's, so after installing the library you can read it in txt, html, inf, rtf or man format.

Licence

Dime is completely free. You may use and distribute it freely and you don't have to give us anything back. It would be nice if you mentioned Dime in the credits, and even nicer if you gave me some feedback (this could be a bug report, a suggestion of a new feature or just a message saying that you adore the library and wouldn't be able to continue living without it, etc) but you are not required to do so.

I have no responsibility for any damage caused by Dime.

Requirements

You need to have installed and compiled Allegro (http://www.talula.demon.co.uk/allegro/). All other requirements must already be fulfilled if you manage to compile Allegro.

Installation

Installation goes in three simple steps, and should be familiar since it is exactly the same way as you installed Allegro:

Tell the installation process what platform you use. This is done by running "fixdjgpp.bat", "fixming.bat" or "fixmsvc.bat" for djgpp, mingw32 or msvc respectively.
Compile the library. This is done by running "make" at the command line. This may generate a bunch of warnings if you are using a version of Allegro that is older than 3.9.34, but they can safely be ignored.
Install the files to common directories. This is done by running "make install" at the command line.

That's it! You may also want to perform some of the optional steps:

You can compile a debugging library by typing "make DEBUGMODE=1". To compile both the usual and the debug library at once, type "make all". There is no profiling version of the library (it doesn't make sense to profile a gui dialog that is just waiting for input :-).
To use the debugging library, link with libdimed.a instead of libdime.a.
If you want to read the Dime documentation with the Rhide online help system, go to the "Help / Syntax help / Files to search" menu, and add "dime" after the existing "libc" entry (separated by a space).
If you want statically linked libraries under Unix or Windows as well as the default dynamically linked libraries (dll under Windows, .so under Unix), set the environment variable "STATICLINK=1", and repeat the "make install" and "make install DEBUGMODE=1". These static libraries require the statically linked version of Allegro.
If you want to save some disk space, you can run "make compress". This will use UPX (see http://upx.tsx.org) to compress the executable files. Under windows, it will also compress the optimized dll. Note that you will have to do this before "make install" if you want the compressed dll to be copied to the windows directory.

Usage

You need Allegro in order to use this library. You most likely already have it since you found this library, but if you don't have it you should download it from http://www.talula.demon.co.uk/allegro/ and get familiar with it before using Dime.

#include <dime.h> in the top of each file that uses a function from the library.

If you link on the command line, link with '-ldime -lalleg'. It is important that you specify the libraries in that order. If you want the ability to debug inside dime's functions, or if you want the library to check for bad format strings (recommended for everything that is not a release version), then link with '-ldimed' instead of '-ldime'.

If you use RHIDE, go to the menu Options/Libraries and fill in dime. It is important that dime is above alleg. Don't forget to check the box to the left of the library. You may replace dime with dimed to include debugging information.

Before calling `dialogf()' or `vdialogf()' you must have initialized Allegro by calling `allegro_init()', `install_keyboard()', `install_mouse()', and `set_gfx_mode()'. Then you must call `dime_init()' to initialize Dime and after this, Dime's functions are ready to use.

Common Problems

It is easy to give invalid arguments to `dialogf()' by accident, and the error might not point out the source of the problem very well. Here is a checklist with the most common problems:

"All input fields in the dialog contain garbage by default."
You have probably forgotten to initialize some of the variables before passing their addresses to `dialogf()'. The values of the `...' parameters will be taken as default values in the input fields.
"Everything crashes when I call `dialogf()'."
This is most likely caused by you passing one of the `...' arguments from the wrong type. Check that all "%something" format specifiers match the correct type of parameter. Remember that you must pass _pointers_ to integers and floating point numbers, not just integers or floating point numbers. Strings should be `char *', not `char **' though. Also remember that "%datafile" requires two arguments. If your format string spans several rows of your source, make sure there isn't an extra comma in the end of one of those lines (that mistake is easy to do if you add an extra input field to an existing call).
"The first field contains garbage by default even though I have initialized it."
You have probably split the format string up on several rows and left an extra comma at the end of one of them.
"The program shuts down and gives a message about some format string being wrong."
Then your format string is wrong! The message should describe pretty well what your mistake is.
"The program crashes horribly when I write a mathematically undefined expression (such as sqrt(-1)) or a very large expression (such as exp(1000)) in the expresison evaluator."
This problem only occurs with Watcom. I know no easy way to fix it -- that's simply Watcom's horrible way of handling floating point errors. Checking for errors before they occur is so hard that it's almost out of the question (_any_ mathematical operation can go wrong, eg. addition of big enough valid numbers results in overflow).

Changes

From 1.1.1b to 1.2b:

Fixed a bug not restoring text background color in some cases.
Made the info format documentation install itself to common directories under djgpp.
Improved the example program.
Peter Wang contributed a Linux port.
Made the statically linked version of Dime link with Allegro statically. (Thanks to Mike Fahlbusch who pointed this out!)

From 1.1b to 1.1.1b:

Removed a bug that prevented the whole thing from building on other machines than mine.

From 1.0 to 1.1b:

No actual changes, really. But 1.0 should have been 1.0 beta, so I released 1.1b to make it a beta :-) . Also fixed some version errors in the documentation and in dime.h.

Wish List

These are features that I'd like to implement some day.

Write makefiles for Unix, BeOS and Borland C++. (I need help for this!)
Make all gui functions be function pointers so that the user can hook the dialog procs and give them different looks.
Datafiles should have an option for ability to select nothing.
The following format specifiers:
- %gridfloat, %cgridfloat,
  %griddouble, %cgriddouble,
  %gridint, %cgridint,
  %griduint, %cgriduint,
  %gridstring
  Lets the user edit a two dimensional grid of numbers/texts.
- %color
  A color. Next argument should be an `int *'.
- %color8
  A color in a palette. Next argument should be an `int *' (for the color), and the argument after that should be an `RGB *' for the palette, or `NULL' to use current palette.
- %slider[max]
  A slider control where the user can drag a handle to select an integer. Next argument should be an `int *' in which the result will be stored. `max' specifies the max value of the slider, inclusive. Min value is always 0, inclusive.
- %radiolist[title,list]
  Almost like %list, but will display as a set of radio buttons rather than as a list. Also, this doesn't take the `lines' modifier that %list takes.
Automatic scroll bars if the window gets too high. Currently the objects will just be invisible and unreachable which isn't exactly beautiful.
Inside the "[]" of a format modifier (and only there) it would be cool to support printf-like format strings, eg
```
      dialogf(..., "%int[%d,%d]", minval, maxval, &my_integer);
```
Currently, nested dialogs behave a bit weird when ok'ing a sub-dialog and then cancelling a parent dialog: the sub-dialog will continue being ok'ed. This is harder than it sounds to fix, but would be good to have anyway.
An option to take away the Cancel button.
Movable windows. (Use BGUI? Perhaps not, since that seems to still be too unstable, and it's not nice to have dependencies to other libraries.)
Find some way to make the file selector look 3d-ish. (Use BGUI?)
Make dialogf() etc actually use our enhanced edit boxes - just need a new d_dime_edit_proc().
Make the %wstrlist, %wlist, %wdatafile formats look like a combo box rather than being an own window.
Write a better suited calculator?
A completely new function that does the same as Allegro's `alert()', but with automatic line breaking and with a format string for the buttons would be useful to have. I'm not sure if it should go in this library or an own though.

Wish list entries from now on are merely dreams that are very unlikely to be implemented.

Some way to show help and/or tooltips.

Authors

Peter Wang (tjaden@alphalink.com.au).

Shawn Hargreaves (shawn@talula.demon.co.uk).

Sven Sandberg (ssven.geo@yahoo.com).

Thanks

Shawn Hargreaves (shawn@talula.demon.co.uk).

Charles Sandmann (sandmann@clio.rice.edu), DJ Delorie (dj@delorie.com), Eli Zaretskii (eliz@is.elta.co.il),

Contact Info

Email:

Homepage:

Telephone:

Real Life Address: