//
//  CustomXmliOSApi.h
//  CustomXmliOSApi
//
//  Created by sviluppo on 24/03/14.
//  Copyright (c) 2014 CUSTOM. All rights reserved.
//

#import <Foundation/Foundation.h>
#import <CoreGraphics/CoreGraphics.h>
#import <UIKit/UIKit.h>
#import "CustomiOSApi.h"


/**
 \mainpage CustomXmliOSApi Documentation
 
 <B>Document Overview</B><BR>
 This document details about CUSTOM XML iOS API. And also explains how to use
 this API for iOS application development for CUSTOM printers.
 
 <B>About Custom Engineering Xml iOS API</B><BR>
 This API provides functions to customize(on the fly) and to print xml projects created with CustomXml Editor
 It includes below functions to manage the project.
 - Open Xml project
 - Set variable fields
 - Get variable fields
 - Get a preview image of the project
 - Print project

 */



/// <summary>
/// Factory class to open a Custom Xml Layout project and print it
/// </summary>
@interface CustomXmliOSApi : NSObject

/// <summary>
/// Returns current library API version
/// </summary>
/// <returns>current API version</returns>
-(NSString *)GetAPIVersion;


/// <summary>
/// Set the name of the xml project file and create the xml project parser. \n 
/// To be done as the FIRST STEP, in order to load the project inside the library. 
/// \n Notes: \n
/// This is the name of the project file created with CustomPowerTool (CPT) Editor (it has .xml extension) \n
/// In fact, you must initialize CPT library with the project file that you want to print. \n       
/// In the same location it is necessary to find "images" and "fonts" directories, as created by CPT Editor. \n
/// </summary>

/// <param name="filepath">Absoulute file path of the xml project file</param>
/// <param name="error">Error pointer</param>
/// <returns>0 in case of success, otherwise -1</returns>
-(int)SetXmlFilePath:(NSString *)filepath error:(NSError **)error;

/// <summary>
/// Set the path of the zipped xml project (to be done as FIRST STEP),
/// unzip the project inside the destination folder in Document and create the xml project parser. \n
/// This function call is alternative to SetXmlFilePath() as it creates the xml project parser.
/// </summary>
/// <param name="zipfilepath">Absolute file path of the zipped xml project </param>
/// <param name="destinationDocumentFolder">Name of the folder (inside Document) to be used to unzip the project</param>
/// <param name="deleteOnDealloc">Delete destination folder when deallocating the object</param>
/// <param name="error">Error pointer</param>
/// <returns>0 in case of success, otherwise -1</returns>
-(int)SetXmlZipFilePath:(NSString *)zipfilepath :(NSString *)destinationDocumentFolder :(BOOL)deleteOnDealloc error:(NSError **)error;


/// <summary>
/// Set the value of the element specified by tag (format Id.Property) \n 
/// In the xml file identify an element with the specified tag and overwrite the value with the supplied one.
/// \n Notes: \n
/// The xml project file contains the description of the layout to print in the form of xml nodes. \n
/// Each node is identified by an Id, and has many properties. \n
/// You can change the value of a property, and the document will be printed with this new value. \n        
/// </summary>
/// <remarks> 
/// Example: \n
/// This is a part of the xml project file describing a textbox field: \n
/// <CustomItem class="text" id="TextBox0"> \n
///.... \n
/// <text>original string</text> \n
/// <fontname>Arial</fontname> \n
/// <fontsize>8</fontsize> \n
/// ..... \n
/// </CustomItem> \n
/// \n
/// Use: [api SetXmlObjectTag:@"TextBox0.text" :@"new string" error:&error]; \n
/// In the printed document, the TextBox0 field will be printed with "new string" instead of "original string".
/// </remarks> 
/// <param name="tag">Xml Tag (in the form Id.Property) to identify an element</param>
/// <param name="value">Value assigned to the element identified by tag</param>
/// <param name="error">Error pointer</param>
/// <returns>0 in case of success, otherwise -1</returns>
-(int)SetXmlObjectTag:(NSString *)tag :(NSString *)value error:(NSError **)error;


