text: /*
   Copyright (c) 2015, Apple Inc. All rights reserved.
   Copyright (c) 2015, Alex Basson. All rights reserved.
  
   Redistribution and use in source and binary forms, with or without modification,
   are permitted provided that the following conditions are met:
   
   1.  Redistributions of source code must retain the above copyright notice, this
   list of conditions and the following disclaimer.
   
   2.  Redistributions in binary form must reproduce the above copyright notice,
   this list of conditions and the following disclaimer in the documentation and/or
   other materials provided with the distribution.
   
   3.  Neither the name of the copyright holder(s) nor the names of any contributors
   may be used to endorse or promote products derived from this software without
   specific prior written permission. No license is granted to the trademarks of
   the copyright holders even if such marks are included in this software.
   
   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
   AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
   IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
   ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
   FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
   DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
   SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
   CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
   OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
   */
  
  
  #import <ResearchKit/ResearchKit.h>
  #import <ResearchKit/ORKConsentSignature.h>
  
  @class ORKHTMLPDFWriter;
  @class ORKConsentSectionFormatter;
  @class ORKConsentSignatureFormatter;
  @class ORKConsentSection;
  
  NS_ASSUME_NONNULL_BEGIN
  
  /**
   The `ORKConsentDocument` class represents the content of an informed consent
   document, which is a document that's used to obtain informed consent from participants
   in a medical or other research study. The ResearchKit framework uses an `ORKConsentDocument` object
   to provide content for visual consent steps (`ORKVisualConsentStep`) and for consent review steps (`ORKConsentReviewStep`).
   
   The `sections` of an `ORKConsentDocument` object are instances of `ORKConsentSection`.
   When an `ORKConsentDocument` object is attached to an visual consent step, these
   sections provide the content for the visual consent screens, and for the
   Learn More pages that are accessible from them. When attached to an consent review step,
   the sections can provide the content for the consent document to
   be reviewed.
   
   If the consent document is simple, each section may be able to map to a visual consent screen. And in some cases, the formatting of the consent document may
   be sufficiently simple that it can be presented using only section headers and
   simple formatting. If your consent document uses simple formatting, you might be able to generate a document to sign by specifying the sections and the signatures.
   In a case like this, you don't need to provide a value for the `htmlReviewContent` property,
   and when the consent review step is completed, the signatures can be
   placed into a copy of the document and a PDF can be generated.
   
   In more complex cases, the visual consent sections may bear little
   relation to the formal consent document. In a situation like this, place the formal consent
   document content in the `htmlReviewContent` property. Doing this overrides all content that would otherwise be generated from the consent
   sections.
   
   The document should be in the user's language, and all the content of
   the document should be appropriately localized.
   */
  ORK_CLASS_AVAILABLE
  @interface ORKConsentDocument : NSObject <NSSecureCoding, NSCopying>
  
  /// @name Properties
  
  /**
   The document's title in a localized string.
   
   The title appears only in the generated PDF for review; it is not used in the
   visual consent process.
    */
  @property (nonatomic, copy, nullable) NSString *title;
  
  /// @name Visual consent sections
  
  /**
   The sections to be in printed in the PDF file and or presented in the
   visual consent sequence.
   
   All sections appear in the animated process, except for those sections of the
   type `ORKConsentSectionTypeOnlyInDocument`.
   
   If the `htmlReviewContent` property is not set, this content is also used to
   populate the document for review in the consent review step.
   
   The PDF file contains all sections.
   */
  @property (nonatomic, copy, nullable) NSArray<ORKConsentSection *> *sections;
  
  /// @name Signatures for consent review
  
  /**
   The title to be rendered on the signature page of the generated PDF in a localized string.
   
   The title is ignored for visual consent. The title is also ignored if you supply a value for the `htmlReviewContent` property.
    */
  @property (nonatomic, copy, nullable) NSString *signaturePageTitle;
  
  /**
   The content to be rendered below the title on the signature page of the generated PDF in a localized string.
   
   The content is ignored for visual consent. The content is also ignored if you supply a value for the `htmlReviewContent` property.
    */
  @property (nonatomic, copy, nullable) NSString *signaturePageContent;
  
  /**
   The set of signatures that are required or prepopulated in the document.
   
   To add a signature to the document after consent review, the `signatures` array
   needs to be modified to incorporate the new signature content prior to PDF
   generation. For more information, see `[ORKConsentSignatureResult applyToDocument:]`.
   */
  @property (nonatomic, copy, nullable) NSArray<ORKConsentSignature *> *signatures;
  
  /**
   Adds a signature to the array of signatures.
   
   @param signature    The signature object to add to the document.
   */
  - (void)addSignature:(ORKConsentSignature *)signature;
  
  /// @name Alternative content provision
  
  /**
   Override HTML content for review.
   
   Typically, the review content is generated from the values of the `sections` and `signatures`
   properties.
   
   When this property is set, the review content is reproduced exactly as provided in the property
   in the consent review step, and the `sections` and `signatures` properties
   are ignored.
   */
  @property (nonatomic, copy, nullable) NSString *htmlReviewContent;
  
  /// @name PDF generation
  
  /**
   Initializer with ORKHTMLPDFWriter parameter. Allows for injecting mock dependency for the
   purposes of isolated unit testing.
  
   @param writer              The instance of the ORKHTMLPDFWriter upon which the class depends.
   @param sectionFormatter    An instance of ORKConsentSectionFormatter
   @param signatureFormatter  An instance of ORKConsentSignatureFormatter
   */
  - (instancetype)initWithHTMLPDFWriter:(ORKHTMLPDFWriter *)writer
                consentSectionFormatter:(ORKConsentSectionFormatter *)sectionFormatter
              consentSignatureFormatter:(ORKConsentSignatureFormatter *)signatureFormatter;
  
  /**
   Writes the document's content into a PDF file.
   
   The PDF is generated in a form suitable for printing. This is done asynchronously,
   so the PDF data is returned through a completion block.
   
   @param handler     The handler block for generated PDF data. When successful, the returned
                      data represents a complete PDF document that represents the consent.
   */
  - (void)makePDFWithCompletionHandler:(void (^)(NSData * _Nullable PDFData, NSError * _Nullable error))handler;
  
  @end
  
  NS_ASSUME_NONNULL_END
  