
GETTING STARTED

Once you have taken a few initial steps, using the library
is very easy and straight forward.

Assumptions:

Linking in Dynamic link libraries (dll) is compiler or 
database application specific.  Virtually all compilers
and database packages can use functions that are contained
in dlls.  We make the assumption that the programmer/developer
is familiar with linking (working) with dlls and can create
a window using their package.  While we cannot provide detailed
instruction on how to link and call functions that are contained
in the dll for every possible compiler or database app that can
use this dll, we do provide guidelines below for some of the 
more popular ones.

If you do not know how to create a window using your package,
we provide code to create a window for those using the Watcom 
compiler only.
While other compilers can use this code to create a window, we
guarantee that it will work with the Watcom compiler.

Again, it is not the goal of this graphics library to teach the
programmer/developer about windows programming, only to provide
a comprehensive graphics toolkit for windows programmers.


And now......

The readme file contains a description of all of the files on the
disk.  First start by running the demos to get an idea of what the
library can do.  Then take a look at the source code to see how
the demos were actually created.  You can follow that by looking
at the complete function list (hds_lib.h) and then the functions
that are included as part of the sample dll (sam_fun.txt).  This 
should give you an idea of how the library works.  

The next step is to actually use the sample library with your package.  
There are a few steps to think about here.  The 2 files that you 
will need are the sample16.dll(win3.1, 95 or NT target) or sample32.dll
(win95 or NT target) and the file that contains the prototypes of the 
functions that you wish to use (hds_lib.h).  A prototype 
describes the name of the function you want to use such as HDS_draw_line 
and the types of the parameters it takes as arguments and the type 
that it returns such as integers, etc.  You only need the prototypes 
for the functions that you wish to use.  The stt variable in this file
was defined as __export FAR CDEDCL for use with the watcom c/c++ compiler
(it is defined in hds_com.h).  Note that almost all database packages 
as well as C/C++ compilers can work with dlls.  Below is a sample 
listing of actual compilers/database packages that we (or our users) 
have been able to link the library in with.  You will notice that there
are also sample16.lib and sample32.lib files.  Most C/C++ compilers can
use these lib files directly without having to create the .lib file from the
dll.  



	Watcom C/C++(tested with 10.5)
		
		To compile the demo sample code with the Watcom compiler
		under the IDE environment, you only need a few steps.
		After selecting the Target environment (either 16 or 
		32 bit exe), you need to include the library and source
		code.  Under the Sources pull down menu select New Source.
		Then type in the name of the dll (sample16.dll for 16bit app
		s or sample32.dll for 32 bit). Next include the source code as a source
		(either sample.c or simple.c source code).  You can also
		specify using sample16.lib or sample32.lib in place of 
		sample16.dll or sample32.dll.

		compile(f4 function key) and run.


	MS Visual C/C++ (tested with 1.52)

		Microsoft folks can use implib.exe (16bit) or the lib.exe
		(for 32bit) programs to import the functions in the dll.
		These build a .lib file from the .dll library.

			implib sample16.lib sample16.dll  (from dos)

		Remember that the prototypes for the functions are contained
		in the file hds_lib.h

	Borland(tested with v3.1)

		From the dll you can create a .lib which then can be 
		linked in.  To create the .lib file from the dll:

			implib.exe sample16.lib sample16.dll

		some versions will be able to use the .lib files that we
		provided without going through this extra step.

		include the source code (either sample.c or simple.c) 
		along with the library.

	Symantec C++(not tested)

		For Symantec you can create the .lib file from the dll
		using the command:	

			implib sample16.lib sample16.dll
		from the DOS command line

	Ca-dbfast

		Declare each function in the dll that you wish to use using
		the Declare statement.  All functions must be declared 
		CFUNCTION type functions.  A return of type void for a 
		function should be declared as an integer.  You can use 
		the function HWND() which gets the handle to the window 
		that Ca-dbfast creates or use one of the libraries functions
		for getting the window handle.


		For Ca-dbfast developers and other data base users who may
		be unfamiliar with some C language variable types or windows
		variable type definitions (such as HWND, HDC ,HBITMAP,etc.),
		we include the chart below.  Note that the definitions are
		dependent on the target platform.  For instance, an int on
		a 16 bit machine is 2 bytes long and on a 32 bit machine it
		is 4 bytes long.


		C syntax	description		windows equivalent

		int		an integer		

		char		character

		long		long int (32bits)	LONG

		unsigned int	unsigned integer(uint)	HANDLE (such as
							  HWND, HDC, and
						          HBITMAP)

		unsigned int	unsigned integer(uint)	WORD

		void		function returns nothing

	But if I can use unsigned integer in place of the type HANDLE
	then what is the purpose of these special types?  The purpose 
	of these special types is to make code more portable between
	various operating systems.  A handle may be of type unsigned
	int on 3.1 but may be something else on an NT machine.  Use of
	these type definitions helps avoid errors and make code more
	portable.  These types are defined in WINDOWS.H header file.
	So, the bottom line is that you should use MicroSoft types 
	whenever possible, and standard type definitions when all else
	fails.

	
	Delphi (1.0 tested): 
		Delphi is not yet supported fully (i.e.
		we do not provide extensive advice on linking and running
		our product with Delphi).  We have had testers use our library
		with Delphi with no problems, though.  The file 
                hds_head.pas is provided as an example of how functions
		in our library would be declared for use with Delphi.
		We do provide full support for the graphics library itself.

