<html>
<head>
<link rel="stylesheet" href="page.css" type="text/css">
<title>Documentation: Messages</title>
</head>
<body bgcolor=#ffffff link=#990033 vlink=#990033 alink=#990033 text=#000000>
<!---- TOPIC TITLE WITH LOGO--->
<table border=0 cellpadding= cellspacing=2 width=100% ><tr><td><a href='http://www.fox-toolkit.org' target=_top><img src='art/foxlogo_small.jpg' border=0></a></td><td width=100% valign=bottom id="HEADLINE"><b>
Documentation: Messages <A href='messages.html' target="_top" align=left><font size=-2>[Remove Frame]</font></a>
<br><img src='art/line.gif' width=100% height=1></b></td></tr></table>
</p>
<!--- TOPIC TITLE WITH LOGO --->
<!--- TOPIC TITLE -->
<p>
<table width=100% cellpadding=0 cellspacing=2><tr><td width=100% valign=bottom id=HEADLINE><b>
Why a Target/Message System
<br><img src='art/line.gif' width=100% height=1></b></td></tr></table>
</p>
<!--- TOPIC TITLE -->
<ul>
<p>
There are many methods to connect Graphical User Interface elements
to an application code; the most common methods being used today are callback
functions. However, in C++, <I>callback</I> functions are not an
obvious choice, as the technique does not easily allow a certain object
to be specified.
</p>
<p>
Another method being used in C++ is the signal-slot technique. In its typical
implementation, <I>connector</I> objects are created that connect a signal to a slot.
However, in order to provide the necessary isolation between caller and callee,
template instantiations are involved; this limits its use to compile-time
connectivity.
</p>
<p>
The approach taken by FOX is a <I>Target/Message System</I>.
Each Widget sends its <I>message</I> to a certain object called the <B><I>target</I></B>.
As there may be multiple Widgets sending messages to one specific target,
a <B><I>message id </I></B>is used to tell them apart.
</p>
<p>
Moreover, a single Widget may be able to send several kinds of messages; this problem
is solved by typing the messages by a <B><I>message type</I></B>.
Using the message type and message id, the source and type of a GUI event or
action can be uniquely identified.<br>
Messages can be sent to any object that is derived (directly or indirectly)
from FXObject. Of course, all FOX Widgets are derived from FXObject, and so is the
FXApp application object.
<u>Thus pretty much <I>every</I> object in FOX is able to <I>receive messages.</I>
</u>
</p>
<p>
An advantage of the fact that an <I>explicit </I>object is the target
of a message (as opposed to lets say an <I>implicit</I> message routing
scheme), is the fact that message id's <I>don't </I>have to be<I> globally
unique </I>within an application; all that is required is that it is unique
for a certain class and its base classes.
</p>
<p>
This is a particularly important consideration when one considers making
<B>component oriented software</B>, where components are perhaps written by
different people, or even different organizations.
<br>
With FOX, they do not have to coordinate message id's with each other in order
for components to interact properly.<br>
Another important benefit of the target/message system is the fact that
the message a Widget sends, and the target to whom it sends it, may be
changed at <I>run time</I>.
</p>
<p>
This is an significant benefit for building programs such as GUI Builders
and other component oriented software.
Finally, since all FOX Widgets derive from FXObject, they are
capable of <B><I>receiving</I></B> messages, as well as <B><I>sending</I></B>
them.
<br>
This allows FOX Widgets to implement a number of typical commands
that are common in GUI systems; for example, consider the following code ragment:
</p>
<pre>
new FXHorizontalFrame(main,LAYOUT_SIDE_TOP|LAYOUT_FILL_X);
....
....
....
new FXMenuCommand(windowmenu,"&Toolbar",NULL,<B>toolbar</B>,FXWindow::ID_TOGGLESHOWN);
</pre>
<p>In the above example, the <B><I>toolbar</I></B> Widget is a direct target
of the MenuCommand Widget. Each time the <B><FONT FACE="Arial,Helvetica"><U>T</U>oolbar</FONT></B>
command is invoked, it will toggle the toolbar Widget on or off.
Moreover, when the GUI Update process takes place during idle time, the
MenuCommand will also send an update message to the toolbar Widget; in
response to this update, the toolbar examines its current state, and either
checks or unchecks the MenuCommand by sending it back a ID_CHECK or ID_UNCHECK
message.</p>
<p>Note that the toolbar can <I>not assume </I>that the sender of the update
message is a MenuCommand; but it <I>does</I> know its an FXObject!
So it needs to send a ID_CHECK (ID_UNCHECK) message to this object instead
of trying to call the check() or uncheck() member function of MenuCommand
directly.
<br>The above code fragment shows the flexibility of the target/message
system, especially when combined with the GUI Update idle processing capability.
The mechanism is used extensively inside FOX itself as well.
</p>
</ul>
<!--- TOPIC TITLE -->
<p>
<table width=100% cellpadding=0 cellspacing=2><tr><td width=100% valign=bottom id=HEADLINE><b>
Message Maps
<br><img src='art/line.gif' width=100% height=1></b></td></tr></table>
</p>
<!--- TOPIC TITLE -->
<ul>
<p>The messages an object receives are mapped to a specific member function
of the object by means of a <B><I>message map</I></B>. A message
map is nothing but a static, compile-time defined table which associates
one or more messages with a certain member function. Complicated
Widgets may have several dozen messages that are being mapped this way.
Message maps are un unfortunate necessity in C++ as the exact binding of
a message to a member function is performed at run time; C++ does not natively
support such dynamic binding very well.Fortunately, FOX makes it fairly easy to define those message maps by
providing a number of macros to set them up. The following code fragment
illustrates the process:</p>
<pre>
<B>FXDEFMAP</B>(FXGLViewer) FXGLViewerMap[]={
FXMAPFUNC</B>(SEL_PAINT,0,FXGLViewer::onPaint),
....</TT>
FXMAPFUNCS</B>(SEL_UPDATE,MINKEY,MAXKEY,FXGLViewer::onUpdAll),
};</TT>
<B>FXIMPLEMENT</B>(FXGLViewer,FXGLCanvas,FXGLViewerMap,<B>ARRAYNUMBER</B>(FXGLViewerMap))
</pre>
<p>The <B>FXDEFMAP</B> macro takes as the argument the name of the class.
It is used to define the entries into the message map table. The
<B>FXMAPFUNC</B>
macro takes three arguments:- first, the type of the message, second, the
id of the message, and last the member function to which this message is
being mapped. A similar macro called <B>FXMAPFUNCS</B> is used to
define a <B><I>range</I></B> of message id's instead of just one.
You can use this macro to map a many messages to one and the same member
function.</p>
<p>For example, in a calculator program you may have one button for '0',
'1', and so on till '9'. Instead of defining ten very similar member
functions, you can define just one of them. The member function can
use the macro <B>FXSELID</B>(sel) to acquire the id of the message that called
it, and <B>FXSELTYPE</B>(sel) to find the messsage type of the message.
</P>
<p>The last macro <B>FXIMPLEMENT</B> has four arguments: the name of the
class, the name of the immediate base class, a pointer to the message map,
and the number of entries in the message map. If an object does not
implement any message handlers, you may pass NULL and 0 for these last
two arguments instead. The corresponding macro in the header file
is called <B>FXDECLARE</B>.</p>
<P><FONT COLOR="#FF0000"><I>Every</I> FOX object should <B><I>always</I></B>
use <B>FXDECLARE</B> in its header file or class declaration, and <B>FXIMPLEMENT</B>
in its implementation file!</FONT></p>
<P>Besides FXMAPFUNC and FXMAPFUNCS, there are two (rarely used) macros
that key on the message type only; <B>FXMAPTYPE</B> takes just two arguments,
the message type and the member function, and <B>FXMAPTYPES</B> takes three,
the first and last message id, and the member function. FXMAPTYPE
and FXMAPTYPES will completely disregard the message id, and map any message
of the appropriate type to the indicated member function.</p>
<P>All <B>message id'</B>s should be in the range <B>MINKEY</B> to <B>MAXKEY</B>,
and all <B>message types </B>in the range <B>MINTYPE</B> to <B>MAXTYPE</B>.
In addition, the special message id of <B>zero</B> <B>(0)</B> is reserved
for system-originated messages.</p>
<P>Messages are <I>resolved to the message handler functions</I> from the
<I>derived
class </I>upward<I> to the base class.</I> This allows developers
to catch messages in their derived class, before it gets handled in the
base class. Thus, you can easily redefine behavior of FOX built-in
Widgets.</p>
<p>As the message association is performed at run time, it is common practice
to place the most-often occurring messages first in the map; this way,
the least amount of searching takes place to find them; thus, the SEL_PAINT
message is often placed first.
</P>
</ul>
<!--- TOPIC TITLE -->
<p>
<table width=100% cellpadding=0 cellspacing=2><tr><td width=100% valign=bottom id=HEADLINE><b>
Keeping Track of Message Numbering
<br><img src='art/line.gif' width=100% height=1></b></td></tr></table>
</p>
<!--- TOPIC TITLE -->
<ul>
<p>FOX does not require that all message id's be globally unique.
However, it does require that they are unique for a specific target.
The messages understood by a target are the union of the messages understood
by the target's class, and all of its base classes.
<BR>An easy way to keep the numbering straight is to use <B><I>enums</I></B>.
FOX itself uses the technique illustrated below:</p>
<pre>
class FXWindow : public FXDrawable {</FONT></TT>
...
public:
enum {
ID_SHOW=1,
ID_HIDE,
...
<B><FONT COLOR="#3366FF">
ID_LAST
</FONT></B>
};
public:
...
};
class MyWindow : public FXWindow {
...
public:
enum {
ID_MYMESSAGE=<B><FONT COLOR="#3366FF">FXWindow::ID_LAST,</FONT></B>
ID_MYOTHERMESSAGE,
...
ID_LAST
};
public:
...
};
</pre>
<p>This way, the compiler will <I>automatically</I> arrange to make sure
the numbering is correct. It is also easy to add more messages in
before ID_LAST, a recompile will adjust the message id's automatically.
Of course, you're welcome to use any other scheme if so desired; just make
sure your messages do not clash with those of the base-classes of your
object.</p>
</ul>
<!--- TOPIC TITLE -->
<p>
<table width=100% cellpadding=0 cellspacing=2><tr><td width=100% valign=bottom id=HEADLINE><b>
Message Targets should Outlive Message Sources
<br><img src='art/line.gif' width=100% height=1></b></td></tr></table>
</p>
<!--- TOPIC TITLE -->
<ul>
<p>It is obvious that when a Widget sends a message to some object, the
receiving object should of course still exist. A potential pitfall
would rear its ugly head if this were not true. Fortunately, in most
cases, Control widgets will send messages to their containing Dialog Box,
or the Application Object, or other long-lived objects. In rare cases,
you may want to make sure that as a Widget or Object is deleted, all references
to it are cleaned up as well.FOX provides two member functions:</p>
<pre>
FXWindow::setTarget(FXObject* tgt)
</pre>
<p>and</p>
<pre>
FXWindow::setSelector(FXSelector sel)
</pre>
<p>that allow you to <B><I>change</I></B> the <B><I>target</I></B>, as well
as the <B><I>message</I></B> that a Widget will send. Setting the
target of a Widget to NULL will stop it from sending any future messages
to anybody.</p>
<P>In order to catch the possibility that messages would be sent to an
object that has been destructed, FOX will<I> <B>utterly</B> <B>thrash</B>
</I>each
object in the<I> </I>destructor. Thus, if such a bug exists in an
application, it is likely to surface quickly, leading to more reliable
programs.
</P>
</ul>
<!--- TOPIC TITLE -->
<p>
<table width=100% cellpadding=0 cellspacing=2><tr><td width=100% valign=bottom id=HEADLINE><b>
Sending Your Own Messages
<br><img src='art/line.gif' width=100% height=1></b></td></tr></table>
</p>
<!--- TOPIC TITLE -->
<ul>
<p>In many cases, you will want to send messages to Widgets yourself.
For example, in an GUI update handler you may want to send a message to
the sender of the update message:</p>
<pre>
....
FXMAPFUNC(SEL_COMMAND,FXWindow::ID_TOGGLESHOWN,FXWindow::onCmdToggleShown),
// Command
FXMAPFUNC(SEL_UPDATE,FXWindow::ID_TOGGLESHOWN,FXWindow::onUpdToggleShown),
// Update
....
// Hide or show window<
long FXWindow::onCmdToggleShown(FXObject*,FXSelector,void*){
....
return 1;
}
// Update hide or show window
long FXWindow::onUpdToggleShown(FXObject* sender,FXSelector,void*){
<B><FONT COLOR="#3366FF">
sender->handle(this,shown()?FXSEL(SEL_COMMAND,ID_CHECK)
:FXSEL(SEL_COMMAND,ID_UNCHECK),NULL);</font></b>
return 1;
}
</pre>
<p>
What happens here? During GUI Updating, the Menu Command connected to
the Toolbar sends a SEL_UPDATE message [instead of the SEL_COMMAND
it sends when the command is invoked by the user].
<BR>The <B><I>onUpdToggleShown </I></B>function above determines whether
the Toolbar is currently shown, then sends a ID_CHECK or ID_UNCHECK back
to the sender.
<BR>Upon getting the ID_CHECK or ID_UNCHECK, a Menu Command object will
subsequently place or remove a little check mark in front of its label.
<BR>If the sender of the SEL_UPDATE message were some other Widget, e.g.
a Check Button, it would still work properly, although the Check Button's
implementation of the ID_CHECK and ID_UNCHECK handlers is of course completely
different.
<BR>If the sender of the SEL_UPDATE message were some completely different
Widget, it would simply ignore the return message.
</P>
<p>
By sending messages instead of calling a member function directly, the
function above does<B><I> not need to know </I></B>what <B><I>type</I></B>
of Widget sent the SEL_UPDATE message; it just sends a message back; if
the sender of the message does not understand the message, nothing happens.
Note that it is guaranteed that the sender of a message is always an object
derived from FXObject.</p>
<P>The FXSEL macro composes to 16 bit unsigned short numbers into one
32 bit unsigned int. Composing the message types and message id's
this way allows for more efficient matching of messages.
<p>
</ul>
<!--- TOPIC TITLE -->
<p>
<table width=100% cellpadding=0 cellspacing=2><tr><td width=100% valign=bottom id=HEADLINE><b>
Message Handler Return Values
<br><img src='art/line.gif' width=100% height=1></b></td></tr></table>
</p>
<!--- TOPIC TITLE -->
<ul>
<p>You may have noticed that some message handlers return <B>1</B>, and
some return <B>0</B>. The general convention is, that if the message
can be considered <B><I>handled</I></B>, i.e. it is normally processed,
the handler s<I>hould return <B>1</B></I>. <I>Otherwise, it should
return <B>0.</B></I>
<BR>Properly returning the correct return value will allow for intelligent
message routing through your application. For messages directly resulting
from a user-input event, such as button presses etc., FOX will use the
return value of the message handler to determine if the GUI needs to be
refreshed.</P>
<p>For example, if the system sent a SEL_LEFTBUTTONPRESS to your Widget,
and your Widget's handler returned <B>1</B>, it is considered handled;
next time the system goes into idle processing, all the GUI Widgets in
the application will be updated again as it is assumed that by handling
the button message, something may have changed. If your handler
had returned <B>0</B>, the message would have been considered unhandled,
and nothing further would happen.</p>
</ul>
<!--- TOPIC TITLE -->
<p>
<table width=100% cellpadding=0 cellspacing=2><tr><td width=100% valign=bottom id=HEADLINE><b>
Message Routing and Delegation
<br><img src='art/line.gif' width=100% height=1></b></td></tr></table>
</p>
<!--- TOPIC TITLE -->
<ul>
<p>Messages may be forwarded from one object to another. For example,
upon receipt of a message, a target may first try to handle the message
itself; then, if no match is found, it may try its luck by forwarding the
message to some other object. Here's how you would code this up:</p>
<pre>
// Delegate message
long MyWidget::onDefault(FXObject* sender,FXSelector key,void* data){
return delegateObject && delegateObject->handle(sender,sel,data);
}
</pre>
<p>We use here the fact that we can overload the so-called <em>default message
handler</em>, <b>onDefault()</b>. The default message handler is called when
no message binding has been found for a message.</p>
<P>In the above code fragment, <I>delegateObject</I> is assumed to be some
type of object derived from FXObject. You can use these delegation
techniques very creatively.</p>
<p>Note that you probably want to start the message id's of the delegateObject
from where the delegator MyWidget left off, i.e. make sure there is no
overlap unless its intended.</p>
<p>In a few cases, some message which would be handled by MyWidget's base class
needs to be forwarded to the delegateObject. You can easily do this by simply
mapping that message to onDefault() in MyWidget's message map:</p>
<pre>
FXMAPFUNC(SEL_COMMAND,BaseWidget::ID_DOSOMETHING,MyWidget::onDefault),
</pre>
</ul>
<!--- COPYRIGHT -->
<p>
<table width=100% cellpadding=0 cellspacing=0><tr><td width=100% valign=top id=HEADLINE align=right>
<img src='art/line.gif' width=100% height=1><font size=-1>
Copyright © 1997-2004 Jeroen van der Zijp</font>
</td></tr></table>
</p>
<!--- COPYRIGHT -->
</body>
</html>
