harbour-core/harbour/doc/gtapi.txt

/*
 * $Id$
 */

GT API functions
================
By Bil Simser (Fri, 14 May 1999)

Using the gt API requires two steps.
The gt API interface is kept in gtapi.c. This houses the gt API and
does not have any platform or compiler specific information. This file
should (read:will) never change except to add new _gt functions. This
file will be used by Harbour or Harbour functions and must be linked
into the RTL.

The second step requires you to link in your platform specific
implementation of the _gt functions. These are functions named with
gtxxxxxx convention and are called by the _gt functions in gtapi.c.
I've provided the following files to implement the console functions:

gtdos.c - DOS implemenation
gtwin.c - Windows 95/NT implementation
gtos2.c - OS/2 implementation
gtxxx.c - Generic template for implementation

If you wish to port the gt functions to another platform, just take the
gtxxx.c and populate it with calls to your OSes functions. Call the file
something appropriate (gtmac.c, gtnext.c or whatever) and add it to
that platforms makefile.

The API supports a dozen or so compilers on three platforms. You only
have to change the gtxxx.c files to implement your platform.

The API needs to be initialized for Windows to setup the Input and Output
handles. These are done in _gtInit() and should always be called. Not sure
how this will be implemented (if at all) into Harbour but it needs to happen
or else you won't see any output under Windows.

There's a test section at the end of gtapi.c. I didn't want to keep
rebuilding

Harbour to build a PRG test and PRGs shouldn't call the _gt functions
directly anyway. Just compile gtapi.c alone with a #define of TEST to see
the output (or build a PRG test if you want).

You must include gtapi.c and one of the platform implementation files
to compile sucessfully!

There are exceptions for various compilers in the platform implementation
files so if you're using a compiler that doesn't support certain routines
or syntax just stick in your changes and surround it with an
#if defined(__XXX__) call.

This is a complete set of gt functions as defined by Clipper. That is
there are no new _gt functions added. But this is not a complete
implementation. I do not know what _gtBegin or _gtEnd will do for
instance. Yes, they buffer the display but what does that really mean
under the covers? Perhaps someone needs to implement a screen buffer
to write to in order to achive this but the issue that immediately comes
to mind is how to initialize the size of this buffer?

The files are attached but I will NOT be checking them into cvs for the
following reasons:

1. There is already a gtapi.c file and under no circumstances will I ever
overwrite someones code. If the author wants to remove his file and check
this in then be my guest.

2. This is my vision of how "I" think the gt API should be implemented.
Perhaps it isn't Antonio's or anyone elses so review it and if you feel
that it deserves being put into Harbour I'll leave that up to you.

TODO:
The following functions are not implemented in gtapi.c:
_gtPostExt
_gtPreExt
_gtScroll
_gtSetBlink
_gtSetMode

The following functions don't work in gtapi.c:
_gtSave
_gtRestore

You get garbage on the screen in DOS mode. Two Harbour functions are
included in the gtapi.c file, ROW() and COL() to get started.

You also may notice that I didn't include any NanFor document headers or
even any cvs macros. The jury is still out on that so I'll leave that to the
reader.

I release this to anyone who wants it. If you feel you don't like the
implementation and want to pursue a different approach, please do.
By not checking this in I'm not forcing anyone to use it.
If however you do feel it's a good start
(or a better start than what we have)
the please check it in and start writing those other terminal functions
(DEVPOS, etc.)

Best regards,
Bil.


How to get rid of unwanted console in Windows GUI applications
==============================================================
By Przemyslaw Czerpak (druzus/at/priv.onet.pl)

Do not use GTWIN :-)
GTWIN is a driver for users who wants to write CUI applications and
should give them all possible features. GUI libraries do not have to
use GT drivers if they don't need any GT functionality, or if they
don't want to give users support for standard Clipper/Harbour functions
which operate on GT resources.

Harbour application can work without any GT driver. In such case all
functions which operates on GT resources are redirected to meta GT
driver (GTNUL) which is part of RTL library. This driver makes all
operations on memory buffer and only OUTSTD()/OUTERR() output is sent
outside. All GT drivers inherits from GTNUL or from other GTs but in
the inheritance chain the first GT driver is always GTNUL.

