GNOME.org
 

[gtkmm-documentation] Update the Recently Used Documents chapter to gtkmm3 status.

commit 34fd2675961e5b76c8beb65e07945736d9f984c4
Author: Kjell Ahlstedt <kjell ahlstedt bredband net>
Date:   Tue Oct 4 16:44:04 2011 +0200

    Update the Recently Used Documents chapter to gtkmm3 status.
    
    * examples/book/recent_files/examplewindow.[h|cc]: Remove obsolete comments.
    Add on_menu_file_recent_files_item().
    * docs/tutorial/C/gtkmm-tutorial-in.xml: Update the Recently Used Documents
    chapter to gtkmm3 status. Bug #658265.

 ChangeLog                                   |    9 +++
 docs/tutorial/C/gtkmm-tutorial-in.xml       |   81 +++++++++++++++-----------
 examples/book/recent_files/examplewindow.cc |   36 +++++++-----
 examples/book/recent_files/examplewindow.h  |    2 +
 4 files changed, 78 insertions(+), 50 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index fee629a..3a5ebef 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,14 @@
 2011-10-04  Kjell Ahlstedt <kjell ahlstedt bredband net>
 
+	Update the Recently Used Documents chapter to gtkmm3 status.
+
+	* examples/book/recent_files/examplewindow.[h|cc]: Remove obsolete comments.
+	Add on_menu_file_recent_files_item().
+	* docs/tutorial/C/gtkmm-tutorial-in.xml: Update the Recently Used Documents
+	chapter to gtkmm3 status. Bug #658265.
+
+2011-10-04  Kjell Ahlstedt <kjell ahlstedt bredband net>
+
 	Update branch name in links to the git repository.
 
 	* docs/tutorial/C/gtkmm-tutorial-in.xml: Change branch name of example code
diff --git a/docs/tutorial/C/gtkmm-tutorial-in.xml b/docs/tutorial/C/gtkmm-tutorial-in.xml
index d2cfcdb..8b00372 100644
--- a/docs/tutorial/C/gtkmm-tutorial-in.xml
+++ b/docs/tutorial/C/gtkmm-tutorial-in.xml
@@ -5408,7 +5408,8 @@ and update the print settings.
     <classname>RecentManager</classname>,
     <classname>RecentChooserDialog</classname>,
     <classname>RecentChooserMenu</classname>,
-    <classname>RecentChooserWidget</classname>, and
+    <classname>RecentChooserWidget</classname>,
+    <classname>RecentAction</classname>, and
     <classname>RecentFilter</classname>.
   </para>
   <para>
@@ -5421,16 +5422,22 @@ and update the print settings.
   <sect1 id="sec-recentmanager">
     <title>RecentManager</title>
     <para>
-      <classname>RecentManager</classname> acts as the central database of
+      <classname>RecentManager</classname> acts as a database of
       recently used files. You use this class to register new files, remove
-      files from the list, or look up recently used files.
+      files from the list, or look up recently used files. There is one list
+      of recently used files per user.
     </para>
     <para>
       You can create a new <classname>RecentManager</classname>, but you'll most
       likely just want to use the default one. You can get a reference to the
       default <classname>RecentManager</classname> with
       <methodname>get_default()</methodname>.
-      </para>
+    </para>
+    <para>
+      <classname>RecentManager</classname> is the model of a model-view pattern,
+      where the view is a class that implements the
+      <classname>RecentChooser</classname> interface.
+    </para>
     <sect2 id="recent-files-adding">
       <title>Adding Items to the List of Recent Files</title>
       <para>
@@ -5445,7 +5452,7 @@ recent_manager->add_item(uri);</programlisting>
         <methodname>add_item()</methodname>. The metadata that can be set on a
         particular file item is as follows:
       </para>
-      <itemizedlist>
+      <itemizedlist id="list-file-metadata">
         <listitem>
           <para><varname>app_exec</varname>: The command line to be used to launch
             this resource. This string may contain the "f" and "u" escape
@@ -5490,13 +5497,19 @@ recent_manager->add_item(uri);</programlisting>
         provides several functions. To look up a specific item by its URI, you
         can use the <methodname>lookup_item()</methodname> function, which will
         return a <classname>RecentInfo</classname> class. If the specified URI
-        did not exist in the list of recent files, the
-        <classname>RecentInfo</classname> object will be invalid.
-        <classname>RecentInfo</classname> provides an implementation for
-        <methodname>operator bool()</methodname> which can be used to test for
-        validity. For example:
+        did not exist in the list of recent files,
+        <methodname>lookup_item()</methodname> throws a
+        <classname>RecentManagerError</classname> exception. For example:
       </para>
