/* * General Descriptions of GTWVW * Copyright 2004 Budyanto Dj. */ Contents - Introduction - Acknowledgements - Version Info - General - Input - Output = Standard Mode = MainCoord Mode - GTWVW and GTWVT = Compiling GTWVT program in GTWVW = Compiling GTWVW program in GTWVT Differences: = Paint Refresh Interval = Vertical/Horizontal Caret = Line Spacing = Status Bar = Timer = Tool Bar = Scroll Bar = Push Button = Progress Bar - List (and Description) of GTWVW Functions - Future of GTWVW - Epilogue ============ INTRODUCTION ============ GTWVW is GT driver for Win32 using GUI windows instead of Console, with multiple windows support. Copyright 2004 Budyanto Dj. GTWVW was initially created based on: GTWVT =Id: gtwvt.c,v 1.60 2004/01/26 08:14:07 vouchcac Exp = Video subsystem for Win32 using GUI windows instead of Console Copyright 2003 Peter Rees Rees Software & Systems Ltd based on Bcc ConIO Video subsystem by Copyright 2002 Marek Paliwoda Copyright 2002 Przemyslaw Czerpak Video subsystem for Win32 compilers Copyright 1999-2000 Paul Tucker Copyright 2002 Przemyslaw Czerpak The following parts are Copyright of the individual authors. www - https://harbour.github.io Copyright 1999 David G. Holm hb_gt_Tone() See COPYING.txt for licensing terms. www - https://harbour.github.io This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option ) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this software; see the file COPYING.txt. If not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA (or visit the web site https://www.gnu.org/ ). As a special exception, the Harbour Project gives permission for additional uses of the text contained in its release of Harbour. The exception is that, if you link the Harbour libraries with other files to produce an executable, this does not by itself cause the resulting executable to be covered by the GNU General Public License. Your use of that executable is in no way restricted on account of linking the Harbour library code into it. This exception does not however invalidate any other reasons why the executable file might be covered by the GNU General Public License. This exception applies only to the code released by the Harbour Project under the name Harbour. If you copy code from other Harbour Project or Free Software Foundation releases into a copy of Harbour, as the General Public License permits, the exception does not apply to the code that you add in this way. To avoid misleading anyone as to the status of such modified files, you must delete this exception notice from them. If you write modifications of your own for Harbour, it is your choice whether to permit this exception to apply to your modifications. If you do not wish that, delete this exception notice. /* * Individual authors: * (C) 2003-2004 Giancarlo Niccolai * Standard xplatform GT Info system, * Graphical object system and event system. * hb_gtInfo() And GTO_* implementation. * * (C) 2004 Mauricio Abre //20040908 * Cross-GT, multiplatform Graphics API * */ ================ ACKNOWLEDGEMENTS ================ GTWVW does not exist without the followings: - Peter Rees, the original author of GTWVT - Pritpal Bedi, with his WVTGUI extensions - All other GTWVT contributors - All (x)Harbour developers, who made it all possible!!! Thanks to all of you! Also thanks to those who gave me feedbacks during the initial stage of GTWVW. And to those who has been persistenly asking me to continue developing it :-). ============ VERSION INFO ============ This document is written when GTWVW version info is as follows. Latest Update: 2004-10-25 Latest Sync with: xHarbour of: (Beta1-2) =Id: ChangeLog,v 1.3493 2004/10/06 02:06:09 ronpinkas Exp = gtwvt of: =Id: hbgtwvt.h,v 1.31 2004/09/28 03:25:07 vouchcac Exp = =Id: gtwvt.c,v 1.133 2004/09/28 03:25:17 vouchcac Exp = =Id: wvtutils.c,v 1.18 2004/09/28 03:25:18 vouchcac Exp = (wvtcore.c is not changed since last sync: =Id: wvtcore.c,v 1.10 2004/08/30 14:10:20 vouchcac Exp = ) ======= GENERAL ======= GTWVW is a General Terminal (GT) driver for xHarbour PLUS some runtime library allowing programmer to have text and GUI elements mixed, in a multi-windowed application. GTWVW is exclusively designed for Win32 platform. Using GTWVW programmer can use all standard GT functions, normally indirectly called through standard xHarbour I/O functions/commands as: - ?, ?? (QOut(), QQOut()) - @ ... SAY ... (DevPos(), DevOut()) - Scroll() - SetPos() - _GET_() - ReadModal() - Inkey() - AChoice() - Alert() - etc. All those commands/functions behave the same way as in other GTs. Unlike other GTs, however, GTWVW supports multi-windows. GTWVW has been tested using BCC32 only. To use GTWVW, build GTWVW.LIB using hbmk2, then link it to your application as your GT. (Currently GTWVW cannot coexist with GTWVT in a MULTIGT environment.) Some special characteristics of GTWVW: - Allow programmer to do some window operations (open, close, ...) and direct OUTPUT to any window. - As with GTWVT, programmer can mix text and pseudo GUI elements. - Additionally, GTWVW also has some native Windows controls as statusbar, toolbars, scrollbars and pushbuttons. Some basic conventions: - Windows are numbered 0..n, with 0 being the Main Window, and n being the topmost window. - Main Window is automatically opened during program init. - All windows are automatically closed during program exit. - Parent of to be opened Window n is Current Window (typically Window n-1). ===== INPUT ===== - Mouse and keyboard input accepted only when topmost window is on focus. (That is, currently GTWVW windows are modals.) - Inputs are therefore stored in topmost window's buffer. - Inputs on non topmost window can now be handled via WVW_INPUTFOCUS function (menu, toolbar, scrollbar, pushbutton, and other keyboard/ mouse events). ====== OUTPUT ====== There are two modes of coordinate addressing that user may select/change DURING RUN TIME: - Standard Mode (default) : coordinates (row,col) are relative to current window - MainCoord Mode : coordinates (row,col) are relative to Main window by using HB_FUNC( WVW_SETMAINCOORD ) --------------------------------------------------------------------------- In Standard Mode: (coordinates are relative to current window) --------------------------------------------------------------------------- - CurrentWindow is automatically reset to topmost window during program start and after wvw_nOpenWindow() and after wvw_lCloseWindow(). - All input/output oriented GT_FUNC() work on CurrentWindow. Notice that this way MaxRow() and MaxCol() will return CurrentWindow's. - Programmer can change CurrentWindow by using HB_FUNC( WVW_NSETCURWINDOW ). Example: nCurWin := wvw_nSetCurWindow(1) ? "In Window 1" wvw_nSetCurWindow(nCurWin) ? "Back in Window " + AllTrim(Str(nCurWin)) - All exported, output oriented C functions work on window designated by usWinNum parameter. - All HB_FUNC( gui_function ) work on window designated by usWinNum parameter. --------------------------------------------------------------------------- In MainCoord Mode: (coordinates are relative to MAIN window, similar to screen-wide coordinates in Clipper) --------------------------------------------------------------------------- - CurrentWindow is automatically reset to MAIN window during program start and after wvw_nOpenWindow() and after wvw_lCloseWindow(). - All output oriented GT_FUNC() work on CurrentWindow, which is internally switched depending of requested row,col position. After each operation, CurrentWindow is reset back to MAIN window. Notice that this way MaxRow() and MaxCol() will always return MAIN window's, as they do in Clipper. To support this feature, each window keeps records of Row and Col Offset to the Main Window, specified during Window opening. Example: Assume this window states: +------... |Main Window (Window 0) |MaxRow()=24 MaxCol()=79 | +---------------... | |Window1 RowOfs=3 ColOfs=4 | |MaxRow()=9 MaxCol()=29 | | +---------------------------... | | |Window2 RowOfs=6 ColOfs=15 | | |MaxRow()=3 MaxCol()=49 | | | @ 6,15 say "text1" will be written to Window2 starting at 0,0 @ 3,15 say "text2" will be written to Window1 starting at 0,11 @ 3, 2 say "text3" will be written to Main Window starting at 3,2 @ 4, 2 say "" //Main Window ?? "t" //Main Window ?? "e" //Window 1 ?? "x" //Window 1 ?? "t" //Window 1 ?? "4" //Window 1 Note that the whole "text3" will be written to Main Window, but "ext4" will be written to Window 1. Note also that all window corners must be within MAIN window's scope. - User can change CurrentWindow by using HB_FUNC( WVW_NSETCURWINDOW ), BUT it is NOT recommended because it is ridiculous and probably dangerous! (If you need to write to a specific window when you are in MainCoord Mode, it is recommended that you turn off MainCoord Mode, select CurrentWindow, do the operation, and turn MainCoord Mode back on when it's done.) - MainCoord Mode is NOT supported by exported C functions. (User must specify which usWinNum to write, using coordinates within that window.) - HB_FUNC( gui_function ) supports MainCoord Mode limited only in translating passed screen-wide row,col coordinates into ones of the selected usWinNum. Notes: MainCoord Mode is meant to be the quickest way of porting an existing Clipper application to xHarbour + GTWVW. =============== GTWVW and GTWVT =============== -------------------------------- Compiling GTWVT program in GTWVW -------------------------------- GTWVW uses the same framework as its parent, GTWVT, and is maintained to be as similar as possible in structure. Although it is not a correct perpective a GTWVT application can be thought of as a GTWVW application with one window (ie. the Main window). With this perspective, one may expect to compile and link his GTWVT program using GTWVW. And yes, to some extent that is possible. One of the simplest way is to include a function translator (wvt2wvw.ch) that will translate GTWVT functions into GTWVW ones, assuming Current Window is used in all WVW_* functions. (Details of translation is described in wvt2wvw.ch). Notes: If one uses wvtclass functions, he must recompile/link wvtclass.prg and wvtpaint.prg, after adding '#include "wvt2wvw.ch"', using GTWVW. Notes: There is no guarantee that GTWVW will always be compatible with GTWVT. -------------------------------- Compiling GTWVW program in GTWVT -------------------------------- I can't imagine that one will ever need to run his program in GTWVW and GTWVT back and forth. Converting GTWVT program to GTWVW is fairly simple, but not the other way around. Well, except if the program never calls GTWVW specific functions. But then in that case why bother linking it with GTWVW anyway? ----------- Differences ----------- There are some differences between GTWVW and GTWVT, besides the fact that GTWVW allows multi-window operation, as described below. -------------------- Paint Refresh Method -------------------- When GTWVW receives WM_PAINT message, GTWVW doesn't always call WVW_PAINT() function immediately. The behaviour is controlled by nPaintRefresh interval (settable by wvw_SetPaintRefresh()). If nPaintRefresh==0 then (like GTWVT) GTWVW will call WVW_PAINT() on every receipt of WM_PAINT message from Windows. (Except if previous call has not returned.) If nPaintRefresh>0 (currently validated to be >= 50) then WVW_PAINT() will be called at nPaintRefresh millisecond interval, only if there was a pending WM_PAINT request. This approach may be desireable if programmer has a simple WVW_PAINT() function that repaint many GUI elements everytime it is called. In any case, WVW_PAINT() can consult wvw_GetPaintRect() to check the pixel regions needing actual repainting. Default nPaintRefresh is 100. ------------------------- Vertical/Horizontal Caret ------------------------- There are two styles of caret: horizontal (classic, console style) and vertical (commonly used in GUI applications). Programmer can select which style to choose, using wvw_SetVertCaret() function. Currently the chosen style will be applied to all windows. (In current implementation of GTWVW caret can only be displayed on topmost window, the only one allowed to accept input). Default caret style is horizontal. ------------ Line Spacing ------------ Programmer may choose to have spacing between lines. This may be desirable, among other reasons, because GUI elements may overwrite the line above or the line below the GUI objects. Each window may have its own line spacing, settable via wvw_SetLineSpacing() function. Next open window will use default line spacing of nDefLineSpacing settable via wvw_SetDefLineSpacing() function. nDefLineSpacing is initially 0. ---------- Status Bar ---------- GTWVW uses native Windows Status Bar Control. This Status Bar will be placed below the MaxRow() line. In GTWVT, on the other hand, Status Bar is drawn at MaxRow() line. Status Bar is automatically resized whenever its parent window is resized, and automatically destroyed when its parent window is closed. Status Bar functions are named WVW_SB*(). ----- Timer ----- Programmer may set a timer process using wvw_SetTimer(), and end it using wvw_KillTimer(). This is meant for a quick, simple timer process like displaying clock on the status bar. GTWVT has similar feature, but currently it is not activated. -------- Tool Bar -------- GTWVW uses native Windows Tool Bar Control. This Tool Bar will be placed above the 0 line. In GTWVT, on the other hand, Tool Bar is drawn anywhere between 0 - MaxRow() line, drawn using GUI primitive functions. Programmer may use system bitmaps in Tool Bar, or use his own bitmap. Tool Bar is automatically resized following its parent window, and destroyed when its parent window is closed. Tool Bar functions are named WVW_TB*(). ---------- Scroll Bar ---------- GTWVW uses native Windows Scroll Bar Control. This Scroll Bar will be placed inside text area, floating above the texts. In GTWVT, on the other hand, Scroll Bar is drawn using GUI primitive functions. A window can have several scroll bars at the same time, vertically or horizontally. Scroll Bar is positioned using character coordinates, automatically resized when its parent window changes dimension. Scroll Bar is also automatically destroyed when its parent window is closed. Scroll Bar functions are named WVW_XB*(). ----------- Push Button ----------- GTWVW uses native Windows Push Button Control. This Push Button will be placed inside text area, floating above the texts. In GTWVT, on the other hand, Push Button is drawn using GUI primitive functions. A window can have several push button at the same time. Programmer creates it by defining where it will be placed, and what's the codeblock to execute when the pushbutton is clicked. That's it. Push button is positioned using character coordinates, automatically resized when its parent window changes dimension. Push button is also automatically destroyed when its parent window is closed. Push button functions are named WVW_PB*(). ------------ Progress Bar ------------ GTWVW uses native Windows Progress Bar Control. This Progress Bar will be placed inside text area, floating above the texts. In GTWVT, on the other hand, Progress Bar is drawn using GUI primitive functions. A window can have several progress bar at the same time, vertically or horizontally. Progress bar is positioned using character coordinates, automatically resized when its parent window changes dimension. Progress bar is also automatically destroyed when its parent window is closed. Progress bar functions are named WVW_PG*(). ------------- Miscellaneous ------------- There are also some lower level differences between GTWVW and GTWVT. For example, when executing SetMode() GTWVW will validate that the window size must not exceed system's client (desktop) area. That's why some overly sized window, as in "Dialog 1" of WVT*Class demo, will work in GTWVT but not in GTWVW. ========================================== XHARBOUR CALLABLE FUNCTIONS (HB_FUNC(...)) ========================================== Please read funclist.txt. =============== FUTURE OF GTWVW =============== Current GTWVW is not put into xHarbour core as another standard GT, because it is not ideal according to xHarbour standards of GT. Ideally GTWVW should be split into two parts: - GTWVW the GT, following xHarbour standards of GT API. - WVW auxiliary library, which provides non standard interaction with the GT. The framework of supporting multi GT has been designed by Giancarlo Niccolai et al, ie. using GTINFO messages. (See xharbour/doc/gtinfo.txt). The multi-window aspects of GTWVW may be easily fit into this scheme, by introducing new message types, for example: - GTI_ISMULTIWINDOW to query if the GT supports multi-windowing - GTI_NUMWINDOWS to query number of windows opened - GTI_CURWINDOW to query/set current window (the target of GT output commands) - GTI_FOCUSEDWINDOW to query/set focused window - etc. However, IMHO this kind of decision requires serious, careful collective thoughts, involving cross-platform gurus of xHarbour, not by bursting ideas like I did in above paragraph :-). Additionally, some aspects of current GTWVW may not be accepted as a 'good practice' by other developers. For example, I am using Windows native controls (toolbar, statusbar, scrollbar) which are intentionally avoided by GTWVT. At best, it is because I can't give a convincing arguments. At worst, it is really a bad design of mine...:-) Well, frankly speaking my design decisions are driven by my actual need to port my (big) application to xHarbour GUI, in Win32 environment. I am now parallelly developing GTWVW and porting this application at the same time. Unfortunately..., both these jobs are not my main jobs... That explains why GTWVW evolves so slowly, and why I prefer pragmatic approach as in applying more 'good looking' and 'simpler to handle' GUI elements like the native Windows controls. In the future perhaps I even deliberately add more controls like dropdown listbox, etc. as I see necessary in my application to port (and if I have time to do that :-)). Today I have a chance of uploading GTWVW into xHarbour contrib area. Hopefully this will make it easier for anybody interested in it. Some other aspects of improvements (like compileability in compilers other than BCC) are also expected. Lorenzo Fiorini and others are helping me with it at the moment. ======== EPILOGUE ======== - This document may contain errors, because nobody is perfect :-) - All specifications herein may change due to further development of GTWVW. - Any comments, suggestions, and feedbacks are much appreciated (please send them to gtwvw@csacomputer.com). Bandung, 25 October 2004 Budyanto Dj.