aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorenen92 <enen92@users.noreply.github.com>2019-03-21 10:30:35 +0000
committerGitHub <noreply@github.com>2019-03-21 10:30:35 +0000
commit8f348eb7aaba0a295c65fd93fa37bebc54ccbdf6 (patch)
tree82fb222a754f1c969487bc4ba8bdc4bd67e0959d
parent836ad543f9ffe8bc7a50b3e62348fd9f8293ba8d (diff)
parent89164446721904d1dd52f015c5360cf6d2ed018a (diff)
Merge pull request #15782 from enen92/warningreset
[pydocs] Add warning to ControlList().reset() regarding ListItem destruction
-rw-r--r--xbmc/interfaces/legacy/Control.h28
1 files changed, 27 insertions, 1 deletions
diff --git a/xbmc/interfaces/legacy/Control.h b/xbmc/interfaces/legacy/Control.h
index 8974f45dd5..ebe051ee41 100644
--- a/xbmc/interfaces/legacy/Control.h
+++ b/xbmc/interfaces/legacy/Control.h
@@ -1282,16 +1282,42 @@ namespace XBMCAddon
///-----------------------------------------------------------------------
/// Clear all ListItems in this control list.
///
+ /// @warning Calling `reset()` will destroy any `ListItem` objects in the
+ /// `ControlList` if not hold by any other class. Make sure you
+ /// you don't call `addItems()` with the previous `ListItem` references
+ /// after calling `reset()`. If you need to preserve the `ListItem` objects after
+ /// `reset()` make sure you store them as members of your `WindowXML` class (see examples).
+ ///
///
///-----------------------------------------------------------------------
///
- /// **Example:**
+ /// **Examples:**
/// ~~~~~~~~~~~~~{.py}
/// ...
/// cList.reset()
/// ...
/// ~~~~~~~~~~~~~
///
+ /// The below example shows you how you can reset the `ControlList` but this time avoiding `ListItem` object
+ /// destruction. The example assumes `self` as a `WindowXMLDialog` instance containing a `ControlList`
+ /// with id = 800. The class preserves the `ListItem` objects in a class member variable.
+ ///
+ /// ~~~~~~~~~~~~~{.py}
+ /// ...
+ /// # Get all the ListItem objects in the control
+ /// self.list_control = self.getControl(800) # ControlList object
+ /// self.listitems = [self.list_control.getListItem(item) for item in range(0, self.list_control.size())]
+ /// # Reset the ControlList control
+ /// self.list_control.reset()
+ /// #
+ /// # do something with your ListItem objects here (e.g. sorting.)
+ /// # ...
+ /// #
+ /// # Add them again to the ControlList
+ /// self.list_control.addItems(self.listitems)
+ /// ...
+ /// ~~~~~~~~~~~~~
+ ///
reset();
#else
virtual void reset();