STR #2041: Addition of a FL_TOOLTIP event (PoC)

STR #2041

Application:	FLTK Library
Status:	4 - Pending
Priority:	1 - Request for Enhancement, e.g. asking for a feature
Scope:	3 - Applies to all machines and operating systems
Subsystem:	Core Library
Summary:	Addition of a FL_TOOLTIP event (PoC)
Version:	1.4-feature
Created By:	alvin
Assigned To:	AlbrechtS
Fix Version:	Unassigned
Update Notification:	Receive EMails Don't Receive EMails

Trouble Report Files:

Post File

#1	alvin 11:12 Sep 11, 2008

SmartChoiceTest-v2.tar.gz
2k

#2	alvin 12:55 Sep 11, 2008

FL_TOOLTIP-v2.patch
1k

#3	alvin 12:55 Sep 11, 2008

SmartChoiceTest-v3.tar.gz
2k

#4	alvin 13:20 Sep 11, 2008

FL_TOOLTIP-v3.patch
1k

#5	alvin 13:20 Sep 11, 2008

SmartChoiceTest-v4.tar.gz
2k

#6	alvin 16:17 Sep 11, 2008

FL_TOOLTIP-v4.patch
1k

#7	alvin 02:12 Sep 12, 2008

FL_TOOLTIP-always fired.patch
1k

#8	alvin 02:12 Sep 12, 2008

SmartChoiceTest-always fired.tar.gz
2k

#9	AlbrechtS 07:23 Sep 12, 2008

Fl_Group_FL_TOOLTIP.patch
0k

#10	alvin 08:04 Sep 12, 2008

FL_TOOLTIP-v5.patch
2k

#11	alvin 08:05 Sep 12, 2008

FL_TOOLTIP_test-v5.tar.gz
3k

#12	alvin 02:48 Sep 18, 2008

names.h-FL_TOOLTIP.patch
0k

#13	alvin 07:41 Sep 22, 2008

FL_TOOLTIP-v6.patch
2k

#14	alvin 07:48 Oct 14, 2008

str2041-v7.patch
2k

#15	alvin 16:10 Jan 05, 2009

str2041-v8.patch
2k

#16	alvin 04:25 Aug 11, 2009

str2041-v10.patch
2k

#17	alvin 05:32 Mar 10, 2010

str2041-v11.patch
2k

#18	alvin 06:23 Oct 31, 2011

str2041-r9162.patch
2k

#19	alvin 05:27 Mar 29, 2012

str2041-r9310.patch
2k

#20	alvin 17:36 Jul 31, 2014

str2041-r9750.patch
2k

#21	alvin 08:12 Aug 27, 2015

str2041-r10844.patch
2k

Trouble Report Comments:

Post Text

#1	alvin 11:12 Sep 11, 2008

Resulting from my previous STR #2040 <http://www.fltk.org/str.php?L2040> I propose the following Proof-of-Concept) patch. This patch adds a FL_TOOLTIP event. The FL_TOOLTIP is sent, to the current widget, just prior to displaying a tooltip. If Fl_Tooltip::current()->handle(FL_TOOLTIP) returns 1, then the widget has 'used' the event. Therefore, the text use for the tooltip (i.e. tip in the source) will be updated. I am also including an example. The example may not be the best one since the widget (Fl_Smart_Choice) does not have a tooltip to start with. In this case, the tooltip is simply a space. Regardless, as the items are selected, you can see the tooltip being dynamically altered (if the selected item's text is longer than the width of the widget). To compile: fltk-config --compile smartchoice.cpp

#2	alvin 13:24 Sep 11, 2008

Well, it looks like I forgot to upload the patch! :) That's ok, I like FL_TOOLTIP-v3.patch better. The patch results in the addition of a FL_TOOLTIP event and an addition statement. That's it. 2 whole lines to get the FL_TOOPTIP event :) Basically, as long as the widget's tooltip is set to something, at the very least the empty string, it will receive the FL_TOOLTIP event. If the tooltip is null (as in tooltip(0)) the event will not be passed to the widget. I have updated the example program (SmartChoiceTest-v4.tar.gz). In the ctor for Fl_Smart_Choice the tooltip is set to the empty string. When the mouse enters the widget (and only that widget) the FL_TOOLTIP event will be past to the widget. That's where the widget decides if it needs a tooltip or not. The example also has two other buttons. One button has a tooltip set the normal way. The other button has no tooltip. Hopefully, this will be that last update patch on my end. How does the patch look? Any side effects that I may have missed/introduced?

#3	alvin 13:25 Sep 11, 2008

In case I wasn't clear, SmartChoiceTest-v4.tar.gz should be used to test FL_TOOLTIP-v3.patch. It would be easier if posted files could be deleted by the submitted of the file :)

#4	AlbrechtS 15:37 Sep 11, 2008

I didn't do any testing, but looking at FL_TOOLTIP-v3.patch, i see some problems: (1) there are some curly braces {} missing. This: if (tw == widget_) return; - if (tw->tooltip()) break; + if (tw->tooltip()) tw->handle(FL_TOOLTIP); break; should read: if (tw == widget_) return; - if (tw->tooltip()) break; + if (tw->tooltip()) { tw->handle(FL_TOOLTIP); break; } otherwise the break statement would always terminate the for loop. (2) However, I think that this wouldn't do what was intended: give the widget a chance to update its tooltip, before displaying the tooltip. Thus, I think it should be: if (tw == widget_) return; + tw->handle(FL_TOOLTIP); // ask the widget to update its tooltip if (tw->tooltip()) break; Note 1: We can't rely on a widget returning 1 from handle(FL_TOOLTIP), because the majority of widgets wouldn't know about FL_TOOLTIP at all (or wouldn't want to _change_ their tooltips) and would return 0. Note 2: The widget must get the FL_TOOLTIP event, even if it doesn't have a tooltip yet (tw->tooltip() == NULL). Otherwise a widget would never get a chance to set its tooltip for the first time. Unless we want to enable the widget only to _change_ its tooltip - i.e. it must have a tooltip to get FL_TOOLTIP events. (3) There is at least one other place in the code to consider, a similar search for the tooltip to display in Fl_Tooltip::current(). Other than this, I think that this would improve FLTK's tooltip handling. Still to be tested.

#5	alvin 16:23 Sep 11, 2008

I posted FL_TOOLTIP-v4.patch which includes the bug fix found by Albrecht Schlosser. The last posted example still valid for testing. Here is how I see the feature working (copied from one of my posts in the newsgroup discussing this STR): <quote> ... // So, at this point, we know the widget has a tooltip and it's pointed to by Fl_Tooltip::tip. // FL_TOOLTIP is sent to tell the widget we are about to draw it's tooltip. // If the widget returns 0, then the widget doesn't care and the tooltip is handle as before. // If the widget returns 1, then the widget used the event, therefore we need to // update the pointer we will be using for rendering the tooltip. // If the widget sets the tooltip to the empty string, no tooltip will be drawn (like before). // The widget will continue to receive the FL_TOOLTIP in the future. // If the widget sets the tooltip to null (0), then it will never receive this // event again - thus making its tooltip static. </quote> Is this the desired functionality of FL_TOOLTIP or am I mistaken?

#6	AlbrechtS 00:08 Sep 12, 2008

I understand your idea, not to send the FL_TOOLTIP event to widgets with the NULL tooltip, and this would be one possible solution. However, I have always had a (small) problem with this tooltip inheritance from parent widgets to child widget. It is documented in [1] with this additional note: "To avoid this behavior, you can set the child's tooltip to an empty string ("")." Therefore, here is my proposal to extend the tooltip functionality in a logical (and compatible) way with this new FL_TOOLTIP event: If a widget returns 1 from FL_TOOLTIP, this means that its tooltip should be used, no matter if it's empty (no tooltip, the NULL pointer) or not. Old widgets or widgets that don't "know" FL_TOOLTIP would return 0 and get the old behavior. With this feature, a widget could decide most flexible, if it wants to show no tooltip at all, an own tooltip, or a parent's tooltip. For this to work, we would have to send the FL_TOOLTIP event also to widgets that have the NULL tooltip.

#8	AlbrechtS 00:22 Sep 12, 2008

Sorry, I forgot the documentation link: [1] http://www.fltk.org/doc-1.3/Fl_Widget.html#Fl_Widget.tooltip

#9	alvin 02:25 Sep 12, 2008

I have attached FL_TOOLTIP-always fired.patch along with an example SmartChoiceTest-always fired.tar.gz. This patch is very similar to v4 of the patch except that the FL_TOOLTIP event is sent to the widget _before_ checking if the widget has a tooltip. My initial idea/understanding for the FL_TOOLTIP event was to sent it to a widget even if it has a tooltip or not. However, the result was not what I expected. I thought the event would be sent to the widget under the cursor. That is not the case. It turns out the FL_TOOLTIP event is sent to every widget regardless of the location of the cursor. For example, apply this patch and run the example. When the cursor is over the text area, the Fl_Smart_Choice receives the FL_TOOLTIP event (printf statement to stdout) even though the cursor is no where near it. I think the cause of this has to do how/when Fl_Tooltip::enter_() is called (I think in Fl.cxx). I didn't look into this further since I assumed that the excessive, irrelevant FL_TOOLTIP events would be undesirable (much like how excessive, unwarranted FL_MOVE events are undesirable). At this point, I recommend FL_TOOLTIP-v4.patch. However, guidance/comments/suggestion would be much appreciated.

#10	AlbrechtS 03:22 Sep 12, 2008

My guess (wrt sending FL_TOOLTIP events around to all widgets) would be that it has to do with FLTK's intent to deliver every event to at least one widget, but I can't do anymore right now (lack of time). If all widgets in the widget's parent() chain return 0 on the FL_TOOLTIP event, then FLTK (maybe Fl_Group::handle()) tries to send it to every widget in the group (recursive) - i.e. finally to all widgets in the window. Maybe the same as with FL_MOVE events.

#11	matt 04:11 Sep 12, 2008

Phew, a lot of messages going back and forth here ;-) This is my take: - tooltip events are very rare. they must only be sent right before the tooltip would actually pop up (usually after the timer expires). I see no problem in sending a TOOLTIP event even if the ttoltip itself is set to NULL. - when the handle() returns and a tooltip is set, we display it and are done (if the tooltip is "", we are done without displaying it) - if handle() returns 1 and no tooltip is set, we are done (no tooltip rendered) - if handle() return 0 and tooltip is NULL, we continue to call hande(TOOLTIP) on the parent until the parent is NULL (or any of the previous conditions) That way, we should work transparently for existing widgets, but keep the tooltip inheritance feature. My example for active tooltips is a function curve editor where hovering the mouse over a curve would pop up a tooltip with the coordinates of the curve at the mouse position. Very useful.

#12	alvin 06:01 Sep 12, 2008

Sounds good to me. So far, FL_TOOLTIP-v4.patch does all but sending the FL_TOOLTIP to widget's with NULL tooltips. So that's 3 out of 4 of the criteria. I will update the patch to do the first criteria (NULL tooltips). The FL_TOOLTIP-always fired.patch does this but I am not completely happy with it. What that patch shows on stdout is that the Fl_Smart_Choice widget receives the FL_TOOLTIP event even though the cursor is not on it; it is on the Fl_Box with the text. I think this can be solved.

#13	AlbrechtS 07:32 Sep 12, 2008

Alvin, could you please try this short patch for Fl_Group: http://www.fltk.org/strfiles/2041/Fl_Group_FL_TOOLTIP.patch If my assumption WRT FL_TOOLTIP event handling is correct, then this should solve the problem that unrelated widgets get FL_TOOLTIP events. Or maybe not - it's untested.

#14	alvin 08:13 Sep 12, 2008

Ok, I think Albrecht and I have this solved. FL_TOOLTIP-v5.patch should satisfy all 4 criteria posted by Matthias. Basically the patch is a merge of "FL_TOOLTIP-always fired.patch" and FL_Group_FL_TOOLTIP.patch. I added some documentation where the FL_TOOLTIP event is fired. I have also documented the FL_TOOLTIP enum in Enumerations.H. The new test app, FL_TOOLTIP_test-v5.tar.gz, hopefully covers most (all?) the cases. Note 1. The dynamic tooltip for MyGroup widget is that the current time is put into the tooltip. ctime_r() is used, and I do not know if locale is taken into consideration. I just used it cause it returned gives a char* :) Note 2. The ctor for Fl_Smart_Choice no longer sets the tooltip to anything. Therefore, by default, it should be null. I don't think it matters too much, but the patch was created against r6190 (the last 1.3 cvs snapshot).

#15	alvin 02:49 Sep 18, 2008

I have posted a patch for FL/names.h to include FL_TOOLTIP in the fl_eventnames array. I have been using FL_TOOLTOP-v5.patch for almost a week now without any problems.

#16	AlbrechtS 16:53 Sep 18, 2008

Thanks for adding this. I'll have another look at your patch shortly.

#17	AlbrechtS 01:32 Sep 19, 2008

I added a svn branch for testing and commited the patches. Not yet tested. URL: http://svn.easysw.com/public/fltk/fltk/branches/branch-1.3-FL_TOOLTIP

#18	alvin 07:42 Sep 22, 2008

I have posted an updated patch that applies cleanly to 1.1.x-r6305. FL_TOOLTIP-v6.patch is a combined patch that includes the changes needed to FL/Enumerations.H, FL/names.h, src/Fl_Tooltip.cxx and src/Fl_Group.cxx.

#19	alvin 07:49 Oct 14, 2008

I have updated the patch to v7 (str2041-v7.patch). This applies cleanly to 1.3 r6427. As before, this patch changes names.H, Enumeration.H, Fl_Group.cxx and Fl_Tooltip.cxx.

#20	AlbrechtS 10:12 Oct 14, 2008

Alvin, thanks for updating the patch again. I'm sorry that it took so long for me to do some more testing. I'm now working on a modified patch that sends the FL_TOOLTIP event when the tooltip timeout expires, as Matthias suggested, but the main problem is to stay compatible with Fl_Tooltip::enter_area(). This can set an *alternate* tooltip without modifying the widget's own tooltip(). I'll post an update, when I have a working and compatible new patch.

#21	alvin 16:11 Jan 05, 2009

Updated patch: str2041-v8.patch Patch applies cleanly to 1.3.x r6622

#22	alvin 04:26 Aug 11, 2009

Uploaded patch that compiles against SVN rev 6841

#23	alvin 05:32 Mar 10, 2010

Posted an updated patch that can be applied to (at the time) latest svn (rev 7235)

#24	alvin 06:23 Oct 31, 2011

Posted update patch file for svn revision 9162.

#25	alvin 05:28 Mar 29, 2012

Updated patch to r9310. Cheers.

#26	alvin 17:43 Jul 31, 2014

Attached is a patch (str2041-r9750.patch) that adds the FL_TOOLTIP event type. I have been applying this patch since 2008 and I have found it very useful. Off the top of my head, I can think of two use cases: 1. Custom widgets that derive from Fl_Slider. The current value is displayed in the tooltip. It doesn't appear all the time, but I use it to inspect the current value. 2. Custom widgets that display a label that is truncated (e.g. "The quick brown fox..."). When the FL_TOOLTIP event is received, the custom widget displays the full label (e.g. The quick brown fox jumped over the lazy dog."). Despite its filename, the patch applies cleanly to FLTK 1.3.x SVN r10223.

#27	alvin 08:14 Aug 27, 2015

Uploaded new patch for SVN r10844. This does replace FL_EVENT_27 with the FL_TOOLTIP event.