1 /* 2 NSPasteboard.h 3 4 Class to transfer data to and from the pasteboard server 5 6 Copyright (C) 1996 Free Software Foundation, Inc. 7 8 Author: Scott Christley <scottc@net-community.com> 9 Date: 1996 10 Author: Richard Frith-Macdonald <rfm@gnu.org> 11 12 This file is part of the GNUstep GUI Library. 13 14 This library is free software; you can redistribute it and/or 15 modify it under the terms of the GNU Lesser General Public 16 License as published by the Free Software Foundation; either 17 version 2 of the License, or (at your option) any later version. 18 19 This library is distributed in the hope that it will be useful, 20 but WITHOUT ANY WARRANTY; without even the implied warranty of 21 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 22 Lesser General Public License for more details. 23 24 You should have received a copy of the GNU Lesser General Public 25 License along with this library; see the file COPYING.LIB. 26 If not, see <http://www.gnu.org/licenses/> or write to the 27 Free Software Foundation, 51 Franklin Street, Fifth Floor, 28 Boston, MA 02110-1301, USA. 29 */ 30 31 #ifndef _GNUstep_H_NSPasteboard 32 #define _GNUstep_H_NSPasteboard 33 #import <GNUstepBase/GSVersionMacros.h> 34 35 #import <Foundation/NSObject.h> 36 #import <AppKit/AppKitDefines.h> 37 38 #if defined(__cplusplus) 39 extern "C" { 40 #endif 41 42 @class NSString; 43 @class NSArray; 44 @class NSData; 45 @class NSFileWrapper; 46 47 /** 48 * Pasteboard contains string data as written by 49 * [NSPasteboard-setString:forType:] or [NSPasteboard-setPropertyList:forType:] 50 */ 51 APPKIT_EXPORT NSString *NSStringPboardType; 52 53 /** 54 * Pasteboard contains color information 55 */ 56 APPKIT_EXPORT NSString *NSColorPboardType; 57 58 /** 59 * Pasteboard contains generic file content information (serialized) 60 * as written by [NSPasteboard-writeFileContents:] or 61 * [NSPasteboard-writeFileWrapper:] 62 */ 63 APPKIT_EXPORT NSString *NSFileContentsPboardType; 64 65 /** 66 * Pasteboard contains an array of filenames (serialized) 67 * as written by [NSPasteboard-setPropertyList:forType:] 68 */ 69 APPKIT_EXPORT NSString *NSFilenamesPboardType; 70 71 /** 72 * Pasteboard contains font color information 73 */ 74 APPKIT_EXPORT NSString *NSFontPboardType; 75 76 /** 77 * Pasteboard contains ruler color information 78 */ 79 APPKIT_EXPORT NSString *NSRulerPboardType; 80 81 /** 82 * Pasteboard contains postscript code 83 */ 84 APPKIT_EXPORT NSString *NSPostScriptPboardType; 85 86 /** 87 * Pasteboard contains tabular text. 88 */ 89 APPKIT_EXPORT NSString *NSTabularTextPboardType; 90 91 /** 92 * Pasteboard contains text in rich text format. 93 */ 94 APPKIT_EXPORT NSString *NSRTFPboardType; 95 96 /** 97 * Pasteboard contains text in rich text format with additional info 98 */ 99 APPKIT_EXPORT NSString *NSRTFDPboardType; 100 101 /** 102 * Pasteboard contains a TIFF image 103 */ 104 APPKIT_EXPORT NSString *NSTIFFPboardType; 105 106 /** 107 * Pasteboard contains a link to data in some document 108 */ 109 APPKIT_EXPORT NSString *NSDataLinkPboardType; 110 111 /** 112 * Pasteboard contains general binary data 113 */ 114 APPKIT_EXPORT NSString *NSGeneralPboardType; 115 116 #if OS_API_VERSION(GS_API_MACOSX, GS_API_LATEST) 117 /** 118 * Pasteboard contains a PDF document 119 */ 120 APPKIT_EXPORT NSString *NSPDFPboardType; 121 122 /** 123 * Pasteboard contains a PICT diagram document 124 */ 125 APPKIT_EXPORT NSString *NSPICTPboardType; 126 127 /** 128 * Pasteboard contains a URL 129 */ 130 APPKIT_EXPORT NSString *NSURLPboardType; 131 132 /** 133 * Pasteboard contains HTML data 134 */ 135 APPKIT_EXPORT NSString *NSHTMLPboardType; 136 137 /** 138 * Pasteboard contains VCard (address book) data 139 */ 140 APPKIT_EXPORT NSString *NSVCardPboardType; 141 142 /** 143 * Pasteboard contains promised files 144 */ 145 APPKIT_EXPORT NSString *NSFilesPromisePboardType; 146 #endif 147 148 /** 149 * The pasteboard used for drag and drop information. 150 */ 151 APPKIT_EXPORT NSString *NSDragPboard; 152 153 /** 154 * The pasteboard used search and replace editing operations. 155 */ 156 APPKIT_EXPORT NSString *NSFindPboard; 157 158 /** 159 * The pasteboard used for cutting and pasting font information. 160 */ 161 APPKIT_EXPORT NSString *NSFontPboard; 162 163 /** 164 * The general purpose pasteboard (mostly used for cut and paste) 165 */ 166 APPKIT_EXPORT NSString *NSGeneralPboard; 167 168 /** 169 * The pasteboard used for cutting and pasting ruler information. 170 */ 171 APPKIT_EXPORT NSString *NSRulerPboard; 172 173 /** 174 * Exception raised when communication with the pasteboard server fails. 175 */ 176 APPKIT_EXPORT NSString *NSPasteboardCommunicationException; 177 178 #if OS_API_VERSION(MAC_OS_X_VERSION_10_6, GS_API_LATEST) 179 APPKIT_EXPORT NSString *const NSPasteboardTypeString; 180 APPKIT_EXPORT NSString *const NSPasteboardTypePDF; 181 APPKIT_EXPORT NSString *const NSPasteboardTypeTIFF; 182 APPKIT_EXPORT NSString *const NSPasteboardTypePNG; 183 APPKIT_EXPORT NSString *const NSPasteboardTypeRTF; 184 APPKIT_EXPORT NSString *const NSPasteboardTypeRTFD; 185 APPKIT_EXPORT NSString *const NSPasteboardTypeHTML; 186 APPKIT_EXPORT NSString *const NSPasteboardTypeTabularText; 187 APPKIT_EXPORT NSString *const NSPasteboardTypeFont; 188 APPKIT_EXPORT NSString *const NSPasteboardTypeRuler; 189 APPKIT_EXPORT NSString *const NSPasteboardTypeColor; 190 APPKIT_EXPORT NSString *const NSPasteboardTypeSound; 191 APPKIT_EXPORT NSString *const NSPasteboardTypeMultipleTextSelection; 192 193 #if OS_API_VERSION(MAC_OS_X_VERSION_10_7, GS_API_LATEST) 194 APPKIT_EXPORT NSString *const NSPasteboardTypeTextFinderOptions; 195 #endif 196 #endif 197 198 199 @interface NSPasteboard : NSObject 200 { 201 NSString *name; // The name of this pasteboard. 202 int changeCount; // What we think the current count is. 203 id target; // Proxy to the object in the server. 204 id owner; // Local pasteboard owner. 205 BOOL useHistory; // Want strict OPENSTEP? 206 } 207 208 // 209 // Creating and Releasing an NSPasteboard Object 210 // 211 + (NSPasteboard*) generalPasteboard; 212 + (NSPasteboard*) pasteboardWithName: (NSString*)aName; 213 + (NSPasteboard*) pasteboardWithUniqueName; 214 - (void) releaseGlobally; 215 216 // 217 // Getting Data in Different Formats 218 // 219 + (NSPasteboard*) pasteboardByFilteringData: (NSData*)data 220 ofType: (NSString*)type; 221 + (NSPasteboard*) pasteboardByFilteringFile: (NSString*)filename; 222 + (NSPasteboard*) pasteboardByFilteringTypesInPasteboard: (NSPasteboard*)pboard; 223 + (NSArray*) typesFilterableTo: (NSString*)type; 224 225 // 226 // Referring to a Pasteboard by Name 227 // 228 - (NSString*) name; 229 230 // 231 // Writing Data 232 // 233 - (int) addTypes: (NSArray*)newTypes 234 owner: (id)newOwner; 235 - (int) declareTypes: (NSArray*)newTypes 236 owner: (id)newOwner; 237 - (BOOL) setData: (NSData*)data 238 forType: (NSString*)dataType; 239 - (BOOL) setPropertyList: (id)propertyList 240 forType: (NSString*)dataType; 241 - (BOOL) setString: (NSString*)string 242 forType: (NSString*)dataType; 243 - (BOOL) writeFileContents: (NSString*)filename; 244 - (BOOL) writeFileWrapper: (NSFileWrapper*)wrapper; 245 246 // 247 // Determining Types 248 // 249 - (NSString*) availableTypeFromArray: (NSArray*)types; 250 - (NSArray*) types; 251 252 // 253 // Reading Data 254 // 255 - (int) changeCount; 256 - (NSData*) dataForType: (NSString*)dataType; 257 - (id) propertyListForType: (NSString*)dataType; 258 - (NSString*) readFileContentsType: (NSString*)type 259 toFile: (NSString*)filename; 260 - (NSFileWrapper*) readFileWrapper; 261 - (NSString*) stringForType: (NSString*)dataType; 262 263 @end 264 265 /** 266 * The NSPasteboardOwner informal protocal defines the messages that 267 * the pasteboard system will send to a pasteboard owner if they are 268 * implemented. These are needed to support lazy provision of 269 * pasteboard data. 270 */ 271 @interface NSObject (NSPasteboardOwner) 272 /** 273 * This method is called by the pasteboard system when it does not have 274 * the data that has been asked for ... the pasteboard owner should 275 * supply the data to the pasteboard by calling -setData:forType: or one 276 * of the related methods. 277 */ 278 - (void) pasteboard: (NSPasteboard*)sender 279 provideDataForType: (NSString*)type; 280 281 #if OS_API_VERSION(GS_API_NONE, GS_API_NONE) 282 /** 283 * Implemented where GNUstep pasteboard extensions are required.<br /> 284 * This method is called by the pasteboard system when it does not have 285 * the data that has been asked for ... the pasteboard owner should 286 * supply the data to the pasteboard by calling -setData:forType: or one 287 * of the related methods. 288 */ 289 - (void) pasteboard: (NSPasteboard*)sender 290 provideDataForType: (NSString*)type 291 andVersion: (int)version; 292 #endif 293 294 /** 295 * This method is called by the pasteboard system when another object 296 * takes ownership of the pasteboard ... it lets the previous owner 297 * know that it is no longer required to supply data. 298 */ 299 - (void) pasteboardChangedOwner: (NSPasteboard*)sender; 300 301 @end 302 303 @interface NSPasteboard (GNUstepExtensions) 304 + (NSString*) mimeTypeForPasteboardType: (NSString*)type; 305 + (NSString*) pasteboardTypeForMimeType: (NSString*)mimeType; 306 - (void) setChangeCount: (int)count; 307 - (void) setHistory: (unsigned)length; 308 @end 309 310 #if OS_API_VERSION(GS_API_MACOSX, GS_API_LATEST) 311 #import <Foundation/NSURL.h> 312 313 @interface NSURL (NSPasteboard) 314 + (NSURL*) URLFromPasteboard: (NSPasteboard*)pasteBoard; 315 - (void) writeToPasteboard: (NSPasteboard*)pasteBoard; 316 @end 317 318 #endif 319 // 320 // Return File-related Pasteboard Types 321 // 322 APPKIT_EXPORT NSString *NSCreateFileContentsPboardType(NSString *fileType); 323 APPKIT_EXPORT NSString *NSCreateFilenamePboardType(NSString *fileType); 324 APPKIT_EXPORT NSString *NSGetFileType(NSString *pboardType); 325 APPKIT_EXPORT NSArray *NSGetFileTypes(NSArray *pboardTypes); 326 327 #if OS_API_VERSION(MAC_OS_X_VERSION_10_6, GS_API_LATEST) 328 typedef NSUInteger NSPasteboardWritingOptions; 329 enum { 330 NSPasteboardWritingPromised = 1 << 9 331 }; 332 333 @protocol NSPasteboardWriting <NSObject> 334 - (NSArray *)writableTypesForPasteboard: (NSPasteboard *)pasteboard; 335 - (id)pasteboardPropertyListForType: (NSString *)type; 336 337 #if GS_PROTOCOLS_HAVE_OPTIONAL 338 @optional 339 #else 340 @end 341 @interface NSObject (NSPasteboardWriting) 342 #endif 343 344 - (NSPasteboardWritingOptions)writingOptionsForType: (NSString *)type 345 pasteboard: (NSPasteboard *)pasteboard; 346 @end 347 348 typedef NSUInteger NSPasteboardReadingOptions; 349 enum { 350 NSPasteboardReadingAsData = 0, 351 NSPasteboardReadingAsString = 1 << 0, 352 NSPasteboardReadingAsPropertyList = 1 << 1, 353 NSPasteboardReadingAsKeyedArchive = 1 << 2 354 }; 355 356 @protocol NSPasteboardReading <NSObject> 357 + (NSArray *)readableTypesForPasteboard:(NSPasteboard *)pasteboard; 358 359 #if GS_PROTOCOLS_HAVE_OPTIONAL 360 @optional 361 #else 362 @end 363 @interface NSObject (NSPasteboardReading) 364 #endif 365 366 + (NSPasteboardReadingOptions)readingOptionsForType: (NSString *)type 367 pasteboard: (NSPasteboard *)pasteboard; 368 - (id)initWithPasteboardPropertyList: (id)propertyList ofType: (NSString *)type; 369 @end 370 #endif 371 372 #if defined(__cplusplus) 373 } 374 #endif 375 376 #endif // _GNUstep_H_NSPasteboard 377