Skip to content

Commit cb8e1ff

Browse files
Free-Pascal-meets-SDL-WebsiteFree-Pascal-meets-SDL-Website
committed
Add SDL_dialog.inc
1 parent d090228 commit cb8e1ff

File tree

2 files changed

+239
-0
lines changed

2 files changed

+239
-0
lines changed

‎units/SDL3.pas‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,7 @@ interface
9292
{$I SDL_error.inc} // 3.1.6-prev
9393
{$I SDL_clipboard.inc} // 3.2.0
9494
{$I SDL_cpuinfo.inc} // 3.2.0
95+
{$I SDL_dialog.inc} // 3.2.0
9596

9697

9798
implementation

‎units/SDL_dialog.inc‎

Lines changed: 238 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,238 @@
1+
{
2+
This file is part of:
3+
4+
SDL3 for Pascal
5+
(https://github.com/PascalGameDevelopment/SDL3-for-Pascal)
6+
SPDX-License-Identifier: Zlib
7+
}
8+
9+
{*
10+
* # CategoryDialog
11+
*
12+
* File dialog support.
13+
}
14+
15+
{*
16+
* An entry for filters for file dialogs.
17+
*
18+
* `name` is a user-readable label for the filter (for example, "Office
19+
* document").
20+
*
21+
* `pattern` is a semicolon-separated list of file extensions (for example,
22+
* "doc;docx"). File extensions may only contain alphanumeric characters,
23+
* hyphens, underscores and periods. Alternatively, the whole string can be a
24+
* single asterisk ("*"), which serves as an "All files" filter.
25+
*
26+
* \since This struct is available since SDL 3.1.3.
27+
*
28+
* \sa SDL_DialogFileCallback
29+
* \sa SDL_ShowOpenFileDialog
30+
* \sa SDL_ShowSaveFileDialog
31+
* \sa SDL_ShowOpenFolderDialog
32+
}
33+
type
34+
PPSDL_DialogFileFilter = ^PSDL_DialogFileFilter;
35+
PSDL_DialogFileFilter = ^TSDL_DialogFileFilter;
36+
TSDL_DialogFileFilter = record
37+
name: PAnsiChar;
38+
pattern: PAnsiChar;
39+
end;
40+
41+
{*
42+
* Callback used by file dialog functions.
43+
*
44+
* The specific usage is described in each function.
45+
*
46+
* If `filelist` is:
47+
*
48+
* - nil, an error occurred. Details can be obtained with SDL_GetError().
49+
* - A Pointer to nil, the user either didn't choose any file or canceled the
50+
* dialog.
51+
* - A Pointer to non-`nil`, the user chose one or more files. The argument
52+
* is a null-terminated list of pointers to C strings, each containing a
53+
* path.
54+
*
55+
* The filelist argument does not need to be freed; it will automatically be
56+
* freed when the callback returns.
57+
*
58+
* The filter argument is the index of the filter that was selected, or -1 if
59+
* no filter was selected or if the platform or method doesn't support
60+
* fetching the selected filter.
61+
*
62+
* \param userdata an app-provided Pointer, for the callback's use.
63+
* \param filelist the file(s) chosen by the user.
64+
* \param filter index of the selected filter.
65+
*
66+
* \since This datatype is available since SDL 3.1.3.
67+
*
68+
* \sa SDL_DialogFileFilter
69+
* \sa SDL_ShowOpenFileDialog
70+
* \sa SDL_ShowSaveFileDialog
71+
* \sa SDL_ShowOpenFolderDialog
72+
}
73+
type
74+
TSDL_DialogFileCallback = procedure(userdata: Pointer; filelist: PPAnsiChar; filter: cint); cdecl;
75+
76+
{*
77+
* Displays a dialog that lets the user select a file on their filesystem.
78+
*
79+
* This function should only be invoked from the main thread.
80+
*
81+
* This is an asynchronous function; it will return immediately, and the
82+
* result will be passed to the callback.
83+
*
84+
* The callback will be invoked with a null-terminated list of files the user
85+
* chose. The list will be empty if the user canceled the dialog, and it will
86+
* be nil if an error occurred.
87+
*
88+
* Note that the callback may be called from a different thread than the one
89+
* the function was invoked on.
90+
*
91+
* Depending on the platform, the user may be allowed to input paths that
92+
* don't yet exist.
93+
*
94+
* On Linux, dialogs may require XDG Portals, which requires DBus, which
95+
* requires an event-handling loop. Apps that do not use SDL to handle events
96+
* should add a call to SDL_PumpEvents in their main loop.
97+
*
98+
* \param callback an SDL_DialogFileCallback to be invoked when the user
99+
* selects a file and accepts, or cancels the dialog, or an
100+
* error occurs. The first argument is a null-terminated list
101+
* of C strings, representing the paths chosen by the user.
102+
* The list will be empty if the user canceled the dialog, and
103+
* it will be nil if an error occurred. If an error occurred,
104+
* it can be fetched with SDL_GetError(). The second argument
105+
* is the userdata Pointer passed to the function. The third
106+
* argument is the index of the filter selected by the user,
107+
* or one past the index of the last filter (therefore the
108+
* index of the terminating nil filter) if no filter was
109+
* chosen, or -1 if the platform does not support detecting
110+
* the selected filter.
111+
* \param userdata an optional Pointer to pass extra data to the callback when
112+
* it will be invoked.
113+
* \param window the window that the dialog should be modal for, may be nil.
114+
* Not all platforms support this option.
115+
* \param filters a list of SDL_DialogFileFilter's, may be nil. Not all
116+
* platforms support this option, and platforms that do support
117+
* it may allow the user to ignore the filters.
118+
* \param nfilters the number of filters. Ignored if filters is nil.
119+
* \param default_location the default folder or file to start the dialog at,
120+
* may be nil. Not all platforms support this option.
121+
* \param allow_many if non-zero, the user will be allowed to select multiple
122+
* entries. Not all platforms support this option.
123+
*
124+
* \since This function is available since SDL 3.1.3.
125+
*
126+
* \sa SDL_DialogFileCallback
127+
* \sa SDL_DialogFileFilter
128+
* \sa SDL_ShowSaveFileDialog
129+
* \sa SDL_ShowOpenFolderDialog
130+
}
131+
procedure SDL_ShowOpenFileDialog(callback: TSDL_DialogFileCallback; userdata: Pointer; window: PSDL_Window; filters: PSDL_DialogFileFilter; nfilters: cint; default_location: PAnsiChar; allow_many: cbool); cdecl;
132+
external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ShowOpenFileDialog' {$ENDIF} {$ENDIF};
133+
134+
{*
135+
* Displays a dialog that lets the user choose a new or existing file on their
136+
* filesystem.
137+
*
138+
* This function should only be invoked from the main thread.
139+
*
140+
* This is an asynchronous function; it will return immediately, and the
141+
* result will be passed to the callback.
142+
*
143+
* The callback will be invoked with a null-terminated list of files the user
144+
* chose. The list will be empty if the user canceled the dialog, and it will
145+
* be nil if an error occurred.
146+
*
147+
* Note that the callback may be called from a different thread than the one
148+
* the function was invoked on.
149+
*
150+
* The chosen file may or may not already exist.
151+
*
152+
* On Linux, dialogs may require XDG Portals, which requires DBus, which
153+
* requires an event-handling loop. Apps that do not use SDL to handle events
154+
* should add a call to SDL_PumpEvents in their main loop.
155+
*
156+
* \param callback an SDL_DialogFileCallback to be invoked when the user
157+
* selects a file and accepts, or cancels the dialog, or an
158+
* error occurs. The first argument is a null-terminated list
159+
* of C strings, representing the paths chosen by the user.
160+
* The list will be empty if the user canceled the dialog, and
161+
* it will be nil if an error occurred. If an error occurred,
162+
* it can be fetched with SDL_GetError(). The second argument
163+
* is the userdata Pointer passed to the function. The third
164+
* argument is the index of the filter selected by the user,
165+
* or one past the index of the last filter (therefore the
166+
* index of the terminating nil filter) if no filter was
167+
* chosen, or -1 if the platform does not support detecting
168+
* the selected filter.
169+
* \param userdata an optional Pointer to pass extra data to the callback when
170+
* it will be invoked.
171+
* \param window the window that the dialog should be modal for, may be nil.
172+
* Not all platforms support this option.
173+
* \param filters a list of SDL_DialogFileFilter's, may be nil. Not all
174+
* platforms support this option, and platforms that do support
175+
* it may allow the user to ignore the filters.
176+
* \param nfilters the number of filters. Ignored if filters is nil.
177+
* \param default_location the default folder or file to start the dialog at,
178+
* may be nil. Not all platforms support this option.
179+
*
180+
* \since This function is available since SDL 3.1.3.
181+
*
182+
* \sa SDL_DialogFileCallback
183+
* \sa SDL_DialogFileFilter
184+
* \sa SDL_ShowOpenFileDialog
185+
* \sa SDL_ShowOpenFolderDialog
186+
}
187+
procedure SDL_ShowSaveFileDialog(callback: TSDL_DialogFileCallback; userdata: Pointer; window: PSDL_Window; filters: PSDL_DialogFileFilter; nfilters: cint; default_location: PAnsiChar); cdecl;
188+
external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ShowSaveFileDialog' {$ENDIF} {$ENDIF};
189+
190+
{*
191+
* Displays a dialog that lets the user select a folder on their filesystem.
192+
*
193+
* This function should only be invoked from the main thread.
194+
*
195+
* This is an asynchronous function; it will return immediately, and the
196+
* result will be passed to the callback.
197+
*
198+
* The callback will be invoked with a null-terminated list of files the user
199+
* chose. The list will be empty if the user canceled the dialog, and it will
200+
* be nil if an error occurred.
201+
*
202+
* Note that the callback may be called from a different thread than the one
203+
* the function was invoked on.
204+
*
205+
* Depending on the platform, the user may be allowed to input paths that
206+
* don't yet exist.
207+
*
208+
* On Linux, dialogs may require XDG Portals, which requires DBus, which
209+
* requires an event-handling loop. Apps that do not use SDL to handle events
210+
* should add a call to SDL_PumpEvents in their main loop.
211+
*
212+
* \param callback an SDL_DialogFileCallback to be invoked when the user
213+
* selects a file and accepts, or cancels the dialog, or an
214+
* error occurs. The first argument is a null-terminated list
215+
* of C strings, representing the paths chosen by the user.
216+
* The list will be empty if the user canceled the dialog, and
217+
* it will be nil if an error occurred. If an error occurred,
218+
* it can be fetched with SDL_GetError(). The second argument
219+
* is the userdata Pointer passed to the function. The third
220+
* argument is always -1 for SDL_ShowOpenFolderDialog.
221+
* \param userdata an optional Pointer to pass extra data to the callback when
222+
* it will be invoked.
223+
* \param window the window that the dialog should be modal for, may be nil.
224+
* Not all platforms support this option.
225+
* \param default_location the default folder or file to start the dialog at,
226+
* may be nil. Not all platforms support this option.
227+
* \param allow_many if non-zero, the user will be allowed to select multiple
228+
* entries. Not all platforms support this option.
229+
*
230+
* \since This function is available since SDL 3.1.3.
231+
*
232+
* \sa SDL_DialogFileCallback
233+
* \sa SDL_ShowOpenFileDialog
234+
* \sa SDL_ShowSaveFileDialog
235+
}
236+
procedure SDL_ShowOpenFolderDialog(callback: TSDL_DialogFileCallback; userdata: Pointer; window: PSDL_Window; default_location: PAnsiChar; allow_many: cbool); cdecl;
237+
external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ShowOpenFolderDialog' {$ENDIF} {$ENDIF};
238+

0 commit comments

Comments
 (0)