Re: Conflicting recommendations about using GTK_BIN(widget)->child in Gtk+ documentation

["Brian J. Tarricone" <bjt23 cornell edu>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Kalle Vahlman wrote:
> Hi all.
> 
> I noticed that there is a conflict in what GtkBin docs say:
> 
> http://developer.gnome.org/doc/API/2.0/gtk/GtkBin.html#GtkBin-struct
> "
> The GtkBin-struct struct contains the following fields. (These fields
> should be considered read-only. They should never be set by an
> application.)
> 
> GtkWidget *child; 	the child widget.
> "
> 
> and what the GtkComboBoxEntry docs say:
> 
> http://developer.gnome.org/doc/API/2.0/gtk/GtkComboBoxEntry.html#gtk-combo-box-entry-new-with-model
> "
> You can get the GtkEntry from a GtkComboBoxEntry using GTK_ENTRY
> (GTK_BIN (combo_box_entry)->child).
> "
> 
> So either the GtkBin or GtkComboBoxEntry docs needs to be changed in
> this regard.

I'm not really seeing how these disagree.  The GtkBin docs say you can
access the child via the struct, but to consider it read-only.  The
GtkComboBoxEntry docs say you can access its GtkEntry by getting the
child of the GtkBin via the struct, which doesn't IMO contradict the
GtkBin documentation.

> Considerations:
> 
> 1) GTK_BIN(widget)->child is officially available as
> gtk_bin_get_child(), so it's not like it would be required to retrieve
> the entry from a GtkComboBoxEntry.

gtk_bin_get_child(), however, survives changes in implementation that
would make GTK_BIN(widget)->child possibly not behave as intended.  Not
that I can see something like that happening in the 2.x series, but it's
true in the general case.

> 2) GTK_BIN(widget)->child is insanely more pleasant to use in code,
> and a little more object oriented than gtk_bin_get_child() (which is
> in my books always a good thing :)

I think the opposite is true: good OO practices (as I understand them,
anyway) seem to indicate using getter and setter methods to access
member variables instead of accessing the variables directly, so
gtk_bin_get_child() makes a bit more sense here. I do agree that
GTK_BIN(widget)->child is easier to use in code, however.

> 3) Use of public widget struct members are used succesfully with
> GtkDialog (->vbox and ->action_area), so it's not like doing something
> new.

True, but just because it's done elsewhere doesn't mean it's good
practice.  Some of this stuff was probably left over from gtk 1.x to
ease porting.

> 4) Given the GtkComboBoxEntry docs recommendation and personal
> observations, GTK_BIN(widget)->child is a common trait so it can't
> really be considered as a contender for change in any way without
> breaking a multitude of code. No point in trying to hide it instead of
> embracing it, right?-)

I'm not sure why this is even a consideration: no one's advocating
removing the GTK_BIN(widget)->child functionality, and the
GtkComboBoxEntry docs don't contradict GtkBin's warning that the child
struct member is read-only.  There doesn't appear to be any effort to
hide it, either.

> So my score is on the side of admitting GtkBin->child as a public
> member in the docs, what's yours?

It *is* considered a public member (albeit read-only) in the docs, so I
don't see the problem.

Cheers,
Brian

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2 (GNU/Linux)

iD8DBQFDuljG6XyW6VEeAnsRAt9NAKCcci8YFfrVHTtaGeMgUMzE8XbetgCg1QO6
RUqqS5Fx7ZqU58VfIy6mEtc=
=J+52
-----END PGP SIGNATURE-----