• cDescript - this string appears in the dialog as a description of a file type. In Windows version this parameter may be an array of descriptions ({ "All files", "Dbf files"});
• cMask - string type parameter, describing the file mask ("*.dbf", for example). In Windows version this parameter may be an array of masks ({ "*.*", "*.dbf"}); The length of this array must be the same as of cDescript;
• cInitDir - optional string parameter, the initial directory for file selecting.
• cTitle - optional string parameter, the title of a dialog box.
• Return value - a string with a selected file name, or an empty string, if a file wasn't selected.

   cFileName := hwg_Selectfile( {"dbf files( *.dbf )","All files(*.*)"}, ;
      {"*.dbf","*.*"}, cPath )

• cTitle - optional string parameter, the title of a dialog box.
• cInitDir - optional string parameter, the initial directory for file selecting.
• aDescript - an array like { { "Dbf files", "*.dbf" }, { "All files", "*" } } with file masks and descriptions;
• Return value - a string with a selected file name, or an empty string, if a file wasn't selected.

   cFileName := hwg_SelectFileEx( ,, { { "Dbf files", "*.dbf" }, { "All files", "*" } } )

• cTitle - optional string parameter, the title of a dialog box.
• Return value - a string with a selected folder name, or an empty string, if a folder wasn't selected.

• cPrompt - this string appears as a prompt of a file name.
• cDescript - this string appears in the dialog as a description of a file type.
• cMask - string type parameter, describing the file mask.
• cInitDir - optional string parameter, the initial directory for file selecting.
• cTitle - optional string parameter, the title of a dialog box.
• Return value - a string with a selected file name, or an empty string, if a file wasn't selected.

   fname := hwg_Savefile( "*.htm","( *.htm )","*.htm", cPath )

• Return value - handle to device context ( hDC ) of selected printer, 0 - if a printer wasn't selected.
• Writes to the cPrinterName parameter the name of a selected printer.

• nColorCurrent - a numeric parameter, initial value of a color,
• Return value ( numeric ) - selected color, Nil - if a color wasn't selected.

These all are standard message boxes with a different buttons set.

• cMessage - a message text;
• cTitle - a title of a box;
• Return value ( logical ) - for those of them, which has more than one button.

Special return values:
hwg_MsgYesNoCancel() : cancel = 0 , yes = 1 , no = 2
WinAPI: hwg_MsgOkCancel() : OK = 1 , Cancel = 2 , GTK: .T., .F.

• cTitle - a title of a box;
• cText - a prompt for the input;
• nStyle - a WinAPI style for a GET item (ES_PASSWORD, for example);
• nLeft, nTop - coordinates of the left upper corner of a dialog box;
• nDlgStyle - a WinAPI style for a dialog;
• cInitStr - init value of a string;
• Return value ( string ) - the string, which you entered, empty - if you press CANCEL.

• arr - an array, one-dimensional or multidimensional, which represents the list;
• cTitle - a header of a dialog box;
• nLeft, nTop - dialog box left upper corner coordinates;
• oFont - a font for a dialog, an object of HFont class;
• clrT, clrB - colors ( text and background ) of a browse;
• clrTSel, clrBSel - colors ( text and background ) of a selected row of a browse;
• cOk - a caption of a button to confirm selecting. If this parameter is omitted, the button will not present;
• cCancel - a caption of a button to cancel selecting. If this parameter is omitted, the button will not present;
• Return value - the number of selected row, 0 - if nothing is selected.

• Return value - a pointer to a paint structure.

• handle - handle of a painted object;
• pps - a pointer to a paint structure;
• Return value - handle of a device context (hDC).

• handle - handle of a painted object;
• pps - a pointer to a paint structure.

• lpDis - a pointer to DRAWITEMSTRUCT;
• Return value - an array aDrawItem with an information about widget being painted;
  aDrawItem[3] - hDC;
  aDrawItem[4] - nLeft, left border of drawing area;
  aDrawItem[5] - nTop, top border of drawing area;
  aDrawItem[6] - nRight, right border of drawing area;
  aDrawItem[7] - nBottom, bottom border of drawing area;

• handle - handle of a control;
• Return value - an array aArea with a control client area coordinates;
  aArea[1] - nLeft, left border of client area;
  aArea[2] - nTop, top border of client area;
  aArea[3] - nRight, right border of client area;
  aArea[4] - nBottom, bottom border of client area;

• hDC - handle of the device context;
• handle - a variable handle of an object of HFont, HPen or HBrush class.

    // Create HPen object: a line thickness - 2px, a color - red
    oPen := HPen():Add( BS_SOLID, 2, 255 )
    // Select this object as current for hDC
    hwg_Selectobject( hDC, oPen:handle )
    // Draw a 2px red line
    hwg_Drawline( hDC, 5, 1, 100, 1 )

• handle - a variable handle of an object of HFont, HPen, HBrush, HBitmap or HIcon class.

• hDC - handle of the device context;
• x1, y1 - point coordinates.

• hDC - handle of the device context;
• x1, y1 - point coordinates.
• lClose - an optional pframeter, GTK only, causes cairo_stroke() call.

• hDC - handle of the device context;
• x1, y1 - left top corner coordinates;
• x2, y2 - right bottom corner coordinates.
• hPen - pen handle

• hDC - handle of the device context;
• x1, y1 - left top corner coordinates;
• x2, y2 - right bottom corner coordinates.
• hPen - pen handle
• hBrush - brush handle

• hDC - handle of the device context;
• x1, y1, x2, y2, x3, y3 - coordinates;
• hPen - pen handle

• hDC - handle of the device context;
• x1, y1, x2, y2, x3, y3 - coordinates;
• hPen - pen handle
• hBrush - brush handle

• hDC - handle of the device context;
• x1, y1 - left top corner coordinates;
• x2, y2 - right bottom corner coordinates;
• iRadius - a radius of an ellipse used to draw rounded corners.
• hPen - pen handle

• hDC - handle of the device context;
• x1, y1 - left top corner coordinates;
• x2, y2 - right bottom corner coordinates;
• iRadius - a radius of an ellipse used to draw rounded corners.
• hPen - pen handle
• hBrush - brush handle

• hDC - handle of the device context;
• x1, y1 - left top corner coordinates of a bounding rectangle;
• x2, y2 - right bottom corner coordinates of a bounding rectangle;
• hPen - pen handle

• hDC - handle of the device context;
• x1, y1 - left top corner coordinates of a bounding rectangle;
• x2, y2 - right bottom corner coordinates of a bounding rectangle;
• hPen - pen handle
• hBrush - brush handle

• hDC - handle of the device context;
• x1, y1 - first point coordinates.
• x2, y2 - second point coordinates.

• hDC - handle of the device context;
• x1, y1 - left top corner coordinates of a bounding rectangle;
• x2, y2 - right bottom corner coordinates of a bounding rectangle;
• xr1, yr1 - coordinates of the endpoint of the first radial;
• xr2, yr2 - coordinates of the endpoint of the second radial.

• hDC - handle of the device context;
• x1, y1 - left top corner coordinates;
• x2, y2 - right bottom corner coordinates;
• hBrush - a handle of a brush ( may be oBrush:handle ).

