harbour-core/contrib/gtwvw/doc/gtwvw.txt

/*
 * General Descriptions of GTWVW
 * Copyright 2004 Budyanto Dj. <budyanto@centrin.net.id>
 */

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. <budyanto@centrin.net.id>

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 <peter@rees.co.nz>
                      Rees Software & Systems Ltd

based on
  Bcc ConIO Video subsystem by
    Copyright 2002 Marek Paliwoda <paliwoda@inteia.pl>
    Copyright 2002 Przemyslaw Czerpak <druzus@polbox.com>
  Video subsystem for Win32 compilers
    Copyright 1999-2000 Paul Tucker <ptucker@sympatico.ca>
    Copyright 2002 Przemyslaw Czerpak <druzus@polbox.com>

The following parts are Copyright of the individual authors.
www - http://www.harbour-project.org

Copyright 1999 David G. Holm <dholm@jsd-llc.com>
   hb_gt_Tone()

See COPYING.txt for licensing terms.

www - http://www.harbour-project.org

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 <gc at niccolai dot ws>
*         Standard xplatform GT Info system,
*         Graphical object system and event system.
*         hb_gtInfo() And GTO_* implementation.
*
* (C) 2004 Mauricio Abre <maurifull@datafull.com>   //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.