path: root/docs/reference/pygtk-gtkfilechooserbutton.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-gtkfilechooserbutton">
  <refnamediv>
    <refname>gtk.FileChooserButton</refname>
    <refpurpose>a button to launch a <link
linkend="class-gtkfilechooserdialog"><classname>gtk.FileChooserDialog</classname></link>
(new in PyGTK 2.6)</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

<classsynopsis language="python">
  <ooclass><classname>gtk.FileChooserButton</classname></ooclass>
  <ooclass><classname><link linkend="class-gtkhbox">gtk.HBox</link></classname></ooclass>
<constructorsynopsis language="python">
    <methodname><link linkend="constructor-gtkfilechooserbutton">gtk.FileChooserButton</link></methodname>
    <methodparam><parameter role="keyword">title</parameter></methodparam>
    <methodparam><parameter role="keyword">backend</parameter><initializer>None</initializer></methodparam>
  </constructorsynopsis>
<constructorsynopsis language="python">
    <methodname><link linkend="constructor-gtkfilechooserbutton2">gtk.FileChooserButton</link></methodname>
    <methodparam><parameter role="keyword">dialog</parameter></methodparam>
  </constructorsynopsis>
<methodsynopsis language="python">
    <methodname><link linkend="method-gtkfilechooserbutton--get-title">get_title</link></methodname>
    <methodparam><parameter role="keyword"></parameter></methodparam>
  </methodsynopsis>
<methodsynopsis language="python">
    <methodname><link linkend="method-gtkfilechooserbutton--set-title">set_title</link></methodname>
    <methodparam><parameter role="keyword">title</parameter></methodparam>
  </methodsynopsis>
<methodsynopsis language="python">
    <methodname><link linkend="method-gtkfilechooserbutton--get-width-chars">get_width_chars</link></methodname>
    <methodparam><parameter role="keyword"></parameter></methodparam>
  </methodsynopsis>
<methodsynopsis language="python">
    <methodname><link linkend="method-gtkfilechooserbutton--set-width-chars">set_width_chars</link></methodname>
    <methodparam><parameter role="keyword">n_chars</parameter></methodparam>
  </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkfilechooserbutton--get-focus-on-click">get_focus_on_click</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkfilechooserbutton--set-focus-on-click">set_focus_on_click</link></methodname>
        <methodparam><parameter role="keyword">focus_on_click</parameter></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-gtkbox">gtk.Box</link>
           +-- <link linkend="class-gtkhbox">gtk.HBox</link>
             +-- <link linkend="class-gtkfilechooserbutton">gtk.FileChooserButton</link> (implements <link linkend="class-gtkfilechooser">gtk.FileChooser</link>)</synopsis>

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

  <refsect1 id="properties-gtkfilechooserbutton">
    <title>gtk.FileChooserButton Properties</title>

    <para><link linkend="properties-gtkfilechooser">gtk.FileChooser Properties</link></para>
    <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-gtkbox">gtk.Box 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="4in"/>
	  <tbody>

	    <row valign="top">
	      <entry>"dialog"</entry>
	      <entry>Write-Construct Only</entry>

	      <entry>The <link
	      linkend="class-gtkfilechooserdialog"><classname>gtk.FileChooserDialog</classname></link>
	      associated with the button. Available in GTK+ 2.6.</entry>
	    </row>

	    <row valign="top">
	      <entry>"focus-on-click"</entry>
	      <entry>Read-Write</entry>

	      <entry>If <literal>True</literal> the <link
	      linkend="class-gtkfilechooserbutton"><classname>gtk.FileChooserButton</classname></link>
	      button grabs focus when it is clicked with the mouse. Default
	      value: <literal>True</literal>. Available in GTK+
	      2.10.</entry>
	    </row>

	    <row valign="top">
	      <entry>"title"</entry>
	      <entry>Read-Write</entry>

	      <entry>The string to use as the title on the <link
	      linkend="class-gtkfilechooserdialog"><classname>gtk.FileChooserDialog</classname></link>
	      associated with the button. Default value: "Select A
	      File". Available in GTK+ 2.6.</entry>
	    </row>

	    <row valign="top">
	      <entry>"width-chars"</entry>
	      <entry>Read-Write</entry>

	      <entry>The width of the entry and label inside the button, in
	      characters. Allowed values: >= -1. Default value:
	      -1. Available in GTK+ 2.6.</entry>
	    </row>

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

  </refsect1>

  <refsect1 id="style-properties-gtkfilechooserbutton">
    <title>gtk.FileChooserButton Style Properties</title>

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

  </refsect1>

  <refsect1 id="child-properties-gtkfilechooserbutton">
    <title>gtk.FileChooserButton Child Properties</title>

    <para><link linkend="child-properties-gtkbox">gtk.Box Child Properties</link></para>

  </refsect1>

  <refsect1 id="signal-prototypes-gtkfilechooserbutton">
    <title>gtk.FileChooserButton 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-gtkfilechooser">gtk.FileChooser Signal Prototypes</link></para>
    
    <variablelist>
      <varlistentry>
        <term>"<link linkend="signal-gtkfilechooserbutton--file-set">file-set</link>"</term>
        <listitem>
          <methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>filechooserbutton</parameter>
            </methodparam>
            <methodparam><parameter>user_param1</parameter>
            </methodparam>
            <methodparam><parameter>...</parameter>
            </methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Description</title>

    <note>
      <para>This widget is available in PyGTK 2.6 and above.</para>
    </note>

    <para>The <link
    linkend="class-gtkfilechooserbutton"><classname>gtk.FileChooserButton</classname></link>
    is a widget that lets the user select a file. It implements the <link
    linkend="class-gtkfilechooser"><classname>gtk.FileChooser</classname></link>
    interface. Visually, it is a file name with a button to bring up a <link
    linkend="class-gtkfilechooserdialog"><classname>gtk.FileChooserDialog</classname></link>. The
    user can then use that dialog to change the file associated with that
    button. This widget does not support setting the "select-multiple"
    property to <literal>True</literal>. For example to create a <link
    linkend="class-gtkfilechooserbutton"><classname>gtk.FileChooserButton</classname></link>
    and set the current folder to '/etc' use:</para>

    <programlisting>
  filechooserbutton = gtk.FileChooserButton('Select a File')
  filechooserbutton.set_current_folder('/etc')
