source: pkg/pygtk/branches/upstream/current/docs/reference/pygtk-gtkfileselection.xml @ 4

Revision 4, 19.3 KB checked in by alanbach-guest, 6 years ago (diff)

[svn-inject] Installing original source of pygtk
Line 
1<?xml version="1.0" standalone="no"?>
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
4
5<refentry id="class-gtkfileselection">
6  <refnamediv>
7    <refname>gtk.FileSelection</refname>
8    <refpurpose>a dialog used to prompt the user for a file or directory
9    name</refpurpose>
10  </refnamediv>
11
12  <refsect1>
13    <title>Synopsis</title>
14
15    <classsynopsis language="python">
16      <ooclass><classname>gtk.FileSelection</classname></ooclass>
17      <ooclass><classname><link
18linkend="class-gtkdialog">gtk.Dialog</link></classname></ooclass>
19      <constructorsynopsis language="python">
20        <methodname><link
21linkend="constructor-gtkfileselection">gtk.FileSelection</link></methodname>
22        <methodparam><parameter
23                       role="keyword">title</parameter><initializer>None</initializer></methodparam>
24      </constructorsynopsis>
25      <methodsynopsis language="python">
26        <methodname><link
27linkend="method-gtkfileselection--set-filename">set_filename</link></methodname>
28        <methodparam><parameter
29                       role="keyword">filename</parameter></methodparam>
30      </methodsynopsis>
31      <methodsynopsis language="python">
32        <methodname><link
33linkend="method-gtkfileselection--get-filename">get_filename</link></methodname>
34        <methodparam></methodparam>  </methodsynopsis>
35      <methodsynopsis language="python">
36        <methodname><link
37linkend="method-gtkfileselection--complete">complete</link></methodname>
38        <methodparam><parameter
39                       role="keyword">pattern</parameter></methodparam>
40      </methodsynopsis>
41      <methodsynopsis language="python">
42        <methodname><link
43linkend="method-gtkfileselection--show-fileop-buttons">show_fileop_buttons</link></methodname>
44        <methodparam></methodparam>  </methodsynopsis>
45      <methodsynopsis language="python">
46        <methodname><link
47linkend="method-gtkfileselection--hide-fileop-buttons">hide_fileop_buttons</link></methodname>
48        <methodparam></methodparam>  </methodsynopsis>
49      <methodsynopsis language="python">
50        <methodname><link
51linkend="method-gtkfileselection--get-selections">get_selections</link></methodname>
52        <methodparam></methodparam>  </methodsynopsis>
53      <methodsynopsis language="python">
54        <methodname><link
55linkend="method-gtkfileselection--set-select-multiple">set_select_multiple</link></methodname>
56        <methodparam><parameter
57                       role="keyword">select_multiple</parameter></methodparam>
58      </methodsynopsis>
59      <methodsynopsis language="python">
60        <methodname><link
61linkend="method-gtkfileselection--get-select-multiple">get_select_multiple</link></methodname>
62        <methodparam></methodparam>  </methodsynopsis>
63    </classsynopsis>
64
65  </refsect1>
66
67  <refsect1>
68    <title>Ancestry</title>
69
70<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
71  +-- <link linkend="class-gtkobject">gtk.Object</link>
72    +-- <link linkend="class-gtkwidget">gtk.Widget</link>
73      +-- <link linkend="class-gtkcontainer">gtk.Container</link>
74        +-- <link linkend="class-gtkbin">gtk.Bin</link>
75          +-- <link linkend="class-gtkwindow">gtk.Window</link>
76            +-- <link linkend="class-gtkdialog">gtk.Dialog</link>
77              +-- <link linkend="class-gtkfileselection">gtk.FileSelection</link>
78</synopsis>
79
80  </refsect1>
81
82  <refsect1 id="properties-gtkfileselection">
83    <title>gtk.FileSelection Properties</title>
84
85    <para><link linkend="properties-gtkobject">gtk.Object Properties</link></para>
86    <para><link linkend="properties-gtkwidget">gtk.Widget Properties</link></para>
87    <para><link linkend="properties-gtkcontainer">gtk.Container Properties</link></para>
88    <para><link linkend="properties-gtkwindow">gtk.Window Properties</link></para>
89    <para><link linkend="properties-gtkdialog">gtk.Dialog Properties</link></para>
90
91    <blockquote role="properties">
92      <informaltable pgwide="1" frame="none">
93        <tgroup cols="3">
94
95          <colspec column="1" colwidth="1in"/>
96          <colspec column="2" colwidth="1in"/>
97          <colspec column="3" colwidth="3.5in"/>
98          <tbody>
99
100        <row valign="top">
101          <entry>"filename"</entry>
102          <entry>Read/Write</entry>
103          <entry>The currently selected filename.</entry>
104        </row>
105
106        <row valign="top">
107          <entry>"select-multiple"</entry>
108          <entry>Read/Write</entry>
109          <entry>If <literal>True</literal> allow multiple files to be
110          selected.</entry>
111        </row>
112
113        <row valign="top">
114          <entry>"show-fileops"</entry>
115          <entry>Read/Write</entry>
116          <entry>If <literal>True</literal> display the buttons for creating
117          and manipulating files.</entry>
118        </row>
119
120        </tbody>
121      </tgroup>
122      </informaltable>
123    </blockquote>
124
125  </refsect1>
126
127  <refsect1 id="style-properties-gtkfileselection">
128    <title>gtk.FileSelection Style Properties</title>
129
130    <para><link linkend="style-properties-gtkwidget">gtk.Widget Style Properties</link></para>
131    <para><link linkend="style-properties-gtkdialog">gtk.Dialog Style Properties</link></para>
132
133  </refsect1>
134
135  <refsect1>
136    <title>Attributes</title>
137
138    <blockquote role="properties">
139      <informaltable pgwide="1" frame="none">
140        <tgroup cols="3">
141        <?dbhtml cellpadding="5"?>
142          <colspec column="1" colwidth="1in"/>
143          <colspec column="2" colwidth="1in"/>
144          <colspec column="3" colwidth="3.5in"/>
145          <tbody>
146
147            <row valign="top">
148              <entry>"dir_list"</entry>
149              <entry>Read</entry>
150              <entry>The <link
151linkend="class-gtktreeview"><classname>gtk.TreeView</classname></link>
152widget used to display the directories</entry>
153            </row>
154
155            <row valign="top">
156              <entry>"file_list"</entry>
157              <entry>Read</entry>
158              <entry>The <link
159linkend="class-gtktreeview"><classname>gtk.TreeView</classname></link>
160widget used to display the files.</entry>
161            </row>
162
163            <row valign="top">
164              <entry>"selection_entry"</entry>
165              <entry>Read</entry>
166              <entry>The <link
167linkend="class-gtkentry"><classname>gtk.Entry</classname></link> widget used
168to display the current file selection</entry>
169            </row>
170
171            <row valign="top">
172              <entry>"selection_text"</entry>
173              <entry>Read</entry>
174              <entry>The <link
175linkend="class-gtklabel"><classname>gtk.Label</classname></link> associated
176with the selection entry.</entry>
177            </row>
178
179            <row valign="top">
180              <entry>"main_vbox"</entry>
181              <entry>Read</entry>
182              <entry>The <link
183linkend="class-gtkvbox"><classname>gtk.VBox</classname></link> widget that
184holds all the widgets of the <link
185linkend="class-gtkfileselection"><classname>gtk.FileSelection</classname></link> 
186dialog.</entry>
187            </row>
188
189            <row valign="top">
190              <entry>"ok_button"</entry>
191              <entry>Read</entry>
192              <entry>The "OK" button.</entry>
193            </row>
194
195            <row valign="top">
196              <entry>"cancel_button"</entry>
197              <entry>Read</entry>
198              <entry>The "Cancel" button.</entry>
199            </row>
200
201            <row valign="top">
202              <entry>"history_pulldown"</entry>
203              <entry>Read</entry>
204              <entry>The <link
205linkend="class-gtkoptionmenu"><classname>gtk.OptionMenu</classname></link>
206widget that provides the pulldown list of directory paths.</entry>
207            </row>
208
209            <row valign="top">
210              <entry>"history_menu"</entry>
211              <entry>Read</entry>
212              <entry>The <link
213linkend="class-gtkmenu"><classname>gtk.Menu</classname></link> part of the
214<parameter>history_pulldown</parameter></entry>
215            </row>
216
217            <row valign="top">
218              <entry>"fileop_dialog"</entry>
219              <entry>Read</entry>
220              <entry>The dialog box used to display the <link
221linkend="class-gtkfileselection"><classname>gtk.FileSelection</classname></link>.
222It can be customized by adding or removing widgets from it using the
223standard <link
224linkend="class-gtkdialog"><classname>gtk.Dialog</classname></link>
225methods.</entry>
226            </row>
227
228            <row valign="top">
229              <entry>"fileop_entry"</entry>
230              <entry>Read</entry>
231              <entry>The <link
232linkend="class-gtkentry"><classname>gtk.Entry</classname></link> in the
233fileops dialog that is created when one of the fileops buttons is
234clicked.</entry>
235            </row>
236
237            <row valign="top">
238              <entry>"fileop_file"</entry>
239              <entry>Read</entry>
240              <entry>The name of the file to be operated on by the
241fileops</entry>
242            </row>
243
244            <row valign="top">
245              <entry>"fileop_c_dir"</entry>
246              <entry>Read</entry>
247              <entry>The "New Folder" fileops button.</entry>
248            </row>
249
250            <row valign="top">
251              <entry>"fileop_del_file"</entry>
252              <entry>Read</entry>
253              <entry>The "Delete File" fileops button</entry>
254            </row>
255
256            <row valign="top">
257              <entry>"fileop_ren_file"</entry>
258              <entry>Read</entry>
259              <entry>The "Rename File" fileops button</entry>
260            </row>
261
262            <row valign="top">
263              <entry>"button_area"</entry>
264              <entry>Read</entry>
265              <entry>The fileops <link
266linkend="class-gtkbuttonbox"><classname>gtk.ButtonBox</classname></link>.</entry>
267            </row>
268
269            <row valign="top">
270              <entry>"action_area"</entry>
271              <entry>Read</entry>
272              <entry>A <link
273linkend="class-gtkhbox"><classname>gtk.HBox</classname></link> that can be
274used by the application to add buttons, etc.</entry>
275            </row>
276
277          </tbody>
278        </tgroup>
279      </informaltable>
280    </blockquote>
281
282  </refsect1>
283
284  <refsect1 id="signal-prototypes-gtkfileselection">
285    <title>gtk.FileSelection Signal Prototypes</title>
286
287    <para><link linkend="signal-prototypes-gobject">gobject.GObject Signal Prototypes</link></para>
288    <para><link linkend="signal-prototypes-gtkobject">gtk.Object Signal Prototypes</link></para>
289    <para><link linkend="signal-prototypes-gtkwidget">gtk.Widget Signal Prototypes</link></para>
290    <para><link linkend="signal-prototypes-gtkcontainer">gtk.Container Signal Prototypes</link></para>
291    <para><link linkend="signal-prototypes-gtkwindow">gtk.Window Signal Prototypes</link></para>
292    <para><link linkend="signal-prototypes-gtkdialog">gtk.Dialog Signal Prototypes</link></para>
293  </refsect1>
294
295  <refsect1>
296    <title>Description</title>
297
298    <para>The <link
299linkend="class-gtkfileselection"><classname>gtk.FileSelection</classname></link> 
300should be used to retrieve file or directory names from the user. It will
301create a new dialog window containing a directory list, and a file list
302corresponding to the current working directory. The filesystem can be
303navigated using the directory list or the drop-down history menu.
304Alternatively, the <keycap>TAB</keycap> key can be used to navigate using
305filename completion - common in text based editors such as emacs and
306jed.</para>
307
308    <para>File selection dialogs are created with a call to the <link
309linkend="constructor-gtkfileselection"><methodname>gtk.FileSelection</methodname>()</link> 
310constructor.</para>
311
312    <para>The default filename can be set using the <link
313linkend="method-gtkfileselection--set-filename"><methodname>set_filename</methodname>()</link> 
314method and the selected filename retrieved using the <link
315linkend="method-gtkfileselection--get-filename"><methodname>get_filename</methodname>()</link> 
316method.</para>
317
318    <para>Use the <link
319linkend="method-gtkfileselection--complete"><methodname>complete</methodname>()</link> 
320method to display files and directories that match a given pattern. This can
321be used for example, to show only *.txt files, or only files beginning with
322gtk*.</para>
323
324    <para>Simple file operations; create directory, delete file, and rename
325file, are available from buttons at the top of the dialog. These can be
326hidden using the <link
327linkend="method-gtkfileselection--hide-fileop-buttons"><methodname>hide_fileop_buttons</methodname>()</link> 
328method and shown again using the <link
329linkend="method-gtkfileselection--show-fileop-buttons"><methodname>show_fileop_buttons</methodname>()</link> 
330method.</para>
331
332  </refsect1>
333
334  <refsect1 id="constructor-gtkfileselection">
335    <title>Constructor</title>
336
337    <programlisting><constructorsynopsis language="python">
338        <methodname>gtk.FileSelection</methodname>
339        <methodparam><parameter
340                       role="keyword">title</parameter><initializer>None</initializer></methodparam>
341      </constructorsynopsis></programlisting>
342    <variablelist>
343      <varlistentry>
344        <term><parameter role="keyword">title</parameter>&nbsp;:</term>
345        <listitem><simpara>the text to be used as the title of the
346fileselection dialog.</simpara></listitem>
347      </varlistentry>
348      <varlistentry>
349        <term><emphasis>Returns</emphasis>&nbsp;:</term>
350        <listitem><simpara>a new fileselection dialog</simpara></listitem>
351      </varlistentry>
352    </variablelist>
353
354    <para>Creates a new file selection dialog. By default it will contain
355<link
356linkend="class-gtktreeview"><classname>gtk.TreeViews</classname></link>
357displaying the application's current working directory, and its file
358listing. File operation buttons that allow the user to create a directory,
359delete files and rename files, are also present.</para>
360
361  </refsect1>
362
363  <refsect1>
364    <title>Methods</title>
365
366    <refsect2 id="method-gtkfileselection--set-filename">
367      <title>gtk.FileSelection.set_filename</title>
368
369      <programlisting><methodsynopsis language="python">
370          <methodname>set_filename</methodname>
371          <methodparam><parameter
372                         role="keyword">filename</parameter></methodparam>
373        </methodsynopsis></programlisting>
374      <variablelist>
375        <varlistentry>
376          <term><parameter role="keyword">filename</parameter>&nbsp;:</term>
377          <listitem><simpara>a string to set as the default file
378name.</simpara></listitem>
379        </varlistentry>
380      </variablelist>
381
382      <para>The <methodname>set_filename</methodname>() method sets a
383default path for the file requester. If <parameter>filename</parameter>
384includes a directory path, then the fileselection will open with that path
385as its current working directory.</para>
386
387      <para>Note the encoding of <parameter>filename</parameter> is the
388on-disk encoding, which may not be UTF-8.</para>
389
390    </refsect2>
391
392    <refsect2 id="method-gtkfileselection--get-filename">
393      <title>gtk.FileSelection.get_filename</title>
394
395      <programlisting><methodsynopsis language="python">
396          <methodname>get_filename</methodname>
397          <methodparam></methodparam>  </methodsynopsis></programlisting>
398      <variablelist>
399        <varlistentry>
400          <term><emphasis>Returns</emphasis>&nbsp;:</term>
401          <listitem><simpara>currently-selected filename in the on-disk
402encoding</simpara></listitem>
403        </varlistentry>
404      </variablelist>
405
406      <para>The <methodname>get_filename</methodname>() method returns the
407selected filename in the on-disk encoding, which may or may not be the same
408as that used by GTK (UTF-8). If no file is selected then the selected
409directory path is returned.</para>
410
411    </refsect2>
412
413    <refsect2 id="method-gtkfileselection--complete">
414      <title>gtk.FileSelection.complete</title>
415
416      <programlisting><methodsynopsis language="python">
417          <methodname>complete</methodname>
418          <methodparam><parameter
419                         role="keyword">pattern</parameter></methodparam>
420        </methodsynopsis></programlisting>
421      <variablelist>
422        <varlistentry>
423          <term><parameter role="keyword">pattern</parameter>&nbsp;:</term>
424          <listitem><simpara>a string containing a pattern which may or may
425not match any filenames in the current directory.</simpara></listitem>
426        </varlistentry>
427      </variablelist>
428
429      <para>The <methodname>complete</methodname>() method will attempt to
430match <parameter>pattern</parameter> to valid filenames or subdirectories in
431the current directory. If a match can be made, the matched filename will
432appear in the text entry field of the file selection dialog. If a partial
433match can be made, the "Files" list will contain those file names which have
434been partially matched, and the "Directories" list those directories which
435have been partially matched.</para>
436
437    </refsect2>
438
439    <refsect2 id="method-gtkfileselection--show-fileop-buttons">
440      <title>gtk.FileSelection.show_fileop_buttons</title>
441
442      <programlisting><methodsynopsis language="python">
443          <methodname>show_fileop_buttons</methodname>
444          <methodparam></methodparam>  </methodsynopsis></programlisting>
445
446      <para>The <methodname>show_fileop_buttons</methodname>() method shows
447the fileops buttons: "New Folder", "Delete File" and "Rename File".</para>
448
449    </refsect2>
450
451    <refsect2 id="method-gtkfileselection--hide-fileop-buttons">
452      <title>gtk.FileSelection.hide_fileop_buttons</title>
453
454      <programlisting><methodsynopsis language="python">
455          <methodname>hide_fileop_buttons</methodname>
456          <methodparam></methodparam>  </methodsynopsis></programlisting>
457
458      <para>The <methodname>hide_fileop_buttons</methodname>() method hides
459the fileops buttons: "New Folder", "Delete File" and "Rename File".</para>
460
461    </refsect2>
462
463    <refsect2 id="method-gtkfileselection--get-selections">
464      <title>gtk.FileSelection.get_selections</title>
465
466      <programlisting><methodsynopsis language="python">
467          <methodname>get_selections</methodname>
468          <methodparam></methodparam>  </methodsynopsis></programlisting>
469      <variablelist>
470        <varlistentry>
471          <term><emphasis>Returns</emphasis>&nbsp;:</term>
472          <listitem><simpara>a tuple containing the selected
473files.</simpara></listitem>
474        </varlistentry>
475      </variablelist>
476
477      <para>The <methodname>get_selections</methodname>() method retrieves a
478tuple containing the file selections the user has made in the file selection
479dialog. The first file in the list is equivalent to what the <link
480linkend="method-gtkfileselection--get-filename"><methodname>get_filename</methodname>()</link> 
481method would return.</para>
482
483    </refsect2>
484
485    <refsect2 id="method-gtkfileselection--set-select-multiple">
486      <title>gtk.FileSelection.set_select_multiple</title>
487
488      <programlisting><methodsynopsis language="python">
489          <methodname>set_select_multiple</methodname>
490          <methodparam><parameter
491                         role="keyword">select_multiple</parameter></methodparam>
492        </methodsynopsis></programlisting>
493      <variablelist>
494        <varlistentry>
495          <term><parameter
496role="keyword">select_multiple</parameter>&nbsp;:</term>
497          <listitem><simpara>If <literal>True</literal> the user is allowed
498to select multiple files in the file list.</simpara></listitem>
499        </varlistentry>
500      </variablelist>
501
502      <para>The <methodname>set_select_multiple</methodname>() method sets
503the file list selection mode according to the value of
504<parameter>select_multiple</parameter>. If
505<parameter>select_multiple</parameter> is <literal>True</literal> the user
506is allowed to select multiple files in the file list. Use the <link
507linkend="method-gtkfileselection--get-selections"><methodname>get_selections</methodname>()</link> 
508method to retrieve the list of selected files.</para>
509
510    </refsect2>
511
512    <refsect2 id="method-gtkfileselection--get-select-multiple">
513      <title>gtk.FileSelection.get_select_multiple</title>
514
515      <programlisting><methodsynopsis language="python">
516          <methodname>get_select_multiple</methodname>
517          <methodparam></methodparam>  </methodsynopsis></programlisting>
518      <variablelist>
519        <varlistentry>
520          <term><emphasis>Returns</emphasis>&nbsp;:</term>
521          <listitem><simpara><literal>True</literal> if the user is allowed
522to select multiple files in the file list</simpara></listitem>
523        </varlistentry>
524      </variablelist>
525
526      <para>The <methodname>get_select_multiple</methodname>() method
527determines whether the user is allowed to make multiple file selection in
528the file list. If the <methodname>get_select_multiple</methodname>() method
529returns <literal>True</literal> the user is allowed to select multiple files
530in the file list. See the <link
531linkend="method-gtkfileselection--set-select-multiple"><methodname>set_select_multiple</methodname>()</link> 
532method.</para>
533
534    </refsect2>
535
536  </refsect1>
537
538</refentry>
Note: See TracBrowser for help on using the repository browser.