Because there is no hard coded bindings between core code and other GT
drivers, then by default only GTNUL will be linked. So if you will want
to use some real GT you will have to add to your code:

    REQUEST HB_GT_<name>

Setting the default GT driver is done exactly the same as setting the
default RDD. In RDD it request DBFNTX by default. It is done inside a
module with RDDSYS() symbol, and core code contains:

    REQUEST RDDSYS

Something like that is also done by Clipper. If you add to your code
RDDSYS symbol, then the default RDD will not be linked because your
RDDSYS will overload the default one (of course if it will be linked
before the one in core code). So it's enough to write something like:

    ANNOUNCE RDDSYS
or:
    PROC RDDSYS; RETURN

Both gives the same effect, and default RDD (DBFNTX) will not be linked.
Exactly the same I've done in GT subsystem. HB_GTSYS() makes exactly
the same job as RDDSYS() but for GT. This symbol is requested by core
code and in the module where it is defined it request default build GT
driver or if it's not set then default GT driver for given platform.
For Win32 it looks like:

    ANNOUNCE HB_GTSYS
    REQUEST HB_GT_WIN

This causes that normal console applications do not have to explicitly
request GT driver and the one set in the module with HB_GTSYS is always
linked. If you do not want to link the GT driver then you have to make
the same as for RDD and add to your code:

    ANNOUNCE HB_GTSYS
or:
    PROC HB_GTSYS; RETURN

In such case your final application will not have any GT driver. If you
want to use GTNUL as base, you should add:

    REQUEST HB_GT_NUL

Though IMHO this request should be part of GUI library core code. You
can link with your application more then one GT driver. It's enough
that you add more lines with:

    REQUEST HB_GT_<name>

For example, compile this code:

    /*** t.prg ***/
    REQUEST HB_GT_WIN
    REQUEST HB_GT_WVT
    PROC MAIN()
       ? HB_GTVERSION(), HB_GTVERSION(1)
       TONE( 200, 3 )
       TONE( 300, 3 )
       TONE( 500, 3 )
       INKEY( 0 )
    RETURN

and link it as Windows GUI application. Then simply execute:

    t //GTWIN
and:
    t //GTWVT

Most of Windows linkers execute startup initialization code in the
order of linked modules, so the first linked GT driver will be the
default one. But you can control it also from your application, by
requesting HB_GT_<name>_DEFAULT symbol (I do not like this name because
it cannot be used with 10 character symbols so I'm ready for any other
positions). For example, if you add to your code:

   REQUEST HB_GT_NUL_DEFAULT

Then GTNUL will be the default GT driver, and even if you would not
disable GTWIN and link it with your application, GTWIN will not be
activated but GTNUL.

It could be intentional, because if your application is linked with more
GTs, then you can also set the default one when you start your
application using //GT<name> switch, or HB_GT environment variable. So
you can create GUI application which will set the default GT driver to
NUL and will not activate GTWIN, and when you'll want to enable debug
messages, you simply run:

    myprog //GTWIN

and debug messages will use the GTWIN console window. You can think of
other situations when it could be useful to have full functional GT
driver in GUI application. You can even create mixed GUI/CUI code in one
program.

And finally, the TONE() function problem.
Low level TONE code is part of GT driver. In the past, GUI libraries in
Windows were linked the whole GTWIN driver and only TONE were used. It
was possible because someone blocked GTWIN to work with application
linked as Windows GUI programs. Now, GTWIN can be used with any
applications, and I do not want reduce its functionality. So GUI
libraries which needs TONE should have their own GT driver which will
support it. Now, such GT driver can also give much more features for
final users, because it allow to integrate GUI library with standard
Clipper screen functions.

How to create such base GUI GT driver?
See as example GTGUI in source/rtl/gtgui/gtgui.c
It supports only TONE and CLIPBOARD operations.
GUI libraries can use it or create other GT driver inheriting from
this one.
NOTE: source/rtl/gtgui/gtdef.c is a hack which overloads the default
      Harbour build time GT driver and should not be replicated.

Best regards,
Przemek