Cocoa Internals/Dialogs: what changed

Revision 2 to 3. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		## Common Considerations
2	2
3	3		### Modality
4	4
5	5		None of the Cocoa dialogs (OpenFile, SaveFile, Font or Color) are modal!
6	6
7	7		This means that one can open a dialog and keep using the other application windows and the application menu.
8	8
9	9		This doesn't work well with the LCL design, where each dialog is opened by an Execute method which doesn't return until the modal dialog is closed.
10	10
11	11		For this particular reason, Cocoa WS does the following:
12	12
13	13		- every dialog is called as the application modal window (preventing other windows of the application from getting any user input);
14	14		- the application menu is disabled, until the dialog is closed;
15	15		- where applicable, "Ok" and "Cancel" buttons are added to dialogs to indicate to a user that the dialog can be closed to make the selection.
16	16
17	17		### No restoration
18	18
19	19		Starting with macOS 10.7 Cocoa will attempt to restore the Application windows between Launches.
20	20
21	21		It's a nice user feature, which conflicts with LCL. Since LCL adds custom controls to a dialog, and the restoration requires a special "restorationClass" to be provided.
22	22
23	23		Instead of restoring dialogs, CocoaWS explicitly forbids the restoration of them.
24	24
25	25		### Class Override
26	26
27	27		Unlike NSApplication, dialog classes cannot be overwritten in the following manner:
28	28
29		-	~~` TCocoaColorPanel.sharedPanel`~~
	29	+	```
	30	+	TCocoaColorPanel.sharedPanel
	31	+	```
