| commit | author | age | ||
| a0a843 | 1 | // |
| H | 2 | // TWTRTweetView.h |
| 3 | // | |
| 4 | // Copyright (c) 2015 Twitter. All rights reserved. | |
| 5 | // | |
| 6 | ||
| 7 | #import <UIKit/UIKit.h> | |
| 8 | #import "TWTRTweetViewDelegate.h" | |
| 9 | ||
| 10 | @class TWTRTweet; | |
| 11 | ||
| 12 | NS_ASSUME_NONNULL_BEGIN | |
| 13 | ||
| 14 | /** | |
| 15 | * The style for Tweet views. | |
| 16 | */ | |
| 17 | typedef NS_ENUM(NSUInteger, TWTRTweetViewStyle) { | |
| 18 | ||
| 19 | /** | |
| 20 | * A full-size Tweet view. Displays images if present. | |
| 21 | */ | |
| 22 | TWTRTweetViewStyleRegular, | |
| 23 | ||
| 24 | /** | |
| 25 | * A small Tweet view, primarily designed to be used in table views. | |
| 26 | */ | |
| 27 | TWTRTweetViewStyleCompact | |
| 28 | }; | |
| 29 | ||
| 30 | /** | |
| 31 | * A default combination of colors for Tweet views. | |
| 32 | */ | |
| 33 | typedef NS_ENUM(NSUInteger, TWTRTweetViewTheme) { | |
| 34 | ||
| 35 | /** | |
| 36 | * Official light theme. | |
| 37 | */ | |
| 38 | TWTRTweetViewThemeLight, | |
| 39 | ||
| 40 | /** | |
| 41 | * Official dark theme. | |
| 42 | */ | |
| 43 | TWTRTweetViewThemeDark, | |
| 44 | }; | |
| 45 | ||
| 46 | /** | |
| 47 | `TWTRTweetView` displays a single Tweet to the user. It handles background taps and other actions displayed to the user. | |
| 48 | ||
| 49 | TWTRAPIClient *APIClient = [[TWTRAPIClient alloc] init]; | |
| 50 | [[APIClient loadTweetWithID:@"20" completion:^(TWTRTweet *tweet, NSError *error) { | |
| 51 | if (tweet) { | |
| 52 | TWTRTweetView *tweetView = [[TWTRTweetView alloc] initWithTweet:tweet]; | |
| 53 | [self.view addSubview:tweetView]; | |
| 54 | } else { | |
| 55 | NSLog(@"Error loading Tweet: %@", [error localizedDescription]); | |
| 56 | } | |
| 57 | }]; | |
| 58 | ||
| 59 | ## Interaction | |
| 60 | ||
| 61 | The `TWTRTweetViewDelegate` is notified: | |
| 62 | ||
| 63 | - When the background is tapped. | |
| 64 | - When a link is selected. | |
| 65 | - When the share button is tapped. | |
| 66 | - When the share action completes. | |
| 67 | - When the favorite action completes. | |
| 68 | ||
| 69 | ## Usage in UITableView | |
| 70 | ||
| 71 | To allow for usage in a `UITableView`, the `configureWithTweet:` method allows configuration of an existing `TWTRTweetView` without having to create a new instance. | |
| 72 | ||
| 73 | ## Sizing | |
| 74 | ||
| 75 | When using Auto Layout, feel free to set a width or margin on the Tweet view. The height will be calculated automatically. For old-fashioned frame based layout you may use the standard `sizeThatFits:` method to calculate the appropriate height for a given width: | |
| 76 | ||
| 77 | // Find the height for a given width (20pts on either side) | |
| 78 | CGFloat desiredHeight = [tweetView sizeThatFits:CGSizeMake(self.view.frame.size.width - 40, CGFLOAT_MAX)].height; | |
| 79 | ||
| 80 | ## UIAppearance | |
| 81 | ||
| 82 | You may use UIAppearance proxy objects to style certain aspects of Tweet views before those views are added to the view hierarchy. | |
| 83 | ||
| 84 | // Using UIAppearance Proxy | |
| 85 | [TWTRTweetView appearance].theme = TWTRTweetViewThemeDark; | |
| 86 | ||
| 87 | // Setting colors directly | |
| 88 | [TWTRTweetView appearance].primaryTextColor = [UIColor yellowColor]; | |
| 89 | [TWTRTweetView appearance].backgroundColor = [UIColor blueColor]; | |
| 90 | ||
| 91 | // Setting action button visibility | |
| 92 | [TWTRTweetView appearance].showActionButtons = NO; | |
| 93 | ||
| 94 | _Note:_ You can't change the theme through an appearance proxy after the view has already been added to the view hierarchy. Direct `theme` property access will work though. | |
| 95 | */ | |
| 96 | @interface TWTRTweetView : UIView <UIAppearanceContainer> | |
| 97 | ||
| 98 | /** | |
| 99 | * The Tweet being displayed. | |
| 100 | */ | |
| 101 | @property (nonatomic, readonly) TWTRTweet *tweet; | |
| 102 | ||
| 103 | /** | |
| 104 | * Background color of the Tweet view and all text labels (fullname, username, Tweet text, timestamp). | |
| 105 | */ | |
| 106 | @property (nonatomic) UIColor *backgroundColor UI_APPEARANCE_SELECTOR; | |
| 107 | ||
| 108 | /** | |
| 109 | * Color of Tweet text and full name. | |
| 110 | */ | |
| 111 | @property (nonatomic) UIColor *primaryTextColor UI_APPEARANCE_SELECTOR; | |
| 112 | ||
| 113 | /** | |
| 114 | * Color of links in Tweet text. | |
| 115 | */ | |
| 116 | @property (nonatomic) UIColor *linkTextColor UI_APPEARANCE_SELECTOR; | |
| 117 | ||
| 118 | /** | |
| 119 | * Set whether the border should be shown. | |
| 120 | * Defaults to YES. | |
| 121 | */ | |
| 122 | @property (nonatomic) BOOL showBorder UI_APPEARANCE_SELECTOR; | |
| 123 | ||
| 124 | /** | |
| 125 | * Set whether the action buttons (Favorite, Share) should be shown. When toggled, | |
| 126 | * both the visibility of the action buttons and the internal constraints are | |
| 127 | * updated immediately. The layout will be updated the next layout pass that occurs. | |
| 128 | * | |
| 129 | * Defaults to NO. | |
| 130 | */ | |
| 131 | @property (nonatomic) BOOL showActionButtons; | |
| 132 | ||
| 133 | /** | |
| 134 | * Setting the theme of the Tweet view will change the color properties accordingly. | |
| 135 | * | |
| 136 | * Set to `TWTRTweetViewThemeLight` by default. | |
| 137 | */ | |
| 138 | @property (nonatomic) TWTRTweetViewTheme theme; | |
| 139 | ||
| 140 | /** | |
| 141 | * The style of the Tweet. i.e. `TWTRTweetViewStyleRegular` or `TWTRTweetViewStyleCompact`. | |
| 142 | */ | |
| 143 | @property (nonatomic, readonly) TWTRTweetViewStyle style; | |
| 144 | ||
| 145 | /** | |
| 146 | * Optional delegate to receive notifications when certain actions happen | |
| 147 | */ | |
| 148 | @property (nonatomic, weak) IBOutlet id<TWTRTweetViewDelegate> delegate; | |
| 149 | ||
| 150 | /** | |
| 151 | * Optional property to set a UIViewController from which to present various new UI | |
| 152 | * e.g. when presenting a Share sheet, presenting a login view controller for actions, etc | |
| 153 | */ | |
| 154 | @property (nonatomic, weak) UIViewController *presenterViewController; | |
| 155 | ||
| 156 | /** | |
| 157 | * Convenience initializer to configure a compact style Tweet view. | |
| 158 | * | |
| 159 | * @param tweet The Tweet to display. | |
| 160 | * | |
| 161 | * @return The fully-configured Tweet view. | |
| 162 | */ | |
| 163 | - (instancetype)initWithTweet:(nullable TWTRTweet *)tweet; | |
| 164 | ||
| 165 | /** | |
| 166 | * Designated initializer. Initializes view with both Tweet and style. | |
| 167 | * | |
| 168 | * @param tweet The Tweet to display. | |
| 169 | * @param style The style of the Tweet view (regular or compact). | |
| 170 | * | |
| 171 | * @return The fully configured Tweet view. | |
| 172 | */ | |
| 173 | - (instancetype)initWithTweet:(nullable TWTRTweet *)tweet style:(TWTRTweetViewStyle)style; | |
| 174 | ||
| 175 | /** | |
| 176 | * Initialization with a frame parameter is not supported. | |
| 177 | */ | |
| 178 | - (instancetype)initWithFrame:(CGRect)frame NS_UNAVAILABLE; | |
| 179 | ||
| 180 | /** | |
| 181 | Find the size that fits into a desired space. This is a system method on UIView but implemented on `TWTRTweetView` | |
| 182 | ||
| 183 | // Calculate the desired height at 280 points wide | |
| 184 | CGSize desiredSize = [tweetView sizeThatFits:CGSizeMake(280, CGFLOAT_MAX)]; | |
| 185 | ||
| 186 | ||
| 187 | @param size The space available. Should generally leave one orientation unconstrained, and the minimum width supported is 200pts. | |
| 188 | ||
| 189 | @return The size that will fit into the space available. | |
| 190 | */ | |
| 191 | - (CGSize)sizeThatFits:(CGSize)size; | |
| 192 | ||
| 193 | /** | |
| 194 | * Update all images and label text to fully represent the given Tweet. | |
| 195 | * | |
| 196 | * @param tweet The Tweet to display. | |
| 197 | */ | |
| 198 | - (void)configureWithTweet:(nullable TWTRTweet *)tweet; | |
| 199 | ||
| 200 | @end | |
| 201 | ||
| 202 | NS_ASSUME_NONNULL_END | |
