guide.doc

开放源码的编译器open watcom 1.6.0版的源代码

GUISetVScrollRow	-- set vertical scrolling position, do scrolling
GUIGetHScrollCol	-- get horizontal scrolling position
GUIGetVScrollRow	-- get vertical scrolling position
GUISetHScrollRangeCols	-- set horizontal scrolling range
GUISetVScrollRangeRows  -- set vertical scrolling range
GUIGetHScrollRangeCols	-- get horizontal scrolling range
GUIGetVScrollRangeRows	-- get vertical scrolling range
GUIDoHScroll		-- do horizontal scrolling
GUIDoVScroll		-- do vertical scrolling
GUIDoHScrollClip	-- do horizontal scrolling, clipping to a region
GUIDoVScrollClip	-- do vertical scrolling, clipping to a region

These are Thumb functions.  They deal in percent of range :

GUISetHScrollThumb 	-- initializes the horizontal thumb position (percent)
GUISetVScrollThumb 	-- initializes the vertical thumb position (percent)

These functions work in terms of the units of the user defined scale :

GUIInitHScroll		-- set horizontal scrolling position
GUIInitVScroll		-- set vertical scrolling position
GUISetHScroll		-- set horizontal scrolling position, do scrolling
GUISetVScroll		-- set vertical scrolling position, do scrolling
GUIGetHScroll		-- get horizontal scrolling position
GUIGetVScroll		-- get vertical scrolling position
GUISetHScrollRange	-- set horizontal scrolling range
GUISetVScrollRange	-- set vertical scrolling range
GUIGetHScrollRange	-- get horizontal scrolling range
GUIGetVScrollRange	-- get vertical scrolling range

GUIGetNumRows		-- get number of text rows that will show in the
			   window

Sizzling Hot Spot Functions
---------------------------

GUIInitHotSpots		-- set the character/bitmaps associated with user defined
			   hot spots
GUIGetNumHotSpots	-- return the number of hot spots defined
GUIGetHotSpotSize	-- get the size (in user coords) of a certain hot spot
GUIDrawHotSpot		-- draw a hot spot at a given location

Spawn Functions
---------------

GUISpawnStart		-- start a spawn
GUISpawnEnd		-- end a spawn

Other Functions
---------------

GUITruncToPixel		-- truncate location (in user coordinates) to nearest pixel
GUIFlushKeys		-- flush the keyboard buffer

High Level Interactions
-----------------------

GUIDisplayMessage 	-- display message and get response (like Windows)
GUIGetNewVal		-- display old value, ask user for new value
GUIGetFileName		-- get file name using common file dialog.  See
			   guifdlg.h or a Windows manual for more information.
GUIDlgPick		-- display choices in list box, have user pick
GUIDisplayHelp+		-- display windows help for a given topic

Dialog Box Functions
--------------------

GUICreateDialog		-- create a dialog
GUICreateSysModalDialog -- create a system modal dialog box ( same as
			   GUICreateDialog in char-based systems )
GUICloseDialog		-- close a dialog
GUIDlgOpen 		-- calls GUICreateDialog, formatting locations to
			   look good in every OS. Takes coordinates in
			   character units.  See guindlg.h for more information.

The following functions work with controls in dialogs.  On Windows and NT,
they also work with controls on windows.

For all controls :

GUIGetControlRect	-- get location of control, relative to parent
GUIResizeControl	-- set size and location of control (relative to
			   parent)
GUIGetControlClass	-- get the gui_control_class for the given control (by id)
GUIIsControlEnabled+	-- returns TRUE if control is enabled
GUIEnableControl+	-- set control enabled or not enabled
GUIHideControl+		-- hide a control
GUIShowControl+		-- show a control
GUIIsControlVisible+	-- returns TRUE if control is visible

List box functions :

GUIAddText		-- add a text item to list
GUISetListItemData+	-- associate data with a list box item
GUIGetListItemData+	-- get the data associated with a list box item
GUIAddTextList		-- add a list of text to list using callback
GUIClearList		-- clear the list
GUIDeleteItem		-- delete an item from a list
GUIGetListSize		-- get number of elements in list
GUIGetCurrSelect	-- get the position of the current selection
GUISetCurrSelect	-- set the current selection by position
GUIGetListItem		-- get the text of a list item by position
GUIDropDown+		-- drop down or raise dropped-down list box
GUIInsertText		-- insert a text item to given location is list
GUISetTopIndex		-- scroll list so given index is at top of list
GUIGetTopIndex		-- get index of item at top of list (-1 if no items)
GUISetHorizontalExtent+ -- set the width of the widest list box item

Functions that work for all controls with text :

GUISetText		-- set the text
GUIClearText		-- clear the text
GUIGetText		-- get a copy of the text
GUISelectAll+		-- select the text (GUI_EDIT and GUI_EDIT_COMBOBOX)
GUISetEditSelect+	-- select portion of text
			   (GUI_EDIT and GUI_EDIT_COMBOBOX)
GUIGetEditSelect+	-- find out the portion of text selected
			   (GUI_EDIT and GUI_EDIT_COMBOBOX)
GUIDlgBuffGetText 	-- get text from control into a buffer

Check box and radio button functions :

GUIIsChecked		-- find of if button (on dialog) is checked or not
GUISetChecked		-- set button (on dialog) as checked or not


Memory routines
---------------

- used to track memory.  Set environment variable TRMEMFILE to the file
  which will contain memory tracking information.
- compile with TRMEM defined (default in GUI makefiles) (see notes for
  compiling below)

