NSFilePromise framework

Headers/AppKit/AppKit.h

@@ -1,4 +1,4 @@
-/* 
+/*
    AppKit.h
 
    Main include file for GNUstep GUI Library
@@ -7,7 +7,7 @@
 
    Author:  Scott Christley <[email protected]>
    Date: 1996
-   
+
    This file is part of the GNUstep GUI Library.
 
    This library is free software; you can redistribute it and/or
@@ -22,10 +22,10 @@
 
    You should have received a copy of the GNU Lesser General Public
    License along with this library; see the file COPYING.LIB.
-   If not, see <http://www.gnu.org/licenses/> or write to the 
-   Free Software Foundation, 51 Franklin Street, Fifth Floor, 
+   If not, see <http://www.gnu.org/licenses/> or write to the
+   Free Software Foundation, 51 Franklin Street, Fifth Floor,
    Boston, MA 02110-1301, USA.
-*/ 
+*/
 
 #ifndef _GNUstep_H_AppKit
 #define _GNUstep_H_AppKit
@@ -170,6 +170,8 @@
 #import <AppKit/NSDocumentController.h>
 #import <AppKit/NSDictionaryController.h>
 #import <AppKit/NSDrawer.h>
+#import <AppKit/NSFilePromiseProvider.h>
+#import <AppKit/NSFilePromiseReceiver.h>
 #import <AppKit/NSFileWrapperExtensions.h>
 #import <AppKit/NSFontAssetRequest.h>
 #import <AppKit/NSFontCollection.h>

Headers/AppKit/NSFilePromiseProvider.h

@@ -0,0 +1,127 @@
+/*
+   NSFilePromiseProvider.h
+
+   Provider for file promises in drag and drop operations
+
+   Copyright (C) 2025 Free Software Foundation, Inc.
+
+   Author: Gregory John Casamento <[email protected]>
+   Date: 2025
+
+   This file is part of the GNUstep GUI Library.
+
+   This library is free software; you can redistribute it and/or
+   modify it under the terms of the GNU Lesser General Public
+   License as published by the Free Software Foundation; either
+   version 2 of the License, or (at your option) any later version.
+
+   This library is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.	 See the GNU
+   Lesser General Public License for more details.
+
+   You should have received a copy of the GNU Lesser General Public
+   License along with this library; see the file COPYING.LIB.
+   If not, see <http://www.gnu.org/licenses/> or write to the
+   Free Software Foundation, 51 Franklin Street, Fifth Floor,
+   Boston, MA 02110-1301, USA.
+*/
+
+#ifndef _GNUstep_H_NSFilePromiseProvider
+#define _GNUstep_H_NSFilePromiseProvider
+
+#import <Foundation/NSObject.h>
+#import <AppKit/AppKitDefines.h>
+#import <AppKit/NSPasteboard.h>
+
+@class NSString;
+@class NSURL;
+@class NSOperationQueue;
+@class NSArray;
+
+@protocol NSFilePromiseProviderDelegate;
+
+#if OS_API_VERSION(MAC_OS_X_VERSION_10_12, GS_API_LATEST)
+
+// UTI for file promise pasteboard type
+APPKIT_EXPORT NSString * const NSFilePromiseProviderUTI;
+
+APPKIT_EXPORT_CLASS
+@interface NSFilePromiseProvider : NSObject <NSPasteboardWriting>
+{
+  NSString *_fileType;
+  id<NSFilePromiseProviderDelegate> _delegate;
+  id _userInfo;
+}
+
+/** Initializes a file promise provider with the specified file type.
+ * The file type should be a UTI (Uniform Type Identifier) that describes
+ * the type of file that will be provided when the promise is fulfilled.
+ */
+- (instancetype)initWithFileType:(NSString *)fileType
+                        delegate:(id<NSFilePromiseProviderDelegate>)delegate;
+
+/** Returns the file type (UTI) that this provider will create.
+ * This is the Uniform Type Identifier for the type of file
+ * that will be created when the promise is fulfilled.
+ */
+- (NSString *)fileType;
+
+/** Returns the delegate responsible for fulfilling file promises.
+ * The delegate provides the actual file data when a drop occurs.
+ */
+- (id<NSFilePromiseProviderDelegate>)delegate;
+
+/** Sets the delegate responsible for fulfilling file promises.
+ * The delegate must implement the required methods to provide
+ * file data when the promise needs to be fulfilled.
+ */
+- (void)setDelegate:(id<NSFilePromiseProviderDelegate>)delegate;
+
+/** Returns arbitrary user data associated with this provider.
+ * Applications can use this to store context information
+ * needed to fulfill the file promise.
+ */
+- (id)userInfo;
+
+/** Sets arbitrary user data associated with this provider.
+ * Applications can store context information here that will
+ * be needed when fulfilling the file promise.
+ */
+- (void)setUserInfo:(id)userInfo;
+
+@end
+
+@protocol NSFilePromiseProviderDelegate <NSObject>
+
+@required
+
+/** Returns the name for the file that will be created.
+ * This method is called when the system needs to know what
+ * filename to use for the promised file.
+ */
+- (NSString *)filePromiseProvider:(NSFilePromiseProvider *)filePromiseProvider
+                  fileNameForType:(NSString *)fileType;
+
+/** Writes the promised file to the specified URL.
+ * This method is called when the drop occurs and the actual
+ * file needs to be created. The implementation should write
+ * the file data to the provided URL.
+ */
+- (void)filePromiseProvider:(NSFilePromiseProvider *)filePromiseProvider
+          writePromiseToURL:(NSURL *)url
+          completionHandler:(void (^)(NSError *error))completionHandler;
+
+@optional
+
+/** Returns the operation queue for file writing operations.
+ * If not implemented, file writing will occur on a default queue.
+ * Implement this to control which queue is used for file operations.
+ */
+- (NSOperationQueue *)operationQueueForFilePromiseProvider:(NSFilePromiseProvider *)filePromiseProvider;
+
+@end
+
+#endif
+
+#endif // _GNUstep_H_NSFilePromiseProvider

