mirrors/fltk
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

converted more html to plain doxygen in {events,subclassing,opengl}.dox

Browse Source 
git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6406 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
This commit is contained in:
engelsman 2008-10-10 20:17:33 +00:00
parent 136b5f86f6
commit d658ae6039
3 changed files with 673 additions and 592 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

411
documentation/events.dox
View File

@ -2,269 +2,273 @@
\page events 6 - Handling Events
<P>This chapter discusses the FLTK event model and how to handle
This chapter discusses the FLTK event model and how to handle
events in your program or widget.
<H2>The FLTK Event Model</H2>
\section events_model The FLTK Event Model
<P>Every time a user moves the mouse pointer, clicks a button,
Every time a user moves the mouse pointer, clicks a button,
or presses a key, an event is generated and sent to your
application. Events can also come from other programs like the
window manager.
<P>Events are identified by the integer argument passed to the
<A href="subclassing.html#handle"><TT>Fl_Widget::handle()</TT></A> virtual
Events are identified by the integer argument passed to the
<A href="subclassing.html#handle"><tt>Fl_Widget::handle()</tt></A>
virtual
method. Other information about the most recent event is stored in
static locations and acquired by calling the \ref events_event_xxx
methods. This static information remains valid until the next event
is read from the window system, so it is ok to look at it outside
of the <TT>handle()</TT> method.
of the <tt>handle()</tt> method.
<H2>Mouse Events</H2>
\section events_mouse Mouse Events
<H3>FL_PUSH</H3>
\subsection events_fl_push FL_PUSH
<P>A mouse button has gone down with the mouse pointing at this
widget. You can find out what button by calling <A
href="Fl.html#Fl.event_button"><TT>
Fl::event_button()</TT></A>. You find out the mouse position by
calling <A
href="Fl.html#Fl.event_x"><TT>Fl::event_x()</TT></A> and <A
href="Fl.html#Fl.event_y"> <TT>Fl::event_y()</TT></A>.
A mouse button has gone down with the mouse pointing at this
widget. You can find out what button by calling
<A href="Fl.html#Fl.event_button"><tt>Fl::event_button()</tt></A>.
You find out the mouse position by calling
<A href="Fl.html#Fl.event_x"><tt>Fl::event_x()</tt></A>
and
<A href="Fl.html#Fl.event_y"> <tt>Fl::event_y()</tt></A>.
<P>A widget indicates that it &quot;wants&quot; the mouse click
by returning non-zero from its <A
href="subclassing.html#handle"><TT>handle()</TT></A> method. It
will then become the <A href="Fl.html#Fl.pushed"><TT>
Fl::pushed()</TT></A> widget and will get <TT>FL_DRAG</TT> and
the matching <TT>FL_RELEASE</TT> events. If <TT>handle()</TT>
returns zero then FLTK will try sending the <TT>FL_PUSH</TT> to
another widget. </P>
A widget indicates that it &quot;wants&quot; the mouse click
by returning non-zero from its
<A href="subclassing.html#handle"><tt>handle()</tt></A>
method. It will then become the
<A href="Fl.html#Fl.pushed"><tt>Fl::pushed()</tt></A>
widget and will get <tt>FL_DRAG</tt> and
the matching <tt>FL_RELEASE</tt> events. If <tt>handle()</tt>
returns zero then FLTK will try sending the <tt>FL_PUSH</tt> to
another widget.
<H3>FL_DRAG</H3>
\subsection events_fl_drag FL_DRAG
<P>The mouse has moved with a button held down. The current
button state is in <a
href="Fl.html#Fl.event_state"><tt>Fl::event_state()</tt></a>.
The mouse position is in <a
href="Fl.html#Fl.event_x"><tt>Fl::event_x()</tt></a> and <a
href="Fl.html#Fl.event_y"><tt>Fl::event_y()</tt></a>.
The mouse has moved with a button held down. The current
button state is in
<a href="Fl.html#Fl.event_state"><tt>Fl::event_state()</tt></a>.
The mouse position is in
<a href="Fl.html#Fl.event_x"><tt>Fl::event_x()</tt></a>
and
<a href="Fl.html#Fl.event_y"><tt>Fl::event_y()</tt></a>.
<P>In order to receive <TT>FL_DRAG</TT> events, the widget must
return non-zero when handling <TT>FL_PUSH</TT>.</P>
In order to receive <tt>FL_DRAG</tt> events, the widget must
return non-zero when handling <tt>FL_PUSH</tt>.
<H3>FL_RELEASE</H3>
\subsection events_fl_release FL_RELEASE
<P>A mouse button has been released. You can find out what
button by calling <A
href="Fl.html#Fl.event_button"><TT>Fl::event_button()</TT></A>.
A mouse button has been released. You can find out what button by calling
<A href="Fl.html#Fl.event_button"><tt>Fl::event_button()</tt></A>.
<P>In order to receive the <TT>FL_RELEASE</TT> event, the widget must
return non-zero when handling <TT>FL_PUSH</TT>.</P>
In order to receive the <tt>FL_RELEASE</tt> event, the widget must
return non-zero when handling <tt>FL_PUSH</tt>.
<H3>FL_MOVE</H3>
\subsection events_fl_move FL_MOVE
<P>The mouse has moved without any mouse buttons held down.
This event is sent to the <A
href="Fl.html#Fl.belowmouse"><TT>Fl::belowmouse()</TT></A>
widget.</P>
The mouse has moved without any mouse buttons held down.
This event is sent to the
<A href="Fl.html#Fl.belowmouse"><tt>Fl::belowmouse()</tt></A>
widget.
<P>In order to receive <TT>FL_MOVE</TT> events, the widget must
return non-zero when handling <TT>FL_ENTER</TT>.</P>
In order to receive <tt>FL_MOVE</tt> events, the widget must
return non-zero when handling <tt>FL_ENTER</tt>.
<H3>FL_MOUSEWHEEL</H3>
\subsection events_fl_mousewheel FL_MOUSEWHEEL
<P>The user has moved the mouse wheel. The <A
HREF="Fl.html#Fl.event_dx"><TT>Fl::event_dx()</TT></A> and <A
HREF="Fl.html#Fl.event_dy"><TT>Fl::event_dy()</TT></A> methods
can be used to find the amount to scroll horizontally and
The user has moved the mouse wheel. The
<A HREF="Fl.html#Fl.event_dx"><tt>Fl::event_dx()</tt></A>
and
<A HREF="Fl.html#Fl.event_dy"><tt>Fl::event_dy()</tt></A>
methods can be used to find the amount to scroll horizontally and
vertically.
<H2>Focus Events</H2>
\section events_focus Focus Events
<H3>FL_ENTER</H3>
\subsection events_fl_enter FL_ENTER
<P>The mouse has been moved to point at this widget. This can
The mouse has been moved to point at this widget. This can
be used for highlighting feedback. If a widget wants to
highlight or otherwise track the mouse, it indicates this by
returning non-zero from its <A
href="Fl.html#Fl.handle"><TT>handle()</TT></A> method. It then
becomes the <A
href="Fl.html#Fl.belowmouse"><TT>Fl::belowmouse()</TT></A>
widget and will receive <TT>FL_MOVE</TT> and <TT>FL_LEAVE</TT>
returning non-zero from its
<A href="Fl.html#Fl.handle"><tt>handle()</tt></A>
method. It then becomes the
<A href="Fl.html#Fl.belowmouse"><tt>Fl::belowmouse()</tt></A>
widget and will receive <tt>FL_MOVE</tt> and <tt>FL_LEAVE</tt>
events.
<H3>FL_LEAVE</H3>
\subsection events_fl_leave FL_LEAVE
<P>The mouse has moved out of the widget.
The mouse has moved out of the widget.
<P>In order to receive the <TT>FL_LEAVE</TT> event, the widget must
return non-zero when handling <TT>FL_ENTER</TT>.</P>
In order to receive the <tt>FL_LEAVE</tt> event, the widget must
return non-zero when handling <tt>FL_ENTER</tt>.
<H3>FL_FOCUS</H3>
\subsection events_fl_focus FL_FOCUS
<P>This indicates an <I>attempt</I> to give a widget the
This indicates an <I>attempt</I> to give a widget the
keyboard focus.
<P>If a widget wants the focus, it should change itself to
display the fact that it has the focus, and return non-zero from
its <A
href="Fl_Widget.html#Fl_Widget.handle"><TT>handle()</TT></A>
method. It then becomes the <A
href="Fl.html#Fl.focus"><TT>Fl::focus()</TT></A> widget and gets
<TT>FL_KEYDOWN</TT>, <TT>FL_KEYUP</TT>, and <TT>FL_UNFOCUS</TT>
If a widget wants the focus, it should change itself to
display the fact that it has the focus, and return non-zero from its
<A href="Fl_Widget.html#Fl_Widget.handle"><tt>handle()</tt></A>
method. It then becomes the
<A href="Fl.html#Fl.focus"><tt>Fl::focus()</tt></A>
widget and gets
<tt>FL_KEYDOWN</tt>, <tt>FL_KEYUP</tt>, and <tt>FL_UNFOCUS</tt>
events.
<P>The focus will change either because the window manager
The focus will change either because the window manager
changed which window gets the focus, or because the user tried
to navigate using tab, arrows, or other keys. You can check <A
href="Fl.html#Fl.event_key"><TT>Fl::event_key()</TT></A> to
figure out why it moved. For navigation it will be the key
pressed and interaction with the window manager it will be
zero.
to navigate using tab, arrows, or other keys. You can check
<A href="Fl.html#Fl.event_key"><tt>Fl::event_key()</tt></A>
to figure out why it moved. For navigation it will be the key
pressed and interaction with the window manager it will be zero.
<H3>FL_UNFOCUS</H3>
\subsection events_fl_unfocus FL_UNFOCUS
<P>This event is sent to the previous <A
href="Fl.html#Fl.focus"><TT>Fl::focus()</TT></A> widget when
another widget gets the focus or the window loses focus.
This event is sent to the previous
<A href="Fl.html#Fl.focus"><tt>Fl::focus()</tt></A>
widget when another widget gets the focus or the window loses focus.
<H2>Keyboard Events</H2>
\section events_keyboard Keyboard Events
<H3>FL_KEYDOWN, FL_KEYUP</H3>
\subsection events_fl_keydown FL_KEYDOWN, FL_KEYUP
<P>A key was pressed or released. The key can be found in <A
href="Fl.html#Fl.event_key"><TT>Fl::event_key()</TT></A>. The
text that the key should insert can be found with <A
href="Fl.html#Fl.event_text"><TT>Fl::event_text()</TT></A> and
its length is in <A
href="Fl.html#Fl.event_length"><TT>Fl::event_length()</TT></A>.
If you use the key <TT>handle()</TT> should return 1. If you
A key was pressed or released. The key can be found in
<A href="Fl.html#Fl.event_key"><tt>Fl::event_key()</tt></A>.
The text that the key should insert can be found with
<A href="Fl.html#Fl.event_text"><tt>Fl::event_text()</tt></A>
and its length is in
<A href="Fl.html#Fl.event_length"><tt>Fl::event_length()</tt></A>.
If you use the key <tt>handle()</tt> should return 1. If you
return zero then FLTK assumes you ignored the key and will
then attempt to send it to a parent widget. If none of them want
it, it will change the event into a <TT>FL_SHORTCUT</TT> event.
it, it will change the event into a <tt>FL_SHORTCUT</tt> event.
<P>To receive <CODE>FL_KEYBOARD</CODE> events you must also
To receive <CODE>FL_KEYBOARD</CODE> events you must also
respond to the <CODE>FL_FOCUS</CODE> and <CODE>FL_UNFOCUS</CODE>
events.
<P>If you are writing a text-editing widget you may also want to
call the <a href="Fl.html#Fl.compose"><TT>Fl::compose()</TT></a>
function to translate individual keystrokes into foreign
characters.
If you are writing a text-editing widget you may also want to
call the
<a href="Fl.html#Fl.compose"><tt>Fl::compose()</tt></a>
function to translate individual keystrokes into foreign characters.
<P><code>FL_KEYUP</code> events are sent to the widget that
<code>FL_KEYUP</code> events are sent to the widget that
currently has focus. This is not necessarily the same widget
that received the corresponding <code>FL_KEYDOWN</code> event
because focus may have changed between events.
<H3>FL_SHORTCUT</H3>
\subsection events_fl_shortcut FL_SHORTCUT
<P>If the <A href="Fl.html#Fl.focus"><TT>Fl::focus()</TT></A>
widget is zero or ignores an <TT>FL_KEYBOARD</TT> event then
If the
<A href="Fl.html#Fl.focus"><tt>Fl::focus()</tt></A>
widget is zero or ignores an <tt>FL_KEYBOARD</tt> event then
FLTK tries sending this event to every widget it can, until one
of them returns non-zero. <TT>FL_SHORTCUT</TT> is first sent to
the <TT>Fl::belowmouse()</TT> widget, then its parents and
of them returns non-zero. <tt>FL_SHORTCUT</tt> is first sent to
the <tt>Fl::belowmouse()</tt> widget, then its parents and
siblings, and eventually to every widget in the window, trying
to find an object that returns non-zero. FLTK tries really hard
to not to ignore any keystrokes!
<P>You can also make &quot;global&quot; shortcuts by using <A
href="Fl.html#Fl.add_handler"><TT>Fl::add_handler()</TT></A>. A
global shortcut will work no matter what windows are displayed
or which one has the focus.</P>
You can also make &quot;global&quot; shortcuts by using
<A href="Fl.html#Fl.add_handler"><tt>Fl::add_handler()</tt></A>.
A global shortcut will work no matter what windows are displayed
or which one has the focus.
<H2>Widget Events</H2>
\section events_widget Widget Events
<H3>FL_DEACTIVATE</H3>
\subsection events_fl_deactivate FL_DEACTIVATE
<P>This widget is no longer active, due to <A
href="Fl_Widget.html#Fl_Widget.deactivate"><TT>deactivate()</TT></A>
being called on it or one of its parents. <TT> active()</TT> may
This widget is no longer active, due to
<A href="Fl_Widget.html#Fl_Widget.deactivate"><tt>deactivate()</tt></A>
being called on it or one of its parents. <tt> active()</tt> may
still be true after this, the widget is only active if
<TT>active()</TT> is true on it and all its parents (use <TT>active_r()</TT> to check this).
<tt>active()</tt> is true on it and all its parents (use <tt>active_r()</tt> to check this).
<H3>FL_ACTIVATE</H3>
\subsection events_fl_activate FL_ACTIVATE
<P>This widget is now active, due to <A
href="Fl_Widget.html#Fl_Widget.activate"><TT>activate()</TT></A>
This widget is now active, due to
<A href="Fl_Widget.html#Fl_Widget.activate"><tt>activate()</tt></A>
being called on it or one of its parents.
<H3>FL_HIDE</H3>
\subsection events_fl_hide FL_HIDE
<P>This widget is no longer visible, due to <A
href="Fl_Widget.html#Fl_Widget.hide"><tt>hide()</tt></a> being
called on it or one of its parents, or due to a parent window
This widget is no longer visible, due to
<A href="Fl_Widget.html#Fl_Widget.hide"><tt>hide()</tt></a>
being called on it or one of its parents, or due to a parent window
being minimized. <tt>visible()</tt> may still be true after
this, but the widget is visible only if <tt>visible()</tt> is
true for it and all its parents (use <tt>visible_r()</tt> to
check this).
<h3>FL_SHOW</h3>
\subsection events_fl_show FL_SHOW
<P>This widget is visible again, due to <a
href="Fl_Widget.html#Fl_Widget.show"><TT>show()</TT></A> being
called on it or one of its parents, or due to a parent window
being restored. <I>Child <TT>Fl_Window</TT>s respond to this by
This widget is visible again, due to
<a href="Fl_Widget.html#Fl_Widget.show"><tt>show()</tt></A>
being called on it or one of its parents, or due to a parent window
being restored. <I>Child <tt>Fl_Window</tt>s respond to this by
actually creating the window if not done already, so if you
subclass a window, be sure to pass <TT>FL_SHOW</TT> to the base
class <TT>handle()</TT> method!</I>
subclass a window, be sure to pass <tt>FL_SHOW</tt> to the base
class <tt>handle()</tt> method!</I>
<H2>Clipboard Events</H2>
\section events_clipboard Clipboard Events
<H3>FL_PASTE</H3>
\subsection events_fl_paste FL_PASTE
<P>You should get this event some time after you call <A
href="Fl.html#Fl.paste"><TT>Fl::paste()</TT></A>. The contents
of <A href="Fl.html#Fl.event_text"><TT>Fl::event_text()</TT></A>
is the text to insert and the number of characters is in <A
href="Fl.html#Fl.event_length"><TT>Fl::event_length()</TT></A>.
You should get this event some time after you call
<A href="Fl.html#Fl.paste"><tt>Fl::paste()</tt></A>.
The contents of
<A href="Fl.html#Fl.event_text"><tt>Fl::event_text()</tt></A>
is the text to insert and the number of characters is in
<A href="Fl.html#Fl.event_length"><tt>Fl::event_length()</tt></A>.
<H3>FL_SELECTIONCLEAR</H3>
\subsection events_fl_selectionclear FL_SELECTIONCLEAR
<P>The <A
href="Fl.html#Fl.selection_owner"><TT>Fl::selection_owner()</TT></A>
The <A href="Fl.html#Fl.selection_owner"><tt>Fl::selection_owner()</tt></A>
will get this event before the selection is moved to another
widget. This indicates that some other widget or program has
claimed the selection. Motif programs used this to clear the
selection indication. Most modern programs ignore this.
<H2><A NAME="dnd">Drag And Drop Events</A></H2>
<A NAME="dnd"></A> <!-- For old HTML links only ! -->
\section events_dnd Drag and Drop Events
<P>FLTK supports drag and drop of text and files from any
FLTK supports drag and drop of text and files from any
application on the desktop. Text is transfered using
the current code page. Files are received as a list of full path
and file names, seperated by newline. On some platforms, path
names are prepended with <tt>file://</tt>.
<P>The drag and drop data is available in <tt>Fl::event_text()</tt>
The drag and drop data is available in <tt>Fl::event_text()</tt>
at the concluding <tt>FL_PASTE</tt>. On some platforms, the
event text is also available for the <tt>FL_DND_*</tt> events,
however application must not depend on that behavior because it
depends on the protocol used on each platform.
<P><tt>FL_DND_*</tt> events cannot be used in widgets derived
<tt>FL_DND_*</tt> events cannot be used in widgets derived
from <tt>Fl_Group</tt> or <tt>Fl_Window</tt>.
<H3>FL_DND_ENTER</H3>
\subsection events_fl_dnd_enter FL_DND_ENTER
<P>The mouse has been moved to point at this widget. A widget
The mouse has been moved to point at this widget. A widget
that is interested in receiving drag'n'drop data must return 1
to receive FL_DND_DRAG, FL_DND_LEAVE and FL_DND_RELEASE events.
<H3>FL_DND_DRAG</H3>
\subsection events_fl_dnd_drag FL_DND_DRAG
<P>The mouse has been moved inside a widget while dragging data.
The mouse has been moved inside a widget while dragging data.
A widget that is interested in receiving drag'n'drop data should
indicate the possible drop position.
<H3>FL_DND_LEAVE</H3>
\subsection events_fl_dnd_leave FL_DND_LEAVE
<P>The mouse has moved out of the widget.
The mouse has moved out of the widget.
<H3>FL_DND_RELEASE</H3>
\subsection events_fl_dnd_release FL_DND_RELEASE
<P>The user has released the mouse button dropping data into
The user has released the mouse button dropping data into
the widget. If the widget returns 1, it will receive the data in
the immediatly following FL_PASTE event.
@ -273,119 +277,108 @@ the immediatly following FL_PASTE event.
<A NAME="event_xxx"></A> <!-- For old HTML links only ! -->
\section events_event_xxx Fl::event_*() methods
<P>FLTK keeps the information about the most recent event in
FLTK keeps the information about the most recent event in
static storage. This information is good until the next event is
processed. Thus it is valid inside <TT>handle()</TT> and
<TT>callback()</TT> methods.
processed. Thus it is valid inside <tt>handle()</tt> and
<tt>callback()</tt> methods.
<P>These are all trivial inline functions and thus very fast and small: </P>
These are all trivial inline functions and thus very fast and small:
<UL>
\li <A HREF="Fl.html#Fl.event_button"><tt>Fl::event_button</tt></A>
<LI><A HREF="Fl.html#Fl.event_button"><TT>Fl::event_button</TT></A></LI>
\li <A HREF="Fl.html#Fl.event_clicks"><tt>Fl::event_clicks</tt></A>
<LI><A HREF="Fl.html#Fl.event_clicks"><TT>Fl::event_clicks</TT></A></LI>
\li <A HREF="Fl.html#Fl.event_dx"><tt>Fl::event_dx</tt></A>
<LI><A HREF="Fl.html#Fl.event_dx"><TT>Fl::event_dx</TT></A></LI>
\li <A HREF="Fl.html#Fl.event_dy"><tt>Fl::event_dy</tt></A>
<LI><A HREF="Fl.html#Fl.event_dy"><TT>Fl::event_dy</TT></A></LI>
\li <A HREF="Fl.html#Fl.event_inside"><tt>Fl::event_inside</tt></A>
<LI><A HREF="Fl.html#Fl.event_inside"><TT>Fl::event_inside</TT></A></LI>
\li <A HREF="Fl.html#Fl.event_is_click"><tt>Fl::event_is_click</tt></A>
<LI><A HREF="Fl.html#Fl.event_is_click"><TT>Fl::event_is_click</TT></A></LI>
\li <A HREF="Fl.html#Fl.event_key"><tt>Fl::event_key</tt></A>
<LI><A HREF="Fl.html#Fl.event_key"><TT>Fl::event_key</TT></A></LI>
\li <A HREF="Fl.html#Fl.event_length"><tt>Fl::event_length</tt></A>
<LI><A HREF="Fl.html#Fl.event_length"><TT>Fl::event_length</TT></A></LI>
\li <A HREF="Fl.html#Fl.event_state"><tt>Fl::event_state</tt></A>
<LI><A HREF="Fl.html#Fl.event_state"><TT>Fl::event_state</TT></A></LI>
\li <A HREF="Fl.html#Fl.event_text"><tt>Fl::event_text</tt></A>
<LI><A HREF="Fl.html#Fl.event_text"><TT>Fl::event_text</TT></A></LI>
\li <A HREF="Fl.html#Fl.event_x"><tt>Fl::event_x</tt></A>
<LI><A HREF="Fl.html#Fl.event_x"><TT>Fl::event_x</TT></A></LI>
\li <A HREF="Fl.html#Fl.event_x_root"><tt>Fl::event_x_root</tt></A>
<LI><A HREF="Fl.html#Fl.event_x_root"><TT>Fl::event_x_root</TT></A></LI>
\li <A HREF="Fl.html#Fl.event_y"><tt>Fl::event_y</tt></A>
<LI><A HREF="Fl.html#Fl.event_y"><TT>Fl::event_y</TT></A></LI>
\li <A HREF="Fl.html#Fl.event_y_root"><tt>Fl::event_y_root</tt></A>
<LI><A HREF="Fl.html#Fl.event_y_root"><TT>Fl::event_y_root</TT></A></LI>
\li <A HREF="Fl.html#Fl.get_key"><tt>Fl::get_key</tt></A>
<LI><A HREF="Fl.html#Fl.get_key"><TT>Fl::get_key</TT></A></LI>
\li <A HREF="Fl.html#Fl.get_mouse"><tt>Fl::get_mouse</tt></A>
<LI><A HREF="Fl.html#Fl.get_mouse"><TT>Fl::get_mouse</TT></A></LI>
<LI><A HREF="Fl.html#Fl.test_shortcut"><TT>Fl::test_shortcut</TT></A></LI>
</UL>
\li <A HREF="Fl.html#Fl.test_shortcut"><tt>Fl::test_shortcut</tt></A>
<A NAME="event_xxx"></A> <!-- For old HTML links only ! -->
\section events_propagation Event Propagation
<P>FLTK follows very simple and unchangeable rules for sending
FLTK follows very simple and unchangeable rules for sending
events. The major innovation is that widgets can indicate (by
returning 0 from the <TT>handle()</TT> method) that they are not
returning 0 from the <tt>handle()</tt> method) that they are not
interested in an event, and FLTK can then send that event
elsewhere. This eliminates the need for &quot;interests&quot;
(event masks or tables), and this is probably the main reason
FLTK is much smaller than other toolkits.
<P>Most events are sent directly to the <TT>handle()</TT> method
of the <TT>Fl_Window</TT> that the window system says they
belong to. The window (actually the <TT>Fl_Group</TT> that
<TT>Fl_Window</TT> is a subclass of) is responsible for sending
Most events are sent directly to the <tt>handle()</tt> method
of the <tt>Fl_Window</tt> that the window system says they
belong to. The window (actually the <tt>Fl_Group</tt> that
<tt>Fl_Window</tt> is a subclass of) is responsible for sending
the events on to any child widgets. To make the
<TT>Fl_Group</TT> code somewhat easier, FLTK sends some events
(<TT>FL_DRAG</TT>, <TT>FL_RELEASE</TT>, <TT>FL_KEYBOARD</TT>,
<TT>FL_SHORTCUT</TT>, <TT>FL_UNFOCUS</TT>, and
<TT>FL_LEAVE</TT>) directly to leaf widgets. These procedures
<tt>Fl_Group</tt> code somewhat easier, FLTK sends some events
(<tt>FL_DRAG</tt>, <tt>FL_RELEASE</tt>, <tt>FL_KEYBOARD</tt>,
<tt>FL_SHORTCUT</tt>, <tt>FL_UNFOCUS</tt>, and
<tt>FL_LEAVE</tt>) directly to leaf widgets. These procedures
control those leaf widgets:
<UL>
\li <A HREF="Fl.html#Fl.add_handler"><tt>Fl::add_handler</tt></A>
<LI><A HREF="Fl.html#Fl.add_handler"><TT>Fl::add_handler</TT></A></LI>
\li <A HREF="Fl.html#Fl.belowmouse"><tt>Fl::belowmouse</tt></A>
<LI><A HREF="Fl.html#Fl.belowmouse"><TT>Fl::belowmouse</TT></A></LI>
\li <A HREF="Fl.html#Fl.focus"><tt>Fl::focus</tt></A>
<LI><A HREF="Fl.html#Fl.focus"><TT>Fl::focus</TT></A></LI>
\li <A HREF="Fl.html#Fl.grab"><tt>Fl::grab</tt></A>
<LI><A HREF="Fl.html#Fl.grab"><TT>Fl::grab</TT></A></LI>
\li <A HREF="Fl.html#Fl.modal"><tt>Fl::modal</tt></A>
<LI><A HREF="Fl.html#Fl.modal"><TT>Fl::modal</TT></A></LI>
\li <A HREF="Fl.html#Fl.pushed"><tt>Fl::pushed</tt></A>
<LI><A HREF="Fl.html#Fl.pushed"><TT>Fl::pushed</TT></A></LI>
\li <A HREF="Fl.html#Fl.release"><tt>Fl::release</tt></A>
<LI><A HREF="Fl.html#Fl.release"><TT>Fl::release</TT></A></LI>
\li <A HREF="Fl_Widget.html#Fl_Widget.take_focus"><tt>Fl_Widget::take_focus</tt></A>
<LI><A HREF="Fl_Widget.html#Fl_Widget.take_focus"><TT>Fl_Widget::take_focus</TT></A></LI>
<A name="compose"></A> <!-- For old HTML links only ! -->
\section events_compose_characters FLTK Compose-Character Sequences
</UL>
The foreign-letter compose processing done by the
<A href="Fl_Input.html#compose"><tt>Fl_Input</tt></a>
widget is provided in a function that you can call if you are writing
your own text editor widget.
<H2><A name="compose">FLTK Compose-Character Sequences</A></H2>
<P>The foreign-letter compose processing done by the <A
href="Fl_Input.html#compose"><tt>Fl_Input</tt></a> widget is provided in
a function that you can call if you are writing your own text editor
widget.
<p>FLTK uses its own compose processing to allow "preview" of
FLTK uses its own compose processing to allow "preview" of
the partially composed sequence, which is impossible with the
usual "dead key" processing.
<p>Although currently only characters in the ISO-8859-1
Although currently only characters in the ISO-8859-1
character set are handled, you should call this in case any
enhancements to the processing are done in the future. The
interface has been designed to handle arbitrary UTF-8 encoded
text.
<P>The following methods are provided for character composition:
The following methods are provided for character composition:
<UL>
\li <A HREF="Fl.html#Fl.compose"><tt>Fl::compose()</tt></A>
<LI><A HREF="Fl.html#Fl.compose"><TT>Fl::compose()</TT></A></LI>
<LI><A HREF="Fl.html#Fl.compose_reset"><TT>Fl::compose_reset()</TT></A></LI>
</UL>
\li <A HREF="Fl.html#Fl.compose_reset"><tt>Fl::compose_reset()</tt></A>
<hr>
<a class="el" href="index.html">[Index]</a> &nbsp;&nbsp;

307
documentation/opengl.dox
View File

@ -2,46 +2,42 @@
\page opengl 8 - Using OpenGL
<P>This chapter discusses using FLTK for your OpenGL applications.
This chapter discusses using FLTK for your OpenGL applications.
<H2>Using OpenGL in FLTK</H2>
\section opengl_using Using OpenGL in FLTK
<P>The easiest way to make an OpenGL display is to subclass <A
href="Fl_Gl_Window.html#Fl_Gl_Window"><TT>Fl_Gl_Window</TT></A>.
Your subclass must implement a <TT>draw()</TT> method which uses
The easiest way to make an OpenGL display is to subclass
<A href="Fl_Gl_Window.html#Fl_Gl_Window"><tt>Fl_Gl_Window</tt></A>.
Your subclass must implement a <tt>draw()</tt> method which uses
OpenGL calls to draw the display. Your main program should call
<TT>redraw()</TT> when the display needs to change, and
(somewhat later) FLTK will call <TT>draw()</TT>.
<tt>redraw()</tt> when the display needs to change, and
(somewhat later) FLTK will call <tt>draw()</tt>.
<P>With a bit of care you can also use OpenGL to draw into
With a bit of care you can also use OpenGL to draw into
normal FLTK windows. This allows you to use Gouraud shading for
drawing your widgets. To do this you use the <A
href="#gl_start"><TT>gl_start()</TT></A> and <A
href=#gl_finish><TT>gl_finish()</TT></A> functions around your
OpenGL code.</P>
drawing your widgets. To do this you use the
<A href="#gl_start"><tt>gl_start()</tt></A>
and
<A href=#gl_finish><tt>gl_finish()</tt></A>
functions around your OpenGL code.
<P>You must include FLTK's <TT><FL/gl.h></TT> header
file. It will include the file <TT><GL/gl.h></TT>, define
You must include FLTK's <tt><FL/gl.h></tt> header
file. It will include the file <tt><GL/gl.h></tt>, define
some extra drawing functions provided by FLTK, and include the
<TT><windows.h></TT> header file needed by WIN32
applications.</P>
<tt><windows.h></tt> header file needed by WIN32
applications.
<H2>Making a Subclass of Fl_Gl_Window</H2>
\section opengl_subclass Making a Subclass of Fl_Gl_Window
<P>To make a subclass of Fl_Gl_Window, you must provide:
To make a subclass of Fl_Gl_Window, you must provide:
<UL>
\li A class definition.
<LI>A class definition.</LI>
\li A <tt>draw()</tt> method.
<LI>A <TT>draw()</TT> method.</LI>
\li A <tt>handle()</tt> method if you need to receive input from the user.
<LI>A <TT>handle()</TT> method if you need to receive
input from the user.</LI>
</UL>
<P>If your subclass provides static controls in the window, they
If your subclass provides static controls in the window, they
must be redrawn whenever the <tt>FL_DAMAGE_ALL</tt> bit is set
in the value returned by <tt>damage()</tt>. For double-buffered
windows you will need to surround the drawing code with the
@ -72,10 +68,9 @@ glDrawBuffer(GL_BACK);
</TR>
</TABLE></CENTER>
<H3>Defining the Subclass</H3>
\subsection opengl_defining Defining the Subclass
<P>To define the subclass you just subclass the
<TT>Fl_Gl_Window</TT> class:
To define the subclass you just subclass the <tt>Fl_Gl_Window</tt> class:
\code
class MyWindow : public Fl_Gl_Window {
@ -88,15 +83,14 @@ public:
};
\endcode
<P>The <TT>draw()</TT> and <TT>handle()</TT> methods are
The <tt>draw()</tt> and <tt>handle()</tt> methods are
described below. Like any widget, you can include additional
private and public data in your class (such as scene graph
information, etc.)
<H3>The draw() Method</H3>
\subsection opengl_draw The draw() Method
<P>The <TT>draw()</TT> method is where you actually do your
OpenGL drawing:
The <tt>draw()</tt> method is where you actually do your OpenGL drawing:
\code
void MyWindow::draw() {
@ -109,9 +103,9 @@ void MyWindow::draw() {
}
\endcode
<H3>The handle() Method</H3>
\subsection opengl_handle The handle() Method
<P>The <TT>handle()</TT> method handles mouse and keyboard
The <tt>handle()</tt> method handles mouse and keyboard
events for the window:
\code
@ -146,13 +140,13 @@ int MyWindow::handle(int event) {
}
\endcode
<P>When <TT>handle()</TT> is called, the OpenGL context is not
When <tt>handle()</tt> is called, the OpenGL context is not
set up! If your display changes, you should call
<TT>redraw()</TT> and let <TT>draw()</TT> do the work. Don't
call any OpenGL drawing functions from inside <TT>handle()</TT>!
<tt>redraw()</tt> and let <tt>draw()</tt> do the work. Don't
call any OpenGL drawing functions from inside <tt>handle()</tt>!
<P>You can call <I>some</I> OpenGL stuff like hit detection and texture
loading functions by doing: </P>
You can call <I>some</I> OpenGL stuff like hit detection and texture
loading functions by doing:
\code
case FL_PUSH:
@ -167,50 +161,44 @@ loading functions by doing: </P>
detection, loading textures, etc...
\endcode
<P>Your main program can now create one of your windows by doing
<TT>new MyWindow(...)</TT>. You can also use <A
href="fluid.html#FLUID">FLUID</A> by:
Your main program can now create one of your windows by doing
<tt>new MyWindow(...)</tt>. You can also use
<A href="fluid.html#FLUID">FLUID</A>
by:
<OL>
-# Putting your class definition in a <tt>MyWindow.H</tt> file.
<br>
-# Creating a <tt>Fl_Box</tt> widget in FLUID.
<br>
-# In the widget panel fill in the "class" field with <tt>MyWindow</tt>.
This will make FLUID produce constructors for your new class.
<br>
-# In the "Extra Code" field put <tt>\#include "MyWindow.H"</tt>,
so that the FLUID output file will compile.
<LI>Putting your class definition in a
<tt>MyWindow.H</tt> file.</LI>
<LI>Creating a <tt>Fl_Box</tt> widget in FLUID.</LI>
<LI>In the widget panel fill in the "class"
field with <tt>MyWindow</tt>. This will make FLUID
produce constructors for your new class.</LI>
<LI>In the "Extra Code" field put <TT>\#include
"MyWindow.H"</TT>, so that the FLUID output
file will compile.</LI>
</OL>
<P>You must put <TT>glwindow->show()</TT> in your main code
after calling <TT>show()</TT> on the window containing the
You must put <tt>glwindow->show()</tt> in your main code
after calling <tt>show()</tt> on the window containing the
OpenGL window.
<H2>Using OpenGL in Normal FLTK Windows</H2>
\section opengl_normal Using OpenGL in Normal FLTK Windows
<P>You can put OpenGL code into an <A
href="subclassing.html#draw"><TT>Fl_Widget::draw()</TT></A>
method or into the code for a <A
href="common.html#boxtypes">boxtype</A> or other places with some
care.
You can put OpenGL code into an
<A href="subclassing.html#draw"><tt>Fl_Widget::draw()</tt></A>
method or into the code for a
<A href="common.html#boxtypes">boxtype</A>
or other places with some care.
<P>Most importantly, before you show <I>any</I> windows,
Most importantly, before you show <I>any</I> windows,
including those that don't have OpenGL drawing, you <B>must</B>
initialize FLTK so that it knows it is going to use OpenGL. You
may use any of the symbols described for Fl_Gl_Window::mode()
to describe how you intend to use OpenGL:</P>
to describe how you intend to use OpenGL:
\code
Fl::gl_visual(FL_RGB);
\endcode
<P>You can then put OpenGL drawing code anywhere you can draw
You can then put OpenGL drawing code anywhere you can draw
normally by surrounding it with:
\code
@ -219,143 +207,145 @@ gl_start();
gl_finish();
\endcode
<P><A name="gl_start"><TT>gl_start()</TT></A> and <A
name="gl_finish"><TT>gl_finish()</TT></A> set up an OpenGL
<A name="gl_start"><tt>gl_start()</tt></A>
and
<A name="gl_finish"><tt>gl_finish()</tt></A>
set up an OpenGL
context with an orthographic projection so that 0,0 is the
lower-left corner of the window and each pixel is one unit. The
current clipping is reproduced with OpenGL <TT>glScissor()</TT>
current clipping is reproduced with OpenGL <tt>glScissor()</tt>
commands. These functions also synchronize the OpenGL graphics stream
with the drawing done by other X, WIN32, or FLTK functions.
<P>The same context is reused each time. If your code changes
The same context is reused each time. If your code changes
the projection transformation or anything else you should use
<TT>glPushMatrix()</TT> and <TT>glPopMatrix()</TT> functions to
put the state back before calling <TT>gl_finish()</TT>.</P>
<tt>glPushMatrix()</tt> and <tt>glPopMatrix()</tt> functions to
put the state back before calling <tt>gl_finish()</tt>.
<P>You may want to use Fl_Window::current()->h() to
You may want to use Fl_Window::current()->h() to
get the drawable height so that you can flip the Y
coordinates.</P>
coordinates.
<P>Unfortunately, there are a bunch of limitations you must
adhere to for maximum portability: </P>
Unfortunately, there are a bunch of limitations you must
adhere to for maximum portability:
<UL>
\li You must choose a default visual with Fl::gl_visual().
<LI>You must choose a default visual with Fl::gl_visual().</LI>
\li You cannot pass <tt>FL_DOUBLE</tt> to Fl::gl_visual().
<LI>You cannot pass <TT>FL_DOUBLE</TT> to Fl::gl_visual().</LI>
\li You cannot use Fl_Double_Window or Fl_Overlay_Window.
<LI>You cannot use Fl_Double_Window or Fl_Overlay_Window.</LI>
Do <I>not</I> call <tt>gl_start()</tt> or
<tt>gl_finish()</tt> when drawing into an Fl_Gl_Window !
</UL>
\section opengl_drawing OpenGL Drawing Functions
<P>Do <I>not</I> call <TT>gl_start()</TT> or
<TT>gl_finish()</TT> when drawing into an Fl_Gl_Window !
<H2>OpenGL Drawing Functions</H2>
<P>FLTK provides some useful OpenGL drawing functions. They can
FLTK provides some useful OpenGL drawing functions. They can
be freely mixed with any OpenGL calls, and are defined by
including <FL/gl.H> which you should include
instead of the OpenGL header <TT><GL/gl.h></TT>.
instead of the OpenGL header <tt><GL/gl.h></tt>.
<H4>void gl_color(Fl_Color)</H4>
void gl_color(Fl_Color)
<P>Sets the current OpenGL color to a FLTK color. <I>For
color-index modes it will use <TT>fl_xpixel(c)</TT>, which is
\par
Sets the current OpenGL color to a FLTK color. <I>For
color-index modes it will use <tt>fl_xpixel(c)</tt>, which is
only right if this window uses the default colormap!</I>
<H4>void gl_rect(int x, int y, int w, int h)
<BR>void gl_rectf(int x, int y, int w, int h)</H4>
void gl_rect(int x, int y, int w, int h) <br>
void gl_rectf(int x, int y, int w, int h)
<P>Outlines or fills a rectangle with the current color. If
\par
Outlines or fills a rectangle with the current color. If
Fl_Gl_Window::ortho() has been called, then the rectangle will exactly
fill the pixel rectangle passed.
<H4>void gl_font(Fl_Font fontid, int size)</H4>
void gl_font(Fl_Font fontid, int size)
<P>Sets the current OpenGL font to the same font you get by
calling <A href="drawing.html#fl_font"><TT>fl_font()</TT></A>.
\par
Sets the current OpenGL font to the same font you get by calling
<A href="drawing.html#fl_font"><tt>fl_font()</tt></A>.
<H4>int gl_height()
<BR>int gl_descent()
<BR>float gl_width(const char *)
<BR>float gl_width(const char *, int n)
<BR>float gl_width(uchar)</H4>
int gl_height() <br>
int gl_descent() <br>
float gl_width(const char *) <br>
float gl_width(const char *, int n) <br>
float gl_width(uchar)
<P>Returns information about the current OpenGL font.
\par
Returns information about the current OpenGL font.
<H4>void gl_draw(const char *)
<BR>void gl_draw(const char *, int n)</H4>
void gl_draw(const char *) <br>
void gl_draw(const char *, int n)
<P>Draws a nul-terminated string or an array of <TT>n</TT>
\par
Draws a nul-terminated string or an array of <tt>n</tt>
characters in the current OpenGL font at the current raster
position.
<H4>void gl_draw(const char *, int x, int y)
<BR>void gl_draw(const char *, int n, int x, int y)
<BR>void gl_draw(const char *, float x, float y)
<BR>void gl_draw(const char *, int n, float x, float y)</H4>
void gl_draw(const char *, int x, int y) <br>
void gl_draw(const char *, int n, int x, int y) <br>
void gl_draw(const char *, float x, float y) <br>
void gl_draw(const char *, int n, float x, float y)
<P>Draws a nul-terminated string or an array of <TT>n</TT>
\par
Draws a nul-terminated string or an array of <tt>n</tt>
characters in the current OpenGL font at the given position.
<H4>void gl_draw(const char *, int x, int y, int w, int h, Fl_Align)</H4>
void gl_draw(const char *, int x, int y, int w, int h, Fl_Align)
<P>Draws a string formatted into a box, with newlines and tabs
\par
Draws a string formatted into a box, with newlines and tabs
expanded, other control characters changed to ^X, and aligned
with the edges or center. Exactly the same output as <A
href="drawing.html#text"><TT>fl_draw()</TT></A>.
with the edges or center. Exactly the same output as
<A href="drawing.html#text"><tt>fl_draw()</tt></A>.
<h2>Speeding up OpenGL</h2>
\section opengl_speed Speeding up OpenGL
<P>Performance of Fl_Gl_Window may be improved on some types of
Performance of Fl_Gl_Window may be improved on some types of
OpenGL implementations, in particular MESA and other software
emulators, by setting the <tt>GL_SWAP_TYPE</tt> environment
variable. This variable declares what is in the backbuffer after
you do a swapbuffers.
<ul>
\li <tt>setenv GL_SWAP_TYPE COPY</tt> <br>
<br>
This indicates that the back buffer is copied to the
front buffer, and still contains it's old data. This is
true of many hardware implementations. Setting this
will speed up emulation of overlays, and widgets that
can do partial update can take advantage of this as
damage() will not be cleared to -1. <p>
<li><tt>setenv GL_SWAP_TYPE COPY</tt>
\li <tt>setenv GL_SWAP_TYPE NODAMAGE</tt> <br>
<br>
This indicates that nothing changes the back buffer
except drawing into it. This is true of MESA and Win32
software emulation and perhaps some hardware emulation
on systems with lots of memory. <p>
<p>This indicates that the back buffer is copied to the
front buffer, and still contains it's old data. This is
true of many hardware implementations. Setting this
will speed up emulation of overlays, and widgets that
can do partial update can take advantage of this as
damage() will not be cleared to -1. <p>
\li All other values for <tt>GL_SWAP_TYPE</tt>, and not
setting the variable, cause FLTK to assume that the
back buffer must be completely redrawn after a swap.
<li><tt>setenv GL_SWAP_TYPE NODAMAGE</tt>
<p>This indicates that nothing changes the back buffer
except drawing into it. This is true of MESA and Win32
software emulation and perhaps some hardware emulation
on systems with lots of memory. <p>
<li>All other values for <tt>GL_SWAP_TYPE</tt>, and not
setting the variable, cause FLTK to assume that the
back buffer must be completely redrawn after a swap.
</ul>
<p>This is easily tested by running the <TT>gl_overlay</TT> demo
This is easily tested by running the <tt>gl_overlay</tt> demo
program and seeing if the display is correct when you drag
another window over it or if you drag the window off the screen
and back on. You have to exit and run the program again for it
to see any changes to the environment variable.
<H2>Using OpenGL Optimizer with FLTK</H2>
\section opengl_optimizer Using OpenGL Optimizer with FLTK
<P><A href="http://www.sgi.com/software/optimizer">OpenGL
Optimizer</A> is a scene graph toolkit for OpenGL available from
<A href="http://www.sgi.com/software/optimizer">OpenGL Optimizer</A>
is a scene graph toolkit for OpenGL available from
Silicon Graphics for IRIX and Microsoft Windows. It allows you
to view large scenes without writing a lot of OpenGL code.
<H4>OptimizerWindow Class Definition</H4>
\par OptimizerWindow Class Definition
<P>To use OpenGL Optimizer with FLTK you'll need to create a
subclass of <TT>Fl_Gl_Widget</TT> that includes several state
\par
To use OpenGL Optimizer with FLTK you'll need to create a
subclass of <tt>Fl_Gl_Widget</tt> that includes several state
variables:
\code
@ -389,15 +379,17 @@ public:
};
\endcode
<H4>The camera() Method</H4>
\par The camera() Method
<P>The <TT>camera()</TT> method sets the camera (projection and
\par
The <tt>camera()</tt> method sets the camera (projection and
viewpoint) to use when drawing the scene. The scene is redrawn after
this call.
<H4>The draw() Method</H4>
\par The draw() Method
<P>The <TT>draw()</TT> method performs the needed initialization and does
\par
The <tt>draw()</tt> method performs the needed initialization and does
the actual drawing:
\code
@ -451,10 +443,11 @@ void OptimizerWindow::draw() {
}
\endcode
<H4>The scene() Method</H4>
\par The scene() Method
<P>The <TT>scene()</TT> method sets the scene to be drawn. The scene is
a collection of 3D objects in a <TT>csGroup</TT>. The scene is redrawn
\par
The <tt>scene()</tt> method sets the scene to be drawn. The scene is
a collection of 3D objects in a <tt>csGroup</tt>. The scene is redrawn
after this call.
<hr>

547
documentation/subclassing.dox
View File

@ -2,46 +2,63 @@
\page subclassing 7 - Adding and Extending Widgets
<P>This chapter describes how to add your own widgets or extend existing
This chapter describes how to add your own widgets or extend existing
widgets in FLTK.
<H2>Subclassing</H2>
New widgets are created by <I>subclassing</I> an existing FLTK widget,
typically <TT>Fl_Widget</TT> for controls and <TT>Fl_Group</TT> for
\section subclassing_subclassing Subclassing
New widgets are created by <I>subclassing</I> an existing FLTK widget,
typically <tt>Fl_Widget</tt> for controls and <tt>Fl_Group</tt> for
composite widgets.
<P>A control widget typically interacts with the user to receive and/or
display a value of some sort. </P>
<P>A composite widget widget holds a list of child widgets and handles moving,
sizing, showing, or hiding them as needed. <TT>Fl_Group</TT> is the
main composite widget widget class in FLTK, and all of the other composite widgets (<TT>
Fl_Pack</TT>, <TT>Fl_Scroll</TT>, <TT>Fl_Tabs</TT>, <TT>Fl_Tile</TT>,
and <TT>Fl_Window</TT>) are subclasses of it. </P>
<P>You can also subclass other existing widgets to provide a different
A control widget typically interacts with the user to receive and/or
display a value of some sort.
A composite widget widget holds a list of child widgets and handles moving,
sizing, showing, or hiding them as needed. <tt>Fl_Group</tt> is the
main composite widget widget class in FLTK, and all of the other composite
widgets (<tt>Fl_Pack</tt>, <tt>Fl_Scroll</tt>, <tt>Fl_Tabs</tt>,
<tt>Fl_Tile</tt>, and <tt>Fl_Window</tt>) are subclasses of it.
You can also subclass other existing widgets to provide a different
look or user-interface. For example, the button widgets are all
subclasses of <TT>Fl_Button</TT> since they all interact with the user
subclasses of <tt>Fl_Button</tt> since they all interact with the user
via a mouse button click. The only difference is the code that draws
the face of the button. </P>
<H2>Making a Subclass of Fl_Widget</H2>
Your subclasses can directly descend from <TT>Fl_Widget</TT> or any
subclass of <TT>Fl_Widget</TT>. <TT>Fl_Widget</TT> has only four
the face of the button.
\section subclassing_fl_widget Making a Subclass of Fl_Widget
Your subclasses can directly descend from <tt>Fl_Widget</tt> or any
subclass of <tt>Fl_Widget</tt>. <tt>Fl_Widget</tt> has only four
virtual methods, and overriding some or all of these may be necessary.
<H2>The Constructor</H2>
The constructor should have the following arguments:
\section subclassing_constructor The Constructor
The constructor should have the following arguments:
\code
MyClass(int x, int y, int w, int h, const char *label = 0);
\endcode
This will allow the class to be used in <A href="fluid.html#FLUID">FLUID</A>
without problems.
<P>The constructor must call the constructor for the base class and
pass the same arguments: </P>
This will allow the class to be used in
<A href="fluid.html#FLUID">FLUID</A>
without problems.
The constructor must call the constructor for the base class and
pass the same arguments:
\code
MyClass::MyClass(int x, int y, int w, int h, const char *label)
: Fl_Widget(x, y, w, h, label) {
// do initialization stuff...
}
\endcode
<TT>Fl_Widget</TT>'s protected constructor sets <TT>x()</TT>, <TT>y()</TT>,
<TT>w()</TT>, <TT>h()</TT>, and <TT>label()</TT> to the passed values
<tt>Fl_Widget</tt>'s protected constructor sets <tt>x()</tt>, <tt>y()</tt>,
<tt>w()</tt>, <tt>h()</tt>, and <tt>label()</tt> to the passed values
and initializes the other instance variables to:
\code
type(0);
box(FL_NO_BOX);
@ -57,36 +74,47 @@ flags(ACTIVE|VISIBLE);
image(0);
deimage(0);
\endcode
<H2>Protected Methods of Fl_Widget</H2>
The following methods are provided for subclasses to use:
<UL>
<LI><A href="#clear_visible"><TT>Fl_Widget::clear_visible</TT></A></LI>
<LI><A href="#damage"><TT>Fl_Widget::damage</TT></A></LI>
<LI><A href="#draw_box"><TT>Fl_Widget::draw_box</TT></A></LI>
<LI><A href="#draw_focus"><TT>Fl_Widget::draw_focus</TT></A></LI>
<LI><A href="#draw_label"><TT>Fl_Widget::draw_label</TT></A></LI>
<LI><A href="#set_flag"><TT>Fl_Widget::set_flag</TT></A></LI>
<LI><A href="#set_visible"><TT>Fl_Widget::set_visible</TT></A></LI>
<LI><A href="#test_shortcut"><TT>Fl_Widget::test_shortcut</TT></A></LI>
<LI><A href="#type"><TT>Fl_Widget::type</TT></A></LI>
</UL>
<H4><A name="damage">void Fl_Widget::damage(uchar mask)
<BR> void Fl_Widget::damage(uchar mask, int x, int y, int w, int h)
<BR> uchar Fl_Widget::damage()</A></H4>
\section subclassing_protected Protected Methods of Fl_Widget
The following methods are provided for subclasses to use:
\li <A href="#clear_visible"><tt>Fl_Widget::clear_visible</tt></A>
\li <A href="#damage"><tt>Fl_Widget::damage</tt></A>
\li <A href="#draw_box"><tt>Fl_Widget::draw_box</tt></A>
\li <A href="#draw_focus"><tt>Fl_Widget::draw_focus</tt></A>
\li <A href="#draw_label"><tt>Fl_Widget::draw_label</tt></A>
\li <A href="#set_flag"><tt>Fl_Widget::set_flag</tt></A>
\li <A href="#set_visible"><tt>Fl_Widget::set_visible</tt></A>
\li <A href="#test_shortcut"><tt>Fl_Widget::test_shortcut</tt></A>
\li <A href="#type"><tt>Fl_Widget::type</tt></A>
<A name="damage"></A> <!-- For old HTML links only ! -->
void Fl_Widget::damage(uchar mask) <br>
void Fl_Widget::damage(uchar mask, int x, int y, int w, int h) <br>
uchar Fl_Widget::damage()
\par
The first form indicates that a partial update of the object is
needed. The bits in mask are OR'd into <TT>damage()</TT>. Your <TT>
draw()</TT> routine can examine these bits to limit what it is
drawing. The public method <TT>Fl_Widget::redraw()</TT> simply does
<TT> Fl_Widget::damage(FL_DAMAGE_ALL)</TT>, but the implementation of
your widget can call the private <TT>damage(n)</TT>.
<P>The second form indicates that a region is damaged. If only these
calls are done in a window (no calls to <TT>damage(n)</TT>) then FLTK
needed. The bits in mask are OR'd into <tt>damage()</tt>. Your <tt>
draw()</tt> routine can examine these bits to limit what it is
drawing. The public method <tt>Fl_Widget::redraw()</tt> simply does
<tt> Fl_Widget::damage(FL_DAMAGE_ALL)</tt>, but the implementation of
your widget can call the private <tt>damage(n)</tt>.
\par
The second form indicates that a region is damaged. If only these
calls are done in a window (no calls to <tt>damage(n)</tt>) then FLTK
will clip to the union of all these calls before drawing anything.
This can greatly speed up incremental displays. The mask bits are
OR'd into <TT>damage()</TT> unless this is a <TT>Fl_Window</TT> widget. </P>
<P>The third form returns the bitwise-OR of all <TT>damage(n)</TT>
calls done since the last <TT>draw()</TT>.</P>
<P><I>When redrawing your widgets you should look at the damage bits to
OR'd into <tt>damage()</tt> unless this is a <tt>Fl_Window</tt> widget.
\par
The third form returns the bitwise-OR of all <tt>damage(n)</tt>
calls done since the last <tt>draw()</tt>.
\par
<I>When redrawing your widgets you should look at the damage bits to
see what parts of your widget need redrawing.</I> The <tt>handle()</tt>
method can then set individual damage bits to limit the amount of drawing
that needs to be done:
@ -108,90 +136,134 @@ MyClass::draw() {
if (damage() &amp; (FL_DAMAGE_ALL | 4)) draw_part3();
}
\endcode
<H4><A name="draw_box">void Fl_Widget::draw_box() const
<BR></A>void Fl_Widget::draw_box(Fl_Boxtype b, ulong c) const</H4>
The first form draws this widget's <TT>box()</TT>, using the
dimensions of the widget. The second form uses <TT>b</TT> as the box
type and <TT>c</TT> as the color for the box.
<H4><A name="draw_focus">void Fl_Widget::draw_focus() const
<BR>void Fl_Widget::draw_focus(Fl_Boxtype b, int x, int y, int w, int h) const</A></H4>
<A name="draw_box"></A> <!-- For old HTML links only ! -->
void Fl_Widget::draw_box() const <br>
void Fl_Widget::draw_box(Fl_Boxtype b, ulong c) const
<P>Draws a focus box inside the widgets bounding box. The second
\par
The first form draws this widget's <tt>box()</tt>, using the
dimensions of the widget. The second form uses <tt>b</tt> as the box
type and <tt>c</tt> as the color for the box.
<A name="draw_focus"></A> <!-- For old HTML links only ! -->
void Fl_Widget::draw_focus() const <br>
void Fl_Widget::draw_focus(Fl_Boxtype b, int x, int y, int w, int h) const
\par
Draws a focus box inside the widgets bounding box. The second
form allows you to specify a different bounding box.
<H4><A name="draw_label">void Fl_Widget::draw_label() const
<BR> void Fl_Widget::draw_label(int x, int y, int w, int h) const
<BR> void Fl_Widget::draw_label(int x, int y, int w, int h, Fl_Align
align) const</A></H4>
This is the usual function for a <TT>draw()</TT> method to call to
<A name="draw_label"></A> <!-- For old HTML links only ! -->
void Fl_Widget::draw_label() const <br>
void Fl_Widget::draw_label(int x, int y, int w, int h) const <br>
void Fl_Widget::draw_label(int x, int y, int w, int h, Fl_Align align) const
\par
This is the usual function for a <tt>draw()</tt> method to call to
draw the widget's label. It does not draw the label if it is supposed
to be outside the box (on the assumption that the enclosing group will
draw those labels).
<P>The second form uses the passed bounding box instead of the widget's
\par
The second form uses the passed bounding box instead of the widget's
bounding box. This is useful so &quot;centered&quot; labels are aligned with some
feature, like a moving slider. </P>
<P>The third form draws the label anywhere. It acts as though <TT>
FL_ALIGN_INSIDE</TT> has been forced on so the label will appear inside
feature, like a moving slider.
\par
The third form draws the label anywhere. It acts as though <tt>
FL_ALIGN_INSIDE</tt> has been forced on so the label will appear inside
the passed bounding box. This is designed for parent groups to draw
labels with. </P>
<H4><A name="set_flag">void Fl_Widget::set_flag(SHORTCUT_LABEL)</A></H4>
Modifies <TT>draw_label()</TT> so that '&amp;' characters cause an underscore
labels with.
<A name="set_flag"></A> <!-- For old HTML links only ! -->
void Fl_Widget::set_flag(SHORTCUT_LABEL)
\par
Modifies <tt>draw_label()</tt> so that '&amp;' characters cause an underscore
to be printed under the next letter.
<H4><A name="set_visible">void Fl_Widget::set_visible()</A>
<BR><A name="clear_visible">void Fl_Widget::clear_visible()</A></H4>
Fast inline versions of <TT>Fl_Widget::hide()</TT> and <TT>
Fl_Widget::show()</TT>. These do not send the <TT>FL_HIDE</TT> and <TT>
FL_SHOW</TT> events to the widget.
<H4><A name="test_shortcut">int Fl_Widget::test_shortcut() const
<BR> static int Fl_Widget::test_shortcut(const char *s)</A></H4>
The first version tests <TT>Fl_Widget::label()</TT> against the
current event (which should be a <TT>FL_SHORTCUT</TT> event). If the
<A name="set_visible"></A> <!-- For old HTML links only ! -->
<A name="clear_visible"></A> <!-- For old HTML links only ! -->
void Fl_Widget::set_visible() <br>
void Fl_Widget::clear_visible()
\par
Fast inline versions of <tt>Fl_Widget::hide()</tt> and <tt>
Fl_Widget::show()</tt>. These do not send the <tt>FL_HIDE</tt> and <tt>
FL_SHOW</tt> events to the widget.
<A name="test_shortcut"></A> <!-- For old HTML links only ! -->
int Fl_Widget::test_shortcut() const <br>
static int Fl_Widget::test_shortcut(const char *s)
\par
The first version tests <tt>Fl_Widget::label()</tt> against the
current event (which should be a <tt>FL_SHORTCUT</tt> event). If the
label contains a '&amp;' character and the character after it matches the key
press, this returns true. This returns false if the <TT>SHORTCUT_LABEL</TT>
flag is off, if the label is <TT>NULL</TT> or does not have a
press, this returns true. This returns false if the <tt>SHORTCUT_LABEL</tt>
flag is off, if the label is <tt>NULL</tt> or does not have a
'&amp;' character in it, or if the keypress does not match the character.
<P>The second version lets you do this test against an arbitrary
string. </P>
<H4><A name="type">uchar Fl_Widget::type() const
<BR> void Fl_Widget::type(uchar t)</A></H4>
The property <TT>Fl_Widget::type()</TT> can return an arbitrary 8-bit
identifier, and can be set with the protected method <TT>type(uchar t)</TT>
. This value had to be provided for Forms compatibility, but you can
\par
The second version lets you do this test against an arbitrary string.
<A name="type"></A> <!-- For old HTML links only ! -->
uchar Fl_Widget::type() const <br>
void Fl_Widget::type(uchar t)
\par
The property <tt>Fl_Widget::type()</tt> can return an arbitrary 8-bit
identifier, and can be set with the protected method <tt>type(uchar t)</tt>.
This value had to be provided for Forms compatibility, but you can
use it for any purpose you want. Try to keep the value less than 100
to not interfere with reserved values.
<P>FLTK does not use RTTI (Run Time Typing Infomation), to enhance
\par
FLTK does not use RTTI (Run Time Typing Infomation), to enhance
portability. But this may change in the near future if RTTI becomes
standard everywhere. </P>
<P>If you don't have RTTI you can use the clumsy FLTK mechanisim, by
having <TT>type()</TT> use a unique value. These unique values must
be greater than the symbol <TT>FL_RESERVED_TYPE</TT> (which is 100).
Look through the header files for <TT>FL_RESERVED_TYPE</TT> to find an
unused number. If you make a subclass of <TT>Fl_Window</TT>
you must use <TT>FL_WINDOW + n</TT> (<TT>n</tt> must be in the
range 1 to 7). </P>
<H2><A NAME="handle">Handling Events</A></H2>
The virtual method <TT>int Fl_Widget::handle(int event)</TT> is called
standard everywhere.
\par
If you don't have RTTI you can use the clumsy FLTK mechanisim, by
having <tt>type()</tt> use a unique value. These unique values must
be greater than the symbol <tt>FL_RESERVED_TYPE</tt> (which is 100).
Look through the header files for <tt>FL_RESERVED_TYPE</tt> to find an
unused number. If you make a subclass of <tt>Fl_Window</tt>
you must use <tt>FL_WINDOW + n</tt> (<tt>n</tt> must be in the
range 1 to 7).
<A NAME="handle"></A> <!-- For old HTML links only ! -->
\section subclassing_events Handling Events
The virtual method <tt>int Fl_Widget::handle(int event)</tt> is called
to handle each event passed to the widget. It can:
<UL>
<LI>Change the state of the widget. </LI>
<LI>Call <A href="Fl_Widget.html#Fl_Widget.redraw"><TT>Fl_Widget::redraw()</TT>
</A> if the widget needs to be redisplayed. </LI>
<LI>Call <A href="Fl_Widget.html#Fl_Widget.damage"><TT>
Fl_Widget::damage(n)</TT></A> if the widget needs a partial-update
(assuming you provide support for this in your <A href="#draw"><TT>Fl_Widget::draw()</TT></A>
method). </LI>
<LI>Call <A href="Fl_Widget.html#Fl_Widget.do_callback"><TT>
Fl_Widget::do_callback()</TT></A> if a callback should be generated. </LI>
<LI>Call <TT>Fl_Widget::handle()</TT> on child widgets. </LI>
</UL>
Events are identified by the integer argument. Other information
\li Change the state of the widget.
\li Call
<A href="Fl_Widget.html#Fl_Widget.redraw"><tt>Fl_Widget::redraw()</tt></A>
if the widget needs to be redisplayed.
\li Call
<A href="Fl_Widget.html#Fl_Widget.damage"><tt>Fl_Widget::damage(n)</tt></A>
if the widget needs a partial-update (assuming you provide support for
this in your
<A href="#draw"><tt>Fl_Widget::draw()</tt></A>
method).
\li Call
<A href="Fl_Widget.html#Fl_Widget.do_callback"><tt>Fl_Widget::do_callback()</tt></A>
if a callback should be generated.
\li Call <tt>Fl_Widget::handle()</tt> on child widgets.
Events are identified by the integer argument. Other information
about the most recent event is stored in static locations and aquired
by calling the <A href="events.html#events"><TT>Fl::event_*()</TT></A>
functions. This information remains valid until another event is
by calling the
<A href="events.html#events"><tt>Fl::event_*()</tt></A>
functions. This information remains valid until another event is
handled.
<P>Here is a sample <TT>handle()</TT> method for a widget that acts as
a pushbutton and also accepts the keystroke 'x' to cause the callback: </P>
Here is a sample <tt>handle()</tt> method for a widget that acts as
a pushbutton and also accepts the keystroke 'x' to cause the callback:
\code
int MyClass::handle(int event) {
switch(event) {
@ -228,52 +300,62 @@ int MyClass::handle(int event) {
}
\endcode
<P>You must return non-zero if your <TT>handle()</TT> method
You must return non-zero if your <tt>handle()</tt> method
uses the event. If you return zero, the parent widget will try
sending the event to another widget.
<H2><A NAME="draw">Drawing the Widget</A></H2>
<A NAME="draw"></A> <!-- For old HTML links only ! -->
\section subclassing_drawing Drawing the Widget
<P>The <TT>draw()</TT> virtual method is called when FLTK wants
The <tt>draw()</tt> virtual method is called when FLTK wants
you to redraw your widget. It will be called if and only if
<TT>damage()</TT> is non-zero, and <TT>damage()</TT> will be
cleared to zero after it returns. The <TT>draw()</TT> method
<tt>damage()</tt> is non-zero, and <tt>damage()</tt> will be
cleared to zero after it returns. The <tt>draw()</tt> method
should be declared protected so that it can't be called from
non-drawing code.
<P>The <TT>damage()</TT> value contains the bitwise-OR of all
the <TT>damage(n)</TT> calls to this widget since it was last
The <tt>damage()</tt> value contains the bitwise-OR of all
the <tt>damage(n)</tt> calls to this widget since it was last
drawn. This can be used for minimal update, by only redrawing
the parts whose bits are set. FLTK will turn on the
<TT>FL_DAMAGE_ALL</TT> bit if it thinks the entire widget must
be redrawn, e.g. for an expose event. </P>
<tt>FL_DAMAGE_ALL</tt> bit if it thinks the entire widget must
be redrawn, e.g. for an expose event.
<P>Expose events (and the above <TT>damage(b,x,y,w,h)</TT>) will cause <TT>
draw()</TT> to be called with FLTK's <A href="drawing.html#clipping">
Expose events (and the above <tt>damage(b,x,y,w,h)</tt>) will cause <tt>
draw()</tt> to be called with FLTK's <A href="drawing.html#clipping">
clipping</A> turned on. You can greatly speed up redrawing in some
cases by testing <TT>fl_not_clipped(x,y,w,h)</TT> or <TT>fl_clip_box(...)</TT> and
skipping invisible parts. </P>
<P>Besides the protected methods described above, FLTK provides a large
number of basic drawing functions, which are described <A href="drawing.html#drawing">
below</A>. </P>
<H2>Resizing the Widget</H2>
The <TT>resize(int x, int y, int w, int h)</TT> method is called when
cases by testing <tt>fl_not_clipped(x,y,w,h)</tt> or <tt>fl_clip_box(...)</tt>
and skipping invisible parts.
Besides the protected methods described above, FLTK provides a large
number of basic drawing functions, which are described
<A href="drawing.html#drawing">below</A>.
\section subclassing_resizing Resizing the Widget
The <tt>resize(int x, int y, int w, int h)</tt> method is called when
the widget is being resized or moved. The arguments are the new
position, width, and height. <TT>x()</TT>, <TT>y()</TT>, <TT>w()</TT>,
and <TT>h()</TT> still remain the old size. You must call <TT>resize()</TT>
on your base class with the same arguments to get the widget size to
position, width, and height. <tt>x()</tt>, <tt>y()</tt>, <tt>w()</tt>,
and <tt>h()</tt> still remain the old size. You must call <tt>resize()</tt>
on your base class with the same arguments to get the widget size to
actually change.
<P>This should <I>not</I> call <TT>redraw()</TT>, at least if only the <TT>
x()</TT> and <TT>y()</TT> change. This is because composite widgets like <A href="Fl_Scroll.html#Fl_Scroll">
<TT>Fl_Scroll</TT></A> may have a more efficient way of drawing the new
position. </P>
<H2>Making a Composite Widget</H2>
A &quot;composite&quot; widget contains one or more &quot;child&quot; widgets.
To make a composite widget you should subclass <A href="Fl_Group.html#Fl_Group"><TT>Fl_Group</TT></A>
. It is possible to make a composite object that is not a subclass of <TT>
Fl_Group</TT>, but you'll have to duplicate the code in <TT>Fl_Group</TT>
anyways.
<P>Instances of the child widgets may be included in the parent: </P>
This should <I>not</I> call <tt>redraw()</tt>, at least if only the <tt>
x()</tt> and <tt>y()</tt> change. This is because composite widgets like
<A href="Fl_Scroll.html#Fl_Scroll"><tt>Fl_Scroll</tt></A>
may have a more efficient way of drawing the new position.
\section subclassing_composite Making a Composite Widget
A &quot;composite&quot; widget contains one or more &quot;child&quot; widgets.
To make a composite widget you should subclass
<A href="Fl_Group.html#Fl_Group"><tt>Fl_Group</tt></A>.
It is possible to make a composite object that is not a subclass of
<tt>Fl_Group</tt>, but you'll have to duplicate the code in <tt>Fl_Group</tt>
anyways.
Instances of the child widgets may be included in the parent:
\code
class MyClass : public Fl_Group {
Fl_Button the_button;
@ -281,9 +363,12 @@ class MyClass : public Fl_Group {
...
};
\endcode
The constructor has to initialize these instances. They are automatically
<TT>add()</TT>ed to the group, since the Fl_Group constructor does Fl_Group::begin().
<I>Don't forget to call Fl_Group::end() or use the Fl_End pseudo-class:</I>
The constructor has to initialize these instances. They are automatically
<tt>add()</tt>ed to the group, since the Fl_Group constructor does
Fl_Group::begin().
<I>Don't forget to call Fl_Group::end() or use the Fl_End pseudo-class:</I>
\code
MyClass::MyClass(int x, int y, int w, int h) :
Fl_Group(x, y, w, h),
@ -294,10 +379,12 @@ MyClass::MyClass(int x, int y, int w, int h) :
end(); // don't forget to do this!
}
\endcode
The child widgets need callbacks. These will be called with a pointer
to the children, but the widget itself may be found in the <TT>parent()</TT>
pointer of the child. Usually these callbacks can be static private
The child widgets need callbacks. These will be called with a pointer
to the children, but the widget itself may be found in the <tt>parent()</tt>
pointer of the child. Usually these callbacks can be static private
methods, with a matching private method:
\code
void MyClass::static_slider_cb(Fl_Widget* v, void *) { // static method
((MyClass*)(v-&gt;parent())-&gt;slider_cb();
@ -306,10 +393,12 @@ void MyClass::slider_cb() { // normal method
use(the_slider-&gt;value());
}
\endcode
If you make the <TT>handle()</TT> method, you can quickly pass all the
events to the children using the <TT>Fl_Group::handle()</TT> method.
You don't need to override <TT>handle()</TT> if your composite widget
If you make the <tt>handle()</tt> method, you can quickly pass all the
events to the children using the <tt>Fl_Group::handle()</tt> method.
You don't need to override <tt>handle()</tt> if your composite widget
does nothing other than pass events to the children:
\code
int MyClass::handle(int event) {
if (Fl_Group::handle(event)) return 1;
@ -317,10 +406,10 @@ int MyClass::handle(int event) {
}
\endcode
<P>If you override <TT>draw()</TT> you need to draw all the
children. If <TT>redraw()</TT> or <TT>damage()</TT> is called
on a child, <TT>damage(FL_DAMAGE_CHILD)</TT> is done to the
group, so this bit of <TT>damage()</TT> can be used to indicate
If you override <tt>draw()</tt> you need to draw all the
children. If <tt>redraw()</tt> or <tt>damage()</tt> is called
on a child, <tt>damage(FL_DAMAGE_CHILD)</tt> is done to the
group, so this bit of <tt>damage()</tt> can be used to indicate
that a child needs to be drawn. It is fastest if you avoid
drawing anything else in this case:
@ -339,93 +428,99 @@ int MyClass::draw() {
}
}
\endcode
<TT>Fl_Group</TT> provides some protected methods to make drawing
<tt>Fl_Group</tt> provides some protected methods to make drawing
easier:
<UL>
<LI><A href="#draw_child">draw_child</A></LI>
<LI><A href="#draw_outside_label">draw_outside_label</A></LI>
<LI><A href="#update_child">update_child</A></LI>
</UL>
<H4><A name="draw_child">void Fl_Group::draw_child(Fl_Widget&amp;)</A></H4>
This will force the child's <TT>damage()</TT> bits all to one and call <TT>
draw()</TT> on it, then clear the <TT>damage()</TT>. You should call
\li <A href="#draw_child">draw_child</A>
\li <A href="#draw_outside_label">draw_outside_label</A>
\li <A href="#update_child">update_child</A>
<A name="draw_child"></A> <!-- For old HTML links only ! -->
void Fl_Group::draw_child(Fl_Widget&)
\par
This will force the child's <tt>damage()</tt> bits all to one and call <tt>
draw()</tt> on it, then clear the <tt>damage()</tt>. You should call
this on all children if a total redraw of your widget is requested, or
if you draw something (like a background box) that damages the child.
Nothing is done if the child is not <TT>visible()</TT> or if it is
Nothing is done if the child is not <tt>visible()</tt> or if it is
clipped.
<H4><A name="draw_outside_label">void
Fl_Group::draw_outside_label(Fl_Widget&amp;) const</A></H4>
Draw the labels that are <I>not</I> drawn by <A href="#draw_label"><TT>
draw_label()</TT></A>. If you want more control over the label
positions you might want to call <TT>child-&gt;draw_label(x,y,w,h,a)</TT>.
<H4><A name="update_child">void Fl_Group::update_child(Fl_Widget&amp;)</A></H4>
Draws the child only if its <TT>damage()</TT> is non-zero. You
should call this on all the children if your own damage is equal to
FL_DAMAGE_CHILD. Nothing is done if the child is not <TT>visible()</TT>
or if it is clipped.
<H2>Cut and Paste Support</H2>
<A name="draw_outside_label"></A> <!-- For old HTML links only ! -->
void Fl_Group::draw_outside_label(Fl_Widget&) const
\par
Draw the labels that are <I>not</I> drawn by <A href="#draw_label"><tt>
draw_label()</tt></A>. If you want more control over the label
positions you might want to call <tt>child-&gt;draw_label(x,y,w,h,a)</tt>.
<A name="update_child"></A> <!-- For old HTML links only ! -->
void Fl_Group::update_child(Fl_Widget&)
\par
Draws the child only if its <tt>damage()</tt> is non-zero. You
should call this on all the children if your own damage is equal to
FL_DAMAGE_CHILD. Nothing is done if the child is not <tt>visible()</tt>
or if it is clipped.
\section subclassing_cutnpaste Cut and Paste Support
FLTK provides routines to cut and paste 8-bit text (in the future this
may be UTF-8) between applications:
<UL>
<LI><A href="Fl.html#Fl.paste"><TT>Fl::paste</TT></A></LI>
<LI><A href="Fl.html#Fl.selection"><TT>Fl::selection</TT></A></LI>
<LI><A href="Fl.html#Fl.selection_owner"><TT>Fl::selection_owner</TT></A></LI>
</UL>
It may be possible to cut/paste non-text data by using <A href="osissues.html#add_handler">
<TT>Fl::add_handler()</TT></A>.
<H2>Drag And Drop Support</H2>
\li <A href="Fl.html#Fl.paste"><tt>Fl::paste</tt></A>
\li <A href="Fl.html#Fl.selection"><tt>Fl::selection</tt></A>
\li <A href="Fl.html#Fl.selection_owner"><tt>Fl::selection_owner</tt></A>
It may be possible to cut/paste non-text data by using
<A href="osissues.html#add_handler"><tt>Fl::add_handler()</tt></A>.
\section subclassing_dragndrop Drag And Drop Support
FLTK provides routines to drag and drop 8-bit text between applications:
<P>Drag'n'drop operations are are initiated by copying data to the
Drag'n'drop operations are are initiated by copying data to the
clipboard and calling the function
<A href="Fl.html#Fl.dnd"><TT>Fl::dnd()</TT></A>.
<A href="Fl.html#Fl.dnd"><tt>Fl::dnd()</tt></A>.
<P>Drop attempts are handled via <A href="events.html#dnd">events</A>:
<UL>
<LI><TT>FL_DND_ENTER</TT></LI>
<LI><TT>FL_DND_DRAG</TT></LI>
<LI><TT>FL_DND_LEAVE</TT></LI>
<LI><TT>FL_DND_RELEASE</TT></LI>
<LI><TT>FL_PASTE</TT></LI>
</UL>
Drop attempts are handled via <A href="events.html#dnd">events</A>:
<H2>Making a subclass of Fl_Window</H2>
\li <tt>FL_DND_ENTER</tt>
\li <tt>FL_DND_DRAG</tt>
\li <tt>FL_DND_LEAVE</tt>
\li <tt>FL_DND_RELEASE</tt>
\li <tt>FL_PASTE</tt>
<P>You may want your widget to be a subclass of
<TT>Fl_Window</TT>, <TT>Fl_Double_Window</TT>, or
<TT>FL_Gl_Window</TT>. This can be useful if your widget wants
\section subclassing_fl_window Making a subclass of Fl_Window
You may want your widget to be a subclass of
<tt>Fl_Window</tt>, <tt>Fl_Double_Window</tt>, or
<tt>FL_Gl_Window</tt>. This can be useful if your widget wants
to occupy an entire window, and can also be used to take
advantage of system-provided clipping, or to work with a library
that expects a system window ID to indicate where to draw.
<P>Subclassing <TT>Fl_Window</TT>is almost exactly like
subclassing <TT>Fl_Group</TT>, and in fact you can easily
Subclassing <tt>Fl_Window</tt>is almost exactly like
subclassing <tt>Fl_Group</tt>, and in fact you can easily
switch a subclass back and forth. Watch out for the following
differences: </P>
differences:
<OL>
-# <tt>Fl_Window</tt> is a subclass of <tt>Fl_Group</tt> so
<I>make sure your constructor calls <tt>end()</tt></I>
unless you actually want children added to your window.
<LI><TT>Fl_Window</TT> is a subclass of
<TT>Fl_Group</TT> so <I>make sure your constructor calls
<TT>end()</TT></I> unless you actually want children
added to your window.</LI>
-# When handling events and drawing, the upper-left corner is at
0,0, not <tt>x(),y()</tt> as in other <tt>Fl_Widget</tt>'s.
For instance, to draw a box around the widget, call
<tt>draw_box(0, 0, w(), h())</tt>, rather than
<tt>draw_box(x(), y(), w(), h())</tt>.
<LI>When handling events and drawing, the upper-left
corner is at 0,0, not <TT>x(),y()</TT> as in other
<TT>Fl_Widget</TT>'s. For instance, to draw a box
around the widget, call <TT>draw_box(0, 0, w(),
h())</TT>, rather than <TT>draw_box(x(), y(), w(),
h())</TT>.</LI>
</OL>
<P>You may also want to subclass <TT>Fl_Window</TT> in order to
You may also want to subclass <tt>Fl_Window</tt> in order to
get access to different visuals or to change other attributes of
the windows. See <A href="osissues.html">"Appendix F - Operating
System Issues"</A> for more information.
the windows. See
<A href="osissues.html">"Appendix F - Operating System Issues"</A>
for more information.
<hr>
<a class="el" href="index.html">[Index]</a> &nbsp;&nbsp;