• hDC - handle of the device context;
• x1, y1 - left top corner coordinates;
• x2, y2 - right bottom corner coordinates;
• nFlag - determines, how to draw a button:
     1 - normal;
     2 - pressed;
     5 - flat;
     6 - flat pressed.

• hDC - handle of the device context;
• x1, y1 - left top corner coordinates;
• x2, y2 - right bottom corner coordinates;
• nFlag - the type of inner and outer edges, it is a combination of one inner-border flag and one outer-border flag. For details look at the MSDN documentation for DrawEdge() function.
• nBorder - the type of border, For details look at the MSDN documentation for DrawEdge() function.

• hDC - handle of the device context;
• x1, y1 - left top corner coordinates;
• x2, y2 - right bottom corner coordinates;
• nFlag - determines, how to draw.

• Angles are passed in degrees.
• Corresponds to the standard X axis, drawing direction is clockwise.

• hDC - handle of device context;
• x1 and y1 - coordinates of upper left corner;
• x2 and y2 - coordinates of bottom right corner;
• type - the type of gradient filling:
     1 - vertical and down;
     2 - vertical and up;
     3 - horizontal and to the right;
     4 - horizontal and to the left;
     5 - diagonal right-up;
     6 - diagonal left-down;
     7 - diagonal right-down;
     8 - diagonal left-up;
     9 - radial gradient;
• colors - our colors (maximum - 16 colors), a color can be represented as 0xBBGGRR;
• stops - fractions on interval [0;1] that correspond to the colors, a stop determines the position where the corresponding color reaches its maximum;
• radiuses - for our rounded corners:
     first - for upper left;
     second - for upper right;
     third - for bottom right;
     fourth - for bottom left;

• cName | cBody - the name of an image file or a string with a previously loaded image file content;
• lMem - a logical variable must be set to .T., if a first parameter is a string with an image file content;
• Return value - handle of a bitmap;

• cName - name of a bmp file;
• hDC - (optional) handle to a current device context.
• Return value - handle of a bitmap;

Function only for internal usage.
To save a bitmap object into a file,
use FUNCTION hwg_oBitmap2file().

• cName - name of a stock object. The set of names you may see, for example, with the help of Tutorial utility, chapter "Advanced using of controls", module "Browse of bitmaps" ;
• nSizeType - (optional) type of a size, may be one of following:
     GTK_ICON_SIZE_MENU,
     GTK_ICON_SIZE_SMALL_TOOLBAR,
     GTK_ICON_SIZE_LARGE_TOOLBAR,
     GTK_ICON_SIZE_BUTTON (default),
     GTK_ICON_SIZE_DND,
     GTK_ICON_SIZE_DIALOG;
• Return value - handle of a bitmap;

• hDC - handle of device context;
• hBitmap - handle of a bitmap (oBitmap:handle usually);
• style - (optional parameter, for WinAPI only). By default the value is SRCCOPY: copies the source rectangle directly to the destination rectangle;
• x, y - coordinates of a point where to start drawing bitmap (left top corner);
• width, height - width and height of a destination image (optional parameters, by default - original bitmap size).

• hDC - handle of device context;
• hBitmap - handle of a bitmap (oBitmap:handle usually);
• x, y - coordinates of a point where to start drawing bitmap (left top corner);
• trcolor - transparent color;
• width, height - width and height of a destination image (optional parameters, by default - original bitmap size).

• hDC - handle of device context;
• hBitmap - handle of a bitmap (oBitmap:handle usually);
• x, y - coordinates of a point where to start drawing bitmap (left top corner).

• hDC - handle of device context;
• hBitmap - handle of a bitmap (oBitmap:handle usually);
• nLeft, nTop, nRight, nBottom - coordinates of a rectangle (optional).

• hDC - handle of device context;
• hIcon - handle of an icon (oIcon:handle usually);
• x, y - coordinates of a point where to start drawing an icon (left top corner);

• hBitmap - handle of a bitmap (oBitmap:handle usually);
• Return value - an array:
  aArray[1] - width of a bitmap;
  aArray[2] - height of a bitmap.

hBitmap : Handle of a bitmap object, for example "oBitmap:handle".
Returns the height of a bitmap.

hBitmap : Handle of a bitmap object, for example "oBitmap:handle".
Returns the width of a bitmap.

• hBitmap - handle of an icon (oIcon:handle usually);
• Return value - an array:
  aArray[1] - width of an icon;
  aArray[2] - height of an icon.

• nCode - look at MSDN, GetSysColor() function.
• Return value - numeric color representation.

• nCode - look at MSDN, GetSysColor() function.
• Return value - a brush handle.

• nStyle - a pen style ( PS_SOLID, PS_DASH, PS_DOT, ... );
• nWidth - a pen thickness;
• nColor - numeric color representation;
• Return value - a pen handle.

• nColor - numeric color representation;
• Return value - a brush handle.

• nHatch - the hatch style of the brush, look at MSDN, CreateHatchBrush() function.;
• nColor - numeric color representation;
• Return value - a brush handle.

• hWnd - handle of GUI element;
• Return value - handle of device context.

• hWnd - handle of appropriate GUI element;
• hDC - handle of device context.

• hDC - handle of the device context;
• x1, y1 - coordinates of a start point.
• cText - the text string to draw.

• hDC - handle of the device context;
• cText - the text string to draw.
• x1, y1, x2, y2 - text area coordinates;
• aRect - an array with text area coordinates, may be passed instead of x1, y1, x2, y2;
• nStyle - alignment style: DT_LEFT (by default), DT_CENTER, DT_RIGHT.

• hDC - handle of the device context;
• Return value - an array:
     array[1] - a text height,
     array[2] - average character width;
     array[3] - maximal character width; (WinAPI only)
     array[4] - tmExternalLeading; (WinAPI only)
     array[5] - tmInternalLeading; (WinAPI only)
     array[6] - tmAscent; (WinAPI only)
     array[7] - tmDescent; (WinAPI only)
     array[8] - tmWeight. (WinAPI only)

• hDC - handle of the device context;
• Return value - an array:
     array[1] - a text width,
     array[2] - a text height;

• hDC - handle of the device context;
• nColor - new color value;
• Return value - previous color value.

• hDC - handle of the device context;
• Return value - previous color value.

• hDC - handle of the device context;
• nColor - new color value;
• Return value - previous color value.

• hDC - handle of the device context;
• Return value - previous color value.

• hDC - handle of the device context;
• lTransparent - boolean value, sets a transparent mode if true, unsets - if false.

• hDC - handle of device context;
• Return value - handle of GUI element.

• hWnd - window handle;
• x1, y1 - coordinates of a top left corner of a selected region;
• width, height - width and height of a selected region;
• Return value - handle of a bitmap.

• Return value - an object of HDialog class, a current modal dialog; Nil - if there is no opened modal dialog.

• handle - optional parameter, a handle of a dialog window, which should be closed.

• Return value (logical) - .T., if the window handle identifies an existing window.

• hWnd - window handle.

• Return value - handle of an active window.

• handle - handle of GUI element;
• nStyle - WinAPI style.

• handle - handle of GUI element;
• Return value - (numeric) WinAPI style.

• handle - handle of GUI element;
• nStyle - an extended WinAPI style.

• handle - handle of GUI element;
• Return value - (numeric) an extended WinAPI style.

