
                      dlg - a DIALOG editor for Allegro
                    -------------------------------------
                    v0.43, by Julien Cugniere, 2003/04/10



This software is completely free. You can do whatever you want with it and
its source. There is however no warranty, so I can't be held responsible for
any problem that its use might cause (like messing up your source files while
saving... =).



-------------
 What is it?
-------------

    Well, this is a graphical editor for the Allegro GUI dialogs. Unlike
    other editors, I tried to make it as WYSIWYG as I could. It can (should)
    load and save any of your C/C++ source files. You can (quite) easily add
    support for your own dialog procs, using a plugin system similar to that
    of the grabber (see plugins.txt).

    The idea behind this editor is to work directly with source code, but to
    make it transparent to the user. It means that all the fields of all the
    DIALOG structures defining your dialog are handled as text by the editor.
    That way you can type whatever you like, and even if the editor doesn't
    understand it, it will be saved untouched. This also means that you can
    load any of your existing dialogs and save them, and they won't have
    changed (except for the formating).

    I'd like to hear from you. Please send any bug reports, suggestions,
    comments, questions, etc. to <uos@free.fr>.



-----------
 Compiling
-----------

    This version require allegro 4.0 or later. To compile the editor, the
    procedure is similar to allegro: you have to run the script fix.bat (for
    DOS/Windows) or fix.sh (for other OS) with the desired platform. If you
    run fix alone, you'll get a list of the platforms available. Then you
    just run make. Example:

        fix mingw32
        make

    By default, the editor is built with three plugins: allegro, dlg_gui and
    tetris. You can get a list of all the plugins with "make info". Then you
    plug/unplug them with commands such as:

        make plug=tetris
        make unplug=allegro
        make plug=tetris,allegro unplug=dlg_gui

    Right now, this has been tested under MingW32, djgpp, MSVC, and Linux.
    I've provided makefiles for other platforms, but they are either untested
    or incomplete. If you want to submit correct version of these, feel free
    to do it =). If you've got problems compiling the editor, don't hesitate
    to send me a mail...



------------------
 Using the editor
------------------

LOADING:
    You just select a source file, and the editor will show a list of all the
    dialog that were found in the file, so you can choose which one to edit.
    If the dialog you're loading is bigger than the current resolution, you
    will get a dialog allowing you to change the graphic mode.

SAVING:
    The "save as" command let you choose a file, then ask you to enter a name
    for the dialog. If you choose the name of a dialog already existing in
    the file, that particular dialog of the file will be replaced. If you
    enter a new name, it will be saved at the top of the file, and you'll
    have to move it yourself to a suitable place. The "save" command saves in
    the file the current dialog was loaded from, with the same name, thus
    replacing the old one. If the dialog was started from scratch, "save"
    acts like "save as".

    There is an option to output "c++ friendly" code to the file. This is
    automatically selected when the file type is known (cpp, cxx, hpp vs. c),
    but when the editor doesn't know (*.h or unknown extension) the editor
    uses the default provided in the "misc->preference" dialog. If you want
    to be sure of the editor's choice, just use "save as" instead of "save".
    Right now, cpp mode only involves adding a cast to void* in front of
    string literals.

    Note: saving always makes a backup, that is erased only at the end of the
    saving process, if you didn't ask for it. So if the program crashes
    during the save, you still have your old file, renamed with a ".bak"
    extension.

EDITING:
    You can create new objects (buttons, edits, lists...) with the "new"
    menu, accessible from the top menubar, or from the second and third mouse
    buttons. You select an object, then drag over the workspace to create it.
    If you have installed multiple proc sets, you can switch between them
    with the "sets" menu. A right click always gives you access to all of the
    installed procs.

    You can move an object by clicking and dragging it, and you can resize it
    by dragging its edges. Pressing ALT after you've begun moving or resizing
    will prevent grid snaping. Double clicking on an object shows its
    properties. There you can manually enter any of the fields of the DIALOG
    struct corresponding to the object. Note that even if the editor doesn't
    understand what you type, it will leave it untouched, and will save it as
    you entered it. You can use the menu "Misc->View Source" to see what the
    code of the dialog looks like (that's how it will be saved).

    DEL deletes the selected objects. PageUp, PageDown, Home and End change
    the indexes of the selected objects in the DIALOG array. For example, if
    you create a shadow_box after a button, the button will be hidden by the
    box. But you can select the box, and press PageUp or Home to put the box
    at the top of the array. This way, the box is drawn before the button.

SELECTING OBJECTS:
    If you click and drag the mouse on an object, you will move it. If you
    click and drag on the background, you will do a rectangle to select
    objects. If all the screen is filled so you can't drag a selection
    rectangle without moving some object, use the ALT key: it will let you
    drag a selection rectangle even over objects. Whatever way you choose to
    select objects, CONTROL adds objects to the current selection, while
    SHIFT removes them.

LIST EDIT:
    The menu item "Selection->List Edit" will give you a list of all the
    objects of the dialog. There, you can select objects with CONTROL, or
    SHIFT. Selecting objects there selects them on the workspace. You can
    also use the buttons to performs actions on the selected objects. A
    double click on an object will open its properties.

GRID SNAPING:
    If you select a grid, objects will be snaped to it when resizing or
    moving them. When moving a multiple selection, it's the object that you
    clicked on that will be snaped to the grid. Others will keep their
    position relative to it. You can ignore the grid by holding ALT, or you
    can select "no grid". You can hide the grid, (it won't be drawn, but it
    won't be disabled either). Any of the three available grids can be
    resized, and the settings are kept in the configuration file "dlg.cfg".

THE EDITOR'S FONT:
    The program uses the font in "font.dat" for the editor's GUI (the edited
    dialog uses Allegro's default font). If you don't like it you can change
    it, or just delete the file: the editor will then fall back to the
    default Allegro font. You can also go to "misc->preference" and ask the
    editor to use the default font.

MISC. COMMANDS:
    "Selection->Set colors" allows you to set the fg and bg color of the
    selected objects.

    "Grid->Snap now!" will resize and move all the selected objects so that
    their edges are aligned on the grid.

    "Misc.->Load palette" can be used to load a palette from an image (BMP,
    PCX, TGA, LBM).

    "Misc.->Graphic mode" lets you change the graphic mode (can also be done
    using command line parameters).

    "Misc.->Gui setting" opens a dialog box where you can edit some of the
    GUI variables, like gui_fg_color, gui_baseline etc. These apply to the
    edited dialog, not the editor itself.

    "Misc.->Preferences" lets you select a few settings for the editor. They
    are saved in the configuration file.

    The "Hooks" menu will contain menu entries added by plugins (if any).



-------------------------
 Command Line Parameters
-------------------------

    Usage: dlg [options] [FILE [DIALOG]]
	 
    Use "dlg -h" to get the list of possible options. FILE is a source file
    to load from. If you don't specify DIALOG, the editor will scan the file
    and let you choose from a list. If you specify it, the dialog with this
    name will be loaded. Examples:

        dlg
        dlg c:/allegro/tools/grabber.c
        dlg src/dedit.c save_dlg


------------------------
 The Configuration File
------------------------

    The editor starts with the settings found in the configuration file named
    "dlg.cfg". You can edit this file manually. Your regular "allegro.cfg" is
    still used for any allegro related settings. Note that command line
    parameters will supersede the configuration file. Also, plugins can add
    sections to it if they need to store any custom information.
