						WINGRAPHICS

		EUPHORIA GRAPHICS FOR USE IN THE WINDOWS ENVIRONMENT

				  Version 8.2       14/4/06

Contents

	1. Description of WinGraphics.

	2. Format of User Files.

	3. Skeleton Code for a User File.

	4.Useful Global Values.
	
	5 Menus

	6. Manipulating Images.

	7. Special Printing Effects.

	8. Dialog Boxes

	9. Scrollbars

	10. Miscellaneous Windows routines.


*************************************************************************************
1. Description of WinGraphics.

	WinGraphics has been created to make it easy to write programs orientated towards displaying graphics in
	Euphoria's Win32 environment without a great knowledge of Windows programming. The demonstration
	programs in the Win32 folder which come with the Euphoria package consist almost entirely of code which
	is needed to interface with the Windows operating system. In WinGraphics, all of this code has been  setup in
	2 include files, WinGraphicsa.ew and winliba.ew. All the user needs to know is the
	basic structure of an exw file to utilise these routines.

*************************************************************************************
2.  Format of User Files.

The .exw should include winliba.ew and should create a callback address to a procedure named
Main(). The dll file graphics.dll should be installed in the bin directory and the files winliba.ew and
WinGraphics.ew in the include directory.

A utility program proggen.exw will produce skelton code and allows for various menus to be included. 

The Main() procedure is called by windows when the program initialises and if a menu item 
'Commence' is included, when that is selected. Processing then continues in the user code in the 
.exw file. This should include calls to Display() typically when something has been drawn on the screen.
The call to Display() serves to make the updates to the display visible and to allow Windows to process any
events such as mouse or keyboard activity.

The .exw file should not include any Euphoria routines which output to the screen
such as puts() and printf(). The MessageBox() and Print() routines should be used instead.

******************************************************************************
3. Skeleton Code for a User File.

The minimum code needed to create a Window and is the equivalent of the
demonstration program Window.exw. However, this minimum code produces a Window with
menus which are standard in the WinGraphics system. These menus contain functions for loading
bitmap files, displaying them, copying sections, pasting and saving them.

The basic code is as follows:-

--********Start of skeleton code

include winliba.ew
include get.e

--********Enter any variables and constants here followed by any initialisation required.


--********The next lines, indicated by *oOo, must be include exactly as shown. 
--********The others should be the statements which kick-off your routines.

global procedure Main()                               --*oOo

end procedure                                                --*oOo


MainProcAddress = routine_id("Main")     --*oOo
if MainProcAddress = -1 then                       --*oOo
	puts(1, "routine_id failed!\n")                  --*oOo
	MainProcAddress=wait_key()                 --*oOo
	abort(1)                                                      --*oOo
end if                                                               --*oOo

WinMain()                                                      --*oOo

--*******End of skeleton code.


************************************************************************
4. Useful Global Values.

A number of global values are set-up and maintained by winliba.ew and may be used
in the client programs. They are :-

General
     constant TRUE         = -1
     constant FALSE       = 0

Screen Dimensions

    integer ScrWidth       - Width of screen in pixels.
    integer ScrHeight      - Height of screen in pixels.

Co-ordinates set when the mouse is used

    atom MouseX & MouseY   - the upper left corner and
    atom MouseX1 & MouseY1 - the bottom right corner of rectangle.
    integer RBand

If the left button is clicked, MouseX and Mouse X1 will be the same as will MouseY
and MouseY1. If the mouse is dragged while the left button is pressed, a rectangle
will be drawn and displayed temporarily on the screen. To disable this function, set
RBand to 1. To enable it. set RBand to 0.

The mouse co-ordinates are displayed on the title bar. They may be set to zero using
the 'Reset Mouse' menu item. 

 
Key Pressed

    sequence Key           - a value representing the latest key pressed.

Sequences created when circles and lines are drawn

   sequence Lineseq     - when a call is made to Line()
   sequence Circseq     - when a call is made to Circle()
   sequence Mseq        - when either the file menu item Track Mouse or a call is made to TrackMouse()
   sequence Bezarr	- when a call is made to BezierArr() to draw a bezier curve.

File Open Dialog

  sequence Extn          - set this to the file type before calling FindFileName(), ee.g. "*.bmp" for bitmap files.
                                    Default is "*.*" for all file types.