• handle - window handle.

• handle - window handle.

• handle - window handle.

• handle - handle of a GUI element;
• lEnable - (logical) enable, if .T., disable if .F..

• handle - handle of a GUI element;
• Return value - (logical) .T., if GUI element is enabled.

• handle - handle of a GUI element.

• handle - handle of a GUI element.

• handle - handle of a GUI element;
• cTitle - the text.

• handle - handle of a GUI element;
• Return value - the text.

• hWnd - handle of a window;
• lResizeable - boolean argument.

• handle - handle of a GUI element;
• Return value - handle to the GUI element that previously had the keyboard focus.

• Return value - handle to the GUI element that has the keyboard focus.

• oWnd - the window with the status pane, an object of one of subclasses of HWindow class;
• nPart - a number of a fragment of the status pane;
• CText - a text for the status pane;
• lRedraw - .T., to redraw status pane immedeately.

• hCtrl - a handle of a widget;
• Return value - an object of a parent GUI element.

• hCtrl - a handle of a widget;
• Return value - an object of a widget.

• oCtrl - an object of a widget;
• Return value - an object of a window.

For BROWSE of arrays:
Copies the array to browse into the
browse object.
Usage see sample program "demobrowsearr.prg".
arr: an array with 2 dimensions, for example
al_DOKs := { {"1"} , {"2"} , {"3"} , {"4"} }
...

Sample for read out the edited array:

@ 360,410 BUTTON oBtn4 CAPTION "OK " SIZE 80,26 ;
ON CLICK { | | bCancel := .F. , ;
al_DOKs := oBrwArr:aArray , ;
hwg_EndDialog() }

Returns an object with a suitable default font
for Windows and LINUX, OS dependent.

• handle - handle of the control;
• cTooltip - a text of a tooltip.

• handle - handle of the control.

• handle - handle of the control;
• cTooltip - a new text of a tooltip.

This function calls the calendar for date selection
in design like the WinAPI datepicker.
Based on the MONTHCALENDAR command.

 dstartdate : Date of start, if NIL, the default is "today" from system date.
 cTitle : Title for this dialog, default is "Calendar"
 cOK : Caption for OK button, default is "OK"
 cCancel : Caption for cancel button, default is "Cancel"
 nx , ny : Position in calling Window (default 0, 0)
 wid, hei : Width and height of the calendar window, add 23 pixels
    to height for size of dialog (space for buttons needed).
    Default is 200, 160.

 Returns the selected date (type "D").

For details see inline comments of sample program
"samples/testget1.prg".
Here you find instructions to create a multiplatform substitute for the Windows only DATEPICKER.

Some Screenshots:

Datepicker Windows:
(Heute = today)


Datepicker substitute Windows all screens:


Datepicker LINUX (Sample program demoget1.prg):


Windows MONTHCALENDAR command:
(Fertig = Ready, Abbruch = Cancel)


LINUX MONTHCALENDAR command:

• handle - handle of a control;
• Return value - handle of a parent GUI element.

Loads a cursor from stock and returns its handle.

GTK: Parameter "cursor" is a numeric value for identifying
the standard cursor from stock.
Allowed values are defined in HWGUI include file "gtk.ch" as
GDK_* definitions, for example:
GDK_ARROW Standard arrow
GDK_SB_V_DOUBLE_ARROW Double pointed arrow pointing north and south
GDK_SB_H_DOUBLE_ARROW Double pointed arrow pointing west and east
Attention !
Invalid value may cause crash or freeze of program.

WinAPI: Parameter "cursor" is a numerical value. It is evaluated from a string for the second parameter of WinAPI function
"LoadCursor(hInstance,lpCursorName)"
by macro
MAKEINTRESOURCE(n) (used in HWGUI source file "control.c").
The allowed values are defined in include "winuser.h"
as IDC_* definitions, for example:
 IDC_ARROW Standard arrow
 IDC_SIZENS Double pointed arrow pointing north and south
 IDC_SIZEWE Double pointed arrow pointing west and east
(not the same cursors as described for GTK above)

For setting of parameter for hwg_LoadCursor()
look into the WinAPI include file "winuser.h"
to get the numerical value, for example:
 IDC_ARROW : 32512
 IDC_SIZENS : 32645
 IDC_SIZEWE : 32644
Invalid value loads the IDC_ARROW, it is the default cursor.

To display the cursor, call functions
hwg_SetCursor() and hwg_ShowCursor().

Use the compiler switch "#ifdef __GTK__" for
use in multi platform applications.
See sample program "demosplit.prg".

Loads a cursor from a "*.cur" type file and returns its handle.
ccurFname : Filename (and path) of cursor file name.
In case of errors the handle for default cursor "Arrow" is
returned.
Cursor files are created and edited with special cursor editor programs.
So it is possible to use customized cursor's in an HWGUI application.

To display the cursor, call functions
hwg_SetCursor() and hwg_ShowCursor().

Use the compiler switch "#ifdef __GTK__" for
use in multi platform applications.

Loads a cursor from a "*.cur" type file and returns its handle.
This is the special version for GTK and has the additional parameters x and y.
All other descriptions see WinAPI version of this function.

Uses the following GTK function for creating the cursor:
GdkCursor* gdk_cursor_new_from_pixbuf(GdkDisplay *display,GdkPixbuf *pixbuf, gint x, gint y)

The parameters x and y are mandatory.

x: the horizontal offset of the 'hotspot' of the cursor
y: the vertical offset of the 'hotspot' of the cursor

We suggest, to try for x and y the half size value of pixels.
The value of the resulting pixbuf (not the file size of the *.cur file)
may not exceed 4095 bytes.

For details read the GTK 2 reference.

Use the compiler switch "#ifdef __GTK__" for
use in multi platform applications.

Loads a cursor from a binary variable and returns its handle.
It is an equivalent to functions "hwg_LoadCursorFromFile()" for WinAPI and GTK.
For details look to the descriptions of this functions.
Parameters nx and ny are ignored on WinAPI, but set them for multi platform applications.

Strategy:

1) Create the *.cur file with an suitable cursor editor.
2) Create an hex value from this file with utility "file2hex.prg"
in directory "utils\bincnt".
3) In your program, convert the hex values into binary with function "hwg_cHex2Bin()".
Create the handle of cursor by calling function "hwg_LoadCursorFromString()".
4) To display the cursor, call functions hwg_SetCursor() and hwg_ShowCursor().

• cursor - cursor handle;
• hCtrl - handle of the widget under cursor (GTK only).

• parentHandle - handle of a parent window (oCtrl:oParent:handle);
• nId - id of a control (oCtrl:id);
• cText - text string to be set.

• parentHandle - handle of a parent window (oCtrl:oParent:handle);
• nId - id of a control (oCtrl:id);
• Return value - text string, displayed in a control.

• parentHandle - handle of a parent window (oCtrl:oParent:handle);
• nId - id of a control (oEdit:id);
• Return value - text string, displayed in an edit control.

• handle - handle of an edit control (oEdit:handle);
• Return value - a number 1 ... - a cursor position.

• handle - handle of an edit control (oEdit:handle);
• nPos - number 1 ... - a cursor position.

