AuroraMiddleware/gtk2
1
0
Fork 0
forked from AuroraMiddleware/gtk
Code Issues Pull Requests Projects Releases Wiki Activity

Add long descriptions.

Browse Source 
2006-04-17  Emmanuele Bassi  <ebassi@cvs.gnome.org>

	* gtk/tmpl/gtkrecent*.sgml: Add long descriptions.
This commit is contained in:
Emmanuele Bassi 2006-04-17 15:39:21 +00:00 committed by Emmanuele Bassi
parent 8782ca6abc
commit 237342c4ec
7 changed files with 225 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/reference/ChangeLog
View File

@ -1,3 +1,7 @@
2006-04-17 Emmanuele Bassi <ebassi@cvs.gnome.org>
* gtk/tmpl/gtkrecent*.sgml: Add long descriptions.
2006-04-16 Matthias Clasen <mclasen@redhat.com>
* gtk/tmpl/gtkrecent*.sgml: Add short descriptions

35
docs/reference/gtk/tmpl/gtkrecentchooser.sgml
View File

@ -6,15 +6,20 @@ Interface implemented by GtkRecentChooserWidget, GtkRecentChooserMenu and GtkRec
<!-- ##### SECTION Long_Description ##### -->
<para>
#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.
</para>
<para>
Recently used files are supported since GTK+ 2.10.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
#GtkRecentManager, #GtkRecentChooserDialog, #GtkRecentChooserWidget,
#GtkRecentChooserMenu
</para>
<!-- ##### SECTION Stability_Level ##### -->
@ -47,20 +52,38 @@ Recently used files are supported since GTK+ 2.10.
@item_activated:
@selection_changed:
<!-- ##### MACRO GTK_RECENT_CHOOSER_ERROR ##### -->
<!-- ##### SIGNAL GtkRecentChooser::item-activated ##### -->
<para>
</para>
@recentchooser: the object which received the signal.
<!-- ##### SIGNAL GtkRecentChooser::selection-changed ##### -->
<para>
</para>
@recentchooser: the object which received the signal.
<!-- ##### MACRO GTK_RECENT_CHOOSER_ERROR ##### -->
<para>
Used to get the #GError quark for #GtkRecentChooser errors.
</para>
<!-- ##### ENUM GtkRecentChooserError ##### -->
<para>
These identify the various errors that can occur while calling
#GtkRecentChooser functions.
</para>
@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
<!-- ##### FUNCTION gtk_recent_chooser_set_show_private ##### -->
<para>

44
docs/reference/gtk/tmpl/gtkrecentchooserdialog.sgml
View File

@ -6,15 +6,55 @@ Displays recently used files in a dialog
<!-- ##### SECTION Long_Description ##### -->
<para>
#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.
</para>
<para>
Note that #GtkRecentChooserDialog does not have any methods of its own.
Instead, you should use the functions that work on a #GtkRecentChooser.
</para>
<example id="gtkrecentchooser-typical-usage">
<title>Typical usage</title>
<para>
In the simplest of cases, you can use the following code to use
a #GtkRecentChooserDialog to select a recently used file:
</para>
<programlisting>
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);
</programlisting>
</example>
<para>
Recently used files are supported since GTK+ 2.10.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
#GtkRecentChooser, #GtkDialog
</para>
<!-- ##### SECTION Stability_Level ##### -->

11
docs/reference/gtk/tmpl/gtkrecentchoosermenu.sgml
View File

@ -6,15 +6,22 @@ Displays recently used files in a menu
<!-- ##### SECTION Long_Description ##### -->
<para>
#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.
</para>
<para>
Note that #GtkRecentChooserMenu does not have any methods of its own. Instead,
you should use the functions that work on a #GtkRecentChooser.
<para>
Recently used files are supported since GTK+ 2.10.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
#GtkRecentChooser
</para>
<!-- ##### SECTION Stability_Level ##### -->

