File: faq.html

package info (click to toggle)
fox 1.0.52-2
links: PTS
area: main
in suites: sarge
size: 10,788 kB
ctags: 13,384
sloc: cpp: 96,482; sh: 8,338; ansic: 1,935; makefile: 1,010; perl: 32
file content (1000 lines) | stat: -rw-r--r-- 48,655 bytes
<html>
<head>
<LINK REL="stylesheet" HREF="styles.css" TYPE="text/css">
<title>FOX-Toolkit</title>
<!-- HTML Copyright 2001 Paul Laufer -->
</head>

<body bgcolor=#ffffff link=#990033 vlink=#4a73ad alink=#ed004f text=#000000>

<!--header-->
<table align=center border=0 cellpadding=0 cellspacing=0 width=100% >
  <tr><td bgcolor=silver colspan=5 align=right height=50><img src=art/oul_grey.gif align=left valign=top width=8 height=8><img src=art/foxlogo.png valign=bottom alt="FOX Toolkit" height=50 width=500 border=0 ></td>
  	<td bgcolor=#557faa valign=top align=right><img src=art/our.gif width=8 height=8></td>
  </tr>
<!-- end header -->
  <tr>
    <td bgcolor=#557faa colspan=2 valign=top align=left>&nbsp;</td>
    <td bgcolor=#557faa colspan=3><font color=#ffffff size=+1><center>
<!-- Page Title -->
FAQ
<!-- End Page Title -->
    </center></font></td>
    <td bgcolor=#557faa valign=top align=right>&nbsp;</td>
  </tr>
  <tr>
    <td bgcolor=#557faa colspan=2>&nbsp;</td>
    <td bgcolor=#ffffff valign=top align=left><img src=art/iul.gif width=8 height=8></td>
    <td bgcolor=#ffffff>&nbsp;</td>
    <td bgcolor=#ffffff valign=top align=right><img src=art/iur.gif width=8 height=8></td>
    <td bgcolor=#557faa width=15>&nbsp;</td>
  </tr>
  <tr>
    <td width=8 bgcolor=#557faa>&nbsp;</td>
    <td valign=top bgcolor=#557faa link=#ffffff width=150>

<!-- start navbar content -->

	<a href=fox.html><font color=#ffffff>Home</font></a><br>
	<a href=news.html><font color=#ffffff>News</font></a><br>
	<a href=download.html><font color=#ffffff>Download</font></a><br>
	<a href=goals.html><font color=#ffffff>Goals & Approach</font></a><br>
	<a href=doc.html><font color=#ffffff>Documentation</font></a><br>
	<a href=faq.html><font color=#ffffff>FAQ</font></a><br>
	<a href=rex.html><font color=#ffffff>FXRex</font></a><br>
	<a href=screenshots.html><font color=#ffffff>Screenshots</font></a><br>
	<br>
	<a href=adie.html><font color=#ffffff>Adie</font></a><br>
	<a href=pathfinder.html><font color=#ffffff>PathFinder</font></a><br>
	<a href=calc.html><font color=#ffffff>FOX Calculator</font></a><br>
	<br>
	<a href=projects.html><font color=#ffffff>Projects</font></a><br>
	<br>
	<a href='http://fxpy.sourceforge.net'><font color=#ffffff>FXPy</font></a><br>
	<a href='http://fxruby.sourceforge.net'><font color=#ffffff>FXRuby</font></a><br>
	<a href='http://eiffelfox.sourceforge.net'><font color=#ffffff>EiffelFox</font></a><br>
        <a href='http://eevolved.com/foxhole/'><font color=#ffffff>The FOX Hole</font></a><br>
        <a href='http://takahr.dhis.portside.net/cgi-bin/rwiki.cgi?cmd=view;name=FOX+FAQ'><font color=#ffffff>Japanese Docs</font></a><br>
	<br>
	<center>
	<a href="http://www.eff.org/br"><img SRC="art/freespeach.gif" border=0></a>
	<p>
	<a href="http://www.slashdot.org"><img SRC="art/slingerzbutton1.gif" border=0></a>
	</center>


<!-- end navbar content -->

    </td>
    <td bgcolor=#ffffff>&nbsp;</td>
    <td valign=top>

<!-- start main window content -->
<center><img src='art/foxstart.png'></center>
<BR><B>QUESTIONS</B><HR>
<p>
<DIV CLASS='NEWSSECTION'>
<a href="#WINDOWSLOOK">Why does FOX look so much like Windows?</a><BR>
<a href="#MACINTOSH">Has FOX been ported to the Apple Macintosh?</a><BR>
<a href="#SYSTEMS">Which Systems are supported by FOX?</a><BR>
<a href="#SIXTYFOURBITS">Is FOX <b>`64-bit clean'</b>?</a><BR>
<a href="#ILLEGALICON">Why do I get an `illegal icon specified' message when I change some Widget's icon?</a><BR>
<a href="#UNRESOLVED">Compiling FOX as a DLL under VC++ gives me a <em>unresolved external symbol.</em>?</a><BR>
<a href="#CLIENTSERVER">When do I call <em>flush()</em>, <em>forceRefresh()</em>, <em>refresh()</em> and <em>update()</em> after a change?</a><BR>
<a href="#LAYOUT">How does layout work, exactly?</a><BR>
<a href="#CREATELATER">When I construct a window at the beginning it works but when I construct it later it doesn't.</a><BR>
<a href="#MESSAGEIDS">About numbering Message ID's.</a><BR>
<a href="#GIFFREE">The FOX web-site is now GIF-Free!</a><BR>
<a href="#MENUPANES">DialogBox with its own MenuBar dumps core.</a><BR>
<a href="#SERIALIZE">How does FXStream serialize an FXObject?</a><BR>
<a href="#CALLBACKS">Why did FOX choose the message-map based callback paradigm?</a><BR>
<a href="#AUTOGRAY">Why does a AUTOGRAY disable, but not enable the Button?</a><BR>
<a href="#NEWPLACEMENT">I get compiler errors in Visual C++ when inclusing FXArray or FXElement.</a><BR>
<a href="#COLORMAPS">My Motif application complains with messages about failing to allocate colors.</a><BR>
<a href="#IRIX">File fxpngio.cpp does not compile on IRIX 6.5.</a><BR>
<a href="#WINDOWS">Developing FOX Applications under Windows.</a><BR>
<a href="#EVENTLOOPS">Why are there various flavors of running an event loop?</a><BR>
<a href="#CONSTRUCTOR">Why do I need to declare a default contructor in my classes?</a><BR>
<a href="#DELETINGSTUFF">Which FOX objects do I need to delete to avoid memory leaks?</a><BR>
<a href="#DETACH">What's the difference between detach and delete?</a><BR>
<a href="#THREADS">Can I use multiple threads in my FOX application?</a><BR>
<a href="#CROSSCOMPILING">Can I cross compile FOX on Linux for Windows?</a><BR>
</DIV>