Searches menu item with id "nId" in an menu array "aMenu" inclusive
all submenus (recursive search).
Returns the array with match of nId, if no match NIL.
nPos returns via call by reference the position in the menu found:
For example:
   LOCAL nPos
   nPos := 1
   Hwg_FindMenuItem( aMenu[ 1,nPos ] , nId, @nPos1 )

• xWnd - it may be a handle of a window - menu owner, or a context menu object, if it is an empty value (Nil), the main window menu is used;
• nId - id of a menu item;
• lCheck - logical value: if .T. item will be checked, if .F. - unckecked.

• xWnd - it may be a handle of a window - menu owner, or a context menu object, if it is an empty value (Nil), the main window menu is used;
• nId - id of a menu item;
• Return value - logical value: if .T. the item is checked, if .F. - unckecked.

• xWnd - it may be a handle of a window - menu owner, or a context menu object, if it is an empty value (Nil), the main window menu is used;
• nId - id of a menu item;
• lValue - logical value: if .T. item will be enabled, if .F. - disabled.

• xWnd - it may be a handle of a window - menu owner, or a context menu object, if it is an empty value (Nil), the main window menu is used;
• nId - id of a menu item;
• Return value - logical value: if .T. the item is enabled, if .F. - disabled.

<not available>
Returns the caption (string) of a menu item defined by the id of a menu item

• xWnd - it may be a handle of a window - menu owner, or a context menu object, if it is an empty value (Nil), the main window menu is used;
• nId - id of a menu item.

Comment for multi platform programs:
It is not a good idea, to store program settings in the registry.
Use configuration files instead, following formats are possible:
-  XML files (best choice, strictly recommended for new applications),
-  Ini files (*.ini), see comment for function Hwg_WriteIni(),
-  Clipper MEM files, are supported by Harbour of course,
-  Pure text files.

The registry functions can be useful for writing a multi platform setup program
with HWGUI.
Use the compiler switch "#ifndef __GTK__" to hide the registry functions on non Windows systems.

Get origin path and name (this were the exe file is located).
ft_origin() is only available in Harbour 3.4 and up, but
here the solution for multi platform usage
and Harbour 3.2 and up !
(for both HWGUI and Harbour terminal/console applications)

argv[0]: The argv[0] argument passed to the main()
function contains the path and name of the executable file.

int main(int argc, char *argv[]) {
printf("Executable path: %s", argv[0]);
return 0;
}
but this is reachable from Harbour and HWGUI by following sequence:

LOCAL coriginp, coriginchdir

* Get the origin path and name
coriginp := hb_argV( 0 )

* Change to origin directory
IF .NOT. EMPTY(coriginp)
coriginchdir := hwg_Dirname(coriginp)
//ft_ChDir( coriginp )
hwg_CHDIR(coriginchdir)
ENDIF
==> find this sequence in sample program "demofunc.prg"
and test program "test/test_origin_cons".

Purpose:
Go to the origin directory before opening files and databases in this directory,
now you can call the programm by using an absolute path !

This is checked on LINUX and MacOS with GCC,
Windows with MinGW and BCC.
Ignore warning with BCC:
Call to function 'chdir' with no prototype in function HB_FUN_HWG_CHDIR
Not checked on other Compilers (Pelles C, ...)
We will add the test results as soon as possible)

• Windows:    "\"
• UNIX/LINUX and MacOS:     "/"

• arr - an array with HwGUI objects,
• cName - a name of HwGUI object.

• n == 1: returns a short string with version number, e.g. "2.20",
• n == 2: returns an integer build number,
• n == 3: returns a logical value, which tells, if this is a UNICODE build,
• n is omitted: returns a string with full information.

Instructions for programmer, who publishes a new HWGUI release:
Set release and build number in this include file before a new release is created:
include\guilib.ch
Reset the values of HWG_VERSION to "Code Snapshot" and
HWG_BUILD to 0 after publification of a new HWGUI release.

• cText - the text to be written;
• fname - (optional) a file name, the default is "a.log".

• sTraceMsg - pointer to a string with the text to be written;
• sFile - (optional) pointer to a string with file name, the default is "ac.log", set to NULL for default value.

A sample code snippet to log numeric values:
   char debug[100];
   int num = 1000;
   itoa(num,&debug,10);
   hwg_writelog(NULL,&debug);

• oDlg - (optional, default value is default parent window) an object of subclass of HWindow, the window, a key is set for;
• nCtrl - a code of a control key (e.g. FCONTROL), 0 - if not defined;
• nKey - a key code,
• block - a codeblock, which should be evaluated while pressing the key;
• lGlobal - (optional, default is .F.) - logical value, which determines, if the "hot key" is set globally.

• cColor - a string in #RRGGBB format, describing the color;
• Return value - an integer representation of a color.

• nColor - an integer representation of a color;
• Return value - a string in RRGGBB format, describing the color.

• nColor - an integer representation of a color;
• nRed - (optional) red component, passed by reference;
• nGreen - (optional) green component, passed by reference;
• nBlue - (optional) blue component, passed by reference;
• Return value - an array of three numbers, which corresponds to red, green and blue color components.

• nRed - red component;
• nGreen - green component;
• nBlue - blue component;
• Return value - a numeric color representation.

• cName - name of a bmp resource;
• Return value - handle of a bitmap;

• cName - a full path and name of a binary container;
• Return value - (logical) .T., if a file is opened successfully and .F. - in other case.

• objBitmap - object from resource container (from HBitmap class);
• cname - resource name of object;
• cfextn - file extension, for example "bmp" (Default);
• Return value - (logical) .T., if a file is opened successfully and .F. - in other case.

Standard dialog for editing memo fields.
Usage see sample program demodlgbox.prg.
(Simple file editor).
Can be also used for editing memo fields in a database by the usage of an UDF (user defined function).
Could substitute the internal memo edit dialog of the
HBROWSE class, if necessary by UDF usage.

Parameters (Default values in brackets):
mpmemo : The memo field to edit

For National Language Support (NLS),
for title, button's caption and tooltips (cTT..) :

cTextTitME : Title of Dialog ("Memo Edit")
cTextSave : ("Save")
cTextClose : ("Close")
cTTSave : ("Save modifications and close")
cTTClose : ("Close without saving modifications")

oHCfont : Font object for HCEDIT in dialog(<NONE>)

Returns the edited memo. If cancelled, the previous memo value
is returned.

• oDlg - the window with GET-elements, an object of one of subclasses of HWindow.

Returns the number of elements of an array.
Fixes the following problem:
LEN(array) crashes with
"Argument error", if array initialized
with empty value: array := {}
In this case, this function
returns correctly 0.
Also returns 0, if array is NIL.
Example:
To create and fill an array the following
example sequence is most suitable:
 LOCAL anewarray
 anewarray := {}
 * --- let array empty for test
 * AADD(anewarray,"One")
 * AADD(anewarray,"Two")
Now get the length:
 ? LEN(anewarray)         && crashes here
 ? HWG_ARRAY_LEN(anewarray)    && 0

Returns .T., if program is running with UTF-8 support.
This function works also on GTK cross development environment.
Windows operating system does not support Unicode.
Result may decide the setting of the local codepage for correct display.

Windows 10: Always returns an empty list.
GTK: Do not use yet, crashes with core dump. Need to fix.

