File Editors
PBFileEditorFlags
Enumeration/bitset of type uint32_t: Flags specifying how an application behaves as a file editor.
Constants
PBFileEditor_NO_STREAM
PBFileEditor_NO_STREAM = 1<<0
If set, the system will not open a stream for the save and open callbacks. Instead, the application is responsible for writing and reading to the file based on the provided path. In this case, only file that exist on the file system will be accessible by the application.
See Also
PBFileEditorAccessData
Structure: A structure containing the necessary information to save the file.
Fields
[in] window (referenced PBWindow): The window containing the file.
[in] stream (nullable referenced PBStream): The input or output stream, for opening and saving respectively. This field will be NULL if PBFileEditor_NO_STREAM was passed to PBWindowUseAsFileEditor.
[in] path (referenced string): The path to the file being saved or opened. This may be an empty string if this is a virtual file. In this case, the application must use the provided stream to access the file.
See Also
PBFileEditorAccessCallback
Callback: Called by the system to instruct the application to save or open a file.
Syntax (C/C++)
void PBFileEditorAccessCallback(
/* in-out */ PBFileEditorAccessData * __restrict data);
You can create a callback of this type from a function pointer with the above signature using PBFileEditorAccessCallback_Make.
Syntax (Python)
FileEditorAccessCallback(data)
Parameters and Return Values
[in-out] data (PBFileEditorAccessData): The data needed to save or open the file.
Discussion
You must call PBWindowFileEditorAccessComplete exactly once in response to receiving this callback.
PBWindowUseAsFileEditor
Function: Use the window to edit files.
Syntax (C/C++)
void PBWindowUseAsFileEditor(PBWindowRef window,
const ConstStr *_Nullable appCreateArgv, size_t appCreateArgvCount,
PBFileEditorFlags flags, PBFileEditorAccessCallback saveCallback,
PBFileEditorAccessCallback openCallback, ConstStr allowedFormats,
PBWindowRef _Nullable sameFileAs,
/* output */ PBCommandListPtr _Nullable * _Nullable __restrict fileMenu);
Syntax (Python)
WindowUseAsFileEditor(window, appCreateArgv, flags, saveCallback, openCallback, allowedFormats, sameFileAs) -> (fileMenu)
Parameters and Return Values
[in] window (referenced PBWindow): The window to use.
[in] appCreateArgv (referenced array of referenced string): The arguments stored in the PBMessageAppCreate used to create the window, or an empty array. This will be parsed and used to open a file if specified.
[in] flags (PBFileEditorFlags): Bitwise OR of flags specifying how the application behaves as a file editor.
[in] saveCallback (PBFileEditorAccessCallback):
[in] openCallback (PBFileEditorAccessCallback):
[in] allowedFormats (referenced string): The string of allowed file formats to be passed to file pickers. See PBFilePickerConfiguration for an explanation. This field may be empty.
[in] sameFileAs (nullable referenced PBWindow): Optional. If a non-NULL window handle is passed, then the two windows will edit the same file. In this case, appCreateArgv should be an empty array. The save callback could be invoked on any of the windows editing the file.
[optional-out] fileMenu (nullable owned PBCommandList): A command list populated with the standard file commands, intended for use as the application's File menu. You must release this pointer with PBCommandListRelease when you no longer need it.
Discussion
This enables the PBCommand_NEW, PBCommand_OPEN, PBCommand_SAVE and PBCommand_SAVE_AS commands as needed.
When the system wants to ask the application to save or open a file, it will invoke the save and open callbacks provided to this function.
The opened file can be marked as modified with PBWindowSetFileModified. Then, a save prompt will appear when the user attempts to close the window or open a different file.
Usually this function is called just after creating a window.
To use this function, you must have the applicationName in the PBWindowCreationOptions when creating the window.
See Also
PBWindowSetFileModified
Function: Mark the file being edited in a window as modified.
Syntax (C/C++)
void PBWindowSetFileModified(PBWindowRef window);
Syntax (Python)
WindowSetFileModified(window)
Parameters and Return Values
[in] window (referenced PBWindow): The window.
Discussion
You must call PBWindowUseAsFileEditor before using this function.
See Also
PBWindowIsFileModified
Function: Check if the file in the window is modified.
Syntax (C/C++)
bool PBWindowIsFileModified(PBWindowRef window,
/* output */ uint32_t * _Nullable __restrict fileOpenInWindowsCount);
Syntax (Python)
WindowIsFileModified(window) -> (isModified, fileOpenInWindowsCount)
Parameters and Return Values
[in] window (referenced PBWindow): The window. It must have been registered a file editor with PBWindowUseAsEditor.
[out] isModified (bool): True if the file has been marked as modified with PBWindowSetFileModified since it was last saved or loaded.
[optional-out] fileOpenInWindowsCount (uint32_t): The number of windows that have this file open in them. Notably, the user is only asked to save the changes to their file when closing the last window that it is editing it.
PBWindowFileEditorAccessComplete
Function: Complete a file open or save operation.
Syntax (C/C++)
bool PBWindowFileEditorAccessComplete(PBWindowRef window, bool success,
ConstStr errorMessage);
Syntax (Python)
WindowFileEditorAccessComplete(window, success, errorMessage) -> (canceled)
Parameters and Return Values
[in] window (referenced PBWindow):
[in] success (bool):
[in] errorMessage (referenced string):
[out] canceled (bool): If the access completed asynchronously but was canceled by the user, then this returns true. For example, this occurs when the user closes the window before the access completes. In the case that an open operation is canceled, the application must not attempt to populate the window with the loaded data. Either way, if an open operation does not succeed, then the data in the window should not be modified. The operation cannot be canceled if it is completed synchronously; that is, this function is called before the application returns from the save or open callback.
Discussion
This function must be called on the UI thread after the window has been asked by the system to save or open a file. It may run inside the access callback, or later if the operation completed asynchronously. In the latter case, the window will be non-interactable until this function is called.
PBWindowGetFilePath
Function: Get the path of the file being edited in the window.
Syntax (C/C++)
MutStr PBWindowGetFilePath(PBWindowRef window);
Syntax (Python)
WindowGetFilePath(window) -> (filePath)
Parameters and Return Values
[in] window (referenced PBWindow): The window object.
[out] filePath (owned string): The path of the file being edited. You must free this string when you no longer need it.
Discussion
Some files may not have paths on the file system. In this case, an empty string is returned. Furthermore, an unsaved file is being edited, then an empty string is also returned. An empty string is also returned if memory cannot be allocated to make a copy of the path.