path: root/docs/reference/pygtk-gtkfileselection.xml

<?xml version="1.0" standalone="no"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<refentry id="class-gtkfileselection">
  <refnamediv>
    <refname>gtk.FileSelection</refname>
    <refpurpose>a dialog used to prompt the user for a file or directory
    name</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.FileSelection</classname></ooclass>
      <ooclass><classname><link
linkend="class-gtkdialog">gtk.Dialog</link></classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link
linkend="constructor-gtkfileselection">gtk.FileSelection</link></methodname>
	<methodparam><parameter
		       role="keyword">title</parameter><initializer>None</initializer></methodparam>
      </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkfileselection--set-filename">set_filename</link></methodname>
	<methodparam><parameter
		       role="keyword">filename</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkfileselection--get-filename">get_filename</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkfileselection--complete">complete</link></methodname>
	<methodparam><parameter
		       role="keyword">pattern</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkfileselection--show-fileop-buttons">show_fileop_buttons</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkfileselection--hide-fileop-buttons">hide_fileop_buttons</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkfileselection--get-selections">get_selections</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkfileselection--set-select-multiple">set_select_multiple</link></methodname>
	<methodparam><parameter
		       role="keyword">select_multiple</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkfileselection--get-select-multiple">get_select_multiple</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
    </classsynopsis>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-gtkobject">gtk.Object</link>
    +-- <link linkend="class-gtkwidget">gtk.Widget</link>
      +-- <link linkend="class-gtkcontainer">gtk.Container</link>
        +-- <link linkend="class-gtkbin">gtk.Bin</link>
          +-- <link linkend="class-gtkwindow">gtk.Window</link>
            +-- <link linkend="class-gtkdialog">gtk.Dialog</link>
              +-- <link linkend="class-gtkfileselection">gtk.FileSelection</link>
</synopsis>

  </refsect1>
  
  <refsect1>
		<title>Implemented Interfaces</title>
		<para>
			<link linkend="class-gtkfileselection"><classname>gtk.FileSelection</classname></link>
			implements 
			<link linkend="class-gtkbuildable"><classname>gtk.Buildable</classname></link>
		</para>
	</refsect1>


  <refsect1 id="properties-gtkfileselection">
    <title>gtk.FileSelection Properties</title>

    <para><link linkend="properties-gtkobject">gtk.Object Properties</link></para>
    <para><link linkend="properties-gtkwidget">gtk.Widget Properties</link></para>
    <para><link linkend="properties-gtkcontainer">gtk.Container Properties</link></para>
    <para><link linkend="properties-gtkwindow">gtk.Window Properties</link></para>
    <para><link linkend="properties-gtkdialog">gtk.Dialog Properties</link></para>

    <blockquote role="properties">
      <informaltable pgwide="1" frame="none">
	<tgroup cols="3">

	  <colspec column="1" colwidth="1in"/>
	  <colspec column="2" colwidth="1in"/>
	  <colspec column="3" colwidth="3.5in"/>
	  <tbody>

	<row valign="top">
	  <entry>"filename"</entry>
	  <entry>Read/Write</entry>
	  <entry>The currently selected filename.</entry>
	</row>

	<row valign="top">
	  <entry>"select-multiple"</entry>
	  <entry>Read/Write</entry>
	  <entry>If <literal>True</literal> allow multiple files to be
	  selected.</entry>
	</row>

        <row valign="top">
          <entry>"show-fileops"</entry>
          <entry>Read/Write</entry>
          <entry>If <literal>True</literal> display the buttons for creating
          and manipulating files.</entry>
        </row>

	</tbody>
      </tgroup>
      </informaltable>
    </blockquote>

  </refsect1>

  <refsect1 id="style-properties-gtkfileselection">
    <title>gtk.FileSelection Style Properties</title>

    <para><link linkend="style-properties-gtkwidget">gtk.Widget Style Properties</link></para>
    <para><link linkend="style-properties-gtkdialog">gtk.Dialog Style Properties</link></para>

  </refsect1>

  <refsect1>
    <title>Attributes</title>

    <blockquote role="properties">
      <informaltable pgwide="1" frame="none">
	<tgroup cols="3">
	<?dbhtml cellpadding="5"?>
	  <colspec column="1" colwidth="1in"/>
	  <colspec column="2" colwidth="1in"/>
	  <colspec column="3" colwidth="3.5in"/>
	  <tbody>

	    <row valign="top">
	      <entry>"dir_list"</entry>
	      <entry>Read</entry>
	      <entry>The <link
