OpenWalnut  1.4.0
WItemSelector.h
1 //---------------------------------------------------------------------------
2 //
3 // Project: OpenWalnut ( http://www.openwalnut.org )
4 //
5 // Copyright 2009 OpenWalnut Community, BSV@Uni-Leipzig and CNCF@MPI-CBS
6 // For more information see http://www.openwalnut.org/copying
7 //
8 // This file is part of OpenWalnut.
9 //
10 // OpenWalnut is free software: you can redistribute it and/or modify
11 // it under the terms of the GNU Lesser General Public License as published by
12 // the Free Software Foundation, either version 3 of the License, or
13 // (at your option) any later version.
14 //
15 // OpenWalnut is distributed in the hope that it will be useful,
16 // but WITHOUT ANY WARRANTY; without even the implied warranty of
17 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 // GNU Lesser General Public License for more details.
19 //
20 // You should have received a copy of the GNU Lesser General Public License
21 // along with OpenWalnut. If not, see <http://www.gnu.org/licenses/>.
22 //
23 //---------------------------------------------------------------------------
24 
25 #ifndef WITEMSELECTOR_H
26 #define WITEMSELECTOR_H
27 
28 #include <istream>
29 #include <ostream>
30 #include <vector>
31 #include <string>
32 
33 #ifndef Q_MOC_RUN
34 #include <boost/shared_ptr.hpp>
35 #endif
36 #ifndef Q_MOC_RUN
37 #include <boost/signals2/signal.hpp>
38 #endif
39 
40 #include "WItemSelection.h"
41 #include "WItemSelectionItem.h"
42 
43 
44 /**
45  * This class represents a subset of a WItemSelection. It is a class for managing selections. The class is kept very restrictive. The selection
46  * can't be edited after the instantiation of the class to keep the interface clean, easily usable and consistent among multiple threads. So
47  * please DO NOT extend it to provide methods for changing it!
48  *
49  * This class can be seen as some kind of special "iterator" providing access to the underlying set without allowing it to be modified. The class
50  * provides methods to access the whole set and the subset represented by itself. The restrictive interface ensures thread-safety and enforces
51  * that each new selection is done by a new instance of this class, which is needed by the WPropertyVariable to work properly.
52  *
53  * \note the protected constructor avoids instance creation of classes not the WItemSelection. This is restrictive but needed. Nobody can create
54  * instances of it, changing the underlying WItemSelection and using it as selector for another ItemSelection instance.
55  */
56 class WItemSelector // NOLINT
57 {
58 friend class WItemSelection;
59 public:
60  /**
61  * The type used for storing index lists. It is a list of integer correlating with the elements in the managed WItemSelection class.
62  */
63  typedef std::vector< size_t > IndexList;
64 
65  /**
66  * Copy constructor. Creates a new copy of the selector and ensure proper signal subscriptions to the underlying selection.
67  *
68  * \param other the selector to copy
69  */
70  WItemSelector( const WItemSelector& other );
71 
72  /**
73  * Copy assignment. Creates a new copy of the selector and ensure proper signal subscriptions to the underlying selection.
74  *
75  * \param other the selector to copy
76  *
77  * \return this.
78  */
79  WItemSelector& operator=( const WItemSelector & other );
80 
81  /**
82  * Destructor.
83  */
84  virtual ~WItemSelector();
85 
86  /**
87  * Creates a new valid instance with the specified items selected. This is especially useful to simply create a new selection if only the old
88  * selection is known.
89  *
90  * \note Please be aware that, in the moment this method returns, another thread can make all selectors invalid again causing the returned
91  * one to be invalid too. To avoid this, use the newSelector method only if the old has locked the selection using \ref lock and \ref unlock.
92  *
93  * \param selected the selected items (their index in WItemSelection).
94  *
95  * \return the new selector instance
96  */
97  WItemSelector newSelector( IndexList selected ) const;
98 
99  /**
100  * Creates a new valid instance with the specified items selected. This can be useful to add a certain index. The new selector has the
101  * selection from this AND the specified one. If you want to create a selector containing only one selected item, use the method that uses
102  * the IndexList.
103  *
104  * \note Please be aware that, in the moment this method returns, another thread can make all selectors invalid again causing the returned
105  * one to be invalid too. To avoid this, use the newSelector method only if the old has locked the selection using \ref lock and \ref unlock.
106  *
107  * \param selected the selected item (the index in WItemSelection).
108  *
109  * \return the new selector instance
110  */
111  WItemSelector newSelector( size_t selected ) const;
112 
113  /**
114  * Creates a new valid instance with the specified items selected. This is especially useful to simply create a new selection if only the
115  * string representing it is known. This somehow correlates to the << operator.
116  *
117  * \note Please be aware that, in the moment this method returns, another thread can make all selectors invalid again causing the returned
118  * one to be invalid too. To avoid this, use the newSelector method only if the old has locked the selection using \ref lock and \ref unlock.
119  *
120  * \param asString the selected items
121  *
122  * \return the new selector instance
123  */
124  WItemSelector newSelector( const std::string asString ) const;
125 
126  /**
127  * Creates a new selector, but basing on this instance as old one. The new selector tries to keep the old selection but makes the internal
128  * selection list valid with the current underlying selection.
129  *
130  * \note Please be aware that, in the moment this method returns, another thread can make all selectors invalid again causing the returned
131  * one to be invalid too. To avoid this, use the newSelector method only if the old has locked the selection using \ref lock and \ref unlock.
132  *
133  * \return the new (valid) selector.
134  */
135  WItemSelector newSelector() const;
136 
137  /**
138  * Compares two selector. They are assumed to be equal if the selected items are equal and if the underlying WItemSelection is the same.
139  *
140  * \param other the selector
141  *
142  * \return true if equal
143  */
144  bool operator==( const WItemSelector& other ) const;
145 
146  /**
147  * Write a selection in string representation to the given output stream.
148  *
149  * \param out the output stream where to put the information
150  *
151  * \return the output stream extended by the information of this selector
152  */
153  std::ostream& operator<<( std::ostream& out ) const;
154 
155  /**
156  * Gives the count of elements in the set of selectable items. This is \ref size + number of unselected items.
157  *
158  * \return the number of all items in the item set.
159  */
160  virtual size_t sizeAll() const;
161 
162  /**
163  * The number of selected items.
164  *
165  * \return the number of selected items.
166  */
167  virtual size_t size() const;
168 
169  /**
170  * True if the selection is empty.
171  *
172  * \return true if nothing is selected.
173  */
174  virtual bool empty() const;
175 
176  /**
177  * Gets the item with the given index from the WItemSelection. This index does not equal the index of the same item for \ref at. This method
178  * is useful to go through the list of ALL items (not only the selected).
179  *
180  * \param index the index
181  *
182  * \return the item
183  */
184  virtual const boost::shared_ptr< WItemSelectionItem > atAll( size_t index ) const;
185 
186  /**
187  * Gets the selected item with the given index. This is not the same index as the element has in the corresponding WItemSelection!
188  * This method is especially useful to iterate the through the selected items.
189  *
190  * \param index the index
191  *
192  * \return the item
193  */
194  virtual const boost::shared_ptr< WItemSelectionItem > at( size_t index ) const;
195 
196  /**
197  * Helps to get the index of an selected item in the WItemSelection. This is somehow similar to \ref at, but does not return the item but the
198  * index to it.
199  *
200  * \param index the index in the selection (not the item index in WItemSelection)
201  *
202  * \return the index in WItemSelection.
203  */
204  virtual size_t getItemIndexOfSelected( size_t index ) const;
205 
206  /**
207  * Checks whether the selection is valid anymore. If a selector is not valid anymore, you should ask the one providing the selectors (most
208  * probably a WPropSelection) for a new one.
209  *
210  * \return true if valid.
211  */
212  virtual bool isValid() const;
213 
214  /**
215  * Read locks the underlying selection. This ensure, that the selection stays fixed as long as this selector is locked. This also ensures
216  * that no invalidation can be issued as long as this selector has the lock. BUT it is possible that an invalidation occurs while this
217  * selector waits. So please always check for validity of the selector ater locking.
218  */
219  void lock();
220 
221  /**
222  * Unlocks the selection again. Always call this after a lock.
223  */
224  void unlock();
225 
226  /**
227  * Allow cast from selector to unsigned int.
228  *
229  * \return the index of the first selected item in the selection.
230  */
231  operator unsigned int() const;
232 
233  /**
234  * Casts the selector to a list of indices currently selected. It contains the list of index in the corresponding WItemSelection. This is
235  * especially useful if the whole index list is needed without nasty iterations.
236  *
237  * \return the list of index.
238  */
239  IndexList getIndexList() const;
240 
241 protected:
242  /**
243  * Constructor creates an selector for the specified selection of items. Noting is selected after construction.
244  *
245  * \param selection the selection handled by this instance
246  * \param selected the set of selected items
247  */
248  WItemSelector( boost::shared_ptr< WItemSelection > selection, IndexList selected );
249 
250  /**
251  * The selection handled by this selector.
252  */
253  boost::shared_ptr< WItemSelection > m_selection;
254 
255  /**
256  * The list of items currently selected.
257  */
258  IndexList m_selected;
259 
260  /**
261  * Stores the connection made using WItemSelection::subscribeInvalidateSignal.
262  */
263  boost::signals2::connection m_invalidateSignalConnection;
264 
265 private:
266  /**
267  * Creates a new selector instance using the specified index list. Handles all needed signal subscription stuff.
268  *
269  * \param selected the index list of selected items
270  *
271  * \return new selector
272  */
273  WItemSelector createSelector( const IndexList& selected ) const;
274 
275  /**
276  * Handles the case of invalidation.
277  */
278  void invalidate();
279 
280  /**
281  * If true the selector is valid.
282  */
283  bool m_valid;
284 
285  /**
286  * This locks prevents the selection to be modified during selector iteration.
287  */
289 };
290 
291 /**
292  * Write a selection in string representation to the given output stream.
293  *
294  * \param out the output stream where to put the information
295  * \param other the instance to write out
296  *
297  * \return the output stream extended by the information of this selector
298  */
299 std::ostream& operator<<( std::ostream& out, const WItemSelector& other );
300 
301 #endif // WITEMSELECTOR_H
302 
IndexList getIndexList() const
Casts the selector to a list of indices currently selected.
WItemSelector newSelector() const
Creates a new selector, but basing on this instance as old one.
virtual size_t size() const
The number of selected items.
virtual size_t getItemIndexOfSelected(size_t index) const
Helps to get the index of an selected item in the WItemSelection.
std::vector< size_t > IndexList
The type used for storing index lists.
Definition: WItemSelector.h:63
bool m_valid
If true the selector is valid.
void invalidate()
Handles the case of invalidation.
IndexList m_selected
The list of items currently selected.
virtual bool empty() const
True if the selection is empty.
virtual const boost::shared_ptr< WItemSelectionItem > at(size_t index) const
Gets the selected item with the given index.
std::ostream & operator<<(std::ostream &out) const
Write a selection in string representation to the given output stream.
virtual size_t sizeAll() const
Gives the count of elements in the set of selectable items.
WItemSelector createSelector(const IndexList &selected) const
Creates a new selector instance using the specified index list.
A class containing a list of named items.
WItemSelection::ReadTicket m_lock
This locks prevents the selection to be modified during selector iteration.
This class represents a subset of a WItemSelection.
Definition: WItemSelector.h:56
boost::shared_ptr< WItemSelection > m_selection
The selection handled by this selector.
virtual const boost::shared_ptr< WItemSelectionItem > atAll(size_t index) const
Gets the item with the given index from the WItemSelection.
WItemSelector(const WItemSelector &other)
Copy constructor.
virtual bool isValid() const
Checks whether the selection is valid anymore.
void unlock()
Unlocks the selection again.
bool operator==(const WItemSelector &other) const
Compares two selector.
virtual ~WItemSelector()
Destructor.
void lock()
Read locks the underlying selection.
boost::signals2::connection m_invalidateSignalConnection
Stores the connection made using WItemSelection::subscribeInvalidateSignal.
boost::shared_ptr< WSharedObjectTicketRead< std::vector< boost::shared_ptr< WItemSelectionItem > > > > ReadTicket
Type for read tickets.
Definition: WSharedObject.h:64
WItemSelector & operator=(const WItemSelector &other)
Copy assignment.