Cocoa Internals/Dialogs: what changed

Revision 3 to 4. 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		-	~~```~~
	29	+	```text
30	30		TCocoaColorPanel.sharedPanel
31	31		```
32	32
33	33		Doing that will cause problems using class methods of the sharedPanel (and likely something else)
34	34
35	35		### No Tags
36	36
37	37		macOS system is using "tags" on files. It seems to be a file system feature that's used commonly in macOS.
38	38
39	39		LCL doesn't have a concept of tags.
40	40
41	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.
42	42
43	43		### File Type Selection
44	44
45	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.
46	46
47	47		The accessory view is used to place the run-time file type selection into the open/save dialog.
48	48
49	49		### File Type Filters
50	50
51	51		There are two ways of filtering out files that can be opened. (Note that "filtering types" is not used when using Save dialog.)
52	52
53	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:
54	54
55	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).
56	56
57	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.
58	58
59	59
60	60		As a result of you should not rely on FilterIndex returned. Instead, you should verify the actual contents of the file selected.
61	61
62	62		2\) Perform the file check manually through the panel:shouldEnableURL: method. Considerations:
63	63
64	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))
65	65
66	66		A developer can control what method is used in the application by changing the global variable CocoaUseUTIFilter at CocoaWSDialogs unit.
67	67
68	68		- CocoaUseUTIFilter = false (default) - "panel:shouldEnableURL" is used
69	69		- CocoaUseUTIFilter = true - macOS UTI method is used
70	70
71	71		```Delphi
72	72		uses
73	73		..
74	74		{$ifdef LCLCOCOA}
75	75		,CocoaWSDialogs
76	76		{$endif}
77	77		...
78	78
79	79		initialization
80	80		{$ifdef LCLCOCOA}
81	81		CocoaUseUTIFilter := true;
82	82		{$endif}
83	83		```
84	84
85	85		## File Dialog Options
86	86
87	87		Some of the options are not supported, please refer to the table below for the implementation details
88	88
89	89		Options
90	90
91	91		Supported
92	92
93	93		Description
94	94
95	95		ofReadOnly
96	96
97	97		No
98	98
99	99		ofOverwritePrompt
100	100
101	101		No
102	102
103	103		In macOS prior to 10.15 it was possible to implement the feature by tricking the NSSaveDialog when selecting the name.
104	104
105	105		However, this ability was removed in 10.15 (due to security considerations?)
106	106
107	107		So now, overwrite prompt will always show up
108	108
109	109		ofHideReadOnly
110	110
111	111		No
112	112
113	113		There's no concept of "readOnly" files in macOS filesystems.
114	114
115	115		There's also no configuration in the dialog, to hide files
116	116
117	117		ofNoChangeDir
118	118
119	119		No
120	120
121	121		ofShowHelp
122	122
123	123		No
124	124
125	125		ofNoValidate
126	126
127	127		No
128	128
129	129		ofAllowMultiSelect
130	130
131	131		Yes
132	132
133	133		NSOpenPanel.setAllowsMultipleSelection()
134	134
135	135		ofExtensionDifferent,
136	136
137	137		No
138	138
139	139		ofPathMustExist
140	140
141	141		No
142	142
143	143		ofFileMustExist
144	144
145	145		No
146	146
147	147		ofCreatePrompt
148	148
149	149		No
150	150
151	151		ofShareAware
152	152
153	153		No
154	154
155	155		System native dialogs are always share aware OR act within sandbox allowances
156	156
157	157		ofNoReadOnlyReturn
158	158
159	159		No
160	160
161	161		No concept of "readonly" file
162	162
163	163		ofNoTestFileCreate
164	164
165	165		No
166	166
167	167		ofNoNetworkButton
168	168
169	169		No
170	170
171	171		All shares and networks are available or restricted by SandBox limitations
172	172
173	173		ofNoLongNames
174	174
175	175		No
176	176
177	177		Any file can have long name. OSX never suffered from 8.3 limitation
178	178
179	179		ofOldStyleDialog
180	180
181	181		No
182	182
183	183		There's no old style on macOS ...but, there's an opportunity to use in order to allow some emulation
184	184
185	185		ofNoDereferenceLinks
186	186
187	187		No
188	188
189	189		Links are treated by the system.
190	190
191	191		ofNoResolveLinks
192	192
193	193		No
194	194
195	195		Links are treated by the system
196	196
197	197		ofEnableIncludeNotify
198	198
199	199		No
200	200
201	201		ofEnableSizing
202	202
203	203		No
204	204
205	205		Dialogs are always sizable to the macOS rules
206	206
207	207		ofDontAddToRecent
208	208
209	209		No
210	210
211	211		ofForceShowHidden
212	212
213	213		Yes
214	214
215	215		NSSaveDialog.setShowsHiddenFiles()
216	216
217	217		ofViewDetail
218	218
219	219		No
220	220
221	221		ofAutoPreview
222	222
223	223		No
224	224
225	225		\-
226	226
227	227		(default)
228	228
229	229		canCreateDirectries
230	230
231	231		The feature controls, if a user can create directories within the dialog.
232	232
233	233		Since Windows dialogs allows creation of folders, macOS LCL dialogs also allows the creation at all times.
234	234
235	235		\-
236	236
237	237		(default)
238	238
239	239		extensionHidden
240	240
241	241		The name of the file, selected by the user hides the extension.
242	242
243	243		Since on Windows there's no control over how the file is displayed.
244	244
245	245		The property is left to its system default.
246	246
247	247		\-
248	248
249	249		(default)
250	250
251	251		treatsFilePackagesAsDirectories
252	252
253	253		If set to true, a user can treat (Application) bundles as directories and navigate into the bundle.
254	254
255	255		There's no such concept in LCL, the value is at system default
256	256
257	257		## See Also
258	258
259	259		- [[Cocoa Internals]]
260	260
261	261		---
262	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).
263	263		Category: Cocoa
264	264		Category: macOS

Back to history