forked from facebookarchive/AsyncDisplayKit
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathASDisplayNode+Subclasses.h
More file actions
380 lines (306 loc) · 13.1 KB
/
ASDisplayNode+Subclasses.h
File metadata and controls
380 lines (306 loc) · 13.1 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
/* Copyright (c) 2014-present, Facebook, Inc.
* All rights reserved.
*
* This source code is licensed under the BSD-style license found in the
* LICENSE file in the root directory of this source tree. An additional grant
* of patent rights can be found in the PATENTS file in the same directory.
*/
#import <pthread.h>
#import <AsyncDisplayKit/_ASDisplayLayer.h>
#import <AsyncDisplayKit/ASAssert.h>
#import <AsyncDisplayKit/ASDisplayNode.h>
#import <AsyncDisplayKit/ASThread.h>
/**
* The subclass header _ASDisplayNode+Subclasses_ defines the following methods that either must or can be overriden by
* subclasses of ASDisplayNode.
*
* These methods should never be called directly by other classes.
*
* ## Drawing
*
* Implement one of +displayWithParameters:isCancelled: or +drawRect:withParameters:isCancelled: to provide
* drawing for your node.
*
* Use -drawParametersForAsyncLayer: to copy any properties that are involved in drawing into an immutable object for
* use on the display queue. The display and drawRect implementations *MUST* be thread-safe, as they can be called on
* the displayQueue (asynchronously) or the main thread (synchronously/displayImmediately).
*
* Class methods that require passing in copies of the values are used to minimize the need for locking around instance
* variable access, and the possibility of the asynchronous display pass grabbing an inconsistent state across multiple
* variables.
*/
@interface ASDisplayNode (Subclassing)
/** @name View Configuration */
/**
* @return The view class to use when creating a new display node instance. Defaults to _ASDisplayView.
*/
+ (Class)viewClass;
/** @name Properties */
/**
* @abstract The scale factor to apply to the rendering.
*
* @discussion Use setNeedsDisplayAtScale: to set a value and then after display, the display node will set the layer's
* contentsScale. This is to prevent jumps when re-rasterizing at a different contentsScale.
* Read this property if you need to know the future contentsScale of your layer, eg in drawParameters.
*
* @see setNeedsDisplayAtScale:
*/
@property (nonatomic, assign, readonly) CGFloat contentsScaleForDisplay;
/**
* @abstract Whether the view or layer of this display node is currently in a window
*/
@property (nonatomic, readonly, assign, getter=isInHierarchy) BOOL inHierarchy;
/** @name View Lifecycle */
/**
* @abstract Called on the main thread immediately after self.view is created.
*
* @discussion This is the best time to add gesture recognizers to the view.
*/
- (void)didLoad ASDISPLAYNODE_REQUIRES_SUPER;
/** @name Layout */
/**
* @abstract Called on the main thread by the view's -layoutSubviews.
*
* @discussion Subclasses override this method to layout all subnodes or subviews.
*/
- (void)layout;
/**
* @abstract Called on the main thread by the view's -layoutSubviews, after -layout.
*
* @discussion Gives a chance for subclasses to perform actions after the subclass and superclass have finished laying
* out.
*/
- (void)layoutDidFinish;
/** @name Sizing */
/**
* @abstract Return the calculated size.
*
* @param constrainedSize The maximum size the receiver should fit in.
*
* @discussion Subclasses that override should expect this method to be called on a non-main thread. The returned size
* is cached by ASDisplayNode for quick access during -layout, via -calculatedSize. Other expensive work that needs to
* be done before display can be performed here, and using ivars to cache any valuable intermediate results is
* encouraged.
*
* @note This method should not be called directly outside of ASDisplayNode; use -measure: or -calculatedSize instead.
*/
- (CGSize)calculateSizeThatFits:(CGSize)constrainedSize;
/**
* @abstract Invalidate previously measured and cached size.
*
* @discussion Subclasses should call this method to invalidate the previously measured and cached size for the display
* node, when the contents of the node change in such a way as to require measuring it again.
*/
- (void)invalidateCalculatedSize;
/** @name Drawing */
/**
* @summary Delegate method to draw layer contents into a CGBitmapContext. The current UIGraphics context will be set
* to an appropriate context.
*
* @param bounds Region to draw in.
* @param parameters An object describing all of the properties you need to draw. Return this from
* -drawParametersForAsyncLayer:
* @param isCancelledBlock Execute this block to check whether the current drawing operation has been cancelled to avoid
* unnecessary work. A return value of YES means cancel drawing and return.
* @param isRasterizing YES if the layer is being rasterized into another layer, in which case drawRect: probably wants
* to avoid doing things like filling its bounds with a zero-alpha color to clear the backing store.
*
* @note Called on the display queue and/or main queue (MUST BE THREAD SAFE)
*/
+ (void)drawRect:(CGRect)bounds
withParameters:(id<NSObject>)parameters
isCancelled:(asdisplaynode_iscancelled_block_t)isCancelledBlock
isRasterizing:(BOOL)isRasterizing;
/**
* @summary Delegate override to provide new layer contents as a UIImage.
*
* @param parameters An object describing all of the properties you need to draw. Return this from
* -drawParametersForAsyncLayer:
* @param isCancelledBlock Execute this block to check whether the current drawing operation has been cancelled to avoid
* unnecessary work. A return value of YES means cancel drawing and return.
*
* @return A UIImage with contents that are ready to display on the main thread. Make sure that the image is already
* decoded before returning it here.
*
* @note Called on the display queue and/or main queue (MUST BE THREAD SAFE)
*/
+ (UIImage *)displayWithParameters:(id<NSObject>)parameters
isCancelled:(asdisplaynode_iscancelled_block_t)isCancelledBlock;
/**
* @abstract Delegate override for drawParameters
*
* @param layer The layer that will be drawn into.
*
* @note Called on the main thread only
*/
- (NSObject *)drawParametersForAsyncLayer:(_ASDisplayLayer *)layer;
/**
* @abstract Indicates that the receiver is about to display.
*
* @discussion Subclasses may override this method to be notified when display (asynchronous or synchronous) is
* about to begin.
*/
- (void)displayWillStart ASDISPLAYNODE_REQUIRES_SUPER;
/**
* @abstract Indicates that the receiver has finished displaying.
*
* @discussion Subclasses may override this method to be notified when display (asynchronous or synchronous) has
* completed.
*/
- (void)displayDidFinish ASDISPLAYNODE_REQUIRES_SUPER;
/**
* @abstract Indicates that the node should fetch any external data, such as images.
*
* @discussion Subclasses may override this method to be notified when they should begin to fetch data. Fetching
* should be done asynchronously. The node is also responsible for managing the memory of any data.
* The data may be remote and accessed via the network, but could also be a local database query.
*/
- (void)fetchData ASDISPLAYNODE_REQUIRES_SUPER;
/**
* @abstract Indicates that the receiver is about to display its subnodes. This method is not called if there are no
* subnodes present.
*
* @discussion Subclasses may override this method to be notified when subnode display (asynchronous or synchronous) is
* about to begin.
*/
- (void)subnodeDisplayWillStart:(ASDisplayNode *)subnode ASDISPLAYNODE_REQUIRES_SUPER;
/**
* @abstract Indicates that the receiver is finished displaying its subnodes. This method is not called if there are
* no subnodes present.
*
* @discussion Subclasses may override this method to be notified when subnode display (asynchronous or synchronous) has
* completed.
*/
- (void)subnodeDisplayDidFinish:(ASDisplayNode *)subnode ASDISPLAYNODE_REQUIRES_SUPER;
/**
* @abstract Marks the receiver's bounds as needing to be redrawn, with a scale value.
*
* @param contentsScale The scale at which the receiver should be drawn.
*
* @discussion Subclasses should override this if they don't want their contentsScale changed.
*
* @note This changes an internal property.
* -setNeedsDisplay is also available to trigger display without changing contentsScaleForDisplay.
* @see -setNeedsDisplay, contentsScaleForDisplay
*/
- (void)setNeedsDisplayAtScale:(CGFloat)contentsScale;
/**
* @abstract Recursively calls setNeedsDisplayAtScale: on subnodes.
*
* @param contentsScale The scale at which the receiver's subnode hierarchy should be drawn.
*
* @discussion Subclasses may override this if they require modifying the scale set on their child nodes.
*
* @note Only the node tree is walked, not the view or layer trees.
*
* @see setNeedsDisplayAtScale:
* @see contentsScaleForDisplay
*/
- (void)recursivelySetNeedsDisplayAtScale:(CGFloat)contentsScale;
/** @name Touch handling */
/**
* @abstract Tells the node when touches began in its view.
*
* @param touches A set of UITouch instances.
* @param event A UIEvent associated with the touch.
*/
- (void)touchesBegan:(NSSet *)touches withEvent:(UIEvent *)event;
/**
* @abstract Tells the node when touches moved in its view.
*
* @param touches A set of UITouch instances.
* @param event A UIEvent associated with the touch.
*/
- (void)touchesMoved:(NSSet *)touches withEvent:(UIEvent *)event;
/**
* @abstract Tells the node when touches ended in its view.
*
* @param touches A set of UITouch instances.
* @param event A UIEvent associated with the touch.
*/
- (void)touchesEnded:(NSSet *)touches withEvent:(UIEvent *)event;
/**
* @abstract Tells the node when touches was cancelled in its view.
*
* @param touches A set of UITouch instances.
* @param event A UIEvent associated with the touch.
*/
- (void)touchesCancelled:(NSSet *)touches withEvent:(UIEvent *)event;
/** @name Managing Gesture Recognizers */
/**
* @abstract Asks the node if a gesture recognizer should continue tracking touches.
*
* @param gestureRecognizer A gesture recognizer trying to recognize a gesture.
*/
- (BOOL)gestureRecognizerShouldBegin:(UIGestureRecognizer *)gestureRecognizer;
/** @name Hit Testing */
/**
* @abstract Returns the view that contains the point.
*
* @discussion Override to make this node respond differently to touches: (e.g. hide touches from subviews, send all
* touches to certain subviews (hit area maximizing), etc.)
*
* @param point A point specified in the node's local coordinate system (bounds).
* @param event The event that warranted a call to this method.
*
* @return Returns a UIView, not ASDisplayNode, for two reasons:
* 1) allows sending events to plain UIViews that don't have attached nodes,
* 2) hitTest: is never called before the views are created.
*/
- (UIView *)hitTest:(CGPoint)point withEvent:(UIEvent *)event;
/** @name Observing node-related changes */
/**
* Called just before the view is added to a superview.
*/
- (void)willEnterHierarchy ASDISPLAYNODE_REQUIRES_SUPER;
/**
* Called after the view is removed from the window.
*/
- (void)didExitHierarchy ASDISPLAYNODE_REQUIRES_SUPER;
/**
* Provides an opportunity to clear backing store and other memory-intensive intermediates, such as text layout managers
* on the current node.
*
* @discussion Called by -recursivelyClearContents. Base class implements self.contents = nil, clearing any backing
* store, for asynchronous regeneration when needed.
*/
- (void)clearContents ASDISPLAYNODE_REQUIRES_SUPER;
/**
* Provides an opportunity to clear any fetched data (e.g. remote / network or database-queried) on the current node.
*
* @discussion This will not clear data recursively for all subnodes. Either call -recursivelyClearFetchedData or
* selectively clear fetched data.
*/
- (void)clearFetchedData ASDISPLAYNODE_REQUIRES_SUPER;
/** @name Placeholders */
/**
* @abstract Optionally provide an image to serve as the placeholder for the backing store while the contents are being
* displayed.
*
* @discussion
* Subclasses may override this method and return an image to use as the placeholder. Take caution as there may be a
* time and place where this method is called on a background thread. Note that -[UIImage imageNamed:] is not thread
* safe when using image assets.
*
* To retrieve the CGSize to do any image drawing, use the node's calculatedSize property.
*
* Defaults to nil.
*
* @note Called on the display queue and/or main queue (MUST BE THREAD SAFE)
*/
- (UIImage *)placeholderImage;
/** @name Description */
/**
* @abstract Return a description of the node
*
* @discussion The function that gets called for each display node in -recursiveDescription
*/
- (NSString *)descriptionForRecursiveDescription;
@end
@interface ASDisplayNode (ASDisplayNodePrivate)
// This method has proven helpful in a few rare scenarios, similar to a category extension on UIView,
// but it's considered private API for now and its use should not be encouraged.
- (ASDisplayNode *)_supernodeWithClass:(Class)supernodeClass;
@end
#define ASDisplayNodeAssertThreadAffinity(viewNode) ASDisplayNodeAssert(!viewNode || ASDisplayNodeThreadIsMain() || !(viewNode).nodeLoaded, @"Incorrect display node thread affinity")
#define ASDisplayNodeCAssertThreadAffinity(viewNode) ASDisplayNodeCAssert(!viewNode || ASDisplayNodeThreadIsMain() || !(viewNode).nodeLoaded, @"Incorrect display node thread affinity")