<P>
<P>
<B>ANSWERS</B><HR>

<P>
<P><a NAME="WINDOWSLOOK"></a><b><u>Why does FOX look so much like Windows?</u></b>

<DIV CLASS='NEWSSECTION'>
FOX looks much like Windows in part because of historical reasons, and
in part because it is intentional. Having FOX look similar to Windows
means the users of a FOX application will be able to bring to bear their
prior experience on Windows, and therefore they will be able to be productive
much quicker.
<br>But let there be no mistake about it:- for software developers, FOX
looks very differently internally.
</DIV>


<P>
<P><a NAME="MACINTOSH"></a><b><u>Has FOX been ported to the Apple Macintosh?</u></b>

<DIV CLASS='NEWSSECTION'>
First off, a Macintosh running some flavor of X11 will almost
certainly be able to run FOX.  Running natively on the Macintosh Operating System,
of course, is going to take a good deal more work.
<p>However, FOX is written to be very portable; it basically relies only on core system
facilities such as drawing primitives, mouse/keyboard event inputs, and some
operating system facilities.<p>
This means that FOX could be ported to other systems such as the Macintosh.
The author currently does not own a Macintosh, nor has access too one.
Therefore, unless some hardware is donated to the FOX Project for this purpose,
chances are slim that a software port will happen any time soon.
</DIV>


<P>
<P><a NAME="SYSTEMS"></a><b><u>Which Systems are supported by FOX?</u></b>

<DIV CLASS='NEWSSECTION'>
There are two main ports of FOX:- UNIX/X11 and MS-Windows. Specifically,
FOX is known to work on the following systems:
<ul>
<p><li><b><a href="http://www.debian.org">Linux</a></b>.
Any version of Linux should work, on any hardware.  FOX is being
developed on LINUX.

<p><li><b><a href="http://www.freebsd.org">FreeBSD</a></b>.
FreeBSD is reported to work.

<p><li><b><a href="http://www.sgi.com">SGI IRIX</a></b>.
SGI systems with IRIX 5.3 and up.  It can be compiled with GCC or
SGI's MIPS Pro C++ compiler.

<p><li><b><a href="http://www.sun.com">SunOS/Solaris</a></B>.
Either Solaris or SunOS.  Compiled with GCC or Sun Workshop C++.

<p><li><b><a href="http://www.hp.com">HP-UX</a></b>.
Tested with GCC under HP-UX 9.x and 10.x.

<p><li><b><a href="http://www.ibm.com">IBM AIX</a></b>.
Tested with GCC under AIX 4.2.

<p><li><b><a href="http://www.compaq.com">DEC Alpha/COMPAQ Tru64</a></b>.
Tested with GCC under Digital Unix 4.0.

<p><li><b>Other UNIX Systems</b>.
If you have a reasonable C++ compiler, UNIX, X11, chances are very good you can get
FOX to work.

<p><li><b><a href="http://www.microsoft.com">Microsoft Windows 2000, Windows NT 4.0, Windows 95,
Windows 98</a></b>.
Compile either with <a href="http://www.microsoft.com">Visual C++ 6.0</a>,
<a href="http://www.inprise.com/">Borland C++ Builder</a>,
<a href="http://sourceware.cygnus.com/cygwin/">CYGWIN32, MINGWIN32</a>,
and <a href="http://www.ibm.com">IBM VisualAge C++</a> for Windows.
Older versions of Visual C++ will work, but you must create your own projects
in that case.


</ul>
<p>
These are the systems we know about.  Since FOX uses GNU autoconfigure, chances
are good that most UNIX/X11 combinations can be made to work.
If you're running FOX under a system not mentioned above, please drop
<a href="mailto:jeroen@fox-toolkit.org">me a line</a> so we can add it to the list.
</DIV>


<P>
<P><a NAME="SIXTYFOURBITS"></a><b><u>Is FOX `64-bit clean'?</u></b>

<DIV CLASS='NEWSSECTION'>
With the imminent arrival of 64-bit PC's, this is a pertinent question.
Currently, FOX is being developed on lots of different systems in parallel; some of these
are 64 bit workstations, such as Digital Unix/COMPAQ Tru64 AXP CPU based systems, and
IRIX 6.x using MIPS Pro C++ in 64-bit mode.
Thus, the source code of FOX itself is definitely 64-bit clean.
</DIV>


<P>
<P><a NAME="ILLEGALICON"></a><b><u>Why do I get an `illegal icon specified' message when I change some Widget's icon?</u></b>

<DIV CLASS='NEWSSECTION'>
Basically, an Icon [Widget, Image, Font, etc] comprises a part which lives in your
program [the <b>client-side</b>], and a part which lives in the X-Server or GDI subsystem
[the <b>server-side</b>].
<p>
The C++ CTOR only builds the part in the client side.  The server side part of the
Icon [Widget, Image, etc] is realized when you call create() on it.
For convenience, all <em>reachable</em> resources may be created with a single call to <b>FXApp::create()</b>.
The call to <b>FXApp::create()</b> traverses the entire Widget tree and creates all Windows, Icons,
and other resources that are needed to realize that Widget tree on the screen.

