Expose cancel state of FileDialog and DirectoryDialog

[HeikoKlare]

The FileDialog and DirectoryDialog implementations do currently not provide any way to identify that the dialog was canceled. The dialogs return a null string in case no file or folder was selected, but is not possible to identify whether this was intended (via a cancel action) or if there was some unexpected error while the dialog was open (such as too long file paths on Windows).

This change introduces the openDialog() method as an alternative to the existing open() method. This new method returns an optional String, which is only present if a file or directory was successfully selected. An empty Optional indicates a cancellation by the user and an actual error is realized as an SWTException. The dialogs evaluate the operating system's response code for the system's dialog control to identify the dialogs result state.

This PR is a result of the proposal by @laeubi in #1005 (comment). Supercedes and thus closes #1005.

[github-actions]

Test Results

   299 files  ±0     299 suites  ±0   6m 18s ⏱️ - 1m 50s
 4 099 tests ±0   4 091 ✅ ±0   8 💤 ±0  0 ❌ ±0 
12 209 runs  ±0  12 134 ✅ ±0  75 💤 ±0  0 ❌ ±0 

Results for commit e6bb8b0. ± Comparison against base commit 0532901.

♻️ This comment has been updated with latest results.

[laeubi]

Just some suggestions/thoughts ...

[laeubi]

Thinking more, maybe the result class is not required and one could have a singel method

Optional<String askForFile/Folder()

that in case of error throws an exception with a meaningful message (e.g. path is to long, IO exception seems suitable if SWT Exception seems not well suited) and an empty optional on cancel, then all cases should be covered.

[HeikoKlare]

Thanks for all the input, @laeubi! I tend to completely agree with your point of view.

In particular, I took a look at the kinds of "errors" that may happen and found that the currently used OS APIs only seem to provide "OK" and "Cancel", and maybe something else if there really is a error (that may then reasonable be thrown as an SWTException). I took the according information from here:
Windows: https://learn.microsoft.com/en-us/windows/win32/api/shobjidl_core/nf-shobjidl_core-imodalwindow-show
Linux/GTK: https://docs.gtk.org/gtk3/method.NativeDialog.run.html
Mac: https://developer.apple.com/documentation/appkit/nssavepanel/1525357-runmodal
And on Windows, I manually tried to produce errors that have been delivered as such in the "old" file dialog implementation (for the result types, see here), but all these kinds of errors are now already handled by the dialog itself, so that you cannot even close the dialog pressing "Ok" with, e.g., an invalid file name. My contribution was driven by the fact that our RCP product still uses SWT with the "old" Windows file dialog implementation, where we had to explicitly handle different kinds of error cases, but this does not seem to be necessary with the current implementation anyway.

So I changed the implementation to only return an Optional result and throw an exception in other cases in 9641b01.
One drawback is that this complicates the realization of the existing open() method. To be API preserving, it has to distinguish between existing SWTExceptions and those potentially thrown due to an error result (i.e., not OK and not Cancel) of the dialog. So either this information has to be wrapped in a result object of some private method or it has to be extracted from the SWTException. I followed the latter approach to not bloat up the code, but it is actually a bit unclean.

[laeubi]

It looks fine for me just a bit unsure about the naming but maybe others like to give advice.

[laeubi]

Suggested change

	return Optional.of(directoryPath);
	return Optional.ofNullable(directoryPath);

could it be null? or maybe the case of empty should also result in a Optional.empty()....

[laeubi]

Suggested change

	public Optional<String> askSelectDirectory() {
	public Optional<String> openDirectory() {

What do you think about something like this? askSelect sounds a bit strange and that way probabbly if it also starts with "open" users that are used to the old method might discover the new one.

[merks]

Yes, I think something that starts with open so that it's sorted to be adjacent in documentation or in proposals....

[HeikoKlare]

Agreed. Maybe just openDialog()? Since the call does not open a file/directory, but a dialog (to choose one).

[laeubi]

I would be fine with openDialog() as well

[HeikoKlare]

I have manually checked the behavior on Windows 11, Ubuntu 22.04 (Gnome 42) and MacOS Sonoma with this simply snippet (also with DirectoryDialog respectively):

System.out.println(new FileDialog(new Shell(new Display())).openDialog());

They all printed an empty Optional when cancelling the dialog and the selected path in case of a successful selection.