			      Codename: Phoenix Documentation
===========================================================================================
	  (c) Copyright 2003,2004 Point Mad, Lukas Lipka. All rights reserved.
===========================================================================================
///////////////////////////////////////////////////////////////////////////////////////////

TABLE OF CONTENTS
I. OVERVIEW
	1. What is it?
	2. Requirements
	3. License
II. TECHNOLOGY OVERVIEW
	1. GFS
	2. DynLd
	3. Skinning system
III. PROGRAMMING MANUAL
	1. Types
	2. Debug
	3. Registry and INI files
	4. Image functions
	5. Metric functions

///////////////////////////////////////////////////////////////////////////////////////////

I.1 What is it?
<name> is a multiplatform GUI. It is the first GUI to have netowrking and
internet support. It uses the newest technologies developed by Lukas Lipka
and Point Mad (See Technology Overview for more information).

I.2 Requirements

I.3 License

II.1 GFS
The GFS (GUI FileSystem) is a new type of a filesystem developed by Lukas Lipka, s.r.o,
which should be a standard for use in GUI's. By using this filesystem you insure
multiplatform support for the GUI itself and the applications developed for it,
thus enabling it to work on diffrent platforms (DOS, Windows, Linux).
For more information and specifications visit Lukas Lipka's website.

II.2 DynLd
<JULIEN PLEASE FINISH THIS SECTION>

II.3 Skinning system
The first dynamic loading skinning system made especially for UI applications.
This skinning system allows you to dynamically load skin items for widgets.
What is so unique about it? When developing an application which implements
this skinning system, adding widgets and their skin support is very easy.
If you write a widget for eg. a window widget, you will need skin items such as
window face, window title which can be in two states (active, passive).
When using this skinning system, all you do is add the names of the new skin
items into your dynamically linked application or library and implement them into
the skin file. No recompilation to the kernel or the hosting application which
contains the skinning system is needed.
For more information and specifications visit Lukas Lipka's website.


III.1 Types
When developing applications, its recommended to use these types instead
of the basics (int, char*) for further compatibility.

long		l_long;
int		l_int;
bool		l_bool;
short		l_short;
char		l_char;
byte		l_byte
unsigend char	l_uchar;
unsigned int	l_uint;
word		l_word;
unsigned long	l_ulong;
dword		l_dword
char*		l_text;
BITMAP*		p_bitmap;

By using these types you insure futre compatibility of your written applications.


III.2 Debug
Debug is the file <name> debugs to. Normally its called kernel.txt.
You have specific functions for use with it.

void DebugMessage( char* format, ... );
NAME:		DebugMessage
TYPE:		void
PARAMETERS:	(the string to print, ...);
DESCRIPTION:	Writes to debug using the "Message:" statement.
EXAMPLE:	DebugMessage("Could not open file - %s", filename);
OUTPUT:		In debug - Message: Could not open file - hello.txt
RETURN:		NONE

void DebugWarning( char* format, ... );
NAME:		DebugWarning
TYPE:		void
PARAMETERS:	(the string to print, ...);
DESCRIPTION:	Writes to debug using the "Warning:" statement.
EXAMPLE:	DebugWarning("Could not open file - %s", filename);
OUTPUT:		In debug - Warning: Could not open file - hello.txt
RETURN:		NONE

void DebugError( char* format, ... );
NAME:		DebugError
TYPE:		void
PARAMETERS:	(the string to print, ...);
DESCRIPTION:	Writes to debug using the "ERROR:" statement.
EXAMPLE:	DebugError("Could not open file - %s", filename);
OUTPUT:		In debug - ERROR: Could not open file - hello.txt
RETURN:		NONE

void DebugFatal( char* format, ... );
NAME:		DebugFatal
TYPE:		void
PARAMETERS:	(the string to print, ...);
DESCRIPTION:	Writes to debug using the "FATAL ERROR:" statement.
NOTE:		By calling this function the main engine is aborted.
			thus ending program execution.
EXAMPLE:	DebugFatal("Could not open file - %s", filename);
OUTPUT:		In debug - FATAL ERROR: Could not open file - hello.txt
RETURN:		NONE


III.3 Registry and INI files
The registry is the file called xsystem.reg in SYSTEM/REGS directory.
It is used for storing information such as screen metrcis, user information,
different settings. It has the same file format as INI files.  The basic INI
file structure is as follows:

[SCREEN]
width=640
height=480
depth=32

[USER]
name="James Hacker"

l_char *RegistryGetKey ( l_text path, l_text key );
NAME:		RegistryGetKey
TYPE:		l_text
PARAMETERS:	(the tag name, the key name);
DESCRIPTION:	Reads the text value from the specified key which is in the the specified
			section.
EXAMPLE:	l_text name = RegistryGetKey("USER", "name");
OUTPUT:		name now conatins the text - James Hacker
RETURN:		Pointer to the string

l_int RegistryGetInteger ( l_text path, l_text key );
NAME:		RegistryGetInteger
TYPE:		l_int
PARAMETERS:	(the tag name, the key name);
DESCRIPTION:	Reads the numeric value from the specified key which is in the specified
			section.
EXAMPLE:	l_int val = RegistryGetInteger("SCREEN", "width");
OUTPUT:		val now conatins the number - 640
RETURN:		The numeric value

l_color  RegistryGetColor(l_char *name);
NAME:		RegistryGetColor
TYPE:		l_color
PARAMETERS:	(the color name);
NOTE:		The color is already calculated using the Allegro makecol();
DESCRIPTION:	Gets the specified color from the registry.
EXAMPLE:	l_color color = RegistryGetInteger("desktop_face");
OUTPUT:		color now conatins the color - 152984
RETURN:		The color

void INIGetText(l_text szFileName, l_text szSection, l_text szItem, l_text szValue, l_text szDefault);
NAME:		INIGetText
TYPE:		void
PARAMETERS:	(filename, section, key, where to store the string, default string);
DESCRIPTION:	Reads a string from the specified key which is in the specified section.
EXAMPLE:	l_text newname;
		INIGetText("file.ini", "user", "name", newname, "NO NAME");
OUTPUT:		newname now conatins the string - James hacker
RETURN:		NONE
NOTE:		If you would rather have the value returned use INIGetNew();

l_text INIGetNew(l_text szFileName, l_text szSection, l_text szItem, l_text szDefault);
NAME:		INIGetNew
TYPE:		l_text
PARAMETERS:	(filename, section, key, default string);
DESCRIPTION:	Reads a string from the specified key which is in the specified section.
EXAMPLE:	l_text newname = GSINIGetNew("file.ini", "user", "name", "NO NAME");
OUTPUT:		newname now conatins the string - James Hacker
RETURN:		pointer to the string

l_int INIGetInteger(l_text szFileName, l_text szSection, l_text szItem, l_int iDefault);
NAME:		INIGetInteger
TYPE:		l_int
PARAMETERS:	(filename, section, key, default value);
DESCRIPTION:	Gets a numeric value from the specified key which is in the specified
			section.
EXAMPLE:	l_int newval = GSINIGetInteger("file.ini", "screen", "width", 640);
OUTPUT:		newval now conatins the value - 640
RETURN:		the new value

l_color INIGetColor(l_text szFileName, l_text szSection, l_text szItem, l_color colDefault);
NAME:		INIGetColor
TYPE:		l_color
PARAMETERS:	(filename, section, key, default color);
NOTE:		The color is already calculated using the Allegro makecol();
DESCRIPTION:	Gets the specified color from the INI file.
EXAMPLE:	l_color color = INIGetColor("file.ini","desktop","face",makecol(0,0,0));
OUTPUT:		color now conatins the color - 152984
RETURN:		The color


III.4 Image functions
These very basic functions are used for loading and manipulating images.
Advanced image manipulation functions are defined in Allegro. See Allegro
documentation for further details.

p_bitmap LoadImage(l_text szFileName);
NAME:		LoadImage
TYPE:		p_bitmap
PARAMETERS:	(filename);
DESCRIPTION:	Loads a image file
EXAMPLE:	p_bitmap bmp = LoadImage("startup.bmp");
RETURN:		Pointer to the image

p_bitmap  LoadImageAs(l_text szFileName, l_int BPP);
NAME:		LoadImageAs
TYPE:		p_bitmap
PARAMETERS:	(filename, BPP);
DESCRIPTION:	Loads a image file allowing you to specify the BPP
EXAMPLE:	p_bitmap bmp = LoadImage("startup.bmp", 16);
RETURN:		Pointer to the image


III.5 Metrics functions
Metrics functions is a specific set of functions used for manipulating with
sizes, rectangles, points and other calculations.

t_point PointAssign	( l_int x, l_int y );
t_point MakePoint	( l_int x, l_int y );
l_bool PointInRect	( t_point p, t_rect r );
t_rect RectAssign	( l_rect ax, l_rect ay, l_rect bx, l_rect by );
t_rect MakeRect 	( l_int ax, l_int ay, l_int bx, l_int by );
l_bool RectInRect	( t_rect r1, t_rect r2 );
t_rect RectMove 	( t_rect r, t_point p );
l_int GetXDelta		( t_rect r );
l_int GetYDelta		( t_rect r );
l_int GetWidth		( t_rect r );
l_int GetHeight		( t_rect r );
t_size MakeSize(l_int w, l_int h);


===========================================================================================
Lukas Lipka
Point Mad	- http://www.pmad.net	 - julien@pmad.net
===========================================================================================