• 1. Introduction
  • 1.1. What is HwGUI
  • 1.2. History of HwGUI
• 2. Installation of HwGUI
  • 2.1. HwGUI package
  • 2.2. How to build HwGUI library
  • 2.3. How to build HwGUI samples
• 3. How to use HwGUI
  • 3.1. First HwGUI application
  • 3.2. Inside HwGUI
• 4. Commands
  • 4.1. Commands for windows and dialogs handling
  • 4.2. Menu commands
  • 4.3. Commands for controls handling
  • 4.4. Get system commands
  • 4.5. Print commands
• 5. Functions
  • 5.1. Common dialogs
  • 5.2. MessageBoxes and HwGUI dialogs
  • 5.3. Drawing functions.
  • 5.4. Menu functions.
• 6. Classes
  • 6.1. Class hierarchy
• 7. QHTM integration
  • 7.1. Overview
  • 7.2. Commands
  • 7.3. Functions
• 8. Utilities
  • 8.1. Designer
• 9. License
• 10. About the author

HwGUI is an add-on library for Harbour and xHarbour, intended for creating GUI applications. There are two versions of HwGUI - Win32 version, which is based on direct calls of Win32 API, and GTK version, which uses GTK2 library and can be used under any platform where GTK is implemented ( Linux, Windows, probably MacOS ). While developing HwGUI I tried to hide from the end user - Harbour programmer technical details of API calls and to build a set of commands and functions, which could allow easily create and manage GUI objects.

I began to work on HwGUI in August 2001 and the first version was released on August 21. My initial intention was to create a small and fast GUI lib mainly for my own needs. And already in October I had wrote the first small application with HwGUI for my firm, it reads the databases, created and managed with the accounting system, generates some documents and sends them by fax.

Firstly, from the initial release and til the 1.3 HwGUI didn't use the OOP paradigm - and I even had declared this as one of HwGUI features. My main motivations was speed and stability. Harbour's implementation of classes at that time had some bugs and I didn't want to add problems to myself. And, of course, access to object's variables is more slow than access to the array items. OOP is an additional level and using of it reduces application's performance.

But later I have arrived at a decision to make HwGUI OOP based - to simplify user interface and make it better structured and more convenient. So starting from the release 2.0 HwGUI is based on OOP paradigm.

Since the autumn'2003 HwGUI is hosted by SourceForge, and there is a group of developers working on it. Thanks to all of them for participation and contributions.

Yet another important milestone in HwGUI's timeline is a December,2005 - where a development of GTK version has been started, so HwGUI became a cross-platform tool.

HwGUI is distributed as a zip package. Currently it doesn't use any setup utility, you need simply unzip it to any place you want. The zip package includes following files and directories:

Before building the library you need to set the HB_PATH environment variable, it should point to the directory where your copy of Harbour or xHarbour is. You may set it on your Windows environment or in the appropriate command ( .bat ) file, including there a line:

   SET HB_PATH=c:\harbour

   #include "hwgui.ch"

   Function Main
   Local oMainWnd, oFont
   Local aCombo := {"First","Second" }

      PREPARE FONT oFont NAME "MS Sans Serif" WIDTH 0 HEIGHT -13

      INIT WINDOW oMainWnd TITLE "Example" ;
         FONT oFont ;
         ON EXIT {||MsgYesNo("Really want to quit ?")}

      @ 20,10 EDITBOX "Hello, World!" SIZE 200,30

      @ 270,10 COMBOBOX aCombo SIZE 100, 150 TOOLTIP "Combobox"

      @ 120,60 BUTTON "Close" SIZE 150,30 ;
         ON CLICK {||oMainWnd:Close()}

      MENU OF oMainWnd
         MENUITEM "About" ACTION MsgInfo("First HwGUI Application")
      ENDMENU

      ACTIVATE WINDOW oMainWnd

  Return

First thing you will want to do, I think, is to create the main window. The best way to do this is the command INIT WINDOW. In this command you can define initial position and the size of the window, it's style, icon, background color. You can set also event handlers - codeblocks, which are evaluated for different events ( INIT, EXIT, PAINT, SIZE changing, GETFOCUS, LOSTFOCUS and others ).

Then you need to define controls for that window and the main menu ( MENU ... ENDMENU commands), and, at least, activate the window, ( ACTIVATE WINDOW ) show it on the screen. Let analyse the above sample.

  PREPARE FONT oFont NAME "MS Sans Serif" WIDTH 0 HEIGHT -13

  INIT WINDOW oMainWnd MAIN TITLE "Example" ;
     FONT oFont ;
     ON EXIT {||MsgYesNo("Really want to quit ?")}

  @ 20,10 EDITBOX "Hello, World!" ;
     SIZE 200,30
  @ 270,10 COMBOBOX aCombo ;
     SIZE 100, 150 TOOLTIP "Combobox"
  @ 120,60 BUTTON "Close" ;
     SIZE 150,30 ;
     ON CLICK {||EndWindow()}

  MENU OF oMainWnd
     MENUITEM "About" ACTION MsgInfo("First HwGUI Application")
  ENDMENU

  ACTIVATE WINDOW oMainWnd

From the point of messages handling all HwGUI windows ( and controls, which, in fact, are windows, too ) may be divided in two groups:

1) The windows, which messages are handled by HwGUI.
2) The windows, which messages are handled by Windows API only.

Handling of messages for the first group is implemented in the following way:
Window ( control ) creation functions stores the pointer to the appropriate HwGUI object in a window extra memory, granted by Windows API - by calling the function SetWindowObject(). Besides, the window creation functions sets the pointer to the window procedure ( an application-defined function that processes messages sent to a window ). This is implemented by setting the pointer in WNDCLASS structure ( see, for example, HWG_INITMAINWINDOW(), HWG_REGBROWSE() ) or by redefinition the window procedure ( HWG_INITEDITPROC(), HWG_INITWINCTRL() ).
Thus, all windows of a first group has special messages processing procedures ( MainWndProc(), WinCtrlProc(), ... ), while messages for windows of a second groups are processed by Windows API internally. The messages processing procedure extracts the pointer to appropriate HwGUI object from a window extra memory and calls the :onEvent method for this object.
The :onEvent method may process the message itself, or pass it to the super method, or, returning -1, pass it to the default Windows API procedure.

For example, the HStatic and HStatus are a second group controls, i.e. messages to this control aren't processed by HwGUI - that's why Windows doesn't process notifications, messages for it child controls.
So, if you want to create ontop of them other controls, they are two ways:

1) create a new class, derived from HStatic and make it a control of a first group ( store a object pointer and redefine the window procedure )
2) use as a place holder for a button not HStatic or HStatus, but, for example, the HPanel. Hpanel is a general purpose control, which I use and recommend you to use for such purposes.