| commit | author | age | ||
| 655e66 | 1 | /* |
| H | 2 | * Copyright (C) 2017 Twitter, Inc. |
| 3 | * | |
| 4 | * Licensed under the Apache License, Version 2.0 (the "License"); | |
| 5 | * you may not use this file except in compliance with the License. | |
| 6 | * You may obtain a copy of the License at | |
| 7 | * | |
| 8 | * http://www.apache.org/licenses/LICENSE-2.0 | |
| 9 | * | |
| 10 | * Unless required by applicable law or agreed to in writing, software | |
| 11 | * distributed under the License is distributed on an "AS IS" BASIS, | |
| 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
| 13 | * See the License for the specific language governing permissions and | |
| 14 | * limitations under the License. | |
| 15 | * | |
| 16 | */ | |
| a0a843 | 17 | |
| H | 18 | #import <UIKit/UIKit.h> |
| 19 | @protocol TWTRTimelineDataSource; | |
| 20 | @protocol TWTRTweetViewDelegate; | |
| 21 | @protocol TWTRTimelineDelegate; | |
| 22 | @class TWTRMoPubAdConfiguration; | |
| 23 | @class TWTRTweet; | |
| 24 | ||
| 25 | NS_ASSUME_NONNULL_BEGIN | |
| 26 | ||
| 27 | /** | |
| 28 | This class is a `UITableViewController` subclass that displays `TWTRTweetTableViewCell` cells. It handles cell-reuse, cell-configuration, and loading more Tweets from the given timeline once the last cell is displayed. | |
| 29 | ||
| 30 | ## Usage | |
| 31 | ||
| 32 | Initialize this class with any object that conforms to the `TWTRTimelineDataSource` protocol. We provide two such classes, `TWTRUserTimelineDataSource` and `TWTRSearchTimelineDataSource`. These provide `TWTRTweet` objects to this table view which then configures the instances of `TWTRTweetTableViewCell`. | |
| 33 | ||
| 34 | // Create the data source | |
| 35 | TWTRAPIClient *client = [[TWTRAPIClient alloc] init]; | |
| 36 | TWTRUserTimelineDataSource *dataSource = [[TWTRUserTimelineDataSource alloc] initWithScreenName:@"jack" APIClient:client]; | |
| 37 | ||
| 38 | // Create the timeline view controller | |
| 39 | TWTRTimelineViewController *timeline = [[TWTRTimelineViewController alloc] initWithDataSource:dataSource]; | |
| 40 | ||
| 41 | ## Loading More | |
| 42 | ||
| 43 | This class loads the first batch of `TWTRTweet` objects from the Twitter API when `viewWillAppear:` is received. It also handles loading more tweets automatically once the last cell has been shown. | |
| 44 | ||
| 45 | */ | |
| 46 | @interface TWTRTimelineViewController : UITableViewController | |
| 47 | ||
| 48 | /** | |
| 49 | The source of `TWTRTweet` objects for this `TWTRTimelineViewController`. | |
| 50 | May be set to update the Tweets being shown by this table view. Must be set on the main thread. | |
| 51 | */ | |
| 52 | @property (nonatomic, copy) id<TWTRTimelineDataSource> dataSource; | |
| 53 | ||
| 54 | /** | |
| 55 | * The configuration of MoPub ads to show in the timeline. You must | |
| 56 | * link against the MoPub framework and provide this configuration in order | |
| 57 | * for ads to be injected. | |
| 58 | * @note Changing this will force a reload of the timeline. You can only set this once. Must be set on the main thread. | |
| 59 | */ | |
| 60 | @property (nonatomic, nullable) TWTRMoPubAdConfiguration *adConfiguration; | |
| 61 | ||
| 62 | /** | |
| 63 | * Whether action buttons (Like, Share) should be shown on the `TWTRTweetTableViewCell`s inside the tableview. | |
| 64 | */ | |
| 65 | @property (nonatomic) BOOL showTweetActions; | |
| 66 | ||
| 67 | /** | |
| 68 | * If set, this value will be passed to all TWTRTweetView instances in the timeline. | |
| 69 | */ | |
| 70 | @property (nonatomic, weak) id<TWTRTweetViewDelegate> tweetViewDelegate; | |
| 71 | ||
| 72 | /** | |
| 73 | * The object that acts as the delegate for the timeline. | |
| 74 | */ | |
| 75 | @property (nonatomic, weak) id<TWTRTimelineDelegate> timelineDelegate; | |
| 76 | ||
| 77 | /** | |
| 78 | Initializes a timeline view controller. Does not start loading tweets until | |
| 79 | `viewWillAppear:` is called. | |
| 80 | ||
| 81 | This method must be used to initialize this class. The `init` method is unavailable. | |
| 82 | ||
| 83 | @param dataSource A timeline data source object that conforms to the `TWTRTimelineDataSource` protocol. | |
| 84 | ||
| 85 | @return A fully initialized `TWTRTimelineViewController` or nil if the data source is missing. | |
| 86 | */ | |
| 87 | - (instancetype)initWithDataSource:(nullable id<TWTRTimelineDataSource>)dataSource; | |
| 88 | ||
| 89 | /** | |
| 90 | * Initializes a timeline view controller with an optional ad configuration. Does not start loading Tweets until `viewWillAppear:` is called. | |
| 91 | * | |
| 92 | * @param dataSource A timeline data source object that conforms to the `TWTRTimelineDataSource` protocol. | |
| 93 | * @param adConfiguration Configuration for the type of MoPub ads to display. Ads will only load after | |
| 94 | * the initial timeline is loaded. No ads will be displayed if nil. | |
| 95 | * | |
| 96 | * @return A fully initialized `TWTRTimelineViewController`. Tweets will not be loaded if the data source is nil. | |
| 97 | */ | |
| 98 | - (instancetype)initWithDataSource:(nullable id<TWTRTimelineDataSource>)dataSource adConfiguration:(nullable TWTRMoPubAdConfiguration *)adConfiguration; | |
| 99 | ||
| 100 | - (instancetype)initWithStyle:(UITableViewStyle)style NS_UNAVAILABLE; | |
| 101 | ||
| 102 | /** | |
| 103 | * Asynchronously refresh and replace all the data in the table view with the latest `TWTRTweet`s. | |
| 104 | */ | |
| 105 | - (void)refresh; | |
| 106 | ||
| 107 | /** | |
| 108 | * Returns the number of Tweets that are currently displayed by the controller. | |
| 109 | */ | |
| 110 | - (NSUInteger)countOfTweets; | |
| 111 | ||
| 112 | /** | |
| 113 | * Returns the Tweet at the given index. | |
| 114 | * | |
| 115 | * @warning This method will throw an exception if the index is out of range of the count of Tweets. | |
| 116 | */ | |
| 117 | - (TWTRTweet *)tweetAtIndex:(NSInteger)index; | |
| 118 | ||
| 119 | /** | |
| 120 | * Returns a copy of the Tweets at the time of calling this method. | |
| 121 | ||
| 122 | * This method returns the copy of the current Tweets. The Tweets may change | |
| 123 | * after this method is called. | |
| 124 | */ | |
| 125 | - (NSArray *)snapshotTweets; | |
| 126 | ||
| 127 | @end | |
| 128 | ||
| 129 | NS_ASSUME_NONNULL_END | |