</programlisting>

    <para>The <link
    linkend="class-gtkfilechooserbutton"><classname>gtk.FileChooserButton</classname></link>
    supports the <literal>gtk.FILE_CHOOSER_ACTION_OPEN</literal> and
    <literal>gtk.FILE_CHOOSER_ACTION_SELECT_FOLDER</literal> actions of the
    <xref linkend="gtk-filechooser-action-constants"
    endterm="gtk-filechooser-action-constants-title"></xref>.</para>

    <note>
      <para>The <link
      linkend="class-gtkfilechooserbutton"><classname>gtk.FileChooserButton</classname></link>
      will ellipsize the label, and thus will thus request little horizontal
      space. To give the button more space, you should call the <link
      linkend="method-gtkwidget--size-request"><methodname>gtk.Widget.size_request</methodname>()</link>
      method, the <link
      linkend="method-gtkfilechooserbutton--set-width-chars"><methodname>set_width_chars</methodname>()</link>
      method, or pack the button in such a way that other interface elements
      give space to the widget.</para>
    </note>

  </refsect1>

  <refsect1>
    <title>Constructor</title>

    <refsect2 id="constructor-gtkfilechooserbutton">
      <title>gtk.FileChooserButton</title>

      <programlisting><constructorsynopsis language="python">
          <methodname>gtk.FileChooserButton</methodname>
          <methodparam><parameter
                         role="keyword">title</parameter></methodparam>
          <methodparam><parameter
                         role="keyword">backend</parameter><initializer>None</initializer></methodparam>
        </constructorsynopsis></programlisting>
      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">title</parameter>&nbsp;:</term>
          <listitem><simpara>the title of the browse dialog</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter role="keyword">backend</parameter>&nbsp;:</term>
          <listitem><simpara>the name of a file system backend or
<literal>None</literal></simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>a new <link
linkend="class-gtkfilechooserbutton"><classname>gtk.FileChooserButton</classname></link></simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This constructor is available in PyGTK 2.6 and above.</para>
      </note>

      <para>Creates a new button widget that opens a <link
linkend="class-gtkfilechooserdialog"><classname>gtk.FileChooserDialog</classname></link>
when clicked. The title of the <link
linkend="class-gtkfilechooserdialog"><classname>gtk.FileChooserDialog</classname></link>
is specified by <parameter>title</parameter>. If
<parameter>backend</parameter> is specified it is the name of a file system
backend.</para>

    </refsect2>

    <refsect2 id="constructor-gtkfilechooserbutton2">
      <title>gtk.FileChooserButton</title>

      <programlisting><constructorsynopsis language="python">
          <methodname>gtk.FileChooserButton</methodname>
          <methodparam><parameter
                         role="keyword">dialog</parameter></methodparam>
        </constructorsynopsis></programlisting>
      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">dialog</parameter>&nbsp;:</term>
          <listitem><simpara>a <link linkend="class-gtkfilechooserdialog"><classname>gtk.FileChooserDialog</classname></link></simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>a new <link
linkend="class-gtkfilechooserbutton"><classname>gtk.FileChooserButton</classname></link></simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This constructor is available in PyGTK 2.6 and above.</para>
      </note>

      <para>Creates a new button widget that opens a <link