/// <summary>
/// Get the value of the element specified by tag (format Id.Property). \n
/// In the xml file identify an element with the specified tag and return its value.
/// \n Notes: \n
/// This is the Get function, while SetXmlObjectTag() is the equivalent Set function.
/// The xml project file contains the description of the layout to print in the form of xml nodes. \n
/// Each node is identified by an Id, and has many properties. \n
/// You can retrieve (get) the value of a property. \n        
/// </summary>
/// <remarks> 
/// Example: \n
/// This is a part of the xml project file describing a textbox field: \n
/// <CustomItem class="text" id="TextBox0"> \n
///.... \n
/// <text>original string</text> \n
/// <fontname>Arial</fontname> \n
/// <fontsize>8</fontsize> \n
/// ..... \n
/// </CustomItem> \n
/// \n
/// Use: [api GetXmlObjectTag:@"TextBox0.text" error:&error]; \n
/// it will return "original string".
/// </remarks> 
/// </summary>
/// <param name="tag">Xml Tag (in the form Id.Property) to identify an element</param>
/// <param name="error">Error pointer</param>
/// <returns>Value of the element identified by tag or nil if there is no match</returns>
-(NSString *)GetXmlObjectTag:(NSString *)tag error:(NSError **)error;



/// <summary>
/// Create a list of tag/value using the supplied xml parameter file and apply it to the xml project file (see SetXmlObjectTag() for tag/value meaning). \n
/// The parameter file must be in the format produced by CPT Editor
/// \n Notes: \n
/// The xml parameter file is generated by CPT Editor, and has extension ".param.xml". \n
/// The xml parameter file contains the description of the "variable" part of the layout to print, in the form of xml nodes. \n
/// This file can be interpreted as a subset of the xml project file, containing only the "variable" properties. \n
/// Each node is identified by an Id and can have one or more properties. \n
/// It can be modifed manually by the user.
/// </summary>
/// <remarks> 
/// Example: \n
/// This is a part of a xml parameter file: \n
/// .... \n
/// <CustomParam class="text" id="TextBox1"> \n
/// <text>new string 1</text> \n
/// </CustomParam> \n        
/// <CustomParam class="text" id="TextBox2"> \n
/// <text>new string 2</text> \n
/// </CustomParam> \n
/// ..... \n
/// A call to SetXmlObjectFromParamFile() produces the same result of multiple calls to SetXmlObjectTag() \n
/// In this example, it is equivalent to: \n
/// [api SetXmlObjectTag:@"TextBox1.text" :@"new string 1" error:&error]; \n
/// [api SetXmlObjectTag:@"TextBox2.text" :@"new string 2" error:&error]; \n
/// </remarks> 
/// <param name="xmlParameterFileName">Absolute file path of xml parameter file or value: nil</param>
/// <param name="error">Error pointer</param>
/// <returns>0 in case of success, otherwise -1</returns>
-(int)SetXmlObjectFromParamFile:(NSString *)xmlParameterFileName error:(NSError **)error;



/// <summary>
/// Get the list of tag/value from the supplied xml parameter file. \n
/// The parameter file must be in the format produced by CPT Editor
/// \n Notes: \n
/// The xml parameter file is generated by CPT Editor, and has extension ".param.xml". \n
/// For a description of the xml parameter file see SetXmlObjectFromParamFile()
/// This function parses the xml parameter file and generates a list of objects, with tag and value.
/// <remarks> 
/// Example: \n
/// This is a part of a xml parameter file: \n
/// .... \n
/// <CustomParam class="text" id="TextBox1"> \n
/// <text>new string 1</text> \n
/// </CustomParam> \n        
/// <CustomParam class="text" id="TextBox2"> \n
/// <text>new string 2</text> \n
/// </CustomParam> \n
/// ..... \n
/// A call to GetXmlObjectFromParamFile() will produce a list of CustomXmlDictionaryItem objects like this: \n        
/// { Tag:"TextBox1.text", Value:"new string 1" } \n
/// { Tag:"TextBox2.text", Value:"new string 2" } \n
/// </remarks>  
/// <param name="xmlParameterFileName">Absolute file path of xml parameter file or value: nil</param>
/// <param name="error">Error pointer</param>
/// <returns>List of CustomXmlDictionaryItem, each representing a tag/value pair</returns>
-(NSArray *)GetXmlTagValListFromParamFile:(NSString *)xmlParameterFileName error:(NSError **)error;


/// <summary>
/// Get a preview image
/// \n Notes: \n
/// This function is used to perform the rendering of the xml project and to return a preview image. \n
/// Prerequiste is loding the project (using SetXmlFilePath() or SetXmlZipFilePath())   
/// </summary>
/// <param name="error">Error pointer</param>
/// <returns>A preview image representing the xml project</returns>
-(UIImage *)PreviewXml:(NSError **)error;


