FreeDOS DFlat+ Application Programming Interface

1.- What is DFlat+ API?

DFlat+ Application Programming Interface is a set of functions in the C programming language to help programmers to write applications for DOS that use a friendly text-mode User Interface, from an object-oriented perspective, based in the concept of Window and Message, and that can be easily manipulated with the mouse.

DFlat+ is distributed both as source and binary, and is compatible to both Borland C/C++ compilers and OpenWatcom C/C++. The binary package cotains the (Large Model) precompiled libraries, and include files, for both languages, so that you can easily create your own DFlat+ applications without messing around compiling the libraries themselves.

DFlat+ is originated from Dr. Dobbs' DFLAT libraries, which in turn were evolved to be used within FreeDOS EDIT (Jose Cosentino, Eric Auer), and that have now been made independent of it (Aitor Santamaría), and can be used to create custom Text User Interface applications.

2.- Windows, messages... and Hello World!

Programming with DFlat+ is easy. The program entry must be changed to DfpMain() instead of Main(), and then it's all about creating and manipulating windows. A window is any object in the user interface which can pick messages from the user from the input devices (such as keyboard or mouse), from the windowing system (such as messages to CLOSE the windows), or from another window, via the SendMessage and PostMessage functions. Here is how a simple Hello World! would work in DFlat+ 1.0: it will simply create a message box with the hello world! notice: we simply create a special type of window, which is the Application, and upon its creation we show the message, then exit (by closing this Application window).

/*
        FreeDOS DFlat+ Hello World!
*/

/* I N C L U D E S /////////////////////////////////////////////////////// */

#include "dflatp.h"
#include "dfptools.h"

// This line is just used to compile the MODULE bit
#include "resource.h"

/* D E F I N E S ///////////////////////////////////////////////////////// */

/* G L O B A L S ///////////////////////////////////////////////////////// */

DEFPROGRAM
MOD_DESCRIPTION("FreeDOS Hello World! 1.0")
MOD_VERSION(1,0,0,0)
MOD_COPYRIGHT("   Aitor Santamar¡a")
MOD_LICENSE("GNU GPL 2.0")
MOD_ABOUT("Simple Hello World based on DFlat+")
END_DEFMODULE

/* P R O T O T Y P E S /////////////////////////////////////////////////// */

static int MainAppProc(WINDOW, MESSAGE, PARAM, PARAM);

/* F U N C T I O N S ///////////////////////////////////////////////////// */

int DfpMain(int argc, char *argv[])
{
    WINDOW wnd;

    wnd = CreateWindow(APPLICATION, "", 0, 0, -1, -1, NULL, NULL, MainAppProc, 0 );

    ProcessMessages();

    return 0;
}

static int MainAppProc(WINDOW wnd,MESSAGE msg,PARAM p1,PARAM p2)
{
    int rtn = DefaultWndProc(wnd, msg, p1, p2);

    if ( msg == CREATE_WINDOW )
    {
        MessageBox ("Message", "Hello world!");
        PostMessage (wnd, CLOSE_WINDOW, 0, 0);
    }

    return rtn;
}

Another interesting concept is the ability to easily create objets that contain a large amount of data, called Resources (for example, the program identification block above is one of such resources). Common types of resources that you can create for your applications are dialogs and menus. An example of a "search text" dialog could be:

/* -------------- the Search Text dialog box --------------- */
DIALOGBOX(SearchTextDB)
    DB_TITLE("Find",-1,-1,9,48)
    CONTROL(TEXT,    "~Find What:",           2, 1, 1, 11, ID_SEARCHFOR)
    CONTROL(EDITBOX, NULL,                   14, 1, 1, 29, ID_SEARCHFOR)
    CONTROL(TEXT, "Match ~Case:" ,           2, 3, 1, 23, ID_MATCHCASE)
    CONTROL(CHECKBOX, NULL,                 26, 3, 1, 3, ID_MATCHCASE)
    CONTROL(BUTTON, "   ~OK   ",              7, 5, 1, 8, ID_OK)
    CONTROL(BUTTON, " ~Cancel ",             19, 5, 1, 8, ID_CANCEL)
    CONTROL(BUTTON, " ~Help ",             31, 5, 1, 8, ID_HELP)
ENDDB

You can create your resources, which are compiled and can be used within your program (in the example above, with a DialogBox() function).