Returns the drive serial number as hex value.
cDrive must be a path to the device, for
example "C:\".
cDrive may be empty for recent drive.
For compatibility purposes on GTK this function
exists and returns forever an empty string "".

Returns the drive serial number as numeric value. cDrive must be a path to the device, for example "C:\". cDrive may be empty for recent drive. This is the same as Harbour function VolSerial() on contrib/hbct. In case of errors, the funtion return -1. For compatibility purposes on GTK this function exists and returns forever -1.

Reads a value from an ini file.
See additional instructions at description of Hwg_WriteIni().

Stores and modifies an ini file. The storage location of the file
depends on the the Windows version.
Example for Windows 10:
C:\Users\<user>\AppData\Local\VirtualStore\Windows\HwGui.ini
This is the directory, where the sample program
"samples\demoini.prg" creates the ini file.

For multi platform use:
Look into the Source code of Harbour:
The following files contains classes and functions for
handling Windows style ini files:
- src\rtl\hbini.prg
- tests\inifiles.prg : Class library from Matthew Hamilton (CLASS TIniFile).
For an extented version with additional functions look at project CLLOG:
https://sourceforge.net/projects/cllog/
File: src\libini.prg
The main section is in file "logw.prg".
Use this as sample for creating your own system
handling ini files. The program code contains
many inline comment with instructions for use
in english and german language.

• n - the value to be converted;
• Return value - the low-order word of the specified value.

• n - the value to be converted;
• Return value - the high-order word of the specified value.

Hides or recovers (displays) the mouse cursor.
No return value.

This feature is also helpful for computers with touchscreen.
The behavior on GTK and Windows differs.
First parameter: .F. hides the cursor, .T. recovers it.
Do not forget, that the mouse action is forever active, only you
cannot see the cursor.
Use compiler switch "#ifdef __GTK__" to activate the individual function call
on WinAPI or GTK for multi platform applications.
For details see inline comments in sample program
"demofunc.prg".

WinAPI:
Use this function only with first parameter, the second and third parameter are ignored.
If used the 2nd and 3rd parameter (as a dummy for multi platform),
be shure that they are not NIL,
because the program crashes with argument error.
The function has effect on all windows of the application
(main window and child windows),
also on internal HWGUI dialogs like hwg_msginfo().
so only one call of this function is needed for the whole application.
Parameter lcursor:
- .T. increases the cursor display counter by 1.
- .F. decrement it by 1.
return value:
Type = int, specifies the new display counter.
The cursor is displayed, if greater or equal 0.
Initial value is 0, if mouse is installed,
otherwise -1.

GTK:
The function has only effect on one window, the handle of the window
desired for hiding the cursor must be delivered in parameter 2.
The parameter 3 is needed for recovery.
Repeat function for every window.
Has no effect on special HWGUI dialogs like hwg_msginfo().
Return values:
0: cursor visible
-1: cursor hidden.
State of development: Only on LINUX the recovery crashes (range overflow).
As a substitute, the cursor is recovered with type GDK_ARROW, which
seems to be standard cursor.
This function works also on GTK cross development environment.

In usage together with hwg_ShowCursor().
Call this function in main section to save the old mouse cursor style
in a numeric variable for later recovery after hiding it.
For details see hwg_ShowCursor() and inline comments in sample program
"demofunc.prg".
Use compiler switch "#ifndef __GTK__" to hide the function call on WinAPI
for multi platform applications.
For recent bug in GTK on LINUX see description of hwg_ShowCursor().

Some standard curser styles are defined in:
include\gtk-2.0\gdk\gdkcursor.h
This function works also on GTK cross development environment.

cLocale: The locale string.
Sets the locale for the HWGUI program.
For WinAPI available, but function body is empty
for compatibility purpose.
Before calling this function, the desired locale must
be requested with the REQUEST command.

Extracts the filename from a path string.
Returns the extracted path.
Is equivalent to the UNIX command "basename".
A trailing / or \ is deleted.

Extracts the filename from a path string.
Returns the extracted file name.
Is equivalent to the UNIX command "dirname".
A trailing \ or / is deleted.
At recent directory it returns "." .

With this rules a path can be combined like this sample:
newname = hwg_Dirname("C:\") + "\" + "hugo.txt"

Special case on Windows for example
(should appear seldom):
Fullpath ="C:hugo.txt"

Handle this case as following:
IF RAT(hwg_GetDirSep(),Fullpath) == 0 .AND. RAT(":",Fullpath) != 0
  newname = hwg_Dirname("Fullpath") + "hugo.txt"
ELSE
  newname = hwg_Dirname("Fullpath") + "\" + "hugo.txt"
ENDIF

Reduce \\ to \ or // to / in pSwithdbl
(depends on operating system).
For handling of file and path names.
Returns the path value with reduced number of slashes or backslashes.
Avoids for example "C:\\".

In most cases, the value is "C:\Windows".
This function works also on GTK cross development environment.
Is available on other operating systems for compatibility,
then returns forever an empty string ("").

Returns the path of the temporary directory.
Value depends on the version of the operating system.
This function works also on GTK cross development environment.
Windows: In most cases, the value is "C:\Users\<userid>\AppData\Local\Temp\".
LINUX/UNIX: In most cases, the value is "/tmp" or "/var/tmp".
First the function reads the environment variable "TMPDIR" and
returns this value. If the TMPDIR variable does not exist, it returns
as default value "/tmp".
This function works also on GTK cross development environment.

Generates a unique full path and file name string for a temporary file.
Format is:
<path to temporary directory>+<cPrefix>999999<cSuffix>

- The number is derived from return value of the SECONDS() function,
   so every hundreth second an new name is created.
   The returned number is of type integer.
   Range is from 0 to 8639900 (86399 * 100).
- Parameters cPrefix and cSuffix are optional.
- Default values: cPrefix = "e", cSuffix = ".tmp".
- <path to temporary directory> is returned from hwg_GetTempDir().
   Directory separator is suitable to used operating system.
- If you need more than one temporary file at one time,
   use different prefixes or suffixes.

Sample:
   cTmp := hwg_CreateTempfileName("pre",".ext")

Don't forget to delete the created file(s) after usage by
   FErase( cTmp )

All characters for cPrefix and cSuffix are allowed, if supported by
operating system for file and directory names (without directory separators).
For best multi platform compatibilty we recommend to use only
ASCII letters in lower case (a ... z).
This function works also on GTK cross development environment.

Don't matter about a path string returned by several functions,
if they are terminated with a trailing directory separator or not.
This function adds the trailing directory separator,
if it is not existing.
So you can concatenate a normal file name
to get full file name + path.
Example:
   cp := hwg_CompleteFullPath( hwg_GetWindowsDir() ) + "filename.bin"
hwg_GetWindowsDir() returns "C:\Windows", then
cp was completed to:    "C:\Windows\filename.bin".
Other example:
hwg_GetTempDir() returns:
   "C:\Users\alex\AppData\Local\Temp\"
so
   cp := hwg_CompleteFullPath( hwg_GetTempDir() ) + "filename.bin"
was completed to:
   "C:\Users\alex\AppData\Local\Temp\filename.bin".
On UNIX/LINUX the functions handle the separator "/"
in the same way as "\".
This function works also on GTK cross development environment.

Process file name extension:
Add file extension, if not available
or replace an existing extension.
pFiname : The filename to be processed
pFiext : The new file extension
lupper : Windows only (parameter ignored on UNIX/LINUX):
         Set to .T. , if extension is set to upper case
         .F. : preserve case (default)
ctestdirsep : Only for test purposes:
Modifies the directory separator, default
is the return value of function hwg_GetDirSep(),
so it is assigned correct by the used operating system.

Sample call: hwg_ProcFileExt("TEST.TXT","PRG")
returns the value "TEST.PRG"
pFiname may contain a full path.
DOS, Windows and UNIX/LINUX filenames
are supported.
Sample usage the sample program "samples\demofunc.prg".

Additional information for functions hwg_GetDesktopWidth() and hwg_GetDesktopWidth():
As reported with bug ticket #112, on newer GCC and Windows versions the
main window is not opened in full size.

A quick fix is reported like this code snippet:
INIT WINDOW oFormMain MAIN AT -7,0 SIZE hwg_Getdesktopwidth()+14,hwg_Getdesktopheight()+14

Please check by compiling the test program
test\ticket112.prg.
If the main window appears nearly in full size, than this is the
intermediate solution.

• parentHandle - handle of a parent window;
• handle - handle of a current control;
• lNext - .T., if a next control is demanded, .F. - if the previous;
• Return value - handle of a next or previous control.

• ptr - a variable of Pointer type;
• Return value - long integer.

Change directory:
Harbour function ft_chdir() only available Harbour 3.4 and up,
so this function is instead OK for all platforms
and Harbour 3.2 and up.

To supply a Harbour Terminal/Console application with this function,
add following code into one of your *.prg file (inline C implementation):

#pragma BEGINDUMP


#if defined(__linux__) || defined(__unix__)
#include <:unistd.h>
#else
#ifdef __APPLE__
#include <unistd.h>
#else
#include <io.h>
#endif
#endif

#include "hbapi.h"
#include "hbapifs.h"

HB_FUNC( HWG_CHDIR )
{
hb_retl( HB_ISCHAR( 1 ) && chdir( hb_parc( 1 ) ) );
}

#pragma ENDDUMP

This is checked on LINUX and MacOS with GCC,
Windows with MinGW and BCC.
Ignore warning with BCC:
Call to function 'chdir' with no prototype in function HB_FUN_HWG_CHDIR
Not checked on other Compilers (Pelles C, ...)
We will add the test results as soon as possible)
==> find this sequence in sample program "demofunc.prg"
and test program "test/test_origin_cons".

