<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
     "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY LIBGDA "<application>libgda</application>">
<!ENTITY LIBGNOMEDB "<application>libgnomedb</application>">
<!ENTITY GNOME-DB "<application>GNOME-DB</application>">
<!ENTITY fdl-appendix SYSTEM "fdl-appendix.sgml">
<!ENTITY visual-index SYSTEM "visual_index.xml">
<!ENTITY migration SYSTEM "migration.xml">
<!ENTITY migration2 SYSTEM "migration2.xml">
<!ENTITY libgnomedb-Example SYSTEM "example.sgml">
<!ENTITY libgnomedb-Example-Code SYSTEM "example.c">
<!ENTITY libgnomedb-init SYSTEM "xml/libgnomedb.xml">
<!ENTITY libgnomedb-GnomeDbBasicForm SYSTEM "xml/gnome-db-basic-form.xml">
<!ENTITY libgnomedb-combo SYSTEM "xml/gnome-db-combo.xml">
<!ENTITY libgnomedb-connection-properties SYSTEM "xml/gnome-db-connection-properties.xml">
<!ENTITY libgnomedb-GnomeDbDataEntry SYSTEM "xml/gnome-db-data-entry.xml">
<!ENTITY libgnomedb-GnomeDbDataImport SYSTEM "xml/gnome-db-data-import.xml">
<!ENTITY libgnomedb-GnomeDbDataStore SYSTEM "xml/gnome-db-data-store.xml">
<!ENTITY libgnomedb-GnomeDbDataWidgetFilter SYSTEM "xml/gnome-db-data-widget-filter.xml">
<!ENTITY libgnomedb-GnomeDbDataWidget SYSTEM "xml/gnome-db-data-widget.xml">
<!ENTITY libgnomedb-GnomeDbDataWidgetInfo SYSTEM "xml/gnome-db-data-widget-info.xml">
<!ENTITY libgnomedb-dsn-assistant SYSTEM "xml/gnome-db-dsn-assistant.xml">
<!ENTITY libgnomedb-dsn-editor SYSTEM "xml/gnome-db-dsn-editor.xml">
<!ENTITY libgnomedb-data-source-selector SYSTEM "xml/gnome-db-dsn-selector.xml">
<!ENTITY libgnomedb-find-dialog SYSTEM "xml/gnome-db-find-dialog.xml">
<!ENTITY libgnomedb-GnomeDbForm SYSTEM "xml/gnome-db-form.xml">
<!ENTITY libgnomedb-GnomeDbGrid SYSTEM "xml/gnome-db-grid.xml">
<!ENTITY libgnomedb-login-dialog SYSTEM "xml/gnome-db-login-dialog.xml">
<!ENTITY libgnomedb-login SYSTEM "xml/gnome-db-login.xml">
<!ENTITY libgnomedb-provider-auth-editor SYSTEM "xml/gnome-db-provider-auth-editor.xml">
<!ENTITY libgnomedb-provider-selector SYSTEM "xml/gnome-db-provider-selector.xml">
<!ENTITY libgnomedb-provider-spec-editor SYSTEM "xml/gnome-db-provider-spec-editor.xml">
<!ENTITY libgnomedb-GnomeDbRawForm SYSTEM "xml/gnome-db-raw-form.xml">
<!ENTITY libgnomedb-GnomeDbRawGrid SYSTEM "xml/gnome-db-raw-grid.xml">
<!ENTITY libgnomedb-GnomeDbServerOperation SYSTEM "xml/gnome-db-server-operation.xml">
<!ENTITY libgnomedb-stock SYSTEM "xml/gnome-db-stock.xml">
<!ENTITY libgnomedb-GnomeDbTools SYSTEM "xml/gnome-db-tools.xml">
<!ENTITY libgnomedb-GnomeDbTransactionStatus SYSTEM "xml/gnome-db-transaction-status.xml">
<!ENTITY libgnomedb-editor SYSTEM "xml/gnome-db-editor.xml">
<!ENTITY libgnomedb-error-dialog SYSTEM "xml/gnome-db-error-dialog.xml">
<!ENTITY libgnomedb-error SYSTEM "xml/gnome-db-error.xml">
<!ENTITY libgnomedb-gray-bar SYSTEM "xml/gnome-db-gray-bar.xml">
<!ENTITY libgnomedb-report-editor SYSTEM "xml/gnome-db-report-editor.xml">
<!ENTITY libgnomedb-GnomeDbSelector SYSTEM "xml/gnome-db-selector.xml">
<!ENTITY libgnomedb-GnomeDbSelectorMeta SYSTEM "xml/gnome-db-selector-meta.xml">
<!ENTITY libgnomedb-GnomeDbSelectorPart SYSTEM "xml/gnome-db-selector-part.xml">
<!ENTITY libgnomedb-GnomeDbSelectorSchema SYSTEM "xml/gnome-db-selector-schema.xml">
<!ENTITY libgnomedb-GnomeDbSelectorTable SYSTEM "xml/gnome-db-selector-table.xml">
<!ENTITY libgnomedb-GnomeDbSelectorView SYSTEM "xml/gnome-db-selector-view.xml">
<!ENTITY libgnomedb-GnomeDbSqlConsole SYSTEM "xml/gnome-db-sql-console.xml">
<!ENTITY libgnomedb-GnomeDbEntryCidr SYSTEM "xml/gnome-db-entry-cidr.xml">
<!ENTITY libgnomedb-GnomeDbEntryFilesel SYSTEM "xml/gnome-db-entry-filesel.xml">
<!ENTITY libgnomedb-GnomeDbEntryPassword SYSTEM "xml/gnome-db-entry-password.xml">
<!ENTITY libgnomedb-GnomeDbEntryText SYSTEM "xml/gnome-db-entry-text.xml">
<!ENTITY libgnomedb-GnomeDbDataCellRendererBoolean SYSTEM "xml/gnome-db-data-cell-renderer-boolean.xml">
<!ENTITY libgnomedb-GnomeDbDataCellRendererCombo SYSTEM "xml/gnome-db-data-cell-renderer-combo.xml">
<!ENTITY libgnomedb-GnomeDbDataCellRendererInfo SYSTEM "xml/gnome-db-data-cell-renderer-info.xml">
<!ENTITY libgnomedb-GnomeDbDataCellRendererTextual SYSTEM "xml/gnome-db-data-cell-renderer-textual.xml">
<!ENTITY libgnomedb-GnomeDbEntryBoolean SYSTEM "xml/gnome-db-entry-boolean.xml">
<!ENTITY libgnomedb-GnomeDbEntryCombo SYSTEM "xml/gnome-db-entry-combo.xml">
<!ENTITY libgnomedb-GnomeDbEntryNone SYSTEM "xml/gnome-db-entry-none.xml">
<!ENTITY libgnomedb-GnomeDbEntryShell SYSTEM "xml/gnome-db-entry-shell.xml">
<!ENTITY libgnomedb-GnomeDbFormatEntry SYSTEM "xml/gnome-db-format-entry.xml">
<!ENTITY libgnomedb-GnomeDbEntryString SYSTEM "xml/gnome-db-entry-string.xml">
<!ENTITY libgnomedb-GnomeDbEntryCommonTime SYSTEM "xml/gnome-db-entry-common-time.xml">
<!ENTITY libgnomedb-GnomeDbEntryTime SYSTEM "xml/gnome-db-entry-time.xml">
<!ENTITY libgnomedb-GnomeDbEntryDate SYSTEM "xml/gnome-db-entry-date.xml">
<!ENTITY libgnomedb-GnomeDbEntryTimestamp SYSTEM "xml/gnome-db-entry-timestamp.xml">
<!ENTITY libgnomedb-GnomeDbEntryWrapper SYSTEM "xml/gnome-db-entry-wrapper.xml">
<!ENTITY libgnomedb-GnomeDbCanvasColumn SYSTEM "xml/gnome-db-canvas-column.xml">
<!ENTITY libgnomedb-GnomeDbCanvasCursor SYSTEM "xml/gnome-db-canvas-cursor.xml">
<!ENTITY libgnomedb-GnomeDbCanvasDbRelations SYSTEM "xml/gnome-db-canvas-db-relations.xml">
<!ENTITY libgnomedb-GnomeDbCanvasFkey SYSTEM "xml/gnome-db-canvas-fkey.xml">
<!ENTITY libgnomedb-GnomeDbCanvas SYSTEM "xml/gnome-db-canvas.xml">
<!ENTITY libgnomedb-GnomeDbCanvasItem SYSTEM "xml/gnome-db-canvas-item.xml">
<!ENTITY libgnomedb-GnomeDbCanvasPrint SYSTEM "xml/gnome-db-canvas-print.xml">
<!ENTITY libgnomedb-GnomeDbCanvasTable SYSTEM "xml/gnome-db-canvas-table.xml">
<!ENTITY libgnomedb-GnomeDbCanvasText SYSTEM "xml/gnome-db-canvas-text.xml">
<!ENTITY libgnomedb-GnomeDbCanvasTip SYSTEM "xml/gnome-db-canvas-tip.xml">
<!ENTITY libgnomedb-GnomeDbGraph SYSTEM "xml/gnome-db-graph.xml">
<!ENTITY libgnomedb-GnomeDbGraphItem SYSTEM "xml/gnome-db-graph-item.xml">
<!ENTITY libgnomedb-TreeIndex SYSTEM "xml/tree_index.sgml">
<!ENTITY libgnomedb-Enums SYSTEM "xml/gnome-db-enums.xml">

]>
<book id="index">
  <bookinfo>
    <title>Libgnomedb 4.0 Reference Manual</title>
    <authorgroup>
      <author>
        <firstname>Rodrigo</firstname>
        <surname>Moya</surname>
        <affiliation>
          <address><email>rodrigo@gnome-db.org</email></address>
        </affiliation>
      </author>
      <author>
        <firstname>Vivien</firstname>
        <surname>Malerba</surname>
        <affiliation>
          <address><email>malerba@gnome-db.org</email></address>
        </affiliation>
      </author>
    </authorgroup>
    <date>2006 January</date>
    <copyright>
      <year>2001-2006</year>
      <holder>The GNOME Foundation</holder>
    </copyright>
    <abstract>
      <para>
	&LIBGNOMEDB; is a data-bound UI library, based on &LIBGDA;.
      </para>
    </abstract>
    <legalnotice id="legalnotice">
      <para>
        Permission is granted to copy, distribute and/or modify this document
        under the terms of the <link linkend="fdl"><citetitle>GNU
        Free Documentation License</citetitle></link>, Version 1.1 or any later
        version published by the Free Software Foundation with no Invariant
        Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the
        license can be found in <xref linkend="fdl">Appendix about FDL</xref>.
      </para>
      <para>
        Many of the names used by companies to distinguish their products and
        services are claimed as trademarks. Where those names appear in any
        GNOME documentation, and those trademarks are made aware to the members
        of the GNOME Documentation Project, the names have been printed in caps
        or initial caps.
      </para>
    </legalnotice>
  </bookinfo>


  <part id="part_begin">
    <title>Getting started</title>
    <chapter id="introduction">
      <title>Introduction</title>
      <para>
	While &LIBGDA; provides the low level data access bits to &GNOME-DB;,
	&LIBGNOMEDB; provides a rich set of UI features targeted to the
	development of data access applications.
      </para>
      <para>
	Using &LIBGNOMEDB; your GTK/GNOME application data access needs will
	be covered. You'll have available, nicely integrated with the rest of
	the GNOME libraries, a whole set of data-bound widgets.
      </para>
    </chapter>

    <chapter id="features">
      <title>&LIBGNOMEDB; features</title>
      <para>
        This section presents the main features of the 4.0 version of &LIBGNOMEDB;.
      </para>
      <para>
	<para>Libgnomedb uses Libgda and provides ready-to-use graphical widgets extending the GTK+ toolkit; 
	  its main features are:
          <itemizedlist>
            <listitem>
              <para>Data bound widgets where any <classname>GdaDataModel</classname> can be presented in a tabular, a form
              or a combo box.</para>
            </listitem>
            <listitem>
              <para>A widget to display the contents of a dictionary.</para>
            </listitem>
            <listitem>
              <para>A widget which acts as a SQL console.</para>
            </listitem>
            <listitem>
              <para>A text widget to enter SQL text with syntaxic coloration.</para>
            </listitem>
            <listitem>
              <para>A widget to enter the required parameters to execute a data definition query.</para>
            </listitem>
            <listitem>
              <para>Widgets to manage data sources.</para>
            </listitem>
            <listitem>
              <para>A widget to perform a login to a database.</para>
            </listitem>
            <listitem>
              <para>Widgets specialized to enter and view diverse kind of data such as text, date, picture, along
              with a plugin system where custom made entry widgets can be used.</para>
            </listitem>
            <listitem>
              <para>Widgets to represents graphs.</para>
            </listitem>
          </itemizedlist>
        </para>
      </para>
    </chapter>

    <chapter id="architecture">
      <title>&LIBGNOMEDB; architecture</title>
      <para>
        &LIBGNOMEDB; extensively uses &LIBGDA; for all the low level access to the databases, and the GTK+ toolkit
	for all the GUI parts. The &LIBGNOMEDB; library is devided into smaller parts which are:
	<itemizedlist>
            <listitem><para>The "core" part which contains all the data bound widgets, and is referenced as 'libgnomedb-4.0'
	      to <application>pkg-config</application>;</para>
            </listitem>
            <listitem><para>The "extra" part which contains some usefull widgets such as the 
		<link linkend="GnomeDbSelector">GnomeDbSelector</link> widget (which displays elements contained in a
		dictionary as a tree like structure); this part is referenced as 'libgnomedb-extra-4.0' to 
		<application>pkg-config</application>;</para>
            </listitem>
            <listitem><para>The "graph" part which contains graph related widgets (and require the GnomeCanvas library),
	      referenced as 'libgnomedb-graph-4.0' to <application>pkg-config</application>; note that this library is not 
		built if the GnomeCanvas library is not found when compiling.</para>
            </listitem>
	</itemizedlist>
      </para>
    </chapter>

    <chapter id="libgnomedb-example">
      <title>A small example</title>
      &libgnomedb-Example;
    </chapter>
    <chapter>
      <title>Widget Gallery</title>
      &visual-index;
    </chapter>

    &migration;
    &migration2;
  </part>
  
  <part>
    <title>&LIBGNOMEDB; API Reference</title>
    <chapter>
      <title>Object Hierarchy</title>
      &libgnomedb-TreeIndex;
    </chapter>

    &libgnomedb-init;

    <chapter id="dsn-widgets">
      <title>Datasources and connection related widgets</title>
      <para>
	This section describes widgets which can be used to work on providers (glue code between
	&LIBGDA; and the various DBMS), on the data sources (parameters for a ready-to-use
	connection), and to display a login information.
      </para>
      &libgnomedb-provider-selector;
      &libgnomedb-provider-auth-editor;
      &libgnomedb-provider-spec-editor;
      &libgnomedb-data-source-selector;
      &libgnomedb-login;
      &libgnomedb-login-dialog;
      &libgnomedb-dsn-editor;
      &libgnomedb-dsn-assistant;
      &libgnomedb-connection-properties;
      &libgnomedb-GnomeDbServerOperation;
      &libgnomedb-GnomeDbTransactionStatus;
    </chapter>
    <chapter id="databound-widgets">
      <title>Data bound widgets</title>
      <para>
	The main feature provided by libgnomedb is a rich set of data bound
	widgets, ranging from the simplest ones, such as entry widgets or
	labels, to the most full-featured ones you can imagine.
      </para>
      &libgnomedb-combo;
      &libgnomedb-GnomeDbBasicForm;
      &libgnomedb-GnomeDbRawForm;
      &libgnomedb-GnomeDbForm;
      &libgnomedb-GnomeDbRawGrid;
      &libgnomedb-GnomeDbGrid;
      &libgnomedb-find-dialog;
      &libgnomedb-GnomeDbDataWidget;
      &libgnomedb-GnomeDbDataWidgetFilter;
      &libgnomedb-GnomeDbDataWidgetInfo;
      &libgnomedb-GnomeDbDataStore;
      &libgnomedb-GnomeDbDataImport;
    </chapter>
    <chapter>
      <title>Individual data entry widgets</title>
      <para>
	The widgets listed in this section implement the <link linkend="GnomeDbDataEntry">GnomeDbDataEntry</link> 
	interface. They are useally created using the corresponding 
	<link linkend="GdaDataHandler">GdaDataHandler</link> data handler.
      </para>
      &libgnomedb-GnomeDbTools;
      &libgnomedb-GnomeDbDataEntry;
      &libgnomedb-GnomeDbFormatEntry;
      &libgnomedb-GnomeDbEntryString;
      &libgnomedb-GnomeDbEntryBoolean;
      &libgnomedb-GnomeDbEntryTime;
      &libgnomedb-GnomeDbEntryDate;
      &libgnomedb-GnomeDbEntryTimestamp;
      &libgnomedb-GnomeDbEntryNone;
      &libgnomedb-GnomeDbEntryCombo;

      &libgnomedb-GnomeDbEntryCidr;
      &libgnomedb-GnomeDbEntryPassword;
      &libgnomedb-GnomeDbEntryText;
      &libgnomedb-GnomeDbEntryFilesel;
    </chapter>
    <chapter>
      <title>Cell renderers</title>
      &libgnomedb-GnomeDbDataCellRendererInfo;
      &libgnomedb-GnomeDbDataCellRendererTextual;
      &libgnomedb-GnomeDbDataCellRendererBoolean;
      &libgnomedb-GnomeDbDataCellRendererCombo;
    </chapter>
    <chapter>
      <title>Extra widgets</title>
      <para>All the widgets in this section are in the "extra" library, you must include the following headers:
	<programlisting>
