130 lines
6.1 KiB
Objective-C
130 lines
6.1 KiB
Objective-C
//
|
||
// MVReportPageElement.h
|
||
//
|
||
// Copyright (c) 2014 Moroverse
|
||
//
|
||
// Permission is hereby granted, free of charge, to any person obtaining a copy
|
||
// of this software and associated documentation files (the "Software"), to deal
|
||
// in the Software without restriction, including without limitation the rights
|
||
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||
// copies of the Software, and to permit persons to whom the Software is
|
||
// furnished to do so, subject to the following conditions:
|
||
//
|
||
// The above copyright notice and this permission notice shall be included in
|
||
// all copies or substantial portions of the Software.
|
||
//
|
||
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
||
// THE SOFTWARE.
|
||
|
||
#import <Foundation/Foundation.h>
|
||
@import CoreGraphics;
|
||
@import UIKit;
|
||
|
||
@class MVReportPageRenderer;
|
||
|
||
/**
|
||
MVReportPageElement is an abstract base class for page elements: objects that lay out custom printable content that can cross page boundaries. Given a page element, the report system can automate the generation of the type of content associated with the page element.
|
||
|
||
Examples of such content could be a web view, a mix of images and text, or a long text document. The MVReport framework provides several concrete subclasses of MVReportPageElement: MVReportSimpleTextFormatter, MVReportMarkupTextFormatter, and MVReportSection (alongside with MVReportSectionElement).
|
||
|
||
You can assign a single page element for a report via the pageElement property of the MVReport instance; or you can specify one or more page elements that are associated with specific pages of a page renderer through the `-addPageElement:startingAtPageAtIndex:` method of MVReportPageRenderer. A page renderer is an instance of a custom subclass of MVReportPageRenderer that draws content for printing.
|
||
|
||
MVReportPageElement publishes an interface that allows you to specify the starting page for a print job and the margins around the printed content; given that information plus the content, a page element computes the number of pages for the report.
|
||
## Subclassing Notes
|
||
You rarely should subclass MVReportPageElement, but in case where you want to add new type of a element to report it will be your only option. Keep in mind that your subclass needs to override all methods metioned bellow.
|
||
## Methods to Override
|
||
When creating custom subclass from MVReportPageElement you should override following methods `-pageCount` to return proper number of pages needed to render the element, `-rectForPageAtIndex:` to return valid rect for rendering for each page requested, and `-drawInRect:forPageAtIndex:` to actually render your element in specified rect.
|
||
*/
|
||
@interface MVReportPageElement : NSObject
|
||
|
||
/**
|
||
@name Laying Out the Content
|
||
*/
|
||
|
||
/**
|
||
The distances the edges of content are inset from the printing rectangle.
|
||
|
||
This property adjusts the margins for content generated by the formatter. The printing rectangle defines the area the printer is capable of printing in; each inset is an inward distance, in points, from a side of the printing area. The top inset is used only on the first page that the element draws. The bottom inset is not used. You can use the UIEdgeInsetsMake macro to create a UIEdgeInsets structure.
|
||
*/
|
||
@property(nonatomic) UIEdgeInsets contentInsets;
|
||
|
||
/**
|
||
The maximum height of the content area.
|
||
*/
|
||
@property(nonatomic) CGFloat maximumContentHeight;
|
||
|
||
/**
|
||
The maximum width of the content area.
|
||
|
||
MVReportPageElement uses this value to determine the maximum width of the content rectangle. It compares the value of this property with the printing rectangle’s width minus the left and right inset values and uses the lower of the two. The default value of this property is the maximum float value.
|
||
*/
|
||
@property(nonatomic) CGFloat maximumContentWidth;
|
||
|
||
/**
|
||
@name Managing Pagination
|
||
*/
|
||
|
||
/**
|
||
The index of the first page that the page element lays out.
|
||
|
||
The value is a zero-based index. You can set the starting page of a page element by assigning an index to this property or by passing one as the second argument of the `-addPageElement:startingAtPageAtIndex:` method of MVReportPageRenderer.
|
||
*/
|
||
@property(nonatomic) NSInteger startPage;
|
||
|
||
/**
|
||
The number of pages to be generated by this element. (read-only)
|
||
|
||
MVReportPageElement calculates this value based on the layout metrics and content.
|
||
*/
|
||
@property(nonatomic, readonly) NSInteger pageCount;
|
||
|
||
/**
|
||
@name Communicating with the Page Renderer
|
||
*/
|
||
|
||
/**
|
||
Returns the page renderer with which the receiver is associated.
|
||
|
||
If the receiving page element was not added to a page renderer—that is, it was assigned to the pageElement property of the MVReport class—the value returned is nil.
|
||
*/
|
||
@property(nonatomic, readonly, assign) MVReportPageRenderer *reportPageRenderer;
|
||
|
||
/**
|
||
Removes the page element from the page renderer.
|
||
|
||
A page element is typically associated with a pages of a MVReportPageRenderer object through the `-addPageElement:startingAtPageAtIndex:` method.
|
||
*/
|
||
- (void)removeFromReportPageRenderer;
|
||
|
||
/**
|
||
@name Drawing the Content
|
||
*/
|
||
|
||
/**
|
||
Draws the portion of a page element's content that goes in the given area for the specified page
|
||
|
||
@param rect The area in which to draw the content.
|
||
@param pageIndex The number of the page of content to draw.
|
||
|
||
This method is called by the default implementation of `-drawPageElement:forPageAtIndex:` of the MVReportPageRenderer class for each page element associated with a page.
|
||
*/
|
||
- (void)drawInRect:(CGRect)rect forPageAtIndex:(NSInteger)pageIndex;
|
||
|
||
/**
|
||
Returns the area enclosing a specified page of content.
|
||
|
||
@param pageIndex The index number of a page.
|
||
|
||
@return A rectangle enclosing the content area for page pageIndex.
|
||
|
||
Returns CGRectZero if the page element draws no content on the specified page.
|
||
*/
|
||
- (CGRect)rectForPageAtIndex:(NSInteger)pageIndex;
|
||
|
||
@end
|