1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 """A specialized set of identified Items."""
17
18
20 """A specialized set of identified Items. Basically the IContainer is a set
21 of L{Item}s, but it imposes certain constraints on its contents. These
22 constraints state the following:
23
24 - All Items in the IContainer must have the same number of Properties.
25 - All Items in the IContainer must have the same Property ID's (see
26 L{Item.getItemPropertyIds}).
27 - All Properties in the Items corresponding to the same Property ID must
28 have the same data type.
29 - All Items within a container are uniquely identified by their non-null
30 IDs.
31
32 The IContainer can be visualized as a representation of a relational
33 database table. Each Item in the IContainer represents a row in the table,
34 and all cells in a column (identified by a Property ID) have the same data
35 type. Note that as with the cells in a database table, no Property in a
36 IContainer may be empty, though they may contain C{None} values.
37
38 Note that though uniquely identified, the Items in a IContainer are not
39 necessarily L{IOrdered} or L{IIndexed indexed}.
40
41 Containers can derive Item ID's from the item properties or use other,
42 container specific or user specified identifiers.
43
44 If a container is L{filtered<IFilterable>} or L{sorted<ISortable>},
45 most of the the methods of the container interface and its subinterfaces
46 (container size, L{containsId}, iteration and indices etc.)
47 relate to the filtered and sorted view, not to the full container contents.
48 See individual method doc-strings for exceptions to this (adding and
49 removing items).
50
51 The IContainer interface is split to several subinterfaces so that a class
52 can implement only the ones it needs.
53
54 @author: Vaadin Ltd.
55 @version: 1.1.2
56 """
57
59 """Gets the L{Item} with the given Item ID from the IContainer. If the
60 IContainer does not contain the requested Item, C{None} is returned.
61
62 Containers should not return Items that are filtered out.
63
64 @param itemId:
65 ID of the L{Item} to retrieve
66 @return: the L{Item} with the given ID or C{None} if the
67 Item is not found in the IContainer
68 """
69 raise NotImplementedError
70
71
73 """Gets the ID's of all Properties stored in the IContainer. The ID's
74 cannot be modified through the returned collection.
75
76 @return: unmodifiable collection of Property IDs
77 """
78 raise NotImplementedError
79
80
82 """Gets the ID's of all visible (after filtering and sorting) Items
83 stored in the IContainer. The ID's cannot be modified through the
84 returned collection.
85
86 If the container is L{IOrdered}, the collection returned by this
87 method should follow that order. If the container is L{ISortable},
88 the items should be in the sorted order.
89
90 Calling this method for large lazy containers can be an expensive
91 operation and should be avoided when practical.
92
93 @return: unmodifiable collection of Item IDs
94 """
95 raise NotImplementedError
96
97
99 """Gets the Property identified by the given itemId and propertyId from
100 the IContainer. If the IContainer does not contain the item or it is
101 filtered out, or the IContainer does not have the Property, C{None} is
102 returned.
103
104 @param itemId:
105 ID of the visible Item which contains the Property
106 @param propertyId:
107 ID of the Property to retrieve
108 @return: Property with the given ID or C{None}
109 """
110 raise NotImplementedError
111
112
114 """Gets the data type of all Properties identified by the given
115 Property ID.
116
117 @param propertyId:
118 ID identifying the Properties
119 @return: data type of the Properties
120 """
121 raise NotImplementedError
122
123
125 """Gets the number of visible Items in the IContainer.
126
127 Filtering can hide items so that they will not be visible through
128 the container API.
129
130 @return: number of Items in the IContainer
131 """
132 raise NotImplementedError
133
134
136 """Tests if the IContainer contains the specified Item.
137
138 Filtering can hide items so that they will not be visible through the
139 container API, and this method should respect visibility of items (i.e.
140 only indicate visible items as being in the container) if feasible for
141 the container.
142
143 @param itemId:
144 ID the of Item to be tested
145 @return: boolean indicating if the IContainer holds the specified Item
146 """
147 raise NotImplementedError
148
149
151 """Creates a new Item with the given ID in the IContainer. Creates a
152 new Item into the IContainer, and assign it an automatic ID if itemId
153 is C{None}.
154
155 The new Item is returned, and it is ready to have its Properties
156 modified. Returns C{None} if the operation fails or the
157 IContainer already contains a Item with the given ID.
158
159 @param itemId:
160 ID of the Item to be created
161 @return: Created new Item, or C{None} in case of a failure
162 @raise NotImplementedError:
163 if adding an item with an explicit item ID is not supported
164 by the container
165 """
166 raise NotImplementedError
167
168
170 """Removes the Item identified by C{ItemId} from the IContainer.
171
172 Containers that support filtering should also allow removing an item
173 that is currently filtered out.
174
175 This functionality is optional.
176
177 @param itemId:
178 ID of the Item to remove
179 @return: C{True} if the operation succeeded, C{False} if not
180 @raise NotImplementedError:
181 if the container does not support removing individual items
182 """
183 raise NotImplementedError
184
185
187 """Adds a new Property to all Items in the IContainer. The Property
188 ID, data type and default value of the new Property are given as
189 parameters.
190
191 This functionality is optional.
192
193 @param propertyId:
194 ID of the Property
195 @param typ:
196 Data type of the new Property
197 @param defaultValue:
198 The value all created Properties are initialized to
199 @return: C{True} if the operation succeeded, C{False} if not
200 @raise NotImplementedError:
201 if the container does not support explicitly adding
202 container properties
203 """
204 raise NotImplementedError
205
206
208 """Removes a Property specified by the given Property ID from the
209 IContainer. Note that the Property will be removed from all Items
210 in the IContainer.
211
212 This functionality is optional.
213
214 @param propertyId:
215 ID of the Property to remove
216 @return: C{True} if the operation succeeded, C{False} if not
217 @raise NotImplementedError:
218 if the container does not support removing container
219 properties
220 """
221 raise NotImplementedError
222
223
225 """Removes all Items from the IContainer.
226
227 Note that Property ID and type information is preserved. This
228 functionality is optional.
229
230 @return: C{True} if the operation succeeded, C{False} if not
231 @raise NotImplementedError:
232 if the container does not support removing all items
233 """
234 raise NotImplementedError
235
236
238 """Interface for IContainer classes whose L{Item}s can be traversed in
239 order.
240
241 If the container is filtered or sorted, the traversal applies to the
242 filtered and sorted view.
243
244 The C{addItemAfter()} methods should apply filters to the added
245 item after inserting it, possibly hiding it immediately. If the container
246 is being sorted, they may add items at the correct sorted position
247 instead of the given position. See also L{IFilterable} and
248 L{ISortable} for more information.
249 """
250
252 """Gets the ID of the Item following the Item that corresponds to
253 C{itemId}. If the given Item is the last or not found in the
254 IContainer, C{None} is returned.
255
256 @param itemId:
257 ID of a visible Item in the IContainer
258 @return: ID of the next visible Item or C{None}
259 """
260 raise NotImplementedError
261
262
264 """Gets the ID of the Item preceding the Item that corresponds to
265 C{itemId}. If the given Item is the first or not found in the
266 IContainer, C{None} is returned.
267
268 @param itemId:
269 ID of a visible Item in the IContainer
270 @return: ID of the previous visible Item or C{None}
271 """
272 raise NotImplementedError
273
274
276 """Gets the ID of the first Item in the IContainer.
277
278 @return: ID of the first visible Item in the IContainer
279 """
280 raise NotImplementedError
281
282
284 """Gets the ID of the last Item in the IContainer..
285
286 @return: ID of the last visible Item in the IContainer
287 """
288 raise NotImplementedError
289
290
292 """Tests if the Item corresponding to the given Item ID is the first
293 Item in the IContainer.
294
295 @param itemId:
296 ID of an Item in the IContainer
297 @return: C{True} if the Item is first visible item in the
298 IContainer, C{False} if not
299 """
300 raise NotImplementedError
301
302
304 """Tests if the Item corresponding to the given Item ID is the last
305 Item in the IContainer.
306
307 @return: C{True} if the Item is last visible item in the
308 IContainer, C{False} if not
309 """
310 raise NotImplementedError
311
312
314 """Adds a new item after the given item.
315
316 Adding an item after null item adds the item as first item of the
317 ordered container.
318
319 @see: L{IOrdered} for adding items in filtered or sorted containers
320
321 @param previousItemId:
322 Id of the visible item in ordered container after which to
323 insert the new item.
324 @param newItemId:
325 Id of the new item to be added.
326 @return: new item or null if the operation fails.
327 @raise NotImplementedError:
328 if the operation is not supported by the container
329 """
330 raise NotImplementedError
331
332
334 """Interface for IContainer classes whose L{Item}s can be sorted.
335
336 When an L{IOrdered} or L{IIndexed} container is sorted, all relevant
337 operations of these interfaces should only use the filtered and
338 sorted contents and the filtered indices to the container. Indices or
339 item identifiers in the public API refer to the visible view unless
340 otherwise stated. However, the C{addItem*()} methods may add
341 items that will be filtered out after addition or moved to another
342 position based on sorting.
343
344 How sorting is performed when a L{IHierarchical} container implements
345 L{ISortable} is implementation specific and should be documented in
346 the implementing class. However, the recommended approach is sorting the
347 roots and the sets of children of each item separately.
348
349 Depending on the container type, sorting a container may permanently
350 change the internal order of items in the container.
351 """
352
353 - def sort(self, propertyId, ascending):
354 """Sort method.
355
356 Sorts the container items.
357
358 Sorting a container can irreversibly change the order of its items or
359 only change the order temporarily, depending on the container.
360
361 @param propertyId:
362 Array of container property IDs, whose values are used to
363 sort the items in container as primary, secondary, ...
364 sorting criterion. All of the item IDs must be in the
365 collection returned by
366 L{getSortableContainerPropertyIds}
367 @param ascending:
368 Array of sorting order flags corresponding to each
369 property ID used in sorting. If this array is shorter than
370 propertyId array, ascending order is assumed for items
371 where the order is not specified. Use C{True} to
372 sort in ascending order, C{False} to use descending order.
373 """
374 raise NotImplementedError
375
376
378 """Gets the container property IDs which can be used to sort the items.
379
380 @return: the IDs of the properties that can be used for sorting the
381 container
382 """
383 raise NotImplementedError
384
385
387 """Interface for IContainer classes whose L{Item}s can be accessed by
388 their position in the container.
389
390 If the container is filtered or sorted, all indices refer to the filtered
391 and sorted view. However, the C{addItemAt()} methods may add
392 items that will be filtered out after addition or moved to another
393 position based on sorting.
394 """
395
397 """Gets the index of the Item corresponding to the itemId. The following
398 is C{True} for the returned index: 0 <= index < size(), or
399 index = -1 if there is no visible item with that id in the container.
400
401 @param itemId:
402 ID of an Item in the IContainer
403 @return: index of the Item, or -1 if (the filtered and sorted view of)
404 the IContainer does not include the Item
405 """
406 raise NotImplementedError
407
408
410 """Gets the ID of an Item by an index number.
411
412 @param index:
413 Index of the requested id in (the filtered and sorted view
414 of) the IContainer
415 @return: ID of the Item in the given index
416 """
417 raise NotImplementedError
418
419
421 """Adds a new item at given index (in the filtered view).
422
423 The indices of the item currently in the given position and all the
424 following items are incremented.
425
426 This method should apply filters to the added item after inserting
427 it, possibly hiding it immediately. If the container is being sorted,
428 the item may be added at the correct sorted position instead of the
429 given position. See L{IIndexed}, L{IOrdered},
430 L{IFilterable} and L{ISortable} for more information.
431
432 @param index:
433 Index (in the filtered and sorted view) at which to add
434 the new item.
435 @param newItemId:
436 Id of the new item to be added.
437 @return: new L{Item} or null if the operation fails.
438 @raise NotImplementedError:
439 if the operation is not supported by the container
440 """
441 raise NotImplementedError
442
443
445 """Interface for C{IContainer} classes whose Items can be arranged
446 hierarchically. This means that the Items in the container belong in a
447 tree-like structure, with the following quirks:
448
449 - The Item structure may have more than one root elements
450 - The Items in the hierarchy can be declared explicitly to be able or
451 unable to have children.
452 """
453
455 """Gets the IDs of all Items that are children of the specified Item.
456 The returned collection is unmodifiable.
457
458 @param itemId:
459 ID of the Item whose children the caller is interested in
460 @return: An iterable containing the IDs of all other Items
461 that are children in the container hierarchy
462 """
463 raise NotImplementedError
464
465
467 """Gets the ID of the parent Item of the specified Item.
468
469 @param itemId:
470 ID of the Item whose parent the caller wishes to find out.
471 @return: the ID of the parent Item. Will be C{None} if the
472 specified Item is a root element.
473 """
474 raise NotImplementedError
475
476
478 """Gets the IDs of all Items in the container that don't have a parent.
479 Such items are called C{root} Items. The returned
480 collection is unmodifiable.
481
482 @return: An iterable containing IDs of all root elements
483 of the container
484 """
485 raise NotImplementedError
486
487
489 """Sets the parent of an Item. The new parent item must exist and be
490 able to have children. (C{L{areChildrenAllowed} == True}). It is
491 also possible to detach a node from the hierarchy (and thus make it
492 root) by setting the parent C{None}.
493
494 This operation is optional.
495
496 @param itemId:
497 ID of the item to be set as the child of the Item
498 identified with C{newParentId}
499 @param newParentId:
500 ID of the Item that's to be the new parent of the Item
501 identified with C{itemId}
502 @return: C{True} if the operation succeeded, C{False} if not
503 """
504 raise NotImplementedError
505
506
508 """Tests if the Item with given ID can have children.
509
510 @param itemId:
511 ID of the Item in the container whose child capability is
512 to be tested
513 @return: C{True} if the specified Item exists in the
514 IContainer and it can have children, C{False} if
515 it's not found from the container or it can't have children.
516 """
517 raise NotImplementedError
518
519
521 """Sets the given Item's capability to have children. If the Item
522 identified with C{itemId} already has children and
523 L{areChildrenAllowed} is false this method fails and C{False} is
524 returned.
525
526 The children must be first explicitly removed with L{setParent} or
527 L{removeItem}.
528
529 This operation is optional. If it is not implemented, the method
530 always returns C{False}.
531
532 @param itemId:
533 ID of the Item in the container whose child capability is
534 to be set
535 @param areChildrenAllowed:
536 boolean value specifying if the Item can have children or
537 not
538 @return: C{True} if the operation succeeded, C{False} if not
539 """
540 raise NotImplementedError
541
542
544 """Tests if the Item specified with C{itemId} is a root Item.
545 The hierarchical container can have more than one root and must have
546 at least one unless it is empty. The L{getParent} method always returns
547 C{None} for root Items.
548
549 @param itemId:
550 ID of the Item whose root status is to be tested
551 @return: C{True} if the specified Item is a root, C{False} if not
552 """
553 raise NotImplementedError
554
555
557 """Tests if the Item specified with C{itemId} has child Items
558 or if it is a leaf. The L{getChildren} method always returns C{None}
559 for leaf Items.
560
561 Note that being a leaf does not imply whether or not an Item is
562 allowed to have children.
563
564 @param itemId:
565 ID of the Item to be tested
566 @return: C{True} if the specified Item has children, C{False} if not
567 (is a leaf)
568 """
569 raise NotImplementedError
570
571
573 """Removes the Item identified by C{ItemId} from the
574 IContainer.
575
576 Note that this does not remove any children the item might have.
577
578 @param itemId:
579 ID of the Item to remove
580 @return: C{True} if the operation succeeded, C{False} if not
581 """
582 raise NotImplementedError
583
584
586 """Interface that is implemented by containers which allow reducing their
587 visible contents based on a set of filters. This interface has been
588 renamed from L{IFilterable}, and implementing the new
589 L{IFilterable} instead of or in addition to L{ISimpleFilterable}
590 is recommended. This interface might be removed in future Muntjac
591 versions.
592
593 When a set of filters are set, only items that match all the filters are
594 included in the visible contents of the container. Still new items that
595 do not match filters can be added to the container. Multiple filters can
596 be added and the container remembers the state of the filters. When
597 multiple filters are added, all filters must match for an item to be
598 visible in the container.
599
600 When an L{IOrdered} or L{IIndexed} container is filtered, all
601 operations of these interfaces should only use the filtered contents and
602 the filtered indices to the container.
603
604 How filtering is performed when a L{IHierarchical} container
605 implements L{ISimpleFilterable} is implementation specific and should
606 be documented in the implementing class.
607
608 Adding items (if supported) to a filtered L{IOrdered} or
609 L{IIndexed} container should insert them immediately after the
610 indicated visible item. The unfiltered position of items added at index
611 0, at index L{IContainer.size} or at an undefined position is up to the
612 implementation.
613
614 The functionality of ISimpleFilterable can be implemented using the
615 L{IFilterable} API and L{SimpleStringFilter}.
616 """
617
620 """Add a filter for given property.
621
622 The API L{IFilterable.addContainerFilter} is recommended instead of
623 this method. A L{SimpleStringFilter} can be used with the new API to
624 implement the old string filtering functionality.
625
626 The filter accepts items for which C{__str__} of the value of the
627 given property contains or starts with given filterString. Other
628 items are not visible in the container when filtered.
629
630 If a container has multiple filters, only items accepted by all
631 filters are visible.
632
633 @param propertyId:
634 Property for which the filter is applied to.
635 @param filterString:
636 String that must match the value of the property
637 @param ignoreCase:
638 Determine if the casing can be ignored when comparing
639 strings.
640 @param onlyMatchPrefix:
641 Only match prefixes; no other matches are included.
642 """
643 raise NotImplementedError
644
645
647 """Remove all filters from all properties."""
648 raise NotImplementedError
649
650
652 """Remove all filters from the given property.
653
654 @param propertyId:
655 for which to remove filters
656 """
657 raise NotImplementedError
658
659
661 """IFilter interface for container filtering.
662
663 If a filter does not support in-memory filtering,
664 L{passesFilter} should throw L{NotImplementedError}.
665
666 Lazy containers must be able to map filters to their internal
667 representation.
668
669 An L{UnsupportedFilterException} can be thrown by the container if a
670 particular filter is not supported by the container.
671
672 An L{IFilter} should implement C{__eq__} and C{__hash__} correctly to
673 avoid duplicate filter registrations etc.
674
675 @see: L{IFilterable}
676 """
677
679 """Check if an item passes the filter (in-memory filtering).
680
681 @param itemId:
682 identifier of the item being filtered; may be null when
683 the item is being added to the container
684 @param item:
685 the item being filtered
686 @return: true if the item is accepted by this filter
687 @raise NotImplementedError:
688 if the filter cannot be used for in-memory filtering
689 """
690 raise NotImplementedError
691
692
694 """Check if a change in the value of a property can affect the
695 filtering result. May always return true, at the cost of performance.
696
697 If the filter cannot determine whether it may depend on the property
698 or not, should return true.
699
700 @return: true if the filtering result may/does change based on changes
701 to the property identified by propertyId
702 """
703 raise NotImplementedError
704
705
707 """Interface that is implemented by containers which allow reducing their
708 visible contents based on a set of filters.
709
710 When a set of filters are set, only items that match all the filters are
711 included in the visible contents of the container. Still new items that
712 do not match filters can be added to the container. Multiple filters can
713 be added and the container remembers the state of the filters. When
714 multiple filters are added, all filters must match for an item to be
715 visible in the container.
716
717 When an L{IOrdered} or L{IIndexed} container is filtered, all
718 operations of these interfaces should only use the filtered and sorted
719 contents and the filtered indices to the container. Indices or item
720 identifiers in the public API refer to the visible view unless otherwise
721 stated. However, the C{addItem*()} methods may add items that
722 will be filtered out after addition or moved to another position based on
723 sorting.
724
725 How filtering is performed when a L{IHierarchical} container
726 implements L{IFilterable} is implementation specific and should be
727 documented in the implementing class.
728
729 Adding items (if supported) to a filtered L{IOrdered} or
730 L{IIndexed} container should insert them immediately after the
731 indicated visible item. However, the unfiltered position of items added
732 at index 0, at index L{IContainer.size} or at an
733 undefined position is up to the implementation.
734 """
735
737 """Adds a filter for the container.
738
739 If a container has multiple filters, only items accepted by all
740 filters are visible.
741
742 @raise UnsupportedFilterException:
743 if the filter is not supported by the container
744 """
745 raise NotImplementedError
746
747
749 """Removes a filter from the container.
750
751 This requires that the C{__eq__} method considers the filters as
752 equivalent (same instance or properly implemented C{__eq__} method).
753 """
754 raise NotImplementedError
755
756
758 """Remove all active filters from the container."""
759 raise NotImplementedError
760
761
763 """Interface implemented by viewer classes capable of using a IContainer
764 as a data source.
765 """
766
768 """Sets the IContainer that serves as the data source of the viewer.
769
770 @param newDataSource:
771 The new data source Item
772 """
773 raise NotImplementedError
774
775
777 """Gets the IContainer serving as the data source of the viewer.
778
779 @return: data source IContainer
780 """
781 raise NotImplementedError
782
783
785 """Interface implemented by the editor classes supporting editing the
786 IContainer. Implementing this interface means that the IContainer serving
787 as the data source of the editor can be modified through it.
788
789 Note that not implementing the C{IEditor} interface does not restrict the
790 class from editing the IContainer contents internally.
791 """
792 pass
793
794
796 """An C{Event} object specifying the IContainer whose Item set has
797 changed (items added, removed or reordered).
798
799 A simple property value change is not an item set change.
800 """
801
803 """Gets the Property where the event occurred.
804
805 @return: source of the event
806 """
807 raise NotImplementedError
808
809
811 """IContainer Item set change listener interface.
812
813 An item set change refers to addition, removal or reordering of items in
814 the container. A simple property value change is not an item set change.
815 """
816
818 """Lets the listener know a Containers visible (filtered and/or sorted,
819 if applicable) Item set has changed.
820
821 @param event:
822 change event text
823 """
824 raise NotImplementedError
825
826
828 """The interface for adding and removing C{IItemSetChangeEvent}
829 listeners. By implementing this interface a class explicitly announces
830 that it will generate a C{IItemSetChangeEvent} when its contents
831 are modified.
832
833 An item set change refers to addition, removal or reordering of items in
834 the container. A simple property value change is not an item set change.
835 """
836
838 """Adds an Item set change listener for the object.
839
840 @param listener:
841 listener to be added
842 """
843 raise NotImplementedError
844
845
846 - def addCallback(self, callback, eventType=None, *args):
847 raise NotImplementedError
848
849
851 """Removes the Item set change listener from the object.
852
853 @param listener:
854 listener to be removed
855 """
856 raise NotImplementedError
857
858
860 raise NotImplementedError
861
862
864 """An C{Event} object specifying the IContainer whose Property set
865 has changed.
866
867 A property set change means the addition, removal or other structural
868 changes to the properties of a container. Changes concerning the set of
869 items in the container and their property values are not property set
870 changes.
871 """
872
874 """Retrieves the IContainer whose contents have been modified.
875
876 @return: Source IContainer of the event.
877 """
878 raise NotImplementedError
879
880
882 """The listener interface for receiving C{IPropertySetChangeEvent}
883 objects.
884
885 A property set change means the addition, removal or other structural
886 change of the properties (supported property IDs) of a container. Changes
887 concerning the set of items in the container and their property values
888 are not property set changes.
889 """
890
892 """Notifies this listener that the set of property IDs supported by
893 the IContainer has changed.
894
895 @param event:
896 Change event.
897 """
898 raise NotImplementedError
899
900
902 """The interface for adding and removing C{IPropertySetChangeEvent}
903 listeners. By implementing this interface a class explicitly announces
904 that it will generate a C{IPropertySetChangeEvent} when the set
905 of property IDs supported by the container is modified.
906
907 A property set change means the addition, removal or other structural
908 changes to the properties of a container. Changes concerning the set of
909 items in the container and their property values are not property set
910 changes.
911 """
912
914 """Registers a new Property set change listener for this IContainer.
915
916 @param listener:
917 The new Listener to be registered
918 """
919 raise NotImplementedError
920
921
922 - def addCallback(self, callback, eventType=None, *args):
923 raise NotImplementedError
924
925
927 """Removes a previously registered Property set change listener.
928
929 @param listener:
930 Listener to be removed
931 """
932 raise NotImplementedError
933
934
936 raise NotImplementedError
937