12
docs/reference/gtk/tmpl/gtkrecentchooserwidget.sgml
View File

@ -6,15 +6,23 @@ Displays recently used files
<!-- ##### SECTION Long_Description ##### -->
<para>
#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.
</para>
<para>
Note that #GtkRecentChooserWidget does not have any methods of its own.
Instead, you should use the functions that work on a #GtkRecentChooser.
<para>
Recently used files are supported since GTK+ 2.10.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
#GtkRecentChooser, #GtkRecentChooserDialog
</para>
<!-- ##### SECTION Stability_Level ##### -->

76
docs/reference/gtk/tmpl/gtkrecentfilter.sgml
View File

@ -2,19 +2,39 @@
GtkRecentFilter
<!-- ##### SECTION Short_Description ##### -->
A filter for recently used files
A filter for selecting a subset of recently used files
<!-- ##### SECTION Long_Description ##### -->
<para>
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()).
</para>
<para>
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/*.
</para>
<para>
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().
</para>
<para>
Recently used files are supported since GTK+ 2.10.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
#GtkRecentChooser
</para>
<!-- ##### SECTION Stability_Level ##### -->
@ -22,43 +42,53 @@ Recently used files are supported since GTK+ 2.10.
<!-- ##### STRUCT GtkRecentFilter ##### -->
<para>
The <structname>GtkRecentFilter</structname> struct contains
only private fields and should not be directly accessed.
</para>
<!-- ##### STRUCT GtkRecentFilterInfo ##### -->
<para>
A <structname>GtkRecentFilterInfo</structname> struct is used
to pass information about the tested file to gtk_recent_filter_filter().
</para>
@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
<!-- ##### ENUM GtkRecentFilterFlags ##### -->
<para>
These flags indicate what parts of a #GtkRecentFilterInfo struct
are filled or need to be filled.
</para>
@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
<!-- ##### USER_FUNCTION GtkRecentFilterFunc ##### -->
<para>
The type of function that is used with custom filters,
see gtk_recent_filter_add_custom().
</para>
@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
<!-- ##### FUNCTION gtk_recent_filter_new ##### -->

90
docs/reference/gtk/tmpl/gtkrecentmanager.sgml
View File

@ -6,9 +6,64 @@ Managing Recently Used Files
<!-- ##### SECTION Long_Description ##### -->
<para>
#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.
</para>
<para>
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:
</para>
<informalexample>
<programlisting>
GtkRecentManager *manager;
GError *error = NULL;
manager = gtk_recent_manager_get_default ();
gtk_recent_manager_add_item (manager, file_uri, &amp;error);
if (error)
{
g_warning ("Could not add the file: &percnt;s", error-&gt;message);
g_error_free (error);
}
</programlisting>
</informalexample>
While looking up a recently used file is as simple as:
<informalexample>
<programlisting>
GtkRecentManager *manager;
GtkRecentInfo *info;
GError *error = NULL;
manager = gtk_recent_manager_get_default ();
info = gtk_recent_manager_lookup_item (manager, file_uri, &amp;error);
if (error)
{
g_warning ("Could not find the file: &percnt;s", error-&gt;message);
g_error_free (error);
}
else
{
/* Use the info object */
g_object_unref (info);
}
</programlisting>
</informalexample>
<para>
Recently used files are supported since GTK+ 2.10.
</para>
@ -23,28 +78,39 @@ Recently used files are supported since GTK+ 2.10.
<!-- ##### STRUCT GtkRecentManager ##### -->
<para>
</para>
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.</para>
<!-- ##### STRUCT GtkRecentInfo ##### -->
<para>
Contains informations found when looking up an entry of the
recently used files list.
</para>
<!-- ##### STRUCT GtkRecentData ##### -->
<para>
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.
</para>
@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
<!-- ##### MACRO GTK_RECENT_MANAGER_ERROR ##### -->
<para>