30	32
31	33		Doing that will cause problems using class methods of the sharedPanel (and likely something else)
32	34
33	35		### No Tags
34	36
35	37		macOS system is using "tags" on files. It seems to be a file system feature that's used commonly in macOS.
36	38
37	39		LCL doesn't have a concept of tags.
38	40
39	41		By default Save dialog is showing a user an ability to select a tag. Since LCL cannot handle it properly (it cannot return the value, nor it has APIs to save the value), the dialog hides the tag selection, by default.
40	42
41	43		### File Type Selection
42	44
43	45		There's no "native" file type selection in macOS dialogs. Instead, there's an opportunity to add "custom options" to an open/save dialog, known as accessory view.
44	46
45	47		The accessory view is used to place the run-time file type selection into the open/save dialog.
46	48
47	49		### File Type Filters
48	50
49	51		There are two ways of filtering out files that can be opened. (Note that "filtering types" is not used when using Save dialog.)
50	52
51	53		1\) Assign the list of file extensions or file types (UTI's) via the setAllowedFileTypes: method. Allowing "any" file can be achieved by using the setAllowsOtherFileTypes: method. Considerations:
52	54
53	55		:* a filter is assigned by "generic type" rather than extension. And thus specifying "txt" as a filter, will assign "public.plain-text" type. Which might correspond to other file extensions other than "txt" file. (i.e. ".pas" files might also be allowed, as they are part of "public.plain-text" group).
54	56
55	57		:* setAllowedFileTypes - is unable to verify compound extensions, such as "tar.gz". In which case the filter configured for ".tag.gz" and a filter configured for ".gz" will provide the exactly the same set of files for selection.
56	58
57	59
58	60		As a result of you should not rely on FilterIndex returned. Instead, you should verify the actual contents of the file selected.
59	61
60	62		2\) Perform the file check manually through the panel:shouldEnableURL: method. Considerations:
61	63
62	64		:* starting with macOS 10.15, there's a security change done in macOS. Save/Open file dialogs are executed in a separate process. Passing the information between the main process and the dialog process introduces a certain lag. If a great number of files, it becomes noticeable for the user. Thus it's possible that not all files might be "available" for the selection as the check runs slowly. (see [issue \#38399](https://bugs.freepascal.org/view.php?id=38399))
63	65
64	66		A developer can control what method is used in the application by changing the global variable CocoaUseUTIFilter at CocoaWSDialogs unit.
65	67
66	68		- CocoaUseUTIFilter = false (default) - "panel:shouldEnableURL" is used
67	69		- CocoaUseUTIFilter = true - macOS UTI method is used
68	70
69	71		```Delphi
70	72		uses
71	73		..
72	74		{$ifdef LCLCOCOA}
73	75		,CocoaWSDialogs
74	76		{$endif}
75	77		...
76	78
77	79		initialization
78	80		{$ifdef LCLCOCOA}
79	81		CocoaUseUTIFilter := true;
80	82		{$endif}
81	83		```
82	84
83	85		## File Dialog Options
84	86
85	87		Some of the options are not supported, please refer to the table below for the implementation details
86	88
87	89		Options
88	90
89	91		Supported
90	92
91	93		Description
92	94
93	95		ofReadOnly
94	96
95	97		No
96	98
97	99		ofOverwritePrompt
98	100
99	101		No
100	102
101	103		In macOS prior to 10.15 it was possible to implement the feature by tricking the NSSaveDialog when selecting the name.
102	104
103	105		However, this ability was removed in 10.15 (due to security considerations?)
104	106
105	107		So now, overwrite prompt will always show up
106	108
107	109		ofHideReadOnly
108	110
109	111		No
110	112
111	113		There's no concept of "readOnly" files in macOS filesystems.
112	114
113	115		There's also no configuration in the dialog, to hide files
114	116
115	117		ofNoChangeDir
116	118
117	119		No
118	120
119	121		ofShowHelp
120	122
121	123		No
122	124
123	125		ofNoValidate
124	126
125	127		No
126	128
127	129		ofAllowMultiSelect
128	130
129	131		Yes
130	132
131	133		NSOpenPanel.setAllowsMultipleSelection()
132	134
133	135		ofExtensionDifferent,
134	136
135	137		No
136	138
137	139		ofPathMustExist
138	140
139	141		No
140	142
141	143		ofFileMustExist
142	144
143	145		No
144	146
145	147		ofCreatePrompt
146	148
147	149		No
148	150
149	151		ofShareAware
150	152
151	153		No
152	154
153	155		System native dialogs are always share aware OR act within sandbox allowances
154	156
155	157		ofNoReadOnlyReturn
156	158
157	159		No
158	160
159	161		No concept of "readonly" file
160	162
161	163		ofNoTestFileCreate
162	164
163	165		No
164	166
165	167		ofNoNetworkButton
166	168
167	169		No
168	170
169	171		All shares and networks are available or restricted by SandBox limitations
170	172
171	173		ofNoLongNames
172	174
173	175		No
174	176
175	177		Any file can have long name. OSX never suffered from 8.3 limitation
176	178
177	179		ofOldStyleDialog
178	180
179	181		No
180	182
181	183		There's no old style on macOS ...but, there's an opportunity to use in order to allow some emulation
182	184
183	185		ofNoDereferenceLinks
184	186
185	187		No
186	188
187	189		Links are treated by the system.
188	190
189	191		ofNoResolveLinks
190	192
191	193		No
192	194
193	195		Links are treated by the system
194	196
195	197		ofEnableIncludeNotify
196	198
197	199		No
198	200
199	201		ofEnableSizing
200	202
201	203		No
202	204
203	205		Dialogs are always sizable to the macOS rules
204	206
205	207		ofDontAddToRecent
206	208
207	209		No
208	210
209	211		ofForceShowHidden
210	212
211	213		Yes
212	214
213	215		NSSaveDialog.setShowsHiddenFiles()
214	216
215	217		ofViewDetail
216	218
217	219		No
218	220
219	221		ofAutoPreview
220	222
221	223		No
222	224
223	225		\-
224	226
225	227		(default)
226	228
227	229		canCreateDirectries
228	230
229	231		The feature controls, if a user can create directories within the dialog.
230	232
231	233		Since Windows dialogs allows creation of folders, macOS LCL dialogs also allows the creation at all times.
232	234
233	235		\-
234	236
235	237		(default)
236	238
237	239		extensionHidden
238	240
239	241		The name of the file, selected by the user hides the extension.
240	242
241	243		Since on Windows there's no control over how the file is displayed.
242	244
243	245		The property is left to its system default.
244	246
245	247		\-
246	248
247	249		(default)
248	250
249	251		treatsFilePackagesAsDirectories
250	252
251	253		If set to true, a user can treat (Application) bundles as directories and navigate into the bundle.
252	254
253	255		There's no such concept in LCL, the value is at system default
254	256
255	257		## See Also
256	258
257	259		- [[Cocoa Internals]]
258	260
259	261		---
260	262		From the Free Pascal wiki, page "Cocoa Internals/Dialogs", as it stood on 2021-01-30 after a change by Skalogryz, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).
261	263		Category: Cocoa
262	264		Category: macOS

Back to history