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 26 27 #include <X11/Xlib.h> 28 29 /////////////////////////////////////////////////////////////////////////////// 30 /* public API */ 31 32 /** open a file select dialog 33 * @param dpy X Display connection 34 * @param parent (optional) if not NULL, become transient for given window 35 * @param x if >0 set explict initial width of the window 36 * @param y if >0 set explict initial height of the window 37 * @return 0 on success 38 */ 39 int x_fib_show (Display *dpy, Window parent, int x, int y); 40 41 /** force close the dialog. 42 * This is normally not needed, the dialog closes itself 43 * when a file is selected or the user cancels selection. 44 * @param dpy X Display connection 45 */ 46 void x_fib_close (Display *dpy); 47 48 /** non-blocking X11 event handler. 49 * It is safe to run this function even if the dialog is 50 * closed or was not initialized. 51 * 52 * @param dpy X Display connection 53 * @param event the XEvent to process 54 * @return status 55 * 0: the event was not for this window, or file-dialog still 56 * active, or the dialog window is not displayed. 57 * >0: file was selected, dialog closed 58 * <0: file selection was cancelled. 59 */ 60 int x_fib_handle_events (Display *dpy, XEvent *event); 61 62 /** last status of the dialog 63 * @return >0: file was selected, <0: canceled or inactive. 0: active 64 */ 65 int x_fib_status (); 66 67 /** query the selected filename 68 * @return NULL if none set, or allocated string to be free()ed by the called 69 */ 70 char *x_fib_filename (); 71 72 /** customize/configure the dialog before calling \ref x_fib_show 73 * changes only have any effect if the dialog is not visible. 74 * @param k key to change 75 * 0: set current dir to display (must end with slash) 76 * 1: set title of dialog window 77 * 2: specify a custom X11 font to use 78 * 3: specify a custom 'places' file to include 79 * (following gtk-bookmark convention) 80 * @param v value 81 * @return 0 on success. 82 */ 83 int x_fib_configure (int k, const char *v); 84 85 /** customize/configure the dialog before calling \ref x_fib_show 86 * changes only have any effect if the dialog is not visible. 87 * 88 * @param k button to change: 89 * 1: show hidden files 90 * 2: show places 91 * 3: show filter/list all (automatically hidden if there is no 92 * filter function) 93 * @param v <0 to hide the button >=0 show button, 94 * 0: set button-state to not-checked 95 * 1: set button-state to checked 96 * >1: retain current state 97 * @return 0 on success. 98 */ 99 int x_fib_cfg_buttons (int k, int v); 100 101 /** set custom callback to filter file-names. 102 * NULL will disable the filter and hide the 'show all' button. 103 * changes only have any effect if the dialog is not visible. 104 * 105 * @param cb callback function to check file 106 * the callback function is called with the file name (basename only) 107 * and is expected to return 1 if the file passes the filter 108 * and 0 if the file should not be listed by default. 109 * @return 0 on success. 110 */ 111 int x_fib_cfg_filter_callback (int (*cb)(const char*)); 112 113 /* 'recently used' API. x-platform 114 * NOTE: all functions use a static cache and are not reentrant. 115 * It is expected that none of these functions are called in 116 * parallel from different threads. 117 */ 118 119 /** release static resources of 'recently used files' 120 */ 121 void x_fib_free_recent (); 122 123 /** add an entry to the recently used list 124 * 125 * The dialog does not add files automatically on open, 126 * if the application succeeds to open a selected file, 127 * this function should be called. 128 * 129 * @param path complete path to file 130 * @param atime time of last use, 0: NOW 131 * @return -1 on error, number of current entries otherwise 132 */ 133 int x_fib_add_recent (const char *path, time_t atime); 134 135 /** get a platform specific path to a good location for 136 * saving the recently used file list. 137 * (follows XDG_DATA_HOME on Unix, and CSIDL_LOCAL_APPDATA spec) 138 * 139 * @param application-name to use to include in file 140 * @return pointer to static path or NULL 141 */ 142 const char *x_fib_recent_file(const char *appname); 143 144 /** save the current list of recently used files to the given filename 145 * (the format is one file per line, filename URL encoded and space separated 146 * with last-used timestamp) 147 * 148 * This function tries to creates the containing directory if it does 149 * not exist. 150 * 151 * @param fn file to save the list to 152 * @return 0: on success 153 */ 154 int x_fib_save_recent (const char *fn); 155 156 /** load a recently used file list. 157 * 158 * @param fn file to load the list from 159 * @return 0: on success 160 */ 161 int x_fib_load_recent (const char *fn); 162 163 /** get number of entries in the current list 164 * @return number of entries in the recently used list 165 */ 166 unsigned int x_fib_recent_count (); 167 168 /** get recently used entry at given position 169 * 170 * @param i entry to query 171 * @return pointer to static string 172 */ 173 const char *x_fib_recent_at (unsigned int i); 174 175 #endif // LIBSOFD_H 176