Headers/AppKit/NSFilePromiseReceiver.h

@@ -0,0 +1,78 @@
+/*
+   NSFilePromiseReceiver.h
+
+   Receiver for file promises in drag and drop operations
+
+   Copyright (C) 2025 Free Software Foundation, Inc.
+
+   Author: Gregory John Casamento <[email protected]>
+   Date: 2025
+
+   This file is part of the GNUstep GUI Library.
+
+   This library is free software; you can redistribute it and/or
+   modify it under the terms of the GNU Lesser General Public
+   License as published by the Free Software Foundation; either
+   version 2 of the License, or (at your option) any later version.
+
+   This library is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.	 See the GNU
+   Lesser General Public License for more details.
+
+   You should have received a copy of the GNU Lesser General Public
+   License along with this library; see the file COPYING.LIB.
+   If not, see <http://www.gnu.org/licenses/> or write to the
+   Free Software Foundation, 51 Franklin Street, Fifth Floor,
+   Boston, MA 02110-1301, USA.
+*/
+
+#ifndef _GNUstep_H_NSFilePromiseReceiver
+#define _GNUstep_H_NSFilePromiseReceiver
+
+#import <Foundation/NSObject.h>
+
+#import <AppKit/AppKitDefines.h>
+#import <AppKit/NSPasteboard.h>
+
+@class NSString;
+@class NSURL;
+@class NSArray;
+@class NSOperationQueue;
+
+#if OS_API_VERSION(MAC_OS_X_VERSION_10_12, GS_API_LATEST)
+
+APPKIT_EXPORT_CLASS
+@interface NSFilePromiseReceiver : NSObject <NSPasteboardReading>
+{
+  NSArray *_fileTypes;
+  NSArray *_fileNames;
+}
+
+/** Returns the file types (UTIs) that this receiver can accept.
+ * These are the Uniform Type Identifiers for file types that
+ * this receiver is willing to accept from file promise providers.
+ */
+- (NSArray *)fileTypes;
+
+/** Returns the file names that will be created for the promised files.
+ * This array corresponds to the fileTypes array and provides the
+ * actual filenames that will be used when the promises are fulfilled.
+ */
+- (NSArray *)fileNames;
+
+/** Receives the promised files to the specified destination URL.
+ * This method initiates the process of fulfilling all file promises
+ * represented by this receiver. The files will be created in the
+ * specified destination directory.
+ */
+- (void)receivePromisedFilesAtDestination:(NSURL *)destinationDir
+                                  options:(NSDictionary *)options
+                        operationQueue:(NSOperationQueue *)operationQueue
+                                reader:(void (^)(NSURL *fileURL, NSError *error))reader;
+
+@end
+
+#endif
+
+#endif // _GNUstep_H_NSFilePromiseReceiver

MISSING

@@ -4,9 +4,7 @@ MISSING HEADERS ( * = difficult, - = quick, + = placeholder, x = won't do )
 > NSDiffableDataSource.h *
 > NSDraggingItem.h -
 > NSDraggingSession.h -
-> NSFilePromiseProvider.h -
-> NSFilePromiseReceiver.h -
-> NSItemProvider.h + 
+> NSItemProvider.h +
 > NSOpenGLLayer.h +
 > NSTypesetter.h +
 > NSUserActivity.h -

Source/GNUmakefile

@@ -18,8 +18,8 @@
 #
 #  You should have received a copy of the GNU Lesser General Public
 #  License along with this library; see the file COPYING.LIB.
-#  If not, see <http://www.gnu.org/licenses/> or write to the 
-#  Free Software Foundation, 51 Franklin Street, Fifth Floor, 
+#  If not, see <http://www.gnu.org/licenses/> or write to the
+#  Free Software Foundation, 51 Franklin Street, Fifth Floor,
 #  Boston, MA 02110-1301, USA.
 
 PACKAGE_NAME = gnustep-gui
@@ -110,6 +110,8 @@ NSDocumentController.m \
 NSDrawer.m \
 NSEPSImageRep.m \
 NSEvent.m \
+NSFilePromiseProvider.m \
+NSFilePromiseReceiver.m \
 NSFileWrapperExtensions.m \
 NSFont.m \
 NSFontAssetRequest.m \
@@ -389,7 +391,7 @@ libgnustep-gui_HEADER_FILES_DIR = ../Headers/Additions/GNUstepGUI
 libgnustep-gui_HEADER_FILES_INSTALL_DIR = /GNUstepGUI
 
 COCOA_HEADERS = \
-Cocoa.h 
+Cocoa.h
 
 APPKIT_HEADERS = \
 AppKit.h \
@@ -460,6 +462,8 @@ NSDrawer.h \
 NSEPSImageRep.h \
 NSErrors.h \
 NSEvent.h \
+NSFilePromiseProvider.h \
+NSFilePromiseReceiver.h \
 NSFileWrapper.h \
 NSFileWrapperExtensions.h \
 NSFont.h \
@@ -646,7 +650,7 @@ NSUserInterfaceItemSearching.h \
 NSUserInterfaceItemIdentification.h \
 NSUserInterfaceValidation.h \
 DPSOperators.h \
-PSOperators.h 
+PSOperators.h
 
 GUI_HEADERS = \
 GSVersion.h \