//////////////////////
// TOC
/

1. Introduction
2. Coding style
3. Directory structure
4. Property stuff
5. Templates
6. Pointer notations/names
7. Changes in Fl_String
8. Wrapper classes

/////////////// MIKKOS NOTES ////////////////////
I have added some comments in this doc.
All my comments starts with "MIKKO:"
MIKKO:	This is useless comment!

PALI: I will use the same notation ;-)

//////////////////////
// 1. Introduction
/

I had some more ideas, so I thought I should write them here.
Maybe we should change this file to HTML format, so we can use
colors to identify ourselves.

PALI: Some terms:
    developer	- the guys who works on eFLTK/RTK ;-)
    user 	- the coder who uses eFLTK for his work

PALI: Because this file is getting bigger and bigger,
    maybe it would be the time to change to some other way to discuss.
    A kinda web forum would be good.
    There are two possibilities:
	- make a new web based forum, specially designed for this
	    (but needs extra work ... and extra time)
	- register the RTK project now (or on savannah, or on sf)
	    and use their web based forum
	    
//////////////////////
// 2. Coding style
/

We should define a coding style.
Here is my coding style (I can negotiate ;-)

Class names: 
    Upper_Case_Each_Word
not:
    UpperCase, Upper_CaseSome    
    
MIKKO: UpperCaseEachWordContinuous
DEJAN: UpperCaseEachWord
PALI: ^-- these are pros or contras ?

method names: 
    lower_case_each_word
not:
    lowerCaseOnlyTheFirst
    
MIKKO: StartAndContinuesWithCapital
DEJAN: LowerCaseEachWord
    
Private members:
    _starts_with_underscore
not:
    starts_with_underscore
    
MIKKO: _this_is_ok :)
DEJAN: _typeName, where type has just 3 characters. Examples:
  _strSurname // member of type string
  _intHowOld  // integer member
  _winMain    // member of type Window
PALI: I do not like the hungarian notain (despite of my nationality ;-)
    Why to encode the type in the variable name ?
    The compiler will warn if the types mismatch ... 
    ... and anyway, this is M$'s style ;-) ...
    
!NOTE: IMHO is better to put an underscore _before_:
 - it's easier to distinguish '_var' from 'var', then 'var_' from 'var'
Also IMHO prefixes, like 'm_' are useless (needs only a lot of extra typing)
Also I hate the hungarian notation (dispite my nationality ;-):
Why anyone would need to encode the type in the name ?!?! M$ sux
Ok, lets continue:

Functions:

return_type name(ptype1 param1, ptype2 param2)
{
    // code
}

Control blocks:

if (cond) {
    // code 
} else {
    // code
}    	

switch (cond) {
    case label1:
	// code
	break;
}

DEJAN:
<dejan>
  I'd prefer 
if (cond) 
{
    // code 
} // if
else 
{
    // code
} // else

and

switch (cond) 
{
    case label1:
		// code for this case
	break;
} // switch

Note also comments after blocks (if, else, switch).
PALI: for long blocks is ok, but after each 'if', 'switch', etc IMHHO is 
    too much... btw, who likes commenting at all ?-)

</dejan>

Ok, so why the 4 char indentation:
- 8 bytes are too much: there are cases when there are a lot of nested blocks
(and in some cases it's NOT better to use more functions, eg: inside class
methods). Suppose there is a function, with 4 nested blocks 
(func->for->switch->case->if->code) that would mean 5*8 = 40 chars of indentation.
That is half of the screen width
- 2 byte are too few: in a longer function you can't see clearly where a block ends

MIKKO:	What's point in this??! 
		IMHO indentation MUST BE ALWAYS TABS!!!
		So developer can decide in editor what's 
		the real size of it!
PALI: Yes, you're right... the only problem is, when tabs and spaces are mixed		

DEJAN: <dejan>
  Well, i would prefer just two characters for identation.
  Something like:
  if (blah)
  {
	if (blah2)
    {
      // something
    } // if
  } // if </dejan>

Well, that's it for today, I'm ready to discuss these, to negotiate ;-)

////////////////////////
// 3. Directory structure:
/

|-- rtk <-- include files (all of them)
|-+ src
| |-- core
| |-+ device <-- common stuff here
| | |-- X11 <-- linux X11 output device here
| | |-- win32 <-- Win32Api output device here
| | |-- ... etc ...
| |-- GUI-core
| |-- GUI
| |-- GameUI
| |-- GLUI <-- OpenGL stuff here
| |-- DB
| |-- Net
| |-- Framework <-- I dont know yet what will be in the framework
| |                 S o I dont know what structure will it has
| |-+ Tools
|
|-- doc <-- user documentaton
|-- devel-notes (or dox) <-- notes/docs for developers (of RTK)
|
|-+ test <-- same structure as /src
| |-- core
| |-- GUI-core
| |-- GUI
| |-- GameUI
| |-- DB
| |-- Net
| |-- Framework

<dejan>
I would add complete subtree for different kind of IDE's with which RTK would
be developed. Here is my proposal:
|-+ work
| |-- devcxx		// Dev-C++
| |-- anjuta		// Anjuta
| |-- bcxxb			// Borland C++ Builder
| |-- bcxx			// Borland C++
| |-- vcpp			// Visual C++
...

PALI: good idea ... of course if there will be somebody, who will update those
    Any succes with CMake ?

Sure we should work on makefile(s) for any compiler kit that we might use in
our everyday work, namely GCC, Borland Free CommandLine Tools, Intel C/C++, etc.
So we would also need some naming scheme for compiler used for building RTK.
I propose Makefile.NNN where NNN is "gcc", "bcc", "vcc", "icc", etc.
</dejan>

MIKKO:	I have excluded some dirs from structure,
		Cause we can't handle them now!
		They may (will) be added later, as soon as
		basics are working.

Here's my structure:
|-- rtk <-- include files (all of them)
|-+ src
| |-- core 		<-- Non-gui stuff here only (all)
| |-+ device	<-- No source files here, only dirs for each GUI subsystem
| | |-- X11 	<-- linux X11 input/output/event device here
| | |-- win32 	<-- Win32 API input/output/event device here
| | |-- ... etc ...
| |-- GUI		<-- Contains all common widgets, including all image io's
| |-- GUI-extra <-- ?? Maybe some very huge widgets, like complete HTML ?? 
| |-+ Tools		<-- UI builder?
|
|-- doc 		<-- user documentaton
|-- devel-notes	<-- notes/docs for developers (of RTK)
|
|-+ test <-- same structure as /src
| |-- core
| |-- GUI


PALI: ok, one question: GUI-core is renamed to GUI, and GUI to GUI-extra ?

About tools: 
Will the RTK package/module contain higher level tools
(Eg. IDE, dialog editor, etc.) ? Or they will be in separate module ?

MIKKO:	Donno yet..
DEJAN: Ide would be separate project.
PALI: I vote for separate project also
    Maybe the framework part could be a separate project also,
    so if someone doesn't need it, just the plain core RTK, don't has
    to download it.
    But if framework goes in separate project, then DB and Net also ?
    (note: some very basic/lowlevel DB (DS) and Net should be in core)
    Too much projects raises another problems ...
    
//////////////////////
// 4. Properties
/

Widgets have a lot of properties: color, boxtype, etc.
These are all store globally. It would be nice to have a special value,
called DEFAULT. When a property is set to DEFAULT, the value is got
from the name_style (or a global value)

Maybe another indirection could be done:
[ WIDGET ] ---> [ STYLE ] ---> [ GLOBAL ]
Practically speaking, there would be a global value. It can be overriden
by a style. And also that value can be overriden by the widget. 
It can be optimised to have only one indirection: when loading a new style
fill all DEFAULT values with the global ones.

There would be 3 methods for each property:
void property(value) - set the value stored in the widget
value property() - if value is DEFAULT, reteurn global one, otherwise return value in widget
value getProperty() - returns the value stired in the widget (this could be DEFAULT)
(the last two may be swaped/renamed)

MIKKO: 	Pali, You should do your homework better :)
		Please find out how Fl_Style works, 
		It will do exactly what you want.
		And even better, make it better :), it's not
		user friendly as it is now.. 
PALI: You're right, I didn't knew about it ... when was it implemented ?		
PALI: I check it again, and it really needs some improvement (mainly speed
    optimization)
    Currently there is a for loop to traverse the parent tree.
    An optimization would be: when registering/adding a new style,
    a copy of it will be made, and all unset field will be set with
    the value of the parent (or the parent-of-the-parent, etc.)
    A pointer to the original style is stored in a field.
    This way:
	1) when adding a new (leaf) style -> recursively fill the unset values
	2) when adding a new (non-leaf) style -> -- || -- + rebuild the subtree
	    (because adding & removing the syle is very rare, it's not a problem
	    if it's a bit slower)
	3) when retrieving a value, this way we have the correct value 
	    IMMEDIATELY	    
		
//////////////////////
// 5. Template files
/

5.1 Header

Here goes header template, which should be used for all new classes.

<code lang="cxx">
/** 
  * Foo.
  * Some explanation about file goes here. This class is example/template
  * class that should be used when creating new RTK classes.
  * 
  * The source below is under LGPL license.
  *     Information about GNU LGPL: http://www.gnu.org/copyleft/lesser.html
  *
  * Copyright (c) RTK Team. More information about project: http://www.rtk.cx
  *
  * Authors (sorted by time they worked on this source file):
  * 	Fname Sname, example§rtk.cx
  *
  * Contributors (ie. people that have sent patches, ideas, suggestions):
  * 	Fname2 Sname2, example§rtk.cx
  *
  * PLEASE report any bug, bugfix, improvement or suggestion to 
  * 	rtk-bugs§rtk.cx
  ****************************************************************************/

#ifndef _FOO_H_
#define _FOO_H_ 1

namespace Rtk
{

class Foo: public Object
{
}; // Foo

} // Rtk

#endif

</code>

... COMMENTS ..................................................................
<dejan> I know for sure that you do not like my comment-style at the begining.
I'll be okay with some other style too. :) </dejan>

PALI: About 'rtk-bugs§rtk.cx': so what we'll do about utf-8 ?
	Maybe the core of RTK will work with utf ? And have converter
	functions ? (like eFLTK now ... of course a bit more stable ;-)
    
5.2 Source template

And here is template for C/C++ source files.

<code lang="cxx">
/** 
  * Foo.
  * Some explanation about file goes here. This class is example/template
  * class that should be used when creating new RTK classes.
  * 
  * The source below is under LGPL license.
  *     Information about GNU LGPL: http://www.gnu.org/copyleft/lesser.html
  *
  * Copyright (c) RTK Team. More information about project: http://www.rtk.cx
  *
  * Authors (sorted by time they worked on this source file):
  * 	Fname Sname, example§rtk.cx
  *
  * Contributors (ie. people that have sent patches, ideas, suggestions):
  * 	Fname2 Sname2, example§rtk.cx
  *
  * PLEASE report any bug, bugfix, improvement or suggestion to 
  * 	rtk-bugs§rtk.cx
  ****************************************************************************/
#include <rtk/foo.h>

</code>
... COMMENTS ..................................................................
<dejan> This one is just copied. I haven't had any other ideas what else should 
be there. </dejan>

PALI:
///////////////////////
// 6. Pointer names
/

I was thinking of a special notation for pointers, to distuingish those one,
which are pointers in static memory, and those ones which must be freed
by the user.
Example lets say there is a function:

char * foo();

Let's say, if the returned string is a pointer in a global buffer (ie. not in
the heap, wo should use one notation:)

s_pchar foo();

If it must be freed:

pchar foo();

And the definitions:

#define pchar 		char *
#define s_pchar 	char *

Or with typedef:

#define P(type) \
    typedef type * p##type; \
    typedef type * s_p##type; 
P(char)

ps: maybe this is usefull in eFLTK also.

/PALI    

PALI:
///////////////////////
// 7. Changes in Fl_String
/ (should we realy number it ? or maybe restructure it ?)
/ (maybe use XML ;-)
/

A crazy idea for changing Fl_String:

Currently Fl_String has these fields:
    char * str_;
    unsigned len_;
    
Maybe we can do something like this:
    union {
	char * str_;
	unsigned * len_;
    }
The first four bytes of str_ would be the length, and the rest
is the string. (like in pascal)

Pro:
    - sizeof(Fl_String) = 4 = sizeof(char*)     
	for a NULL string, no extra memory needed       
    - there is a differences between an empty string and a NULL string
Contra:
    - extra indirection for getting the length	
    - extra addition (+4) for getting the pointer to the string 
	(this is just one extra clock cycle)
/PALI    

PALI:
///////////////////////
// 8. Wrapper classes
/

Given the following:

class Type
{
    type _field;
    // a bunch of methods
};

sizeof(Type) == sizeof(type)

We should use this type of wrapping for a lot of types/variables.
One example is for keycodes:

class Keycode
{
    uint _code;
    
    char * ToString();
    static Keycode FromString(char *);
    
    inline Keycode operator + (Keycode b)  { return Keycode(_code+b._code); }
    // etc.
};    

Here is a short list of examples for which wrapping would be usefull:
 - Color
 - CursorType
 - EventType
 - Keycode
 - Version
 - Time (timestamp)
 
/PALI