-<programlisting>Gtk::RecentInfo info = recent_manager-&gt;lookup_item(uri);
+<programlisting>Glib::RefPtr&lt;Gtk::RecentInfo&gt; info;
+try
+{
+  info = recent_manager-&gt;lookup_item(uri);
+}
+catch(const Gtk::RecentManagerError&amp; ex)
+{
+  std::cerr &lt;&lt; "RecentManagerError: " &lt;&lt; ex.what() &lt;&lt; std::endl;
+}
 if (info)
 {
   // item was found
@@ -5504,25 +5517,22 @@ if (info)
       <para>
         A <classname>RecentInfo</classname> object is essentially an object
         containing all of the metadata about a single recently-used file. You
-        can use this object to look up any of the properties listed above. FIXME
-        - add cross-reference.
+        can use this object to look up any of the properties listed
+        <link linkend="list-file-metadata">above</link>.
       </para>
       <para>
         If you don't want to look for a specific URI, but instead want to get a
         list of all recently used items, <classname>RecentManager</classname>
         provides the <methodname>get_items()</methodname> function. The return
-        value of this function can be assigned to any standard C++ container
-        (e.g. <classname>std::vector</classname>,
-        <classname>std::list</classname>, etc) and contains a list of all
-        recently-used files up to a user-defined limit (FIXME: what's the
-        default limit?). The following code demonstrates how you might get a
-        list of recently-used files:
+        value of this function is a <classname>std::vector</classname> of all
+        recently used files. The following code demonstrates how you might get a
+        list of recently used files:
       </para>
-      <programlisting>std::vector&lt;Gtk::RecentInfo&gt; info_list = recent_manager-&gt;get_items();</programlisting>
+      <programlisting>std::vector&lt; Glib::RefPtr&lt;Gtk::RecentInfo&gt; &gt; info_list = recent_manager-&gt;get_items();</programlisting>
       <para>
-        The limit on the number of items returned can be set
-        by <methodname>set_limit()</methodname>, and queried with
-        <methodname>get_limit()</methodname>.
+        The maximum age of items in the recently used files list can be set with
+        <methodname>Gtk::Settings::property_gtk_recent_files_max_age()</methodname>.
+        Default value: 30 days.
       </para>
     </sect2>
     <sect2 id="recent-files-modifying">
@@ -5536,7 +5546,7 @@ if (info)
       </para>
       <para>
         In addition to changing a file's URI, you can also remove items from the
-        list, either one at a time or by clearint them all at once. The former
+        list, either one at a time or by clearing them all at once. The former
         is accomplished with <methodname>remove_item()</methodname>, the latter with
         <methodname>purge_items()</methodname>.
       </para>
@@ -5557,10 +5567,11 @@ if (info)
     <para>
       <classname>RecentChooser</classname> is an interface that can be
       implemented by widgets displaying the list of recently used files.
-      &gtkmm; provides three built-in implementations for choosing recent files:
+      &gtkmm; provides four built-in implementations for choosing recent files:
       <classname>RecentChooserWidget</classname>,
-      <classname>RecentChooserDialog</classname>, and
-      <classname>RecentChooserMenu</classname>.
+      <classname>RecentChooserDialog</classname>,
+      <classname>RecentChooserMenu</classname>, and
+      <classname>RecentAction</classname>.
     </para>
     <para>
       <classname>RecentChooserWidget</classname> is a simple widget for
@@ -5570,16 +5581,18 @@ if (info)
       user interface if you want to.
     </para>
     <para>
-      The last class that implements the <classname>RecentChooser</classname>
-      interface is <classname>RecentChooserMenu</classname>. This class allows
-      you to list recently used files as a menu.
+      <classname>RecentChooserMenu</classname> and
+      <classname>RecentAction</classname> allow you to list recently used files
+      as a menu.
     </para>
-    <sect2 id="recenchooserwidget-example">
-      <title>Simple RecentChooserWidget example</title>
+    <sect2 id="recentchooserdialog-example">
+      <title>Simple RecentChooserDialog example</title>
       <para>
         Shown below is a simple example of how to use the
-        <classname>RecentChooserDialog</classname> class in a program. This
-        simple program has a menubar with a "Recent Files Dialog" menu item.
+        <classname>RecentChooserDialog</classname> and the
+        <classname>RecentAction</classname> classes in a program.
+        This simple program has a menubar with a
+        <guimenuitem>Recent Files Dialog</guimenuitem> menu item.
         When you select this menu item, a dialog pops up showing the list of
         recently used files.
       </para>
diff --git a/examples/book/recent_files/examplewindow.cc b/examples/book/recent_files/examplewindow.cc
index d86b8c7..8633058 100644
--- a/examples/book/recent_files/examplewindow.cc
+++ b/examples/book/recent_files/examplewindow.cc
@@ -36,23 +36,22 @@ ExampleWindow::ExampleWindow()
   //File menu:
   m_refActionGroup->add( Gtk::Action::create("FileMenu", "_File") );
   m_refActionGroup->add( Gtk::Action::create("FileNew", Gtk::Stock::NEW),
-          sigc::mem_fun(*this, &ExampleWindow::on_menu_file_new));
+    sigc::mem_fun(*this, &ExampleWindow::on_menu_file_new));
 
