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 implementation 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 successfully! 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 achieve 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 else's 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_ 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_ 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__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 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 color 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 PC-ANSI 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 similar to GTWIN but for another 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 renders 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. Additionally 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 Allegro 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-Windows, 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