*********************************************************************
5. Menus

Menus can be created by using the Euphoria program Proggen.exw. This creates a skeleton .exw file and
allows the following menu creating options

	1 - A program with standard menus which require no code from you to perform the functions;
	2 - A program with a menu which provides for a restart and exit again requiring no extra code; and
	3 - A program with the minimum menu items to which you can select extras from the standard menu items.

The standard menus comprise 'Control' with items 
	'Commence', 'Print Screen', 'Clear', 'Reset Mouse', 'Track Mouse', and 'Exit',
and 'Bitmap' with items 
	'Load Bitmap', Save Bitmap, 'Cut', and 'Paste'.

If you opt for any of the standard menu items the coding for servicing them is provided, but any extra menu
items you request will require you to provide the coding. The skeleton program will contain blank procedures
for each item, e.g. if you specified an item 'Circle' you would find something like

                      procedure Itemc()       --Code for Circle

					end procedure

in the program.

*********************************************************************
6. Manipulating Images.

There are a number of useful routines for manipulating images in winliba.ew.

The existing routines in Euphoria can only read .bmp files and then load the bitmap data into a 2d sequence
as follows
	(((R,G,B)...........................(R,G,B))...................((R,G,B).....................(R,G,B)))
         1st pixel, 1st line   nth pixel, 1st line			   1st pixel, nth line    nth pixel, nth line
These images are usually displayed by using SetPixel() which can take a significant amount of time.

Windows can display images much faster, but the pixel data has to be presented using a 1d array of pixel data as follows
	(R,G,B,..................................R,G,B,0*......................................R,G,B,.........................R,G,B,0*)
	1st pixel 1st line      last pixel 1st line                              1st pixel nth line	     last pixel last line  
*=1 to 3 packing bytes See function get_padding

The routines in winliba.ew read files containg .bmp, .ppm, and .jpg images and create sequences containing
the image in a 1d array of bitmap data. This sequence can then be sized to fit the screen and displayed
using the optimised Windows display routine. A sequence of bitmap data can also be built up in a Euphoria program
but each line of data must must end on a word boundary. The following code creates a sequence to hold an
image 99 pixels wide by 56 high

           sequence image
           integer line,height
              line= 99*3+get_padding(99)	--3 bytes per pixel plus any packing to end the line on a word boundary
              height=56
              image=repeat(255,line*height)

A list of the global routines and their descriptions follows. Certain routines must be called before others
to set up the necessary data required by the subsequent routines.

The global variables used are mainly the ones used in the bitmap header as follows

