diff options
Diffstat (limited to 'documentation')
| -rw-r--r-- | documentation/events.dox | 411 | ||||
| -rw-r--r-- | documentation/opengl.dox | 319 | ||||
| -rw-r--r-- | documentation/subclassing.dox | 551 |
3 files changed, 681 insertions, 600 deletions
diff --git a/documentation/events.dox b/documentation/events.dox index 6f4db3c1c..f41628bdf 100644 --- a/documentation/events.dox +++ b/documentation/events.dox @@ -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 "wants" 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 "wants" 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 "global" 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 "global" 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. - -<P>These are all trivial inline functions and thus very fast and small: </P> +processed. Thus it is valid inside <tt>handle()</tt> and +<tt>callback()</tt> methods. -<UL> +These are all trivial inline functions and thus very fast and small: - <LI><A HREF="Fl.html#Fl.event_button"><TT>Fl::event_button</TT></A></LI> +\li <A HREF="Fl.html#Fl.event_button"><tt>Fl::event_button</tt></A> - <LI><A HREF="Fl.html#Fl.event_clicks"><TT>Fl::event_clicks</TT></A></LI> +\li <A HREF="Fl.html#Fl.event_clicks"><tt>Fl::event_clicks</tt></A> - <LI><A HREF="Fl.html#Fl.event_dx"><TT>Fl::event_dx</TT></A></LI> +\li <A HREF="Fl.html#Fl.event_dx"><tt>Fl::event_dx</tt></A> - <LI><A HREF="Fl.html#Fl.event_dy"><TT>Fl::event_dy</TT></A></LI> +\li <A HREF="Fl.html#Fl.event_dy"><tt>Fl::event_dy</tt></A> - <LI><A HREF="Fl.html#Fl.event_inside"><TT>Fl::event_inside</TT></A></LI> +\li <A HREF="Fl.html#Fl.event_inside"><tt>Fl::event_inside</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_is_click"><tt>Fl::event_is_click</tt></A> - <LI><A HREF="Fl.html#Fl.event_key"><TT>Fl::event_key</TT></A></LI> +\li <A HREF="Fl.html#Fl.event_key"><tt>Fl::event_key</tt></A> - <LI><A HREF="Fl.html#Fl.event_length"><TT>Fl::event_length</TT></A></LI> +\li <A HREF="Fl.html#Fl.event_length"><tt>Fl::event_length</tt></A> - <LI><A HREF="Fl.html#Fl.event_state"><TT>Fl::event_state</TT></A></LI> +\li <A HREF="Fl.html#Fl.event_state"><tt>Fl::event_state</tt></A> - <LI><A HREF="Fl.html#Fl.event_text"><TT>Fl::event_text</TT></A></LI> +\li <A HREF="Fl.html#Fl.event_text"><tt>Fl::event_text</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"><tt>Fl::event_x</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_x_root"><tt>Fl::event_x_root</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"><tt>Fl::event_y</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.event_y_root"><tt>Fl::event_y_root</tt></A> - <LI><A HREF="Fl.html#Fl.get_key"><TT>Fl::get_key</TT></A></LI> +\li <A HREF="Fl.html#Fl.get_key"><tt>Fl::get_key</tt></A> - <LI><A HREF="Fl.html#Fl.get_mouse"><TT>Fl::get_mouse</TT></A></LI> +\li <A HREF="Fl.html#Fl.get_mouse"><tt>Fl::get_mouse</tt></A> - <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 "interests" (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> +\li <A HREF="Fl.html#Fl.add_handler"><tt>Fl::add_handler</tt></A> - <LI><A HREF="Fl.html#Fl.belowmouse"><TT>Fl::belowmouse</TT></A></LI> +\li <A HREF="Fl.html#Fl.belowmouse"><tt>Fl::belowmouse</tt></A> - <LI><A HREF="Fl.html#Fl.focus"><TT>Fl::focus</TT></A></LI> +\li <A HREF="Fl.html#Fl.focus"><tt>Fl::focus</tt></A> - <LI><A HREF="Fl.html#Fl.grab"><TT>Fl::grab</TT></A></LI> +\li <A HREF="Fl.html#Fl.grab"><tt>Fl::grab</tt></A> - <LI><A HREF="Fl.html#Fl.modal"><TT>Fl::modal</TT></A></LI> +\li <A HREF="Fl.html#Fl.modal"><tt>Fl::modal</tt></A> - <LI><A HREF="Fl.html#Fl.pushed"><TT>Fl::pushed</TT></A></LI> +\li <A HREF="Fl.html#Fl.pushed"><tt>Fl::pushed</tt></A> - <LI><A HREF="Fl.html#Fl.release"><TT>Fl::release</TT></A></LI> +\li <A HREF="Fl.html#Fl.release"><tt>Fl::release</tt></A> - <LI><A HREF="Fl_Widget.html#Fl_Widget.take_focus"><TT>Fl_Widget::take_focus</TT></A></LI> +\li <A HREF="Fl_Widget.html#Fl_Widget.take_focus"><tt>Fl_Widget::take_focus</tt></A> -</UL> +<A name="compose"></A> <!-- For old HTML links only ! --> +\section events_compose_characters FLTK Compose-Character Sequences -<H2><A name="compose">FLTK Compose-Character Sequences</A></H2> +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>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: - -<UL> - - <LI><A HREF="Fl.html#Fl.compose"><TT>Fl::compose()</TT></A></LI> +The following methods are provided for character composition: - <LI><A HREF="Fl.html#Fl.compose_reset"><TT>Fl::compose_reset()</TT></A></LI> +\li <A HREF="Fl.html#Fl.compose"><tt>Fl::compose()</tt></A> -</UL> +\li <A HREF="Fl.html#Fl.compose_reset"><tt>Fl::compose_reset()</tt></A> <hr> <a class="el" href="index.html">[Index]</a> diff --git a/documentation/opengl.dox b/documentation/opengl.dox index c06d1bb4d..4fd6d6ec0 100644 --- a/documentation/opengl.dox +++ b/documentation/opengl.dox @@ -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> - -<P>You must include FLTK's <TT><FL/gl.h></TT> header -file. It will include the file <TT><GL/gl.h></TT>, define +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. + +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> - -<H2>Making a Subclass of Fl_Gl_Window</H2> - -<P>To make a subclass of Fl_Gl_Window, you must provide: +<tt><windows.h></tt> header file needed by WIN32 +applications. -<UL> +\section opengl_subclass Making a Subclass of Fl_Gl_Window - <LI>A class definition.</LI> +To make a subclass of Fl_Gl_Window, you must provide: - <LI>A <TT>draw()</TT> method.</LI> +\li A class definition. - <LI>A <TT>handle()</TT> method if you need to receive - input from the user.</LI> +\li A <tt>draw()</tt> method. -</UL> +\li A <tt>handle()</tt> method if you need to receive input from the user. -<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: - -<OL> - - <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 +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: + +-# 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. + +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> - - <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><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 +\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 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> + +\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. + +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> diff --git a/documentation/subclassing.dox b/documentation/subclassing.dox index 865f58cb8..4b9cf82d0 100644 --- a/documentation/subclassing.dox +++ b/documentation/subclassing.dox @@ -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() & (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 + +\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. -<P>Draws a focus box inside the widgets bounding box. The second +<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 "centered" 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 '&' 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 '&' 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 '&' 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 '&' 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 "composite" widget contains one or more "child" 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 "composite" widget contains one or more "child" 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->parent())->slider_cb(); @@ -306,10 +393,12 @@ void MyClass::slider_cb() { // normal method use(the_slider->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&)</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&) 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->draw_label(x,y,w,h,a)</TT>. -<H4><A name="update_child">void Fl_Group::update_child(Fl_Widget&)</A></H4> - Draws the child only if its <TT>damage()</TT> is non-zero. You + +<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->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. +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 -<H2>Cut and Paste Support</H2> 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>. - -<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> - -<H2>Making a subclass of Fl_Window</H2> - -<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 +<A href="Fl.html#Fl.dnd"><tt>Fl::dnd()</tt></A>. + +Drop attempts are handled via <A href="events.html#dnd">events</A>: + +\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> + +\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> - -<OL> - - <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> +differences: - <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> +-# <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. -</OL> +-# 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>. -<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> |