fltk/documentation/Fl_Widget.html
Michael R Sweet 19518ebe35 Make Fl_Widget::parent() work with Fl_Group pointers...
git-svn-id: file:///fltk/svn/fltk/branches/branch-1.1@1647 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
2001-10-22 21:15:11 +00:00

311 lines
16 KiB
HTML

<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.html#Fl_Box>Fl_Box</A>, <A href=Fl_Browser_.html#Fl_Browser_>Fl_Browser_</A>, <A href=Fl_Button.html#Fl_Button>Fl_Button</A>, <A href=Fl_Chart.html#Fl_Chart>Fl_Chart</A>, <A href=Fl_Clock.html#Fl_Clock>Fl_Clock</A>,
<A href=Fl_Free.html#Fl_Free>Fl_Free</A>, <A href=Fl_Group.html#Fl_Group>Fl_Group</A>, <A href=Fl_Input_.html#Fl_Input_>Fl_Input_</A>, <A href=Fl_Menu_.html#Fl_Menu_>Fl_Menu_</A>, <A href=Fl_Positioner.html#Fl_Positioner>Fl_Positioner</A>,
<A href=Fl_Timer.html#Fl_Timer>Fl_Timer</A>, <A href=Fl_Valuator.html#Fl_Valuator>Fl_Valuator</A>
</PRE>
</UL>
<H3>Include Files</H3>
<UL>
<PRE>
#include &lt;FL/Fl_Widget.H&gt;
</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.html#subclassing">subclass</A> it.
<P>All &quot;property&quot; 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. </P>
<H3>Methods</H3>
<CENTER>
<TABLE width=90% summary="Fl_Widget methods.">
<TR><TD align=left valign=top>
<UL>
<LI><A href=#Fl_Widget.Fl_Widget>Fl_Widget</A></LI>
<LI><A href=#Fl_Widget.~Fl_Widget>~Fl_Widget</A></LI>
<LI><A href=#Fl_Widget.activate>activate</A></LI>
<LI><A href=#Fl_Widget.active>active</A></LI>
<LI><A href=#Fl_Widget.active_r>active_r</A></LI>
<LI><A href=#Fl_Widget.align>align</A></LI>
<LI><A href=#Fl_Widget.argument>argument</A></LI>
<LI><A href=#Fl_Widget.box>box</A></LI>
<LI><A href=#Fl_Widget.callback>callback</A></LI>
</UL>
</TD><TD align=left valign=top>
<UL>
<LI><A href=#Fl_Widget.changed>changed</A></LI>
<LI><A href=#Fl_Widget.clear_changed>clear_changed</A></LI>
<LI><A href=#Fl_Widget.color>color</A></LI>
<LI><A href=#Fl_Widget.contains>contains</A></LI>
<LI><A href=#Fl_Widget.damage>damage</A></LI>
<LI><A href=#Fl_Widget.deactivate>deactivate</A></LI>
<LI><A href=#Fl_Widget.default_callback>default_callback</A></LI>
<LI><A href=#Fl_Widget.do_callback>do_callback</A></LI>
<LI><A href=#Fl_Widget.h>h</A></LI>
</UL>
</TD><TD align=left valign=top>
<UL>
<LI><A href=#Fl_Widget.hide>hide</A></LI>
<LI><A href=#Fl_Widget.inside>inside</A></LI>
<LI><A href=#Fl_Widget.label>label</A></LI>
<LI><A href=#Fl_Widget.labelcolor>labelcolor</A></LI>
<LI><A href=#Fl_Widget.labelfont>labelfont</A></LI>
<LI><A href=#Fl_Widget.labelsize>labelsize</A></LI>
<LI><A href=#Fl_Widget.labeltype>labeltype</A></LI>
<LI><A href=#Fl_Widget.output>output</A></LI>
<LI><A href=#Fl_Widget.parent>parent</A></LI>
</UL>
</TD><TD align=left valign=top>
<UL>
<LI><A href=#Fl_Widget.position>position</A></LI>
<LI><A href=#Fl_Widget.redraw>redraw</A></LI>
<LI><A href=#Fl_Widget.resize>resize</A></LI>
<LI><A href=#Fl_Widget.selection_color>selection_color</A></LI>
<LI><A href=#Fl_Widget.set_changed>set_changed</A></LI>
<LI><A href=#Fl_Widget.show>show</A></LI>
<LI><A href=#Fl_Widget.size>size</A></LI>
<LI><A href=#Fl_Widget.take_focus>take_focus</A></LI>
<LI><A href=#Fl_Widget.takesevents>takesevents</A></LI>
</UL>
</TD><TD align=left valign=top>
<UL>
<LI><A href=#Fl_Widget.type>type</A></LI>
<LI><A href=#Fl_Widget.user_data>user_data</A></LI>
<LI><A href=#Fl_Widget.visible>visible</A></LI>
<LI><A href=#Fl_Widget.visible_r>visible_r</A></LI>
<LI><A href=#Fl_Widget.w>w</A></LI>
<LI><A href=#Fl_Widget.when>when</A></LI>
<LI><A href=#Fl_Widget.window>window</A></LI>
<LI><A href=#Fl_Widget.x>x</A></LI>
<LI><A href=#Fl_Widget.y>y</A></LI>
</UL>
</TD></TR>
</TABLE>
</CENTER>
<H4><A NAME="Fl_Widget.Fl_Widget">Fl_Widget::Fl_Widget(int x, int y, int w, int h, const char*
label=0);</A></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><A NAME="Fl_Widget.~Fl_Widget">virtual Fl_Widget::~Fl_Widget();</A></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><A NAME="Fl_Widget.type">uchar Fl_Widget::type() const;</A></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 x, int y, int w, int h)</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 its 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>
. </P>
<H4><A name=Fl_Widget.window>Fl_Window* Fl_Widget::window() const;</A></H4>
Return a pointer to the <A href=Fl_Window.html#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 <TT>NULL</TT> if none. Note:
for an <TT>Fl_Window</TT>, this returns its <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=common.html#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.html#Enumerations>
enumeration list</A> for predefined colors. Use <A href=functions.html#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="common.html#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:
<UL>
<LI><TT>FL_ALIGN_CENTER</TT></LI>
<LI><TT>FL_ALIGN_TOP</TT></LI>
<LI><TT>FL_ALIGN_BOTTOM</TT></LI>
<LI><TT>FL_ALIGN_LEFT</TT></LI>
<LI><TT>FL_ALIGN_RIGHT</TT></LI>
<LI><TT>FL_ALIGN_INSIDE</TT></LI>
<LI><TT>FL_ALIGN_CLIP</TT></LI>
<LI><TT>FL_ALIGN_WRAP</TT></LI>
</UL>
<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.html#Enumerations>
enumeration list</A> for predefined typefaces. The default value uses a
Helvetica typeface (Arial for Microsoft&reg; Windows&reg;). The function <A href=functions.html#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 &quot;OK&quot; button.
<P>Most widgets turn this flag off when they do the callback, and when
the program sets the stored value. </P>
<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 &quot;OK&quot; 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=functions.html#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.visible_r>int Fl_Widget::visible_r() 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. The
<TT>visible()</TT> method returns true if the widget is set to be
visible.The <TT>visible_r()</TT> method returns true if the widget and
all of its parents are visible. A widget is only visible if
<TT>visible()</TT> is true on it <I>and all of its parents</I>.
<P>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.active_r>int Fl_Widget::active_r() const</A></BR>
<A name=Fl_Widget.activate>void Fl_Widget::activate()</A></BR>
<A name=Fl_Widget.deactivate>void Fl_Widget::deactivate()</A></H4>
<TT>Fl_Widget::active()</TT> returns whether the widget is active.
<TT>Fl_Widget::active_r()</TT> returns whether the widget and all of
its parents are active. An inactive widget does not get any events,
but it does get redrawn. A widget is only active if <TT>active()</TT> is
true on it <I>and all of its parents</I>.
<P>Changing this value will send <TT>FL_ACTIVATE</TT> or <TT>
FL_DEACTIVATE</TT> to the widget if <tt>active_r()</tt> is true.
<P>Currently you cannot deactivate <TT>Fl_Window</TT> widgets. </P>
<H4><A name=Fl_Widget.output>int Fl_Widget::output() const</A><BR>
<A name=Fl_Widget.set_output>void Fl_Widget::set_output()</A></BR>
<A name=Fl_Widget.clear_output>void Fl_Widget::clear_output()</A></H4>
<tt>output()</tt> means the same as <tt>!active()</tt> except it does
not change how the widget is drawn. The widget will not receive any
events. This is useful for making scrollbars or buttons that work as
displays rather than input devices.
<H4><A name=Fl_Widget.takesevents>int Fl_Widget::takesevents() const</A>
</H4>
This is the same as <TT>(active() &amp;&amp; visible() &amp;&amp;
!output())</TT> but is faster.
<H4><A name=Fl_Widget.redraw>void Fl_Widget::redraw()</A></H4>
Mark the widget as needing its <A HREF="subclassing.html#draw"><TT>draw()</TT></A> routine called.
<H4><A name=Fl_Widget.damage>uchar Fl_Widget::damage() const</A></H4>
Non-zero if <A HREF="subclassing.html#draw"><TT>draw()</TT></A> 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_Group *Fl_Widget::parent() const</A></H4>
Returns a pointer to the parent widget. Usually this is a <A
href=Fl_Group.html#Fl_Group> <TT>Fl_Group</TT></A> or <A
HREF="Fl_Window.html#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>.
<H4><A name=Fl_Widget.take_focus>int Fl_Widget::take_focus()</A></H4>
Tries to make this widget be the <TT>Fl::focus()</TT> widget, by first
sending it an <TT>FL_FOCUS</TT> event, and if it returns non-zero,
setting <TT>Fl::focus()</TT> to this widget. You should use this
method to assign the focus to an widget. Returns true if the widget
accepted the focus. </BODY></HTML>