96ca3fe470
* Makefile
* config/*
* contrib/*
* doc/*
* extras/*
* include/*
* lib/*
* package/*
* src/*
* tests/*
* utils/*
* removed empty lines left after removed '$' + 'Id' + '$' identifiers
345 lines
14 KiB
Plaintext
345 lines
14 KiB
Plaintext
GT API functions
|
|
================
|
|
By Bil Simser (1999-05-14)
|
|
|
|
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 - MS-DOS implemenation
|
|
gtwin.c - Windows 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
|
|
|
|
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:
|
|
PROCEDURE 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 Windows 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:
|
|
PROCEDURE 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
|
|
PROCEDURE 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 --hb:gtwin
|
|
and:
|
|
t --hb: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 --hb: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 --hb: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 src/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.
|
|
|
|
|
|
gtnul - base GT driver from which each other inherits.
|
|
it gives screen buffer functionality but does not
|
|
produce any screen output from disp*() commands
|
|
Only OutStd()/OutErr() are supported.
|
|
It's present on all platforms and i always linked.
|
|
|
|
gtcgi - very simple GT driver which does not make any output
|
|
formatting and simply send it as to stdout.
|
|
Supported by all platforms.
|
|
|
|
gtstd - it uses stdout output but tries to support full screen output but
|
|
without collor support and cursor shape. It format text to number
|
|
of row and columns if is able to detect these values on given
|
|
platform.
|
|
Supported by all platforms.
|
|
|
|
gtpca - It's PCANSI terminal GT - it works in similar way to ANSI GT
|
|
driver in Clipper though keyboard input is not fully supported.
|
|
Now GTTRM can make all GTPCA job and much more.
|
|
Supported by all platforms.
|
|
|
|
gtdos - GT driver for MS-DOS - it uses BIOS and direct hardware screen output
|
|
so it's very similar to Clipper one - in practice due to the same
|
|
environment you will noticed that all small details of Clipper
|
|
GT drivers are replicated here. You can think about it like 100%
|
|
Clipper compatible.
|
|
Supported only by MS-DOS builds.
|
|
|
|
gtos2 - GT driver for OS/2 - It's sth like GTWIN but for other OS.
|
|
Supported only by OS/2 builds.
|
|
|
|
gtwin - GT driver for MS-Windows console window.
|
|
Supported only by Windows builds.
|
|
|
|
gtcrs - GT driver for platforms which supports curses or compatible
|
|
(ncurses) library - in practice POSIX systems.
|
|
Supported by POSIX systems (mostly different *nixes)
|
|
|
|
gtsln - GT driver for platforms which supports slang library.
|
|
It's like GTCRS but instead of CURSES it uses SLANG.
|
|
Supported by POSIX systems (mostly different *nixes).
|
|
It supports Unicode input/output if compiled with slang
|
|
version which also supports it.
|
|
|
|
gttrm - it's like GTCRS and GTSLN but it does not use any external
|
|
terminal library like SLANG or CURSES and it does not use
|
|
any external database to extract terminal capabilities so
|
|
it can be compiled on any POSIX system - I'll add support
|
|
also for MS-DOS/Windows in the future. It should automatically
|
|
detect UTF-8 terminal mode and switch internally to Unicode
|
|
mode if necessary. In theory is less functional then GTCRS
|
|
and GTSLN because I hard coded escape sequences only for few
|
|
terminals but because I added support also for some non
|
|
standard terminal extensions and I'm using very limited set
|
|
of output sequences then it usually works better then GTCRS
|
|
and GTSLN.
|
|
Supported by POSIX systems (mostly different *nixes)
|
|
|
|
gtwvt - GT driver for MS-Windows. It creates its own GUI window
|
|
instead of using MS-console window. It allows to change
|
|
font, window size, etc.
|
|
Supported only by Windows builds.
|
|
is a pure console implementation of traditional Clipper terminal
|
|
taking Windows API as its base console IO protocols. Its OI are
|
|
rendered in a Windows window and hence all of MSDN is available
|
|
for use with GTWVT.
|
|
To let the memory refreshed, I must remind
|
|
everybody that it is a superb work of Peter Rees contributed
|
|
to xHarbour on 2003-12-22.
|
|
gtwvg - GUI emulation of GTWVT. It implements itself on top of GTWVT.
|
|
GTWVG ( WVTGUI in xHarbour ) offers functions and classes to
|
|
present a console application look like a windows one.
|
|
It renderes GUI elements on top of Clipper elements
|
|
( GETS, BROWSERS, BOXES, LINES ) which makes them
|
|
feel like a Windows element. GTWVG can be used with existing
|
|
code just adding some more code but without sacrificing or
|
|
modifying old one.
|
|
Also all IO commands can be rendered on top of the GUI elements
|
|
gtxwc - GT driver for X-Window. It's like GTWVT but for nixes.
|
|
Additionaly it has set of predefined vector characters
|
|
(box and arrow drawing characters) which can be used
|
|
instead of the one defined in font. It means that you
|
|
will have all boxes and arrows you know from MS-DOS and CP437
|
|
even if you chose font which does not have them. Additionally
|
|
it support some simple graphic output. See tests/gfx.prg
|
|
for simple program which demonstrates it.
|
|
Supported by POSIX systems (mostly different *nixes)
|
|
|
|
gtalleg- GT driver which uses alegro library for input/output.
|
|
It's also GUI driver which support HB_GFX*() drawing.
|
|
Multi platform, works on all platforms for which allegro
|
|
library has been ported: MS-Win, MS-DOS, VESA, X11, FB, SDL, ...
|
|
|
|
gtgui - pseudo GT driver which adds to GTNUL Clipboard and Tone
|
|
functionality. If you are using some MS-Windows GUI library
|
|
and you still want to use Tone() function or HB_GTI_CLIPBOARD
|
|
actions then link this GT driver with your application.
|
|
If you do not want to use Tone() or HB_GTI_CLIPBOARD then
|
|
do not link it - it will be only waste of memory.
|
|
|
|
gtctw - GT driver which adds CT3 Window functionality to any other
|
|
GT driver from which it inherits. It's activated automatically
|
|
when you execute first W*() function.
|
|
In similar way in Harbour it's possible to add support for
|
|
GTWVW/GTWVG inheriting from GTWVT.
|
|
|
|
Some of the GT drivers support additional functionality with hb_gtInfo()
|
|
interface.
|
|
See include/hbgtinfo.ch for different actions.
|
|
|
|
Best regards,
|
|
Przemek
|