GNOME Bugzilla – Bug 154188
GTK_SELECTION_* needs documenting and explaining
Last modified: 2004-12-22 21:47:04 UTC
There aren't good user docs on what each of the selection modes means, and what an app developer can expect. For example, you _can_ get an empty list with GTK_SELECTION_BROWSE due to typeahead. Also, it starts out unselected. We need a way to stop people from doing: gtk_tree_selection_get_selected (selection, &model, &iter); gtk_tree_model_get (model, &iter, ...); without checking the return value of get_selected().
Here is what CVS head has in terms of GTK_SELECTION_MODE docs. Isn't this good enough ? @GTK_SELECTION_NONE: No selection is possible. @GTK_SELECTION_SINGLE: Zero or one element may be selected. @GTK_SELECTION_BROWSE: Exactly one element is always selected (this can be false after you have changed the selection mode). @GTK_SELECTION_MULTIPLE: Any number of elements may be selected. Clicks toggle the state of an item. Any number of elements may be selected. Click-drag selects a range of elements; the Ctrl key may be used to enlarge the selection, and Shift key to select between the focus and the child pointed to. @GTK_SELECTION_EXTENDED: Deprecated, behaves identical to %GTK_SELECTION_MULTIPLE.
"(this can be false after you have changed the selection mode)." probably would be better as "In some circumstances, such as initially or during a search operation, it's possible for no element to be selected with %GTK_SELECTION_BROWSE. What is really enforced is that the user can't deselect a currently selected element except by selecting another element."
What Owen said. The issue here is to make it clear to the developer that the selection mode are user behaviors, and not programatic invariants. We need to make sure they know what to write their code to handle. eg, BROWSE can have one or zero selected, but it won't ever have more than one.
2004-10-06 Matthias Clasen <mclasen@redhat.com> * gtk/tmpl/gtkenums.sgml: Clarify documentation for selection modes. (#154188, Jonathan Blandford, new wording proposed by Owen Taylor)