The library, as in version 1.0, comes in the form of a big library file, plus some other tools that you can link with, in the form of the tool libraries. The library file depends on the Compiler and the Memory Model that you'd like to link your program too. The binary package contains two such DFlat+ library files:

DFLATPLB.LIB	Borland (c) C/C++ ver 3.0	Large Memory model
DFLATPLO.LIB	Open Watcom C/C++ 1.6	Large Memory model

(as you can notice, the penultimate letter refers to the model, and the last one refers to the compiler).

The debugging help functions come with the tools libraries, and implement different debug methods (for example, no_debug, the classical DFlat debugging, or the new DFlat+ debugging). Every tool library implements ALL the tool functions, and only differ in the debug method they implement: thus, from the very same OBJ of your application, you can create a debug or non-debug EXE, by simply linking to one or other tool library.
The tool libraries relate to the methods as follow (for example, for the Borland C/C++ 3.0 compiler in the large memory model):

DTOOL0LB.LIB	DFlat+ Tools library - No debug
DTOOL1LB.LIB	DFlat+ Tools library - Legacy DFLAT debugging
DTOOL2LB.LIB	DFlat+ Tools library - New DFlat+ debugging

3.- DFlat+ Versioning scheme

Current version for the DFlat+ libraries is:

DFlat+ 1.0.0

Any release of the DFlat+ libraries comes in the form of:

DFlat+ X.Y.Z

Notice that X, Y, Z are POSITIVE INTEGERS (i.e., versions such as 1.0.13 are possible, and differ from 1.1.3).

The meaning of such versioning scheme is the following:

X	Major version number This number reflects changes that affect the vaste majority of the DFlat+ arquitecture, or a significant change in the appearance or the user interface. It will very seldomly vary.
Y	User-oriented changes This number reflects a variation or accumulation of STABLE changes that usually improve the user experience of the application. For example, if you have linked your application against version 1.3 of DFlat+, you are advised to link to 1.4.0 whenever this version appears, as version 1.4 will have a large number of improvements and stability with respect to 1.3.X that the users of your application will notice and mostly appreciate.
Z	Developer-oriented changes A change in the Z number will probably mean one of the following situations: - A small post-release that provides an X.Y version with small fixes and cosmetic changes (as could be the case of 1.3.0 to 1.3.1). - A step towards the next X.Y version, with some changes that are recent, and hence unstable (as could be the case of 1.3.6 to 1.3.7). As developer, you are encouraged to link against a new Z version in the first case, but optionally for the second case: you may want to create yourself unstable pre-release versions of your own applications that are linked against such second-case Z versions, but you are advised to to release those for end-users, at the risk of unstability.

4.- License, Contributing, and contribution directives

The libraries are double-licensed. You can choose the license that best fits your purposes. Any use of the libraries beyond such licenses is illegal, and may be liable of legal actions.

GNU-GPL 2.0.
GNU-LGPL plus the following extra condition: BOTH the user interface of your program (e.g. the About... box, if you have such thing) AND the user documentation accompaining the application must clearly state, when describing the program architecture or general description, that it is making use of "FreeDOS DFlat+ API, by the FreeDOS Team (http://www.freedos.org/)".

As for any Open-Source program, you are allowed to copy, distribute or modify the libraries, according to the terms of such licenses. The license under which your program is distributed is up to you, but notice that if you choose the first license, then your program must be GNU-GPL 2.0 or weaker license.

You may also want to commit your changes to the FreeDOS DFlat+ Team. Note however that, for reasons of maintainability and clearance, the code should be in good condition, well commented, and fulfill with the following conditions. Note that current DFlat+ code (as inherited from DFlat) does not fulfill with some of such conditions, but it is planned to be changed to meet these requirements:

Maintain compatibility with OpenWatcom C/C++ compiler, presently the best option for an Open Source alive 16/32-bit C/C++ compiler for DOS.
Avoid the ussage of global variables: try to use only local variables, and those who are in the contest of the window you are using.
Use the hungarian notation for variables. For example, replace char *Name with char *lpszName.
Avoid making the application programs dependent on the local DFlat+ structures, which make it more difficult to maintain. For example, in what refers to the structure of the Window: any field should be protected by macros or functions, that could be easily replaced or rewritten, should that field be modified, or would disappear.