<p>
The reasons for all this are:
<p>
<ul>
<li>Since all FOX classes may be subclassed, it cannot be
assumed that after an object's ctor has run that the object has been fully constructed;
after all, you may have subclassed it.
<p>
<li>It will also be important later on when the GUI itself will be subject to serialization.
As we can not serialize server-resident resources, we need a two-step process of construction
[via deserialization] and creation [from a single call to FXApp::create()].
</ul>

<p>
Because of this, when you construct an FXIcon later on, then you need to call <b>FXIcon::create()</b>
manually, as the icon was not a part of the Widget tree at the time the Widget tree was first realized.
</DIV>


<P>
<P><a NAME="UNRESOLVED"></a><b><u>Compiling FOX as a DLL under VC++ gives me a <em>unresolved external symbol</em>?</u></b>

<DIV CLASS='NEWSSECTION'>
If you build a project under VC++ to compile a FOX application, do not forget to specify
<b>-DFOXDLL</b> on the compiler command line.  Without it, you will get an error like:
error LNK2001: unresolved external symbol "public: static struct FXMetaClass const  FXApp::metaClass"
(?metaClass@FXApp@@2UFXMetaClass@@B).  Or words to that effect.
<p>
Of course, you can also build FOX as a static library, in which case there is no problem.
</DIV>


<P>
<P><a NAME="CLIENTSERVER"><b><u>When do I call <em>flush()</em>, <em>forceRefresh()</em>, <em>refresh()</em> and <em>update()</em> after a change?</a></u></b>

<DIV CLASS='NEWSSECTION'>
Under normal circumstances, the display on the screen is kept up-to-date automatically.
However, FOX uses a <em>lazy</em> screen refreshing technique.  The lazy technique allows
your callback routine to make lots of changes in the GUI, then update the screen in one
fell swoop.   This obviates the need that some other toolkits have for <em>freeze/thaw</em>
API's.
<p>
There are several aspects to this: repainting the screen, i.e. processing expose or repaint events,
performing layout computations, and performing GUI updating.
<ul>
<p><li><b>Repaint Events</b> are piled up until there are no further events to be processed.
In fact, repaint events are not simply saved but are conglomerated into larger and larger
rectangles, so as to minimize the number of times that repainting is actually done (it actually
also minimizes the area which is repainted).
<p><li><b>Layout Reconciliation</b> is also delayed.  No layout is performed until returning
to the event loop, in fact.  Like repainting, layout is delayed until no more events are
available.
<p><li><b>GUI Updating</b> is also delayed until there are no more events in the queue.
</ul>
<p>
The order in which these are performed are repaints, layout, and gui-updates.
Contrary to intuition, delaying the expensive operations such as repainting instead of doing them
right away is actually faster.
<p>
Sometimes, you want to force the display to refresh without returning from a callback; this
can be effected with the following routines:
<ul>
<p><li><b>FXApp::flush()</b> will flush all drawing commands to the display.
In other words, it will cause all drawing commands to be executed eventually.
Note hat flush() is moderately expensive as it causes synchronization between the display
and the program.
<p><li><b>FXApp::forceRefresh()</b> will perform a layout reconciliation, followed by a GUI update.
Since this may lead to more expose events, you typically follow a call to forceRefresh() with
a call to flush().  Note that forceRefresh() is a very expensive operation.
<p><li><b>FXApp::refresh()</b> is similar to forceRefresh() in that it causes a layout and a GUI update to
be performed.  The difference is that refresh() will not actually perform the operation but
simply cause the system to perform layout/gui-update later, after returning to the event loop.
The call to refresh() is very cheap.
<p><li><b>FXWindow::update()</b> marks the window, or part of the window as dirty.  This causes the window
to receive an expose event at some point in the future.
The rectangles marked with update() as dirty may be conglomerated into a few big rectangles.
No repainting is actually performed until returning to the event loop or calling flush().
Since no drawing is performed, a call to update() is fairly cheap.
<p><li><b>FXWindow::repaint()</b> performs the opposite of update().  It paints the window, or part of
the window by issuing SEL_PAINT messages if necessary.
It works by first pulls all outstanding expose events from the X server, compositing
the dirty rectangles.  Then, it processes all dirty rectangles pertaining to the given
window; if a rectangle is passed, it only processes the dirty rectangles overlapping with the
given rectangle.
Note that repaint() should NOT be called while performing a painting operation as it would
lead to multiple locks of the device context FXDCWindow.
<p><li><b>FXApp::repaint()</b>, does the same as FXWindow::repaint(), except FXApp::repaint()
causes ALL windows to process their backlogged SEL_PAINT messages.
<p><li><b>FXWindow::recalc()</b> marks the widget, and all of its parents, as dirty, i.e. in need of
layout.  Under normal circumstances, layout is only called when the size of a widget has changed;
however, there are often other reasons why layout is needed.  In such cases, calling recalc()
will ultimately cause a layout to happen also.  The entire chain from the widget to its top
most parent must be marked this way, otherwise (as there may have been no size changes), the
layout process will stop.  A few widgets will overload recalc() to cause additional layout
computations to happen (e.g. computing content size inside a scrolled view of a list).
</ul>
</DIV>

<P>
<P><a NAME="LAYOUT"><b><u>How does layout work, exactly?</a></u></b>

