<html>
<head>
<link rel="stylesheet" href="page.css" type="text/css">
<title>Documentation: Writing your very own Widgets</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: Writing your very own Widgets <A href='widgets.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 --->
<ul>
<p>FOX makes it very easy to build your own widgets.
It was designed to do this from the ground up. This is actually one
of the prime benefits of FOX <I>vis-a-vis</I> other widget libraries.
As FOX is completely written in C++, and most important functions are overloadable,
writing your own widget typically entails picking an existing widget class
which looks close to the one you want, and then redefining selected aspects
of that widget by subclassing it.</p>
<P>We illustrate this process with an example from
FOX itself:- the FXProgressBar widget. First, you pick which widget
to subclass from; in this case, we subclass of of FXFrame, as the progress
bar widget needs to inherit the margins and borders from FXFrame.</p>
<p>In terms of C++ code, this means:</p>
<pre>
class FXProgressBar: public FXFrame {
FXDECLARE(FXProgressBar)
</pre>
<p>The FXDECLARE() macro establishes some boilerplate member functions that
every class derived from FXObject should redefine. Next, we add some member
data. In the case, we want to add:</p>
<pre>
protected:
FXuint progress; // Integer percentage number
FXuint total; // Amount for completion
FXint barsize; // Bar size
FXFont* font; // Font used for the percentage text
FXPixel barBGColor; // Background color of bar
FXPixel barColor; // Bar color
FXPixel textNumColor; // Text color outside of bar
FXPixel textAltColor; // Text color inside of bar
</pre>
<p>There is nothing unusual about this. Standard C++ programming practice!
Next, we make the default and copy constructors protected; while this is
not required, it prevents an application programmer from accidentally creating
an object with these, causing the creation of an improperly initialized
object, which will most certainly cause problems later on.</p>
<pre>
protected:
FXProgressBar(){}
FXProgressBar(const FXProgressBar&){}
</pre>
<p>So far so good. Now comes the meat. The progress bar should
of course draw itself to reflect the amount of progress. This should
look something like:</p>
<CENTER><IMG SRC="art/progress.png" HEIGHT=23 WIDTH=171 ALIGN=BOTTOM><br>Progress Bar</CENTER>
<p>This is done by implementing the onPaint() message. Every time
FOX determines that a widget needs to be repainted, for example, after
moving a window out of the way, it sends the widget a SEL_PAINT message.
This message should be intercepted by your widget so that you can make
it draw in a different manner. If you didn't intercept it, the message
would be intercepted later on by the base class, which will perform its
usual drawing behaviour. Hence, we declare the message-handling routine (handler):</p>
<pre>
public:
long onPaint(FXObject*,FXSelector,void*);
</pre>
<p>Note that the message handler should be declared public. The message
handler is passed three parameters when invoked: the object that sent it
the message, the selector, and a pointer. The sending object is in
this case the widget itself; the selector is a combination of the <I>message-type </I>and <I>message-id.</I>
<BR>The message type identifies the type of message that occurred; here
it is SEL_PAINT. The message id identifies the sender of the message;
for mesages from the system itself, this id is always set to zero (0).
The message type and id can be extracted from the selector by means of
two convenience macros: FXSELTYPE(selector) and FXSELID(selector).</p>
<p>The pointer which is passed to the message handler may refer to different
things; for system messages, however, it typically points to a data structure
called FXEvent, which contains information about the event that caused
this handler to be invoked.</p>
<P>The onPaint() handler may use the information in the FXEvent structure
to determine the rectangle that needs to be repainted. Widgets (especially
complicated ones!) should try and redraw only the indicated area.
This cuts down significantly on expensive drawing commands, as well as
reducing visual flickering on the screen.</p>
<p>Next, we define the widget's main constructor. As a first
argument, all child-widgets pass in a pointer to the parent widget (Toplevel
or <I>shell</I> widgets pass in a pointer to the application object).
Next, the layout and other options are passed, followed by the x,
y coordinate, followed by the width, and height. All of these have
default values, as in many cases the exact widget placement and size is
left to a container class such as the Packer or Matrix layout manager.</p>
<p>The options should be passed in as a <I>bit-wise <B>or</B></I> (|) of
a number of option flags. <I>Care should be taken so as to <B>not conflict</B>
with any option flags which have already been used in base classes of this
widget .</I>
<pre>
FXProgressBar(FXComposite* p,FXuint opts=(FRAME_SUNKEN|FRAME_THICK),
FXint x=0,FXint y=0,FXint w=0,FXint h=0,FXint pl=DEFAULT_PAD,
FXint pr=DEFAULT_PAD,FXint pt=DEFAULT_PAD,FXint pb=DEFAULT_PAD);
</pre>
<p>The constructor you write should simply pass the arguments to their corresponding
arguments in the base class of your class, then initialize the newly added
member data to some sensible values.
<BR>The intent is that your widget should be useful without setting additional
parameters or calling additional member functions, at least for the most
common usage of your widget.</p>
<p>In order to interact properly with the layout managers, each child widget
needs to properly compute its dimensions when asked by its parent.
The two functions involved with this are:</p>
<pre>
virtual FXint getDefaultWidth();
virtual FXint getDefaultHeight();
</pre>
<p>These two functions compute the <I>minimum</I> width and height of the
widget, given the current state of the widget. The layout managers
use this information to place the widgets properly. In the case of
the ProgressBar, for example, getDefaultWidth() computes the widget's size
based on the border, left- and right padding, current text font, whether
it is horizontal or vertical, and presence of the percentage display.</p>
<p>Next, the create() function needs to be implemented:</p>
<pre>
void create();
</pre>
<p>The create() function is called in the second stage of the widget instantiation
process. In the first stage, the C++ objects have been created, but
no windows have been associated yet with those C++ objects. The second
stage takes place when the application is instantiating the widgets, and
building X-Windows associated with the C++ objects. It does this
by recursively travering all widgets, starting from the root window.</p>
<BR>It is sometimes necessary to overload the create() routine, so as to
determine resources which were not yet known before. In the case
of the ProgressBar, until the connection with the X-Server was established,
it was not yet known which colors were going to be available, so these
colors will have to be allocated in the create() routine. Also, the create()
routine makes sure the font is available, by calling font->create() to
create the font.</p>
<p>After implementing the ordinary C++ member functions for your new widget,
you may have to define a destructor:</p>
<pre>
virtual ~FXProgressBar();
</pre>
<p>The FOX library usually implements a destructor which intentionally thrashes
the object; in this case, it sets font to (FXFont*)(-1). Thrashing
objects intentionally may cause dangling pointers etc. to be discovered
much sooner, and thus ease debugging and increase program correctness.</p>
<P>Note that FOX does not try trash the other member variables:- thrash-values
for the other variables would not be distinguishable from good values anyway.
But a thrash value for a pointer like -1 will most likely cause a SIGSEGV,
when accidentally used!!</P>
</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>