-  /* A recent-files sub-menu: */
-  //TODO: Shouldn't this have a default constructor?: 
-  //See bug #450032.
-  //m_refActionGroup->add( Gtk::RecentAction::create() );
-  m_refActionGroup->add( Gtk::RecentAction::create("FileRecentFiles",
-              "_Recent Files"));
+  //A recent-files submenu:
+  m_refRecentAction = Gtk::RecentAction::create("FileRecentFiles", "_Recent Files");
+  m_refActionGroup->add(m_refRecentAction);
+  //Connect to RecentChooser's item_activated signal
+  //instead of Action's activate signal:
+  m_refRecentAction->signal_item_activated().connect(
+    sigc::mem_fun(*this, &ExampleWindow::on_menu_file_recent_files_item) );
 
-  /* A menu item to open the recent-files dialog: */
-  m_refActionGroup->add( Gtk::Action::create("FileRecentDialog",
-              "Recent Files _Dialog"), sigc::mem_fun(*this,
-                  &ExampleWindow::on_menu_file_recent_files_dialog) );
+  //A menu item to open the recent-files dialog:
+  m_refActionGroup->add( Gtk::Action::create("FileRecentDialog", "Recent Files _Dialog"),
+    sigc::mem_fun(*this, &ExampleWindow::on_menu_file_recent_files_dialog) );
 
   m_refActionGroup->add( Gtk::Action::create("FileQuit", Gtk::Stock::QUIT),
-          sigc::mem_fun(*this, &ExampleWindow::on_menu_file_quit) );
-
+    sigc::mem_fun(*this, &ExampleWindow::on_menu_file_quit) );
 
   m_refUIManager = Gtk::UIManager::create();
   m_refUIManager->insert_action_group(m_refActionGroup);
@@ -91,7 +90,7 @@ ExampleWindow::ExampleWindow()
   if(pMenubar)
     m_Box.pack_start(*pMenubar, Gtk::PACK_SHRINK);
 
-  Gtk::Widget* pToolbar = m_refUIManager->get_widget("/ToolBar") ;
+  Gtk::Widget* pToolbar = m_refUIManager->get_widget("/ToolBar");
   if(pToolbar)
     m_Box.pack_start(*pToolbar, Gtk::PACK_SHRINK);
 
@@ -104,7 +103,7 @@ ExampleWindow::~ExampleWindow()
 
 void ExampleWindow::on_menu_file_new()
 {
-    std::cout << " New File" << std::endl;
+  std::cout << " New File" << std::endl;
 }
 
 void ExampleWindow::on_menu_file_quit()
@@ -112,6 +111,11 @@ void ExampleWindow::on_menu_file_quit()
   hide(); //Closes the main window to stop the Gtk::Main::run().
 }
 
+void ExampleWindow::on_menu_file_recent_files_item()
+{
+  std::cout << "URI selected = " << m_refRecentAction->get_current_uri() << std::endl;
+}
+
 void ExampleWindow::on_menu_file_recent_files_dialog()
 {
   Gtk::RecentChooserDialog dialog(*this, "Recent Files", m_refRecentManager);
@@ -122,7 +126,7 @@ void ExampleWindow::on_menu_file_recent_files_dialog()
   dialog.hide();
   if(response == Gtk::RESPONSE_OK)
   {
-     std::cout << "URI selected = " << dialog.get_current_uri() << std::endl;
+    std::cout << "URI selected = " << dialog.get_current_uri() << std::endl;
   }
 }
 
diff --git a/examples/book/recent_files/examplewindow.h b/examples/book/recent_files/examplewindow.h
index 634c8fb..43f4490 100644
--- a/examples/book/recent_files/examplewindow.h
+++ b/examples/book/recent_files/examplewindow.h
@@ -29,6 +29,7 @@ public:
 
 protected:
   //Signal handlers:
+  void on_menu_file_recent_files_item();
   void on_menu_file_recent_files_dialog();
   void on_menu_file_quit();
   void on_menu_file_new();
@@ -38,6 +39,7 @@ protected:
 
   Glib::RefPtr<Gtk::UIManager> m_refUIManager;
   Glib::RefPtr<Gtk::ActionGroup> m_refActionGroup;
+  Glib::RefPtr<Gtk::RecentAction> m_refRecentAction;
 
   Glib::RefPtr<Gtk::RecentManager> m_refRecentManager;
 };
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]