GUIAlloc		-- cover function for alloc
GUIFree			-- cover function for free
GUIRealloc		-- cover function for realloc
GUIMemOpen		-- initialize memory tracker
GUIMemClose		-- close memory tracker
GUIMemPrtUsage		-- print current memory usage


Directory structure
-------------------

gui/h - gui.h, guitypes.h, guifdlg.h and guidlg.h are intended to be included
 	by the user.

	- gui.h contains the messages, structs and API that you need
	  to get you started

	- guitypes.h contains common typedefs and constants (bool, TRUE, etc.).
	  You may want to include this if you're not defining these types
	  for yourself.

	- guifdlg.h contains the prototypes that you need to call the common
	  file dialog (as in Windows)

 	- guidlg.h contains some macros and API to make creating dialogs
	  easier

gui/ui - contains libraries to be used for character based platforms
	  (DOS, QNX, OS2, WIN and NT character based).
	- libraries created are :

	Library		OS		Memory Model	Directory 	16/32
	-------		--		------------	---------	-----

	guidosm.lib  	DOS		medium		objm		16
	guidosl.lib  	DOS		large		obj		16
	guidosf.lib	Pharlap/DOS4G	flat		objf		32
	guios2l.lib	OS2       	large		obj2		16
	guios2f.lib	OS2V2   	flat		obj2f		32
	guiqnxl.lib	QNX		large		objq		16
	guiqnxs.lib	QNX		small		obj32q		32
	guintf.lib	NT		flat		objnt		32
	guiwinl.lib	WIN		large		objw		16

gui/win - contains libraries to be used for graphical platforms (Windows, NT)
	- libraries created are :

	Library		OS		Memory Model	Directory 	16/32
	-------		--		------------	---------	-----

	guiwinm.lib	Windows		medium		objm		16
	guiwinl.lib	Windows		large		obj		16
	guintf.lib	NT		flat		objnt		32
	guipmf.lib	PM		flat		objpmf		32
	guipml.lib	PM		large		objpm		16

gui/sample - contains sample code and directories to build it in

	- gui/sample/c/sample.c and sampdef.c create a sample program that
	  uses a lot of the functionality of the GUI library.  It includes
	  gui/sample/h/sample.h.

	- gui/sample/obj* directories are set up to compile the sample
	  for several operating systems :

	DOS
	---
	  obj - DOS large memory model
	  objm - DOS medium memory model
	  objf - Pharlap/DOS4G flat memory model

	OS/2
	----
	  obj2 - OS2 16-bit large memory model
	  obj2f - OS2 32-bit flat memory model

	QNX
	---
	  objq - QNX large memory model
	  obj32q - QNX 32 bit small memory model

	Windows
	-------
	  objw - Windows large memory model
	  objwm - Windows medium memory model
	  objwc	- Windows character mode large memory model

	NT
	--
	  objnt - NT flat memory model
	  objcnt - NT character mode flat memory model

	PM
	--
	  objpmf - PM flat memory model
	  objpm - PM large memory model

Notes for compiling :

-- if you want to use the memory tracker, put the trmem project on your
   machine (from n:\utils\trmem) and set the environment variable
   trmem_dir to point to it.  Compile with TRMEM define (default).
-- set the guidir environment variable to point to the gui directory
   before trying to compile
-- you must compile ui and have the environment variable uidir set to point
   to it
-- to compile for graphics Windows or NT, set sdk_dir to point to the sdk
   directory on you machine (from n:\cproj\sdk).
-- ***when using the GUIMDIInit function call, and compiling for a graphical
   system, your app must have a .rc which include the gui.rc file found in
   /gui/win/gui.rc.  The resource compiler must also have the directive
   /i=$(sdk_dir)/misc so that it can find the bitmap indicated in gui.rc.


Messages
--------

typedef struct gui_window gui_window;
typedef bool (GUICALLBACK)( gui_window *, gui_event, void * );

When GUICreateWindow is called, a gui_window * is returned.  This is a struct
private to the GUI library and is used for communication between the
application and the GUI library.  The prototype for the callback routine is
shown above.  When it is called, it will be given a gui_window, an event
and (possibly) a third parameter, depending on the event.  Macros are
provided to extract information from the third parameter.  The following
is a description of the messages.  Descriptions of the macros are found
following the message list.  

Note :	The return codes from processing the following messages are important
	(the rest are ignored) : GUI_INIT_WINDOW and GUI_CLOSE.

typedef enum {
    GUI_NO_EVENT,	
    GUI_INIT_WINDOW,
    ...
    ...
    ...
    GUI_DESTROY     
} gui_event;

GUI_NO_EVENT
 	Never sent to app.  Included because it can be handy for internal use.

GUI_INIT_WINDOW
	This is the first message sent to a window.  If TRUE is returned,
	the creation process continues.  If FALSE is returned, the creation
	process is aborted and all memory for that window is freed.  NULL
	will be returned from the GUICreateWindow call.

GUI_INIT_DIALOG
	This is the first message sent to a dialog.  The app may want to
	initialize the values of controls.

GUI_NOT_ACTIVE
	The window was active but now is not.  Either the user selected
	another window as active through mouse or keyboard input, or
	GUIBringToFront was called for another window.

GUI_NOW_ACTIVE
	The window was not active but is now active.  Either the user
	selected this window through mouse or keyboard input or
	GUIBringToFront was called for this window.

GUI_MOVE
 	This window has just moved, either through user input or a call
	to GUIResizeWindow.

GUI_RESIZE
	The window has been resized, either through user input or a call
	to GUIResizeWindow.
	Macro : GUI_GET_SIZE

GUI_ICONIFIED
	The window has just been iconified.