<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> </td>
<td bgcolor=#557faa colspan=3><font color=#ffffff size=+1><center>
<!-- Page Title -->
Documentation: Introduction
<!-- End Page Title -->
</center></font></td>
<td bgcolor=#557faa valign=top align=right> </td>
</tr>
<tr>
<td bgcolor=#557faa colspan=2> </td>
<td bgcolor=#ffffff valign=top align=left><img src=art/iul.gif width=8 height=8></td>
<td bgcolor=#ffffff> </td>
<td bgcolor=#ffffff valign=top align=right><img src=art/iur.gif width=8 height=8></td>
<td bgcolor=#557faa width=15> </td>
</tr>
<tr>
<td width=8 bgcolor=#557faa> </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> </td>
<td valign=top>
<!-- start main window content -->
<center><img src='art/foxstart.png'>
<BR><B>Documentation: Introduction</B>
</center>
<p>
<p>
<b>FOX Programming</b>
<hr>
To illustrate the facility with which you can build a FOX application,
we're going to build a few simple FOX applications. The first application
called Scribble. A picture of the Scribble application is shown below:
<br>
<br>
<br>
<br>
<center>
<p><img SRC="art/scribble.png">
<br>Fig 1. The Scribble Application.</center>
<p>Scribble demonstrates how to use the FOX Layout Managers, how to create
Buttons, and how to handle messages. Enough talk, lets start coding!
The very first thing is to include the FOX header files. This is
simple, as there is just one thing you need to include:
<br>
<ul><tt><font size=-1>#include "fx.h"</font></tt></ul>
Next, we need a top level Window object, this is a class derived from FXMainWindow.
There is only one Main Window; if you need additional toplevel windows,
you will probably derive those from FXDialogBox or FXTopWindow.
<p>In the case of Scribble, we make a class called ScribbleWindow:
<br>
<ul><tt><font size=-1>// Event Handler Object</font></tt>
<br><tt><font size=-1>class ScribbleWindow : public FXMainWindow {</font></tt>
<p><tt><font size=-1> // Macro for class hierarchy declarations</font></tt>
<br><tt><font size=-1> FXDECLARE(ScribbleWindow)</font></tt></ul>
The first line says <i>ScribbleWindow</i> is derived from <i>FXMainWindow</i>;
FXMainWindow, like most FOX classes, is derived from FXObject. Most
classes you will write in the course of programming with FOX are either
directly or indirectly derived from one single top level class called FXObject.
<p>The macro <i>FXDECLARE(ScribbleWindow)</i> declares a number of member
functions which every object derived from FXObject should have; we've used
a macro as it is always the same, and more convenient to program this way.
<p>Next, we add some member variables to keep track of the various Widgets,
and the drawing color. We also keep a flag to remember if the mouse
was down, and a flag to remember if the canvas is dirty, i.e. has been
scribbled on:
<br>
<ul><tt><font size=-1>private:</font></tt>
<p><tt><font size=-1> FXHorizontalFrame *contents;
// Content frame</font></tt>
<br><tt><font size=-1> FXVerticalFrame *canvasFrame;
// Canvas frame</font></tt>
<br><tt><font size=-1> FXVerticalFrame *buttonFrame;
// Button frame</font></tt>
<br><tt><font size=-1> FXCanvas
*canvas;
// Canvas to draw into</font></tt>
<br><tt><font size=-1> int
mdflag;
// Mouse button down?</font></tt>
<br><tt><font size=-1> int
dirty;
// Canvas has been painted?</font></tt>
<br><tt><font size=-1> FXColor
drawColor;
// Color for the line</font></tt>
</ul>
<p>
To satisfy the serialization macro, we need to furnish a default contructor:
<p>
<ul><tt><font size=-1>protected:</font></tt>
<p><tt><font size=-1> ScribbleWindow(){}</font></tt>
</ul>
<br>
<p>
FOX handles events from the user through a system of <i>messages</i> sent
to a certain <i>object</i>. In this case, the received of the messages
is the ScribbleWindow class. Thus, we need to add handler member
functions to catch these messages and perform some action in response.
All message handler functions in FOX have the same argument signature:
<br>
<ul><tt><font size=-1>long onSomeCommand(FXObject* sender,FXSelector sel,void *ptr);</font></tt></ul>
Where:
<br>
<ul><b><i>sender</i></b> is the sender object that sent the message to
us.
<br><b><i>sel </i></b>is the selector, a combination of a message type
and message id, which identifies the action being performed.
<br><b><i>ptr </i></b>is a pointer to some event-related data; usually,
this points to the FXEvent structure which contains the event that led
to the message.</ul>
For the Scribble application, we want to handle mouse messages, as
well as messages from the two buttons:
<br>
<ul><tt><font size=-1>public:</font></tt>
<br><tt><font size=-1> long onPaint(FXObject*,FXSelector,void*);</font></tt>
<br><tt><font size=-1> long onMouseDown(FXObject*,FXSelector,void*);</font></tt>
<br><tt><font size=-1> long onMouseUp(FXObject*,FXSelector,void*);</font></tt>
<br><tt><font size=-1> long onMouseMove(FXObject*,FXSelector,void*);</font></tt>
<br><tt><font size=-1> long onCmdClear(FXObject*,FXSelector,void*);</font></tt>
<br><tt><font size=-1> long onUpdClear(FXObject*,FXSelector,void*);</font></tt></ul>
ScribbleWindow also needs to define some new message ID's. A message
consists of a <b><i>type </i></b>and an <b><i>id</i></b>. The <i>type</i>
defines <i>what</i> has happened; the <i>id</i> identifies the <i>source</i>
of the message. Even though we know the object that sent us the message,
in many cases, we can be sent the same message from different sources,
and the id is much more convenient; so:
<br>
<ul><tt><font size=-1>public:</font></tt>
<br><tt><font size=-1> enum{</font></tt>
<br><tt><font size=-1> ID_CANVAS=FXMainWindow::ID_LAST,</font></tt>
<br><tt><font size=-1> ID_CLEAR,</font></tt>
<br><tt><font size=-1> ID_LAST</font></tt>
<br><tt><font size=-1> };</font></tt></ul>
<p><br>We typically define the list of messages some target understands
as an
<i>enum</i> type. As the ScribbleWindow class is derived from
FXMainWindow, it also understands all the messages already understood by
the basic FXMainWindow. Our new messages should have different numbers
from those. Rather than counting by hand, we let the compiler worry
about this by simply defining one extra message id with the name <b><i>ID_LAST</i></b>,
a subclass can simply use the ID_LAST of it's base class to start counting
its message id's from; if ever any new message id's are added to the base
class, our own messages are automatically renumbered by the compiler.
<p>We wrap up the remainder of the ScribbleApp class declaration by defining
a constructor and one member function called create():
<br>
<ul><tt><font size=-1>public:</font></tt>
<br><tt><font size=-1> ScribbleWindow(FXApp* a);</font></tt>
<br><tt><font size=-1> virtual void create();</font></tt>
<br><tt><font size=-1> };</font></tt></ul>
<p><br>In our implementation, the constructor ScribbleWindow will actually
build the GUI. The create() function is a virtual function that is
called by the system. Most FOX Widgets have this create function.
FOX Widgets have a two-stage creation process; first, the client side Widgets
are constructed, using ordinary C++ constructors. Then, once the
whole widget tree is complete, a single call to the application's create()
function will create all the windows for those widgets. This two
step process is needed as the second step may only be executed one the
connecion to the display has been established.
<p>Now, we're ready to implement this new class; in most cases, the previous
code would reside in a header file, while the implementation would be in
a C++ source file, of course. In the case of ScribbleWindow, it is
so simple that we placed everything into one file.
<p>The first thing to do is to define the <b><i>message map</i></b>.
The message map is a simple table that <i>associates </i>a<i> message type,
</i>and<i>
message id </i>to a class's<i> member function.</i> Having a message
map allows us to send any message to any [FXObject-derived] object.
<br>Thus:
<br>
<ul><tt><font size=-1>FXDEFMAP(ScribbleWindow) ScribbleWindowMap[]={</font></tt>
<p><tt><font size=-1> //________Message_Type_____________________ID_______________Message_Handler_______</font></tt>
<br><tt><font size=-1> FXMAPFUNC(SEL_PAINT,
ScribbleWindow::ID_CANVAS, ScribbleWindow::onPaint),</font></tt>
<br><tt><font size=-1> FXMAPFUNC(SEL_LEFTBUTTONPRESS,
ScribbleWindow::ID_CANVAS, ScribbleWindow::onMouseDown),</font></tt>
<br><tt><font size=-1> FXMAPFUNC(SEL_LEFTBUTTONRELEASE, ScribbleWindow::ID_CANVAS,
ScribbleWindow::onMouseUp),</font></tt>
<br><tt><font size=-1> FXMAPFUNC(SEL_MOTION,
ScribbleWindow::ID_CANVAS, ScribbleWindow::onMouseMove),</font></tt>
<br><tt><font size=-1> FXMAPFUNC(SEL_COMMAND,
ScribbleWindow::ID_CLEAR, ScribbleWindow::onCmdClear),</font></tt>
<br><tt><font size=-1> FXMAPFUNC(SEL_UPDATE,
ScribbleWindow::ID_CLEAR, ScribbleWindow::onUpdClear),</font></tt>
<br><tt><font size=-1> };</font></tt>
<br> </ul>
Note several things about this table; first, there are several messages
with the same <b><i>id</i></b>, but a different <b><i>type</i></b>. Message
types indicate what happened, for example, SEL_LEFTBUTTONPRESS means that
the left mouse button was just pressed. The message id identifies
the source. FOX defines a large collection of message types, each
of them has a specific meaning.
<p>Next, we need to implement the ``boilerplate'' stuff that the previous
FXDECLARE macro has declared:
<br>
<ul><tt>FXIMPLEMENT(ScribbleWindow,FXMainWindow,ScribbleWindowMap,ARRAYNUMBER(ScribbleWindowMap))</tt></ul>
<p><br>This the first argument of the macro should have the name of the
class, in this case ScribbleWindow; the second argument should be the name
of the class from which the class has been derived; in this case, that's
FXMainWindow. The last to arguments are a pointer to the message
map, and the number of messages in that map. FOX has a convenience
macro ARRAYNUMBER() that expands to the number of elements in a compile-time
defined array; this makes it easier to add or remove messages.
<p>If the class you're defining implements no additional messages, the
last two arguments of FXIMPLEMENT should be simply NULL and 0.
<p>The remainder of the ScribbleWindow's implementation is pretty much
ordinary C++ code. The constructor follows below:
<br>
<ul><tt><font size=-1>// Construct a ScribbleWindow</font></tt>
<br><tt><font size=-1>ScribbleWindow::ScribbleWindow(FXApp *a):FXMainWindow(a,"Scribble
Application",NULL,NULL,DECOR_ALL,0,0,800,600){</font></tt>
<p><tt><font size=-1> contents=new FXHorizontalFrame(this,LAYOUT_SIDE_TOP|LAYOUT_FILL_X|LAYOUT_FILL_Y,0,0,0,0,
0,0,0,0);</font></tt>
<p><tt><font size=-1> // LEFT pane to contain the canvas</font></tt>
<br><tt><font size=-1> canvasFrame=new FXVerticalFrame(contents,FRAME_SUNKEN|LAYOUT_FILL_X|LAYOUT_FILL_Y|LAYOUT_TOP|LAYOUT_LEFT,0,0,0,0,10,10,10,10);</font></tt>
<p><tt><font size=-1> // Label above the canvas</font></tt>
<br><tt><font size=-1> new FXLabel(canvasFrame,"Canvas
Frame",NULL,JUSTIFY_CENTER_X|LAYOUT_FILL_X);</font></tt>
<p><tt><font size=-1> // Horizontal divider line</font></tt>
<br><tt><font size=-1> new FXHorizontalSeparator(canvasFrame,SEPARATOR_GROOVE|LAYOUT_FILL_X);</font></tt>
<p><tt><font size=-1> // Drawing canvas</font></tt>
<br><tt><font size=-1> canvas=new FXCanvas(canvasFrame,this,ID_CANVAS,FRAME_SUNKEN|FRAME_THICK|LAYOUT_FILL_X|LAYOUT_FILL_Y|LAYOUT_TOP|LAYOUT_LEFT);</font></tt>
<p><tt><font size=-1> // RIGHT pane for the buttons</font></tt>
<br><tt><font size=-1> buttonFrame=new FXVerticalFrame(contents,FRAME_SUNKEN|LAYOUT_FILL_Y|LAYOUT_TOP|LAYOUT_LEFT,0,0,0,0,10,10,10,10);</font></tt>
<p><tt><font size=-1> // Label above the buttons</font></tt>
<br><tt><font size=-1> new FXLabel(buttonFrame,"Button
Frame",NULL,JUSTIFY_CENTER_X|LAYOUT_FILL_X);</font></tt>
<p><tt><font size=-1> // Horizontal divider line</font></tt>
<br><tt><font size=-1> new FXHorizontalSeparator(buttonFrame,SEPARATOR_RIDGE|LAYOUT_FILL_X);</font></tt>
<p><tt><font size=-1> // Button to clear</font></tt>
<br><tt><font size=-1> new FXButton(buttonFrame,"&Clear",NULL,this,ID_CLEAR,FRAME_THICK|FRAME_RAISED|LAYOUT_FILL_X|LAYOUT_TOP|LAYOUT_LEFT,0,0,0,0,10,10,5,5);</font></tt>
<p><tt><font size=-1> // Exit button</font></tt>
<br><tt><font size=-1> new FXButton(buttonFrame,"&Exit",NULL,getApp(),FXApp::ID_QUIT,FRAME_THICK|FRAME_RAISED|LAYOUT_FILL_X|LAYOUT_TOP|LAYOUT_LEFT,0,0,0,0,10,10,5,5);</font></tt>
<p><tt><font size=-1> // Initialize private variables</font></tt>
<br><tt><font size=-1> drawColor=FXRGB(255,0,0);</font></tt>
<br><tt><font size=-1> mdflag=0;</font></tt>
<br><tt><font size=-1> dirty=0;</font></tt>
<br><tt><font size=-1> }</font></tt>
<br> </ul>
In almost all cases, it takes just one line of C++ code to create a FOX
Widget. Typically, that is a constructor invocation. As most
FOX Widget supply convenient default parameters to the constructor, you
may not have to specify most of them.
<p>The first line in the body of the constructor creates a top level window;
toplevel windows in FOX have no parent, so pass in a pointer to the application
object (<b><i>this</i></b> in this case). The remaining parameters
are the window title, window decorations (such as resize handles, borders,
etc.), as well as the initial size and position. The initial size
and position may be ignored by your particular window manager, they are
just hints.
<p>The next line creates a FXHorizontalFrame Widget. The FXHorizontalFrame
Widget is a <a href="layout.html#LAYOUT">Layout Manager</a> that places
its children horizontally.
<p>The FXMainWindow Widget itself is also a Layout Manager, and the options
passed to the FXHorizontalFrame widget's constructor determine how
it is placed in the FXMainWindow.
<p>Next, two FXVerticalFrame widgets are created, one for the drawing Canvas
and one for the buttons. In the canvasFrame, we then place a Label,
a grooved Separator, and the Canvas for drawing into. The Canvas's
target object is ScribbleWindow (i.e. <b><i>this</i></b>), and its message
is set to ID_CANVAS. This causes Canvas to send all its messages
to the ScribbleApp object, with the ID set to ID_CANVAS.
<p>Likewise, in the right buttonFrame we place a Label, a grooved Separator,
and two Buttons. The clear button has a caption "&Clear".
The & in front of a latter will cause the Button to install a hot-key
Alt-C automatically. The caption is drawn with the C underlines,
as in "<u>C</u>lear." The target of the clear Button is again the
ScribbleApp object, and its message ID is ID_CLEAR. Likewise, the
exit Button sends ID_QUIT.
<p>Note that we didn't have to define ID_QUIT, as this is a message every
FXApp object already understands. Thus, we can simply hook
up buttons to their targets.
<p>The remaining arguments to the Buttons determine its frame style (FRAME_THICK|FRAME_RAISED),
and how it is placed inside the VerticalFrame Layout Manager (LAYOUT_FILL_X|LAYOUT_TOP|LAYOUT_LEFT)
tells the Layout Manager to stretch the Buttons to fill the available room,
making them nicely the same size.
<p>Finally, the ScribbleWindow's constructor initializes its member variables
for the drawing color and the flags.
<p>Next, we implement the create() routine:
<br>
<ul><tt><font size=-1>// Create and initialize</font></tt>
<br><tt><font size=-1>void ScribbleWindow::create(){</font></tt>
<p><tt><font size=-1> // Create the windows</font></tt>
<br><tt><font size=-1> FXMainWindow::create();</font></tt>
<p><tt><font size=-1> // Make the main window appear</font></tt>
<br><tt><font size=-1> show();</font></tt>
<br><tt><font size=-1> }</font></tt></ul>
First, we call the base classes' create; then, the main window is shown
on the screen by calling its show() member function.
<p>Now, we're ready to handle some messages:
<br>
<ul><tt><font size=-1>// Mouse button was pressed somewhere</font></tt>
<br><tt><font size=-1>long ScribbleWindow::onMouseDown(FXObject*,FXSelector,void*){</font></tt>
<p><tt><font size=-1> // While the mouse is down, we'll draw lines</font></tt>
<br><tt><font size=-1> mdflag=1;</font></tt>
<p><tt><font size=-1> return 1;</font></tt>
<br><tt><font size=-1> }</font></tt>
<br>
<p><tt><font size=-1>// The mouse has moved, draw a line</font></tt>
<br><tt><font size=-1>long ScribbleWindow::onMouseMove(FXObject*, FXSelector,
void* ptr){</font></tt>
<br><tt><font size=-1> FXEvent *ev=(FXEvent*)ptr;</font></tt>
<br><tt><font size=-1> if(mdflag){</font></tt>
<p><tt><font size=-1> // Get DC for the canvas</font></tt>
<br><tt><font size=-1> FXDCWindow dc(canvas);</font></tt>
<p><tt><font size=-1> // Set foreground color</font></tt>
<br><tt><font size=-1> dc.setForeground(drawColor);</font></tt>
<p><tt><font size=-1> // Draw line</font></tt>
<br><tt><font size=-1> dc.drawLine(ev->last_x, ev->last_y,
ev->win_x, ev->win_y);</font></tt>
<p><tt><font size=-1> // We have drawn something, so
now the canvas is dirty</font></tt>
<br><tt><font size=-1> dirty=1;</font></tt>
<br><tt><font size=-1> }</font></tt>
<br><tt><font size=-1> return 1;</font></tt>
<br><tt><font size=-1> }</font></tt>
<br>
<p><tt><font size=-1>// The mouse button was released again</font></tt>
<br><tt><font size=-1>long ScribbleWindow::onMouseUp(FXObject*,FXSelector,void*
ptr){</font></tt>
<br><tt><font size=-1> FXEvent *ev=(FXEvent*) ptr;</font></tt>
<br><tt><font size=-1> if(mdflag){</font></tt>
<br><tt><font size=-1> FXDCWindow dc(canvas);</font></tt>
<p><tt><font size=-1> dc.setForeground(drawColor);</font></tt>
<br><tt><font size=-1> dc.drawLine(ev->last_x, ev->last_y,
ev->win_x, ev->win_y);</font></tt>
<p><tt><font size=-1> // We have drawn something, so
now the canvas is dirty</font></tt>
<br><tt><font size=-1> dirty=1;</font></tt>
<p><tt><font size=-1> // Mouse no longer down</font></tt>
<br><tt><font size=-1> mdflag=0;</font></tt>
<br><tt><font size=-1> }</font></tt>
<br><tt><font size=-1> return 1;</font></tt>
<br><tt><font size=-1> }</font></tt>
<br>
<p><tt><font size=-1>// Paint the canvas</font></tt>
<br><tt><font size=-1>long ScribbleWindow::onPaint(FXObject*,FXSelector,void*
ptr){</font></tt>
<br><tt><font size=-1> FXEvent *ev=(FXEvent*)ptr;</font></tt>
<br><tt><font size=-1> FXDCWindow dc(canvas,ev);</font></tt>
<br><tt><font size=-1> dc.setForeground(canvas->getBackColor());</font></tt>
<br><tt><font size=-1> dc.fillRectangle(ev->rect.x,ev->rect.y,ev->rect.w,ev->rect.h);</font></tt>
<br><tt><font size=-1> return 1;</font></tt>
<br><tt><font size=-1> }</font></tt></ul>
<p><br>The <i>onMouseDown</i> message handler simply sets a flag to remember
than the mouse is now down; the <i>onMouseMove</i> handler draws
a line from the last to the current mouse positions; it then sets a dirty
flag to 1 to remember that the Canvas has been drawn onto. The <i>onMouseUp</i>
handler finishes the line, and resets the mouse down flag. Finally,
the <i>onPaint</i> handler repaints the canvas to the background color.
<br>Nothing remarkable here at all.
<p>The next few message handlers are more interesting:
<br>
<ul><tt><font size=-1>// Handle the clear message</font></tt>
<br><tt><font size=-1>long ScribbleWindow::onCmdClear(FXObject*,FXSelector,void*){</font></tt>
<br><tt><font size=-1> FXDCWindow dc(canvas);</font></tt>
<br><tt><font size=-1> dc.setForeground(canvas->getBackColor());</font></tt>
<br><tt><font size=-1> dc.fillRectangle(0,0,canvas->getWidth(),canvas->getHeight());</font></tt>
<br><tt><font size=-1> dirty=0;</font></tt>
<br><tt><font size=-1> return 1;</font></tt>
<br><tt><font size=-1> }</font></tt>
<br><tt><font size=-1></font></tt>
<br>
<br>
<p><tt><font size=-1>// Update the clear button</font></tt>
<br><tt><font size=-1>long ScribbleWindow::onUpdClear(FXObject* sender,FXSelector,void*){</font></tt><tt><font size=-1></font></tt>
<p><tt><font size=-1> if(dirty)</font></tt>
<br><tt><font size=-1> sender->handle(this,MKUINT(FXWindow::ID_ENABLE,SEL_COMMAND),NULL);</font></tt>
<br><tt><font size=-1> else</font></tt>
<br><tt><font size=-1> sender->handle(this,MKUINT(FXWindow::ID_DISABLE,SEL_COMMAND),NULL);</font></tt><tt><font size=-1></font></tt>
<p><tt><font size=-1> return 1;</font></tt>
<br><tt><font size=-1> }</font></tt>
<br> </ul>
The <i>onCmdClear</i> message handler clears the canvas, then resets the
dirty flag. The <i>onUpdClear</i> message handler <b><i>updates</i></b>
the clear Button.
<p>Each Widget in FOX receives a message during idle processing asking
it to be updated. For example, Buttons can be sensitized or desensitized
when the state of the application changes. In this case, we desensitize
the sender (the clear Button) when the Canvas has already been cleared,
and sensitize it when it has been painted (as indicated by the dirty flag).
<p>This GUI Update process is extremely powerful:- if an application has
N commands, and M Widgets to update for each command, one might have to
write NxM update routines; with the GUI Update process, one needs to write
only N+M routines. Moreover, if the application data change by some
other means (e.g. timers, external data inputs, mulitple computing threads,
etc), the GUI will automatically keep itself up to date without any additional
coding.
<p>To complete the Scribble Application, only one thing remains:- to kick
it all off from the main() routine:
<br>
<ul><tt><font size=-1>// Here we begin</font></tt>
<br><tt><font size=-1>int main(int argc,char *argv[]){</font></tt><tt><font size=-1></font></tt>
<p><tt><font size=-1> // Make application</font></tt>
<br><tt><font size=-1> FXApp* application=new FXApp("Scribble","Test");</font></tt>
<br><tt><font size=-1> </font></tt>
<br><tt><font size=-1> // Start app</font></tt>
<br><tt><font size=-1> application->init(argc,argv);</font></tt><tt><font size=-1></font></tt>
<p><tt><font size=-1> // Scribble window</font></tt>
<br><tt><font size=-1> new ScribbleWindow(application);</font></tt>
<br><tt><font size=-1> </font></tt>
<br><tt><font size=-1> // Create the application's windows</font></tt>
<br><tt><font size=-1> application->create();</font></tt>
<br><tt><font size=-1> </font></tt>
<br><tt><font size=-1> // Run the application</font></tt>
<br><tt><font size=-1> application->run();</font></tt>
<br><tt><font size=-1> </font></tt>
<br><tt><font size=-1> return 0;</font></tt>
<br><tt><font size=-1> }</font></tt>
<br><tt><font size=-1></font></tt> </ul>
First, we construct a FXApp object by calling<i> new FXApp("Scribble","Test").</i>
The first string is the name of the application `Scribble' is often referred
to as the Application Key, while the second string`Test' is called the
Vendor Key. Together, these two strings are used to determine the
application's registry- or preference-settings.
<p>The call to <i>application->init(argc,argv) </i>initializes the application;
argc and argv of the command line are passed in so that the FOX system
can filter out some FOX-specific command line arguments, such as for example
the <i>-display</i> parameter.
<p>The call <i>new ScribbleWindow(application)</i><tt><font size=-1> </font></tt>builds
the entire GUI for our application; the GUI consists essentially of two
parts:- the <i>client-side </i>resources, which live in our own process,
and the <i>server-side</i> resources which live in the X server (X11) or
GDI (Windows).
<br>When we construct a FOX widget, only the client-side resources are
determined. A subsequent call to <i>application->create()</i> recursively
creates all server-side resources for each widget that has been previously
constructed.
<p>Finally, <i>application->run()</i> member function is called to run
the application. This function never returns.
<br>
<p>
<b>Recap</b>
<hr>
<p>In the previous example, several FOX features have been discussed:
<br>
<ul>
<li>
Building applications using FOX means <b><i>building</i></b> more C++ classes;
these new classes should always be derived from FXObject, either directly
or indirectly. The sophisticated developer will try and make these
new classes general, so that he/she may use these again in some other project.
Thus, the development effort may be leveraged many times over.<br>
<BR></li>
<li>
FOX uses a target/message system; Each message handler has three arguments:-
the sender of the message, which is always an object derived from FXObject,
the message selector, which is a combination of the message <b><i>type</i></b>
and message <b><i>id</i></b>, and a void pointer which may provide additional
information about the message. The message type identifies the type
of action that occurred, whereas the message id identifies the source of
the message; it makes the message unique.<br>
<BR></li>
<li>
When <b><i>defining</i></b> new messages, use <b><i>enums</i></b>.
The first new message for a derived class should be equal to the base classes
ID_LAST. This way, the compiler takes care of unique message numbering.
Note that messages should be <i><b>unique</b> </i>with respect to <i><b>a
specific target</b> </i>only:- unrelated targets do not have to be unique.
If the class you're writing may be subclassed later, define a message ID_LAST,
so that the subclass may define additional message id's starting from that
point.<br>
<BR></li>
<li>
Major FOX building blocks already understand a bunch of messages; for example,
FXApp understands the message ID_QUIT. This means that in many cases,
simple <b><i>glue-cod</i></b>e may be avoided.<br>
<BR></li>
<li>
During idle processing, FOX <b><i>automatically updates </i></b>eachWidget<b><i>,</i></b>
by asking the Widget's target what its state should be; the message being
sent to the target object is of type SEL_UPDATE. The GUI Update process
is an important tool to use for large-scale applications, where multiple
developers may not even be aware of which widgets may need updating when
some data structure changes. With GUI Updating, it is easy to keep
it consistent.<br>
<BR></li>
<li>
Hot Keys may be set on Button captions simply by prefixing the hotkey latter
with an <b><i>&</i></b>. The indicated letter will be automatically
underlined.<br>
<BR></li>
<li>
FOX uses a two-step process to build its Widgets; in the construction phase,
C++ data structures are built, and member data are filled in; in the second
phase, the connection to the display is established, and actual windows
are created for each Widget.</li>
</ul>
<!-- end main window content -->
</td>
<td bgcolor=#ffffff> </td>
<td bgcolor=#557faa width=15> </td>
</tr>
<tr>
<td colspan=2 bgcolor="#557faa" align=center>
</td>
<td bgcolor=#ffffff valign=bottom align=left><img src=art/ill.gif width=8 height=8></td>
<td bgcolor=#ffffff> </td>
<td bgcolor=#ffffff valign=bottom align=right><img src=art/ilr.gif width=8 height=8></td>
<td bgcolor=#557faa width=15> </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> </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>