/// <summary>
/// Parse Xml project file performing a syntax/correctness check
/// \n Notes: \n
/// After a call to SetXmlFilePath() or SetXmlZipFilePath(), the project is loaded inside the library. \n
/// With this function call it is possible to verify if the syntax of the project is correct: in case of syntax error, a message is returned.
/// </summary>
/// <param name="error">Error pointer</param>
/// <returns>>Error information string in case of errors or an empty string in case of success</returns>
-(NSString *)GetXmlParsingErrors:(NSError **)error;

/// <summary>
/// Enable link feature (internal use only, this may slow down xml parsing and printing)
/// </summary>
/// <param name="error">Error pointer</param>
/// <returns>0 in case of success, otherwise -1</returns>
-(int)SetXmlLinkFeatureEnable:(NSError **)error;

/// <summary>
/// Superseded Function ( replaced by SetXmlObjectTag)
/// </summary>
-(int)SetXmlTag:(NSString *)tag :(NSString*)value error:(NSError **)error;

/// <summary>
/// Set the value of the element specified by "link" tag (internal use only)
/// </summary>
/// <param name="tag">Xml Tag (in the form ID.LINK) to identify an element</param>
/// <param name="value">Value assigned to the element identified by tag</param>
/// <param name="error">Error pointer</param>
/// <returns>0 in case of success, otherwise -1</returns>
-(int)SetXmlObjectLink:(NSString *)tag :(NSString *)value error:(NSError **)error;

/// <summary>
/// Get the value of the element specified by "link" tag (internal use only)
/// </summary>
/// <param name="tag">Xml Tag (in the form ID.LINK) to identify an element</param>
/// <param name="error">Error pointer</param>
/// <returns>Value of the element identified by tag or nil if there is no match</returns>
-(NSString *)GetXmlObjectLink:(NSString *)tag error:(NSError **)error;

/// <summary>
/// Print xml project file
/// \n Notes: \n
/// This function is used to perform the rendering of the xml project and to send it to the printer. \n
/// Prerequistes are loding the project (using SetXmlFilePath() or SetXmlZipFilePath()) and selecting the printer (using CustomiOSApi library)
/// </summary>
/// <param name="prnDevice">Printing device, as returned by CustomiOSApi library</param>
/// <param name="error">Error pointer</param>
/// <returns>0 in case of success, otherwise -1</returns>
-(int)PrintXml:(CustomPrinter *)prnDevice  error:(NSError **)error;

/// <summary>
/// Print xml project file
/// \n Notes: \n
/// This function is used to perform the rendering of the xml project and to send it to the printer. \n
/// Prerequistes are loding the project (using SetXmlFilePath() or SetXmlZipFilePath()) and selecting the printer (using CustomiOSApi library)
/// </summary>
/// <param name="prnDevice">Printing device, as returned by CustomiOSApi library</param>
/// <param name="leftAlign">Left alignment behavior, see PrintImage in CustomiOSApi library documentation</param>
/// <param name="widthOption">Scaling options, see PrintImage in CustomAndroidAPI library documentation</param>
/// <param name="imgWidth">Printed image width in pixel/dots in case of "Scale to Width" option selected, see PrintImage in CustomiOSApi library documentation</param>
/// <param name="error">Error pointer</param>
/// <returns>0 in case of success, otherwise -1</returns>
-(int)PrintXml:(CustomPrinter *)prnDevice :(NSInteger)leftAlign :(enum ImageScale)widthOption :(NSInteger)imgWidth error:(NSError **)error;

/// <summary>
/// Get bold and italic properties for the font identified by fontname.
/// </summary>
/// <param name="fontname">Font family name</param>
/// <param name="isBoldAvailable">Pointer to a bool variable to indicate if bold is available: false[bold not available] true[bold available] (output value)</param>
/// <param name="isItalicAvailable">Pointer to a bool variable to indicate if italic is available: false[italic not available] true[italic available] (output value)</param>
/// <param name="isBoldItalicAvailable">Pointer to a bool variable to indicate if bold-italic is available: false[bold-italic not available] true[bold-italic available] (output value)</param>
/// <param name="error">Error pointer</param>
/// <returns>0 in case of success, otherwise -1</returns>
-(int)GetFontProperty:(NSString *)fontname :(BOOL *)isBoldAvailable :(BOOL *)isItalicAvailable :(BOOL *)isBoldItalicAvailable error:(NSError **)error;


@end