#include &lt;libgnomedb/libgnomedb.h&gt;
#include &lt;libgnomedb-extra/libgnomedb-extra.h&gt;
	</programlisting>
	and request the "libgnomedb-extra-4.0" library when using <application>pkg-config</application>.
      </para>
      &libgnomedb-GnomeDbSqlConsole;
      &libgnomedb-editor;
      &libgnomedb-GnomeDbSelector;
      &libgnomedb-GnomeDbSelectorPart;
      &libgnomedb-GnomeDbSelectorMeta;
      &libgnomedb-GnomeDbSelectorSchema;
      &libgnomedb-GnomeDbSelectorTable;
      &libgnomedb-GnomeDbSelectorView;
      &libgnomedb-error-dialog;
      &libgnomedb-error;
      &libgnomedb-report-editor;
      &libgnomedb-gray-bar;
    </chapter>
    <chapter>
      <title>Graph widgets</title>
      <para>All the widgets in this section are in the "graph" library, you must include the following headers:
	<programlisting>
#include &lt;libgnomedb/libgnomedb.h&gt;
#include &lt;libgnomedb-graph/libgnomedb-graph.h&gt;
	</programlisting>
	and request the "libgnomedb-graph-4.0" library when using <application>pkg-config</application>.
      </para>
      &libgnomedb-GnomeDbCanvasColumn;
      &libgnomedb-GnomeDbGraph;
      &libgnomedb-GnomeDbGraphItem;
      &libgnomedb-GnomeDbCanvas;
      &libgnomedb-GnomeDbCanvasDbRelations;
      &libgnomedb-GnomeDbCanvasItem;
      &libgnomedb-GnomeDbCanvasPrint;
      &libgnomedb-GnomeDbCanvasTable;
      &libgnomedb-GnomeDbCanvasTip;
      &libgnomedb-GnomeDbCanvasCursor;
      &libgnomedb-GnomeDbCanvasText;
      &libgnomedb-GnomeDbCanvasFkey;
    </chapter>
    <chapter id="misc">
      <title>Miscellaneous</title>
      &libgnomedb-Enums;
      &libgnomedb-stock;
    </chapter>
    <chapter id="non-inst-widgets">
      <title>Non instantiable objects and widgets</title>
      &libgnomedb-GnomeDbEntryShell;
      &libgnomedb-GnomeDbEntryWrapper;
      &libgnomedb-GnomeDbEntryCommonTime;
    </chapter>
  </part>

  <part id="part_index">
    <title>Appendix</title>
    &fdl-appendix;
    <index>
      <title>Index</title>
    </index>
  </part>
</book>
