root/Trunk/AIUtilities.framework/Versions/A/Headers/AIMutableOwnerArray.h @ 2

Revision 2, 6.8 KB (checked in by jon, 16 years ago)

Initial commit of skeletal project.

Line 
1/*-------------------------------------------------------------------------------------------------------*\
2| Adium, Copyright (C) 2001-2005, Adam Iser  (adamiser@mac.com | http://www.adiumx.com)                   |
3\---------------------------------------------------------------------------------------------------------/
4 | This program is free software; you can redistribute it and/or modify it under the terms of the GNU
5 | General Public License as published by the Free Software Foundation; either version 2 of the License,
6 | or (at your option) any later version.
7 |
8 | This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
9 | the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
10 | Public License for more details.
11 |
12 | You should have received a copy of the GNU General Public License along with this program; if not,
13 | write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
14 \------------------------------------------------------------------------------------------------------ */
15
16#define Highest_Priority        0.0
17#define High_Priority           0.25
18#define Medium_Priority         0.5
19#define Low_Priority            0.75
20#define Lowest_Priority         1.0
21
22@class AIMutableOwnerArray;
23
24//Delegate protocol for documentation purposes; it is not necessary to declare conformance to this protocol.
25@protocol AIMutableOwnerArrayDelegate
26- (void)mutableOwnerArray:(AIMutableOwnerArray *)inArray didSetObject:(id)anObject withOwner:(id)inOwner priorityLevel:(float)priority;
27@end
28
29/*!
30 * @class AIMutableOwnerArray
31 * @brief An container object that keeps track of who owns each of its objects.
32 *
33 * Every object in the \c AIMutableOwnerArray has an associated owner.  The best use for this class is when
34 * multiple pieces of code may be trying to control the same thing.  For instance, if there are several events that can
35 * cause something to change colors, by using an owner-array it is possible to prevent conflicts and determine an
36 * average color based on all the values.  It's also easy for a specific owner to remove the value they contributed,
37 * or replace it with another.
38 *
39 * An owner can only own one object in a given \c AIMutableOwnerArray.
40 *
41 * Floating point priority levels can be used to dictate the ordering of objects in the array.
42 * Lower numbers have higher priority.
43 */
44@interface AIMutableOwnerArray : NSObject {
45    NSMutableArray      *contentArray;
46    NSMutableArray      *ownerArray;
47    NSMutableArray      *priorityArray;
48       
49        BOOL                    valueIsSortedToFront;
50       
51        id                              delegate;
52        BOOL                    delegateRespondsToDidSetObjectWithOwnerPriorityLevel;
53}
54
55#pragma mark Value Storage
56
57/*!
58 * @brief Store an object with an owner at default (medium) priority
59 *
60 * Calls <code>setObject:withOwner:priorityLevel:</code> with a priorityLevel of Medium_Priority.
61 * Pass nil to remove the object
62 */
63- (void)setObject:(id)anObject withOwner:(id)inOwner;
64/*!
65 * @brief Store an object with an owner and a priority
66 *
67 *      <p>Stores an object in the array with a specified owner at a given priority</p>
68 *      @param anObject An object to store
69 *      @param inOwner The owner of the object
70 *  @param priority priority is a float from 0.0 to 1.0, with 0.0 the highest-priority (earliest in the array). Possible preset values are:
71 *                      - Highest_Priority
72 *                      - High_Priority
73 *                      - Medium_Priority
74 *                      - Low_Priority
75 *                      - Lowest_Priority
76 */
77- (void)setObject:(id)anObject withOwner:(id)inOwner priorityLevel:(float)priority;
78
79#pragma mark Value Retrieval
80
81/*!
82 * @brief Highest priority object
83 *
84 * @result The object with the highest priority, performing no other comparison
85 */
86- (id)objectValue;
87/*!
88 * @brief Greatest NSNumber value
89 *
90 * Assumes the \c AIMutableOwnerArray contains \c NSNumber instances
91 * @result Returns the greatest (highest value) contained \c NSNumber value.
92 */
93- (NSNumber *)numberValue;
94/*!
95 * @brief Greatest integer value
96 *
97 * Assuming the \c AIMutableOwnerArray contains \c NSNumber instances, returns the \c intValue of the greatest (highest-valued) one.
98 * @return  Returns the greatest contained integer value.
99 */
100- (int)intValue;
101/*!
102 * @brief Greatest double value
103 *
104 * Assuming the \c AIMutableOwnerArray contains \c NSNumber instances, returns the \c doubleValue of the greatest (highest-valued) one.
105 * @return  Returns the greatest contained double value.
106 */
107- (double)doubleValue;
108/*!
109 * @brief Earliest date
110 *
111 * Assuming the \c AIMutableOwnerArray contains \c NSDate instances, returns the earliest one.
112 * @return  Returns the earliest contained date.
113 */
114- (NSDate *)date;
115/*!
116 * @brief Retrieve object by owner
117 *
118 * Retrieve the object within the \c AIMutableOwnerArray owned by the specified owner.
119 * @param inOwner The owner
120 * @return  Returns the object owned by \a inOwner.
121 */
122- (id)objectWithOwner:(id)inOwner;
123/*!
124 * @brief Retrieve priority by owner
125 *
126 * Retrieve the priority of the object within the \c AIMutableOwnerArray owned by the specified owner.
127 * @param inOwner An owner
128 * @return  Returns the priority of the object owned by \a inOwner, or 0 if no object is owned by the owner.
129 */
130- (float)priorityOfObjectWithOwner:(id)inOwner;
131/*!
132 * @brief Retrieve owner by object
133 *
134 * Retrieve the owner within the \c AIMutableOwnerArray which owns the specified object.  If multiple owners own a single object, returns the one with the highest priority.
135 * @param anObject An object
136 * @return  Returns the owner which owns \a inObject.
137 */
138- (id)ownerWithObject:(id)anObject;
139/*!
140 * @brief Retrieve priority by object
141 *
142 * Retrieve the priority of an object within the \c AIMutableOwnerArray.
143 * @param inObject An object
144 * @return Returns the priority of the object, or 0 if the object is not in the array.
145 */
146- (float)priorityOfObject:(id)inObject;
147/*!
148 * @brief Retrieve enumerator for objects
149 *
150 * Retrieve an \c NSEnumerator for all objects in the \c AIMutableOwnerArray. Order is not guaranteed.
151 * @return  Returns \c NSEnumerator for all objects.
152 */
153- (NSEnumerator *)objectEnumerator;
154/*!
155 * @brief Retrieve array of values
156 *
157 * Retrieve an \c NSArray for all objects in the \c AIMutableOwnerArray. Order is not guaranteed.
158 * @return  Returns \c NSArray for all objects.
159 */
160- (NSArray *)allValues;
161/*!
162 * @brief Retrieve number of objects
163 *
164 * Retrieve the number of objects in the \c AIMutableOwnerArray.
165 * @return  Returns an unsigned of the number of objects.
166 */
167- (unsigned)count;
168
169//Delegation
170/*!
171 * @brief Set the delegate
172 *
173 * The delegate may implement:<br>
174 * <code>- (void)mutableOwnerArray:(AIMutableOwnerArray *)inArray didSetObject:(id)anObject withOwner:(id)inOwner priorityLevel:(float)priority</code><br>
175 * to be notified with the \c AIMutableOwnerArray is modified.
176 * @param inDelegate The delegate
177 */
178- (void)setDelegate:(id)inDelegate;
179/*!
180 * @brief Retrieve the delegate.
181 *
182 * Retrieve the delegate.
183 * @return Returns the delegate.
184 */
185- (id)delegate;
186
187@end
Note: See TracBrowser for help on using the browser.