User Guide for GUI Library
==========================

Overview
--------

  The GUI library is a user interface library that is designed to provide
a common API (Application Programmer's Interface) across several platforms.
The API most closely resembles the API, messaging and callback structure
used by Windows. This library is intended for internal WATCOM use.

Platforms
---------

    The operating systems currently supported are :

Character based :

DOS  (16-bit, Pharlap, DOS4G)
OS/2 (16- and 32-bit)
QNX  (16- and 32-bit)
WIN  (16-bit)
NT

Graphical :

Windows
NT
PM (16- and 32-bit) (not yet completed)

Operating systems that are intended to be supported are :

Graphical :

QNX/Windows (maybe, if demand and time exist)

  There is another library, known as AUI, which can be used in conjunction
with the GUI library.  It provides additional support for windows that
implement text display and selection.

Location
--------

  The GUI library is found on the network under cproj/gui.  The AUI library
  is found under /cproj/aui.

Functionality Provided
----------------------

  The GUI library allows the application program to create windows and process
messages, including user input message, corresponding to those windows.
The windows can display text, have menus, have floating popup menus,
display messages in message boxes and create dialogs.  The GUI library also
allows the creating of toolbars (floating and fixed) and different fonts (in
graphical environments). Controls may be created on windows (as opposed
to controls on dialogs) on all platforms.  In Windows and NT, although,
putting a group box in a window will not give good results when painting. 

* = for character mode only
+ = for graphical mode only

Functions not implemented for a certain mode will be politely stubbed out.
Use the GUIIsGUI call to determine mode.

General Information
-------------------

    Data passed in to GUI functions is not assumed to exist past when the
function call returns.  The exception to this is the 'hinttext' field of
the gui_menu_struct.  A copy of this char * is retained.  This is done to
avoid wasting memory.  When GUISetHintText is called, that char * is retained
and any previous hint text for that menu item is no longer assumed to exist.

    When the GUI library returns a piece of text, it has been allocated using
GUIAlloc and must be freed by the application.  When a buffer and length
are passed in to the GUI function, the buffer will be filled, up to length
characters, and the GUI library will not allocate any memory.  Examples
of functions which allocation memory which must be freed by the application
are : GUIGetText, GUIGetListItem, GUIGetFontInfo, GUIGetFontFromUser.  Text
is written to an existing buffer in such calls as GUIGetWindowText.

API
===

Getting Started
---------------

 The following are initialization functions :

GUIWndInit 		-- must be called first to initialize the library
GUIGMouseOn*		-- enable graphics mouse and character mapping (DOS only)
GUIGMouseOff*		-- disable graphics mouse and character mapping (DOS only)
GUIMDIInit		-- initialize MDI code***
GUI3DDialogInit+	-- initialized 3D-look controls in dialogs in Windows**
GUISetBetweenTitles*	-- set the number of characters between mail menu titles
GUIGetRoundScale	-- ask for information about choosing a good scale
GUISetScale		-- allows the user to set the scale (screen coordinates)
GUIGetScale		-- get the scale (as was set with GUISetScale)
GUISetDClickRate	-- set the double click rate for mouse
GUISetCharacter*	-- set a character used for drawing windows
GUIGetCharacter*	-- get a character used for drawing windows

** this function causes the app to need ctd3d.dll to be in the path when
   it is executing.  It is found in the /lang/binw directory.

Window Creation 
---------------

GUICreateWindow 	-- create a window
GUIAddControl		-- add a control to a window.  Do not add a group box
			   to a window in graphical systems
GUIDeleteControl	-- delete control from a window or dialog.
GUISetExtra		-- set data associated with window.  For your use only.
GUIGetExtra		-- get pointer to data associated with window

Window Functions
----------------

GUISetWindowText	-- reset the text which is the window title
GUIGetWindowTextLength 	-- gets the length of a windows title
GUIGetWindowText	-- copies a windows title to a buffer supplied

GUIDestroyWnd		-- destroy the window.  Passing NULL will destroy all
			   windows

dirty functions :

GUIWndDirty		-- tell library that a whole window is dirty
GUIWndDirtyRow		-- tell library that a row of a window is dirty
GUIWndDirtyRect		-- tell library that a rect in a window is dirty
GUIRefresh		-- tell library to refresh the screen
GUIWndUpdate*		-- tell library to update a window
GUISetBackgroundChar*	-- set the character user to draw the background of
			   the main window

focus functions :

GUIBringToFront 	-- bring the window to the top of all others
GUIGetFront		-- returns window that is on top of all others
GUIGetNextWindow	-- returns window that is below given window in z-order
GUISetFocus		-- set input (keyboard) focus to a window
GUIGetFocus		-- find out which window has the focus

resize functions :

GUIResizeWindow		-- give a window a new size (and location)
GUIMinimizeWindow	-- minimize a window
GUIIsMinimized		-- returns TRUE if window is minimized
GUIMaximizeWindow	-- maximize a window
GUIIsMaximized		-- returns TRUE if window is maximized
GUIRestoreWindow	-- restore a window to pre-minimize or maximize size
GUIHideWindow		-- Hide a window
GUIShowWindow		-- Show a window previously hidden

drawing functions :

GUIDrawRect 		-- draw the outline of a rectangle given a gui_attr
GUIDrawRectRGB+		-- draw the outline of a rectangle given an RGB
GUIFillRect 		-- draw a filled in rectangle given a gui_attr
GUIFillRectRGB+		-- draw a filled in rectangle given an RGB
GUIDrawLine		-- draw a line given a gui_attr and style information
GUIDrawLineRGB+		-- draw a line given an RGB and style information
GUIDrawText		-- draw text at a row and indent.  Indent is in user
			   coordinates.
GUIDrawTextPos		-- draw text at a point
GUIDrawTextExtent	-- draw text at a row and indent, blanking a portion
			   of the screen to the right of the text as if it
			   were spaces.  Indent is in user coordinates.
GUIDrawTextExtentPos	-- draw text at a point, blanking a portion of the
			   screen to the right of the text as if it were
			   spaces

information functions :

GUIGetClientRect	-- get the size and location of the window's client
			   area in absolute user defined units
GUIGetAbsRect		-- get the window's size and location in absolute
			   user defined units
GUIGetRect		-- get the window's size and its location relative
			   to its parent.  If there is no parent,
			   GUIGetRect and GUIGetAbsRect will return the same
			   value.
GUIGetScrollStyle 	-- get the scroll style (set on creation)
GUIGetCreateStyle	-- get the creation style (set on creation)


Colour Functions
----------------

GUISetBackgroundColour*	-- set the background colour of the main window
GUISetDialogColours*	-- set the main and border colours of dialogs
GUISetWindowColours	-- set the colours for a window
GUIGetNumWindowColours	-- find the number of colour attribute a window has
GUIGetWindowColours	-- get a copy of the colours of a window
GUISetRGB+		-- set the RGB value for a certain gui_colour
GUIGetRGB+		-- get the RGB value for a certain gui_colour
GUIGetWndColour		-- get the colour of a certain gui_attr for a window
GUISetWndColour		-- set the colour of a certain gui_attr for a window
GUIGetRGBFromUser+	-- create dialog to ask user for colour, return it's RGB
GUIGetColourFromUser	-- create dialog listing names of colour for user to
			   choose from

Cursor Functions
----------------

GUIGetCursorPos*		-- get the position of the window's cursor
GUISetCursorPos*		-- set the position of the window's cursor
GUIGetCursorType*		-- get cursor type (none, normal, insert)
GUISetCursorType*		-- set cursor type (none, normal, insert)
GUISetMouseCursor+		-- set the type of mouse cursor
GUIResetMouseCursor+		-- reset the type of mouse cursor
GUIMouseCursorNeedsReset+	-- check if the type of mouse cursor needs to
				   be reset
Font Functions
--------------

GUIFontsSupported	-- returns TRUE if these font functions are supported
GUIChangeFont+		-- gets font choice from user and changes the font of
			   the given window
GUIGetFontInfo+		-- get the font information for a window
GUISetFontInfo+		-- sets the font information for a window
GUIGetFontFromUser+	-- gets font information from the user (using a dialog)
GUISetSystemFont	-- set font to system font (fixed or proportional)

General Information Functions
-----------------------------

GUIIsGUI		-- returns TRUE if on a graphical OS, FALSE otherwise
GUIGetMousePosn		-- get the mouse position (in user coordinates)
GUIGetKeyState		-- get the current shift state
GUIGetSystemMetrics	-- get system dependent size information
GUIGetMinSize		-- get the smallest valid size for a window
GUIEnumChildWindows	-- enumerate child windows by calling given function
			   with the gui_window * for each
GUIEnumControls		-- enumerate controls on a window by calling given
			   function with the id for each control

Text Functions
--------------

GUIGetRow		-- return which text row is at the given mouse point
GUIGetCol		-- find offset (in characters) of the given point
GUIGetStringPos 	-- find offset (in characters) of the given point if
			   string is offset from left by given amount

GUIGetExtentX		-- find x extent of given string (in current font)
GUIGetExtentY		-- find y extent of given string (in current font)
GUIGetTextMetrics	-- get the metrics of the current font
GUIGetDlgTextMetrics	-- get the metrics of the dialog font

GUIGetPoint		-- return the point address of given text row and col

Menu Functions
--------------

GUICreateFloatingPopup	-- create a floating popup menu
GUITrackFloatingPopup   -- track a floating popup menu created using GUIAppendMenu
			   and GUIAppendMenuToPopup with floating set to TRUE
GUIEnableMenuItem	-- enable/disable a menu item
GUICheckMenuItem	-- check/uncheck a menu item
GUISetMenuText		-- change text of menu item
GUISetHintText		-- set the hint text for a menu item

GUIEnableMDIMenus	-- enable/disable a the MDI menus
GUIEnableMenus		-- enable/disable all menus // NYI
GUIDeleteMenuItem	-- delete a menu item from a pull down menu

GUIResetMenus		-- reset the entire menu structure for a window

GUIInsertMenu		-- insert menu item before given offset (top level)
GUIInsertMenuByID-- insert menu before given id
GUIAppendMenu		-- append menu to top level menus
GUIAppendMenuByOffset	-- append menu to submenu indicated by offset
GUIAppendMenuToPopup	-- append menu to a popup menu indicated by id

Toolbar Functions
-----------------

GUICreateToolBar 	-- create a toolbar
GUICloseToolBar 	-- close the toolbar
GUIHasToolBar 		-- check if a window has a toolbar
GUIChangeToolBar 	-- change the toolbar (fixed->floating or floating->fixed)
GUIToolBarFixed 	-- returns TRUE if the toolbar is fixed

Status Window Functions
-----------------------

GUICreateStatusWindow	-- create a status window
GUICloseStatusWindow	-- close the status window
GUIHasStatus		-- check if a window has a status window
GUIDrawStatusText	-- draw text to the status window
GUIResizeStatusWindow	-- resize the status window

Scroll Functions
----------------

In the name of the function, words have the following meanings :

Init 		- set value, don't draw anything
Set  		- set value, do scrolling indicated
Get  		- just return current value
Do  		- just do scrolling, don't touch value
Thumb		- does an init

These are Row/Col functions.  They deal in character units :

GUIInitHScrollCol	-- set horizontal scrolling position
GUIInitVScrollRow	-- set vertical scrolling position
GUISetHScrollCol	-- set horizontal scrolling position, do scrolling