Mercurial > hg > pub > prymula > com

comparison DPF-Prymula-audioplugins/dpf/distrho/extra/sofd/libsofd.h @ 3:84e66ea83026

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
DPF-Prymula-audioplugins-0.231015-2
author prymula <prymula76@outlook.com>
date Mon, 16 Oct 2023 21:53:34 +0200
parents
children
comparison
equal deleted inserted replaced
2:cf2cb71d31dd 3:84e66ea83026
1 /* libSOFD - Simple Open File Dialog [for X11 without toolkit]
2 *
3 * Copyright (C) 2014 Robin Gareus <robin@gareus.org>
4 *
5 * Permission is hereby granted, free of charge, to any person obtaining a copy
6 * of this software and associated documentation files (the "Software"), to deal
7 * in the Software without restriction, including without limitation the rights
8 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 * copies of the Software, and to permit persons to whom the Software is
10 * furnished to do so, subject to the following conditions:
11 *
12 * The above copyright notice and this permission notice shall be included in
13 * all copies or substantial portions of the Software.
14 *
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21 * THE SOFTWARE.
22 */
23
24 #ifndef LIBSOFD_H
25 #define LIBSOFD_H 1
26
27 #ifdef HAVE_X11
28 #include <X11/Xlib.h>
29
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33
34 ///////////////////////////////////////////////////////////////////////////////
35 /* public API */
36
37 /** open a file select dialog
38 * @param dpy X Display connection
39 * @param parent (optional) if not NULL, become transient for given window
40 * @param x if >0 set explict initial width of the window
41 * @param y if >0 set explict initial height of the window
42 * @return 0 on success
43 */
44 int x_fib_show (Display *dpy, Window parent, int x, int y, double scalefactor);
45
46 /** force close the dialog.
47 * This is normally not needed, the dialog closes itself
48 * when a file is selected or the user cancels selection.
49 * @param dpy X Display connection
50 */
51 void x_fib_close (Display *dpy);
52
53 /** non-blocking X11 event handler.
54 * It is safe to run this function even if the dialog is
55 * closed or was not initialized.
56 *
57 * @param dpy X Display connection
58 * @param event the XEvent to process
59 * @return status
60 * 0: the event was not for this window, or file-dialog still
61 * active, or the dialog window is not displayed.
62 * >0: file was selected, dialog closed
63 * <0: file selection was cancelled.
64 */
65 int x_fib_handle_events (Display *dpy, XEvent *event);
66
67 /** last status of the dialog
68 * @return >0: file was selected, <0: canceled or inactive. 0: active
69 */
70 int x_fib_status ();
71
72 /** query the selected filename
73 * @return NULL if none set, or allocated string to be free()ed by the called
74 */
75 char *x_fib_filename ();
76
77 /** customize/configure the dialog before calling \ref x_fib_show
78 * changes only have any effect if the dialog is not visible.
79 * @param k key to change
80 * 0: set current dir to display (must end with slash)
81 * 1: set title of dialog window
82 * 2: specify a custom X11 font to use
83 * 3: specify a custom 'places' file to include
84 * (following gtk-bookmark convention)
85 * @param v value
86 * @return 0 on success.
87 */
88 int x_fib_configure (int k, const char *v);
89
90 /** customize/configure the dialog before calling \ref x_fib_show
91 * changes only have any effect if the dialog is not visible.
92 *
93 * @param k button to change:
94 * 1: show hidden files
95 * 2: show places
96 * 3: show filter/list all (automatically hidden if there is no
97 * filter function)
98 * @param v <0 to hide the button >=0 show button,
99 * 0: set button-state to not-checked
100 * 1: set button-state to checked
101 * >1: retain current state
102 * @return 0 on success.
103 */
104 int x_fib_cfg_buttons (int k, int v);
105
106 /** set custom callback to filter file-names.
107 * NULL will disable the filter and hide the 'show all' button.
108 * changes only have any effect if the dialog is not visible.
109 *
110 * @param cb callback function to check file
111 * the callback function is called with the file name (basename only)
112 * and is expected to return 1 if the file passes the filter
113 * and 0 if the file should not be listed by default.
114 * @return 0 on success.
115 */
116 int x_fib_cfg_filter_callback (int (*cb)(const char*));
117
118 #ifdef __cplusplus
119 }
120 #endif
121
122 #endif /* END X11 specific functions */
123
124 #ifdef __cplusplus
125 extern "C" {
126 #endif
127
128 /* 'recently used' API. x-platform
129 * NOTE: all functions use a static cache and are not reentrant.
130 * It is expected that none of these functions are called in
131 * parallel from different threads.
132 */
133
134 /** release static resources of 'recently used files'
135 */
136 void x_fib_free_recent ();
137
138 /** add an entry to the recently used list
139 *
140 * The dialog does not add files automatically on open,
141 * if the application succeeds to open a selected file,
142 * this function should be called.
143 *
144 * @param path complete path to file
145 * @param atime time of last use, 0: NOW
146 * @return -1 on error, number of current entries otherwise
147 */
148 int x_fib_add_recent (const char *path, time_t atime);
149
150 /** get a platform specific path to a good location for
151 * saving the recently used file list.
152 * (follows XDG_DATA_HOME on Unix, and CSIDL_LOCAL_APPDATA spec)
153 *
154 * @param application-name to use to include in file
155 * @return pointer to static path or NULL
156 */
157 const char *x_fib_recent_file(const char *appname);
158
159 /** save the current list of recently used files to the given filename
160 * (the format is one file per line, filename URL encoded and space separated
161 * with last-used timestamp)
162 *
163 * This function tries to creates the containing directory if it does
164 * not exist.
165 *
166 * @param fn file to save the list to
167 * @return 0: on success
168 */
169 int x_fib_save_recent (const char *fn);
170
171 /** load a recently used file list.
172 *
173 * @param fn file to load the list from
174 * @return 0: on success
175 */
176 int x_fib_load_recent (const char *fn);
177
178 /** get number of entries in the current list
179 * @return number of entries in the recently used list
180 */
181 unsigned int x_fib_recent_count ();
182
183 /** get recently used entry at given position
184 *
185 * @param i entry to query
186 * @return pointer to static string
187 */
188 const char *x_fib_recent_at (unsigned int i);
189
190 #ifdef __cplusplus
191 }
192 #endif
193
194 #endif // header guard