| commit | author | age | ||
| 6e1425 | 1 | // |
| H | 2 | // UIView+Toast.h |
| 3 | // Toast | |
| 4 | // | |
| 5 | // Copyright (c) 2011-2015 Charles Scalesse. | |
| 6 | // | |
| 7 | // Permission is hereby granted, free of charge, to any person obtaining a | |
| 8 | // copy of this software and associated documentation files (the | |
| 9 | // "Software"), to deal in the Software without restriction, including | |
| 10 | // without limitation the rights to use, copy, modify, merge, publish, | |
| 11 | // distribute, sublicense, and/or sell copies of the Software, and to | |
| 12 | // permit persons to whom the Software is furnished to do so, subject to | |
| 13 | // the following conditions: | |
| 14 | // | |
| 15 | // The above copyright notice and this permission notice shall be included | |
| 16 | // in all copies or substantial portions of the Software. | |
| 17 | // | |
| 18 | // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS | |
| 19 | // OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF | |
| 20 | // MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. | |
| 21 | // IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY | |
| 22 | // CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, | |
| 23 | // TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE | |
| 24 | // SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. | |
| 25 | ||
| 26 | #import <UIKit/UIKit.h> | |
| 27 | ||
| 28 | extern const NSString * CSToastPositionTop; | |
| 29 | extern const NSString * CSToastPositionCenter; | |
| 30 | extern const NSString * CSToastPositionBottom; | |
| 31 | ||
| 32 | @class CSToastStyle; | |
| 33 | ||
| 34 | /** | |
| 35 | Toast is an Objective-C category that adds toast notifications to the UIView | |
| 36 | object class. It is intended to be simple, lightweight, and easy to use. Most | |
| 37 | toast notifications can be triggered with a single line of code. | |
| 38 | ||
| 39 | The `makeToast:` methods create a new view and then display it as toast. | |
| 40 | ||
| 41 | The `showToast:` methods display any view as toast. | |
| 42 | ||
| 43 | */ | |
| 44 | @interface UIView (Toast) | |
| 45 | ||
| 46 | /** | |
| 47 | Creates and presents a new toast view with a message and displays it with the | |
| 48 | default duration and position. Styled using the shared style. | |
| 49 | ||
| 50 | @param message The message to be displayed | |
| 51 | */ | |
| 52 | - (void)makeToast:(NSString *)message; | |
| 53 | ||
| 54 | /** | |
| 55 | Creates and presents a new toast view with a message. Duration and position | |
| 56 | can be set explicitly. Styled using the shared style. | |
| 57 | ||
| 58 | @param message The message to be displayed | |
| 59 | @param duration The toast duration | |
| 60 | @param position The toast's center point. Can be one of the predefined CSToastPosition | |
| 61 | constants or a `CGPoint` wrapped in an `NSValue` object. | |
| 62 | */ | |
| 63 | - (void)makeToast:(NSString *)message | |
| 64 | duration:(NSTimeInterval)duration | |
| 65 | position:(id)position; | |
| 66 | ||
| 67 | /** | |
| 68 | Creates and presents a new toast view with a message. Duration, position, and | |
| 69 | style can be set explicitly. | |
| 70 | ||
| 71 | @param message The message to be displayed | |
| 72 | @param duration The toast duration | |
| 73 | @param position The toast's center point. Can be one of the predefined CSToastPosition | |
| 74 | constants or a `CGPoint` wrapped in an `NSValue` object. | |
| 75 | @param style The style. The shared style will be used when nil | |
| 76 | */ | |
| 77 | - (void)makeToast:(NSString *)message | |
| 78 | duration:(NSTimeInterval)duration | |
| 79 | position:(id)position | |
| 80 | style:(CSToastStyle *)style; | |
| 81 | ||
| 82 | /** | |
| 83 | Creates and presents a new toast view with a message, title, and image. Duration, | |
| 84 | position, and style can be set explicitly. The completion block executes when the | |
| 85 | toast view completes. `didTap` will be `YES` if the toast view was dismissed from | |
| 86 | a tap. | |
| 87 | ||
| 88 | @param message The message to be displayed | |
| 89 | @param duration The toast duration | |
| 90 | @param position The toast's center point. Can be one of the predefined CSToastPosition | |
| 91 | constants or a `CGPoint` wrapped in an `NSValue` object. | |
| 92 | @param title The title | |
| 93 | @param image The image | |
| 94 | @param style The style. The shared style will be used when nil | |
| 95 | @param completion The completion block, executed after the toast view disappears. | |
| 96 | didTap will be `YES` if the toast view was dismissed from a tap. | |
| 97 | */ | |
| 98 | - (void)makeToast:(NSString *)message | |
| 99 | duration:(NSTimeInterval)duration | |
| 100 | position:(id)position | |
| 101 | title:(NSString *)title | |
| 102 | image:(UIImage *)image | |
| 103 | style:(CSToastStyle *)style | |
| 104 | completion:(void(^)(BOOL didTap))completion; | |
| 105 | ||
| 106 | /** | |
| 107 | Creates a new toast view with any combination of message, title, and image. | |
| 108 | The look and feel is configured via the style. Unlike the `makeToast:` methods, | |
| 109 | this method does not present the toast view automatically. One of the showToast: | |
| 110 | methods must be used to present the resulting view. | |
| 111 | ||
| 112 | @warning if message, title, and image are all nil, this method will return nil. | |
| 113 | ||
| 114 | @param message The message to be displayed | |
| 115 | @param title The title | |
| 116 | @param image The image | |
| 117 | @param style The style. The shared style will be used when nil | |
| 118 | @return The newly created toast view | |
| 119 | */ | |
| 120 | - (UIView *)toastViewForMessage:(NSString *)message | |
| 121 | title:(NSString *)title | |
| 122 | image:(UIImage *)image | |
| 123 | style:(CSToastStyle *)style; | |
| 124 | ||
| 125 | /** | |
| 126 | Creates and displays a new toast activity indicator view at a specified position. | |
| 127 | ||
| 128 | @warning Only one toast activity indicator view can be presented per superview. Subsequent | |
| 129 | calls to `makeToastActivity:` will be ignored until hideToastActivity is called. | |
| 130 | ||
| 131 | @warning `makeToastActivity:` works independently of the showToast: methods. Toast activity | |
| 132 | views can be presented and dismissed while toast views are being displayed. `makeToastActivity:` | |
| 133 | has no effect on the queueing behavior of the showToast: methods. | |
| 134 | ||
| 135 | @param position The toast's center point. Can be one of the predefined CSToastPosition | |
| 136 | constants or a `CGPoint` wrapped in an `NSValue` object. | |
| 137 | */ | |
| 138 | - (void)makeToastActivity:(id)position; | |
| 139 | ||
| 140 | /** | |
| 141 | Dismisses the active toast activity indicator view. | |
| 142 | */ | |
| 143 | - (void)hideToastActivity; | |
| 144 | ||
| 145 | /** | |
| 146 | Displays any view as toast using the default duration and position. | |
| 147 | ||
| 148 | @param toast The view to be displayed as toast | |
| 149 | */ | |
| 150 | - (void)showToast:(UIView *)toast; | |
| 151 | ||
| 152 | /** | |
| 153 | Displays any view as toast at a provided position and duration. The completion block | |
| 154 | executes when the toast view completes. `didTap` will be `YES` if the toast view was | |
| 155 | dismissed from a tap. | |
| 156 | ||
| 157 | @param toast The view to be displayed as toast | |
| 158 | @param duration The notification duration | |
| 159 | @param position The toast's center point. Can be one of the predefined CSToastPosition | |
| 160 | constants or a `CGPoint` wrapped in an `NSValue` object. | |
| 161 | @param completion The completion block, executed after the toast view disappears. | |
| 162 | didTap will be `YES` if the toast view was dismissed from a tap. | |
| 163 | */ | |
| 164 | - (void)showToast:(UIView *)toast | |
| 165 | duration:(NSTimeInterval)duration | |
| 166 | position:(id)position | |
| 167 | completion:(void(^)(BOOL didTap))completion; | |
| 168 | ||
| 169 | @end | |
| 170 | ||
| 171 | /** | |
| 172 | `CSToastStyle` instances define the look and feel for toast views created via the | |
| 173 | `makeToast:` methods as well for toast views created directly with | |
| 174 | `toastViewForMessage:title:image:style:`. | |
| 175 | ||
| 176 | @warning `CSToastStyle` offers relatively simple styling options for the default | |
| 177 | toast view. If you require a toast view with more complex UI, it probably makes more | |
| 178 | sense to create your own custom UIView subclass and present it with the `showToast:` | |
| 179 | methods. | |
| 180 | */ | |
| 181 | @interface CSToastStyle : NSObject | |
| 182 | ||
| 183 | /** | |
| 184 | The background color. Default is `[UIColor blackColor]` at 80% opacity. | |
| 185 | */ | |
| 186 | @property (strong, nonatomic) UIColor *backgroundColor; | |
| 187 | ||
| 188 | /** | |
| 189 | The title color. Default is `[UIColor whiteColor]`. | |
| 190 | */ | |
| 191 | @property (strong, nonatomic) UIColor *titleColor; | |
| 192 | ||
| 193 | /** | |
| 194 | The message color. Default is `[UIColor whiteColor]`. | |
| 195 | */ | |
| 196 | @property (strong, nonatomic) UIColor *messageColor; | |
| 197 | ||
| 198 | /** | |
| 199 | A percentage value from 0.0 to 1.0, representing the maximum width of the toast | |
| 200 | view relative to it's superview. Default is 0.8 (80% of the superview's width). | |
| 201 | */ | |
| 202 | @property (assign, nonatomic) CGFloat maxWidthPercentage; | |
| 203 | ||
| 204 | /** | |
| 205 | A percentage value from 0.0 to 1.0, representing the maximum height of the toast | |
| 206 | view relative to it's superview. Default is 0.8 (80% of the superview's height). | |
| 207 | */ | |
| 208 | @property (assign, nonatomic) CGFloat maxHeightPercentage; | |
| 209 | ||
| 210 | /** | |
| 211 | The spacing from the horizontal edge of the toast view to the content. When an image | |
| 212 | is present, this is also used as the padding between the image and the text. | |
| 213 | Default is 10.0. | |
| 214 | */ | |
| 215 | @property (assign, nonatomic) CGFloat horizontalPadding; | |
| 216 | ||
| 217 | /** | |
| 218 | The spacing from the vertical edge of the toast view to the content. When a title | |
| 219 | is present, this is also used as the padding between the title and the message. | |
| 220 | Default is 10.0. | |
| 221 | */ | |
| 222 | @property (assign, nonatomic) CGFloat verticalPadding; | |
| 223 | ||
| 224 | /** | |
| 225 | The corner radius. Default is 10.0. | |
| 226 | */ | |
| 227 | @property (assign, nonatomic) CGFloat cornerRadius; | |
| 228 | ||
| 229 | /** | |
| 230 | The title font. Default is `[UIFont boldSystemFontOfSize:16.0]`. | |
| 231 | */ | |
| 232 | @property (strong, nonatomic) UIFont *titleFont; | |
| 233 | ||
| 234 | /** | |
| 235 | The message font. Default is `[UIFont systemFontOfSize:16.0]`. | |
| 236 | */ | |
| 237 | @property (strong, nonatomic) UIFont *messageFont; | |
| 238 | ||
| 239 | /** | |
| 240 | The title text alignment. Default is `NSTextAlignmentLeft`. | |
| 241 | */ | |
| 242 | @property (assign, nonatomic) NSTextAlignment titleAlignment; | |
| 243 | ||
| 244 | /** | |
| 245 | The message text alignment. Default is `NSTextAlignmentLeft`. | |
| 246 | */ | |
| 247 | @property (assign, nonatomic) NSTextAlignment messageAlignment; | |
| 248 | ||
| 249 | /** | |
| 250 | The maximum number of lines for the title. The default is 0 (no limit). | |
| 251 | */ | |
| 252 | @property (assign, nonatomic) NSInteger titleNumberOfLines; | |
| 253 | ||
| 254 | /** | |
| 255 | The maximum number of lines for the message. The default is 0 (no limit). | |
| 256 | */ | |
| 257 | @property (assign, nonatomic) NSInteger messageNumberOfLines; | |
| 258 | ||
| 259 | /** | |
| 260 | Enable or disable a shadow on the toast view. Default is `NO`. | |
| 261 | */ | |
| 262 | @property (assign, nonatomic) BOOL displayShadow; | |
| 263 | ||
| 264 | /** | |
| 265 | The shadow color. Default is `[UIColor blackColor]`. | |
| 266 | */ | |
| 267 | @property (strong, nonatomic) UIColor *shadowColor; | |
| 268 | ||
| 269 | /** | |
| 270 | A value from 0.0 to 1.0, representing the opacity of the shadow. | |
| 271 | Default is 0.8 (80% opacity). | |
| 272 | */ | |
| 273 | @property (assign, nonatomic) CGFloat shadowOpacity; | |
| 274 | ||
| 275 | /** | |
| 276 | The shadow radius. Default is 6.0. | |
| 277 | */ | |
| 278 | @property (assign, nonatomic) CGFloat shadowRadius; | |
| 279 | ||
| 280 | /** | |
| 281 | The shadow offset. The default is `CGSizeMake(4.0, 4.0)`. | |
| 282 | */ | |
| 283 | @property (assign, nonatomic) CGSize shadowOffset; | |
| 284 | ||
| 285 | /** | |
| 286 | The image size. The default is `CGSizeMake(80.0, 80.0)`. | |
| 287 | */ | |
| 288 | @property (assign, nonatomic) CGSize imageSize; | |
| 289 | ||
| 290 | /** | |
| 291 | The size of the toast activity view when `makeToastActivity:` is called. | |
| 292 | Default is `CGSizeMake(100.0, 100.0)`. | |
| 293 | */ | |
| 294 | @property (assign, nonatomic) CGSize activitySize; | |
| 295 | ||
| 296 | /** | |
| 297 | The fade in/out animation duration. Default is 0.2. | |
| 298 | */ | |
| 299 | @property (assign, nonatomic) NSTimeInterval fadeDuration; | |
| 300 | ||
| 301 | /** | |
| 302 | Creates a new instance of `CSToastStyle` with all the default values set. | |
| 303 | */ | |
| 304 | - (instancetype)initWithDefaultStyle NS_DESIGNATED_INITIALIZER; | |
| 305 | ||
| 306 | /** | |
| 307 | @warning Only the designated initializer should be used to create | |
| 308 | an instance of `CSToastStyle`. | |
| 309 | */ | |
| 310 | - (instancetype)init NS_UNAVAILABLE; | |
| 311 | ||
| 312 | @end | |
| 313 | ||
| 314 | /** | |
| 315 | `CSToastManager` provides general configuration options for all toast | |
| 316 | notifications. Backed by a singleton instance. | |
| 317 | */ | |
| 318 | @interface CSToastManager : NSObject | |
| 319 | ||
| 320 | /** | |
| 321 | Sets the shared style on the singleton. The shared style is used whenever | |
| 322 | a `makeToast:` method (or `toastViewForMessage:title:image:style:`) is called | |
| 323 | with with a nil style. By default, this is set to `CSToastStyle`'s default | |
| 324 | style. | |
| 325 | ||
| 326 | @param sharedStyle | |
| 327 | */ | |
| 328 | + (void)setSharedStyle:(CSToastStyle *)sharedStyle; | |
| 329 | ||
| 330 | /** | |
| 331 | Gets the shared style from the singlton. By default, this is | |
| 332 | `CSToastStyle`'s default style. | |
| 333 | ||
| 334 | @return the shared style | |
| 335 | */ | |
| 336 | + (CSToastStyle *)sharedStyle; | |
| 337 | ||
| 338 | /** | |
| 339 | Enables or disables tap to dismiss on toast views. Default is `YES`. | |
| 340 | ||
| 341 | @param allowTapToDismiss | |
| 342 | */ | |
| 343 | + (void)setTapToDismissEnabled:(BOOL)tapToDismissEnabled; | |
| 344 | ||
| 345 | /** | |
| 346 | Returns `YES` if tap to dismiss is enabled, otherwise `NO`. | |
| 347 | Default is `YES`. | |
| 348 | ||
| 349 | @return BOOL | |
| 350 | */ | |
| 351 | + (BOOL)isTapToDismissEnabled; | |
| 352 | ||
| 353 | /** | |
| 354 | Enables or disables queueing behavior for toast views. When `YES`, | |
| 355 | toast views will appear one after the other. When `NO`, multiple Toast | |
| 356 | views will appear at the same time (potentially overlapping depending | |
| 357 | on their positions). This has no effect on the toast activity view, | |
| 358 | which operates independently of normal toast views. Default is `YES`. | |
| 359 | ||
| 360 | @param queueEnabled | |
| 361 | */ | |
| 362 | + (void)setQueueEnabled:(BOOL)queueEnabled; | |
| 363 | ||
| 364 | /** | |
| 365 | Returns `YES` if the queue is enabled, otherwise `NO`. | |
| 366 | Default is `YES`. | |
| 367 | ||
| 368 | @return BOOL | |
| 369 | */ | |
| 370 | + (BOOL)isQueueEnabled; | |
| 371 | ||
| 372 | /** | |
| 373 | Sets the default duration. Used for the `makeToast:` and | |
| 374 | `showToast:` methods that don't require an explicit duration. | |
| 375 | Default is 3.0. | |
| 376 | ||
| 377 | @param duration The toast duration | |
| 378 | */ | |
| 379 | + (void)setDefaultDuration:(NSTimeInterval)duration; | |
| 380 | ||
| 381 | /** | |
| 382 | Returns the default duration. Default is 3.0. | |
| 383 | ||
| 384 | @return duration The toast duration | |
| 385 | */ | |
| 386 | + (NSTimeInterval)defaultDuration; | |
| 387 | ||
| 388 | /** | |
| 389 | Sets the default position. Used for the `makeToast:` and | |
| 390 | `showToast:` methods that don't require an explicit position. | |
| 391 | Default is `CSToastPositionBottom`. | |
| 392 | ||
| 393 | @param position The default center point. Can be one of the predefined | |
| 394 | CSToastPosition constants or a `CGPoint` wrapped in an `NSValue` object. | |
| 395 | */ | |
| 396 | + (void)setDefaultPosition:(id)position; | |
| 397 | ||
| 398 | /** | |
| 399 | Returns the default toast position. Default is `CSToastPositionBottom`. | |
| 400 | ||
| 401 | @return position The default center point. Will be one of the predefined | |
| 402 | CSToastPosition constants or a `CGPoint` wrapped in an `NSValue` object. | |
| 403 | */ | |
| 404 | + (id)defaultPosition; | |
| 405 | ||
| 406 | @end | |
