+2009-04-06 Alberto Garcia <agarcia@igalia.com>
+
+ Patch by Iván Gómez (igomez@igalia.com)
+
+ * doc/building.sgml
+ * doc/compiling.sgml
+ * doc/hildon-docs.sgml
+ * doc/hildon-sections.txt
+ * doc/migration.sgml
+ * doc/resources.sgml
+ * doc/running.sgml:
+ New chapters on using the Hildon library.
+ Updated the general structure of the reference manual.
+ Other minor documentation fixes.
+
+ * src/hildon-calendar-popup.c
+ * src/hildon-calendar.c
+ * src/hildon-controlbar.c
+ * src/hildon-date-editor.c
+ * src/hildon-dialog.c
+ * src/hildon-hvolumebar.c
+ * src/hildon-number-editor.c
+ * src/hildon-range-editor.c
+ * src/hildon-sort-dialog.c
+ * src/hildon-time-editor.c
+ * src/hildon-time-picker.c
+ * src/hildon-volumebar-range.c
+ * src/hildon-volumebar.c
+ * src/hildon-vvolumebar.c
+ * src/hildon-weekday-picker.c:
+ Add deprecation notes
+
+ * src/hildon-pannable-area.c (hildon_pannable_area_class_init):
+ Document 'horizontal-movement' and 'vertical-movement' signals.
+
2009-04-06 Claudio Saavedra <csaavedra@igalia.com>
[Release 2.1.60]
--- /dev/null
+<refentry id="hildon-building">
+<refmeta>
+<refentrytitle>Compiling the Hildon libraries</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>Hildon Library</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>Compiling the Hildon Libraries</refname>
+<refpurpose>
+How to compile Hildon itself
+</refpurpose>
+</refnamediv>
+ <refsect1 id="overview">
+ <title>Building Hildon on UNIX-like systems</title>
+ <para>
+ This chapter covers building and installing Hildon on UNIX and
+ UNIX-like systems such as GNU/Linux.
+ </para>
+ <para>
+ On UNIX-like systems Hildon uses the standard GNU build system,
+ using <application>autoconf</application> for package
+ configuration and resolving portability issues,
+ <application>automake</application> for building makefiles that
+ comply with the GNU Coding Standards, and
+ <application>libtool</application> for building shared libraries
+ on multiple platforms.
+ </para>
+ <para>
+ The first thing to do before start building Hildon widgets is to
+ uncompress the source tarball packages. For example:
+ </para>
+ <programlisting>
+ $ tar xvzf hildon-widgets-2.2.0.tar.gz
+ $ tar xvjf hildon-widgets-2.2.0.tar.bz2
+ </programlisting>
+ <para>
+ In the toplevel of the directory that is created, there will be
+ a shell script called <filename>configure</filename> which
+ you then run to take the template makefiles called
+ <filename>Makefile.in</filename> in the package and create
+ makefiles customized for your operating system. The <filename>configure</filename>
+ script can be passed various command line arguments to determine how
+ the package is built and installed. The most commonly useful
+ argument is the <systemitem>--prefix</systemitem> argument which
+ determines where the package is installed. To install a package
+ in <filename>/opt/hildon</filename> you would run configure as:
+ </para>
+ <programlisting>
+ $ ./configure --prefix=/opt/hildon
+ </programlisting>
+ <para>
+ A full list of options can be found by running
+ <filename>configure</filename> with the
+ <systemitem>--help</systemitem> argument. In general, the defaults are
+ right and should be trusted. After you've run
+ <filename>configure</filename>, you then run the
+ <command>make</command> and <command>make install</command> commands
+ to build the package and install it, respectively.
+ </para>
+ <programlisting>
+ $ make
+ $ make install
+ </programlisting>
+ <para>
+ If you don't have permission to write to the directory you are
+ installing in, you may have to change to root temporarily before
+ running <literal>make install</literal>. Also, if you are
+ installing in a system directory, on some systems you will need
+ to run <command>ldconfig</command> after <literal>make
+ install</literal> so that the newly installed libraries will be
+ found.
+ </para>
+ <para>
+ Several environment variables are useful to pass to set before
+ running configure. <envar>CPPFLAGS</envar> contains options to
+ pass to the C compiler, and is used to tell the compiler where
+ to look for include files. The <envar>LDFLAGS</envar> variable
+ is used in a similar fashion for the linker. Finally, the
+ <envar>PKG_CONFIG_PATH</envar> environment variable contains
+ a search path that <command>pkg-config</command> (see below)
+ uses when looking for for file describing how to compile
+ programs using different libraries. If you were installing Hildon
+ and its dependencies into <filename>/opt/hildon</filename>, you
+ might want to set these variables as:
+ </para>
+ <programlisting>
+ $ CPPFLAGS="-I/opt/hildon/include"
+ $ LDFLAGS="-L/opt/hildon/lib"
+ $ PKG_CONFIG_PATH="/opt/hildon/lib/pkgconfig"
+ $ export CPPFLAGS LDFLAGS PKG_CONFIG_PATH
+ </programlisting>
+ <para>
+ You may also need to set the <envar>LD_LIBRARY_PATH</envar>
+ environment variable so the systems dynamic linker can find
+ the newly installed libraries, and the <envar>PATH</envar>
+ environment program so that utility binaries installed by
+ the various libraries will be found.
+ </para>
+ <programlisting>
+ $ LD_LIBRARY_PATH="/opt/hildon/lib"
+ $ PATH="/opt/hildon/bin:$PATH"
+ $ export LD_LIBRARY_PATH PATH
+ </programlisting>
+ </refsect1>
+ <refsect1 id="dependencies">
+ <title>Dependencies</title>
+ <para>
+ Before you can compile the Hildon widget toolkit, you need to have
+ various other tools and libraries installed on your
+ system. The two tools needed during the build process (apart from
+ the tools mentioned above such as <application>autoconf</application>)
+ are <command>pkg-config</command> and GNU make.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <ulink
+ url="http://pkg-config.freedesktop.org">pkg-config</ulink>
+ is a tool for tracking the compilation flags needed for
+ libraries that are used by the Hildon libraries. For each
+ library, a small <literal>.pc</literal> text file is installed
+ in a standard location that contains the compilation flags
+ needed for that library along with version number information.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The Hildon makefiles will mostly work with different versions
+ of <command>make</command>, however, there tends to be
+ a few incompatibilities, so the Hildon team recommends
+ installing <ulink url="http://www.gnu.org/software/make">GNU
+ make</ulink> if you don't already have it on your system
+ and using it.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ GTK+
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Canberra
+ </para>
+ </listitem>
+ </itemizedlist>
+ </refsect1>
+ <refsect1 id="extra-configuration-options">
+ <title>Extra Configuration Options</title>
+ <para>
+ In addition to the normal options, the
+ <command>configure</command> script for the Hildon library
+ supports a number of additional arguments.
+ <cmdsynopsis>
+ <command>configure</command>
+ <group>
+ <arg>--disable-gtk-doc</arg>
+ <arg>--enable-gtk-doc</arg>
+ </group>
+ <group>
+ <arg>--enable-deprecated=[no|yes]</arg>
+ </group>
+ <group>
+ <arg>--with-examples=[no|yes]</arg>
+ </group>
+ <group>
+ <arg>--with-html-dir=PATH</arg>
+ </group>
+ <group>
+ <arg>--with-maemo-gtk=[no|yes]</arg>
+ </group>
+ <group>
+ <arg>--with-asserts=[no|yes]</arg>
+ </group>
+ </cmdsynopsis>
+ </para>
+ <formalpara>
+ <title><systemitem>--disable-gtk-doc</systemitem> and
+ <systemitem>--enable-gtk-doc</systemitem></title>
+
+ <para>
+ The <application>gtk-doc</application> package is
+ used to generate the reference documentation included
+ with Hildon. By default, support for <application>gtk-doc</application>
+ is disabled because it requires several extra dependencies
+ to be installed. If you have
+ <application>gtk-doc</application> installed and
+ are modifying Hildon, you may want to enable
+ <application>gtk-doc</application> support by passing
+ in <systemitem>--enable-gtk-doc</systemitem>. If not
+ enabled, pre-generated HTML files distributed with Hildon
+ will be installed.
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title><systemitem>--enable-deprecated</systemitem></title>
+
+ <para>
+ This option allows you to specify whether deprecated widgets included in the
+ package will be built or not.
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title><systemitem>--with-examples</systemitem></title>
+
+ <para>
+ This option allows you to specify whether examples included in the
+ package will be built or not.
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title><systemitem>--with-html-dir</systemitem></title>
+
+ <para>
+ This option allows you to specify the directory to install the
+ generated documentation.
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title><systemitem>--with-maemo-gtk</systemitem></title>
+
+ <para>
+ Use Maemo GTK+ API (enabled by default).
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title><systemitem>--with-asserts</systemitem></title>
+
+ <para>
+ Build with the assertion checks
+ </para>
+ </formalpara>
+
+ </refsect1>
+
+</refentry>
+
+<!-- Local Variables: -->
+<!-- sgml-parent-document: ("hildon-docs.sgml" "chapter" "refentry") -->
+<!-- End: -->
--- /dev/null
+<refentry id="hildon-compiling" revision="4 Feb 2001">
+<refmeta>
+<refentrytitle>Compiling Hildon Applications</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>HILDON Library</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>Compiling Hildon Applications</refname>
+<refpurpose>
+How to compile your Hildon application
+</refpurpose>
+</refnamediv>
+
+<refsect1>
+<title>Compiling Hildon Applications on UNIX</title>
+
+<para>
+To compile a Hildon application, you need to tell the compiler where to
+find the Hildon header files and libraries. This is done with the
+<literal>pkg-config</literal> utility.
+</para>
+<para>
+The following interactive shell session demonstrates how
+<literal>pkg-config</literal> is used (the actual output on
+your system may be different):
+<programlisting>
+$ pkg-config --cflags hildon-1
+-DMAEMO_CHANGES -DMAEMO_GTK -I/usr/include/hildon-1 -I/usr/include/gtk-2.0 -I/usr/lib/gtk-2.0/include -I/usr/include/atk-1.0 -I/usr/include/cairo -I/usr/include/pango-1.0
+-I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -I/usr/include/freetype2 -I/usr/include/libpng12 -I/usr/include/pixman-1
+$ pkg-config --libs hildon-1
+-lhildon-1 -lgtk-x11-2.0 -lgdk-x11-2.0 -latk-1.0 -lgdk_pixbuf-2.0 -lpangocairo-1.0 -lpango-1.0 -lcairo -lgobject-2.0 -lgmodule-2.0 -lglib-2.0
+</programlisting>
+</para>
+<para>
+The simplest way to compile a program is to use the "backticks"
+feature of the shell. If you enclose a command in backticks
+(<emphasis>not single quotes</emphasis>), then its output will be
+substituted into the command line before execution. So, to compile
+a Hildon Hello World you should type the following:
+<programlisting>
+$ cc `pkg-config --cflags --libs hildon-1` hello.c -o hello
+</programlisting>
+</para>
+
+<para>
+If you want to make sure that your program doesn't use any deprecated
+functions, you can define the preprocessor symbol HILDON_DISABLE_DEPRECATED
+by using the command line option <literal>-DHILDON_DISABLE_DEPRECATED=1</literal>.
+</para>
+
+</refsect1>
+</refentry>
<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY version SYSTEM "version.xml">
+<!ENTITY hildon-Building SYSTEM "building.sgml">
+<!ENTITY hildon-Compiling SYSTEM "compiling.sgml">
+<!ENTITY hildon-Building SYSTEM "building.sgml">
+<!ENTITY hildon-Running SYSTEM "running.sgml">
+<!ENTITY hildon-Resources SYSTEM "resources.sgml">
+<!ENTITY hildon-Migration SYSTEM "migration.sgml">
+<!ENTITY hildon-main SYSTEM "xml/hildon-main.xml">
+<!ENTITY hildon-gtk SYSTEM "xml/hildon-gtk.xml">
+<!ENTITY hildon-defines SYSTEM "xml/hildon-defines.xml">
+<!ENTITY HildonWindowStack SYSTEM "xml/hildon-window-stack.xml">
+<!ENTITY hildon-sound SYSTEM "xml/hildon-sound.xml">
]>
<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
<bookinfo>
- <title>hildon Reference Manual</title>
- <releaseinfo>
- for hildon &version;
- </releaseinfo>
+ <title>Hildon Reference Manual</title>
+ <releaseinfo>for Hildon &version;</releaseinfo>
</bookinfo>
- <chapter>
- <title>Object Hierarchy</title>
- <xi:include href="xml/tree_index.sgml"/>
- </chapter>
+ <part id="hildon">
+ <title>Hildon Overview</title>
+ <partintro>
+ <para>
+ Hildon Widgets is a set of widgets present in the Hildon framework.
+ Its aim is to create finger-friendly graphical interfaces specially
+ designed for use in mobile devices.
+ </para>
+ <para>
+ This set of widgets is based on GTK+ and were first developed for
+ the Maemo platform, used by Nokia Internet Tablets.
+ </para>
+ <para>
+ Hildon depends on the following libraries:
+ <variablelist>
- <chapter>
- <title>Widgets gallery</title>
- <xi:include href="visual_index.xml"/>
- </chapter>
+ <varlistentry>
+ <term>GTK+</term>
+ <listitem>
+ <para>
+ GTK+ is a library for creating graphical user interfaces.
+ </para></listitem>
+ </varlistentry>
- <chapter>
- <title>Toplevel Widgets</title>
- <xi:include href="xml/hildon-window.xml"/>
- <xi:include href="xml/hildon-stackable-window.xml"/>
- <xi:include href="xml/hildon-program.xml"/>
- </chapter>
-
- <chapter>
- <title>Selectors</title>
- <xi:include href="xml/hildon-button.xml"/>
- <xi:include href="xml/hildon-check-button.xml"/>
- <xi:include href="xml/hildon-color-button.xml"/>
- <xi:include href="xml/hildon-color-chooser.xml"/>
- <xi:include href="xml/hildon-controlbar.xml"/>
- <xi:include href="xml/hildon-volumebar.xml"/>
- <xi:include href="xml/hildon-vvolumebar.xml"/>
- <xi:include href="xml/hildon-hvolumebar.xml"/>
- <xi:include href="xml/hildon-seekbar.xml"/>
- <xi:include href="xml/hildon-calendar-popup.xml"/>
- <xi:include href="xml/hildon-calendar.xml"/>
- <xi:include href="xml/hildon-weekday-picker.xml"/>
- <xi:include href="xml/hildon-time-picker.xml"/>
- <xi:include href="xml/hildon-app-menu.xml"/>
- <xi:include href="xml/hildon-touch-selector.xml"/>
- <xi:include href="xml/hildon-touch-selector-column.xml"/>
- <xi:include href="xml/hildon-touch-selector-entry.xml"/>
- <xi:include href="xml/hildon-date-selector.xml"/>
- <xi:include href="xml/hildon-time-selector.xml"/>
- <xi:include href="xml/hildon-picker-button.xml"/>
- <xi:include href="xml/hildon-time-button.xml"/>
- <xi:include href="xml/hildon-date-button.xml"/>
- </chapter>
-
- <chapter>
- <title>Containers</title>
- <xi:include href="xml/hildon-pannable-area.xml"/>
- </chapter>
-
- <chapter>
- <title>Editors</title>
- <xi:include href="xml/hildon-number-editor.xml"/>
- <xi:include href="xml/hildon-range-editor.xml"/>
- <xi:include href="xml/hildon-time-editor.xml"/>
- <xi:include href="xml/hildon-date-editor.xml"/>
- <xi:include href="xml/hildon-entry.xml"/>
- <xi:include href="xml/hildon-text-view.xml"/>
- </chapter>
-
- <chapter>
- <title>Miscellaneous controls</title>
- <xi:include href="xml/hildon-find-toolbar.xml"/>
- <xi:include href="xml/hildon-edit-toolbar.xml"/>
- <xi:include href="xml/hildon-caption.xml"/>
- <xi:include href="xml/hildon-bread-crumb-trail.xml"/>
- </chapter>
-
- <chapter>
- <title>Notifications</title>
- <xi:include href="xml/hildon-banner.xml"/>
- <xi:include href="xml/hildon-note.xml"/>
- </chapter>
-
- <chapter>
- <title>Dialogs</title>
- <xi:include href="xml/hildon-dialog.xml"/>
- <xi:include href="xml/hildon-color-chooser-dialog.xml"/>
- <xi:include href="xml/hildon-set-password-dialog.xml"/>
- <xi:include href="xml/hildon-get-password-dialog.xml"/>
- <xi:include href="xml/hildon-login-dialog.xml"/>
- <xi:include href="xml/hildon-sort-dialog.xml"/>
- <xi:include href="xml/hildon-font-selection-dialog.xml"/>
- <xi:include href="xml/hildon-code-dialog.xml"/>
- <xi:include href="xml/hildon-wizard-dialog.xml"/>
- <xi:include href="xml/hildon-picker-dialog.xml"/>
- </chapter>
-
- <chapter>
- <title>Other</title>
+ <varlistentry>
+ <term>GConf</term>
+ <listitem><para>
+ GConf is a system for storing application preferences. It is intended for user preferences; not configuration of something like Apache, or arbitrary data storage.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>libcanberra</term>
+ <listitem><para>
+ libcanberra is an implementation of the XDG Sound Theme and Name Specifications, for generating event sounds on free desktops, such as GNOME.
+ </para></listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </para>
+ </partintro>
+ &hildon-Building;
+ &hildon-Compiling;
+ &hildon-Running;
+ &hildon-Resources;
+ </part>
+
+ <part id="hildonbase">
+ <title>Hildon Core Reference</title>
<xi:include href="xml/hildon-main.xml"/>
<xi:include href="xml/hildon-gtk.xml"/>
- <xi:include href="xml/hildon-sound.xml"/>
- <xi:include href="xml/hildon-helper.xml"/>
<xi:include href="xml/hildon-defines.xml"/>
- <xi:include href="xml/hildon-bread-crumb.xml"/>
- <xi:include href="xml/hildon-window-stack.xml"/>
- </chapter>
+ <xi:include href="xml/hildon-helper.xml"/>
+ <xi:include href="xml/hildon-sound.xml"/>
+ <xi:include href="xml/hildon-program.xml"/>
+ </part>
+
+ <part id="hildonobjects">
+ <title>Hildon Widgets and Objects</title>
+
+ <chapter>
+ <title>Object Hierarchy</title>
+ <xi:include href="xml/tree_index.sgml"/>
+ </chapter>
+
+ <chapter>
+ <title>Widgets gallery</title>
+ <xi:include href="visual_index.xml"/>
+ </chapter>
+
+ <chapter>
+ <title>Toplevel Widgets</title>
+ <xi:include href="xml/hildon-window.xml"/>
+ <xi:include href="xml/hildon-stackable-window.xml"/>
+ </chapter>
+
+ <chapter>
+ <title>Window Stacking</title>
+ <xi:include href="xml/hildon-window-stack.xml"/>
+ </chapter>
+
+ <chapter>
+ <title>Buttons and Toggles</title>
+ <xi:include href="xml/hildon-button.xml"/>
+ <xi:include href="xml/hildon-check-button.xml"/>
+ <xi:include href="xml/hildon-picker-button.xml"/>
+ <xi:include href="xml/hildon-date-button.xml"/>
+ <xi:include href="xml/hildon-time-button.xml"/>
+ </chapter>
+
+ <chapter>
+ <title>Display and Notification Widgets</title>
+ <xi:include href="xml/hildon-caption.xml"/>
+ <xi:include href="xml/hildon-banner.xml"/>
+ <xi:include href="xml/hildon-note.xml"/>
+ </chapter>
+
+ <chapter>
+ <title>Data Selection and Handling</title>
+ <xi:include href="xml/hildon-touch-selector.xml"/>
+ <xi:include href="xml/hildon-touch-selector-column.xml"/>
+ <xi:include href="xml/hildon-touch-selector-entry.xml"/>
+ <xi:include href="xml/hildon-date-selector.xml"/>
+ <xi:include href="xml/hildon-time-selector.xml"/>
+ </chapter>
+
+ <chapter>
+ <title>Navigation Widgets</title>
+ <xi:include href="xml/hildon-pannable-area.xml"/>
+ </chapter>
+
+ <chapter>
+ <title>Text Display and Handling</title>
+ <xi:include href="xml/hildon-entry.xml"/>
+ <xi:include href="xml/hildon-text-view.xml"/>
+ </chapter>
+
+ <chapter>
+ <title>Menus and Toolbars</title>
+ <xi:include href="xml/hildon-app-menu.xml"/>
+ <xi:include href="xml/hildon-find-toolbar.xml"/>
+ <xi:include href="xml/hildon-edit-toolbar.xml"/>
+ </chapter>
+
+ <chapter>
+ <title>Dialogs</title>
+ <xi:include href="xml/hildon-wizard-dialog.xml"/>
+ <xi:include href="xml/hildon-picker-dialog.xml"/>
+ </chapter>
+
+ <chapter>
+ <title>Deprecated</title>
+ <xi:include href="xml/hildon-color-button.xml"/>
+ <xi:include href="xml/hildon-color-chooser.xml"/>
+ <xi:include href="xml/hildon-controlbar.xml"/>
+ <xi:include href="xml/hildon-volumebar.xml"/>
+ <xi:include href="xml/hildon-vvolumebar.xml"/>
+ <xi:include href="xml/hildon-hvolumebar.xml"/>
+ <xi:include href="xml/hildon-seekbar.xml"/>
+ <xi:include href="xml/hildon-calendar.xml"/>
+ <xi:include href="xml/hildon-calendar-popup.xml"/>
+ <xi:include href="xml/hildon-weekday-picker.xml"/>
+ <xi:include href="xml/hildon-time-picker.xml"/>
+ <xi:include href="xml/hildon-number-editor.xml"/>
+ <xi:include href="xml/hildon-range-editor.xml"/>
+ <xi:include href="xml/hildon-time-editor.xml"/>
+ <xi:include href="xml/hildon-date-editor.xml"/>
+ <xi:include href="xml/hildon-bread-crumb-trail.xml"/>
+ <xi:include href="xml/hildon-dialog.xml"/>
+ <xi:include href="xml/hildon-color-chooser-dialog.xml"/>
+ <xi:include href="xml/hildon-set-password-dialog.xml"/>
+ <xi:include href="xml/hildon-get-password-dialog.xml"/>
+ <xi:include href="xml/hildon-login-dialog.xml"/>
+ <xi:include href="xml/hildon-sort-dialog.xml"/>
+ <xi:include href="xml/hildon-font-selection-dialog.xml"/>
+ <xi:include href="xml/hildon-code-dialog.xml"/>
+ <xi:include href="xml/hildon-bread-crumb.xml"/>
+ </chapter>
+
+ </part>
+
+ <part id="hildonmigration">
+ <title>Migration</title>
+ <partintro>
+ <para>This section helps you migrate widgets that are deprecated by
+ providing an alternative to them. Most sections have examples
+ of how a given deprecated widget was used and provide another example
+ of how the functionality of that widget should be accomplished in
+ newly written code.</para>
+ </partintro>
+ &hildon-Migration;
+ </part>
<index>
<title>Index</title>
</index>
+ <index role="deprecated">
+ <title>Index of deprecated symbols</title>
+ </index>
+
+ <index role="2.2">
+ <title>Index of new symbols in 2.2</title>
+ </index>
+
<!-- New symbols index -->
</book>
<SECTION>
<FILE>hildon-gtk</FILE>
+<TITLE>Additions to GTK+</TITLE>
hildon_gtk_menu_new
hildon_gtk_button_new
hildon_gtk_toggle_button_new
<SECTION>
<FILE>hildon-sound</FILE>
+<TITLE>Sound Utilities</TITLE>
hildon_play_system_sound
</SECTION>
<SECTION>
<FILE>hildon-helper</FILE>
+<TITLE>Helper Functions</TITLE>
hildon_helper_set_logical_font
hildon_helper_set_logical_color
hildon_helper_event_button_is_finger
<SECTION>
<FILE>hildon-defines</FILE>
+<TITLE>Defines</TITLE>
HILDON_ICON_SIZE_XSMALL
HILDON_ICON_SIZE_SMALL
HILDON_ICON_SIZE_STYLUS
<SECTION>
<FILE>hildon-main</FILE>
+<TITLE>Main</TITLE>
hildon_init
hildon_gtk_init
</SECTION>
--- /dev/null
+<refentry id="hildon-migration-control-bar" revision="13 Feb 2001">
+<refmeta>
+<refentrytitle>Control Bar</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>Hildon Library</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+ <refname>Control Bar</refname>
+ <refpurpose>How to migrate Control Bars</refpurpose>
+</refnamediv>
+
+<refsect1 id="hildon-migrating-control-bar">
+ <title>Migrating Control Bars</title>
+
+ <para>ControlBar widgets are deprecated since Hildon 2.2 and a GtkScale
+ should be used to accomplish the same functionality.</para>
+
+ <para>To make a GtkScale have the same functionality as a control
+ bar you'll need to change some properties of the widget's Adjustment
+ so it has a range equal to the control bar's as well as the step
+ increment.</para>
+
+ <para>The following example shows a control bar with the range of
+ 0 to 4.</para>
+
+ <example>
+ <title>A Typical Control Bar</title>
+ <programlisting>
+<![CDATA[
+HildonControlbar *bar = HILDON_CONTROLBAR (hildon_controlbar_new ());
+hildon_controlbar_set_range (bar, 1, 4);
+hildon_controlbar_set_value (bar, 2);
+]]>
+ </programlisting>
+ </example>
+
+ <para>To accomplish the same functionality as the previous control
+ bar example, one could use something like in the following example.</para>
+
+ <example>
+ <title>A Replacement for the Control Bar</title>
+ <programlisting>
+<![CDATA[
+GtkHScale *scale = GTK_HSCALE (hildon_gtk_hscale_new ());
+GtkAdjustment *adjustment = GTK_ADJUSTMENT (
+ gtk_range_get_adjustment (GTK_RANGE (scale)));
+g_object_set (adjustment, "step-increment", 1, "lower", 0, NULL);
+g_object_set (adjustment, "upper", 4, NULL);
+g_object_set (adjustment, "value", 2, NULL);
+]]>
+ </programlisting>
+ </example>
+</refsect1>
+</refentry>
+
+<refentry id="hildon-migration-volume-bar" revision="13 Feb 2001">
+<refmeta>
+<refentrytitle>Volume Bar</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>Hildon Library</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+ <refname>Volume Bar</refname>
+ <refpurpose>How to migrate Volume Bars</refpurpose>
+</refnamediv>
+
+<refsect1 id="hildon-migrating-volume-bar">
+ <title>Migrating Volume Bars</title>
+
+ <para>VolumeBar widgets are deprecated since Hildon 2.2 and the way
+ to exactly reproduce their functionality is to use a GtkScale together
+ with a toggle button. Instead of the toggle button, a Hildon picker
+ button could be used or two radio buttons or any other widgets that
+ allow the user to choose from two options. The toggle button is used
+ in this example since it is the very similar with the deprecated
+ volume bar's button.</para>
+
+ <para>The deprecated volume bar is shown on the example bellow.</para>
+
+ <example>
+ <title>A Typical Volume Bar</title>
+ <programlisting>
+<![CDATA[
+HildonVVolumebar *bar = HILDON_VVOLUMEBAR (hildon_vvolumebar_new ());
+gtk_widget_set_size_request (GTK_WIDGET (bar), -1, 300);
+]]>
+ </programlisting>
+ </example>
+
+ <para>A very similar widget can be done like the following example
+ shows.</para>
+
+ <example>
+ <title>A Replacement for the Volume Bar</title>
+ <programlisting>
+<![CDATA[
+void
+toggle_volume_state_cb (GtkToggleButton *toggle, gpointer data)
+{
+ GtkVScale *bar = GTK_VSCALE (data);
+ gboolean mute = gtk_toggle_button_get_active (toggle);
+ gtk_widget_set_sensitive (GTK_WIDGET (bar), !mute);
+}
+
+GtkVScale *bar = GTK_VSCALE (hildon_gtk_vscale_new ());
+gtk_widget_set_size_request (GTK_WIDGET (bar), -1, 300);
+gtk_range_set_restrict_to_fill_level (GTK_RANGE (bar), TRUE);
+GtkToggleButton *toggle_volume = GTK_TOGGLE_BUTTON (hildon_gtk_toggle_button_new (
+ HILDON_SIZE_FINGER_HEIGHT));
+gtk_button_set_label (GTK_BUTTON (toggle_volume), "Mute");
+g_signal_connect (toggle_volume, "toggled",
+ G_CALLBACK (toggle_volume_state_cb), bar);
+GtkVBox *volume = GTK_VBOX (gtk_vbox_new (0, FALSE));
+gtk_container_add (GTK_CONTAINER (volume), GTK_WIDGET (bar));
+gtk_box_pack_end (GTK_BOX (volume), GTK_WIDGET (toggle_volume), FALSE, FALSE, 0);
+]]>
+ </programlisting>
+ </example>
+</refsect1>
+</refentry>
+
+<refentry id="hildon-migration-date-widgets" revision="13 Feb 2001">
+<refmeta>
+<refentrytitle>Date Widgets</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>Hildon Library</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+ <refname>Date Bar</refname>
+ <refpurpose>How to migrate Date widgets</refpurpose>
+</refnamediv>
+
+<refsect1 id="hildon-migrating-date-widgets">
+ <title>Migrating Date Widgets</title>
+
+ <para>Being deprecated since Hildon 2.2, the calendar popup and
+ date editor can be substituded by a HildonDateButton.</para>
+
+ <para>Examples of a typical calendar popup and a date editor are
+ presented bellow.</para>
+
+ <example>
+ <title>A Typical Calendar Popup</title>
+ <programlisting>
+<![CDATA[
+guint y = 2009, m = 4, d = 25;
+GtkWidget *parent, *popup;
+popup = hildon_calendar_popup_new (GTK_WINDOW (parent), y, m, d);
+gtk_dialog_run (GTK_DIALOG (popup));
+hildon_calendar_popup_get_date (HILDON_CALENDAR_POPUP (popup),
+ &y, &m, &d);
+]]>
+ </programlisting>
+ </example>
+
+ <example>
+ <title>A Typical Date Editor</title>
+ <programlisting>
+<![CDATA[
+gboolean
+on_error (GtkWidget *widget, HildonDateTimeError error_type);
+
+gboolean
+on_error (GtkWidget *widget, HildonDateTimeError error_type)
+{
+ g_debug ("Error: %d", error_type);
+ return FALSE;
+}
+
+GtkDialog *dialog = GTK_DIALOG (gtk_dialog_new ());
+HildonDateEditor *date_editor = HILDON_DATE_EDITOR (hildon_date_editor_new ());
+
+gtk_box_pack_start (GTK_BOX (dialog->vbox), gtk_label_new ("Choose a date"), FALSE, FALSE, 10);
+gtk_box_pack_start (GTK_BOX (dialog->vbox), GTK_WIDGET (date_editor), FALSE, FALSE, 10);
+gtk_dialog_add_button (dialog, "Close", GTK_RESPONSE_CANCEL);
+
+g_signal_connect (G_OBJECT (date_editor), "date_error", G_CALLBACK (on_error), NULL);
+
+gtk_widget_show_all (GTK_WIDGET (dialog));
+gtk_dialog_run (dialog);
+
+hildon_date_editor_get_date (date_editor, &y, &m, &d);
+]]>
+ </programlisting>
+ </example>
+
+ <para>The following example accomplishes equivalent functionality
+ using a HildonDateButton.</para>
+
+ <example>
+ <title>A Replacement for the Calendar Popup</title>
+ <programlisting>
+<![CDATA[
+GtkDialog *dialog = GTK_DIALOG (gtk_dialog_new ());
+guint y = 2009, m = 3, d = 25;
+HildonDateButton *date_button = HILDON_DATE_BUTTON (hildon_date_button_new (
+ HILDON_SIZE_THUMB_HEIGHT, HILDON_BUTTON_ARRANGEMENT_VERTICAL));
+hildon_date_button_set_date (date_button, y, m, d);
+gtk_box_pack_end (GTK_BOX (dialog->vbox), GTK_WIDGET (date_button), FALSE, FALSE, 0);
+gtk_widget_show_all (GTK_WIDGET (dialog));
+gtk_dialog_run (dialog);
+hildon_date_button_get_date (date_button, &y, &m, &d);
+]]>
+ </programlisting>
+ </example>
+</refsect1>
+
+<refsect1>
+ <title>Weekday Picker</title>
+
+ <para>A weekday picker (deprecated since Hildon 2.2) can be easily
+ replaced by a HildonPickerButton.</para>
+
+ <para>The following example presents the deprecated weekday picker
+ in a dialog.</para>
+
+ <example>
+ <title>A Typical Weekday Picker</title>
+ <programlisting>
+<![CDATA[
+GtkDialog *dialog = GTK_DIALOG (gtk_dialog_new ());
+GtkWidget *picker = hildon_weekday_picker_new ();
+gtk_box_pack_start (GTK_BOX (dialog->vbox), picker, TRUE, TRUE, 0);
+gtk_dialog_add_button (dialog, "Close", GTK_RESPONSE_CLOSE);
+gtk_widget_show_all (GTK_WIDGET (dialog));
+gtk_dialog_run (dialog);
+]]>
+ </programlisting>
+ </example>
+
+ <para>With a HildonPickerButton it is easy to add the weekdays to its
+ TouchSelector and thus having the same functionality.</para>
+
+ <example>
+ <title>A Replacement for the Weekday Picker</title>
+ <programlisting>
+<![CDATA[
+GtkDialog *dialog = GTK_DIALOG (gtk_dialog_new ());
+GtkWidget *picker = hildon_picker_button_new (HILDON_SIZE_THUMB_HEIGHT,
+ HILDON_BUTTON_ARRANGEMENT_VERTICAL);
+hildon_button_set_title (HILDON_BUTTON (picker), "Weekday:");
+HildonTouchSelector *selector = HILDON_TOUCH_SELECTOR (
+ hildon_touch_selector_new_text ());
+hildon_touch_selector_append_text (selector, "Sunday");
+hildon_touch_selector_append_text (selector, "Monday");
+hildon_touch_selector_append_text (selector, "Tuesday");
+hildon_touch_selector_append_text (selector, "Thursday");
+hildon_touch_selector_append_text (selector, "Friday");
+hildon_touch_selector_append_text (selector, "Saturday");
+hildon_touch_selector_set_column_selection_mode (selector,
+ HILDON_TOUCH_SELECTOR_SELECTION_MODE_MULTIPLE);
+
+hildon_picker_button_set_selector (HILDON_PICKER_BUTTON (picker), selector);
+hildon_picker_button_set_active (HILDON_PICKER_BUTTON (picker), 0);
+gtk_box_pack_start (GTK_BOX (dialog->vbox), picker, TRUE, TRUE, 0);
+gtk_widget_show_all (GTK_WIDGET (dialog));
+gtk_dialog_run (dialog);
+]]>
+ </programlisting>
+ </example>
+</refsect1>
+</refentry>
+
+<refentry id="hildon-migration-time-widgets" revision="13 Feb 2001">
+<refmeta>
+<refentrytitle>Time Widgets</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>Hildon Library</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+ <refname>Time Widgets</refname>
+ <refpurpose>How to migrate Time Widgets</refpurpose>
+</refnamediv>
+
+<refsect1 id="hildon-migrating-time-widgets">
+ <title>Migrating Time Widgets</title>
+
+ <para>A HildonTimeButton is the way to replace the time picker and
+ time editor widgets (deprecated
+ since Hildon version 2.2).</para>
+
+ <para>A time picker and time editor are shown in the examples bellow.</para>
+
+ <example>
+ <title>A Typical Time Picker</title>
+ <programlisting>
+<![CDATA[
+GtkDialog *dialog = GTK_DIALOG (hildon_time_picker_new (NULL));
+
+gtk_widget_show_all (GTK_WIDGET (dialog));
+gtk_dialog_run (dialog);
+]]>
+ </programlisting>
+ </example>
+
+ <example>
+ <title>A Typical Time Editor</title>
+ <programlisting>
+<![CDATA[
+GtkDialog *dialog = GTK_DIALOG (gtk_dialog_new ());
+HildonTimeEditor *time_editor = HILDON_TIME_EDITOR (hildon_time_editor_new ());
+
+gtk_box_pack_start (GTK_BOX (dialog->vbox), GTK_WIDGET (time_editor), FALSE, FALSE, 0);
+gtk_dialog_add_button (dialog, "Close", GTK_RESPONSE_CANCEL);
+
+gtk_widget_show_all (GTK_WIDGET (dialog));
+gtk_dialog_run (dialog);
+]]>
+ </programlisting>
+ </example>
+
+ <para>The same functionality can be achieved as the following example
+ shows.</para>
+
+ <example>
+ <title>A Replacement for the Time Picker</title>
+ <programlisting>
+<![CDATA[
+GtkDialog *dialog = GTK_DIALOG (gtk_dialog_new ());
+HildonTimeButton *time_button = HILDON_TIME_BUTTON (hildon_time_button_new (
+ HILDON_SIZE_THUMB_HEIGHT, HILDON_BUTTON_ARRANGEMENT_VERTICAL));
+gtk_box_pack_end (GTK_BOX (dialog->vbox), GTK_WIDGET (time_button), FALSE, FALSE, 0);
+gtk_widget_show_all (GTK_WIDGET (dialog));
+gtk_dialog_run (dialog);
+]]>
+ </programlisting>
+ </example>
+</refsect1>
+</refentry>
+
+<refentry id="hildon-migration-number-widgets" revision="13 Feb 2001">
+<refmeta>
+<refentrytitle>Number Widgets</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>Hildon Library</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+ <refname>Number Widgets</refname>
+ <refpurpose>How to migrate Number Widgets</refpurpose>
+</refnamediv>
+
+<refsect1 id="hildon-migrating-number-widgets">
+ <title>Migrating Number Widgets</title>
+
+ <para>To achieve the same functionlity of HildonNumberEditor you
+ can use a HildonPickerButton with a HildonTouchSelectorEntry assigned
+ to it. With these widgets you can also easily have the functionality
+ of a HildonRangeEditor (not covered in this example). Both the
+ HildonNumberEditor and the HildonRangeEditor are deprecated since
+ Hildon 2.2.</para>
+
+ <para>The following example shows a typical NumberEditor.</para>
+
+ <example>
+ <title>A Typical Number Editor</title>
+ <programlisting>
+<![CDATA[
+GtkDialog *dialog = GTK_DIALOG (gtk_dialog_new ());
+GtkWidget *editor = hildon_number_editor_new (0, 30);
+GtkWidget *label = gtk_label_new ("Number:");
+GtkWidget *hbox = gtk_hbox_new (FALSE, 12);
+
+gtk_box_pack_start (GTK_BOX (hbox), label, TRUE, TRUE, 0);
+gtk_box_pack_start (GTK_BOX (hbox), editor, FALSE, FALSE, 0);
+gtk_box_pack_start (GTK_BOX (dialog->vbox), hbox, TRUE, TRUE, 0);
+
+gtk_widget_show_all (GTK_WIDGET (dialog));
+gtk_dialog_run (dialog);
+]]>
+ </programlisting>
+ </example>
+
+ <para>The functionality of the example above is shown on the example
+ bellow using by validating the HildonPickerButton's value every time
+ it's changed. The choices given in the HildonTouchSelectorShould be
+ the most common choices.</para>
+
+ <example>
+ <title>A Replacement for the Number Editor</title>
+ <programlisting>
+<![CDATA[
+void
+changed_value_cb (HildonPickerButton *picker, gpointer data)
+{
+ gdouble number = 0;
+ const gchar *choice = hildon_button_get_value(HILDON_BUTTON (picker));
+ number = CLAMP(g_ascii_strtod (choice, NULL), 0, 30);
+ hildon_button_set_value(HILDON_BUTTON (picker), g_strdup_printf ("%d", (int) number));
+}
+
+GtkDialog *dialog = GTK_DIALOG (gtk_dialog_new ());
+GtkWidget *picker = hildon_picker_button_new (HILDON_SIZE_THUMB_HEIGHT,
+ HILDON_BUTTON_ARRANGEMENT_VERTICAL);
+hildon_button_set_title (HILDON_BUTTON (picker), "Number:");
+HildonTouchSelector *selector = HILDON_TOUCH_SELECTOR (
+ hildon_touch_selector_entry_new_text ());
+hildon_touch_selector_append_text (selector, "0");
+hildon_touch_selector_append_text (selector, "5");
+hildon_touch_selector_append_text (selector, "10");
+hildon_touch_selector_append_text (selector, "15");
+hildon_touch_selector_append_text (selector, "20");
+hildon_touch_selector_append_text (selector, "25");
+hildon_touch_selector_append_text (selector, "30");
+hildon_picker_button_set_selector (HILDON_PICKER_BUTTON (picker), selector);
+hildon_picker_button_set_active (HILDON_PICKER_BUTTON (picker), 0);
+g_signal_connect (G_OBJECT (picker), "value-changed",
+ G_CALLBACK (changed_value_cb), NULL);
+gtk_box_pack_start (GTK_BOX (dialog->vbox), picker, TRUE, TRUE, 0);
+gtk_widget_show_all (GTK_WIDGET (dialog));
+gtk_dialog_run (dialog);
+]]>
+ </programlisting>
+ </example>
+</refsect1>
+</refentry>
+
+<refentry id="hildon-migration-hildon-dialogs" revision="13 Feb 2001">
+<refmeta>
+<refentrytitle>Hildon Dialogs</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>Hildon Library</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+ <refname>Hildon Dialogs</refname>
+ <refpurpose>How to migrate Hildon Dialogs</refpurpose>
+</refnamediv>
+
+<refsect1 id="hildon-migrating-hildon-dialogs">
+ <title>Migrating Hildon Dialogs</title>
+
+ <para>The substitution of a HildonDialog should be easy. Since version
+ 2.2, dialogs in Hildon should be used as normal GtkDialog objects.</para>
+</refsect1>
+</refentry>
+
+<refentry id="hildon-migration-sort-dialogs" revision="13 Feb 2001">
+<refmeta>
+<refentrytitle>Sort Dialogs</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>Hildon Library</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+ <refname>Sort Dialogs</refname>
+ <refpurpose>How to migrate Sort Dialogs</refpurpose>
+</refnamediv>
+
+<refsect1 id="hildon-migrating-sort-dialogs">
+ <title>Migrating Sort Dialogs</title>
+
+ <para>HildonSortDialog is deprecated since Hildon 2.2. The correct way
+ to let the user sort contents is with menu filters.</para>
+
+ <para>The following example shows a typical NumberEditor.</para>
+
+ <example>
+ <title>A Typical Number Editor</title>
+ <programlisting>
+<![CDATA[
+GtkDialog *dialog = GTK_DIALOG (hildon_sort_dialog_new (NULL));
+
+hildon_sort_dialog_add_sort_key (HILDON_SORT_DIALOG (dialog), "First key");
+hildon_sort_dialog_add_sort_key_reversed (HILDON_SORT_DIALOG (dialog), "Second, key");
+]]>
+ </programlisting>
+ </example>
+
+ <para>The functionality of the example above is shown on the example
+ bellow using by validating the HildonPickerButton's value every time
+ it's changed. The choices given in the HildonTouchSelectorShould be
+ the most common choices.</para>
+
+ <example>
+ <title>A Replacement for the Number Editor</title>
+ <programlisting>
+<![CDATA[
+GtkRadioButton *filter;
+GtkWidget *window = hildon_stackable_window_new ();
+gtk_window_set_title (GTK_WINDOW (window), "Sort Example");
+
+HildonAppMenu *menu = HILDON_APP_MENU (hildon_app_menu_new ());
+
+filter = GTK_RADIO_BUTTON (hildon_gtk_radio_button_new (
+ HILDON_SIZE_THUMB_HEIGHT, NULL));
+gtk_button_set_label (GTK_BUTTON (filter), "1st Key");
+hildon_app_menu_add_filter (menu, GTK_BUTTON (filter));
+gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (filter), FALSE);
+gtk_toggle_button_set_active (GTK_TOGGLE_BUTTON (filter), TRUE);
+
+filter = GTK_RADIO_BUTTON (hildon_gtk_radio_button_new_from_widget (
+ HILDON_SIZE_FINGER_HEIGHT, filter));
+gtk_button_set_label (GTK_BUTTON (filter), "2nd Key");
+hildon_app_menu_add_filter (menu, GTK_BUTTON (filter));
+gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (filter), FALSE);
+
+filter = GTK_RADIO_BUTTON (hildon_gtk_radio_button_new (
+ HILDON_SIZE_THUMB_HEIGHT, NULL));
+gtk_button_set_label (GTK_BUTTON (filter), "A-Z");
+hildon_app_menu_add_filter (menu, GTK_BUTTON (filter));
+gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (filter), FALSE);
+
+filter = GTK_RADIO_BUTTON (hildon_gtk_radio_button_new_from_widget (
+ HILDON_SIZE_FINGER_HEIGHT, filter));
+gtk_button_set_label (GTK_BUTTON (filter), "Z-A");
+hildon_app_menu_add_filter (menu, GTK_BUTTON (filter));
+gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (filter), FALSE);
+
+hildon_stackable_window_set_main_menu (HILDON_STACKABLE_WINDOW (window), menu);
+]]>
+ </programlisting>
+ </example>
+</refsect1>
+</refentry>
--- /dev/null
+<refentry id="hildon-resources">
+<refmeta>
+<refentrytitle>Mailing lists and bug reports</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>Mailing lists and bug reports</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>Mailing lists and bug reports</refname>
+<refpurpose>
+Getting help with Hildon
+</refpurpose>
+</refnamediv>
+
+<refsect1>
+<title>Filing a bug report or feature request</title>
+
+<para>
+If you encounter a bug, misfeature, or missing feature in Hildon, please
+file a bug report on
+<ulink url="http://bugs.maemo.org">http://bugs.maemo.org</ulink>. File those
+against the "hildon-libs" component of the "Desktop Platform".
+</para>
+
+<para>
+Don't hesitate to file a bug report, even if you think we may know
+about it already, or aren't sure of the details. Just give us as much
+information as you have, and if it's already fixed or has already been
+discussed, we'll add a note to that effect in the report.
+</para>
+
+<para>
+The bug tracker should definitely be used for feature requests, it's
+not only for bugs. We track all Hildon development in Bugzilla, so it's
+the way to be sure the Hildon developers won't forget about an issue.
+</para>
+
+</refsect1>
+
+<refsect1>
+<title>Submitting Patches</title>
+
+<para>
+If you develop a bugfix or enhancement for Hildon, please file that in
+Bugzilla as well. Bugzilla allows you to attach files; please attach a
+patch generated by the <command>diff</command> utility, using the
+<option>-u</option> option to make the patch more readable. All patches
+must be offered under the terms of the GNU LGPL license, so be sure you
+are authorized to give us the patch under those terms.
+</para>
+
+<para>
+If you want to discuss your patch before or after developing it, mail
+<ulink url="mailto:maemo-developers@maemo.org">maemo-developers@maemo.org</ulink>.
+But be sure to file the Bugzilla report as well; if the patch is only on the
+list and not in Bugzilla, it's likely to slip through the cracks.
+</para>
+
+</refsect1>
+
+<refsect1>
+<title>Mailing lists</title>
+
+<para>
+There are several mailing lists dedicated to Maemo platform and related
+libraries as Hildon. You can find more information on mailing lists at
+<ulink url="http://maemo.org/community/mailing-lists">http://maemo.org/community/mailing-lists</ulink>.
+</para>
+
+
+</refsect1>
+
+
+</refentry>
--- /dev/null
+<refentry id="hildon-running">
+<refmeta>
+<refentrytitle>Running Hildon Applications</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>Hildon Library</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>Running Hildon Applications</refname>
+<refpurpose>
+How to run and debug your Hildon application
+</refpurpose>
+</refnamediv>
+
+<refsect1>
+<title>Running and debugging Hildon Applications</title>
+
+<para>
+Since Hildon is built on top of GTK+, all Hildon applications
+support the same standard commandline options and inspect
+the same environment variables that a GTK+ application does.
+To know more about this, read
+<link linkend="gtk-running">Running GTK+ Applications</link>
+</para>
+
+</refsect1>
+
+</refentry>
* also contains arrow buttons for changing the month/year. If an
* entered date is invalid, an information message will be shown.
*
+ * <note>
+ * <para>
+ * #HildonCalendarPopup has been deprecated since Hildon 2.2 and should not
+ * be used in newly written code.
+ * See <link linkend="hildon-migrating-date-widgets">Migrating Date Widgets</link>
+ * section to know how to migrate this deprecated widget.
+ * </para>
+ * </note>
+ *
* <example>
* <title>HildonCalendarPopup example</title>
* <programlisting>
* SECTION:hildon-calendar
* @short_description: A calendar widget
*
- * HildonCalendar is a slightly modified #GtkCalendar. It has an almost same API
- * but a slightly different look and behaviour. Use this widget instead of
+ * #HildonCalendar is a slightly modified #GtkCalendar. It has an almost same API
+ * but a slightly different look and behaviour. Use this widget instead of
* standard #GtkCalendar or use #HildonDateEditor for more higher-level date setting
* operations.
*
* <note>
* <para>
- * #HildonCalendar has been deprecated since Hildon 2.2 and should not
- * be used in newly written code. Use #HildonDateSelector instead.
+ * #HildonCalendar has been deprecated since Hildon 2.2
+ * See <link linkend="hildon-migrating-date-widgets">Migrating Date Widgets</link>
+ * section to know how to migrate this deprecated widget.
* </para>
* </note>
*/
* #HildonControlbar is a horizontally positioned range widget that is
* visually divided into blocks and supports setting a minimum and
* maximum value for the range.
- *
+ *
+ * <note>
+ * <para>
+ * #HildonControlbar has been deprecated since Hildon 2.2
+ * See <link linkend="hildon-migrating-control-bar">Migrating Control Bars</link>
+ * section to know how to migrate this deprecated widget.
+ * </para>
+ * </note>
+ *
* <example>
* <title>HildonControlbar example</title>
* <programlisting>
* year) and an icon (button): clicking on the icon opens up a
* HildonCalendarPopup.
*
+ *
* <note>
* <para>
* #HildonDateEditor has been deprecated since Hildon 2.2 and should
- * not be used in newly written code. Use #HildonDateSelector instead.
+ * not be used in newly written code. Use #HildonDateSelector instead. See
+ * <link linkend="hildon-migrating-date-widgets">Migrating Date Widgets</link>
+ * section to know how to migrate this deprecated widget.
* </para>
* </note>
*
*
* As of hildon 2.2, #HildonDialog has been deprecated in favor of #GtkDialog.
*
+ * <note>
+ * <para>
+ * #HildonDialog has been deprecated since Hildon 2.2 and should not
+ * be used in newly written code. See
+ * <link linkend="hildon-migrating-hildon-dialogs">Migrating Hildon Dialogs</link>
+ * section to know how to migrate this deprecated widget.
+ * </para>
+ * </note>
+ *
* <example>
* <title>Simple <structname>HildonDialog</structname> usage</title>
* <programlisting>
* The #HildonHVolumebar widget displays a horizontal volume bar that allows
* increasing or decreasing volume within a pre-defined range, and includes
* a mute icon which users can click to mute the sound.
- *
+ *
+ * <note>
+ * <para>
+ * #HildonHVolumeBar has been deprecated since Hildon 2.2
+ * See <link linkend="hildon-migrating-volume-bar">Migrating Volume Bars</link>
+ * section to know how to migrate this deprecated widget.
+ * </para>
+ * </note>
+ *
* <example>
* <programlisting>
* GtkWidget *volbar = hildon_hvolumebar_new ();
* There are two buttons to scroll the value in number field.
* Manual input is also possible.
*
+ * <note>
+ * <para>
+ * #HildonNumberEditor has been deprecated since Hildon 2.2
+ * See <link linkend="hildon-migrating-number-widgets">Migrating Number Widgets</link>
+ * section to know how to migrate this deprecated widget.
+ * </para>
+ * </note>
+ *
* <example>
* <title>HildonNumberEditor example</title>
* <programlisting>
"Pixel width used to draw the scroll indicators.",
0, G_MAXUINT, 8,
G_PARAM_READWRITE));
-
+ /**
+ * HildonPannableArea::horizontal-movement:
+ * @hildonpannable: the object which received the signal
+ * @direction: the direction of the movement #HILDON_MOVEMENT_UP or #HILDON_MOVEMENT_DOWN
+ * @initial_x: the x value of the touched point in the area when the motion started
+ * @initial_y: the y value of the touched point in the area when the motion started
+ *
+ * The horizontal-movement signal is emitted when the pannable area
+ * starts a horizontal movement.
+ */
pannable_area_signals[HORIZONTAL_MOVEMENT] =
g_signal_new ("horizontal_movement",
G_TYPE_FROM_CLASS (object_class),
G_TYPE_DOUBLE,
G_TYPE_DOUBLE);
+ /**
+ * HildonPannableArea::vertical-movement:
+ * @hildonpannable: the object which received the signal
+ * @direction: the direction of the movement #HILDON_MOVEMENT_LEFT or #HILDON_MOVEMENT_RIGHT
+ * @initial_x: the x value when the motion started
+ * @initial_y: the y value when the motion started
+ *
+ * The vertical-movement signal is emitted when the pannable area
+ * starts a vertical movement.
+ */
pannable_area_signals[VERTICAL_MOVEMENT] =
g_signal_new ("vertical_movement",
G_TYPE_FROM_CLASS (object_class),
* HidlonRangeEditor allows entering a pair of integers, e.g. the lower
* and higher bounds of a range. A minimum and maximum can also be set
* for the bounds.
- *
+ *
+ * <note>
+ * <para>
+ * #HildonRangeEditor has been deprecated since Hildon 2.2 and should not
+ * be used in newly written code. See
+ * <link linkend="hildon-migrating-number-widgets">Migrating Number Widgets</link>
+ * section to know how to migrate this deprecated widget.
+ * </para>
+ * </note>
+ *
* <example>
* <programlisting>
* range_editor = hildon_range_editor_new ();
* and a field by which items are sorted in a list. The combo boxes
* display the current value when the dialog is opened.
*
+ * <note>
+ * <para>
+ * #HildonSortDialog has been deprecated since Hildon 2.2
+ * See <link linkend="hildon-migrating-sort-dialogs">Migrating Sort Dialogs</link>
+ * section to know how to migrate this deprecated widget.
+ * </para>
+ * </note>
+ *
* <example>
* <title>An example for using HildonSortDialog</title>
* <programlisting>
* <note>
* <para>
* #HildonTimeEditor has been deprecated since Hildon 2.2 and should not
- * be used in newly written code. Use #HildonTimeSelector instead.
+ * be used in newly written code. See
+ * <link linkend="hildon-migrating-time-widgets">Migrating Time Widgets</link>
+ * section to know how to migrate this deprecated widget.
* </para>
* </note>
*
* using up/down arrows on hours and minutes. There are two arrows for minutes,
* so that minutes can be added also in 10 min increments.This widget is mainly
* used as a part of #HildonTimeEditor implementation.
- *
+ *
+ * <note>
+ * <para>
+ * #HildonTimePicker has been deprecated since Hildon 2.2 and should not
+ * be used in newly written code. See
+ * <link linkend="hildon-migrating-time-widgets">Migrating Time Widgets</link>
+ * section to know how to migrate this deprecated widget.
+ * </para>
+ * </note>
+ *
* <example>
* <title>HildonTimePicker example</title>
* <programlisting>
* that #HildonVolumebar can meet its specifications.
*
* Currently #HildonVolumebarRange models range of [0..100].
- *
+ *
+ * <note>
+ * <para>
+ * #HildonVolumebarRange has been deprecated since Hildon 2.2 and should not
+ * be used in newly written code. See
+ * <link linkend="hildon-migrating-volume-bar">Migrating Volume Bars</link>
+ * section to know how to migrate this deprecated widget.
+ * </para>
+ * </note>
*/
#include <gdk/gdkkeysyms.h>
* #HildonVolumebar is a base class for widgets that display a volume bar that
* allows increasing or decreasing volume within a predefined range, and muting
* the volume when users click the mute icon.
+ *
+ * <note>
+ * <para>
+ * #HildonVolumebar has been deprecated since Hildon 2.2 and should not
+ * be used in newly written code. See
+ * <link linkend="hildon-migrating-volume-bar">Migrating Volume Bars</link>
+ * section to know how to migrate this deprecated widget.
+ * </para>
+ * </note>
*/
#undef HILDON_DISABLE_DEPRECATED
* #HildonVVolumebar is a subclass of #HildonVolumebar. It displays a
* vertical volume bar that allows increasing or decreasing volume
* within a predefined range, and muting when users click the mute icon.
- *
+ *
+ * <note>
+ * <para>
+ * #HildonVVolumebar has been deprecated since Hildon 2.2 and should not
+ * be used in newly written code. See
+ * <link linkend="hildon-migrating-volume-bar">Migrating Volume Bars</link>
+ * section to know how to migrate this deprecated widget.
+ * </para>
+ * </note>
+ *
* Here is an example that creates a vertical volume bar and connects
* both its signals.
+ *
* <example>
* <title>HildonVVolumebar example</title>
* <programlisting>
* a certain event should take place, for example, which days a Calendar event
* should be repeated on. It is used in Calendar in the Repeat dialog, in Tasks
* in the Repeat dialog and in the Email set-up wizard.
- *
+ *
+ * <note>
+ * <para>
+ * #HildonWeekdayPicker has been deprecated since Hildon 2.2 and should not
+ * be used in newly written code. See
+ * <link linkend="hildon-migrating-date-widgets">Migrating Date Widgets</link>
+ * section to know how to migrate this deprecated widget.
+ * </para>
+ * </note>
+ *
* <example>
* <title>HildonWeekdayPicker example</title>
* <programlisting>
projects / hildon / commitdiff