linkend="class-gtktreeview"><classname>gtk.TreeView</classname></link>
widget used to display the directories</entry>
	    </row>

	    <row valign="top">
	      <entry>"file_list"</entry>
	      <entry>Read</entry>
	      <entry>The <link
linkend="class-gtktreeview"><classname>gtk.TreeView</classname></link>
widget used to display the files.</entry>
	    </row>

	    <row valign="top">
	      <entry>"selection_entry"</entry>
	      <entry>Read</entry>
	      <entry>The <link
linkend="class-gtkentry"><classname>gtk.Entry</classname></link> widget used
to display the current file selection</entry>
	    </row>

	    <row valign="top">
	      <entry>"selection_text"</entry>
	      <entry>Read</entry>
	      <entry>The <link
linkend="class-gtklabel"><classname>gtk.Label</classname></link> associated
with the selection entry.</entry>
	    </row>

	    <row valign="top">
	      <entry>"main_vbox"</entry>
	      <entry>Read</entry>
	      <entry>The <link
linkend="class-gtkvbox"><classname>gtk.VBox</classname></link> widget that
holds all the widgets of the <link
linkend="class-gtkfileselection"><classname>gtk.FileSelection</classname></link> 
dialog.</entry>
	    </row>

	    <row valign="top">
	      <entry>"ok_button"</entry>
	      <entry>Read</entry>
	      <entry>The "OK" button.</entry>
	    </row>

	    <row valign="top">
	      <entry>"cancel_button"</entry>
	      <entry>Read</entry>
	      <entry>The "Cancel" button.</entry>
	    </row>

	    <row valign="top">
	      <entry>"history_pulldown"</entry>
	      <entry>Read</entry>
	      <entry>The <link
linkend="class-gtkoptionmenu"><classname>gtk.OptionMenu</classname></link>
widget that provides the pulldown list of directory paths.</entry>
	    </row>

	    <row valign="top">
	      <entry>"history_menu"</entry>
	      <entry>Read</entry>
	      <entry>The <link
linkend="class-gtkmenu"><classname>gtk.Menu</classname></link> part of the
<parameter>history_pulldown</parameter></entry>
	    </row>

	    <row valign="top">
	      <entry>"fileop_dialog"</entry>
	      <entry>Read</entry>
	      <entry>The dialog box used to display the <link
linkend="class-gtkfileselection"><classname>gtk.FileSelection</classname></link>. 
It can be customized by adding or removing widgets from it using the
standard <link
linkend="class-gtkdialog"><classname>gtk.Dialog</classname></link>
methods.</entry>
	    </row>

	    <row valign="top">
	      <entry>"fileop_entry"</entry>
	      <entry>Read</entry>
	      <entry>The <link
linkend="class-gtkentry"><classname>gtk.Entry</classname></link> in the
fileops dialog that is created when one of the fileops buttons is
clicked.</entry>
	    </row>

	    <row valign="top">
	      <entry>"fileop_file"</entry>
	      <entry>Read</entry>
	      <entry>The name of the file to be operated on by the
fileops</entry>
	    </row>

	    <row valign="top">
	      <entry>"fileop_c_dir"</entry>
	      <entry>Read</entry>
	      <entry>The "New Folder" fileops button.</entry>
	    </row>

	    <row valign="top">
	      <entry>"fileop_del_file"</entry>
	      <entry>Read</entry>
	      <entry>The "Delete File" fileops button</entry>
	    </row>

	    <row valign="top">
	      <entry>"fileop_ren_file"</entry>
	      <entry>Read</entry>
	      <entry>The "Rename File" fileops button</entry>
	    </row>

	    <row valign="top">
	      <entry>"button_area"</entry>
	      <entry>Read</entry>
	      <entry>The fileops <link
