<?xml version='1.0' encoding='UTF-8'?>
<page xmlns="http://projectmallard.org/1.0/"
      xmlns:its="http://www.w3.org/2005/11/its"
      xmlns:xi="http://www.w3.org/2001/XInclude"
      type="guide" style="task"
      id="filechooserdialog.py">
  <info>
    <title type="text">FileChooserDialog (Python)</title>
    <link type="guide" xref="beginner.py#file-selectors"/>
    <link type="seealso" xref="gmenu.py"/>
    <link type="seealso" xref="toolbar_builder.py"/>
    <link type="seealso" xref="textview.py"/>
    <link type="next" xref="combobox.py"/>
    <revision version="0.1" date="2012-08-14" status="draft"/>

    <credit type="author copyright">
      <name>Marta Maria Casetti</name>
      <email its:translate="no">mmcasetti@gmail.com</email>
      <years>2012</years>
    </credit>

    <desc>A dialog suitable for "Open" and "Save" commands</desc>
  </info>

  <title>FileChooserDialog</title>
  <media type="image" mime="image/png" src="media/filechooserdialog_save.png"/>
  <p>This FileChooserDialog saves a text document, which can be opened or written from scratch in a TextView (see below).</p>
  <media type="image" mime="image/png" src="media/filechooserdialog_menu.png"/>
  <p>It is also possible to call a FileChooserDialog to open a new document.</p>

  <links type="sections" />
  
  <section id="overview">
  <title>Steps to recreate the example</title>
  <steps>
    <item><p>Create a file .ui to describe an app-menu with items "New", "Open", "Save", "Save as", and "Quit". This can be done with Glade or in a text editor. See <link xref="#xml" /></p></item>
    <item><p>Create a Python program for a Gtk.TextView with a Gtk.Buffer <code>self.buffer</code>, and a <code>self.file</code> which will be a Gio.File and we set initially as <code>None</code>.</p></item>
    <item><p>In this program, create also the actions corresponding to the items in the app-menu, connect them to callback functions, and import the menu in the <code>do_startup()</code> method with a Gtk.Builder.</p></item>
    <item><p>"New" and "Quit" actions and callback functions are quite straightforward, see <link xref="#code" />. See <link xref="signals-callbacks.py"/> for a more detailed explanation of signals and callback functions.</p></item>
    <item><p>"Open" callback should create and open a Gtk.FileChooserDialog for "Open", connected with another callback function for each of the two "Open" and "Cancel" buttons of the FileChooserDialog.</p></item>
    <item><p>"Save as" works basically as "Open", but the callback function of the "Save" button depends on a more complex method <code>save_to_file()</code>.</p></item>
    <item><p>"Save" can be reduced to the case where the file is <code>None</code>, that is the case where <code>self.file</code> is a new file, which in turn is the case "Save as"; and to the case where the file is not <code>None</code>, which in turn is reduced to <code>save_to_file()</code>.</p></item>
    <item><p>Finally, the method <code>save_to_file()</code>: see <link xref="#code" />, lines 146 - 175.</p></item>
  </steps>
  </section>
  
  <section id="xml">
  <title>XML file which creates the app-menu</title>
  <code mime="application/xml" style="numbered"><xi:include href="samples/filechooserdialog.ui" parse="text"><xi:fallback/></xi:include></code>
  </section>
  
  <section id="code">
  <title>Code used to generate this example</title>
  <code mime="text/x-python" style="numbered"><xi:include href="samples/filechooserdialog.py" parse="text"><xi:fallback/></xi:include></code>
  </section>
  
  <section id="methods">
  <title>Useful methods for a FileChooserDialog</title>
    <p>Note that the action of the FileChooserDialog can be one of the following: <code>Gtk.FileChooserAction.OPEN</code> (the file chooser will only let the user pick an existing file) <code>Gtk.FileChooserAction.SAVE</code> (the file chooser will let the user pick an existing file, or type in a new filename), <code>Gtk.FileChooserAction.SELECT_FOLDER</code> (the file chooser will let the user pick an existing folder), <code>Gtk.FileChooserAction.CREATE_FOLDER</code> (the file chooser will let the user name an existing or new folder).</p>
    <p>Besides the methods used in the <link xref="#code" />, we have:</p>
    <list>
      <item><p><code>set_show_hidden(True)</code> is used to display hidden files and folders.</p></item>
      <item><p><code>set_select_multiple(True)</code> sets that multiple files can be selected. This is only relevant if the mode is <code>Gtk.FileChooserAction.OPEN</code> or <code>Gtk.FileChooserAction.SELECT_FOLDER</code>.</p></item>
      <item><p>In a "Save as" dialog, <code>set_current_name(current_name)</code> sets <code>current_name</code> in the file selector, as if entered by the user; <code>current_name</code> can be something like <em>Untitled.txt</em>. This method should not be used except in a "Save as" dialog.</p></item>
      <item><p>The default current folder is "recent items". To set another folder use <code>set_current_folder_uri(uri)</code>; but note you should use this method and cause the file chooser to show a specific folder only when you are doing a "Save as" command and you already have a file saved somewhere.</p></item>
    </list>
  </section>

  <section id="references">
  <title>API References</title>
  <p>In this sample we used the following:</p>
  <list>
    <item><p><link href="http://developer.gnome.org/gtk3/stable/GtkFileChooserDialog.html">GtkFileChooserDialog</link></p></item>
    <item><p><link href="http://developer.gnome.org/gtk3/stable/GtkFileChooser.html">GtkFileChooser</link></p></item>
    <item><p><link href="http://developer.gnome.org/gtk3/stable/GtkWindow.html">GtkWindow</link></p></item>
    <item><p><link href="http://developer.gnome.org/gtk3/stable/GtkTextView.html">GtkTextView</link></p></item>
    <item><p><link href="http://developer.gnome.org/gtk3/stable/GtkTextBuffer.html">GtkTextBuffer</link></p></item>
    <item><p><link href="http://developer.gnome.org/gtk3/stable/GtkScrolledWindow.html">GtkScrolledWindow</link></p></item>
    <item><p><link href="http://developer.gnome.org/gio/stable/GFile.html">GFile</link></p></item>
    <item><p><link href="http://developer.gnome.org/gio/stable/GSimpleAction.html">GSimpleAction</link></p></item>
    <item><p><link href="http://developer.gnome.org/gtk3/stable/GtkBuilder.html">GtkBuilder</link></p></item>
  </list>
  </section>
</page>