From d4f87e14801eea28f3bd204b2c9ee3debd1a0aab Mon Sep 17 00:00:00 2001 From: CaS Date: Fri, 27 Jun 2003 18:37:00 +0000 Subject: [PATCH] More documentation tweaks git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/gui/trunk@17053 72102866-910b-0410-8b05-ffd578937521 --- Source/NSPasteboard.m | 85 ++++++++++++++++++++++++++++++++++--------- 1 file changed, 68 insertions(+), 17 deletions(-) diff --git a/Source/NSPasteboard.m b/Source/NSPasteboard.m index ee585714e..21bcc3a02 100644 --- a/Source/NSPasteboard.m +++ b/Source/NSPasteboard.m @@ -882,10 +882,19 @@ static NSMapTable *mimeMap = NULL; /** *

Sets the owner of the pasteboard to be newOwner and declares newTypes - * as the types of data supported by it. + * as the types of data supported by it.
+ * This invalidates existing data in the pasteboard (except where the GNUstep + * -setHistory: extension allows multi-version data to be held). *

- *

Returns the new change count for the pasteboard, or zero if an error - * occurs. + *

The value of newOwner may be nil, but if it is, data should + * immediately be written to the pasteboard for all the value in newTypes + * as a nil owner cannot be used for lazy supply of data. + *

+ *

This increments the change count for the pasteboard and the new + * count is returned, or zero is returned if an error occurs.
+ * Where -setChangeCount: has been used, the highest count to date + * is incremented and returned, rather than the last value specified + * by the -setChangeCount: method. *

*/ - (int) declareTypes: (NSArray*)newTypes @@ -928,7 +937,8 @@ static NSMapTable *mimeMap = NULL; /** *

Writes data of type dataType to the pasteboard server so that other * applications can read it. The dataType must be one of the types - * previously declared for the pasteboard. + * previously declared for the pasteboard.
+ * All the other methods for writing data to the pasteboard call this one. *

*

Returns YES on success, NO if the data could not be written for some * reason. @@ -957,8 +967,12 @@ static NSMapTable *mimeMap = NULL; } /** - * Serialises the data in the supplied property list and writes it to the + *

Serialises the data in the supplied property list and writes it to the * pasteboard server using the -setData:forType: method. + *

+ *

Data written using this method can be read by -propertyListForType: + * or, of it was a simple string, by -stringForType: + *

*/ - (BOOL) setPropertyList: (id)propertyList forType: (NSString*)dataType @@ -969,8 +983,12 @@ static NSMapTable *mimeMap = NULL; } /** - * Writes string it to the pasteboard server using the + *

Writes string it to the pasteboard server using the * -setPropertyList:forType: method. + *

+ *

The data may subsequently be read from the reciver using the + * -stringForType: or -propertyListForType: method. + *

*/ - (BOOL) setString: (NSString*)string forType: (NSString*)dataType @@ -979,10 +997,15 @@ static NSMapTable *mimeMap = NULL; } /** - * Writes the contents of the file filename to the pasteboard server + *

Writes the contents of the file filename to the pasteboard server * after declaring the type NSFileContentsPboardType as well as a type * based on the file extension (given by the NSCreateFileContentsPboardType() - * function) if there is one. + * function) if those types have not already been declared.
+ * If the filename has no extension, only NSFileContentsPboardType is used. + *

+ *

Data written to a pasteboard by this method should be read using + * the -readFileContentsType:toFile: or -readFileWrapper method. + *

*/ - (BOOL) writeFileContents: (NSString*)filename { @@ -1004,9 +1027,12 @@ static NSMapTable *mimeMap = NULL; { types = [NSArray arrayWithObject: NSFileContentsPboardType]; } - if ([self declareTypes: types owner: owner] == 0) + if ([[self types] isEqual: types] == NO) { - return NO; // Unable to declare types. + if ([self declareTypes: types owner: owner] == 0) + { + return NO; // Unable to declare types. + } } NS_DURING { @@ -1028,10 +1054,14 @@ static NSMapTable *mimeMap = NULL; /** *

Writes the contents of the file wrapper to the pasteboard server * after declaring the type NSFileContentsPboardType as well as a type - * based on the file extension of the wrappers preferred filename. + * based on the file extension of the wrappers preferred filename if + * those types have not already been declared. *

*

Raises an exception if there is no preferred filename. *

+ *

Data written to a pasteboard by this method should be read using + * the -readFileContentsType:toFile: or -readFileWrapper method. + *

*/ - (BOOL) writeFileWrapper: (NSFileWrapper *)wrapper { @@ -1057,9 +1087,12 @@ static NSMapTable *mimeMap = NULL; { types = [NSArray arrayWithObject: NSFileContentsPboardType]; } - if ([self declareTypes: types owner: owner] == 0) + if ([[self types] isEqual: types] == NO) { - return NO; // Unable to declare types. + if ([self declareTypes: types owner: owner] == 0) + { + return NO; // Unable to declare types. + } } NS_DURING { @@ -1191,8 +1224,12 @@ static NSMapTable *mimeMap = NULL; } /** - * Obtains data of the specified dataType from the pasteboard, deserializes + *

Obtains data of the specified dataType from the pasteboard, deserializes * it to the specified filename and returns the file name (or nil on failure). + *

+ *

This method should only be used to read data written by + * the -writeFileContents: or -writeFileWrapper method. + *

*/ - (NSString*) readFileContentsType: (NSString*)type toFile: (NSString*)filename @@ -1223,8 +1260,12 @@ static NSMapTable *mimeMap = NULL; } /** - * Obtains data of the specified dataType from the pasteboard, deserializes + *

Obtains data of the specified dataType from the pasteboard, deserializes * it and returns the resulting file wrapper (or nil). + *

+ *

This method should only be used to read data written by + * the -writeFileContents: or -writeFileWrapper method. + *

*/ - (NSFileWrapper*) readFileWrapper { @@ -1238,8 +1279,12 @@ static NSMapTable *mimeMap = NULL; } /** - * Obtains data of the specified dataType from the pasteboard, deserializes + *

Obtains data of the specified dataType from the pasteboard, deserializes * it and returns the resulting string (or nil). + *

+ *

The string should have been written using the -setString:forType: or + * -setPropertyList:forType: method. + *

*/ - (NSString*) stringForType: (NSString*)dataType { @@ -1272,11 +1317,16 @@ static NSMapTable *mimeMap = NULL; @implementation NSPasteboard (GNUstepExtensions) /** - * Once the -setChangeCount: message has been sent to an NSPasteboard + *

Once the -setChangeCount: message has been sent to an NSPasteboard * the object will gain an extra GNUstep behaviour - when geting data * from the pasteboard, the data need no longer be from the latest * version but may be a version from a previous representation with * the specified change count. + *

+ *

The value of count must be one which has previously been returned + * by -declareTypes:owner: and should not be further in the past than + * specified by the -setHistory: method. + *

*/ - (void) setChangeCount: (int)count { @@ -1413,6 +1463,7 @@ static NSMapTable *mimeMap = NULL; * [NSPasteboard-writeFileWrapper:] method. Similarly, the data should * be read using the [NSPasteboard-readFileContentsType:toFile:] or * [NSPasteboard-readFileWrapper] method. + *

*/ NSString* NSCreateFileContentsPboardType(NSString *fileType)