| commit | author | age | ||
| 6e1425 | 1 | // |
| H | 2 | // UIView+Toast.h |
| 3 | // Toast | |
| 4 | // | |
| 09e73a | 5 | // Copyright (c) 2011-2024 Charles Scalesse. |
| 6e1425 | 6 | // |
| H | 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; | |
| 09e73a | 124 | |
| L | 125 | /** |
| 126 | Hides the active toast. If there are multiple toasts active in a view, this method | |
| 127 | hides the oldest toast (the first of the toasts to have been presented). | |
| 128 | ||
| 129 | @see `hideAllToasts` to remove all active toasts from a view. | |
| 130 | ||
| 131 | @warning This method has no effect on activity toasts. Use `hideToastActivity` to | |
| 132 | hide activity toasts. | |
| 133 | */ | |
| 134 | - (void)hideToast; | |
| 135 | ||
| 136 | /** | |
| 137 | Hides an active toast. | |
| 138 | ||
| 139 | @param toast The active toast view to dismiss. Any toast that is currently being displayed | |
| 140 | on the screen is considered active. | |
| 141 | ||
| 142 | @warning this does not clear a toast view that is currently waiting in the queue. | |
| 143 | */ | |
| 144 | - (void)hideToast:(UIView *)toast; | |
| 145 | ||
| 146 | /** | |
| 147 | Hides all active toast views and clears the queue. | |
| 148 | */ | |
| 149 | - (void)hideAllToasts; | |
| 150 | ||
| 151 | /** | |
| 152 | Hides all active toast views, with options to hide activity and clear the queue. | |
| 153 | ||
| 154 | @param includeActivity If `true`, toast activity will also be hidden. Default is `false`. | |
| 155 | @param clearQueue If `true`, removes all toast views from the queue. Default is `true`. | |
| 156 | */ | |
| 157 | - (void)hideAllToasts:(BOOL)includeActivity clearQueue:(BOOL)clearQueue; | |
| 158 | ||
| 159 | /** | |
| 160 | Removes all toast views from the queue. This has no effect on toast views that are | |
| 161 | active. Use `hideAllToasts` to hide the active toasts views and clear the queue. | |
| 162 | */ | |
| 163 | - (void)clearToastQueue; | |
| 6e1425 | 164 | |
| H | 165 | /** |
| 166 | Creates and displays a new toast activity indicator view at a specified position. | |
| 167 | ||
| 168 | @warning Only one toast activity indicator view can be presented per superview. Subsequent | |
| 169 | calls to `makeToastActivity:` will be ignored until hideToastActivity is called. | |
| 170 | ||
| 171 | @warning `makeToastActivity:` works independently of the showToast: methods. Toast activity | |
| 172 | views can be presented and dismissed while toast views are being displayed. `makeToastActivity:` | |
| 173 | has no effect on the queueing behavior of the showToast: methods. | |
| 174 | ||
| 175 | @param position The toast's center point. Can be one of the predefined CSToastPosition | |
| 176 | constants or a `CGPoint` wrapped in an `NSValue` object. | |
| 177 | */ | |
| 178 | - (void)makeToastActivity:(id)position; | |
| 179 | ||
| 180 | /** | |
| 181 | Dismisses the active toast activity indicator view. | |
| 182 | */ | |
| 183 | - (void)hideToastActivity; | |
| 184 | ||
| 185 | /** | |
| 186 | Displays any view as toast using the default duration and position. | |
| 187 | ||
| 188 | @param toast The view to be displayed as toast | |
| 189 | */ | |
| 190 | - (void)showToast:(UIView *)toast; | |
| 191 | ||
| 192 | /** | |
| 193 | Displays any view as toast at a provided position and duration. The completion block | |
| 194 | executes when the toast view completes. `didTap` will be `YES` if the toast view was | |
| 195 | dismissed from a tap. | |
| 196 | ||
| 197 | @param toast The view to be displayed as toast | |
| 198 | @param duration The notification duration | |
| 199 | @param position The toast's center point. Can be one of the predefined CSToastPosition | |
| 200 | constants or a `CGPoint` wrapped in an `NSValue` object. | |
| 201 | @param completion The completion block, executed after the toast view disappears. | |
| 202 | didTap will be `YES` if the toast view was dismissed from a tap. | |
| 203 | */ | |
| 204 | - (void)showToast:(UIView *)toast | |
| 205 | duration:(NSTimeInterval)duration | |
| 206 | position:(id)position | |
| 207 | completion:(void(^)(BOOL didTap))completion; | |
| 208 | ||
| 209 | @end | |
| 210 | ||
| 211 | /** | |
| 212 | `CSToastStyle` instances define the look and feel for toast views created via the | |
| 213 | `makeToast:` methods as well for toast views created directly with | |
| 214 | `toastViewForMessage:title:image:style:`. | |
| 215 | ||
| 216 | @warning `CSToastStyle` offers relatively simple styling options for the default | |
| 217 | toast view. If you require a toast view with more complex UI, it probably makes more | |
| 218 | sense to create your own custom UIView subclass and present it with the `showToast:` | |
| 219 | methods. | |
| 220 | */ | |
| 221 | @interface CSToastStyle : NSObject | |
| 222 | ||
| 223 | /** | |
| 224 | The background color. Default is `[UIColor blackColor]` at 80% opacity. | |
| 225 | */ | |
| 226 | @property (strong, nonatomic) UIColor *backgroundColor; | |
| 227 | ||
| 228 | /** | |
| 229 | The title color. Default is `[UIColor whiteColor]`. | |
| 230 | */ | |
| 231 | @property (strong, nonatomic) UIColor *titleColor; | |
| 232 | ||
| 233 | /** | |
| 234 | The message color. Default is `[UIColor whiteColor]`. | |
| 235 | */ | |
| 236 | @property (strong, nonatomic) UIColor *messageColor; | |
| 237 | ||
| 238 | /** | |
| 239 | A percentage value from 0.0 to 1.0, representing the maximum width of the toast | |
| 240 | view relative to it's superview. Default is 0.8 (80% of the superview's width). | |
| 241 | */ | |
| 242 | @property (assign, nonatomic) CGFloat maxWidthPercentage; | |
| 243 | ||
| 244 | /** | |
| 245 | A percentage value from 0.0 to 1.0, representing the maximum height of the toast | |
| 246 | view relative to it's superview. Default is 0.8 (80% of the superview's height). | |
| 247 | */ | |
| 248 | @property (assign, nonatomic) CGFloat maxHeightPercentage; | |
| 249 | ||
| 250 | /** | |
| 251 | The spacing from the horizontal edge of the toast view to the content. When an image | |
| 252 | is present, this is also used as the padding between the image and the text. | |
| 253 | Default is 10.0. | |
| 254 | */ | |
| 255 | @property (assign, nonatomic) CGFloat horizontalPadding; | |
| 256 | ||
| 257 | /** | |
| 258 | The spacing from the vertical edge of the toast view to the content. When a title | |
| 259 | is present, this is also used as the padding between the title and the message. | |
| 260 | Default is 10.0. | |
| 261 | */ | |
| 262 | @property (assign, nonatomic) CGFloat verticalPadding; | |
| 263 | ||
| 264 | /** | |
| 265 | The corner radius. Default is 10.0. | |
| 266 | */ | |
| 267 | @property (assign, nonatomic) CGFloat cornerRadius; | |
| 268 | ||
| 269 | /** | |
| 270 | The title font. Default is `[UIFont boldSystemFontOfSize:16.0]`. | |
| 271 | */ | |
| 272 | @property (strong, nonatomic) UIFont *titleFont; | |
| 273 | ||
| 274 | /** | |
| 275 | The message font. Default is `[UIFont systemFontOfSize:16.0]`. | |
| 276 | */ | |
| 277 | @property (strong, nonatomic) UIFont *messageFont; | |
| 278 | ||
| 279 | /** | |
| 280 | The title text alignment. Default is `NSTextAlignmentLeft`. | |
| 281 | */ | |
| 282 | @property (assign, nonatomic) NSTextAlignment titleAlignment; | |
| 283 | ||
| 284 | /** | |
| 285 | The message text alignment. Default is `NSTextAlignmentLeft`. | |
| 286 | */ | |
| 287 | @property (assign, nonatomic) NSTextAlignment messageAlignment; | |
| 288 | ||
| 289 | /** | |
| 290 | The maximum number of lines for the title. The default is 0 (no limit). | |
| 291 | */ | |
| 292 | @property (assign, nonatomic) NSInteger titleNumberOfLines; | |
| 293 | ||
| 294 | /** | |
| 295 | The maximum number of lines for the message. The default is 0 (no limit). | |
| 296 | */ | |
| 297 | @property (assign, nonatomic) NSInteger messageNumberOfLines; | |
| 298 | ||
| 299 | /** | |
| 300 | Enable or disable a shadow on the toast view. Default is `NO`. | |
| 301 | */ | |
| 302 | @property (assign, nonatomic) BOOL displayShadow; | |
| 303 | ||
| 304 | /** | |
| 305 | The shadow color. Default is `[UIColor blackColor]`. | |
| 306 | */ | |
| 307 | @property (strong, nonatomic) UIColor *shadowColor; | |
| 308 | ||
| 309 | /** | |
| 310 | A value from 0.0 to 1.0, representing the opacity of the shadow. | |
| 311 | Default is 0.8 (80% opacity). | |
| 312 | */ | |
| 313 | @property (assign, nonatomic) CGFloat shadowOpacity; | |
| 314 | ||
| 315 | /** | |
| 316 | The shadow radius. Default is 6.0. | |
| 317 | */ | |
| 318 | @property (assign, nonatomic) CGFloat shadowRadius; | |
| 319 | ||
| 320 | /** | |
| 321 | The shadow offset. The default is `CGSizeMake(4.0, 4.0)`. | |
| 322 | */ | |
| 323 | @property (assign, nonatomic) CGSize shadowOffset; | |
| 324 | ||
| 325 | /** | |
| 326 | The image size. The default is `CGSizeMake(80.0, 80.0)`. | |
| 327 | */ | |
| 328 | @property (assign, nonatomic) CGSize imageSize; | |
| 329 | ||
| 330 | /** | |
| 331 | The size of the toast activity view when `makeToastActivity:` is called. | |
| 332 | Default is `CGSizeMake(100.0, 100.0)`. | |
| 333 | */ | |
| 334 | @property (assign, nonatomic) CGSize activitySize; | |
| 335 | ||
| 336 | /** | |
| 337 | The fade in/out animation duration. Default is 0.2. | |
| 338 | */ | |
| 339 | @property (assign, nonatomic) NSTimeInterval fadeDuration; | |
| 340 | ||
| 341 | /** | |
| 342 | Creates a new instance of `CSToastStyle` with all the default values set. | |
| 343 | */ | |
| 344 | - (instancetype)initWithDefaultStyle NS_DESIGNATED_INITIALIZER; | |
| 345 | ||
| 346 | /** | |
| 347 | @warning Only the designated initializer should be used to create | |
| 348 | an instance of `CSToastStyle`. | |
| 349 | */ | |
| 350 | - (instancetype)init NS_UNAVAILABLE; | |
| 351 | ||
| 352 | @end | |
| 353 | ||
| 354 | /** | |
| 355 | `CSToastManager` provides general configuration options for all toast | |
| 356 | notifications. Backed by a singleton instance. | |
| 357 | */ | |
| 358 | @interface CSToastManager : NSObject | |
| 359 | ||
| 360 | /** | |
| 361 | Sets the shared style on the singleton. The shared style is used whenever | |
| 362 | a `makeToast:` method (or `toastViewForMessage:title:image:style:`) is called | |
| 363 | with with a nil style. By default, this is set to `CSToastStyle`'s default | |
| 364 | style. | |
| 365 | ||
| 09e73a | 366 | @param sharedStyle the shared style |
| 6e1425 | 367 | */ |
| H | 368 | + (void)setSharedStyle:(CSToastStyle *)sharedStyle; |
| 369 | ||
| 370 | /** | |
| 371 | Gets the shared style from the singlton. By default, this is | |
| 372 | `CSToastStyle`'s default style. | |
| 373 | ||
| 374 | @return the shared style | |
| 375 | */ | |
| 376 | + (CSToastStyle *)sharedStyle; | |
| 377 | ||
| 378 | /** | |
| 379 | Enables or disables tap to dismiss on toast views. Default is `YES`. | |
| 380 | ||
| 09e73a | 381 | @param tapToDismissEnabled YES or NO |
| 6e1425 | 382 | */ |
| H | 383 | + (void)setTapToDismissEnabled:(BOOL)tapToDismissEnabled; |
| 384 | ||
| 385 | /** | |
| 386 | Returns `YES` if tap to dismiss is enabled, otherwise `NO`. | |
| 387 | Default is `YES`. | |
| 388 | ||
| 09e73a | 389 | @return BOOL YES or NO |
| 6e1425 | 390 | */ |
| H | 391 | + (BOOL)isTapToDismissEnabled; |
| 392 | ||
| 393 | /** | |
| 394 | Enables or disables queueing behavior for toast views. When `YES`, | |
| 395 | toast views will appear one after the other. When `NO`, multiple Toast | |
| 396 | views will appear at the same time (potentially overlapping depending | |
| 397 | on their positions). This has no effect on the toast activity view, | |
| 09e73a | 398 | which operates independently of normal toast views. Default is `NO`. |
| 6e1425 | 399 | |
| 09e73a | 400 | @param queueEnabled YES or NO |
| 6e1425 | 401 | */ |
| H | 402 | + (void)setQueueEnabled:(BOOL)queueEnabled; |
| 403 | ||
| 404 | /** | |
| 405 | Returns `YES` if the queue is enabled, otherwise `NO`. | |
| 09e73a | 406 | Default is `NO`. |
| 6e1425 | 407 | |
| H | 408 | @return BOOL |
| 409 | */ | |
| 410 | + (BOOL)isQueueEnabled; | |
| 411 | ||
| 412 | /** | |
| 413 | Sets the default duration. Used for the `makeToast:` and | |
| 414 | `showToast:` methods that don't require an explicit duration. | |
| 415 | Default is 3.0. | |
| 416 | ||
| 417 | @param duration The toast duration | |
| 418 | */ | |
| 419 | + (void)setDefaultDuration:(NSTimeInterval)duration; | |
| 420 | ||
| 421 | /** | |
| 422 | Returns the default duration. Default is 3.0. | |
| 423 | ||
| 424 | @return duration The toast duration | |
| 425 | */ | |
| 426 | + (NSTimeInterval)defaultDuration; | |
| 427 | ||
| 428 | /** | |
| 429 | Sets the default position. Used for the `makeToast:` and | |
| 430 | `showToast:` methods that don't require an explicit position. | |
| 431 | Default is `CSToastPositionBottom`. | |
| 432 | ||
| 433 | @param position The default center point. Can be one of the predefined | |
| 434 | CSToastPosition constants or a `CGPoint` wrapped in an `NSValue` object. | |
| 435 | */ | |
| 436 | + (void)setDefaultPosition:(id)position; | |
| 437 | ||
| 438 | /** | |
| 439 | Returns the default toast position. Default is `CSToastPositionBottom`. | |
| 440 | ||
| 441 | @return position The default center point. Will be one of the predefined | |
| 442 | CSToastPosition constants or a `CGPoint` wrapped in an `NSValue` object. | |
| 443 | */ | |
| 444 | + (id)defaultPosition; | |
| 445 | ||
| 446 | @end | |
