StaticContentTableViewManager.h 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255
  1. /*
  2. * Copyright 2019 Google
  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. #import <UIKit/UIKit.h>
  17. #pragma mark - Forward Declarations
  18. @class StaticContentTableViewCell;
  19. @class StaticContentTableViewContent;
  20. @class StaticContentTableViewSection;
  21. #pragma mark - Block Type Definitions
  22. /** @typedef StaticContentTableViewCellAction
  23. @brief The type of block invoked when a cell is tapped.
  24. */
  25. typedef void(^StaticContentTableViewCellAction)(void);
  26. #pragma mark -
  27. /** @class StaticContentTableViewManager
  28. @brief Generic class useful for populating a @c UITableView with static content.
  29. @remarks Because I keep writing the same UITableView code for every internal testing app, and
  30. it's getting too tedious and ugly to keep writing the same thing over and over. It makes
  31. our sample apps harder to maintain with all this code sprinkled around everywhere, and
  32. we end up cutting corners and making junky testing apps, and spending more time in the
  33. process.
  34. */
  35. @interface StaticContentTableViewManager : NSObject<UITableViewDelegate, UITableViewDataSource>
  36. /** @property contents
  37. @brief The static contents of the @c UITableView.
  38. @remarks Setting this property will reload the @c UITableView.
  39. */
  40. @property(nonatomic, strong, nullable) StaticContentTableViewContent *contents;
  41. /** @property tableView
  42. @brief A reference to the managed @c UITableView.
  43. @remarks This is needed to automatically reload the table view when the @c contents are changed.
  44. */
  45. @property(nonatomic, weak, nullable) IBOutlet UITableView *tableView;
  46. @end
  47. #pragma mark -
  48. /** @class StaticContentTableViewContent
  49. @brief Represents the contents of a @c UITableView.
  50. */
  51. @interface StaticContentTableViewContent : NSObject
  52. /** @property sections
  53. @brief The sections for the @c UITableView.
  54. */
  55. @property(nonatomic, copy, readonly, nullable) NSArray<StaticContentTableViewSection *> *sections;
  56. /** @fn contentWithSections:
  57. @brief Convenience factory method for creating a new instance of
  58. @c StaticContentTableViewContent.
  59. @param sections The sections for the @c UITableView.
  60. */
  61. + (nullable instancetype)contentWithSections:
  62. (nullable NSArray<StaticContentTableViewSection *> *)sections;
  63. /** @fn init
  64. @brief Please use initWithSections:
  65. */
  66. - (nullable instancetype)init NS_UNAVAILABLE;
  67. /** @fn initWithSections:
  68. @brief Designated initializer.
  69. @param sections The sections in the @c UITableView.
  70. */
  71. - (nullable instancetype)initWithSections:
  72. (nullable NSArray<StaticContentTableViewSection *> *)sections;
  73. @end
  74. #pragma mark -
  75. /** @class StaticContentTableViewSection
  76. @brief Represents a section in a @c UITableView.
  77. @remarks Each section has a title (used for the section title in the @c UITableView) and an
  78. array of cells.
  79. */
  80. @interface StaticContentTableViewSection : NSObject
  81. /** @property title
  82. @brief The title of the section in the @c UITableView.
  83. */
  84. @property(nonatomic, copy, readonly, nullable) NSString *title;
  85. /** @property cells
  86. @brief The cells in this section of the @c UITableView.
  87. */
  88. @property(nonatomic, copy, readonly, nullable) NSArray<StaticContentTableViewCell *> *cells;
  89. /** @fn sectionWithTitle:cells:
  90. @brief Convenience factory method for creating a new instance of
  91. @c StaticContentTableViewSection.
  92. @param title The title of the section in the @c UITableView.
  93. @param cells The cells in this section of the @c UITableView.
  94. */
  95. + (nullable instancetype)sectionWithTitle:(nullable NSString *)title
  96. cells:(nullable NSArray<StaticContentTableViewCell *> *)cells;
  97. /** @fn init
  98. @brief Please use initWithTitle:cells:
  99. */
  100. - (nullable instancetype)init NS_UNAVAILABLE;
  101. /** @fn initWithTitle:cells:
  102. @brief Designated initializer.
  103. @param title The title of the section in the @c UITableView.
  104. @param cells The cells in this section of the @c UITableView.
  105. */
  106. - (nullable instancetype)initWithTitle:(nullable NSString *)title
  107. cells:(nullable NSArray<StaticContentTableViewCell *> *)cells;
  108. @end
  109. #pragma mark -
  110. /** @class StaticContentTableViewCell
  111. @brief Represents a cell in a @c UITableView.
  112. @remarks Cells may be custom cells (in which you specify a @c UITableViewCell to use), or
  113. simple single-label cells which you supply the title text for. It does not make sense to
  114. specify both @c customCell and also @c title, but if a @c customCell is specified, it will
  115. be used instead of the @c title.
  116. */
  117. @interface StaticContentTableViewCell : NSObject
  118. /** @property customCell
  119. @brief The custom @c UITableViewCell to use for this cell.
  120. */
  121. @property(nonatomic, strong, readonly, nullable) UITableViewCell *customCell;
  122. /** @property title
  123. @brief If no custom cell is being used, this is the text of the @c titleLabel of the
  124. @c UITableViewCell.
  125. */
  126. @property(nonatomic, copy, readonly, nullable) NSString *title;
  127. /** @property value
  128. @brief If no custom cell is being used, this is the text of the @c detailTextLabel of the
  129. @c UITableViewCell.
  130. */
  131. @property(nonatomic, copy, readonly, nullable) NSString *value;
  132. /** @property accessibilityIdentifier
  133. @brief The accessibility ID for the corresponding @c UITableViewCell.
  134. */
  135. @property(nonatomic, copy, readonly, nullable) NSString *accessibilityIdentifier;
  136. /** @property action
  137. @brief A block which is executed when the cell is selected.
  138. @remarks Avoid retain cycles. Since these blocked are retained here, and your
  139. @c UIViewController's object graph likely retains this object, you don't want these blocks
  140. to retain your @c UIViewController. The easiest thing is just to create a weak reference to
  141. your @c UIViewController and pass it a message as the only thing the block does.
  142. */
  143. @property(nonatomic, copy, readonly, nullable) StaticContentTableViewCellAction action;
  144. /** @fn cellWithTitle:
  145. @brief Convenience factory method for a new instance of @c StaticContentTableViewCell.
  146. @param title The text of the @c titleLabel of the @c UITableViewCell.
  147. */
  148. + (nullable instancetype)cellWithTitle:(nullable NSString *)title;
  149. /** @fn cellWithTitle:value:
  150. @brief Convenience factory method for a new instance of @c StaticContentTableViewCell.
  151. @param title The text of the @c titleLabel of the @c UITableViewCell.
  152. @param value The text of the @c detailTextLabel of the @c UITableViewCell.
  153. */
  154. + (nullable instancetype)cellWithTitle:(nullable NSString *)title
  155. value:(nullable NSString *)value;
  156. /** @fn cellWithTitle:action:
  157. @brief Convenience factory method for a new instance of @c StaticContentTableViewCell.
  158. @param title The text of the @c titleLabel of the @c UITableViewCell.
  159. @param action A block which is executed when the cell is selected.
  160. */
  161. + (nullable instancetype)cellWithTitle:(nullable NSString *)title
  162. action:(nullable StaticContentTableViewCellAction)action;
  163. /** @fn cellWithTitle:value:action:
  164. @brief Convenience factory method for a new instance of @c StaticContentTableViewCell.
  165. @param title The text of the @c titleLabel of the @c UITableViewCell.
  166. @param value The text of the @c detailTextLabel of the @c UITableViewCell.
  167. @param action A block which is executed when the cell is selected.
  168. */
  169. + (nullable instancetype)cellWithTitle:(nullable NSString *)title
  170. value:(nullable NSString *)value
  171. action:(nullable StaticContentTableViewCellAction)action;
  172. /** @fn cellWithTitle:value:action:accessibilityLabel:
  173. @brief Convenience factory method for a new instance of @c StaticContentTableViewCell.
  174. @param title The text of the @c titleLabel of the @c UITableViewCell.
  175. @param value The text of the @c detailTextLabel of the @c UITableViewCell.
  176. @param action A block which is executed when the cell is selected.
  177. @param accessibilityID The accessibility ID to add to the cell.
  178. */
  179. + (nullable instancetype)cellWithTitle:(nullable NSString *)title
  180. value:(nullable NSString *)value
  181. action:(nullable StaticContentTableViewCellAction)action
  182. accessibilityID:(nullable NSString *)accessibilityID;
  183. /** @fn cellWithCustomCell:
  184. @brief Convenience factory method for a new instance of @c StaticContentTableViewCell.
  185. @param customCell The custom @c UITableViewCell to use for this cell.
  186. */
  187. + (nullable instancetype)cellWithCustomCell:(nullable UITableViewCell *)customCell;
  188. /** @fn cellWithCustomCell:action:
  189. @brief Convenience factory method for a new instance of @c StaticContentTableViewCell.
  190. @param customCell The custom @c UITableViewCell to use for this cell.
  191. @param action A block which is executed when the cell is selected.
  192. */
  193. + (nullable instancetype)cellWithCustomCell:(nullable UITableViewCell *)customCell
  194. action:(nullable StaticContentTableViewCellAction)action;
  195. /** @fn init
  196. @brief Please use initWithCustomCell:title:action:
  197. */
  198. - (nullable instancetype)init NS_UNAVAILABLE;
  199. /** @fn initWithCustomCell:title:action:
  200. @brief Designated initializer.
  201. @param customCell The custom @c UITableViewCell to use for this cell.
  202. @param title If no custom cell is being used, this is the text of the @c titleLabel of the
  203. @c UITableViewCell.
  204. @param action A block which is executed when the cell is selected.
  205. @param accessibilityID The accessibility ID to add to the cell.
  206. */
  207. - (nullable instancetype)initWithCustomCell:(nullable UITableViewCell *)customCell
  208. title:(nullable NSString *)title
  209. value:(nullable NSString *)value
  210. action:(nullable StaticContentTableViewCellAction)action
  211. accessibilityID:(nullable NSString *)accessibilityID
  212. NS_DESIGNATED_INITIALIZER;
  213. @end