TRACING

                            About Tracing using FXTRACE
                            ===========================



The basic idea is similar to FXASSERT:- you will add lots FXTRACE commands, but
you probably never want to remove them.  Just like FXASSERT, FXTRACE commands can
be left in the code, as they're automatically compiled out when the library
is build for release mode, i.e. with -DNDEBUG on the command line of your compiler.

If this isn't reason enough to forego old printf() statements for FXTRACE, I remind
you that under MSWindows, no stdout/stderr is opened up for non-console applications,
and one has to use the Debug API calls instead of printf() calls.

Using FXTRACE is therefore pretty convenient, as the MSWindows implementation of FOX
will automatically use those Debug API's if your program is not compiled as a console
application, and will revert to stderr under console mode [and of course under UNIX].


You use FXTRACE with DOUBLE PARENTHESES, as in:


  FXTRACE((200,"%s::onFocusIn %08x\n",getClassName(),this));


This is done so the C preprocessor can expand:


  FXTRACE((200,"%s::onFocusIn %08x\n",getClassName(),this))


into:


  fxtrace (200,"%s::onFocusIn %08x\n",getClassName(),this)


or, in case of -DNDEBUG or release builds:


  ((void)0)


Which any self-respecting compiler completely ignores and generates no
object code for.  BTW, this is what everybody does for asserts also.


The number `200' in the above example is the tracelevel at which the statement
will produce actual outputs on your screen.

Starting your FOX program with:


  <programname> -tracelevel 300


will cause all FXTRACE statements with levels 300 and up to be BLOCKED from
producing any outputs.

Since you don't want to see reams of outputs, the most frequently occuring types
of events should be given the highest trace level.

For now, tracelevels 0 through 99 are reserved for application use, with FOX itself
using levels 100 and upwards.

Note that as tracing is controlled by a simple global variable fxTraceLevel, your
program can simply set a higher tracelevel at a point in its execution where things
are starting to get a little bit hairy.....

Another way to set the tracelevel is to set the environment variable FOX_TRACE_LEVEL.
The tracelevel takes effect when the FXApp is initialized.  Setting the tracelevel
from the command-line takes precedence over the FOX_TRACE_LEVEL tracelevel value.
 

Tentative assignments of tracelevels in FOX:


  100: Important, high-level info, such as ctors and dtors for Icons, Images,
       Bitmaps, Fonts, and Cursors.
       Since you may easily leak those resources if your program does not track
       these properly, setting tracelevel to 101 (or higher) will allow you to
       see easily what's being created and destroyed.

  200: Infrequent events such as mapping/unmapping of windows, selection requests,
       and such stuff.

  250: More frequent stuff such as DND events.

  300: Button clicks.

  350: Mouse movements.

  400: GUI Updates, when GUI Updates are allowed.


I have not been overzealous sticking to these conventions, but now that it's written
down for me to re-read, there's a higher chance that I'll stick to it in the future.

Further assignments will probably follow some day....



  - Jeroen