CSTheme.h



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.

Methods

addFileFromData:theData

Abstract: Adds a file from data to the CSTheme.
- (void)addFileFromData:(NSData *)theData fileName:(NSString *)theName; 

This method will take the passed data, compress it, and then add it to the CSTheme.

Parameters

NameDescription
theDataThe data of the file you wish to add.
fileNameThe file name that the data should be refered to within the CSObject

addFileFromFile:thePath

Abstract: Adds a file to the theme with hash support
- (void)addFileFromFile:(NSString *)thePath fileName:(NSString *)theName withHashForFile:(NSString *)hashFile; 

This method is identical to addFileFromFile:theLocation fileName:theName but with one more argument.

Parameters

NameDescription
hashFileThe 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.

addFileFromFile:thePath

Abstract: Adds a file to the CSTheme.
- (void)addFileFromFile:(NSString *)thePath fileName:(NSString *)theName; 

This method will take the specified file, compress it, and then add it to the CSTheme.

Parameters

NameDescription
thePathThe location the file is currently located at as a string.
fileNameThe file name that the file should be refered to within the CSObject

addFileFromFile:thePath

Abstract: Adds a file to the theme with hash support
- (void)addFileFromFile:(NSString *)thePath fileName:(NSString *)theName withHashForData:(NSData *)hashFile; 

This method is identical to addFileFromFile:theLocation fileName:theName but with one more argument.

Parameters

NameDescription
hashFileThe 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.

addLinkForVariation:theVariationName

Abstract: Adds a link to the specified variation.
- (void)addLinkForVariation:(NSString *)theVariationName forFile:(NSString *)fileName forDestination:(NSString *)theDestination; 

Use this method to add a file link to a theme variation using a file already added to the CSTheme.

Parameters

NameDescription
theVariationNameThe variation to add the link to.
fileNameThe file already present in the CSTheme to use.
theDestinationThe destination to copy the file to on install.

addPreviewFromData:theData

Abstract: Adds a preview to a theme variation from data
- (void)addPreviewFromData:(NSData *)theData forVariation:(NSString *)theVariationName; 

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.

Parameters

NameDescription
theDataThe data containing the picture.
theVariationNameThe variation to add the theme preview picture to.

addPreviewFromFile:thePath

Abstract: Adds a preview to a theme variation from a file
- (void)addPreviewFromFile:(NSString *)thePath forVariation:(NSString *)theVariationName; 

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.

Parameters

NameDescription
thePathThe path to the file to be used as a preview.
theVariationNameThe variation to add the theme preview picture to.

addVariationWithName:theName

Abstract: Creates a new theme variation and adds it to the reciever
- (void)addVariationWithName:(NSString *)theName; 

Use this method to create a new theme variation within the CSTheme to hold information such as file linkings, preview pictures, theme descriptions, etc.

Parameters

NameDescription
theNameThe name to assign the variation

allDestinationsForVariation:theVariationName

Abstract: Returns an NSArray containing all the destination locations in theVariationName.
- (NSArray *)allDestinationsForVariation:(NSString *)theVariationName; 

Both allDestinationsForVariation and allFilesForVariation return the same order, and have identical index numbers.

Parameters

NameDescription
theVariationNameThe name of the variation to return all the destinations from.

allFilesForVariation:theVariationName

Abstract: Returns an NSArray containing all the destination locations in theVariationName.
- (NSArray *)allFilesForVariation:(NSString *)theVariationName; 

Both allDestinationsForVariation and allFilesForVariation return the same order, and have identical index numbers.

Parameters

NameDescription
theVariationNameThe name of the variation to return all the files from.

compareHashForThemeFile:theThemeFile

Abstract: Compares the hash of one file in the theme to one on the local drive
- (BOOL)compareHashForThemeFile:(NSString *)theThemeFile forFile:(NSString *)thePath; 

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.

Parameters

NameDescription
theThemeFileThe file present within the CSTheme to read the hash from.
theFileThe file on the local computer to compare the hash to.

compressFiles

Abstract: Compresses all non-compressed files within the CSTheme.
- (void)compressFiles; 

This method will be executed automatically when doing any file I/O operations..


currentThemeType

Abstract: Returns the current style of the theme
- (int)currentThemeType; 

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.


dataForFile:theName

Abstract: Returns the data for a file in the CSTheme
- (NSData *)dataForFile:(NSString *)theName; 

Use this method to retrieve the data of a file previously stored in the CSTheme

Parameters

NameDescription
theNameThe name assigned to the file to be retrieved

descriptionForVariation:theVariationName

Abstract: Returns the description of a theme variation
- (NSString *)descriptionForVariation:(NSString *)theVariationName; 

Use this method to return the description of a variation as a string.

Parameters

NameDescription
theVariationNameThe variation to pull the description from.

dictionaryForVariation:theVariationName

Abstract: Returns a theme variation as a dictionary
- (NSDictionary *)dictionaryForVariation:(NSString *)theVariationName; 

You can use this method to copy a variation from one CSTheme to another. addVariationFromDictionary is not yet implemented.

Parameters

NameDescription
theVariationNameThe variation to pull the dictionary from.

fileHasHash:theThemeFile

Abstract: Tests to see if the specified file has a hash present
- (BOOL)fileHasHash:(NSString *)theThemeFile; 

