Bug 4598

Summary: HildonCheckButton documentation doesn't say why it exists
Product: [Maemo Official Platform] Desktop platform Reporter: Murray Cumming <murrayc>
Component: hildon-widgetsAssignee: Alberto Garcia Gonzalez <agarcia>
Status: RESOLVED FIXED QA Contact: hildon-libs-bugs
Severity: normal    
Priority: Low CC: agarcia, andre_klapper, dneary, ext-mox.soini
Version: 5.0-betaKeywords: docs
Target Milestone: 5.0 (1.2009.41-10)   
Hardware: All   
OS: Linux   

Description Murray Cumming (reporter) 2009-05-29 18:02:39 UTC
The HildonCheckButtons documentation
http://maemo.org/api_refs/5.0/alpha/libhildon/HildonCheckButton.html#HildonCheckButton.description
does not say why this class exists and should be used instead of
GtkCheckButton.

A screenshot might make that clearer but it should also be explained in text.
Hopefully this does more than just a rethemed GtkCheckButton.
Comment 1 Claudio Saavedra 2009-06-10 08:55:41 UTC
Moving to the widgets.
Comment 2 Andre Klapper maemo.org 2009-06-10 19:18:29 UTC
Mass-adding the new "docs" keyword. Sorry for the noise - You can filter your
bugmail by searching for "docs-cleanup-20090610".
Comment 3 Dave Neary maemo.org 2009-06-10 20:08:08 UTC
So - why does the widget exist? Anyone know?
Comment 4 Alberto Garcia Gonzalez 2009-06-11 18:19:02 UTC
HildonCheckButton is very similar to GtkCheckButton, but it was
created because it was not possible to obtain the desired look using
existing Gtk widgets.

So maybe it's a good idea to add a short note explaining that.
Comment 5 Alberto Garcia Gonzalez 2009-06-11 18:41:52 UTC
How about something like this?:

"HildonCheckButton is similar to the GtkCheckButton widget, but with a
different look that combines the appearance of a standard button with
that of a check box."
Comment 6 Murray Cumming (reporter) 2009-06-11 22:30:11 UTC
I think you need to mention that this could not be done by theming alone. I
take your word for that.

I guess you can ignore that this could be done by changing the GTK+
implementation because there seems to be general disagreement about whether
easier porting is preferable to API changes.

And you should mention that this appearance (not "look") is demanded by the
Hildon HIG, conveniently ignoring the fact that the Hildon HIG doesn't say why.
Comment 7 Alberto Garcia Gonzalez 2009-06-12 20:34:11 UTC
(In reply to comment #6)
> I think you need to mention that this could not be done by theming
> alone. I take your word for that.

I don't see why the widget documentation should say that.

For example, GtkCheckButton doesn't explain why it was created, or how
it is different from GtkToggleButton (appart from its appearance), or
the technical reasons why it can't be implemented with
GtkToggleButton.

http://library.gnome.org/devel/gtk/unstable/GtkCheckButton.html

It doesn't add new properties, new signals nor new API. It has the
same semantics as GtkToggleButton, yet it's a different widget.

And well, I never got confused because of that :-)
Comment 9 Murray Cumming (reporter) 2009-06-18 17:48:27 UTC
(In reply to comment #7)
> (In reply to comment #6)
> > I think you need to mention that this could not be done by theming
> > alone. I take your word for that.
> 
> I don't see why the widget documentation should say that.
> 
> For example, GtkCheckButton doesn't explain why it was created, or how
> it is different from GtkToggleButton (appart from its appearance), or
> the technical reasons why it can't be implemented with
> GtkToggleButton.

That's because applications have reasons to use both in the same UI.
(GtkToggleButton is useful when there is very little space, though
unfortunately neither the API nor the GNOME HIG mention that's purpose).

But there is _no_ time that a GtkCheckButton should be used in a Maemo 5
application. So it's reasonable for people to wonder why HildonCheckButton
exists just to change the appearance of a GtkCheckButton. Right now, the logic
is "Use GtkCheckButton (via GtkRadioButton's helpful API) if you want a radio
button, or use HildonCheckButton if you are using Hildon", which is strangely
arbitrary.
Comment 10 Alberto Garcia Gonzalez 2009-06-25 21:15:16 UTC
(In reply to comment #9)
> > For example, GtkCheckButton doesn't explain why it was created, or
> > how it is different from GtkToggleButton (appart from its
> > appearance), or the technical reasons why it can't be implemented
> > with GtkToggleButton.
> That's because applications have reasons to use both in the same UI.

There _is_ a reason to use GtkCheckButton: if you are using an
application written for Maemo 4.

In this case, we don't want to break those apps by changing
GtkCheckButton unconditionally.

I agree that this is debatable, though, but I don't think we can
change it at this point.

So, to have this bug fixed, what do you suggest for the
HildonCheckButton documentation?
Comment 11 Alberto Garcia Gonzalez 2009-09-03 20:37:32 UTC
I'd like to have this bug closed.

To summarize this: we support apps written with the Maemo 4 (or
desktop) UI style, hence we keep GtkCheckButton as it has always been
but we also provide HildonCheckButton, which has the style recommended
in Maemo 5.
Comment 12 Andre Klapper maemo.org 2009-09-04 18:07:59 UTC
(In reply to comment #11)
> I'd like to have this bug closed.

...and you already have the bug permissions to do this. :-)
So is that actually a question to the reporter whether he agrees, or how to
interpret?
Comment 13 Alberto Garcia Gonzalez 2009-09-04 19:14:42 UTC
(In reply to comment #12)
> > I'd like to have this bug closed.
> ...and you already have the bug permissions to do this. :-)
> So is that actually a question to the reporter whether he agrees, or
> how to interpret?

Ah, yes, I was just trying to summarize everything to see if anyone
has anything else to say before closing this.
Comment 14 Alberto Garcia Gonzalez 2009-09-11 15:17:40 UTC
Marking as fixed