<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: DataTargets
<!-- 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: DataTargets</B>
</center>
<p>
<p>
<b>Using FXDataTarget</b>
<hr>
<font color="#000000">A common application of GUI development is the
collection of inputs from the user in the form of booleans, numbers and
strings of text. This usually involves building a dialog panel with
a collection of controls such as text fields, sliders, and other input
controls. The GUI developer then would write callback handler functions
so as to be notified when any of these controls changes value. Often,
the developer is forced to fill up these controls to reflect the initial
suggested values.</font>
<p><font color="#000000">This process is common enough that we have found
that it makes sense to support it with a much more declarative programming
style:- instead of writing many callback routines, and routines to
preset the GUI controls with their initial value, we have implemented a
more easy to use method in the form of the FOX FXDataTarget class.</font>
<p><font color="#000000">The FXDataTarget acts as an intermediary between
a program variable, such as an integer or string, and a FOX widget such
as a FXTextField or FXSlider. The FXDataTarget works by associating
a variable in the application code with one or more control widgets in
the GUI. Several controls may be connected to the same data target,
although each data target is associated with only one variable at a time.</font>
<p><font color="#000000">A FXDataTarget forms a bi-directional channel
through which a GUI control can communicate with a variable in an application
program. Thus, once the GUI is created and connected via the FXDataTarget,
the GUI controls will automatically display the current value of that variable,
and when the user starts interacting with a control, the variable will
be automatically changed. Moreover, if several GUI controls are connected
to one single FXDataTarget, each of these controls will automatically update
when the variable has been changed.</font>
<p>
<p>
<b>Example Usage</b>
<hr>
<font color="#000000">Suppose you are writing a program to enter personnel
data by means of a dialog. One or the first things you may want to
do is to design a data structure which is to hold this information:</font>
<br>
<center><table BORDER CELLSPACING=0 COLS=1 WIDTH="90%" BGCOLOR="#FFF8E1" NOSAVE >
<tr>
<td><tt>// Employee record</tt>
<br><tt>struct Employee {</tt>
<br><tt> FXString name;</tt>
<br><tt> FXint number;</tt>
<br><tt> FXdouble salary;</tt>
<br><tt> FXString address;</tt>
<br><tt> };</tt></td>
</tr>
</table></center>
<p>Lets make a dialog box which obtains this information from the user,
and of course we'll use the FXDataTargets to eliminate as much coding as
possible; first comes the header file (we'll omit some details in the interest
of brevity):
<br>
<br>
<center><table BORDER CELLSPACING=0 COLS=1 WIDTH="90%" BGCOLOR="#FFF8E1" NOSAVE >
<tr>
<td><tt>/* EmployeeEntry.h */</tt>
<p><tt>// Employee Information Entry Dialog</tt>
<br><tt>class EmployeeEntry : public FXDialogBox {</tt>
<br><tt> FXDECLARE(EmployeeEntry)</tt>
<br><tt>public:</tt>
<br><tt> Employee record; // Record we'll be modifying</tt>
<br><tt>private:</tt>
<br><tt> FXDataTarget nameTarget;</tt>
<br><tt> FXDataTarget numberTarget;</tt>
<br><tt> FXDataTarget salaryTarget;</tt>
<br><tt> FXDataTarget addressTarget;</tt>
<br><tt>public:</tt>
<br><tt> EmployeeEntry(FXWindow* owner);</tt>
<br><tt> };</tt></td>
</tr>
</table></center>
<p>Well, that's basically it. Now for the implementation file:
<br>
<br>
<center><table BORDER CELLSPACING=0 COLS=1 WIDTH="90%" BGCOLOR="#FFF8E1" NOSAVE >
<tr>
<td><tt>/* EmployeeEntry.cpp */</tt>
<br><tt>#include "EmployeeEntry.h"</tt>
<p><tt>FXIMPLEMENT(EmployeeEntry,FXDialogBox,NULL,0)</tt>
<p><tt>EmployeeEntry::EmployeeEntry(FXWindow* owner):</tt>
<br><tt> FXDialogBox(owner,"Enter Employee Information"),</tt>
<br><tt> nameTarget(record.name),</tt>
<br><tt> numberTarget(record.number),</tt>
<br><tt> salaryTarget(record.salary),</tt>
<br><tt> addressTarget(record.address){</tt>
<p><tt> ...</tt>
<br><tt> new FXTextField(frame,5,&nameTarget,FXDataTarget::ID_VALUE,...);</tt>
<br><tt> new FXSpinner(frame,5,&numberTarget_target,FXDataTarget::ID_VALUE,...);</tt>
<br><tt> new FXTextField(frame,5,&addressTarget,FXDataTarget::ID_VALUE,...);</tt>
<br><tt> new FXSlider(frame,&salaryTarget,FXDataTarget::ID_VALUE,...);</tt>
<br><tt> new FXTextField(frame,5,&salaryTarget,FXDataTarget::ID_VALUE,...);</tt>
<br><tt> ...</tt>
<br><tt> new FXButton(frame,"Cancal",NULL,this,FXDialogBox::ID_CANCEL,...);</tt>
<br><tt> new FXButton(frame,"Accept",NULL,this,FXDialogBox::ID_ACCEPT,...);</tt>
<br><tt> }</tt></td>
</tr>
</table></center>
<p>We have of course omitted some details here regarding the layout and
other visual paraphernalia. Note that we have connected
the data target controlling the <b>salary </b>member to both a text field
as well as a slider, so we can set the salary either way. So far,
it sounds rediculously simple, doesn't it? The secret is, it really is!
<p>Next, we're getting ready to use this new panel. Here's how we
would do that. Lets say we have selected the employee from a big
array of employee records, and we enter the following callback handler
to edit one of the entries in this array:
<br>
<br>
<center><table BORDER CELLSPACING=0 COLS=1 WIDTH="90%" BGCOLOR="#FFF8E1" NOSAVE >
<tr>
<td><tt>/* EmployeeDatabase.cpp */</tt>
<br><tt>#include "EmployeeEntry.h"</tt>
<p><tt> ...</tt>
<p><tt>Employee *employeedatabase; // Database
of records</tt>
<br><tt>int currentemployee;
// Current employee number we're going to edit</tt>
<br><tt>int numberofemployees;
// Total number</tt>
<p><tt> ...</tt>
<p><tt>long EmployeeDatabase::onCmdChangeInformation(FXObject*,FXSelector,void*){</tt>
<br><tt> EmployeeEntry dialog(mainwindow);</tt>
<br><tt> dialog.record=employeedatabase[currentemployee];
// We will work on the copy</tt>
<br><tt> if(dialog.execute()){</tt>
<br><tt> employeedatabase[currentemployee]=dialog.record;
// We accept the change</tt>
<br><tt> }</tt>
<br><tt> return 1;</tt>
<br><tt> }</tt></td>
</tr>
</table></center>
<p>In the above code, we <i>copy</i> the employee record from the database,
and then pop up the EmployeeEntry dialog by calling its <b>execute()</b>
member function.
<p>When this dialog shows up, it will initially display the old information
from <b><tt>employeedatabase[currentemployee]</tt></b>. After editing
it with the dialog, if the user hits the <b>Accept</b> button, <b>execute()
</b>will return <b>true</b> and we copy the changed record back into the
database; if the user hit the <b>Cancel</b> button, <b>execute()</b> we
will simply do nothing and return from the callback.
<p>The EmployeeEntry dialog's destructors will automatically clean up the
mess.
<p>
<p>
<b>More Advanced Usage</b>
<hr>
<font color="#000000">The above shows the most basic usage of FXDataTarget.
It uses the <b>ID_VALUE</b> message. When a FXDataTarget receives
this message, it will ask the sender of the message for the desired value,
and then place that value into the connected program variable.</font>
<br><font color="#000000">However, the FXDataTarget also understands the
<b>ID_OPTION</b> messages. With these messages, the actual value
is encoded in the message ID itself, by adding the value to the message
ID.</font>
<br><font color="#000000">For example, to set a program variable to the
value <b>10</b>, we could send the FXDataTarget a message <b>ID_OPTION+10</b>.
With the ID_OPTION messages we can for example connect a FXDataTarget to
a number of <b>FXRadioButtons</b>, and set a program variable by clicking
on one of several radio buttons:</font>
<br><font color="#000000"></font>
<br>
<center><table BORDER CELLSPACING=0 COLS=1 WIDTH="90%" BGCOLOR="#FFF8E1" NOSAVE >
<tr>
<td><tt> enum Color {Red, Green, Blue};</tt><tt></tt>
<p><tt> FXint color;</tt>
<br><tt> FXDataTarget colorTarget(color);</tt>
<br><tt> color=Red;</tt><tt></tt>
<p><tt> new FXRadioButton(matrix,"Red",option_target,FXDataTarget::ID_OPTION+Red,...);</tt>
<br><tt> new FXRadioButton(matrix,"Green",option_target,FXDataTarget::ID_OPTION+Green,...);</tt>
<br><tt> new FXRadioButton(matrix,"Blue",option_target,FXDataTarget::ID_OPTION+Blue,...);</tt></td>
</tr>
</table></center>
<p>Here we set the variable <b>color</b> to one of the three values <b>{Red,
Green, Blue}</b> by directly connecting the FXDataTarget to three FXRadioButtons.
<br>When the FXDataTarget receives an ID_OPTION message, it changes the
program variable to (message-<b>ID_OPTION</b>). Using this method,
its easy to input<b> yes/no</b> values, lists of <b>choices</b>, and so
on, all without having to write explicit callback handlers.
<p>
<p>
<b>How It Works</b>
<hr>
<font color="#000000">The FXDataTarget idea works because of FOX's built-in
GUI Update mechanism. The GUI Update mechanism is responsible for
refreshing the state of each widget in your program, based on the state
of your application data structures. Basically, each widget periodically
inquires about its state by sending its target a <b>SEL_UPDATE</b> message.</font><font color="#000000"></font>
<p><font color="#000000">When an FXDataTarget receives a message of type
SEL_UPDATE, it reads the value of its associated variable and updates the
sender of the message by means of another message. Note that the
FXDataTarget does not need to know what type of Widget did the sending.</font><font color="#000000"></font>
<p><font color="#000000">There are two ways the FXDataTarget can receive
updates: by an <b>ID_VALUE</b> message or an <b>ID_OPTION</b> message.
The former type is usually generated by a <b>valuator control</b>, such
as an FXSlider. When a message from a valuator control is received,
FXDataTarget responds by sending back an <b>ID_SETINTVALUE, ID_SETREALVALUE,
</b>or<b> ID_SETSTRINGVALUE</b> message to the sender of the request.</font><font color="#000000"></font>
<p><font color="#000000">When a FXDataTarget receives a message of the
form (<b>ID_OPTION+i</b>), it resonds by sending back one of two
messages: <b>ID_CHECK</b> or <b>ID_UNCHECK,</b> depending on whether the
value of the associated variable is equal to<b> i</b>.</font><font color="#000000"></font>
<p><font color="#000000">In the example above, the "Red" radio button will
receive an <b>ID_CHECK</b> message, because the initial value of the variable
color is red. The other radio buttons will receive the <b>ID_UNCHECK</b>
message.</font>
<p>All of these methods explained here are deployed in the <b>datatarget</b>
example program.
<p>
<!-- 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>
distrib
>
Mandriva
>
10.0
>
i586
>
media
>
contrib
>
by-pkgid
>
a30195132950ef62bc2a088ae34f5204
>
files
>
224