linkend="class-gtkbuttonbox"><classname>gtk.ButtonBox</classname></link>.</entry>
	    </row>

	    <row valign="top">
	      <entry>"action_area"</entry>
	      <entry>Read</entry>
	      <entry>A <link
linkend="class-gtkhbox"><classname>gtk.HBox</classname></link> that can be
used by the application to add buttons, etc.</entry>
	    </row>

	  </tbody>
	</tgroup>
      </informaltable>
    </blockquote>

  </refsect1>

  <refsect1 id="signal-prototypes-gtkfileselection">
    <title>gtk.FileSelection Signal Prototypes</title>

    <para><link linkend="signal-prototypes-gobject">gobject.GObject Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkobject">gtk.Object Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkwidget">gtk.Widget Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkcontainer">gtk.Container Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkwindow">gtk.Window Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkdialog">gtk.Dialog Signal Prototypes</link></para>
  </refsect1>

  <refsect1>
    <title>Description</title>

    <note>
      <para>The <link linkend="class-gtkfileselection"><classname>gtk.FileSelection</classname></link> is
      deprecated and should not be used in newly-written code.</para>
    </note>

    <para>The <link
linkend="class-gtkfileselection"><classname>gtk.FileSelection</classname></link> 
should be used to retrieve file or directory names from the user. It will
create a new dialog window containing a directory list, and a file list
corresponding to the current working directory. The filesystem can be
navigated using the directory list or the drop-down history menu.
Alternatively, the <keycap>TAB</keycap> key can be used to navigate using
filename completion - common in text based editors such as emacs and
jed.</para>

    <para>File selection dialogs are created with a call to the <link
linkend="constructor-gtkfileselection"><methodname>gtk.FileSelection</methodname>()</link> 
constructor.</para>

    <para>The default filename can be set using the <link
linkend="method-gtkfileselection--set-filename"><methodname>set_filename</methodname>()</link> 
method and the selected filename retrieved using the <link
linkend="method-gtkfileselection--get-filename"><methodname>get_filename</methodname>()</link> 
method.</para>

    <para>Use the <link
linkend="method-gtkfileselection--complete"><methodname>complete</methodname>()</link> 
method to display files and directories that match a given pattern. This can
be used for example, to show only *.txt files, or only files beginning with
gtk*.</para>

    <para>Simple file operations; create directory, delete file, and rename
file, are available from buttons at the top of the dialog. These can be
hidden using the <link
linkend="method-gtkfileselection--hide-fileop-buttons"><methodname>hide_fileop_buttons</methodname>()</link> 
method and shown again using the <link
linkend="method-gtkfileselection--show-fileop-buttons"><methodname>show_fileop_buttons</methodname>()</link> 
method.</para>

  </refsect1>

  <refsect1 id="constructor-gtkfileselection">
    <title>Constructor</title>

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.FileSelection</methodname>
	<methodparam><parameter
		       role="keyword">title</parameter><initializer>None</initializer></methodparam>
      </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><parameter role="keyword">title</parameter>&nbsp;:</term>
	<listitem><simpara>the text to be used as the title of the
fileselection dialog.</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>a new fileselection dialog</simpara></listitem>
      </varlistentry>
    </variablelist>

    <para>Creates a new file selection dialog. By default it will contain
<link
linkend="class-gtktreeview"><classname>gtk.TreeViews</classname></link>
displaying the application's current working directory, and its file
listing. File operation buttons that allow the user to create a directory,
delete files and rename files, are also present.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkfileselection--set-filename">
      <title>gtk.FileSelection.set_filename</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_filename</methodname>
	  <methodparam><parameter
			 role="keyword">filename</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">filename</parameter>&nbsp;:</term>
	  <listitem><simpara>a string to set as the default file
