diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index c593aa0e4e..831be398f1 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,7 @@ +2006-04-17 Emmanuele Bassi + + * gtk/tmpl/gtkrecent*.sgml: Add long descriptions. + 2006-04-16 Matthias Clasen * gtk/tmpl/gtkrecent*.sgml: Add short descriptions diff --git a/docs/reference/gtk/tmpl/gtkrecentchooser.sgml b/docs/reference/gtk/tmpl/gtkrecentchooser.sgml index 72937ba4c9..e488ef3d36 100644 --- a/docs/reference/gtk/tmpl/gtkrecentchooser.sgml +++ b/docs/reference/gtk/tmpl/gtkrecentchooser.sgml @@ -6,15 +6,20 @@ Interface implemented by GtkRecentChooserWidget, GtkRecentChooserMenu and GtkRec - +#GtkRecentChooser is an interface that can be implemented by widgets +displaying the list of recently used files. In GTK+, the main objects +that implement this interface are #GtkRecentChooserWidget, +#GtkRecentChooserDialog and #GtkRecentChooserMenu. + Recently used files are supported since GTK+ 2.10. - +#GtkRecentManager, #GtkRecentChooserDialog, #GtkRecentChooserWidget, +#GtkRecentChooserMenu @@ -47,20 +52,38 @@ Recently used files are supported since GTK+ 2.10. @item_activated: @selection_changed: - + + +@recentchooser: the object which received the signal. + + + + + + +@recentchooser: the object which received the signal. + + + + + +Used to get the #GError quark for #GtkRecentChooser errors. + + - +These identify the various errors that can occur while calling +#GtkRecentChooser functions. -@GTK_RECENT_CHOOSER_ERROR_NOT_FOUND: -@GTK_RECENT_CHOOSER_ERROR_INVALID_URI: +@GTK_RECENT_CHOOSER_ERROR_NOT_FOUND: Indicates that a file does not exist +@GTK_RECENT_CHOOSER_ERROR_INVALID_URI: Indicates a malformed URI diff --git a/docs/reference/gtk/tmpl/gtkrecentchooserdialog.sgml b/docs/reference/gtk/tmpl/gtkrecentchooserdialog.sgml index 6c70c06725..d328db3af6 100644 --- a/docs/reference/gtk/tmpl/gtkrecentchooserdialog.sgml +++ b/docs/reference/gtk/tmpl/gtkrecentchooserdialog.sgml @@ -6,15 +6,55 @@ Displays recently used files in a dialog - +#GtkRecentChooserDialog is a dialog box suitable for displaying the recently +used documents. This widgets works by putting a #GtkRecentChooserWidget inside +a #GtkDialog. It exposes the #GtkRecentChooserIface interface, so you can use +all the #GtkRecentChooser functions on the recent chooser dialog as well as +those for #GtkDialog. + + +Note that #GtkRecentChooserDialog does not have any methods of its own. +Instead, you should use the functions that work on a #GtkRecentChooser. + + + + Typical usage + + + In the simplest of cases, you can use the following code to use + a #GtkRecentChooserDialog to select a recently used file: + + + +GtkWidget *dialog; + +dialog = gtk_recent_chooser_dialog_new ("Recent Documents", + parent_window, + GTK_STOCK_CANCEL, GTK_RESPONSE_CANCEL, + GTK_STOCK_OPEN, GTK_RESPONSE_ACCEPT, + NULL); + +if (gtk_dialog_run (GTK_DIALOG (dialog)) == GTK_RESPONSE_ACCEPT) + { + GtkRecentInfo *info; + + info = gtk_recent_chooser_get_current_item (GTK_RECENT_CHOOSER (dialog)); + open_file (gtk_recent_info_get_uri (info)); + gtk_recent_info_unref (info); + } + +gtk_widget_destroy (dialog); + + + Recently used files are supported since GTK+ 2.10. - +#GtkRecentChooser, #GtkDialog diff --git a/docs/reference/gtk/tmpl/gtkrecentchoosermenu.sgml b/docs/reference/gtk/tmpl/gtkrecentchoosermenu.sgml index 5390966529..bbb9fda056 100644 --- a/docs/reference/gtk/tmpl/gtkrecentchoosermenu.sgml +++ b/docs/reference/gtk/tmpl/gtkrecentchoosermenu.sgml @@ -6,15 +6,22 @@ Displays recently used files in a menu - +#GtkRecentChooserMenu is a widget suitable for displaying recently used files +inside a menu. It can be used to set a sub-menu of a #GtkMenuItem using +gtk_menu_item_set_submenu(), or as the menu of a #GtkMenuToolButton. + + +Note that #GtkRecentChooserMenu does not have any methods of its own. Instead, +you should use the functions that work on a #GtkRecentChooser. + Recently used files are supported since GTK+ 2.10. - +#GtkRecentChooser diff --git a/docs/reference/gtk/tmpl/gtkrecentchooserwidget.sgml b/docs/reference/gtk/tmpl/gtkrecentchooserwidget.sgml index 1a3f4fe502..837ce0cefe 100644 --- a/docs/reference/gtk/tmpl/gtkrecentchooserwidget.sgml +++ b/docs/reference/gtk/tmpl/gtkrecentchooserwidget.sgml @@ -6,15 +6,23 @@ Displays recently used files - +#GtkRecentChooserWidget is a widget suitable for selecting recently used +files. It is the main building block of a #GtkRecentChooserDialog. Most +applications will only need to use the latter; you can use +#GtkRecentChooserWidget as part of a larger window if you have special needs. + + +Note that #GtkRecentChooserWidget does not have any methods of its own. +Instead, you should use the functions that work on a #GtkRecentChooser. + Recently used files are supported since GTK+ 2.10. - +#GtkRecentChooser, #GtkRecentChooserDialog diff --git a/docs/reference/gtk/tmpl/gtkrecentfilter.sgml b/docs/reference/gtk/tmpl/gtkrecentfilter.sgml index 3a30daf2c4..c6d601d1aa 100644 --- a/docs/reference/gtk/tmpl/gtkrecentfilter.sgml +++ b/docs/reference/gtk/tmpl/gtkrecentfilter.sgml @@ -2,19 +2,39 @@ GtkRecentFilter -A filter for recently used files +A filter for selecting a subset of recently used files - +A #GtkRecentFilter can be used to restrict the files being shown +in a #GtkRecentChooser. Files can be filtered based on their name +(with gtk_recent_filter_add_pattern()), on their mime type (with +gtk_file_filter_add_mime_type()), on the application that has +registered them (with gtk_recent_filter_add_application()), or by +a custom filter function (with gtk_recent_filter_add_custom()). + + +Filtering by mime type handles aliasing and subclassing of mime +types; e.g. a filter for text/plain also matches a file with mime +type application/rtf, since application/rtf is a subclass of text/plain. +Note that #GtkRecentFilter allows wildcards for the subtype of a +mime type, so you can e.g. filter for image/*. + + + +Normally, filters are used by adding them to a #GtkRecentChooser, +see gtk_recent_chooser_add_filter(), but it is also possible to +manually use a filter on a file with gtk_recent_filter_filter(). + + Recently used files are supported since GTK+ 2.10. - +#GtkRecentChooser @@ -22,43 +42,53 @@ Recently used files are supported since GTK+ 2.10. - +The GtkRecentFilter struct contains +only private fields and should not be directly accessed. - +A GtkRecentFilterInfo struct is used +to pass information about the tested file to gtk_recent_filter_filter(). -@contains: -@uri: -@display_name: -@mime_type: -@applications: -@groups: -@age: +@contains: Flags indicating which of the following fields need + are filled +@uri: the URI of the file being tested +@display_name: the string that will be used to display the file + in the recent chooser +@mime_type: the mime type of the file +@applications: the list of applications that have registered the file +@groups: the groups to which the file belongs to +@age: the number of days elapsed since the file has been registered - +These flags indicate what parts of a #GtkRecentFilterInfo struct +are filled or need to be filled. -@GTK_RECENT_FILTER_URI: -@GTK_RECENT_FILTER_DISPLAY_NAME: -@GTK_RECENT_FILTER_MIME_TYPE: -@GTK_RECENT_FILTER_APPLICATION: -@GTK_RECENT_FILTER_GROUP: -@GTK_RECENT_FILTER_AGE: +@GTK_RECENT_FILTER_URI: the URI of the file being tested +@GTK_RECENT_FILTER_DISPLAY_NAME: the string that will be used to + display the file in the recent chooser +@GTK_RECENT_FILTER_MIME_TYPE: the mime type of the file +@GTK_RECENT_FILTER_APPLICATION: the list of applications that have + registered the file +@GTK_RECENT_FILTER_GROUP: the groups to which the file belongs to +@GTK_RECENT_FILTER_AGE: the number of days elapsed since the file + has been registered - +The type of function that is used with custom filters, +see gtk_recent_filter_add_custom(). -@filter_info: -@user_data: -@Returns: +@filter_info: a #GtkRecentFilterInfo that is filled according + to the @needed flags passed to gtk_recent_filter_add_custom() +@user_data: user data passed to gtk_recent_filter_add_custom() +@Returns: %TRUE if the file should be displayed diff --git a/docs/reference/gtk/tmpl/gtkrecentmanager.sgml b/docs/reference/gtk/tmpl/gtkrecentmanager.sgml index 0a4c5fb9b2..613e0140e7 100644 --- a/docs/reference/gtk/tmpl/gtkrecentmanager.sgml +++ b/docs/reference/gtk/tmpl/gtkrecentmanager.sgml @@ -6,9 +6,64 @@ Managing Recently Used Files - +#GtkRecentManager provides a facility for adding, removing and +looking up recently used files. Each recently used file is +identified by its URI, and has meta-data associated to it, like +the names and command lines of the applications that have +registered it, the number of time each application has registered +the same file, the mime type of the file and whether the file +should be displayed only by the applications that have +registered it. + +The #GtkRecentManager acts like a database of all the recently +used files. You can create new #GtkRecentManager objects, but +it is more efficient to use the standard recent manager for +the #GdkScreen so that informations about the recently used +files is shared with other people using them. In case the +default screen is being used, adding a new recently used +file is as simple as: + + + + +GtkRecentManager *manager; +GError *error = NULL; + +manager = gtk_recent_manager_get_default (); +gtk_recent_manager_add_item (manager, file_uri, &error); +if (error) + { + g_warning ("Could not add the file: %s", error->message); + g_error_free (error); + } + + + +While looking up a recently used file is as simple as: + + + +GtkRecentManager *manager; +GtkRecentInfo *info; +GError *error = NULL; + +manager = gtk_recent_manager_get_default (); +info = gtk_recent_manager_lookup_item (manager, file_uri, &error); +if (error) + { + g_warning ("Could not find the file: %s", error->message); + g_error_free (error); + } +else + { + /* Use the info object */ + g_object_unref (info); + } + + + Recently used files are supported since GTK+ 2.10. @@ -23,28 +78,39 @@ Recently used files are supported since GTK+ 2.10. - - +Acts as a database of information about the list of recently +used files. Normally, you retrieve the recent manager for a +particular screen using gtk_recent_manager_get_for_screen() +and it will contain information about current recent manager +for that screen. - +Contains informations found when looking up an entry of the +recently used files list. - +Meta-data passed to gtk_recent_manager_add_full(). You should +use #GtkRecentData if you want to control the meta-data associated +to an entry of the recently used files list when you are adding +a new file to it. -@display_name: -@description: -@mime_type: -@app_name: -@app_exec: -@groups: -@is_private: +@display_name: the string to be used when displaying the file + inside a #GtkRecentChooser +@description: a user readable description of the file +@mime_type: the mime type of the file +@app_name: the name of the application that is registering + the file +@app_exec: the command line that should be used when launching + the file +@groups: the list of group names to which the file belongs to +@is_private: whether the file should be displayed only by + the applications that have registered it