// // CSTheme.h // Centralized class for native XScheme support while bridging existing services. // Uses modernized services and support of new technologies to support easy // creation and reading of both Aqua backups and deployment style themes. // Copyright (c) 2003 Conundrum Software. All rights reserved. // /*! @header CSTheme @discussion Centralized class for native XScheme support while bridging existing services. Uses modernized services and support of new technologies to support easy creation and reading of both Aqua backups and deployment style themes. */ #import #import "RAZipper.h" #import "CSCheckSum.h" #import "CSTextReader.h" @interface CSTheme : NSObject { int theCurrentType; BOOL runOptimized; NSMutableDictionary *theFiles; NSMutableDictionary *theLinkedFiles; NSMutableDictionary *theUncompressedFiles; NSMutableDictionary *theThemeNames; NSString *theCollectionName; } -(void)removeLinkForVariation:(NSString *)theVariationName forDestination:(NSString *)theDestination; -(NSString *)theName; +(id)theme; -(void)changeNameOfVariation:(NSString *)variationName toName:(NSString*)newName; -(NSArray *)files; -(void)setName:(NSString *)theName; - (id)CSGetMMXPath:(id)line; /*! * @method fileHasHash:theThemeFile * @abstract Tests to see if the specified file has a hash present * @discussion This method will return true if the specified file within the theme has a hash set. */ -(BOOL)fileHasHash:(NSString *)theThemeFile; /*! * @method themeWithDLTAFromFile:thePath theTags:tags * @abstract Returns a instance of a theme from the DLTA specified in thePath. * @discussion This method returns an autoreleased instance of a DLTA CSTheme. Pass the tags you want the parser to use via an NSArray passed using theTags. */ +(id)themeWithDLTAFromFile:(NSString *)thePath theTags:(NSArray *)tags; /*! * @method themeWithXMLBundle:thePath forLanguage:theLanguage * @abstract Returns a instance of a theme from the MetaMorphX theme specified in thePath. * @discussion This method returns an autoreleased instance of a MetaMorphX CSTheme. Pass the language you want the parser to use using theLanguage. */ +(id)themeWithXMLBundle:(NSString *)thePath forLanguage:(NSString *)theLanguage; /*! * @method themeWithThemeFromFile:thePath * @abstract Returns a instance of a theme from the theme specified in thePath. * @discussion This method returns an autoreleased instance of a CSTheme (XScheme). */ +(id)themeWithThemeFromFile:(NSString *)thePath; //Declaring the initialization methods /*! * @method init * @abstract Initializes a new CSTheme * @discussion Initializes a new, non-Aqua backup CSTheme. */ -(id)init; /*! * @method initWithAquaTheme * @abstract Initializes a new Aqua theme backup * @discussion Use this method to initialize a new CSTheme that is built to be an Aqua restore theme. Aqua restore themes should not be provided to the end user. Only use this method when creating a restore theme as part of a theme switch. Files are brough in as linked. */ -(id)initWithNewAquaTheme; /*! * @method initWithDLTAFromFile:theFile theTags:tags forIndex:theIndex * @abstract Initializes a new CSTheme from a DLTA * @discussion Import a theme using a DLTA bridge. You must specify an array of OS tags (e.g. 10.2) for the method to read the theme. This method is compatible with ThemeStep themes that use the tag and will bridge over to modern ThemeStep services if your software uses any sort of resource parser. This function returns nil if the specified index cannot be found within the theme. * @param theFile A string specifying the DLTA bundle to be read * @param theTags An array of tags for the bridge to use when reading the theme. Use tags for each OS you want support to be included for. * @param theIndex The index number of the variation you wish to use within the DLTA. */ -(id)initWithDLTAFromFile:(NSString *)thePath theTags:(NSArray *)tags; /*! * @method initWithXMLBundle:thePath forLanguage:theLanguage * @abstract Initializes a new Aqua theme backup * @discussion Imports a theme using a Metamorphx style theme bundle with an info.plist file. This method will ignore any OS information. The developer should check using their own code in order to check for any prospective issues with the OS tag. Files are brough in as linked. * @param thePath A string specifying the XML bundle to be read * @param theLanguage A string specifying the language to be used to read from the XML property list. */ -(id)initWithXMLBundle:(NSString *)thePath forLanguage:(NSString *)theLanguage; /*! * @method currentThemeType * @abstract Returns the current style of the theme * @discussion Returns what style of theme this object is currently using (CSDeploymentTheme or CSBackupStyleTheme). Use this method to check for Aqua backups that may be hiding. CSBackupStyleTheme types should be handled carefully, as you should not run into them under normal conditions. */ -(int)currentThemeType; -(void)CSNicelySetupTheme; + (id)getFirstDLTAArgument:(id)line; + (id)getSecondDLTAArgument:(id)line; /*! * @method addFileFromFile:thePath fileName:theName * @abstract Adds a file to the CSTheme. * @discussion This method will take the specified file, compress it, and then add it to the CSTheme. * @param thePath The location the file is currently located at as a string. * @param fileName The file name that the file should be refered to within the CSObject */ -(void)addFileFromFile:(NSString *)thePath fileName:(NSString *)theName; /*! * @method addFileFromFile:thePath fileName:theName withHashForFile:hashFile * @abstract Adds a file to the theme with hash support * @discussion This method is identical to addFileFromFile:theLocation fileName:theName but with one more argument. * @param hashFile The path to a file to be used as a checksum for the file being added to the theme. The generation of a checksum, or hash, allows you to track the changing of files on a users machine by generating a key from the current file and comparing that against the a later version of the file at a later point. */ -(void)addFileFromFile:(NSString *)thePath fileName:(NSString *)theName withHashForFile:(NSString *)hashFile; /*! * @method addFileFromData:theData fileName:theName * @abstract Adds a file from data to the CSTheme. * @discussion This method will take the passed data, compress it, and then add it to the CSTheme. * @param theData The data of the file you wish to add. * @param fileName The file name that the data should be refered to within the CSObject */ -(void)addFileFromData:(NSData *)theData fileName:(NSString *)theName; /*! * @method writeAsThemeToPath:thePath atomically:atomYN * @abstract Writes a CSTheme to an XScheme file * @discussion Allows a CSTheme to be saved to an XScheme. * @param thePath The path to save the XScheme to * @param fileName Pass YES to write the XScheme atomically, and NO to not. */ -(void)writeAsThemeToPath:(NSString *)thePath atomically:(BOOL)atomYN; /*! * @method initWithContentsOfFile:thePath * @abstract Initializes the reciever with the contents of an XScheme file * @discussion This function will allow you to work with XSchemes as CSObjects * @param theFile The location of an XScheme to initialize the reciever with */ -(id)initWithContentsOfFile:(NSString *)theFile; /*! * @method variations * @abstract Returns the theme variations present in a CSTheme * @discussion This method returns the theme variations present in the CSTheme as an array. */ -(NSArray *)variations; /*! * @method addVariationWithName:theName * @abstract Creates a new theme variation and adds it to the reciever * @discussion Use this method to create a new theme variation within the CSTheme to hold information such as file linkings, preview pictures, theme descriptions, etc. * @param theName The name to assign the variation */ -(void)addVariationWithName:(NSString *)theName; /*! * @method dataForFile:theName * @abstract Returns the data for a file in the CSTheme * @discussion Use this method to retrieve the data of a file previously stored in the CSTheme * @param theName The name assigned to the file to be retrieved */ -(NSData *)dataForFile:(NSString *)theName; /*! * @method removeVariationWithName:theName * @abstract Removes a variation from a CSTheme * @discussion This method removes a theme variation, and all associated links, names, descriptions, and preview pictures from the CSTheme. * @param theName The name assigned to the theme to be deleted */ -(void)removeVariationWithName:(NSString *)theName; /*! * @method addPreviewFromFile:thePath forVariation:theVariationName * @abstract Adds a preview to a theme variation from a file * @discussion Use this method to assign a theme preview from a tiff formatted file to a theme variation. Theme changer programs use the preview picture to display a preview of the theme for the user on screen. The picture will be compressed to save space. * @param thePath The path to the file to be used as a preview. * @param theVariationName The variation to add the theme preview picture to. */ -(void)addPreviewFromFile:(NSString *)thePath forVariation:(NSString *)theVariationName; /*! * @method addPreviewFromData:theData forVariation:theVariationName * @abstract Adds a preview to a theme variation from data * @discussion Use this method to assign a theme preview from tiff formatted data to a theme variation. Theme changer programs use the preview picture to display a preview of the theme for the user on screen. The picture will be compressed to save space. * @param theData The data containing the picture. * @param theVariationName The variation to add the theme preview picture to. */ -(void)addPreviewFromData:(NSData *)theData forVariation:(NSString *)theVariationName; /*! * @method setVariationDescriptionWithString:theDescription forVariation:theVariationName * @abstract Sets the description of a theme variation * @discussion This method sets the description of a theme variation to theDescription * @param theDescription A string containing the description to set the variation equal to. * @param theVariationName The variation to set the description of. */ -(void)setVariationDescriptionWithString:(NSString *)theDescription forVariation:(NSString *)theVariationName; /*! * @method descriptionForVariation:theVariationName * @abstract Returns the description of a theme variation * @discussion Use this method to return the description of a variation as a string. * @param theVariationName The variation to pull the description from. */ -(NSString *)descriptionForVariation:(NSString *)theVariationName; /*! * @method dictionaryForVariation:theVariationName * @abstract Returns a theme variation as a dictionary * @discussion You can use this method to copy a variation from one CSTheme to another. addVariationFromDictionary is not yet implemented. * @param theVariationName The variation to pull the dictionary from. */ -(NSDictionary *)dictionaryForVariation:(NSString *)theVariationName; /*! * @method addLinkForVariation:theVariationName forFile:fileName forDestination:theDestination * @abstract Adds a link to the specified variation. * @discussion Use this method to add a file link to a theme variation using a file already added to the CSTheme. * @param theVariationName The variation to add the link to. * @param fileName The file already present in the CSTheme to use. * @param theDestination The destination to copy the file to on install. */ -(void)addLinkForVariation:(NSString *)theVariationName forFile:(NSString *)fileName forDestination:(NSString *)theDestination; /*! * @method setHashForThemeFile:theThemeFile forFile:theFile * @abstract Changes the hash (or creates one) for a file added to a CSTheme * @discussion This method enables checksum support for file theThemeFile that is present in the CSTheme. * @param theThemeFile The file present within the CSTheme to add the hash to/replace. * @param theFile The file on the local computer to generate a checksum from. */ -(void)setHashForThemeFile:(NSString *)theThemeFile forFile:(NSString *)theFile; /*! * @method compareHashForThemeFile:theThemeFile forFile:thePath * @abstract Compares the hash of one file in the theme to one on the local drive * @discussion Use this method to compare the checksum of a file in the theme to a theme on the local drive to track changes on the computer. * @param theThemeFile The file present within the CSTheme to read the hash from. * @param theFile The file on the local computer to compare the hash to. */ -(BOOL)compareHashForThemeFile:(NSString *)theThemeFile forFile:(NSString *)thePath; + (id)getFirstDLTAArgument:(id)line; + (id)getDynamicLink:(id)link; + (id)getSecondDLTAArgument:(id)line; //just defining which theme type is which -(NSData *)previewForVariation:(NSString *)theVariationName; /*! * @method compressFiles * @abstract Compresses all non-compressed files within the CSTheme. * @discussion This method will be executed automatically when doing any file I/O operations.. */ -(void)compressFiles; /*! * @method setHashForThemeFile:theThemeFile forData:thePath * @abstract Sets the hash of a file present in the CSTheme. * @discussion This method can be used to change the hash of a file after it has already been added to a CSTheme. The hash is generated by NSData. * @param theThemeFile The file to change the hash of. * @param forData The data of a file to generate the hash from. */ -(void)setHashForThemeFile:(NSString *)theThemeFile forData:(NSData *)thePath; /*! * @method addFileFromFile:thePath fileName:theName withHashForData:hashFile * @abstract Adds a file to the theme with hash support * @discussion This method is identical to addFileFromFile:theLocation fileName:theName but with one more argument. * @param hashFile The data of a file to be used as a checksum for the file being added to the theme. The generation of a checksum, or hash, allows you to track the changing of files on a users machine by generating a key from the current file and comparing that against the a later version of the file at a later point. */ -(void)addFileFromFile:(NSString *)thePath fileName:(NSString *)theName withHashForData:(NSData *)hashFile; /*! * @method allDestinationsForVariation:theVariationName * @abstract Returns an NSArray containing all the destination locations in theVariationName. * @discussion Both allDestinationsForVariation and allFilesForVariation return the same order, and have identical index numbers. * @param theVariationName The name of the variation to return all the destinations from. */ -(NSArray *)allDestinationsForVariation:(NSString *)theVariationName; /*! * @method allFilesForVariation:theVariationName * @abstract Returns an NSArray containing all the destination locations in theVariationName. * @discussion Both allDestinationsForVariation and allFilesForVariation return the same order, and have identical index numbers. * @param theVariationName The name of the variation to return all the files from. */ -(NSArray *)allFilesForVariation:(NSString *)theVariationName; /*! * @method setOSTag:theTag forVariation:theVariation * @abstract Sets the OS tag of the passed variation name * @discussion Use this method to set the OS tag of a variation. This method is most useful for DLTA imports because DLTA imports do not contain OS tags. * @param theTag The tag you wish to set the variation to use as an NSString * @param theVariation The variation to set the OS tag of. */ -(void)setOSTag:(NSString *)theTag forVariation:(NSString *)theVariation; /*! * @method getOSTagForVariation:theVariation * @abstract Gets the OS tag of the passed variation name * @discussion Use this method to get the OS tag of a variation. * @param theVariation The variation to get the OS tag of. */ -(NSString *)getOSTagForVariation:(NSString *)theVariation; - (BOOL)writeToFile:(NSString *)path atomically:(BOOL)flag; /*! @typedef CSTheme @discussion This is a list of various constants used. @constant CSResourceStyle Storage resource by resource. To be implemented in 2.0. @constant CSDeploymentStyle A deployment style theme meant for the end user. @constant CSBackupStyleTheme A aqua backup style theme meant for backing up the current setup. @constant CSThemeKitVersion Contains the current version of ThemeKit. Developers should always check this against the build used for development. */ /*! * @method compressLinkedFiles * @abstract Compresses all linked file in the CSTheme * @discussion Use this method to prepare the files in a CSTheme for advanced operations. Normally automatically run when needed. */ -(void)compressLinkedFiles; -(void)runOptimized:(BOOL)ryn; -(void)removeFileWithName:(NSString *)theName; #define CSDeploymentStyleTheme 1 #define CSBackupStyleTheme 2 #define CSResourceStyleTheme 2 #define CSThemeKitVersion 4 @end