linkend="class-gtkfilechooserdialog"><classname>gtk.FileChooserDialog</classname></link>
specified by <parameter>dialog</parameter> when clicked.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkfilechooserbutton--get-title">
      <title>gtk.FileChooserButton.get_title</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_title</methodname>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the title of the <link
linkend="class-gtkfilechooserdialog"><classname>gtk.FileChooserDialog</classname></link></simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.6 and above.</para>
      </note>

      <para>The <methodname>get_title</methodname>() method returns the
value of the "title" property which contains the title of the associated
<link
linkend="class-gtkfilechooserdialog"><classname>gtk.FileChooserDialog</classname></link>.</para>

    </refsect2>

    <refsect2 id="method-gtkfilechooserbutton--set-title">
      <title>gtk.FileChooserButton.set_title</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_title</methodname>
	  <methodparam><parameter
			 role="keyword">title</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">title</parameter>&nbsp;:</term>
	  <listitem><simpara>a string to use as the title of the associated 
<link
linkend="class-gtkfilechooserdialog"><classname>gtk.FileChooserDialog</classname></link>.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.6 and above.</para>
      </note>

      <para>The <methodname>set_title</methodname>() method sets the "title"
property to the value of <parameter>title</parameter>. The "title" property
contains the title string of the associated <link
linkend="class-gtkfilechooserdialog"><classname>gtk.FileChooserDialog</classname></link>.</para>

    </refsect2>

    <refsect2 id="method-gtkfilechooserbutton--get-width-chars">
      <title>gtk.FileChooserButton.get_width_chars</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_width_chars</methodname>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <term><parameter
role="keyword"></parameter>&nbsp;:</term>
	  <listitem><simpara>the width in characters of the
button</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.6 and above.</para>
      </note>

      <para>The <methodname>get_width_chars</methodname>() method returns
the value of the "width-characters" property which contains the number of
characters the button width should be set to.</para>

    </refsect2>

    <refsect2 id="method-gtkfilechooserbutton--set-width-chars">
      <title>gtk.FileChooserButton.set_width_chars</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_width_chars</methodname>
	  <methodparam><parameter
			 role="keyword">n_chars</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">n_chars</parameter>&nbsp;:</term>
	  <listitem><simpara>the width in characters for the
button</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.6 and above.</para>
      </note>

      <para>The <methodname>set_width_chars</methodname>() method sets the
"width-chars" property to the value of <parameter>n_chars</parameter>. The
"width-chars" property contains the width in characters that the button
should be set to.</para>

    </refsect2>

    <refsect2 id="method-gtkfilechooserbutton--get-focus-on-click">
      <title>gtk.FileChooserButton.get_focus_on_click</title>

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

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara><literal>True</literal> if the button grabs
          focus when it is clicked with the mouse.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.10 and above.</para>
      </note>

      <para>The <methodname>get_focus_on_click</methodname>() method returns
      the value of the "focus-on-click" property. If the return value is
      <literal>True</literal> if the button grabs focus when it is clicked
      with the mouse.  See the <link
      linkend="method-gtkfilechooserbutton--set-focus-on-click"><methodname>set_focus_on_click()</methodname></link>
      method.</para>

    </refsect2>

    <refsect2 id="method-gtkfilechooserbutton--set-focus-on-click">
      <title>gtk.FileChooserButton.set_focus_on_click</title>

      <programlisting><methodsynopsis language="python">
        <methodname>set_focus_on_click</methodname>
        <methodparam><parameter role="keyword">focus_on_click</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">focus_on_click</parameter>&nbsp;:</term>
          <listitem><simpara>If <literal>True</literal>, the button grabs
          focus when clicked with the mouse</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.10 and above.</para>
      </note>

      <para>The <methodname>set_focus_on_click</methodname>() method sets
      the "focus-on-click" property to the value of
      <parameter>focus_on_click</parameter>.  If
      <parameter>focus_on_click</parameter> is <literal>True</literal>, the
      button will grab focus when it is clicked with the mouse.  Making
      mouse clicks not grab focus is useful in places like toolbars where
      you don't want the keyboard focus removed from the main area of the
      application.</para>

    </refsect2>

  </refsect1><refsect1>
    <title>Signals</title>

    <refsect2 id="signal-gtkfilechooserbutton--file-set">
      <title>The "file-set" gtk.FileChooserButton Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>filechooserbutton</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>filechooserbutton</parameter>&nbsp;:</term>
	  <listitem><simpara>the filechooserbutton that received the signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified with the
	  <link linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
	  method</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional user parameters (if any)</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This signal is available in GTK+ 2.12 and above.</para>
      </note>

      <para>
	  The "file-set" signal is emitted when the user selects a file. 
      </para>
      <para>
	  Note that this signal is only emitted when the user changes the file.
      </para>

    </refsect2>
  </refsect1>

</refentry>