<DIV CLASS='NEWSSECTION'>
Automatic layout is a very usuful feature in FOX.  It allows automatic placement of
widgets in the desired arrangement without explicitly placing each widget in terms
of position and size.  Thus, changes in widget's contents, font, and language binding
can be accomodated with ease.
<P>
But automatic placement takes a bit of getting used to, especially for Windows developers
who are not accustomed to the concept (many UNIX GUI systems such as Xt and Motif have
similar layout facilities so UNIX programmers tend to be more familiar with the idea).
<p>
Composite widgets may contain one or more child widgets.  These child widgets could be
simple controls, like Buttons, but also other Composite widgets.  Thus, layout is inherently
a recursive process.<br>
Layout of a widget tree is determined by the following:
<ul>
<li>The arrangement pattern.  For example, a Matrix layout manager arranges the children
in rows and columns; a HorizontalFrame arranges its children side by side, and a Packer
arranges them against the sides of the interior.<br>
<li>The packing flags.  A layout manager has certain flags which apply to the layout
of all of its children.  For example the flag PACK_UNIFORM_WIDTH causes each child to
be made the same width.
<li>The layout hints.  Each child has certain layout flags which affect the way the
layout manager places that child; an example is the LAYOUT_FIX_WIDTH flag which tells
the layout manager of that child that the child wants to keep its initially assigned
width instead of its minimum (default) width. <br>
Not all layout hints are observed by the layout manager; certain arrangements interpret
certain hints, and ignore others.  For instance the Switcher layout manager places
all children on top of each other, and makes them all the same size.<BR>
<li>Other information, such as the interior padding between the edges of the layout
manager and its children, spacing between children, and other information like
the number of rows and columns in a Matrix layout manager, or which child is on top
in a Switcher layout manager, and so on.
</ul>
Layout is a recursive process, proceeding from the top down.  A layout recalculation
is needed under the following circumstances:
<ul>
<li>The widget's size has changed in response to position() or resize().
<li>The widget has been marked as dirty by means of recalc().
<li>In a few cases, layout() is called directly.
</ul>
Because layout involves a lot of calculations, its quite expensive; we therefore try
to perform it as infrequently as possible, and to stop the layout recursion as soon as we
can.
The former is implemented by performing the layout only when there's nothing better to
do, during idle time when there are no events demanding our immediate attention.
The latter is done by stopping the recursion when we hit a widget that already has the right
size and is not marked as dirty.  <br>
This makes layout pretty fast (close to real-time when interactively resizing windows).
<p>
Only a handful of API's are responsible for the whole layout process:
<ul>
<li>getDefaultWidth() and getDefaultHeight().  These API's measure the minimum size of the
widget.  For simple controls such as Buttons the implementation consists of simply adding
up the size of the icon, caption, and surrounding borders.  <br>
For layout managers however, it is more complex:- the size of the layout manager depends
on the arrangement, and the size of the children, and needs to take into account the
packing flags and layout hints as well.
<li>getWidthForHeight() and getHeightForWidth().  These measure the width of a widget
in terms of its height, and the height of a widget given its width, respectively.
In order for getWidthForHeight() to work, the height has to be known in advance.<br>
Because of these restrictions, these functions are basically only called from top level
windows, as top level windows are given a size directly by the user and therefore the
required information is known.
<li>position().  This API physcally moves a child's to its new location, and if
the child's size was changed or the child was marked as dirty, recursively invokes
layout() on the child.
<li>layout().  This is the workhorse of the layout system.  The typical implementation in
a layout manager loops over all the children, applying each child's layout hints and
default size as computed by getDefaultWidth() and getDefaultHeight(), and then placing
each child accordingly by calling position().  Note that by calling position(), the
<em>child's</em> layout() may in turn be called!
</ul>
</DIV>

<P>
<P><a NAME="CREATELATER"><b><u>When I construct a window at the beginning it works but when I construct it later it doesn't</a></u></b>

<DIV CLASS='NEWSSECTION'>
When you construct a window before calling <b>FXpp::create()</b>, the window will be created when all
windows are created.  If however you construct a window later on, then you need to call <b>window->create()</b>
yourself.
<p>
Please refer to the section about creating <a href="#ILLEGALICON">icons</a> for a more detailed explanation.
</DIV>


<P>
<P><a NAME="MESSAGEIDS"><b><u>About numbering Message ID's.</u></b></a>

<DIV CLASS='NEWSSECTION'>
When deriving classes from FOX Widgets such as FXDialogBox, make sure you're messages
are numbered so as to not conflict with those of the base classes.
The most simple way is to continue numbering from where the base class left of; I
suggest the following C++ trick:
<pre>
class MyDialog : public FXDialogBox {
  ...
  enum{
    ID_CLICKED_YES=FXDialogBox::ID_LAST,
    ID_CLICKED_NO,
    ID_CLICKED_OK,
    ID_CLICKED_CANCEL,
    ID_CLICKED_QUIT,
    ID_CLICKED_SAVE,
    ID_LAST
    };
  ...
  };
</pre>
<p>
As you see, the implementor of the base class can insert additional message ID's but the
numbering is automatically kept straight by the compiler.  Also, if you're own class
is being derived from then this derived class can start counting from MyDialog::ID_LAST
and not worry about any messages being inserted into MyDialog.
</DIV>


<P>
<p><a NAME="GIFFREE"><b><u>The FOX web-site is now GIF-Free!</u></b></a>

<DIV CLASS='NEWSSECTION'>
The FOX web site is now GIF-Free!  Please take a look at the
<a href="http://burnallgifs.org/"><b>Burn All Gifs</b></a> site to see why we've done this.
<p>
FOX does not contain any GIF compression, only decompression; from what I've
<a href="http://cloanto.com/users/mcb/19950127giflzw.html">read</a>, LZW decompression is not
subject to the patent [hence ability gzip support for the old ``compressed'' files].
I feel that there is therefore no need to remove the FOX support for GIF icons/images, and
therefore any existing investment should you have in large icon collections would be protected.
<p>
Should you still harbor any qualms about using GIF's in your project, you could of course always
use BMP icons.  Typically, GIF icons are about half the size of BMP icons.
<p>
Note that the LZW patent will expire around December 2002; after that time compressed
GIF format will therefore be reinstated.
<p>
For more, see <a href="http://lpf.ai.mit.edu/Patents/chaining-oss.html">The Case Against Software Patents</a>.
</DIV>


<P>
<P><a NAME="MENUPANES"><b><u>DialogBox with its own MenuBar dumps core.</u></b></a>

<DIV CLASS='NEWSSECTION'>
When invoking a command, my application displays a DialogBox which has its own
MenuBar.  Then the DialogBox runs modally for a while, and upon completion
it is deleted.  Some time after that the application core dumps; what gives?
<p>
The answer to the problem is that MenuPane is a self contained widget which
is <b>not owned</b> by the MenuTitle or MenuCascade; this way, the MenuPane may
be reused for example as a right-mouse popup menu.

