Improve wxListCtrl::SetItemState() documentation.

Better explain the meaning of its parameters.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@70910 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

diff --git a/interface/wx/listctrl.h b/interface/wx/listctrl.h
index 6a7a539801d63c4123db9e74ba64f7aafe935a3f..a0b397013c9c5fb266054d029c284b41033bee41 100644 (file)
--- a/interface/wx/listctrl.h
+++ b/interface/wx/listctrl.h
@@ -971,8 +971,24 @@ public:
     bool SetItemPtrData(long item, wxUIntPtr data);
 
     /**
-        Sets the item state. For a list of state flags, see SetItem().
-        The @b stateMask indicates which state flags are valid.
+        Sets the item state.
+
+        The @a stateMask is a combination of @c wxLIST_STATE_XXX constants
+        described in wxListItem documentation. For each of the bits specified
+        in @a stateMask, the corresponding state is set or cleared depending on
+        whether @a state argument contains the same bit or not.
+
+        So to select an item you can use
+        @code
+            list->SetItemState(item, wxLIST_STATE_SELECTED, wxLIST_STATE_SELECTED);
+        @endcode
+        while to deselect it you should use
+        @code
+            list->SetItemState(item, 0, wxLIST_STATE_SELECTED);
+        @endcode
+
+        Consider using wxListView if possible to avoid dealing with this
+        error-prone and confusing method.
     */
     bool SetItemState(long item, long state, long stateMask);