This method will return true if the specified file within the theme has a hash set.


getOSTagForVariation:theVariation

Abstract: Gets the OS tag of the passed variation name
- (NSString *)getOSTagForVariation:(NSString *)theVariation; 

Use this method to get the OS tag of a variation.

Parameters

NameDescription
theVariationThe variation to get the OS tag of.

init

Abstract: Initializes a new CSTheme
- (id)init; 

Initializes a new, non-Aqua backup CSTheme.


initWithAquaTheme

Abstract: Initializes a new Aqua theme backup
- (id)initWithNewAquaTheme; 

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.


initWithContentsOfFile:thePath

Abstract: Initializes the reciever with the contents of an XScheme file
- (id)initWithContentsOfFile:(NSString *)theFile; 

This function will allow you to work with XSchemes as CSObjects

Parameters

NameDescription
theFileThe location of an XScheme to initialize the reciever with

initWithDLTAFromFile:theFile

Abstract: Initializes a new CSTheme from a DLTA
- (id)initWithDLTAFromFile:(NSString *)thePath theTags:(NSArray *)tags; 

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.

Parameters

NameDescription
theFileA string specifying the DLTA bundle to be read
theTagsAn array of tags for the bridge to use when reading the theme. Use tags for each OS you want support to be included for.
theIndexThe index number of the variation you wish to use within the DLTA.

initWithXMLBundle:thePath

Abstract: Initializes a new Aqua theme backup
- (id)initWithXMLBundle:(NSString *)thePath forLanguage:(NSString *)theLanguage; 

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.

Parameters

NameDescription
thePathA string specifying the XML bundle to be read
theLanguageA string specifying the language to be used to read from the XML property list.

removeVariationWithName:theName

Abstract: Removes a variation from a CSTheme
- (void)removeVariationWithName:(NSString *)theName; 

This method removes a theme variation, and all associated links, names, descriptions, and preview pictures from the CSTheme.

Parameters

NameDescription
theNameThe name assigned to the theme to be deleted

setHashForThemeFile:theThemeFile

Abstract: Sets the hash of a file present in the CSTheme.
- (void)setHashForThemeFile:(NSString *)theThemeFile forData:(NSData *)thePath; 

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.

Parameters

NameDescription
theThemeFileThe file to change the hash of.
forDataThe data of a file to generate the hash from.

setHashForThemeFile:theThemeFile

Abstract: Changes the hash (or creates one) for a file added to a CSTheme
- (void)setHashForThemeFile:(NSString *)theThemeFile forFile:(NSString *)theFile; 

This method enables checksum support for file theThemeFile that is present in the CSTheme.

Parameters

NameDescription
theThemeFileThe file present within the CSTheme to add the hash to/replace.
theFileThe file on the local computer to generate a checksum from.

setOSTag:theTag

Abstract: Sets the OS tag of the passed variation name
- (void)setOSTag:(NSString *)theTag forVariation:(NSString *)theVariation; 

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.

Parameters

NameDescription
theTagThe tag you wish to set the variation to use as an NSString
theVariationThe variation to set the OS tag of.

setVariationDescriptionWithString:theDescription

Abstract: Sets the description of a theme variation
- (void)setVariationDescriptionWithString:(NSString *)theDescription forVariation:(NSString *)theVariationName; 

This method sets the description of a theme variation to theDescription

Parameters

NameDescription
theDescriptionA string containing the description to set the variation equal to.
theVariationNameThe variation to set the description of.

themeWithDLTAFromFile:thePath

Abstract: Returns a instance of a theme from the DLTA specified in thePath.
+ (id)themeWithDLTAFromFile:(NSString *)thePath theTags:(NSArray *)tags; 

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.


themeWithThemeFromFile:thePath

Abstract: Returns a instance of a theme from the theme specified in thePath.
+ (id)themeWithThemeFromFile:(NSString *)thePath; 

This method returns an autoreleased instance of a CSTheme (XScheme).


themeWithXMLBundle:thePath

Abstract: Returns a instance of a theme from the MetaMorphX theme specified in thePath.
+ (id)themeWithXMLBundle:(NSString *)thePath forLanguage:(NSString *)theLanguage; 

This method returns an autoreleased instance of a MetaMorphX CSTheme. Pass the language you want the parser to use using theLanguage.


variations

Abstract: Returns the theme variations present in a CSTheme
- (NSArray *)variations; 

This method returns the theme variations present in the CSTheme as an array.


writeAsThemeToPath:thePath

Abstract: Writes a CSTheme to an XScheme file
- (void)writeAsThemeToPath:(NSString *)thePath atomically:(BOOL)atomYN; 

Allows a CSTheme to be saved to an XScheme.

Parameters

NameDescription
thePathThe path to save the XScheme to
fileNamePass YES to write the XScheme atomically, and NO to not.

Typedefs

CSTheme

   * @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;

#define CSDeploymentStyleTheme 1
#define CSBackupStyleTheme 2
#define CSThemeKitVersion 3

@end

This is a list of various constants used.

Constants

NameDescription
CSDeploymentStyleA deployment style theme meant for the end user.
CSBackupStyleThemeA aqua backup style theme meant for backing up the current setup.
CSThemeKitVersionContains the current version of ThemeKit. Developers should always check this against the build used for development.

(Last Updated 3/21/2003)