Debian Codegraph @

extensions/Fl_Native_File_Chooser/documentation/Fl_Native_File_Chooser.html

raw
1 <html>
2 <head>
3 <title>[Fltk-1.x] Fl_Native_File_Chooser</title>
4 </head>
5 <body>
6 <H1>[Fltk-1.x] Fl_Native_File_Chooser</H1>
7
8 <h2>class Fl_Native_File_Chooser</a></h2>
9 <!--
10 <h3>Class Hierarchy</h3>
11 <ul>
12 <pre>
13 Fl_Native_File_Chooser
14 </pre>
15 </ul>
16 -->
17
18 <h3>Include Files</h3>
19 <ul>
20 <pre>
21 #include &lt;FL/Fl_Native_File_Chooser.H&gt;
22 </pre>
23 </ul>
24 Dowload latest source from <a href="http://seriss.com/people/erco/fltk/Fl_Native_File_Chooser/">here</a>.
25 <br>
26 <h3>Description</h3>
27 This class lets an FLTK application easily and consistently access
28 the local operating system's native file chooser. Some operating systems
29 have very complex and specific file choosers that many users want access
30 to specifically, instead of FLTK's default file chooser(s).
31 <p>
32 <h3>Methods</h3>
33 <center>
34 <table width="90%" summary="Fl_Native_File_Chooser methods">
35 <tr><td align="left" valign="top">
36 <ul>
37 <li> <a href="#Fl_Native_File_Chooser">Fl_Native_File_Chooser</a>
38 <li> <a href="#~Fl_Native_File_Chooser">~Fl_Native_File_Chooser</a>
39 <li> <a href="#count">count</a>
40 </ul>
41 </td><td align="left" valign="top">
42 <ul>
43 <li> <a href="#directory">directory</a>
44 <li> <a href="#errmsg">errmsg</a>
45 <li> <a href="#filename">filename</a>
46 </ul>
47 </td><td align="left" valign="top">
48 <ul>
49 <li> <a href="#filter">filter</a>
50 <li> <a href="#filter_value">filter_value</a>
51 <li> <a href="#filters">filters</a>
52 </ul>
53 </td><td align="left" valign="top">
54 <ul>
55 <li> <a href="#options">options</a>
56 <li> <a href="#preset_file">preset_file</a>
57 <li> <a href="#show">show</a>
58 </ul>
59 </td><td align="left" valign="top">
60 <ul>
61 <li> <a href="#title">title</a>
62 <li> <a href="#type">type</a>
63 </ul>
64 &nbsp;<br>
65 &nbsp;<br>
66 </td> </tr> </table>
67 </center>
68
69 <h4><a name="Fl_Native_File_Chooser">
70 Fl_Native_File_Chooser::Fl_Native_File_Chooser()<br>
71 Fl_Native_File_Chooser::Fl_Native_File_Chooser(type)
72 </h4>
73 <ul>
74 The constructor for the Fl_Native_File_Chooser.
75 <p>
76 If the optional <tt>type</tt> is not specified,
77 BROWSE_FILE (browse to open a file) is assumed.
78 The type can also be set later with <a href="#type">type()</a>.
79 </ul>
80
81 <h4><a name="~Fl_Native_File_Chooser">
82 Fl_Native_File_Chooser::~Fl_Native_File_Chooser()
83 </h4>
84 <ul>
85 The destructor; destroys any resources allocated to this widget.
86 </ul>
87
88 <h4>
89 <a name="count"></a>
90 int Fl_Native_File_Chooser::count() const
91 </h4>
92 <ul>
93 Returns the number of filenames (or directory names) the user
94 selected. These are zero-indexed.
95 See this example of <a href="#multi_example">how to retrieve
96 multiple filenames</a>.
97 </ul>
98
99
100 <h4>
101 <a name="directory"></a>
102 void Fl_Native_File_Chooser::directory(const char*)<br>
103 const char* Fl_Native_File_Chooser::directory() const;<br>
104 </h4>
105 <ul>
106 Sets the directory with which to start the chooser.
107 If NULL is passed, or if no directory is specified,
108 the chooser will attempt to use the last non-cancelled folder.<br>
109 </ul>
110
111 <h4>
112 <a name="errmsg"></a>
113 const char *Fl_Native_File_Chooser::errmsg() const<br>
114 </h4>
115 <ul>
116 Returns a system dependent error message for the last
117 method that failed. This message should at least be flagged
118 to the user in a dialog box, or to some kind of error log.
119 </ul>
120
121 <h4>
122 <a name="filename"></a>
123 const char *Fl_Native_File_Chooser::filename() const<br>
124 const char *Fl_Native_File_Chooser::filename(int) const<br>
125 </h4>
126 <ul>
127 The first form returns the single filename selected
128 by the user from the browser. (In a multiple browser
129 context, this returns the first filename the user selected).
130 <p>
131 The second form should be used to return multiple filenames,
132 and is normally used inside a loop to retrieve all the files
133 the user selected, eg:
134 <p>
135 <a name="multi_example">
136 <pre>
137 if ( <b>chooser->show()</b> == 0 ) {
138 // HANDLE MULTIPLE FILENAMES
139 for (int n = 0; n &lt; <b>chooser->count()</b>; n++ ) {
140 fprintf(stderr, "%d) '%s'\n", n, <b>chooser->filename(n)</b>);
141 }
142 }
143 </pre>
144 You can preset the directory with
145 <a href="#directory">directory()</a> method, and the filename using the
146 <a href="#preset_file">preset_file()</a> method.<br>
147 </ul>
148
149 <h4>
150 <a name="filter"></a>
151 const char *Fl_Native_File_Chooser::filter() const<br>
152 void Fl_Native_File_Chooser::filter(const char*)
153 </h4>
154 <ul>
155 Gets or sets the filename filters used for browsing.
156 The default is NULL, which browses all files.
157 <p>
158 The filter string can be any of:
159 <p>
160 <ul>
161 <li> A single wildcard (eg. "*.txt")
162 </li>
163 <li> Multiple wildcards (eg. "*.{cxx,h,H})
164 </li>
165 <li> A descriptive name followed by a '\t' and a wildcard
166 (eg. "Text&nbsp;Files\t*.txt")
167 </li>
168 <li> A list of separate wildcards with a \n between each (eg. "*.{cxx,H}\n*.txt")
169 </li>
170 <li> A list of descriptive names and wildcards
171 (eg. "C++ Files\t*.{cxx,H}\nTxt Files\t*.txt")
172 </li>
173 </ul>
174 <p>
175 The format of each filter is a wildcard, or an optional
176 user description followed by '\t' and the wildcard.
177 <p>
178 On most platforms, each filter is available to the user
179 via a pulldown menu in the file chooser. The 'All Files'
180 option is always available to the user.
181 </ul>
182
183 <h4>
184 <a name="filter_value"></a>
185 void Fl_Native_File_Chooser::filter_value(int)<br>
186 int Fl_Native_File_Chooser::filter_value()<br>
187 </h4>
188 <ul>
189 The first form sets which filter will be initially selected.<br>
190 The second returns which filter was chosen. This is only valid
191 if the chooser returns success.<br>
192 <p>
193 The first filter is indexed as 0. If filter_value()==filters(),
194 then "All Files" was chosen. If filter_value() > filters(), then
195 a custom filter was set.<br>
196 </ul>
197
198 <h4>
199 <a name="filters"></a>
200 int Fl_Native_File_Chooser::filters()<br>
201 </h4>
202 <ul>
203 Gets how many filters were available, not including "All Files"
204 </ul>
205
206 <h4>
207 <a name="options"></a>
208 void Fl_Native_File_Chooser::options(int)<br>
209 int Fl_Native_File_Chooser::options()<br>
210 </h4>
211 <ul>
212 Sets/gets the platform specific chooser options.
213 <p>
214 Some platforms have file choosers with specific functions
215 that can be enabled/disabled via this method.
216 <p>
217 Flags can be ORed together to enable several features. Flags currently supported:
218 <p>
219 <center><table cellpadding=3>
220 <tr><td BGCOLOR=#8888cc align=left>Flag </td><td BGCOLOR=#8888cc>Description </td><td BGCOLOR=#8888cc>Win</td><td BGCOLOR=#8888cc>Mac</td><td BGCOLOR=#8888cc>Other</td></tr>
221 <tr><td BGCOLOR=#dddddd align=left><tt>Fl_Native_File_Chooser::SAVEAS_CONFIRM</td><td BGCOLOR=#dddddd>With a BROWSE_SAVEAS chooser, prompts a confirmation if file exists</td><td BGCOLOR=#dddddd>Ignored </td><td BGCOLOR=#88dd88>Used </td><td BGCOLOR=#dddddd>Ignored</td></tr>
222 <tr><td BGCOLOR=#dddddd align=left><tt>Fl_Native_File_Chooser::NEW_FOLDER </td><td BGCOLOR=#dddddd>Shows the 'New Folder' button </td><td BGCOLOR=#dddddd>Ignored </td><td BGCOLOR=#dddddd>Ignored</td><td BGCOLOR=#88dd88>Used</td></tr>
223 <tr><td BGCOLOR=#dddddd align=left><tt>Fl_Native_File_Chooser::PREVIEW </td><td BGCOLOR=#dddddd>Enables the 'Preview' mode by default </td><td BGCOLOR=#dddddd>Ignored </td><td BGCOLOR=#dddddd>Ignored</td><td BGCOLOR=#88dd88>Used</td></tr>
224 </table></center>
225 </ul>
226
227 <h4>
228 <a name="preset_file"></a>
229 void Fl_Native_File_Chooser::preset_file(const char*)<br>
230 const char* Fl_Native_File_Chooser::preset_file()<br>
231 </h4>
232 <ul>
233 Sets a default filename for the chooser.
234 (Use <a href="#directory">directory()</a> to set the default directory)
235 <br>
236 Mainly used to preset the filename for save dialogs,
237 and on most platforms can be used for opening files as well.
238 </ul>
239
240 <h4>
241 <a name="show"></a>
242 int Fl_Native_File_Chooser::show() const<br>
243 </h4>
244 <ul>
245 Opens the current file chooser on the screen. This method
246 will block until the user has chosen something, or cancelled.
247 <p>
248 Return value:
249 <ul type=disc>
250 <li> 0 - user picked a file, filename() will have the result
251 <li> 1 - user hit 'cancel'
252 <li>-1 - failed; <a href="#errmsg">errmsg()</a> has reason
253 </ul>
254 </ul>
255
256 <h4>
257 <a name="title"></a>
258 const char *Fl_Native_File_Chooser::title() const<br>
259 void Fl_Native_File_Chooser::title(const char*)
260 </h4>
261 <ul>
262 Gets or sets the title of the file chooser's window.
263 <p>
264 The default title varies according to the platform, so you
265 are advised to set the title explicitly.
266 </ul>
267
268 <h4><a name="type"></a>
269 int Fl_Native_File_Chooser::type() const<br>
270 Fl_Native_File_Chooser::type(int)
271 </h4>
272 <ul>
273 Gets or sets the current type of browser. Possible choices are:
274 <p>
275 <center><table cellpadding=3>
276 <tr>
277 <td BGCOLOR=#8888cc align=left>Flag</td>
278 <td BGCOLOR=#8888cc>Description</td>
279 </tr><tr>
280 <td BGCOLOR=#dddddd align=left><tt>Fl_Native_File_Chooser::BROWSE_FILE</td>
281 <td BGCOLOR=#dddddd>Browse for a single file</td>
282 </tr><tr>
283 <td BGCOLOR=#dddddd align=left><tt>Fl_Native_File_Chooser::BROWSE_DIRECTORY</td>
284 <td BGCOLOR=#dddddd>Browse for a single directory</td>
285 </tr><tr>
286 <td BGCOLOR=#dddddd align=left><tt>Fl_Native_File_Chooser::BROWSE_MULTI_FILE</td>
287 <td BGCOLOR=#dddddd>Browse for multiple files</td>
288 </tr><tr>
289 <td BGCOLOR=#dddddd align=left><tt>Fl_Native_File_Chooser::BROWSE_MULTI_DIRECTORY</td>
290 <td BGCOLOR=#dddddd>Browse for multiple directories (implementation varies)</td>
291 </tr><tr>
292 <td BGCOLOR=#dddddd align=left><tt>Fl_Native_File_Chooser::BROWSE_SAVE_FILE</td>
293 <td BGCOLOR=#dddddd>Browse to save a single file</td>
294 </tr><tr>
295 <td BGCOLOR=#dddddd align=left><tt>Fl_Native_File_Chooser::BROWSE_SAVE_DIRECTORY</td>
296 <td BGCOLOR=#dddddd>Browse for a directory, allowing creation</td>
297 </tr>
298 </table></center>
299 <p>
300 These may be changed in future versions of Fl_Native_File_Chooser.
301 </ul>
302
303 <h3>Typical Usage</h3>
304 <ul>
305 <pre>
306 #include &lt;Fl_Native_File_Chooser.H&gt;
307 :
308 Fl_Native_File_Chooser *chooser = <b>new Fl_Native_File_Chooser</b>();
309 <b>chooser-&gt;type</b>(Fl_Native_File_Chooser::BROWSE_FILE); <i>// let user browse a single file</i>
310 <b>chooser-&gt;title</b>("Open a file"); <i>// optional title</i>
311 <b>chooser-&gt;preset_file</b>("/var/tmp/somefile.txt"); <i>// optional filename preset</i>
312 <b>chooser-&gt;filter</b>("Text Files\t*.txt"); <i>// optional filter</i>
313 switch ( <b>chooser-&gt;show</b>() ) {
314 case -1: // ERROR
315 fprintf(stderr, "*** ERROR show() failed:%s\n", <b>chooser-&gt;errmsg</b>());
316 break;
317 case 1: // CANCEL
318 fprintf(stderr, "*** CANCEL\n");
319 break;
320 default: // USER PICKED A FILE
321 fprintf(stderr, "Filename was '%s'\n", <b>chooser-&gt;filename</b>());
322 break;
323 }
324 <p><hr><p>
325 <b>// EXAMPLE 'SAVEAS' FILE BROWSER</b>
326 #include &lt;Fl_Native_File_Chooser.H&gt;
327 :
328 Fl_Native_File_Chooser *chooser = <b>new Fl_Native_File_Chooser</b>();
329 <b>chooser-&gt;type</b>(Fl_Native_File_Chooser::BROWSE_SAVE_FILE); <i>// 'saveas' browser</i>
330 <b>chooser-&gt;title</b>("Save As.."); <i>// optional title for chooser window</i>
331 <b>chooser-&gt;directory</b>("/var/tmp"); <i>// optional starting directory</i>
332 <b>chooser-&gt;preset_file</b>("untitled.txt"); <i>// optional default filename</i>
333 <b>chooser-&gt;filter</b>("Text Files\t*.txt"); <i>// optional filter</i>
334 switch ( <b>chooser-&gt;show</b>() ) {
335 case -1: // ERROR
336 fprintf(stderr, "*** ERROR show() failed:%s\n", <b>chooser-&gt;errmsg</b>());
337 break;
338 case 1: // CANCEL
339 fprintf(stderr, "*** CANCEL\n");
340 break;
341 default: // USER PICKED A FILE
342 fprintf(stderr, "Filename was '%s'\n", <b>chooser-&gt;filename</b>());
343 break;
344 }
345 </pre>
346 </ul>
347
348 <br> <br> <br> <br> <br> <br>
349 <br> <br> <br> <br> <br> <br>
350 <br> <br> <br> <br> <br> <br>
351
352 <br> <br> <br> <br> <br> <br>
353 <br> <br> <br> <br> <br> <br>
354 <br> <br> <br> <br> <br> <br>
355
356 <br> <br> <br> <br> <br> <br>
357 <br> <br> <br> <br> <br> <br>
358 <br> <br> <br> <br> <br> <br>
359
360 </body>
361 </html>