Revised documentation files.

git-svn-id: file:///fltk/svn/fltk/trunk@177 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
author: Michael R Sweet <michael.r.sweet@gmail.com> 1998-12-29 14:21:17 +0000
committer: Michael R Sweet <michael.r.sweet@gmail.com> 1998-12-29 14:21:17 +0000
commit: 87dd7f0d23eba5c09e71ec6efeb34c6844f5e95f (patch)
tree: ecd25b3fbecdd2d1c6abf106d0c94ac2b1e9926e /documentation/Fl_Widget.html
parent: 20adb6834b22523e9d1fecdb7bb8a117f7b6179a (diff)
1 files changed, 380 insertions, 0 deletions
diff --git a/documentation/Fl_Widget.html b/documentation/Fl_Widget.html
new file mode 100644
index 000000000..5509a8f85
--- /dev/null
+++ b/documentation/Fl_Widget.html
@@ -0,0 +1,380 @@
+<html>
+<body>
+
+<hr break>
+
+<h2><a name="Fl_Widget">class Fl_Widget</a></h2>
+
+<hr>
+
+<h3>Class Hierarchy</h3>
+
+<ul><pre>
+<b>Fl_Widget</b>
+   |
+   +----<a href="#Fl_Box">Fl_Box</a>, <a href="#Fl_Browser">Fl_Browser</a>, <a href="#Fl_Button">Fl_Button</a>, <a href="#Fl_Chart">Fl_Chart</a>, <a href="#Fl_Clock">Fl_Clock</a>,
+        <a href="#Fl_Free">Fl_Free</a>, <a href="#Fl_Group">Fl_Group</a>, <a href="#Fl_Input">Fl_Input</a>, <a href="#Fl_Menu_">Fl_Menu_</a>, <a href="#Fl_Positioner">Fl_Positioner</a>,
+        <a href="#Fl_Timer">Fl_Timer</a>, <a href="#Fl_Valuator">Fl_Valuator</a>
+</pre></ul>
+
+<h3>Include Files</h3>
+
+<ul><pre>
+#include &lt;FL/Fl_Widget.H>
+</pre></ul>
+
+<h3>Description</h3>
+
+<tt>Fl_Widget</tt> is the base class for all widgets in FLTK. You can't create
+one of these because the constructor is not public.  However you can
+<a href=#subclassing">subclass</a> it.
+
+<p>All "property" accessing methods, such as <tt>color()</tt>,
+<tt>parent()</tt>, or <tt>argument()</tt> are implemented as trivial inline
+functions and thus are as fast and small as accessing fields in a structure.
+Unless otherwise noted, the property setting methods such as <tt>color(n)</tt>
+or <tt>label(s)</tt> are also trivial inline functions, even if they change
+the widget's appearance.  It is up to the user code to call <tt>redraw()</tt>
+after these.
+
+<h3>Methods</h3>
+
+<center>
+<table width=90%>
+<tr>
+<td align=left valign=top>
+<ul>
+       <li><a href="#Fl_Widget.Fl_Widget">Fl_Widget</a>
+       <li><a href="#Fl_Widget.~Fl_Widget">~Fl_Widget</a>
+       <li><a href="#Fl_Widget.activate">activate</a>
+       <li><a href="#Fl_Widget.active">active</a>
+       <li><a href="#Fl_Widget.activevisible">activevisible</a>
+       <li><a href="#Fl_Widget.align">align</a>
+       <li><a href="#Fl_Widget.argument">argument</a>
+       <li><a href="#Fl_Widget.box">box</a>
+       <li><a href="#Fl_Widget.callback">callback</a>
+       <li><a href="#Fl_Widget.changed">changed</a>
+</ul>
+</td>
+<td align=left valign=top>
+<ul>
+       <li><a href="#Fl_Widget.clear_changed">clear_changed</a>
+       <li><a href="#Fl_Widget.color">color</a>
+       <li><a href="#Fl_Widget.contains">contains</a>
+       <li><a href="#Fl_Widget.damage">damage</a>
+       <li><a href="#Fl_Widget.deactivate">deactivate</a>
+       <li><a href="#Fl_Widget.default_callback">default_callback</a>
+       <li><a href="#Fl_Widget.do_callback">do_callback</a>
+       <li><a href="#Fl_Widget.h">h</a>
+       <li><a href="#Fl_Widget.hide">hide</a>
+       <li><a href="#Fl_Widget.ih">ih</a>
+</ul>
+</td>
+<td align=left valign=top>
+<ul>
+       <li><a href="#Fl_Widget.init_size">init_size</a>
+       <li><a href="#Fl_Widget.inside">inside</a>
+       <li><a href="#Fl_Widget.iw">iw</a>
+       <li><a href="#Fl_Widget.ix">ix</a>
+       <li><a href="#Fl_Widget.iy">iy</a>
+       <li><a href="#Fl_Widget.label">label</a>
+       <li><a href="#Fl_Widget.labelcolor">labelcolor</a>
+       <li><a href="#Fl_Widget.labelfont">labelfont</a>
+       <li><a href="#Fl_Widget.labelsize">labelsize</a>
+       <li><a href="#Fl_Widget.labeltype">labeltype</a>
+</ul>
+</td>
+<td align=left valign=top>
+<ul>
+       <li><a href="#Fl_Widget.parent">parent</a>
+       <li><a href="#Fl_Widget.position">position</a>
+       <li><a href="#Fl_Widget.redraw">redraw</a>
+       <li><a href="#Fl_Widget.resize">resize</a>
+       <li><a href="#Fl_Widget.selection_color">selection_color</a>
+       <li><a href="#Fl_Widget.set_changed">set_changed</a>
+       <li><a href="#Fl_Widget.show">show</a>
+       <li><a href="#Fl_Widget.size">size</a>
+       <li><a href="#Fl_Widget.type">type</a>
+       <li><a href="#Fl_Widget.user_data">user_data</a>
+</ul>
+</td>
+<td align=left valign=top>
+<ul>
+       <li><a href="#Fl_Widget.visible">visible</a>
+       <li><a href="#Fl_Widget.w">w</a>
+       <li><a href="#Fl_Widget.when">when</a>
+       <li><a href="#Fl_Widget.window">window</a>
+       <li><a href="#Fl_Widget.x">x</a>
+       <li><a href="#Fl_Widget.y">y</a>
+</ul>
+</td>
+</tr>
+</table>
+</center>
+
+<h4>Fl_Widget::Fl_Widget(int x, int y, int w, int h, const char* label=0);</h4>
+
+This is the protected constructor for an Fl_Widget, but all derived
+widgets have a matching public constructor.  It takes a value for
+x(), y(), w(), h(), and an optional value for label().
+
+<h4>virtual Fl_Widget::~Fl_Widget();</h4>
+
+Destroying single widgets is not very common.  It is your
+responsibility to either remove() them from any enclosing group, or to
+destroy that group <i>immediately</i> after destroying the children.
+
+<h4>uchar Fl_Widget::type() const;</h4>
+
+This value is used for Forms compatability and to simulate RTTI.
+
+<h4><a name="Fl_Widget.x">short Fl_Widget::x() const</a><br>
+<a name="Fl_Widget.y">short Fl_Widget::y() const</a><br>
+<a name="Fl_Widget.w">short Fl_Widget::w() const</a><br>
+<a name="Fl_Widget.h">short Fl_Widget::h() const</a></h4>
+
+The position of the upper-left corner of the widget in its enclosing
+Fl_Window (<i>not</i> its parent if that is not an Fl_Window), and its
+width and height.
+
+<h4><a name="Fl_Widget.resize">virtual void Fl_Widget::resize(int,int,int,int)</a><br>
+<a name="Fl_Widget.position">void Fl_Widget::position(short x,short y)</a><br>
+<a name="Fl_Widget.size">void Fl_Widget::size(short w,short h)</a></h4>
+
+Change the size or position of the widget.  This is a virtual function
+so the widget may implement it's own handling of resizing.  The
+default version does <i>not</i> do redraw(), that is the parent
+widget's responsibility (this is because the parent may know a faster
+way to update the display, such as scrolling from the old position).
+
+<p><tt>position(x,y)</tt> is a shortcut for <tt>resize(x,y,w(),h())</tt>,
+and <tt>size(w,h)</tt> is a shortcut for <tt>resize(x(),y(),w,h)</tt>.
+
+<h4><a name="Fl_Widget.ix">short Fl_Widget::ix() const</a><br>
+<a name="Fl_Widget.iy">short Fl_Widget::iy() const</a><br>
+<a name="Fl_Widget.iw">short Fl_Widget::iw() const</a><br>
+<a name="Fl_Widget.ih">short Fl_Widget::ih() const</a><br>
+<a name="Fl_Widget.init_size">void Fl_Widget::init_size(int,int,int,int)</a></h4>
+
+The initial size and position of the widget.  This is a copy of the
+arguments that the constructor was called with.  This information is
+used by <a href="#Fl_Group"><tt>Fl_Group</tt></a> to calculate new sizes of
+the children when they are resized.
+
+<p><tt>init_size()</tt> calls <tt>resize()</tt> with the passed sizes,
+and then replaces the initial size with the new values.  If this widget
+is a group you will have to init_size all the children as well or
+unpredictable results will occur.
+
+<h4><a name="Fl_Widget.window">Fl_Window* Fl_Widget::window() const;</a></h4>
+
+Return a pointer to the <a href="#Fl_Window"><tt>Fl_Window</tt></a>
+that this widget is in (it will skip any and all parent widgets between
+this and the window).  Returns NULL if none.  Note: for an
+<tt>Fl_Window</tt>, this returns it's <i>parent</i> window (if any),
+not <i>this</i> window.
+
+<h4><a name="Fl_Widget.box">Fl_Boxtype Fl_Widget::box() const<br>
+void Fl_Widget::box(Fl_Boxtype)</a></h4>
+
+The <tt>box()</tt> identifies a routine that draws the background of the
+widget.  See <a href="#BoxTypes">Box Types</a> for the available
+types.  The default depends on the widget, but is usually <tt>FL_NO_BOX</tt>
+or <tt>FL_UP_BOX</tt>.
+
+<h4><a name="Fl_Widget.color">Fl_Color Fl_Widget::color() const<br>
+void Fl_Widget::color(Fl_Color)</a></h4>
+
+This color is passed to the box routine.  Color is an index into an
+internal table of rgb colors.  For most widgets this defaults to
+<tt>FL_GRAY</tt>.  See the <a href="#Enumerations">enumeration list</a>
+for predefined colors.  Use
+<a href="#set_color"><tt>Fl::set_color()</tt></a> to redefine colors.
+
+<h4><a name="Fl_Widget.selection_color">Fl_Color Fl_Widget::selection_color() const<BR>
+void Fl_Widget::selection_color(Fl_Color)</a><br>
+void Fl_Widget::color(Fl_Color, Fl_Color)</h4>
+
+For Forms compatibility a second color is defined.  This is usually
+used to color the widget when it is selected, although some widgets
+use this color for other purposes.  You can set both colors at once
+with <tt>color(a,b)</tt>.
+
+<h4><a name="Fl_Widget.label">const char* Fl_Widget::label() const<br>
+void Fl_Widget::label(const char*)</a></h4>
+
+The label is printed somewhere on the widget or next to it.  The
+string is <i>not</i> copied, the passed pointer is stored unchanged in
+the widget.
+
+<h4><a name="Fl_Widget.labeltype">void Fl_Widget::label(Fl_Labeltype, const char*)<br>
+uchar Fl_Widget::labeltype() const<br>
+void Fl_Widget::labeltype(Fl_Labeltype)</a></h4>
+
+A <a href=#LabelTypes><tt>labeltype</tt></a> identifies a routine that
+draws the label of the widget.  This can be used for special effects
+such as emboss, or to use the <tt>label()</tt> pointer as another form
+of data such as a bitmap.  The value <tt>FL_NORMAL_LABEL</tt> prints
+the label as text.
+
+<h4><a name="Fl_Widget.align">Fl_Align Fl_Widget::align() const<br>
+void Fl_Widget::align(Fl_Align)</a></h4>
+
+How the label is printed next to or inside the widget.  The default
+value is <tt>FL_ALIGN_CENTER</tt>, which centers the label.  The value
+can be any of these constants or'd together:
+
+<tt><ul>
+<li>FL_ALIGN_CENTER
+<li>FL_ALIGN_TOP
+<li>FL_ALIGN_BOTTOM
+<li>FL_ALIGN_LEFT
+<li>FL_ALIGN_RIGHT
+<li>FL_ALIGN_INSIDE
+<li>FL_ALIGN_CLIP
+<li>FL_ALIGN_WRAP
+</ul></tt>
+
+<h4><a name="Fl_Widget.labelcolor">Fl_Color Fl_Widget::labelcolor() const<br>
+void Fl_Widget::labelcolor(Fl_Color)</a></h4>
+
+This color is passed to the labeltype routine, and is typically the
+color of the label text.  This defaults to <tt>FL_BLACK</tt>.
+
+<h4><a name="Fl_Widget.labelfont">Fl_Font Fl_Widget::labelfont() const<br>
+void Fl_Widget::labelfont(Fl_Font)</a></h4>
+
+Fonts are identified by small 8-bit indexes into a table.  See the
+<a href="#Enumerations">enumeration list</a> for predefined typefaces. The
+default value uses a Helvetica typeface (Arial for Microsoft&reg;
+Windows&reg;).  The function <a href="#set_font"><tt>Fl::set_font()
+</tt></a> can define new typefaces.
+
+<h4><a name="Fl_Widget.labelsize">uchar Fl_Widget::labelsize() const<br>
+void Fl_Widget::labelsize(uchar)</a></h4>
+
+Fonts are further identified by a point size.  The default is 14.
+
+<h4><a name="Fl_Widget.callback">typedef void (Fl_Callback)(Fl_Widget*, void*)<br>
+Fl_Callback* Fl_Widget::callback() const<br>
+void Fl_Widget::callback(Fl_Callback*, void* = 0)</a></h4>
+
+Each widget has a single callback.  You can set it or examine it with
+these methods.
+
+<h4><a name="Fl_Widget.user_data">void* Fl_Widget::user_data() const<br>
+void Fl_Widget::user_data(void*)</a></h4>
+
+You can also just change the <tt>void *</tt> second argument to the callback
+with the <tt>user_data</tt> methods.
+
+<h4><a name="Fl_Widget.argument">void Fl_Widget::callback(void (*)(Fl_Widget*, long), long = 0)<br>
+long Fl_Widget::argument() const<br>
+void Fl_Widget::argument(long)</a></h4>
+
+For convenience you can also define the callback as taking a long
+argument.  This is implemented by casting this to a
+<tt>Fl_Callback</tt> and casting the <tt>long</tt> to a <tt>void *</tt>
+and may not be portable to some machines.
+
+<h4>void Fl_Widget::callback(void (*)(Fl_Widget*))</h4>
+
+For convenience you can also define the callback as taking only one
+argument.  This is implemented by casting this to a
+<tt>Fl_Callback</tt> and may not be portable to some machines.
+
+<h4><a name="Fl_Widget.do_callback">void Fl_Widget::do_callback()<br>
+void Fl_Widget::do_callback(Fl_Widget*, void* = 0)<br>
+void Fl_Widget::do_callback(Fl_Widget*, long)</a></h4>
+
+You can cause a widget to do its callback at any time, and even pass
+arbitrary arguments.
+
+<h4><a name="Fl_Widget.changed">int Fl_Widget::changed() const</a><br>
+<a name="Fl_Widget.set_changed">void Fl_Widget::set_changed()</a><br>
+<a name="Fl_Widget.clear_changed">void Fl_Widget::clear_changed()</a></h4>
+
+<tt>Fl_Widget::changed()</tt> is a flag that is turned on when the user
+changes the value stored in the widget.  This is only used by
+subclasses of <tt>Fl_Widget</tt> that store values, but is in the base
+class so it is easier to scan all the widgets in a panel and
+<tt>do_callback()</tt> on the changed ones in response to an "OK"
+button.
+
+<p>Most widgets turn this flag off when they do the callback, and when
+the program sets the stored value.
+
+<h4><a name="Fl_Widget.when">Fl_When Fl_Widget::when() const<br>
+void Fl_Widget::when(Fl_When)</a></h4>
+
+<tt>Fl_Widget::when()</tt> is a set of bitflags used by subclasses of
+<tt>Fl_Widget</tt> to decide when to do the callback.  If the value is
+zero then the callback is never done.  Other values are described in
+the individual widgets.  This field is in the base class so that you
+can scan a panel and <tt>do_callback()</tt> on all the ones that don't
+do their own callbacks in response to an "OK" button.
+
+<h4><a name="Fl_Widget.default_callback">static void Fl_Widget::default_callback(Fl_Widget*, void*)</a></h4>
+
+The default callback, which puts a pointer to the widget on the queue
+returned by <a href="#readqueue"><tt>Fl::readqueue()</tt></a>.  You
+may want to call this from your own callback.
+
+<h4><a name="Fl_Widget.visible">int Fl_Widget::visible() const</a><br>
+<a name="Fl_Widget.show">void Fl_Widget::show()</a><br>
+<a name="Fl_Widget.hide">void Fl_Widget::hide()</a></h4>
+
+An invisible widget never gets redrawn and does not get events.  An
+widget is really visible if <tt>visible()</tt> is true on it <i>and all
+it's parents</i>.  Changing it will send <tt>FL_SHOW</tt> or
+<tt>FL_HIDE</tt> events to the widget.  <i>Do not change it if the
+parent is not visible, as this will send false <tt>FL_SHOW</tt> or
+<tt>FL_HIDE</tt> events to the widget</i>.  <tt>redraw()</tt> is called
+if necessary on this or the parent.
+
+<h4><a name="Fl_Widget.active">int Fl_Widget::active() const</a><br>
+<a name="Fl_Widget.activate">void Fl_Widget::activate()</a><br>
+<a name="Fl_Widget.deactivate">void Fl_Widget::deactivate()</a><br></h4>
+
+<tt>Fl_Widget::active()</tt> returns whether the widget is active.  An
+inactive widget does not get any events, but it does get redrawn.  A
+widget is active if <tt>active()</tt> is true on it <i>and all it's
+parents</i>. Changing this value will send <tt>FL_ACTIVATE</tt> or
+<tt>FL_DEACTIVATE</tt> to the widget.  <i>Do not change it if the
+parent is not active, as this will send false <tt>FL_ACTIVATE</tt> or
+<tt>FL_DEACTIVATE</tt> events to the widget</i>.
+
+<p>Currently you cannot deactivate <tt>Fl_Window</tt> widgets.
+
+<h4><a name="Fl_Widget.activevisible">int Fl_Widget::activevisible() const</a></h4>
+
+This is the same as <tt>active() &amp;&amp; visible()</tt> but is faster.
+
+<h4><a name="Fl_Widget.redraw">void Fl_Widget::redraw()</a></h4>
+
+Mark the widget as needing its <tt>draw()</tt> routine called.
+
+<h4><a name="Fl_Widget.damage">uchar Fl_Widget::damage() const</a></h4>
+
+Non-zero if <tt>draw()</tt> needs to be called.  Actually this is a bit
+field that the widget subclass can use to figure out what parts to
+draw.
+
+<h4><a name="Fl_Widget.parent">Fl_Widget *Fl_Widget::parent() const</a></h4>
+
+Returns a pointer to the parent widget.  Usually this is a
+<a href="#Fl_Group"><tt>Fl_Group</tt></a> or
+<a href="Fl_Window><tt>Fl_Window</tt></a>.  Returns <tt>NULL</tt> if none.
+
+<h4><a name="Fl_Widget.contains">int Fl_Widget::contains(Fl_Widget* b) const</a></h4>
+
+Returns true if <tt>b</tt> is a child of this widget, or is equal to
+this widget.  Returns false if <tt>b</tt> is <tt>NULL</tt>.
+
+<h4><a name="Fl_Widget.inside">int Fl_Widget::inside(const Fl_Widget* a) const</a></h4>
+
+Returns true if this is a child of <tt>a</tt>, or is equal to <tt>a</tt>.
+Returns false if <tt>a</tt> is <tt>NULL</tt>.
+
+</body>
+</html>
author	Michael R Sweet <michael.r.sweet@gmail.com>	1998-12-29 14:21:17 +0000
committer	Michael R Sweet <michael.r.sweet@gmail.com>	1998-12-29 14:21:17 +0000
commit	87dd7f0d23eba5c09e71ec6efeb34c6844f5e95f (patch)
tree	ecd25b3fbecdd2d1c6abf106d0c94ac2b1e9926e /documentation/Fl_Widget.html
parent	20adb6834b22523e9d1fecdb7bb8a117f7b6179a (diff)