For a binary distribution this issue isn't actual, of course. So, we are talking here about the source distribution. Compiling HwGUI is quite simple - as compiling of any Harbour program.

Harbour programmers may use Hbmk utility (it is absent in xHarbour). Just run it with hbp files:

       hbmk2 hwgui.hbp hbxml.hbp hwgdebug.hbp procmisc.hbp
    

As a result, ypu will get hwgui, hbxml, hwgdebug and procmisc libraries in your hwgui/lib/ directory.

You may use also one of command files, included in distribution, depending of your C compiler. For xHarbour programmers it is the only way. I prefer it, too, simply because I like to keep control ob the building process.

Before building the libraries 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
    

The sources of GTK version are located in hwgui/source/gtk/ directory. In the same place ypu will find a bash script for libraries building - build.sh. Before to launch it, you need to check the Harbour installation. If it was installed using binary deb or rpm package, Harbour files most likely are placed in /usr/local/bin, /usr/local/include/harbour, /usr/local/lib/harbour. In this case you don't need to do any additional work. But if your Harbour is placed in separate directory, compiled from sources, you need to set the path to this directory in HB_ROOT environment variable. You may insert appropriate line in build.sh, for example:

       export HB_ROOT=../../..
    

Now you can run the build.sh and the ready libraries must appear in hwgui/lib/ directory.

Now let talk about compiling and linking GUI programs with Harbour. HwGUI provides few header files in include/ and four libraries:

• hwgui - main HwGUI library;
• hwgdebug - visual debugger library, need to be linked together with hbdebug for program debugging;
• hbxml - a library of classes for reading/writing xml files, it is necessary to use forms and reports, created with the Designer;
• procmisc - a set of additional functions and HcEdit class.

Hwgdebug, hbxml and procmisc may be used without HwGUI, too. Besides, there are 3 additional library from contrib/, which may be linked, if needed:

• hbactivex - a library of classes for ActiveX support;
• hwg_extctrl - few additional controls, extending appropriate standard controls;
• hwg_qhtm - bindings to qhtm, a simple 3-rd party library for html rendering.

To build the GUI program, you need to link necessary libraries and add some options for the C linker - these options are different for different C systems. For to not write all these manually, HwGUI distribution includes scripts that solve this task. For those, who use Hbmk, there is hwgui/hwgui.hbc. Following is a command line to build some myprog.prg, if your hwgui\ directory is located in c:\harbour\:

      hbmk2 c:\harbour\hwgui\hwgui.hbc myprog.prg
    

      hbmk2 c:\harbour\hwgui\hwgui.hbc hwgui_xp.rc myprog.prg
    

For those, who don't use Hbmk, there are command files in samples\ directory for different C compilers. You may use them to build sample programs from samples\ or as a templates to build your programs.

For GTK version you may use Hbmk or samples/gtk_samples/build.sh bash script - probably, you will need to set the HB_ROOT environment variable, as described in a subsection 2.3. How to build HwGUI library (GTK version).

       #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 {||hwg_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 hwg_MsgInfo("First HwGUI Application")
          ENDMENU

          ACTIVATE WINDOW oMainWnd

          hwg_writelog( "Program terminated " + Dtoc(Date()) + " at " + Time() )

      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

At first, we create the font object for the main window. HwGUI works in such a way, that if a font isn't defined for a control, this control uses the font, defined for his parent window.

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

This command creates main window with the title "Example" and with previously created font. ON EXIT clause will cause appearance of a message box, user will need to choose "Yes" to quit the application.

      @ 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 {||hwg_EndWindow()}

The above commands creates appropriate controls - Edit, Combobox and Push Button. ComboBox is initialized with aCombo array, which was declared before. Button has an event handler defined - closing the application.

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

These commands creates the main menu, which includes the only item "About".

      ACTIVATE WINDOW oMainWnd

And, at least, this last command activates the main window. It appears on the screen with menu and all controls defined. Pay attention to the important fact: the main window is modal, i.e., when it appears on the screen the program stops. This means, that the lines of the code, which are located after ACTIVATE WINDOW oMainWnd, will be executed only after the window closes. In our sample this is a line, which writes date and time to a log:

      hwg_writelog( "Program terminated " + Dtoc(Date()) + " at " + Time() )

You can see that it is added to the file not immediately after the appearance of the window, but only after it is closed. These explanations may seem trivial for you, but many programmers just starting to write GUI applications, have some difficulties with this behaviour.

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.