However, as the DialogBox is deleted, some of the MenuCommands still refer to it.
Typically, it is caught during GUI update:- when MenuCommand is being updated,
it will try to send a SEL_UPDATE to the demised DialogBox, and will print out a
message such as ``<b>MenuCommand::onUpdate: references a deleted target object at
0001bcfed</b>''.
<br>
In a few cases, some other message is sent to the target first, and the application
will core dump because the target object is no longer valid.
<p>
Solution: the destructor of your DialogBox should <b>explicitly delete</b>
the MenuPane's constructed in the DialogBox.
In fact, the DialogBox's destructor should probably destroy all resources previously allocated
in the DialogBox's constructor, such as icons, images, bitmaps, and so on.
<br>
Although it is safe to do so, there is no need to delete any Widgets, however.
</DIV>


<P>
<P><a NAME="SERIALIZE"><b><u>How does FXStream serialize an FXObject?</u></b></a>

<DIV CLASS='NEWSSECTION'>
When you serialize a pointer to an object, like for example:
<pre>

  // Declarations
  <b>FXStream</b>    stream;
  <b>FXDocument</b> *document;

  // Serialize
  stream.open(FXStreamSave);
  stream &lt< document;
  stream.close();

  // Deserialize
  stream.open(FXStreamLoad);
  stream &gt> document;
  stream.close();

</pre>
What really happens when you <em>serialize</em> a pointer to an object is the following:
<p>
<ul>
<li><b>stream</b> checks an internal hash table to see if <b>document</b> has been serialized before.
<li>if it has been serialized before we just save a <b>reference number</b> into the <b>stream</b>,
and we're done.
<li>if <b>document</b> was not encountered before, <b>stream</b> saves the <b>classname</b>.
<li>then, the <b>document</b>->save(<b>stream</b>) is called to save the object's contents [member data]
into the <b>stream</b>.
</ul>
<p>
When you <em>deserialize</em> an object is:
<p>
<ul>
<li><b>stream</b> loads an item from the stream.
<li>if the item represents a <b>reference number</b>, then we must have loaded the <b>document</b>
previously; using an internal lookup table, <b>stream</b> maps <b>reference number</b> to the
memory address where <b>document</b> was loaded, and returns this address.
<li>if the item is a <b>classname</b>, then <b>stream</b> calls FXMetaClass::getMetaClassFromName(classname)
to obtain the <b>metaclass</b>, and calls <b>metaclass</b>->makeInstance() to properly manufacture an object.
<li>then, <b>stream</b> calls <b>document</b>->load(<b>stream</b>) to pull in the object's contents.
</ul>
<p>
Sometimes, a special <b>container</b> object is referred by other objects, but should <b>not</b> itself be serialized.
In this case, you may want to use the constructor:
<pre>
  <b>FXStream</b>    stream(container);
</pre>
<p>
instead. This will add the pointer <b>container</b> to the internal table of <b>stream</b>, so
that any subsequent encounter of the same pointer value will generate a reference number only.
</DIV>


<P>
<P><a NAME="CALLBACKS"><b><u>Why did FOX choose the message-map based callback paradigm?</u></b></a>

<DIV CLASS='NEWSSECTION'>
There are several different mechanisms to <em>connect</em> Widgets, the <b>sources</b> of events, and
their <b>targets</b>, or the application code that you write.<br>
I have evaluated several different callback mechanisms, each have their different
strengths and weaknesses.

<ul>
<li><b>Function pointer</b> [<em>Motif, Xt</em>].
<ul>
<p>
<li>Very dissatisfying for C++ programs, as it is not object-oriented.
<li>Extra callback parameter [call_data] is not type safe.
<li>This is mostly interesting for procedural programming styles, e.g. using C.
<li>Hard to serialize (or save to file) the connectivity.
</ul>
<BR>
<p>

<li><b>Message handling with fixed routing</b> [<em>Microsoft Foundation Classes, Borland C++ Builder</em>].
<ul>
<p>
<li>Can bind source and target together at run time.
<li>Need fixed message routing scheme, since there is no specific target.
<li>Need to keep the messages globally unique (because of the fixed message routing scheme).
<li>Message-delegation [forwarding of messages to another party] is easy.
<li>GUI widgets can not receive messages, only sent them (because of a fixed message routine scheme).
<li>May be not type-safe.
<li>Easy to serialize the connectivity.
</ul>
<BR>
<p>

<li><b>Signal/Slot</b> [<em>Qt (Preprocessor), C++ templates (Gtk--, I believe)</em>]
<ul>
<p>
<li>A special preprocessor does not seem very elegant to me [Qt].
<li>A template-based signal/slot system is elegant from a theoretical point of view.
<li>Templates are instantiated at compile time.  This means it's going to be difficult to
hook up objects which are only known at run time [like e.g. loading a custom control from a DLL].
<li>To connect a message source and a target, you actually construct a
connector object that is parameterized by the target; you can not
do this unless you know the type of the target [This is because
pointer-to-member-of-class types can only be <em>downcast</em>!].
<li>Hard to serialize, because a pointer-to-member-of-class contains a function-pointer
when the member is not a virtual.
</ul>
<BR>
<p>

