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

                               Dialogs Made Easy
                                 version 1.2.1

                                  Readme File

                          http://dime.sourceforge.net/

                               by Sven Sandberg

Introduction
Licence
Requirements
Installation
Usage
Common Problems
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/). You need at least version 3.9.35 (3.12 won't do, it's very old!). 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", "fixwat.bat", "fixunix.sh", "fixming.bat" or "fixmsvc.bat" for djgpp, Watcom, Linux, 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.35, 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:

"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. - 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. Also, the crash may not be a crash but rather an assertion that failed in one of Dime's routines. If this is true, then an allegro.log file has been created which describes the error. It usually means that there is something wrong with your format string.
"All input fields in the dialog contain garbage by default."
- You may have 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. - 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.
"The program shuts down and says that an assertion has been raised."
Then your format string is wrong. An allegro.log file should have been created, in which you find an error message that describes 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 expression evaluator."
This problem only occurs with Watcom. I don't know any easy way to fix it: that's simply Watcom's horrible way of handling floating point exceptions. 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). The best solution is that you switch to djgpp: it's a much better compiler anyway.

Contact Info

Email:

Homepage:

Telephone:

Real Life Address: