Created attachment 88772 [details] [review]
Initial rough patch

Attaching an initial prod at integrating this into GtkEntry.  This is just to make sure I'm not going totally insane with how I'm manipulating the entry field.

To do:
- api documentation
- handle hinting in GtkEditable:get_characters implementation (cf gtk_entry_get_text)
- check that I don't need handle ->hinting in any more places

The patch also contains a test application which shows a "normal" entry and a "hinted" entry, with labels which are updated when the entries change to check that the hint cannot be obtained except via _get_hint().

I know that this kind of "hint" has become more popular recently, but I have some reservations about the design:

- it sends a mixed message: the insensitive appearance says "not editable", while
  the text says "edit me!"

- it shows text that looks like the "content" of the entry, but doesn't behave
  like it, e.g. can't be copied and pasted

In most cases, a clear label and/or a tooltip would probably work just as well without these drawbacks.

Rationale for hinting includes to add extra context (see the Evolution search bar), or for explaining what an entry is for (like a label would) without taking up the extra space (for small screens or compact interfaces).

I like the idea, its one of the UI concepts I've considered for showing properties inherited from a parent object. The parent's property text would be displayed in a hint like text, and could be over-ridden by typing in the entry.

Un-setting a parent property isn't immediately covered by this case, and I'm not sure how discoverable putting that option in a sexy icon is (E.g. The Evolution icon which sets the find options.)

Will the hint support markup to make the text italic, for example? This makes it look less like text which could be copy-pasted.

The current patch doesn't support markup, but always showing the hint in italic could be a good idea.

- too many font styles make for a messy ui appearance

- italic is not meaningful in certain typographies

That convinced me. :)

Ok, but I think italic may work in English. (I've not mocked it up to see how it looks though). If we allow markup, then the translators can add/remove what is meaningful for their typography. Does that seem a good compromise?

I'd really like to see this discussed with some usability/interface designer people, before committing to anything.

I think that recommending that the hints imply further action such as "New Task..." would be a better solution to markup.

one problematic aspect of the whole "conserve space by putting informative text in the empty entry" approach that I failed to mention so far:

Once the entry is not empty anymore, the informative text is gone. 
How is a user that comes to the scene at this point going to infer 
what the entry is about ? 

I don't think users would type into entries randomly.  Before it is focused, they'll see the message.  If they have no idea what the entry does they can delete the text and when they focus away, the hint will return.  They only need to use the entry once to understand what it is for.

Obviously this means that people replacing a table of label and entries with a table of hinted entries should be shot.  Hinted entries should be used sparingly, with obvious uses (such as Evolution search bar, Tasks new task bar).

an interesting twist would be using the "tooltip-markup" property to fill the hint for GtkEntry; this would make the hinting useful on touchscreen devices which do not have tooltip support.

so:

  g_object_set (entry, "tooltip-markup", "Write foo here", NULL);
  gtk_entry_set_enable_hint (GTK_ENTRY (entry), TRUE);

would show the value of "tooltip-markup" inside the entry (stripped of any real markup), with the text using the colour for the disabled state (it wouldn't look like a disabled entry, because the background colour would not change).

> I don't think users would type into entries randomly.  Before it is focused,
> they'll see the message.  If they have no idea what the entry does they can
> delete the text and when they focus away, the hint will return.  They only need
> to use the entry once to understand what it is for.

That is what you are saying now, but soon enough, people will forget about that
and just prefill the entry with the saved value from last time around - which is 
generally a good thing, but in this case, makes the hint useless.

Also, it doesn't help the user who typed something in the entry, switched to a different workspace, and comes back half a day later...

I second Matthias's concerns.  Evo moved to use such hints for the search target and it's not usable.

Emmanuele's suggestion on the other hand sounds good.

The widget set should be a useful toolkit, the "sense" and elegance of an UI comes from the design, how it is done.

I think this kind of functionality would be good idea, because it helps consistency - currently everyone seems to do this their own way which can lead into inconsistent implementations, being a lot worse.

I think this is especially helpful in handheld devices with small screen, but also for desktop to avoid unnecessary clutter. This would give yet another tool to use when needed.

I do see the problem of this looking "disabled" - but whether this is a real problem, or something we just think in our own heads is hard to say - if the hint text in an entry says "Add new entry..." it's still pretty obvious. I think this would need to be tested whether people really assume the widget is not active. Keep in mind the disabled entry *widget* itself has a different style nevertheless - the hint text is just a label inside otherwise active looking entry.

*** Bug 566741 has been marked as a duplicate of this bug. ***

I understand Mathias Clasen's reservations about this UI technique in general. But there are situations where there just isn't enough space to show the hint anywhere else, so it would be overall better to have the hint in the GtkEntry itself. That's particularly true in embedded UIs that have very large widgets.

Because this bug was unresolved, the Hildon API in Maemo 5 has awkward custom widgets (HildonEntry and HildonTextView) to add this functionality. It would be nice to deprecate them in favour of upstream GTK+ widgets in a future Maemo version. 

Maemo 5's GTK+ has now this implemented in GtkEntry and GtkTextView. I'll try to rebase the patches for GTK+'s master in the next days..

I campaigned against an equivalent attribute being included for text fields in HTML5 last year, on the grounds that making bad design more difficult to implement would discourage developers from doing it.
<http://lists.whatwg.org/pipermail/whatwg-whatwg.org/2008-November/017441.html>
I lost the argument in that case.
<http://www.w3.org/TR/html5/forms.html#the-placeholder-attribute>

Even if GTK+ makes it easy, I hope the Human Interface Guidelines will say "don't do that".

*** Bug 602090 has been marked as a duplicate of this bug. ***

Created attachment 162125 [details] [review]
maemo patch rebased against master

This is a cleaner version of the patch in Maemo 5, rebased against master, looking forward to 3.0..

Are there any chances to get this or similar merged into GTK+ or are you so diametrically opposed to it?

*** Bug 625919 has been marked as a duplicate of this bug. ***

At the very least, shouldn't the color of hints be other than INSENSITIVE?  

Otherwise it's entirely possible for unacceptably low contrast between the input box and the hinting text.  This is especially true as the Theme Manager allows for the Input box color to be set by a user without any indication of how it will affect the display of hinted input boxes.

Created attachment 172869 [details] [review]
Patch against master using tooltip-markup for the text

(In reply to comment #13)
> an interesting twist would be using the "tooltip-markup" property to
> fill the hint for GtkEntry

I like this idea, so I've taken the existing patch and updated it to
compile against master and use "tooltip-markup" instead.

I've tested it and it appears to work fine, but comments are of course
appreciated.

Created attachment 172870 [details]
Test case

And here's a test case

Created attachment 181822 [details] [review]
gtkentry: Add hinting to GtkEntry

This is alberto's patch updated to current git master, ported to GtkStyleContext and connecting to tooltip-text notify signals only when hint is enabled.

btw, to test it I used test/testentryicons using the props editor.

Quick comments:

- I don't like reusing the tooltip for this. It took me 10 seconds to spot the firefox search entry which has a hint text of 'Google' and a tooltip of 'Search using Google'. So better keep this separate.

- I don't think just blanket doing fg-color / 2 is going to work. Better to have a separate color for this that themes can set independently.

Another question that I have not seen discussed before is the a11y implications of displaying text that goes away on focus-in, since focusing a control is usually the way to get the screen reader to read the text to you...

Created attachment 182189 [details] [review]
gtkentry: Add hinting to GtkEntry

Updated patch according to comments:

 - Use gtk_entry_set_hint_text() instead of enable_hint() and use the tooltip text
 - Add hint_text_color to default css theme

(In reply to comment #31)
> Another question that I have not seen discussed before is the a11y implications
> of displaying text that goes away on focus-in, since focusing a control is
> usually the way to get the screen reader to read the text to you...

Could the hint text be exposed to ATs as the accessible description?

(In reply to comment #33)
> (In reply to comment #31)
> > Another question that I have not seen discussed before is the a11y implications
> > of displaying text that goes away on focus-in, since focusing a control is
> > usually the way to get the screen reader to read the text to you...
> 
> Could the hint text be exposed to ATs as the accessible description?

No reason it couldn't. I think we normally use the tooltip text for that if no description has been explicitly set.

(In reply to comment #34)
> (In reply to comment #33)
> > (In reply to comment #31)
> > > Another question that I have not seen discussed before is the a11y implications
> > > of displaying text that goes away on focus-in, since focusing a control is
> > > usually the way to get the screen reader to read the text to you...
> > 
> > Could the hint text be exposed to ATs as the accessible description?
> 
> No reason it couldn't. I think we normally use the tooltip text for that if no
> description has been explicitly set.

Yes, AFAIR, tooltip is the default description. So it would be just reimplement ->get_description on gailentry. And in the case of having both, I think that the more sensible option would be use the tooltip (so use hint text as the fallback option, when no tooltip or custom accessible description available)

Created attachment 182276 [details] [review]
gail: Implement AtkObject::get_description() in GailEntry

Patch for GailEntry. As suggested by API, the hint text is only used as description when GailWidget::get_description() returns NULL.

(In reply to comment #36)
> Created an attachment (id=182276) [details] [review]
> gail: Implement AtkObject::get_description() in GailEntry
> 

Thanks for doing this Carlos!

> Patch for GailEntry. As suggested by API, the hint text is only used as
> description when GailWidget::get_description() returns NULL.

From the perspective of Orca and its users, my question is: How do we get the hint text the rest of the time, i.e. when GailWidget::get_description() does not return NULL?

I personally think that what is most desirable is consistency. In other words, an assistive technology needs a reliable means by which it can get the hint text (for the purpose of presenting it to the user) and get the tooltip text (for the purpose of presenting it to the user). The presence or absence or one should not impact the other, IMHO.

FWIW, the way Orca users currently get the tooltip text from a Gtk+ widget is by pressing Ctrl+F1 to toggle the tooltip's appearance. When the appearance changes to showing/visible we get the appropriate events and are able to present the tooltip to the user from those events (i.e. we present the tooltip itself and NOT the description associated with the widget).

What I was suggesting in comment 33 is that the hint text always be exposed via the description. Mind you, I had forgotten that tooltip text comes to us this way as well. I completely understand if it is not desirable to change what is currently done with tooltip text. But then I would propose a different solution. For instance, what about always exposing the hint text as an AtkObject Attribute (e.g. 'hint':'bla bla bla')?

(Sorry....)

(In reply to comment #32)
> Created an attachment (id=182189) [details] [review]
> gtkentry: Add hinting to GtkEntry
> 
+  *
+  * The text taht will be displayed in the #GtkEntry when it is empty and unfocused.
+  *
Typo in there.

Question: Why do you keep an extra PangoLayout around for the hint text? I'd much prefer it if we just kept one layout around, namely the layout that is actually displayed. I suspect that's a bit more code to write, but it makes the code cleaner in that priv->cached_layout is the actual layout that is displayed at all times.

Last but not least, I don't like the name "hint", as that is not really correct.
HTML5 names it "placeholder" - see http://dev.w3.org/html5/spec/Overview.html#attr-input-placeholder - I think that's a much better name as it more accurately describes what that string is for.

(In reply to comment #38)
> Last but not least, I don't like the name "hint", as that is not
> really correct.  HTML5 names it "placeholder"

That's actually how we named it in Maemo-GTK as well.

I've reworked the patch to use one pango layout, and fix the typo mentioned by Company, and I'm about to rename hint_text as placeholder_text but I want to make sure we all agree before doing it.

Just to comment that I agree with Joanmarie (see comment 37) after a long discussion (that I think that lead her to write that comment).

In summary:

  * Although the tooltip can be accessed using Ctrl+F1, lets maintain the default accessible description as the tooltip
  * But, as it could be interesting to get the hint (or placeholder) *always*, expose it always, for example using attributes [1]


You can see as a example of this on gailwidget, as it exposes the toolkit. As with the method ref_state_set this should be done incrementally (so gailentry will call the parent get_attributes to get the attributes from the parent, and then add this new attribute).

This is somewhat more complex that just redefine the description, but have the advantage that we could always get the hint, and not just conditionally of having or not a tooltip.

[1] http://library.gnome.org/devel/atk/stable/AtkObject.html#atk-object-get-attributes

Created attachment 182937 [details] [review]
gtkentry: Add hinting to GtkEntry

Updated patch:

 - Using only one pango layout
 - Fixed the typo
 - Renamed to placeholder_text

Created attachment 182938 [details] [review]
gail: Implement AtkObject::get_attributes() in GailEntry

Use AtkObject::get_attributes() instead of AtkObject::get_description(). It still renames get/set_description to get/set_action_description becuase it's confusing.

While we are on it - the same should be done for GtkCellRendererText because it is used in the same way as GtkEntry regarding this matter. One example is the signal-editor for glade.

Review of attachment 182937 [details] [review]:

Seems to address all the points raised in review, looks good to me now.

Once thing that would be nice to have is an example for this in gtk3-demo. Maybe add some placeholder text to the 'Search Entry' example ?

::: gtk/gtkentry.c
@@ +5601,1 @@
 

This looks like an unrelated change, should be left out.

Review of attachment 182938 [details] [review]:

Looks ok to me.

(In reply to comment #45)
> Review of attachment 182937 [details] [review]:
> 
> Seems to address all the points raised in review, looks good to me now.
> 
> Once thing that would be nice to have is an example for this in gtk3-demo.
> Maybe add some placeholder text to the 'Search Entry' example ?

The problem with the search entry example is that the entry is always focused, so you don't see the placeholder text unless you move the focus to another widget. I'll add a new entry demo showing several entries with different placeholder texts

> ::: gtk/gtkentry.c
> @@ +5601,1 @@
> 
> 
> This looks like an unrelated change, should be left out.

Pushed to git master.