------------

Once you have the dll linked in, you're almost there.  Next, you will 
notice that most of the functions in the library need a device context
to draw on (the dc).  We supply a function for just such a purpose
call HDS_getdc, as shown in the sample codes.  It needs as its argument 
the window handle to draw in.
Many applications supply functions for returning the window handle, as 
this is the handle to the window that your application creates.  Once 
you have this window handle, you're home free.  For those who cannot
get the window handle (i.e. Foxpro does not return the handle), we 
supply a few functions that can make this work.

	HDS_get_winhandle_act:  this function will get the window 
		handle of the active windows window (i.e. the one
		that has the focus)

	HDS_get_winhandle_title:  this function will get the window
		handle of the window whose title is given.  For
		example, if you are viewing this file with notepad.exe
		the title of the window may be "Notepad - GET_STR.TXT".

	HDS_get_winhandle_class:  this function is used when you know
		the class of the window as well as the title of the 
		window.


The best scenario is that you get the window handle directly from your
application.  If this is not possible then you can use one of the 3
mentioned functions above.  After that, then using any of the functions
in the library is very simple.   Below is a couple of scenarios similar
to what you would set up to draw a line and a few circles.  This example
is in the C language and your application or language will differ 
slightly.


/* set up a few variables of type unsigned integer */

	HDC    dc_screen; 
        HWND   hwnd;         

/* get the window handle of the window that has as its title the word demo */
	hwnd=HDS_get_winhandle("demo");

/* get the dc which tells where to draw on, passing in the hwnd value we */
/* just got */

	dc_screen=HDS_getdc(hwnd);

/* create the initial color palette */

	HDS_make_master_palette(dc_screen);

/* and now draw to our hearts content */
/* first we draw a line of style 0 (a solid line) 2 pixels thick that has
one end point at the origin (0,0) and the other end point at 100,100.  The
line is draw with the color that is in slot 2 of the master color palette
and is draw on the visible screen).  Remember that the origin (0,0) is at
the top left corner of the window that you are drawing in */

	HDS_draw_line(0,2,5,0,0,100,100,dc_screen);

/* next we draw a filled circle at location 20,10 on the screen */
	

	HDS_draw_fcircle(3,20,10,30,dc_screen);






If your application already has the window handle stored in a variable
name hw for example then you would skip the HDS_get_winhandle call in
the above example and pass that directly to getdc function (HDS_getdc(hw)).



A summary of the steps needed to use the functions in the sample library:

	1)  link in the dll to your code that creates a window
		and declares which functions in the library that
		you will use.
	2)  get the window handle to the window that your application
		creates or use one of the library functions that gets this
		handle.
	3)  create a device context for drawing on (a dc) using HDS_getdc
		function
	4)  make the initial palette with HDS_make_master_palette
	5)  start calling other graphics functions!!!



Remember that the quick reference section of the manual (manualqr.wri)
will show the values used and returned for all of the functions.

This should get you started.  If you have any questions you can get
in touch with us (8am to 6pm CST).  We check email at least 3 times
a day and can be reached:


	email:	support@hdri.com
		or 73631.2431@CompuServe.com
	phone:	(612) 730-6203
	fax:	(612) 730-6206
