diff options
| author | Michael R Sweet <michael.r.sweet@gmail.com> | 2001-11-29 19:24:00 +0000 |
|---|---|---|
| committer | Michael R Sweet <michael.r.sweet@gmail.com> | 2001-11-29 19:24:00 +0000 |
| commit | 09daf20b81cdae78772f07c0af22a571d7cc73eb (patch) | |
| tree | 1641f788cafe20b505355b0479ba0d528297eb30 /documentation/events.html | |
| parent | b105ab8b7fb6281635076559aae96f2b3b12fc51 (diff) | |
Documentation updates galore (up to chapter 7, still need to do chapter
8 and 9, tweek the appendices, and recapture the screenshots...)
git-svn-id: file:///fltk/svn/fltk/branches/branch-1.1@1786 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
Diffstat (limited to 'documentation/events.html')
| -rw-r--r-- | documentation/events.html | 468 |
1 files changed, 283 insertions, 185 deletions
diff --git a/documentation/events.html b/documentation/events.html index 2eb847545..a742d69f4 100644 --- a/documentation/events.html +++ b/documentation/events.html @@ -1,238 +1,336 @@ -<HTML><BODY> -<H1 ALIGN=RIGHT><A NAME=events>6 - Handling Events</A></H1> - This chapter discusses the FLTK event model and how to handle events -in your program or widget. +<HTML> +<BODY> + +<H1 ALIGN="RIGHT"><A NAME="events">6 - Handling Events</A></H1> + +<P>This chapter discusses the FLTK event model and how to handle +events in your program or widget. + <H2>The FLTK Event Model</H2> -<P>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>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 -method. Other information about the most recent event is stored in +<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 <A -href=#event_xxx><TT>Fl::event_*()</TT></A> methods. This static -information remains valid until the next event is read from window -system (i.e. it is ok to look at it outside of the <TT>handle()</TT> -method). +href="#event_xxx"><TT>Fl::event_*()</TT></A> 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. <H2>Mouse Events</H2> + <H3>FL_PUSH</H3> -A mouse button has gone down with the mouse pointing at this widget. -You can find out what button by calling <A href="functions.html#event_button"><TT> -Fl::event_button()</TT></A>. You find out the mouse position by -calling <A href="functions.html#event_x"><TT>Fl::event_x()</TT></A> and <A href="functions.html#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="functions.html#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> + +<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>. + +<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> + <H3>FL_DRAG</H3> -The mouse has moved with a button held down. The current button state is -in <a href="functions.html#event_state"><tt>Fl::event_state()</tt></a>. The mouse position -is in <a href="functions.html#event_x"><tt>Fl::event_x()</tt></a> and -<a href="functions.html#event_y"><tt>Fl::event_y()</tt></a>. + +<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>. <P>To receive <CODE>FL_DRAG</CODE> events you must also respond to the <CODE>FL_PUSH</CODE> and <CODE>FL_RELEASE</CODE> events. <H3>FL_RELEASE</H3> - A mouse button has been released. You can find out what button by -calling <A href="functions.html#event_button"><TT>Fl::event_button()</TT></A>. + +<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>. + <H3>FL_MOVE</H3> - The mouse has moved without any mouse buttons held down. This event -is sent to the <A href="functions.html#belowmouse"><TT>Fl::belowmouse()</TT></A> + +<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. + +<H3>FL_MOUSEWHEEL</H3> + +<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 +vertically. + <H2>Focus Events</H2> + <H3>FL_ENTER</H3> - 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=functions.html#handle> -<TT>handle()</TT></A> method. It then becomes the <A href=functions.html#belowmouse> -<TT>Fl::belowmouse()</TT></A> widget and will receive <TT>FL_MOVE</TT> - and <TT>FL_LEAVE</TT> events. + +<P>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> +events. + <H3>FL_LEAVE</H3> - The mouse has moved out of the widget. + +<P>The mouse has moved out of the widget. + <H3>FL_FOCUS</H3> - 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=functions.html#handle> -<TT>handle()</TT></A> method. It then becomes the <A href=functions.html#focus> -<TT>Fl::focus()</TT></A> widget and gets <TT>FL_KEYBOARD</TT> and <TT> -FL_UNFOCUS</TT> events. </P> -<P>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=functions.html#event_key> -<TT>Fl::event_key()</TT></A> to figure out why it moved. For -navigation it will be the key pressed and for instructions from the -window manager it will be zero. </P> + +<P>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> +events. + +<P>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. + <H3>FL_UNFOCUS</H3> -Sent to the previous <A href=functions.html#focus><TT>Fl::focus()</TT></A> -widget when another widget gets the focus. + +<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. + <H2>Keyboard Events</H2> -<H3>FL_KEYBOARD</H3> - A key press. The key pressed can be found in <A href=functions.html#event_key> -<TT>Fl::event_key()</TT></A>. The text that the key should insert can -be found with <A href=functions.html#event_text><TT>Fl::event_text()</TT> -</A> and its length is in <A href=functions.html#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 assummes you ignored -the key. It 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. - -<P>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=#compose>Fl::compose()</a> function to translate -individual keystrokes into foreign characters. + +<H3>FL_KEYDOWN, FL_KEYUP</H3> + +<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 +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. + +<P>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. <H3>FL_SHORTCUT</H3> -If the <A href=functions.html#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>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=osissues.html#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> + +<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 +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 +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> + <H2>Widget Events</H2> + <H3>FL_DEACTIVATE</H3> - 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). + +<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 +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). + <H3>FL_ACTIVATE</H3> - 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. + +<P>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> - 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). +<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 +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> -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> +<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 +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> + <H2>Clipboard Events</H2> + <H3>FL_PASTE</H3> - You should get this event some time after you call <A href=functions.html#paste> -<TT>Fl::paste()</TT></A>. The contents of <A href=functions.html#event_text> -<TT>Fl::event_text()</TT></A> is the text to insert and the number of -characters is in <A href=functions.html#event_length><TT> -Fl::event_length()</TT></A>. + +<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>. + <H3>FL_SELECTIONCLEAR</H3> - The <A href=functions.html#selection_owner>Fl::selection_owner()</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=event_xxx>Fl::event_*() methods</A></H2> - 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>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="event_xxx">Fl::event_*() methods</A></H2> + +<P>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> + <UL> -<LI><A href=functions.html#event_button><TT>Fl::event_button</TT></A></LI> -<LI><A href=functions.html#event_clicks><TT>Fl::event_clicks</TT></A></LI> -<LI><A href=functions.html#event_inside><TT>Fl::event_inside</TT></A></LI> -<LI><A href=functions.html#event_is_click><TT>Fl::event_is_click</TT></A></LI> -<LI><A href=functions.html#event_key><TT>Fl::event_key</TT></A></LI> -<LI><A href=functions.html#event_length><TT>Fl::event_length</TT></A></LI> -<LI><A href=functions.html#event_state><TT>Fl::event_state</TT></A></LI> -<LI><A href=functions.html#event_text><TT>Fl::event_text</TT></A></LI> -<LI><A href=functions.html#event_x><TT>Fl::event_x</TT></A></LI> -<LI><A href=functions.html#event_x_root><TT>Fl::event_x_root</TT></A></LI> -<LI><A href=functions.html#event_y><TT>Fl::event_y</TT></A></LI> -<LI><A href=functions.html#event_y_root><TT>Fl::event_y_root</TT></A></LI> -<LI><A href=functions.html#get_key><TT>Fl::get_key</TT></A></LI> -<LI><A href=functions.html#get_mouse><TT>Fl::get_mouse</TT></A></LI> -<LI><A href=functions.html#test_shortcut><TT>Fl::test_shortcut</TT></A></LI> + + <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> + + <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> + + <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> + + <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> + + <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> + + <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> + + <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> + + <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> + + <LI><A HREF="Fl.html#Fl.test_shortcut"><TT>Fl::test_shortcut</TT></A></LI> + </UL> + <H2><A name=propagation>Event Propagation</A></H2> - 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 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 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 control those leaf widgets: </P> + +<P>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 +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 +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 +control those leaf widgets: + <UL> -<LI><A href=osissues.html#add_handler><TT>Fl::add_handler</TT></A></LI> -<LI><A href=functions.html#belowmouse><TT>Fl::belowmouse</TT></A></LI> -<LI><A href=functions.html#focus><TT>Fl::focus</TT></A></LI> -<LI><A href=functions.html#grab><TT>Fl::grab</TT></A></LI> -<LI><A href=functions.html#modal><TT>Fl::modal</TT></A></LI> -<LI><A href=functions.html#pushed><TT>Fl::pushed</TT></A></LI> -<LI><TT>Fl::release</TT></LI> -<LI><A href=Fl_Widget.html#Fl_Widget.take_focus><TT>Fl_Widget::take_focus</TT></A> -</LI> + + <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> + + <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> + + <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> + + <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> + </UL> -<H2><A name=compose>FLTK Compose-Character Sequences</A></H2> +<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 +<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 it's 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 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. - -<h4><tt>int Fl::compose(int& del)</tt></h4> +<p>FLTK uses its own compose processing to allow "preview" of +the partially composed sequence, which is impossible with the +usual "dead key" processing. -<p>Use of this function is very simple. Any text editing widget should -call this for each <tt>FL_KEYBOARD</tt> event. +<p>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>If <i>true</i> is returned, then it has modified the -Fl::event_text() and Fl::event_length() to a set of <i>bytes</i> to -insert (it may be of zero length!). In will also set the "del" -parameter to the number of <i>bytes</i> to the left of the cursor to -delete, this is used to delete the results of the previous call to -Fl::compose(). +<P>The following methods are provided for character composition: -<p>If <i>false</i> is returned, the keys should be treated as function -keys, and del is set to zero. You could insert the text anyways, if -you don't know what else to do. +<UL> -<p>Though the current implementation returns immediately, future -versions may take quite awhile, as they may pop up a window or do -other user-interface things to allow characters to be selected. + <LI><A HREF="Fl.html#Fl.compose"><TT>Fl::compose()</TT></A></LI> -<h4><tt>int Fl::compose_reset()</tt></h4> + <LI><A HREF="Fl.html#Fl.compose_reset"><TT>Fl::compose_reset()</TT></A></LI> -<p>If the user moves the cursor, be sure to call Fl::compose_reset(). -The next call to Fl::compose() will start out in an initial state. In -particular it will not set "del" to non-zero. This call is very fast -so it is ok to call it many times and in many places. +</UL> -</body></html> +</BODY> +</HTML> |