global integer  BitCount			the number of bits holding the colour data ie 2,4,8,24, or 32
global atom Width, Height		the dimensions of the bitmap
global atom SizeImage			the size of the image (length of the sequence containg the bitmap data
global sequence XY                       the x and y coordinates where ShowImage places the image ({x,y}).
						defaults to {0,0}.

The following global constants are error codes returned by read_bitmap(), save_bitmap() and save_screen()

BMP_SUCCESS = 0,
BMP_OPEN_FAILED = 1,
BMP_UNEXPECTED_EOF = 2,
BMP_UNSUPPORTED_FORMAT = 3,
BMP_INVALID_MODE = 4

********function get_padding(integer width)
returns an integer giving the number of bytes to be added to each line of pixel data to ensure that each line ends
on a word boundary.

********procedure PrintBMPHdr(object fname)
Displays the header information in the .bmp file given by fname.

********function ReadBits(sequence fname)
reads the bitmap file given by fname and returns the pixel data in a 1d sequence if successful, else M_NO.

********function WriteBits(sequence fname,sequence bits,integer width, integer height)
writes a bitmap file to the file given by fname from the 1d data in bits and the dimensions in width and height.

Returns M_YES if successful,else M_NO

********procedure reduce_bmp(sequence im)
reduces a .bmp file size to fit the screen if necessary and then displays it.

*******function Read_jpg(sequence fname)
Reads a .jpg file and returns a one dimensional array of pixel data suitable for displaying using Disp_image().
If fname is empty, it asks for the name of the .jpg file. Global variables Width, Height, and SizeImage contain
the dimensions of the bitmap.

*******procedure Write_jpg(sequence im,sequence fname,integer width,integer height)
Writes the one dimensional array of pixel data as a .jpg file. If fname is empty, it asks for the name of the .jpg file.
The dimensions of the image are taken from width and height.

********function Disp_image(sequence bits, atom width, atom height, atom sizeim)
displays the image in the 1 dimensional sequence bits,which has the dimensions width and height.
The atom sizeim holds the total size of the bitmap data eg width*3+packing *height (usually length(bits)).
If the top left corner of the image is not to go in the top left corner of the screen,  set XY before
calling this routine. 

Returns 0 if the image was displayed; 1 if an error.

*********************************************************************
7. Special Printing Effects.

The Print procedure described in the next section outputs text in black using the standard system font.
To print in different typestyles include font.ew in your program and call the PrintLargeFont procedure
described below. Include fonta.ew

The global integers Bold, Italic and Underline should be set TRUE if those effects are needed otherwise
set them FALSE. They default to FALSE.

The global sequence Fontname defaults to "Times New Roman". If another typeface is required set
Fontname to the name of that type. Use capitals in the name i.e. NOT "times new roman".

********procedure PrintLargeFont(sequence text,integer x,integer y,integer size,sequence colour)
where

         text contains the text to be displayed,

         x and y are the screen co-ordinates of the screen position.The y position is the top of the rectangle
         in which the text will appear,

         size is an integer defining the size of the text. This will have to be determined by experiment as the
         value will have different effects on different typefaces. Using Times New Roman a size setting of
         80 produces a character approximately 80 pixels high.

         colour is a sequence of RGB values e.g. {0,255,0} for green.

*********************************************************************
8. Dialog Boxes.

Some dialog boxes are already setup e.g. FindFileName (see below). To create bespoke dialog boxes
use the utility program CreateDialog.exw which has a gui interface. This allows the sizing of the box, the
positioning of controls and entering the text to accompany them.

During this procedure there is a facility to show the dialog as it will appear in your program
and then make any necessary adjustments.

When satisfied with the design, the elements can be saved so that the design can be restarted after the
program has been exited. Th program will also create an include file which handles the display of the
dialog in your program. for an example of the use of this include file see the demonstration program
dlgs.exw in the utilities folder.

*********************************************************************
9. Scrollbars

To attach scrollbars to a window, include the file scroll.ew in the program. This uses the global procedures

	InitScroll to setup scrollbars before the window is created
			parameter  -  1 for vertical bar;  2 for a horizontal bar; and 3 for both.

	UpdateScroll to change the details of the file to be displayed e.g. when a file is loaded
			parameters  	- filelength; filewidth (i.e. the length of the longest line
					in the file). (see GetFileSize below);
					xptr and yptr settings for the initial display usually 1 and 1
					for the first line and leftmost character in each line

	GetFileSize	parameter 	- a sequence containing the file. This procedure calculates
					the length of the file and the length of the longest line in the file.

The program using this incude file must set the global atom 'refresh' with the routine id of the procedure which
redraws the screen. It must also set the global objects hscroll and vscroll to 1 before calling WinMain(). 

A demonstration of the use of these scrollbar routines is the program scrolldemo.exw in the utilities folder.

*********************************************************************
10.  Miscellaneous Windows routines.

This section contains descriptions of other routines which are implemented in WinGraphics.


***************************BezierArr***************************
usage       function BezierArr(sequence points, sequence colour)

where       points contains the coordinates defining the curve and colour the colour.
            The points are in the form {{x,y},{x,y}.........{x,y}}. The initial curve
            is represented by 4 points and each subsequent one 3 points. On return the
            global variable Bezarr would contain the coordinates to plot the curve.

eg          reply=BezierArr({{100,100},{120,80},{150,90},{250,200},{350,190},{370,150},
              {500,100}},{255,0,0}) would draw a red curve consisting of 2 elements.

see also DrawBezier()
***************************Box******************************
usage       procedure Box(sequence coords,sequence colr,integer fill)

where       coords contains the co-ordinates of the upper-left and lower-right corners
            of the box, colr the rgb values for the colour, and fill = 0 for an outline
            and 1 for a filled box.

eg          Box({10,20,100,200},{0,255,0},0) would draw an outline box whose corners were
            at 10/20, 100/20, 100/200, and 10/200 respectively.

see also BoxArr

***************************BoxArr***************************
usage     function BoxArr(sequence coords,sequence clr,integer fill,sequence image)

where    coords contains the co-ordinates of the upper leftand bottom right corners of the
             box, clr the colour values in rgb form, fill =0 for an outline box, and image is the
             sequence in which the box is to be drawn.

eg          image=BoxArr({10,20,100,200},{0,255,0},1,image) which would draw a filled red box
             whose corners were 10/20,100/20,100/200 and 10/200 respectively.

               image must first have been initialised to a bitmap format in the form
              {{{0,0,0},{0,0,0},.......{0,0,0}}}, either by 'Copy'ing part of the screen or initialising
              the sequence as follows.

              size=100
              image=repeat({255,255,255},size)
              for j=1 to length(image) do
                     image[j]=repeat({255,255,255},size)
              end for

             which would create a bitmap format 100 pixels high and 100 pixels wide.

see also Box

***************************Circle****************************
usage       procedure Circle(sequence cntr, integer rad, sequence clr)

where       cntr contains the x and y co-ordinates for the centre of the circle, rad is
            the radius, and clr contains 3 rgb values for the colour of the circle.

eg          Circle({100,150},50,{255,0,0}) would draw a red circle whose center is at
            100/150 and whose radius is 50. The co-ordinates of the cicumference of this
            circle will be found in the global sequence Circseq.

see also CircleArr
***************************CircleArr***********************
usage    function CircleArr(cntr, rad, clr, image)

where   cntr contains the x and y co-ordinates for the centre of the circle, rad is
            the radius, clr contains 3 rgb values for the colour of the circle, and image contains
            the bitmap data on which the circle is to drawn.

eg        image=CircleArr({50,50},20,{255,0,0},image}

           This works as for Circle except it draws a circle in a sequence containing bitmap data
           instead of the screen. The advantage is that it operates more efficiently than drawing a
           circle on the screen and then 'Copy'ing it to a sequence for later manipulation.

           image must first have been initialised to a bitmap format in the form
          {{{0,0,0},{0,0,0},.......{0,0,0}}}, either by 'Copy'ing part of the screen or initialising
          the sequence as follows.

           size=100
           image=repeat({255,255,255},size)
           for j=1 to length(image) do
                  image[j]=repeat({255,255,255},size)
           end for

          This would create a bitmap format 100 pixels high and 100 pixels wide.

see also  Circle

***************************CheckOverwrite******************
usage       integer CheckOverwrite(sequence filename)

            This displays a Message Box asking whether the file should be overwritten
            and returns the user's response.


***************************Clear***************************
usage       procedure Clear()

            used to wipe every item from the display.

see also  ClearBack()

***************************ClearBack************************
usage       procedure ClearBack()

            used to wipe every item from the background screen without affecting the
            visible screen. Performs the same function as Clear() without Display().

see also  Clear()
****************************Copy**************************
usage      procedure Copy(integer x,integer y,integer x1, integer y1)

where     x,y and x1,y1 define the upper left and bottom right co-ordinates of the
              area to be copied to the Clipboard.

              This procedure operates like the menu item Copy from the Bitmap menu
              except that the latter takes the co-ordinates from the global variables
              MouseX, MouseY, MouseX1, and MouseY1. These are set by using the
              mouse to define the area to be copied.

see also CopyScreen() and Paste()
****************************CopyScreen*********************
usage       function CopyScreen(integer x,integer y,integer x1,integer y1)

eg          copy = CopyScreen(95,95,305,305)

where       'copy' is a sequence and x,y,x1,y1 are the co-ordinates of the rectangle to be
            copied. The structure of the returned sequence will be in the form
		copy[no of lines][no of pixels in width]. Each value of copy[n][m]will be
            an RGB value {R,G,B}.

see also    Paste() PutScreen() and PutScreenTrans()

****************************curt***********************************
usage	atom reply=curt(n)

           Calculates the cube root of n. If there is no cube root, returns 0

***************************DialogBox*************************
include dialog.ew

usage       function DialogBox(sequence MainDlg, sequence DlgItems)

where       MainDlg contains details of the dialog box and DlgItems details of the
                 controls in the box. These sequences can be constructed using the program
                 CreateDialog.ew.

                 See the section on dialog boxes for full details.

***************************Disp_image************************
include bitmap.ew

usage      function Disp_image(sequence bits, atom width, atom height, atom sizeim)

                displays the image in the 1 dimensional sequence bits,which has the dimensions
                width and height. The atom sizeim holds the total size of the bitmap data eg
                width*3+packing *height (usually length(bits)). If the top left corner of the
                image is not to go in the top left corner of the screen,  set XY before calling
                this routine. 

                Returns 0 if the image was displayed; 1 if an error.

***************************Display*********************************
usage       procedure Display()

            used whenever a drawing function is used, e.g. SetPixel, to release control
            to Windows and to have the screen updated.

***************************DrawBezier*****************************
usage      procedure DrawBezier(sequence points, sequence colr)

               used to draw one or more curves from the data in points using the colour specified
               in colr. 

               The layout of points is {{x1,y1},{x2,y2},{x3,y3},{x4,y4}} where x1,y1 are
               the co-ordinates of the starting point; x2,y2,x3, and y3 are the co-ordinates of the
               first and second control points; and x4,y4 are the co-ordinates of the end point.
               x2,y2,x3,y3,x4 and y4 may be repeated for subsequent curves, the starting points
               for which are the end points of the previous curve.

see also Bezier()
***************************EditText*******************************
usage     function EditText(sequence MyText) 

where    MyText is a sequence containing the text to be edited.

			This function opens an edit box containing the text to be edited and returns the
              amended text.

eg          sequence MyText
              MyText=EditText("This is an example")

***************************FindFileName***************************
usage       function FindFileName()

eg          filename=FindFileName()
		
where       filename is a sequence.

            used to invoke a file dialogue box which permits navigating the filing system.
            The filename selected will be returned in the sequence 'filename'.
            If a particular file type is required, set the global sequence Extn to that type
            e.g. "*.bmp" for bitmap files before calling this function.
	
***************************FloodFill*********************************
usage      procedure FloodFill(sequence coords,sequence colr)

                used to fill an area of the screen with the colour specified in colr. The area must
                first have been drawn using the same colour and must be completely enclosed by
                that colour.  The sequence coords must contain the co-ordinates of any point within
                the enclosed figure. If the figure is not completely enclosed, the colour will 'leak'
                out, possibly filling the entire screen. If coords specifies a point outside the enclosed
                figure, the latter will remain untouched.

see also    FloodFillArr

***************************FloodFillArr*******************************
usage       function FloodFillArr(sequence coords,sequence clr,sequence image)

                As FloodFill except it floods an area in a sequence containing bitmap data instead of
                the screen. The advantage is that it operates more efficiently than 'FloodFill'ing the
                screen and then 'Copy'ing it to a sequence for later manipulation.

eg            image=FloodFillArr({20,20},{255,0,0},image)

               image must first have been initialised to a bitmap format in the form
              {{{0,0,0},{0,0,0},.......{0,0,0}}}, either by 'Copy'ing part of the screen or initialising
              the sequence as follows.

              size=100
              image=repeat({255,255,255},size)
              for j=1 to length(image) do
                     image[j]=repeat({255,255,255},size)
              end for

             which would create a bitmap format 100 pixels high and 100 pixels wide.

see also    LineArr, PolygonArr

***************************GetBMSize********************************
usage      function GetBMSize(sequence fname)

              Used to get the dimensions of a bitmap which can then be loaded using LoadBitMap().
              
eg          sequence BMsize
              BMsize=GetBMSize("cat.bmp")
              
              BMsize will consist of 2 elements; BMsize[1] containing the width of the bitmap in pixels,
              and BMsize[2] the height.

see also  LoadBitMap() GetPasteSize()

***************************GetNumber********************************
usage       function GetNumber(sequence prompt)

eg          Reply=GetNumber("Please input your text")

where       Reply must be an atom and the text in the sequence prompt is displayed in
            the resulting dialogue box. This function is similar to GetString but only
            numeric data are accepted.

***************************GetPasteSize**********************
usage     function GetPasteSize()

             used to obtain the size of the image on the Clipboard

eg          sequence dimension
             dimension=GetPasteSize()

             The values returned in dimension are {width,height}but will be zero
             if there is no image on the clipboard.

see also GetBMSize()

***************************GetPixel**************************
usage		function GetPixel(integer x,integer y)

eg          col=GetPixel(20,40)

where		x and y are the co-odinates of the point to be examined. After the call,
            col would contain the rgb values in the form {R,G,B}.

***************************GetString*************************
usage     function GetString(sequence prompt)

eg          Reply=GetString("Please input your text")

where    Reply must be a sequence and the text in the prompt sequence is displayed in
	    the resulting dialogue box. The text input will be returned in Reply. See also
             GetNumber()
 
***************************Line*****************************
usage     procedure Line(integer x, integer y, integer x1, integer y1, sequence clr)

eg          Line(10,10,100,20,{0,255,0})

where    x, y,x1,y1 are the co-ordinates for the start and end of the line, and clr
            contains rgb values of the line. The example would draw a red line from 10/10
            to 100/20. The co-ordinates of the line will be recorded in the global sequence
            Lineseq.

see also LineArr

***************************LineArr************************
usage   function LineArr(integer sx, integer sy, integer ex, integer ey, sequence clr,sequence image)

eg        image = LineArr(10,10,100,20,{0,255,0},image)

where    x, y,x1,y1 are the co-ordinates for the start and end of the line, and clr
            contains rgb values of the line. The example would draw a red line from 10/10
            to 100/20 in the sequence image. This function operates faster than Line if the image is
            to be manipulated further.

            image must first have been initialised to a bitmap format in the form
           {{{0,0,0},{0,0,0},.......{0,0,0}}}, either by 'Copy'ing part of the screen or initialising
           the sequence as follows.

           size=100
           image=repeat({255,255,255},size)
           for j=1 to length(image) do
                  image[j]=repeat({255,255,255},size)
           end for

          which would create a bitmap format 100 pixels high and 100 pixels wide.

see also Line

***************************LoadBitMap*********************
usage       procedure LoadBitMap(sequence filename)

eg            LoadBitMap("c:\\euphoria\\pic.bmp") or LoadBitMap("")

                In the first case the bitmap will be loaded and displayed at the point defined
                by MouseX and MouseY. These values can be set within the program or by
                clicking on the approriate point on the screen using the mouse.

                In the second case, a file dialog will be displayed for the filename to be selected
                before loading the bitmap as before. 

***************************MessageBox**********************
usage       function MessageBox(sequence mess,integer sort)

eg          sequence mess
            integer reply
            mess="File closed"
            reply=MessageBox(mess,M_NOTIFY) 
 
where       mess contains the text of the message to be displayed and sort is either
            M_NOTIFY or M_QUERY. The former is for a notification type message box;
            M_NOTIFY displays a Message Box with an OK button, and M_QUERY elicits
            a Yes/No/Cancel response. The return values are

            M_OK        OK button pressed
            M_YES       Yes button pressed
            M_NO        No button pressed
            M_CANCEL    Cancel button pressed

            This would put up a Message Box with an OK button.

***************************Paste****************************
usage    procedure Paste(integer x, integer y, integer method)

where   x and y are the co-ordinates of the top left corner of the area on the screen
            where the contents of the Clipboard are to be pasted, and method indicates
            how the image is to be copied. The method must be one of the global constants
            defined in WinGraphics.ew. The most common method is SRCCOPY which
            places the image on the screen overwriting anything already there.

            This procedure operates like the menu item Paste from the Bitmap menu
            except that the latter takes the co-ordinates from the global variables MouseX,
            MouseY and SRCCOPY is used. The co-ordinates can set by using the mouse
            to define the top left corner.
      
see also Copy() PutScreen() and PutScreenTrans()

***************************Polygon**************************
usage     procedure Polygon(sequence points, sequence colour)

where    points is a sequence detailing the co-ordinates of the polygon to displayed
             in the form {{x1,y1},{x2,y2},.....,{xn,yn}}, and colour specifies the fill
             colour of the polygon in the form {r,g,b}.

see also PolygonArr

***************************PolygonArr***********************
usage    function PolygonArr(sequence points, sequence clr,sequence image,integer fill)

where    points is a sequence detailing the co-ordinates of the polygon to displayed
             in the form {{x1,y1{,{x2,y2},.....,{xn,yn}}; clr specifies the fill
             colour of the polygon in the form {r,g,b}; image is the sequence to be operated
             on{format see below), and fill specifies whether the polygon is to be filled with clr.
             if fill is 1 then the shape is filled, otherwise only the outline is drawn.

             PolygonArr operates as for Polygon except that the polygon is drawn in a sequence
             of bitmap data instead of the screen. This has speed advantages if the bitmap is to
             be manipulated further.

               image must first have been initialised to a bitmap format in the form
              {{{0,0,0},{0,0,0},.......{0,0,0}}}, either by 'Copy'ing part of the screen or initialising
              the sequence as follows.

              size=100
              image=repeat({255,255,255},size)
              for j=1 to length(image) do
                     image[j]=repeat({255,255,255},size)
              end for

             which would create a bitmap format 100 pixels high and 100 pixels wide.

see also Polygon 

***************************Print*****************************
usage     procedure Print(sequence mess,integer x,integer y)

where    mess is a sequence containing the message to be displayed, and x and y
             are the co-ordinates of the upper left corner where the text is to be displayed.

eg          Print("This is a message",20,20)
             
             sequence mess
             mess = "This is another message"
             Print(mess,20,20)

             integer total
             Print(sprintf("Total is %d",total),20,20)       

             sequence mess,num
             num={10,20,30}
             mess = "Num contains "
             for j=1 to 3 do
                  mess=mess & sprintf(" %d ",num[j])
             end for
             Print(mess,20,20)

***************************PrintBMPHdr*********************
include bitmap.ew

usage      procedure PrintBMPHdr(object fname)

                Displays the header information in the .bmp file given by fname.

***************************PrintLargeFont********************
include  fonts.ew

usage    PrintLargeFont(sequence text,integer x,integer y,integer size,sequence colour)

where   text contains the text to be displayed; x and y are the screen co-ordinates of the
             screen position (the y position is the top of the rectangle in which the text will appear);
             size is an integer defining the size of the text (this will have to be determined by experiment
             as the value will have different effects on different typefaces. Using Times New Roman a
             size setting of 80 produces a character approximately 80 pixels high); and colour is a
             sequence of RGB values e.g. {0,255,0} for green.

             The global integers Bold, Italic and Underline should be set TRUE if those effects are
              needed otherwise set them FALSE. They default to FALSE.

             The global sequence Fontname defaults to "Times New Roman". If another typeface is
              required set Fontname to the name of that type. Use capitals in the name i.e. NOT 
              "times new roman".

***************************PutScreen************************
usage       PutScreen(sequence copy,integer x,integer y)

eg          PutScreen(copy,400,100)

where       copy is a sequence in the form returned by CopyScreen() and x and y are
            the co-ordinates of the top left hand corner of the area on the screen
            where the image is to placed.

see also    CopyScreen()and PutScreenTrans()

***************************PutScreenTrans************************
usage       procedure PutScreenTrans(sequence copy,sequence colr,integer x,integer y)

eg          PutScreenTrans(copy,{0,0,0},400,100)

where       copy is a sequence in the form returned by CopyScreen(); x and y are
            the co-ordinates of the top left hand corner of the area on the screen
            where the image is to placed; and colr contains the RGB values of the
            pixels which are to be regarded as transparent and therefore not overwritten
            on the screen.

see also    CopyScreen() and PutScreen()

***********************************ReadBits************************
include bitmap.ew

usage     function ReadBits(fname)

where    the bitmap file specified in fname is read into the returned sequence as a
              one dimensional array. Returns M_NO if unsuccessful so the call item should
             be declared as object.

***************************reduce_bmp***********************
include bitmap.ew

usage     procedure reduce_bmp(sequence im)

               reduces a .bmp file size to fit the screen if necessary and then displays it.

****************************Read_jpg*************************
include bitmap.ew

usage           function Read_jpg(sequence fname)

               Reads a .jpg file and returns a one dimensional array of pixel data suitable for
               displaying using Disp_image(). If fname is empty, it asks for the name of the
               .jpg file. Global variables Width, Height, and SizeImage contain the dimensions
               of the bitmap.
***************************RunProg*********************
usage       RunProg(atom file,atom params)

            This issues a command to the system to run a program named in file with
            parameters in params.
            the sequences containing the program name and parameters must first be
            converted to atoms using allocate_string

***************************SaveScr*********************
usage       procedure SaveBitMap()

            This procedure saves an area of the screen as a bitmap file. The file to which
            the bitmap is saved can be entered or selected from the file dialog which is
            invoked by this procedure. The dimensions of the bitmap are governed by the
            settings in MouseX, MouseY, MouseX1 and MouseY1. These can be
            programmed or set by using the mouse. The resultant bitmap is in 32 bit format
            with no colour table
***************************SelectFont*************************
usage       sequence SelectFont()

            This invokes the system dialog box allowing the selection of a font and its
            attributes. It returns a sequence containing these attributes.
            The attributes can be accesed using global constants Fontnamea, Bolda,
            Sizea, Colra, Italica, and Underlinea eg atts[Fontnamea] for the name.

example     f=SelectFont()
            Fontname=f[Fontnamea] Italic=f[Italica] Bold=f[Bolda] Underline=f[Underlinea]


***************************SelectColour()*********************
usage       sequence SelectColour()

            This invokes the system dialog box to allow you to select the attributes
            of a colour. These are 3 8 bit integers representing the RGB values of
            that colour

***************************Setcursor**************************
usage       procedure Setcursor(integer cursor)

eg             Setcursor(0) to change the cursor to the hourglass symbol indicating a
                 lengthy operation in progress. The parameters are either 0 or 1. The latter
                 changes the cursor to the normal arrow icon, but this is automatically carried
                 out when procedures WaitMouse or WaitKey are called.

***************************SetPixel***************************
usage       SetPixel(sequence position,sequence rgb)

eg          SetPixel({10,20},{255,0,0}) 

where    the sequence position contains the x and y values of the pixel and sequence
              bgr the colour values. The example would place a red pixel at position 10/20.

see also		GetPixel.

****************************ShadeLine***********************
usage     procedure ShadeLine(integer x, integer y, integer x1, integer y1, sequence clr1,sequence clr2)

where    x,y,x1,y1 are the start and end points of the line and clr1 and clr2 are the colour
              values between which the line is to be shaded.

see also Line()

****************************Timer**************************
usage      procedure Timer(atom secs)

where     secs is a number specifying the length of the delay.

              used to yield control to windows for the specified amount of time.

****************************TrackMouse*********************
usage      procedure TrackMouse(sequence colr)

eg            TrackMouse({0,0,0}) would commence to draw a black line following the cursor
                after the left button has been pressed and continuing until the left button
                is released. The co-ordinates of the line are recorded in the global sequence 
                Mseq.

****************************unpack24()*********************
usage      sequence unpack24(sequence Bits,  integer Width, integer Height)

where      Bits is a one dimensional bitmap array and Width and Height its dimensions.

           This function returns a two dimensional bitmap image. The length of the sequence
           returned is the height of the image and each element of the sequence is a line
           of the image. The bitmap must be one where a pixel is represented by a 24 bit
           colour array.
           
****************************WaitKey************************
usage		procedure WaitKey()

            Used to pause the processing until a key is pressed. Return from the procedure
            will only occur when a key is pressed. The single character of the key pressed
            will be in the global sequence 'Key'.

****************************WaitMouse************************
usage	      procedure WaitMouse()

              Used to pause the processing until a mouse button is pressed. If the right
	     button was pressed the global integer RButton will contain 1 otherwise 0.
              if the left button was released the global integers MouseX, MouseY, MouseX1
              and MouseY1 will contain the co-ordinates of the mouse operation.

***************************WriteBits*****************************
include bitmap.ew

usage      integer reply=WriteBits(sequence fname,sequence bits,integer width, integer height)

               writes a bitmap file to the file given by fname from the 1d data in bits and the
               dimensions in width and height.

Returns M_YES if successful,else M_NO

****************************Write_jpg*******************************
include bitmap.ew

usage    procedure Write_jpg(sequence im,sequence fname,integer width,integer height)

             Writes the one dimensional array of pixel data as a .jpg file. If fname is empty,
             it asks for the name of the .jpg file.
The dimensions of the image are taken from width and height.


