libsofd.h (6214B)
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