name.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_filename</methodname>() method sets a
default path for the file requester. If <parameter>filename</parameter>
includes a directory path, then the fileselection will open with that path
as its current working directory.</para>

      <para>Note the encoding of <parameter>filename</parameter> is the
on-disk encoding, which may not be UTF-8.</para>

    </refsect2>

    <refsect2 id="method-gtkfileselection--get-filename">
      <title>gtk.FileSelection.get_filename</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_filename</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>currently-selected filename in the on-disk
encoding</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_filename</methodname>() method returns the
selected filename in the on-disk encoding, which may or may not be the same
as that used by GTK (UTF-8). If no file is selected then the selected
directory path is returned.</para>

    </refsect2>

    <refsect2 id="method-gtkfileselection--complete">
      <title>gtk.FileSelection.complete</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>complete</methodname>
	  <methodparam><parameter
			 role="keyword">pattern</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">pattern</parameter>&nbsp;:</term>
	  <listitem><simpara>a string containing a pattern which may or may
not match any filenames in the current directory.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>complete</methodname>() method will attempt to
match <parameter>pattern</parameter> to valid filenames or subdirectories in
the current directory. If a match can be made, the matched filename will
appear in the text entry field of the file selection dialog. If a partial
match can be made, the "Files" list will contain those file names which have
been partially matched, and the "Directories" list those directories which
have been partially matched.</para>

    </refsect2>

    <refsect2 id="method-gtkfileselection--show-fileop-buttons">
      <title>gtk.FileSelection.show_fileop_buttons</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>show_fileop_buttons</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>

      <para>The <methodname>show_fileop_buttons</methodname>() method shows
the fileops buttons: "New Folder", "Delete File" and "Rename File".</para>

    </refsect2>

    <refsect2 id="method-gtkfileselection--hide-fileop-buttons">
      <title>gtk.FileSelection.hide_fileop_buttons</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>hide_fileop_buttons</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>

      <para>The <methodname>hide_fileop_buttons</methodname>() method hides
the fileops buttons: "New Folder", "Delete File" and "Rename File".</para>

    </refsect2>

    <refsect2 id="method-gtkfileselection--get-selections">
      <title>gtk.FileSelection.get_selections</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_selections</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a tuple containing the selected
files.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_selections</methodname>() method retrieves a
tuple containing the file selections the user has made in the file selection
dialog. The first file in the list is equivalent to what the <link
linkend="method-gtkfileselection--get-filename"><methodname>get_filename</methodname>()</link> 
method would return.</para>

    </refsect2>

    <refsect2 id="method-gtkfileselection--set-select-multiple">
      <title>gtk.FileSelection.set_select_multiple</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_select_multiple</methodname>
	  <methodparam><parameter
			 role="keyword">select_multiple</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">select_multiple</parameter>&nbsp;:</term>
	  <listitem><simpara>If <literal>True</literal> the user is allowed
to select multiple files in the file list.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_select_multiple</methodname>() method sets
the file list selection mode according to the value of
<parameter>select_multiple</parameter>. If
<parameter>select_multiple</parameter> is <literal>True</literal> the user
is allowed to select multiple files in the file list. Use the <link
linkend="method-gtkfileselection--get-selections"><methodname>get_selections</methodname>()</link> 
method to retrieve the list of selected files.</para>

    </refsect2>

    <refsect2 id="method-gtkfileselection--get-select-multiple">
      <title>gtk.FileSelection.get_select_multiple</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_select_multiple</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if the user is allowed
to select multiple files in the file list</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_select_multiple</methodname>() method
determines whether the user is allowed to make multiple file selection in
the file list. If the <methodname>get_select_multiple</methodname>() method
returns <literal>True</literal> the user is allowed to select multiple files
in the file list. See the <link
linkend="method-gtkfileselection--set-select-multiple"><methodname>set_select_multiple</methodname>()</link> 
method.</para>

    </refsect2>

  </refsect1>

</refentry>