<li><b>Message handling with specific target</b> [<em>FOX, NeXTSTEP (using Objective-C of course)</em>].
<ul>
<p>
<li>You can connect at run-time, because connectivity does not involve compile-time
code generation like with a signal-slot mechanism.
Run-time connectivity is needed because you may load objects dynamically from a DLL,
from deserialization, or you may want to write an GUI-Builder which interactively
connects things up.
<li>There is no need for a globally unique list of message ID's. The message is addressed
to a specific target, and the same message-ID can be reused by another target for another
purpose.<br>
<li>Widgets may receive messages as well as send them.
This is very important for component-based programming paradigms.
It is also important to note that this allows for ``glue-less'' programming; for
example, a message ID_HIDE to any Control will hide the Control.
<li>No special preprocessor is needed.  The compiler automatically keeps the message-ID's
straight [see <a href="#MESSAGEIDS">above</a>].
<li>It is not type safe, in the sense that if you do need to interpret
the void*, you would need to cast.  Note however that in the vast majority
of cases, the void* argument is not used; when it is used, the use is pretty
consistent:- what do you think the void* refers to when the message-id is
ID_SETINTVALUE?
<li>In the case of NeXTSTEP, the argument signature was a part of the message, which
means that for an object to implement the message, the signature had to match up; this
was type-safe while at the same time very flexible. <br>
Alas, FOX was written in C++, not Objective-C.
<li>You connect things simply by passing the target-pointer in the constructor
when you create a widget.
<li>FOX supports message delegation very easily.
<li>You can actually <b>turn</b> FOX into a type of <b>template-based signal/slot</b>
system of you make FXObject-derived connectors!
</ul>
</ul>
As you see, FOX's message handling system may not be type safe, but it is
<b>very compact</b>, allows for <b>run-time connectivity</b>, is </b>serializable</b>,
and favors <b>component-oriented</b> development.<br>
Were FOX written in Objective-C, one could achieve the goal of type-safety as well; C++
clearly limits our choices.
</DIV>


<P>
<P><a NAME="AUTOGRAY"><b><u>Why does a AUTOGRAY disable, but not enable the Button?</u></b></a>

<DIV CLASS='NEWSSECTION'>
<em>AUTOGRAY</em> and <em>AUTOHIDE</em> are very useful features when messages are being delegated
around, like for example in an Multiple Document Interface [MDI] application.
In an MDI application, the target which actually ends up handling the message may be different
from one moment to the next.
When no target handles the message (e.g. when all FXMDIChild windows have been deleted), an
FXButton which is set to BUTTON_AUTOGRAY will be
disabled automatically.  When there is a target, this target should enable or disable the button
as appropriate.  The FXButton does <em>not</em> automatically enable itself when there is
a target that handles the message, as it is not necessarily the case that the button should be
enabled when it does.
</DIV>


<P>
<P><a NAME="NEWPLACEMENT"><b><u>I get compiler errors in Visual C++ when inclusing FXArray or FXElement</u></b></a>

<DIV CLASS='NEWSSECTION'>
FOX uses the <em>placement</em> version of the C++ <b>new</b> operator.  Declarations for this
operator may be made available to your program by:
<pre>
  #include &lt new &gt
</pre>
just before including FXArray and FXElement.
FXArray and FXElement are not automatically included into <b>fx.h</b> because these files rely
on a proper template implementation of your compiler; also, FOX widgets do not need these headers.
</DIV>


<P>
<P><a NAME="COLORMAPS"><b><u>My Motif application complains with messages about failing to allocate colors</u></b></a>

<DIV CLASS='NEWSSECTION'>
This typically happens on PseudoColor systems, i.e. systems which use a <em>colormap</em> or <em>color palette</em>.
Even many high end SGI systems run the Motif GUI in PseudoColor mode [these systems support multiple
hardware colormaps].
FOX normally allocates about half of the available colormap [125 colors, to be exact].  Under normal
circumstances, this leaves plenty of colors for other applications.
However, sometimes of course it can happen that other X11 applications require more colors than are
available.
Fortunately, FOX can be told to use a different number of colors.  There are several ways to do
this:

<ul>
<li>The simplest way is to specify the maximum number of colors on the command line, with the parameter <b>-maxcolors <i>n</i></b>.
The number <i>n</i> should be between 2 and 256.  Setting the parameter causes FOX to allocate no more
than the indicated number of colors.   FOX will attempt to allocate a block of colors such that
nRed x nGreen x nBlue is not larged than <i>n</i>; it will favor slightly more resolution in the
green and red than in blue, because the eye is more sensitive to these colors.
<p>
<li>If you find yourself passing this parameter regularly, you may consider specifying the number of
colors using the <b>Registry</b> mechanism instead; this way, FOX applications will automatically pick
this up.  The most easy way to do this is to load the file $HOME/.foxrc/Desktop into your editor,
and adding the following to the <b>[SETTINGS]</b> group:

<pre>
[SETTINGS]
maxcolors = 64
</pre>

Of course you may specify any number you like.

<p>
<li>The last method is to specify the maximum number of colors programmatically.  In case you're
developing e.g. a data-entry application, you may not need many colors and you can simply set the
value to a fairly low value, like 27:
<pre>
FXVisual *vis = application->getDefaultVisual();
vis->setMaxColors(27);
</pre>
Of course you will need to do this prior to a call to <i>application->create()</i>.
</ul>
On some machines, you may be able to switch the video hardware into a higher color resolution,
and if this is possible, it may be by far the best solution.
</DIV>


<P>
<P><a NAME="IRIX"><b><u>File fxpngio.cpp does not compile on IRIX 6.5</u></b></a>

<DIV CLASS='NEWSSECTION'>
FOX uses <a href="http://www.fsf.org">GNU</a> autoconfigure to determine the whereabouts of
various files.  It so happens that IRIX 6.5 ships with an older release of the PNG library.
You can do two things:
<ul>
<li>Re-run configure as <b>configure --disable-png</b> to disable PNG image file support.
FOX will be fully functional, except that PNG image file support is stubbed out.<p>
<li>Obtain the PNG library libpng version 1.05 or better, and install this on your machine.
<br>
You can find PNG on: <a href="http://www.libpng.org/pub/png/">http://www.libpng.org/pub/png/</a>.
</ul>
If you choose the latter, you will of course have to make sure the configure script is
able to locate the new library; how this is done depends on where it is installed.
</DIV>


<P>
<P><a NAME="WINDOWS"><b><u>Developing FOX Applications under Windows.</u></b></a>

<DIV CLASS='NEWSSECTION'>
Developing FOX applications under Windows warrants a lot of extra information.  You can
find this <a href="win32.html">here</a>.
</DIV>


<P>
<P><a NAME="EVENTLOOPS"><b><u>Why are there various flavors of running an event loop?</u></b></a>

