Commit 52a6d22d authored by Shaun McCance's avatar Shaun McCance

[libyelp] Adding gtk-doc API reference

parent 33e1b4f7
......@@ -18,11 +18,11 @@ EXTRA_DIST = \
important_docs.xml \
$(desktop_in_files)
DISTCLEANFILES = \
intltool-extract \
intltool-merge \
intltool-update
DISTCLEANFILES = \
intltool-extract \
intltool-merge \
intltool-update
CLEANFILES = $(desktop_DATA)
DISTCHECK_CONFIGURE_FLAGS = --disable-scrollkeeper
DISTCHECK_CONFIGURE_FLAGS = --disable-scrollkeeper --enable-gtk-doc
......@@ -8,12 +8,9 @@ AC_CONFIG_HEADERS([config.h])
AM_INIT_AUTOMAKE([1.9 dist-bzip2 no-dist-gzip])
AM_MAINTAINER_MODE
AC_SUBST(ACLOCAL_AMFLAGS, "\${ACLOCAL_FLAGS}")
IT_PROG_INTLTOOL([0.35.0])
AC_PATH_PROG(GCONFTOOL, gconftool-2)
AC_CONFIG_MACRO_DIR(m4)
AM_GCONF_SOURCE_2
AC_SUBST(ACLOCAL_AMFLAGS, "\${ACLOCAL_FLAGS}")
AC_PROG_LN_S
AC_PROG_CC
......@@ -22,9 +19,15 @@ AC_ISC_POSIX
AC_HEADER_STDC
AM_PROG_LIBTOOL
AM_PATH_GLIB_2_0
AM_PROG_CC_C_O
IT_PROG_INTLTOOL([0.35.0])
GTK_DOC_CHECK(1.9)
AC_PATH_PROG(GCONFTOOL, gconftool-2)
AM_GCONF_SOURCE_2
GNOME_DEBUG_CHECK
GNOME_COMPILE_WARNINGS([maximum])
......@@ -253,6 +256,9 @@ AC_SUBST([AM_LDFLAGS])
AC_CONFIG_FILES([
Makefile
docs/Makefile
docs/libyelp/Makefile
docs/libyelp/version.xml
libyelp/Makefile
src/Makefile
stylesheets/Makefile
......@@ -278,6 +284,7 @@ yelp-$VERSION:
source code location: ${srcdir}
compiler: ${CC}
Documentation: ${enable_gtk_doc}
Debug enabled: ${enable_debug}
Search backend: ${search_backend}
Using SMClient: ${with_smclient}
......
SUBDIRS = libyelp
AUTOMAKE_OPTIONS = 1.6
DOC_MODULE = libyelp
DOC_MAIN_SGML_FILE = libyelp-docs.xml
SCAN_OPTIONS = --deprecated-guards="G_DISABLE_DEPRECATED" --rebuild-types
SCANGOBJ_OPTIONS = --type-init-func="g_type_init();g_thread_init(NULL);"
DOC_SOURCE_DIR = $(top_srcdir)/libyelp
GTKDOC_CFLAGS = \
$(YELP_CFLAGS) \
-I$(top_srcdir)/libyelp
GTKDOC_LIBS = \
$(YELP_LIBS) \
$(top_builddir)/libyelp/libyelp.la
HFILE_GLOB = $(top_srcdir)/libyelp/*.h
CFILE_GLOB = $(top_srcdir)/libyelp/*.c
IGNORE_HFILES = yelp-debug.h
MKDB_OPTIONS = --output-format=xml --sgml-mode --name-space=yelp --ignore-files='yelp-debug.h yelp-debug.c'
content_files = version.xml
extra_viles = version.xml.in
include $(top_srcdir)/gtk-doc.make
EXTRA_DIST += version.xm.in
# Extra options to supply to gtkdoc-mktmpl
# e.g. MKTMPL_OPTIONS=--only-section-tmpl
#MKTMPL_OPTIONS=
# Extra options to supply to gtkdoc-mkhtml
#MKHTML_OPTIONS=
# Extra options to supply to gtkdoc-fixref. Not normally needed.
# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html
#FIXXREF_OPTIONS=
# Extra header to include when scanning, which are not under DOC_SOURCE_DIR
# e.g. EXTRA_HFILES=$(top_srcdir}/contrib/extra.h
#EXTRA_HFILES=
# Images to copy into HTML directory.
# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
#HTML_IMAGES=
# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
#content_files=
# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
# These files must be listed here *and* in content_files
# e.g. expand_content_files=running.sgml
#expand_content_files=
# This includes the standard gtk-doc make rules, copied by gtkdocize.
# Other files to distribute
# e.g. EXTRA_DIST += version.xml.in
#EXTRA_DIST +=
# Files not to distribute
# for --rebuild-types in $(SCAN_OPTIONS), e.g. $(DOC_MODULE).types
# for --rebuild-sections in $(SCAN_OPTIONS) e.g. $(DOC_MODULE)-sections.txt
#DISTCLEANFILES +=
# Comment this out if you want your docs-status tested during 'make check'
#if ENABLE_GTK_DOC
#TESTS_ENVIRONMENT = cd $(srcsrc) &&
#TESTS = $(GTKDOC_CHECK)
#endif
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
<!ENTITY version SYSTEM "version.xml">
]>
<book id="index">
<bookinfo>
<title>Yelp Reference Manual</title>
<releaseinfo>for libyelp &version;</releaseinfo>
</bookinfo>
<chapter>
<title>API Reference</title>
<section>
<title>Widgets</title>
<include href="xml/yelp-view.xml" xmlns="http://www.w3.org/2003/XInclude"/>
<include href="xml/yelp-location-entry.xml" xmlns="http://www.w3.org/2003/XInclude"/>
</section>
<section>
<title>Document Processing</title>
<include href="xml/yelp-document.xml" xmlns="http://www.w3.org/2003/XInclude"/>
<include href="xml/yelp-simple-document.xml" xmlns="http://www.w3.org/2003/XInclude"/>
</section>
<include href="xml/yelp-uri.xml" xmlns="http://www.w3.org/2003/XInclude"/>
<include href="xml/yelp-settings.xml" xmlns="http://www.w3.org/2003/XInclude"/>
<include href="xml/yelp-error.xml" xmlns="http://www.w3.org/2003/XInclude"/>
</chapter>
<chapter id="object-tree">
<title>Object Hierarchy</title>
<include href="xml/tree_index.sgml" xmlns="http://www.w3.org/2003/XInclude"/>
</chapter>
<index id="api-index-full">
<title>API Index</title>
<include href="xml/api-index-full.xml" xmlns="http://www.w3.org/2003/XInclude"><fallback/></include>
</index>
<include href="xml/annotation-glossary.xml" xmlns="http://www.w3.org/2003/XInclude"><fallback/></include>
</book>
noinst_LTLIBRARIES = libyelp.la
lib_LTLIBRARIES = libyelp.la
libyelp_la_SOURCES = \
yelp-debug.c \
......
......@@ -27,7 +27,7 @@
#include "yelp-debug.h"
/**
/*
* @file: you should pass the __FILE__ constant as this parameter
* @line: you should pass the __LINE__ constant as this parameter
* @function: you should pass the __FUNCTION__ constant as this parameter
......
......@@ -26,20 +26,37 @@
#include "yelp-location-entry.h"
struct _YelpLocationEntryPrivate
{
GtkWidget *text_entry;
gint icon_column;
gint flags_column;
gboolean enable_search;
GtkTreeRowReference *row;
gboolean search_mode;
GtkCellRenderer *icon_cell;
};
/**
* SECTION:yelp-location-entry
* @short_description: A location entry with history and search
* @include: yelp.h
*
* #YelpLocationEntry is a #GtkComboBoxEntry designed to show the current location,
* provide a drop-down menu of previous locations, and allow the user to perform
* searches.
*
* The #GtkTreeModel used by a #YelpLocationEntry is expected to have at least
* three columns: #GtkComboBoxEntry::text-column contains the displayed name
* of the location, #YelpLocationEntry::icon-column contains an icon name for
* the location, and #YelpLocationEntry::flags-column contains a bit field
* of #YelpLocationEntryFlags. These columns are specified when creating a
* #YelpLocationEntry widget with yelp_location_entry_new_with_model().
*
* Usually, a single row in the #GtkTreeModel corresponds to a location. When
* a user selects a row from the drop-down menu, the icon and text for that
* row will be placed in the embedded text entry, and the
* #YelpLocationEntry:location-selected signal will be emitted.
*
* If a row has the %YELP_LOCATION_ENTRY_IS_SEARCH flag set, selecting that
* row will not emit the #YelpLocationEntry::location-selected signal. Instead,
* the #YelpLocationEntry widget will be placed into search mode, as if by a
* call to yelp_location_entry_start_search().
*
* When a row has the %YELP_LOCATION_ENTRY_CAN_BOOKMARK flag set, an icon
* will be displayed in the secondary icon position of the embedded text
* entry allowing the user to bookmark the location. Clicking this icon
* will cause the FIXME signal to be emitted.
**/
static void location_entry_get_property (GObject *object,
guint prop_id,
......@@ -85,6 +102,20 @@ static gboolean entry_key_press_cb (GtkWidget *widget,
GdkEventKey *event,
gpointer user_data);
struct _YelpLocationEntryPrivate
{
GtkWidget *text_entry;
gint icon_column;
gint flags_column;
gboolean enable_search;
GtkTreeRowReference *row;
gboolean search_mode;
GtkCellRenderer *icon_cell;
};
enum {
LOCATION_SELECTED,
......@@ -116,8 +147,14 @@ yelp_location_entry_class_init (YelpLocationEntryClass *klass)
/**
* YelpLocationEntry::location-selected
* @widget: The object which received the signal
*/
* @widget: The #YelpLocationEntry for which the signal was emitted.
* @user_data: User data set when the handler was connected.
*
* This signal will be emitted whenever a user selects a normal row from the
* drop-down menu. Note that if a row has the flag %YELP_LOCATION_ENTRY_IS_SEARCH,
* clicking the row will cause @widget to enter search mode, and this signal
* will not be emitted.
**/
location_entry_signals[LOCATION_SELECTED] =
g_signal_new ("location_selected",
G_OBJECT_CLASS_TYPE (klass),
......@@ -127,10 +164,15 @@ yelp_location_entry_class_init (YelpLocationEntryClass *klass)
G_TYPE_NONE, 0);
/**
* YelpLocationEntry::search_activated
* @widget: The object which received the signal
* @text: The search text
*/
* YelpLocationEntry::search-activated
* @widget: The #YelpLocationEntry for which the signal was emitted.
* @text: The search text.
* @user_data: User data set when the handler was connected.
*
* This signal will be emitted whenever the user activates a search, generally
* by pressing <keycap>Enter</keycap> in the embedded text entry while @widget
* is in search mode.
**/
location_entry_signals[SEARCH_ACTIVATED] =
g_signal_new ("search-activated",
G_OBJECT_CLASS_TYPE (klass),
......@@ -140,6 +182,12 @@ yelp_location_entry_class_init (YelpLocationEntryClass *klass)
G_TYPE_NONE, 1,
G_TYPE_STRING);
/**
* YelpLocationEntry:icon-column
*
* The column in the #GtkTreeModel containing an icon name for each row.
* This must be a name that can be looked up through #GtkIconTheme.
**/
g_object_class_install_property (object_class,
PROP_ICON_COLUMN,
g_param_spec_int ("icon-column",
......@@ -150,6 +198,12 @@ yelp_location_entry_class_init (YelpLocationEntryClass *klass)
-1,
G_PARAM_READWRITE | G_PARAM_STATIC_NAME |
G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB));
/**
* YelpLocationEntry:flags-column
*
* The column in the #GtkTreeModel containing #YelpLocationEntryFlags flags
* for each row.
**/
g_object_class_install_property (object_class,
PROP_FLAGS_COLUMN,
g_param_spec_int ("flags-column",
......@@ -160,6 +214,13 @@ yelp_location_entry_class_init (YelpLocationEntryClass *klass)
-1,
G_PARAM_READWRITE | G_PARAM_STATIC_NAME |
G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB));
/**
* YelpLocationEntry:enable-search
*
* Whether the location entry can act as a search entry. If search is not
* enabled, the user will not be able to initiate a search by clicking in
* the embedded text entry or selecting a search row in the drop-down menu.
**/
g_object_class_install_property (object_class,
PROP_ENABLE_SEARCH,
g_param_spec_boolean ("enable-search",
......@@ -545,17 +606,16 @@ entry_key_press_cb (GtkWidget *widget,
}
/**
* yelp_location_entry_ew_with_model:
* yelp_location_entry_new_with_model:
* @model: A #GtkTreeModel.
* @text_column: The column in @model containing the title of each entry.
* @icon_column: The column in @model containing the icon name of each entry.
* @bookmark_column: The column in @model containing a gboolean specifying
* whether or not each entry is bookmarked.
* @flags_column: The column in @model containing #YelpLocationEntryFlags.
*
* Creates a new #YelpLocationEntry widget.
*
* Return value: A new #YelpLocationEntry.
*/
* Returns: A new #YelpLocationEntry.
**/
GtkWidget*
yelp_location_entry_new_with_model (GtkTreeModel *model,
gint text_column,
......@@ -581,6 +641,14 @@ yelp_location_entry_new_with_model (GtkTreeModel *model,
return ret;
}
/**
* yelp_location_entry_start_search:
* @entry: A #YelpLocationEntry.
*
* Puts @entry into search mode. This focuses the entry and clears its text
* contents. When the user activates the search, the
* #YelpLocationEntry::search-activated signal will be emitted.
**/
void
yelp_location_entry_start_search (YelpLocationEntry *entry)
{
......
......@@ -42,6 +42,9 @@ G_BEGIN_DECLS
(G_TYPE_INSTANCE_GET_CLASS((obj), YELP_TYPE_LOCATION_ENTRY, \
YelpLocationEntryClass))
/**
* YelpLocationEntry:
**/
typedef struct _YelpLocationEntry YelpLocationEntry;
typedef struct _YelpLocationEntryClass YelpLocationEntryClass;
typedef struct _YelpLocationEntryPrivate YelpLocationEntryPrivate;
......@@ -57,6 +60,20 @@ struct _YelpLocationEntryClass
GtkComboBoxEntryClass parent;
};
/**
* YelpLocationEntryFlags:
* @YELP_LOCATION_ENTRY_CAN_BOOKMARK: This location can be bookmarked. When a
* bookmarkable location is selected, the secondary icon of the embedded text
* entry will be a clickable bookmark icon.
* @YELP_LOCATION_ENTRY_IS_LOADING: Page data for this location is still loading.
* The #YelpLocationEntry widget will display an indeterminate progress indicator.
* @YELP_LOCATION_ENTRY_IS_SEPARATOR: This row should be displayed as a separator.
* @YELP_LOCATION_ENTRY_IS_SEARCH: Selecting this row initiates a search instead
* of selecting a location.
*
* Flags which can be used to provide additional information about rows
* to be displayed by a #YelpLocationEntry.
**/
typedef enum {
YELP_LOCATION_ENTRY_CAN_BOOKMARK = 1 << 0,
YELP_LOCATION_ENTRY_IS_LOADING = 1 << 1,
......@@ -74,4 +91,4 @@ void yelp_location_entry_start_search (YelpLocationEntry *entry);
G_END_DECLS
#endif /* __YELP_DOCUMENT_H__ */
#endif /* __YELP_LOCATION_ENTRY_H__ */
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment