gtkradiant/docs/developer/DRAFT

usefull global variables in Radiant:
g_strAppPath has the path to the binary

-----------------------------------------------------------------------
using prefs / ini settings:
are stored in Radiant.ini and *.bin files
win32:
looks in the current directory for a Radiant.ini file
if found, will use it and set the ini directory to the proper location
if not found:
the registry has a path to the default directory?
under key HKEY_CURRENT_USER/Software/GtkRadiant/PrimaryEditorPath
(DefaultEditorPath cause that gets used for 
if the key doesn't exist create in current directory and set the key
NOTE: need some registry version info, when we find in another dir than ours,
  check version and prompt to use existing settings or our own?

storing version information:
each build publicly released should have a version string
- use it in the about box
- store it in the Radiant.ini file
- use it in the registry GtkRadiant/
do we need major and minor? minor could be used for versions that don't break .ini compatibility
  (well I'm lazy .. won't do)

linux:
look in the current directory (check write permission!)
if found, use it
if not found:
look in ~/.q3a/radiant

-----------------------------------------------------------------------
icons:
look for bitmaps/ under g_strAppPath
win32:
if not found, use DefaultEditorPath registry key and try to locate there
linux:
we also need a DefaultEditorPath kind of thing?
somewhere in ~/.q3a/radiant?

-----------------------------------------------------------------------
project file:
Radiant.ini must have full path to the project file
if no project file path:
win32:
we have to locate BASEPATH one way or the other. we have code that will look for the
main directory and go down into baseq3/scripts. If that fails we prompt the user.
it would be good to store BASEPATH in the .ini as well!
linux:
store path to Radiant installation somewhere in ~/.q3a/radiant
if not found try some defaults and prompt the user

NOTE: on linux radiant is in /usr/local/games/quake3/ instead of some
quake3/tools directory. This makes looking for the basepath easier.

g_PrefsDlg.m_strLastProject points to the project to be loaded
if radiant cannot find it at startup it will try to guess and/or ask the user
once the project file is loaded you can deduce a lot of things..
but project file parsing has some prerequisites: __QERPATH / __QERHOMEPATH ??
need to unify between win32 and linux!
PrefsDlg has a bunch of defaults, but it must not try to guess 
  __QERPATH and __QERHOMEPATH until there has been an ini load (or a lack of)
the involved members are:
m_strQuake2 <- points to the engine path, renamed to m_strBasePath m_strEngine
m_strPAKFile <- built from m_strBasePath, removed (not used?)
and: need to add more, like map compilers directory m_strToolsPath

project file syntax:
linux version is using __QERPATH / __QERHOMEPATH
win32 has __Q2PATH __QERPATH
and the overall syntax is different!

big problem is user customization, it performs expansion and saves with static
paths. but we'd like to keep the original one with generic naming. (cause if the
config fucks up and user reinstalls he'll still get broken project settings)
so: we try to load quake.qe4 project, expand it, and save as user.qe4
(on linux, user.qe4 goes in ~/.q3a/baseq3/scripts)

TODO: how is "New project" supposed to work? would copy the current project..
TODO: get rid of m_bLoadLast .. we require having a project loaded for use?
TODO: store path to the tools in prefs? (see usage for project file expansion?)
  -> so you can use q3map in a given dir etc?

unifying project file syntaxes:

get rid of BuildShortPathName things!

-----------------------------------------------------------------
some common operations and portable code:
document XP use of stat, checking for directory / file existence

how to have code that reads well across XP:
don't use TABS, have them emulated to 2 spaces

-----------------------------------------------------------------
project files:
unless we rewrite a whole bunch of it from scratch there's no much
hope for evolution of the project files. Nevertheless, introduced
a new "version" key that describes the version of the project file.
version 2 adds a # keyword for q3map global options
NOTE: and it's a compatibility nightmare, we can't call this one
quake.qe4 or default.qe4 cause it will break backward compatibility

-----------------------------------------------------------------
monitoring BSP process:
we monitor through network connections
we need to stop the process if an error occurs during one of the three steps
and launch quake3 when all is done
we don't want to CreateProcess and watch cause for rsh mode it will return immediately
a BSP process is decomposed in several steps and we expect a connection at each step
- later we can add custom steps that don't net connect and then we just spawn and
watch them
- we could add a name to the step to identify them, for now we'll just assume
the first connection that we get is the one of the process we spawned
when we loose the connection we wait one sec and spawn the next one...
- we don't use batch file, just produce the command lines for each steps, the batch file
will be produced only if we don't monitor the process (we can add an option to output
the BAT file anyway)

what stuff goes in prefs? "Monitor BSP process"

detecting when the socket closes?
using select() one can detect if a socket has closed or if there's some input
NOTE: when launching a new BSP process we may still be connected. Need to ask the user
about overridding and closing current connection.

in prefs, boolean flag for process monitoring .. g_PrefsDlg.m_bWatchBSP

when running in monitored mode, the BSP watcher is in charge of spawning and watching
the processes (and more later when it will be parsing the output).