<DIV CLASS='NEWSSECTION'>
FOX applications are event driven applications.  All FOX applications therefore spend almost all
their time in an event loop, waiting for events [such as keyboard and mouse events] from a user.
Depending on the situation, there are several types of event loops possible:
<p>
<ul>
<li><b>FXApp::run()</b>.  This is the main event loop and it is entered when you
start your program, and does not exit until you call <b>FXApp::exit()</b>, or the
application object receives the ID_QUIT message.
Typically, after returning from FXApp::run() your program will exit.
<p>
<li><b>FXApp::runModalFor(window)</b>.  You enter this event loop to run a <em>modal dialog</em>.
A modal dialog is a dialog which will block any interaction with any other window of the
program except for the indicated dialog window, until the modal event loop is exited. <br>
FXApp::runModalFor() is a recursive invocation of the event loop, and it will not return until
<b>FXApp::stopModal(window,code)</b> is called.  The return code is passed along and will be
returned by FXApp::runModalFor().
<p>
<li><b>FXApp::runModalWhileShown(window)</b>.  This routine is a variant of FXApp::runModalFor()
which returns as soon as the window is no longer visible, or until terminated by FXApp::stopModal().
<p>
<li><b>FXApp::runUntil(condition)</b>.  This routine enters a recursive event loop, passing all
events normally.  The event loop returns as soon as the variable <em>condition</em> is set no a
non-zero value.
<p>
<li><b>FXApp::runWhileEvents()</b>.  This routine enters a recursive event loop, but returns
as soon as no current events are outstanding in the event queue.  This can be used to <em>catch up</em>
with the event stream during processing of some long computation, and then resume the computation
as soon as all events have been processed.
<p>
<li><b>FXApp::runOneEvent()</b>.  This function processes one single event and then returns.
<p>
<li><b>FXApp::peekEvent()</b>.  This tests if any events are present on the event queue, and
returns immediately with TRUE if there are, or FALSE otherwise.
</ul>
<p>
Recursive invocations of the event loop are very useful, because they allow you to temporarily
resume processing of events without returning from your message handler. <br>
The runModalFor() is especially useful if your message handler needs to display a temporary
dialog box, acquire some information from a user, and then continue processing the user
input all without returning to the main event loop.
</DIV>


<P>
<P><a NAME="CONSTRUCTOR"><b><u>Why do I need to declare a default contructor in my classes?</u></b></a>

<DIV CLASS='NEWSSECTION'>
The FXObject-derived classes need to have the <b>FXDECLARE()</b> macro in the header <b>(.h)</b> file and the
<b>FXIMPLEMENT()</b> macro in the implementation <b>(.cpp)</b> file.  The FXDECLARE macro declares
a static const member variable called <b>metaClass</b>, which is a table describing this class.  It provides some
form of runtime type information.  It also declares a virtual function <b>getMetaClass()</b> which can be used to
obtain a pointer to an objects metaclass variable; this way, one can interrogate the type of
an object.
In addition, it declares a static member function called
<b>manufacture()</b> which will construct an object of this class using the <b>default constructor</b>.
Finally, it declares two convenience functions for serialization of pointers to objects of this class.
<br>
The FXIMPLEMENT macro is used to define and fill-in the table declared using FXDECLARE.  It defines
the static member function <b>manufacture()</b>, the virtual member function <b>getMetaClass()</b>,
and fills in the static member variable <b>metaClass</b>.  If the object handles messages, it also
fills in a pointer to the message table.
</ul>
<p>
A <b>default constructor</b> needs to be defined in your class because the <b>manufacture()</b> function needs
to use the default contructor to create a properly initialized object of this type.
This is needed by the deserialization system so that it can allocate and initialize an object prior
to loading values for the persistent member variables.
</DIV>


<P>
<P><a NAME="DELETINGSTUFF"><b><u>Which FOX objects do I need to delete to avoid memory leaks?</u></b></a>

<DIV CLASS='NEWSSECTION'>
Most FOX Widgets are automatically deleted by their parent Widget.  However there are some
resources which are sharable, and these resources must be deleted explicitly by the
program in order to avoid memory leaks or other problems.
<p>
Cursors, Fonts, Images, Icons, Bitmaps, and Visuals are sharable resources which must be
cleaned up explicitly.
Because several Widgets may refer to the same icon or font, these resources are not
automatically deleted by the Widget as they may be used in another Widget.
A number of resources, such as the default cursors, the default font, and the default
visual, are automatically created by the Application object, and the Application object
also assumes responsibility to destroy these when the Application object itself is
being destroyed.
<p>
Menu panes usually refer to the Widget that owns them, and because dangling references
to a deleted owner object are not allowed, the owner Widget must make sure the Menu
panes are deleted when the owner Widget itself is.  Failing to do this will leave the
Menu pane in existence while their owner is already deleted, and this will cause
problems.
<p>
Ordinary Widgets, like Buttons, Sliders, and so on, are automatically deleted by
their parent Widget; therefore it is not necessary for your application to keep
track of them explicitly
</DIV>


<P>
<P><a NAME="DETACH"><b><u>What's the difference between detach and delete?</u></b></a>

<DIV CLASS='NEWSSECTION'>
Many FOX objects, like widgets and icons and fonts and so on, have resources which
are resident in the <b>X-Server</b> (or <b>GDI</b> in the case of Windows).  The existence of
these X-Server resident resources is manipulated through the member functions
<b>create()</b> and <b>destroy()</b>.<br>
When a program's GUI is realized, all the X-Server resident resources are automatically
created by recursively working through the entire widget tree and calling <b>create()</b>
for every reachable object. <br>
When a widget is deleted, the X-Server resident resources are released by recursing
through the widget tree and calling <b>destroy()</b>. <br>
However, <b>destroy()</b> is only called for those objects which not shared; shared
resources like icons and fonts are not destroyed because they may still be referenced from other places. <br>
On UNIX systems, it is possible to <b>fork()</b> a process, which creates a child
process which has initially all the same data as the parent.  This includes the
<b>handles</b> to the X-Server resident resources.  Of course, these resources
really belong to the parent process, and should not be references by the child
process after the fork. <br>
To clean up, a child process forked off from a parent process needs to call <b>detach()</b>.
The call to detach() will recursively work down the widget tree and detach all reachable objects
(widgets as well as sharable resources like icons and fonts) from their X-Server resident representations.
After having been detached, the objects can then be destroyed without generating a
call to <b>destroy()</b> along the way, so the child will not accidentally release
any resources which the parent process still needs.
</DIV>