• cCommand - a command line to execute;
• cOutFile - optional parameter, a file name for program output;
• Return value - (integer) program exit code.

lshow :
(Windows only, this parameter ignored on other operating systems)
Set to .T., to set STARTUPINFO.wShowWindow to SW_SHOW.
Default is .F., set to SW_HIDE.
SW_SHOW is needed for programs, starting in console mode,
but opens child window(s). Otherwise they are running
in background. For example:
Running ZBar (QR decoder reading QR codes from camera)
the sub window does not appear if SW_HIDE,
so cannot use the camera for scanning QR code.
See sample program and information.

Exit codes WinAPI:
1: Cannot create output pipe
2: Failure of: Ensure the read handle to the pipe for STDOUT is not inherited
3: Cannot create process
otherwise:
Return code of GetExitCodeProcess() function call.
Attention !
Do not call internal commands of the command shell "cmd"
(for example cmd -c "dir") direct, otherwise the program freezes, so it must be terminated by.
the Task Manager.

Exit Codes UNIX/LINUX/MacOS:
0: Success
-1: no file to run

• cCommand - a command line to execute;
• Return value - (integer) program exit code.

For details read instructions in sample program tststconsapp.prg,
it demonstrates the usage of
- hwg_RunApp() (async mode)
- hwg_RunConsoleApp() (sync mode)
- hwg_RunConsApp() (async mode, GTK)
- hwg_ShellExecute() (under construction, will be added later)
Be pleasant, to try, what is the best for your HWGUI application.

  Here a code sample snippet to read a text file:
  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  LOCAL lEOF, arrrea
  lEOF := .F.
  * Open the input text file
  handle := FOPEN("textfile_Win.txt",0)
  * read the input file
  DO WHILE .NOT. lEOF
    arrrea := hwg_RdLn(handle)
    * Detect EOF
    IF arrrea[2]
     lEOF := .T.
    ELSE
     * Process data read delivered in arrrea[1]
     * ...
    ENDIF
  ENDDO
  FCLOSE(handle)
  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For debugging purposes:
Returns string "NIL" or "not NIL",
if parameter xParchk is NIL or not.
For usage in combination with hwg_WriteLog() to
write value(s) into a log file.

For debugging purposes:
Returns string ".T." or ".F.",
if logical parameter ltoCheck is true or false.
For usage in combination with hwg_WriteLog() to
write value(s) into a log file.

For debugging purposes:
Displays with a messagebox if oObj is an object or not.
("Is object" or "Is not an object")
The condition for "IF" command to check for a valid object is:
IF Valtype(oObj) == "O"
...

Converts double (8 bytes) to
Numeric Value.
Parameters:
cbin : Hex value of binary
(double 8 bytes => 16 hex characters)
Size 16 Bytes with or without blanks in one line.
nlen : number of digits
ndec : number of digits after decimal point

Sample call:
hwg_Bin2D(hwg_HEX_DUMP(Buffer,0),10,2)
Buffer is the 8 bytes of double var memory.

For usage sample look into source code file
utils\devtools\memdump.prg

Converts double (8 bytes) to
Numeric Value.
Only for internal usage.
This function is called by
hwg_Bin2D().

Add file extension "cext",
if not passed with "cfilename".
If cext is NIL, original name is returned.
Pass "cext" without previous ".".
It is recommended, to pass cext in lower case.
lcs : Set to .T., if case sensitive.
This is recommended for LINUX/UNIX.
On Windows set to .F. (Default).
For example:
 #ifdef __PLATFORM__WINDOWS
  lblname := hwlabel_addextens(lblname,"lbl")
 #else
  lblname := hwlabel_addextens(lblname,"lbl",.T.)
 #endif

This function is very useful, if you want to query a new file name for storing.
For example for *.prg:
#ifdef __GTK__
fname := hwg_SelectFileEx(,,{{ "XBase source code( *.prg )","*.prg" },{ "All files" ,"*"}} )
#else
fname := hwg_SaveFile( "Enter name of new file","XBase source code( *.prg )","*.prg",,"Save File" )
#endif
After query, add the extension "prg" corresponding the sample above.

Replace all leading blanks with
"0". ce : string
Returns : String

Returns the Euro currency sign (€) in UTF-8 code.
0xE2 + 0x82 + 0xAC = CHR(226) + CHR(130) + CHR(172)
On Windows 10 the Euro sign is CHR(128) = 0x80

This functions returns .T., if the used Harbour Version
supports the Euro currency sign (€) on Windows.
In this case, the following code page must be requested:
 REQUEST HB_CODEPAGE_DE858
If for example your datebase uses a Euro currency sign, you
can set this codepage at opening time of a database with
the USE command.
The UTF-8 codepage supports forever the Euro currency sign.

Use the compiler switch to REQUEST the
codepage, if available in used Harbour version
like this sample code snippet:
#if ( HB_VER_REVID - 0 ) >= 2002101634
* 858 : same as 850 with Euro Currency sign
 REQUEST HB_CODEPAGE_DE858
#endif

But it is sometimes possible,
to handle the Euro currency sign
without support of Harbour.
For details read instructions in
comment lines of sample program
"samples\demostrrev.prg".

Returns the linked in GUI type as string,
return values are:
"WinAPI"
"GTK2"
"GTK3"

Returns the type of a variable or expression:
"A", "L", "N", "C", "D", "O", "P", "U"
("P" = pointer, "U" = NIL)

Converts the value of xxx to string, dependant of type.
This function may be helpful for debugging.

Starts a messagebox to display a value of xxx.
The displayed values are simular to function "hwg_xvalLog()"
This function may be helpful for debugging.
The header texts written to message:
cttype : default is "Type : "
cttval : default is "Value : "
cttitle: default is "Debug"

Additional info for debugging:
On GTK/Linux you can use the function QOUT()
to display values of variables in the terminal,
where the program is started.
On Windows, these outputs are not visible.
So these functions for debugging are helpful on Windows.

Writes a value of xxx into a log file.
This function may be helpful for debugging.
The default file name is "a.log".
If you don't know the type of a variable passed to a function
(for example to STR() ) and you want to investigate the reason for a crash like this sample:

  Error BASE/1099 Argument error: STR
  Called from ->STR(0)
  Called from source\winapi/hprinter.prg->HPRINTER:SAY(416)
  ...
then the argument passed to STR() is not of type N.

Expected values in logfile:
  Type : U Value : NIL
  Type : A Value : <ARRAY>
  Type : L Value : .T.
  Type : N Value : 12345
  Type : C Value : Test
  Type : D Value : 20220627
  Type : O Value : <OBJECT>
(This is the output written to logfile by test program "test/xval.prg")

Parameters cttype,cttval and cttitle same as hwg_xvalMsg(),
but written into logfile.

The compilation of this expression (for example)
IIF(nbChecked==0, oStatus:SetText(""),.t.)
throws the following warning:
Warning W0027 Meaningless use of expression 'Logical'
and the program freezes.
So modify to:
IIF(nbChecked==0,oStatus:SetText(""),hwg_nothing(.t.) )

Internal: Needed by HAlert class

Internal: Needed by HAlert class

Table: Temperatures equation list

Building rule for function names
for temperature conversion functions:
hwg_TEMP_<k1>2<k2>
k1,k2: Abbreviation see table above

Constants in formulas:
9/5 = 1.8
9/4 = 2.25
10/8 = 1.25

C=Celsius K=Kelvin F=Fahrenheit RA=Rankine R=Réaumur

hwg_TEMP_C2F( T )
hwg_TEMP_C2K( T )
hwg_TEMP_C2RA( T )
hwg_TEMP_C2R( T )
hwg_TEMP_K2C( T )
hwg_TEMP_K2F( T )
hwg_TEMP_K2RA( T )
hwg_TEMP_K2R( T )
hwg_TEMP_F2C( T )
hwg_TEMP_F2K( T )
hwg_TEMP_F2RA( T )
hwg_TEMP_F2R( T )
hwg_TEMP_RA2C( T )
hwg_TEMP_RA2F( T )
hwg_TEMP_RA2K( T )
hwg_TEMP_RA2R( T )
hwg_TEMP_R2C( T )
hwg_TEMP_R2F( T )
hwg_TEMP_R2K( T )
hwg_TEMP_R2RA( T )

A collection of important unit conversion functions for real life.
(both directions)

=== in / cm ===
hwg_INCH2CM( I )
hwg_CM2INCH( cm )

=== feet / m ===
hwg_FT2METER( ft )
hwg_METER2FT( m )

=== mile / km ===
hwg_MILES2KM( mi )
hwg_KM2MILES( km )

=== sqin / sq cm ===
hwg_SQIN2SQCM( sqin )
hwg_SQCM2SQIN( sqcm )

=== sqft / sq m ===
hwg_SQFT2SQM( sqft )
hwg_SQM2SQFT( sqm )

=== usoz / c.c. (Cubic cm) ===
hwg_USOZ2CC( usoz )
hwg_CC2USOZ( cc )

=== usgal / litre ===
hwg_USGAL2L( usgal )
hwg_L2USGAL( l )

=== lb / kg ===
hwg_LB2KG( lb )
hwg_KG2LB( kg )

=== oz / g ===
hwg_OZ2GR( oz )
hwg_GR2OZ( gr )

=== Nautical mile / km ===
hwg_NML2KM(nml)
hwg_KM2NML(km)

• (set it with command "SET CENTURY ON|OFF")
• .F. : OFF
• .T. : ON

• filename : Full filename and path for bitmap file to create, with extension ".bmp"
• fileoffset_to_pixelarray : Start position of image data in bytes (must be >=54)
• bmp_height : Image height in pixels
• bmp_width : Image width in pixels
• bmp_bit_depth : Number of bits per pixel
• colors : Number of colors in the image
• xpixelpermeter : Vertical resolution in pixels per meter
• ypixelpermeter : Horizontal resolution in pixels per meter

• 2835 in DPI: 72 (Default value)
• 3780 in DPI: 96 (recommended value)

Save a bitmap in an bitmap object into a file.
- oBitmap : The bitmap object
- coutfilename : The file into the bitmap saved,
cbmpname is the unique name of the bitmap written to file,
Is mandatory, otherwise the bitmap is not processed.
Also the cbmpname is case sensitive.
We stricly recommend to use only pure ASCII charset and
lower case (UNIX/LINUX) for the cbmpname.
    pass complete with extension .bmp
    (Default is bitmap.bmp)
Returns forever NIL.

nnn)
 Default is "name"
nnn starts with 1 from program start.
This function may have a little more
performance than a random generating
function.
Use it for creating masses of bitmaps,
like lot's of QR codes.
Some more alternative usages:
- If cprefix is passed with an empty string "",
    you can realize a simple counter, starting
    with 1 at program start.
- For debug purposes, count how often a function is called.
For usage see test program
    test\testunique.prg

hwg_Stretch_BMP_i(cbmp, clocname, nWidth, nHeight )
Stretch a bitmap from binary string image
(independant, without needing a device context)

cbmp : The binary image of a bitmap as string
clocname : The name of the bitmap ( of cbmp )
nWidth, nHeight : The size parameters.
To Respect the size ratio use focus values (nfocus).
for example :
nWidth := nfocus * nWidth
nHeight := nfocus * nHeight