<P>
<P><a NAME="THREADS"><b><u>Can I use multiple threads in my FOX application?</u></b></a>

<DIV CLASS='NEWSSECTION'>
FOX assumes one single thread to be responsible for the User Interface related tasks.
This is because certain FOX resources are not thread-safe; also, because on MS-Windows
message queues from a window are tied to the thread that created that window, it is
very important for portability reasons that it is <b><em>always the same thread</em></b>
performing the User Interface tasks.
<p>
You <em>can</em> however use any number of threads in your application, as long as they
are <b><em>worker bees</em></b>, i.e. they do not perform User Interface functions.  <p>
Synchronization between the User Interface thread and the worker threads can be performed
using a synchronization object, a pipe (UNIX/LINUX) or an event object (MS-Windows). <p>
The synchronization object is passed to FXApp::addInput() so that the User Interface thread
is awakened when the worker thread turns the synchronization object into a <em>signalled</em>
state.
</DIV>


<P>
<P><a NAME="CROSSCOMPILING"><b><u>Can I cross compile FOX on Linux for Windows?</u></b></a>

<DIV CLASS='NEWSSECTION'>
Yes.  <a href="mailto:fleck@isoc.de">Markus Fleck</a> writes:<br>
<pre>
  FROM: Markus Fleck
  DATE: 04/10/2001 09:42:55
  SUBJECT:  [Foxgui-users]Convenient cross-compiling for Win32 on Linux



  Hi!

  Below are some experiences that I thought I'd share; they're mostly of
  interest if you're a UNIX developer at heart and are forced to create Win32
  versions of your applications as well (using FOX for the GUI part, of
  course :-).

  I'm currently using FOX for cross-platform development (Linux and Win32),
  and have been using Cygwin under Windows for some time to create binaries
  for Win32. Unfortunately, Cygwin under Windows is quite slow, and tends to
  crash rather often (at least for me.)

  Recently, I came across a patched GCC cross-compiler for Win32:

    <a href="http://www.devolution.com/~slouken/SDL/Xmingw32/">http://www.devolution.com/~slouken/SDL/Xmingw32/</a>

  A Linux binary build of the cross-compiler can be downloaded from that site,
  or you can use the script at

    <a href="http://www.devolution.com/~slouken/SDL/Xmingw32/crossgcc/cross.sh">http://www.devolution.com/~slouken/SDL/Xmingw32/crossgcc/cross.sh</a>

  to automatically download, configure and build the cross-compiler from
  sources for your platform.

  The cross-compiler works like a charm; I am now able to create Win32 .EXE
  binaries in a fraction of the time that Cygwin used to require running under
  native Windows.

  Using the cross-configure.sh/cross-make.sh scripts as a starting point, even
  "configure" and "make" can be run on Linux, even though you're generating
  target code for the Win32 platform.

  I have also started to make use of "Wine" (the Linux/FreeBSD-based execution
  environment for Win32 EXE/DLL code) instead of booting into Windows for the
  purpose of testing my application; I had to uncomment (or "#if 0") the call
  to "TrackMouseEvent" in FOX's src/FXApp.cpp, though, because apparently Wine
  doesn't implement that function and aborts when it encounters a call to it.

  I also had to disable (or actually, comment out using "dnl") the invocation
  of autoconf's "AC_C_BIGENDIAN" macro in configure.in (and invoke "autoconf"
  to rebuild the "configure" script); it appears that "AC_C_BIGENDIAN" doesn't
  (yet) accept a default endianness value to use when cross-compiling, so that
  effectively the "AC_C_BIGENDIAN" test cannot be used when cross-compiling
  (yet). So in order to better support cross-compiling, configure.in should
  probably test for "ac_cv_prog_cc_cross=yes" and/or shortcut the endianness
  test if Win32 is the target platform.

  In a nutshell, I can only recommend using the GCC cross-compiler to build
  Win32 executables; it's much faster than Cygwin and much more convenient if
  you prefer to do development on a UNIX-type system. If you're using Linux
  or FreeBSD, "Wine" can give you some additional convenience when it comes
  to testing you application.
</pre>
<p>
So cross compiling is not only possible, but it works very well and may be faster
than working natively.
One note on the AC_C_BIGENDIAN thing:- you can simply pass -DFOX_BIGENDIAN=0 on
the compiler command line to override it.
</DIV>



<!-- end main window content -->

    </td>
    <td bgcolor=#ffffff>&nbsp;</td>
    <td bgcolor=#557faa width=15>&nbsp;</td>
  </tr>
  <tr>
    <td colspan=2 bgcolor="#557faa" align=center>&nbsp;
     </td>
    <td bgcolor=#ffffff valign=bottom align=left><img src=art/ill.gif width=8 height=8></td>
    <td bgcolor=#ffffff>&nbsp;</td>
    <td bgcolor=#ffffff valign=bottom align=right><img src=art/ilr.gif width=8 height=8></td>
    <td bgcolor=#557faa width=15>&nbsp;</td>
  </tr>
  <tr>
    <td valign=bottom align=left bgcolor=#557faa><img src=art/oll.gif width=8 height=8></td>
    <td colspan=4 bgcolor=#557faa>&nbsp;</td>
    <td valign=bottom align=right bgcolor=#557faa><img src=art/olr.gif width=8 height=8></td>
  </tr>
</table>

<address>Copyright 1997-2002 <a href=mailto:jeroen@fox-toolkit.org>Jeroen van der Zijp</a></address>
<!-- Created: Mon Apr 10 11:20:32 CEST 2000 -->
<!-- hhmts start -->

<!-- hhmts end -->
</body>
</html>