Returns the resized bitmap as string,
If error, empty string "" is returned.
nWidth and nHeight both must be > 0,
otherwise the original bitmap is returned.
This function is important for WinAPI,
but works also with GTK.
For GTK use for better performance the resizing feature
of GTK, for example
METHOD AddString()
(but has no resizing feature on WinAPI,
see HWGUI class documentation of HBITMAP.

long cxdib_Stretch( PCXDIB pdib, HDC pDC, long xoffset, long yoffset, long xsize, long ysize )
of cxshade.c (WinAPI) needs a device context,
so it is not useful for pure resizing of a bitmap.

For lot's of details about resizing (stretching) of bitmaps,
read the comment lines in sample program "stretch.prg".

hwg_bpmObj2String(obmp,cname)
extract the a bitmap string from an
bitmap object.
(for example to display it)
obmp : The bitmap object
cname : The bitmap name
Returns the string image,
in case of error an empty
string (check for success by for example)
EMPTY(cBitmap)

hwg_BMPRename(oBitmap,cnamold,cnamnew)
Renames a bitmap in an bitmap object
oBitmap : The bitmap object
cnamold : The old bitmap name
cnamnew : The new bitmap name
Returns the new bitmap object with
the renamed bitmap.

This function is useful, if
a bitmap is stored in a tempory file
and must be read after resizing,
so it becomes the previous name.
For details see sample program
"stretch.prg"
with lots of comments.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Some debug helpers for bitmap programming
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

hwg_bitmapTOC(oBitmap)
Returns a table of contents (TOC) of a bitmap object (name's) in an array

BMPSize2Logfile(oBitmap,name)
Write the bmp size (height and width)in the log file a.log .
oBitmap : The bitmap object
name : The bitmap name

hwg_Debug_logarrayC(acarray)
Only for debug purposes:
Write a single dimension array with c values into logfile.

2.) Add this sample function code into your HWGUI application code:

Write TOC of bitmap to logfile:

FUNCTION BMPTOC2Logfile(oBitmap)
LOCAL atoc
atoc := hwg_bitmapTOC(oBitmap)
hwg_Debug_logarrayC(atoc)
RETURN NIL
IF .NOT. hwg_is_object(oBmp)
hwg_MsgStop("oBmp is not an object!","Error")
ENDIF

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
End of Functions for raw bitmap support
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

QR code functions

Advice:
QR codes are mainly standisized by JIS X 0510 (Japanese Industrial Standard)
and ISO/IEC 18004:2006.
QR codes are operating with UTF-8 charset.
On Windows, which not origin supports UTF-8,
use compiler switch to insert the translation
sequence following this example:

#ifdef __PLATFORM__WINDOWS
   * Convert to UTF-8
   * Set "DEWIN" to your language setting on Windows
   ctext := HB_TRANSLATE(ctext, "DEWIN" , "UTF8")
#endif

Also you need to request the needed codepages
in the MAIN section, corresponding the code sample above:

* Windows codepage
REQUEST HB_CODEPAGE_DEWIN
* Forever needed
REQUEST HB_CODEPAGE_UTF8

REQUEST HB_CODEPAGE_UTF8EX

The reverse translation is needed for the
QR code decoding sequence.


More non standard QR codes are existing. They are not supported.
Also inverted (negative) QR codes are not recognized.


Here an example for a standard QR code with the URL to the HWGUI project site:



All functions start with prefix "hwg_QR".

QR code encoding

The encode functions need an external library, instructions to
integrate into HWGUI see file contrib\qrencode\Readme.txt.
Please respect the copyright notes of external libraries.

QR code decoding

The encode functions need an external library, instructions to
integrate into HWGUI see file contrib\qredcode\Readme.txt.
Please respect the copyright notes of external libraries.

For decoding QR codes from camera, you need on all platforms the
Open Source package "ZBar".
The version 0.10 is available on the HWGUI project site in the "Files" section
under: contrib/qrdecode/
It works at it's best and can also decode many bar codes.
For Windows, a ready to install setup archive is there available.
On MacOS, an additional shell script and another program "imagesnap" is needed,
so look into the ReadMe.txt file for detailed instructions.
To compile the ZBar package from source, a code patch is needed.

Format description

The encoding function hwg_QRCodeTxtGen() returns a pure text image,
where a blank " " represents a white pixel and the "#" a black pixel.
The lines ends with a UNIX/LINUX line ending.
For example:

In this state, the image can be processes with the hwg_QR... functions.
Finally, the QR code text image must be converted to a binary bimap image by
calling the function hwg_QRCodetxt2BPM().

HWG_QRENCODE(ctext [, nzoomf] [,nboarder] )
Creates the QR code and convert it to bitmap binary image of type C.
Function to call from main or other functions starting the encode action.
It is the "user interface".
Returns the bitmap binary image of type C.
Not to be used with DLL (for example Borland C).

ctext      :    The text to convert to QR code
nzoomf     :    The zoom factor, default is 3
nboarder   :    The boarder in pixels, default is 10.
                This value is strictly recommended for successfull scans.

This function is not included in the main HWGUI source,
find it in
contrib\qrencode\libqrencode.prg

hwg_CBmp2file(cbitmap,cbitmapfile)
Write the bitmap binary image of type C to file,
for example returned by HWG_QRENCODE().

cbitmapfile : The bitmap file name containing the QR code, with extension ".bmp"

For compatibilty with UNIX/LINUX and MacOS,
use file name always in lower case.

hwg_QRCodeTxtGen(ctext,<border>)
Converts a string ctext into a
QR code text string,
needed character set is UTF-8.
If the operating system does not support
UTF, convert it with function
HB_TRANSLATE().
border: Number of pixel of the
desired (white) border in pixels.
Default value is 4.
For usage see sample program
samples\qrencode.prg.
This function is part of the interface module, all
other functions for QR encoding are part of the HWGUI base libraries.

hwg_QRCodetxt2BPM(cqrcode)
Encode QR code (text format) to bitmap
cqrcode : The text string to encode to
a bitmap.

hwg_QRCodeZoom(cqrcode,nzoom)
Increases the size of a QR code image
cqrcode : The QR code in text format
nzoom : The zoom factor 1 ... n
Returns the new QR code text string.

Important advice:
This function needs some CPU time to finish calculation.
We recommend, not to use a zoom factor
greater than 3 or 4.

hwg_QRCodeZoom_C(cqrcode,nlen,nzoom)

Only experimental status !!

This is the eqivalent function to hwg_QRCodeZoom().
Detected by some tests, the code effeciency is not signficant better than
hwg_QRCodeZoom() (about 10 % faster). This fact shows, that the Harbour compiler creates very
effective code !
cqrcode : The QR code in text format
nlen : Pass LEN(cqrcode)
nzoom : The zoom factor 1 ... n, the default is 1 (no zoom)
There are some limitations caused by the buffer size of the internal string buffer (16 kByte).
A NULL byte at end of every line do not cause trouble creating the bitmap
with hwg_QRCodetxt2BPM().

hwg_QR_SetPixel(cmbp,x,y,xw,yh)
Set a single pixel into QR code bitmap string.
Background color is white, pixel color is black.

hwg_QRCodeAddBorder(cqrcode,nborder)

Add border to QR code image.
cqrcode : The QR code in text format
nborder : The number of border pixels to add 1 ... n
Returns the new QR code text string.
For best performance call this function after hwg_QRCodeZoom()

hwg_QRCodeGetSize(cqrcode)

Get the size of a QR code in text format "cqrcode"
Returns an array with 2 elements: xSize,ySize.

References

   [1] Spence, Rick (Co-Developer of Clipper):
       Clipper Programming Guide, Second Edition Version 5.
       Microtrend Books, Slawson Communication Inc., San Marcos, CA, 1991
       ISBN 0-915391-41-4

   [2] Project CLLOG at Sourceforge:

       https://sourceforge.net/projects/cllog/

---

prev	table of contents	next
commands		classes