# Extra options to supply to gtkdoc-scan.
# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED"
-SCAN_OPTIONS=\
- --source-dir=$(top_srcdir)/src \
+SCAN_OPTIONS= \
+ --source-dir=$(top_srcdir)/src/widgets \
--source-dir=$(top_srcdir)/src/gtk \
- --source-dir=$(top_srcdir)/src/widgets
+ --source-dir=$(top_srcdir)/src
# Extra options to supply to gtkdoc-mkdb.
# e.g. MKDB_OPTIONS=--sgml-mode --output-format=xml
# Used for dependencies. The docs will be rebuilt if any of these change.
# e.g. HFILE_GLOB=$(top_srcdir)/*.h
# e.g. CFILE_GLOB=$(top_srcdir)/*.c
-HFILE_GLOB=$(top_srcdir)/src/*.h
-CFILE_GLOB=$(top_srcdir)/src/*.c
+HFILE_GLOB=$(top_srcdir)/src/*.h $(top_srcdir)/src/widgets/*.h $(top_srcdir)/src/gtk/*.h
+CFILE_GLOB=$(top_srcdir)/src/*.c $(top_srcdir)/src/widgets/*.c $(top_srcdir)/src/gtk/*.c
# Header files to ignore when scanning.
# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
# 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=xml/tree_index.sgml
+content_files= \
+ xml/tree_index.sgml \
+ modest-preface.sgml \
+ modest-architecture.sgml \
+ modest-design.sgml \
+ modest-coding-guidelines.sgml
# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
# These files must be listed here *and* in content_files
-I$(top_srcdir)/src/widgets
-GTKDOC_LIBS=\
+GTKDOC_LIBS= \
$(MODEST_LIBTINYMAIL_GNOME_DESKTOP_LIBS) \
$(MODEST_LIBTINYMAIL_MAEMO_LIBS) \
$(MODEST_GSTUFF_LIBS) \
$(top_builddir)/src/gtk/libmodest-ui.la \
$(top_builddir)/src/widgets/libmodest-widgets.la\
- ${top_builddir}/src/modest-conf.o \
${top_builddir}/src/modest-account-mgr.o \
- ${top_builddir}/src/modest-tny-platform-factory.o \
+ ${top_builddir}/src/modest-conf.o \
+ ${top_builddir}/src/modest-formatter.o \
+ ${top_builddir}/src/modest-icon-factory.o \
+ ${top_builddir}/src/modest-mail-operation.o \
+ ${top_builddir}/src/modest-mail-operation-queue.o \
+ ${top_builddir}/src/modest-marshal.o \
+ ${top_builddir}/src/modest-pair.o \
+ ${top_builddir}/src/modest-presets.o \
${top_builddir}/src/modest-protocol-mgr.o \
${top_builddir}/src/modest-proto.o \
- ${top_builddir}/src/modest-pair.o \
- ${top_builddir}/src/modest-marshal.o \
+ ${top_builddir}/src/modest-text-utils.o \
${top_builddir}/src/modest-tny-account-store.o \
- ${top_builddir}/src/modest-mail-operation.o \
- ${top_builddir}/src/modest-mail-operation-queue.o \
- ${top_builddir}/src/modest-tny-msg-actions.o \
${top_builddir}/src/modest-tny-attachment.o \
+ ${top_builddir}/src/modest-tny-msg-actions.o \
+ ${top_builddir}/src/modest-tny-platform-factory.o \
${top_builddir}/src/modest-tny-stream-gtkhtml.o \
${top_builddir}/src/modest-widget-factory.o \
- ${top_builddir}/src/modest-widget-memory.o \
- ${top_builddir}/src/modest-icon-factory.o \
- ${top_builddir}/src/modest-formatter.o \
- ${top_builddir}/src/modest-text-utils.o
+ ${top_builddir}/src/modest-widget-memory.o
# This includes the standard gtk-doc make rules, copied by gtkdocize.
include $(top_srcdir)/gtk-doc.make
--- /dev/null
+ <part>
+ <title>Architecture</title>
+ <partintro>
+ <para><application>modest</application> tries to be quite flexible in its
+ design. However, it's always important not to make things too
+ generic. Both for reasons of time limitations and keeping the software
+ understandable and 'modest', it's important to limit the scope.
+ </para>
+
+ <para>
+ For <application>modest</application>, the following:
+ <itemizedlist>
+ <listitem><application>modest</application> is a e-mail program
+ using the <package>tinymail</package> and <package>camel</package>
+ libraries;</listitem>
+ <listitem><application>modest</application> targets gtk and
+ gconf-based user-interfaces, including the Hildon
+ environment;</listitem>
+ <listitem><application>modest</application> main use-case is in
+ small, mobile device such as the <productname>Nokia 770 Internet
+ Tablet</productname>;</listitem>
+ <listitem>However, effort is made also to
+ make <application>modest</application> usable as a general-purpose
+ e-mail client on normal desktop computer.</listitem>
+ </itemizedlist>
+ </para>
+ </partintro>
+ </part>
--- /dev/null
+ <part>
+ <title>Coding guidelines</title>
+ <partintro>
+ When hacking on modest, please honour these time-tested coding guidelines.
+ First, please follow the <emphasis>Linux CodingStyle guidelines</emphasis>
+ (<filename>/usr/src/linux/Documentation/CodingStyle</filename>).
+ </partintro>
+
+ <para>
+ Here are only some additional notes.
+ </para>
+
+ <para>
+ Your editor may help you with this, for example for <application>emacs</application>:
+ <programlisting>
+ (c-set-style "K&R")
+ (setq tab-width 8)
+ (setq indent-tabs-mode t)
+ (setq c-basic-offset 8)
+ </programlisting>
+
+ Or the equivalent in your favourite editor.
+ </para>
+
+ <para>
+ Lines must not exceed 100 characters.
+ </para>
+
+ <para>
+ Functions should do one thing, and do it well. In general, functions
+ should not be much longer than 20-30 lines (except for, say, handling
+ many different cases in a 'switch'-statement). Files should not get to
+ big either; if there are more than, say, 800 lines, it's a sign that
+ some refactoring should take place.
+ </para>
+
+ <para>
+ Code should compile cleanly
+ with <command>gcc</command>'s <symbol>-Wall</symbol> compile option. Of
+ course this might not always be possible due to problems in dependent
+ libraries and/or compiler version. Therefore, do not
+ include <symbol>-Werror</symbol> in the standard compile options; but
+ do use it when building / testing things yourself.
+ </para>
+
+ <para>
+ Code should also run cleanly. GTK+/GLib warnings and errors must be
+ taken very seriously. If you run <application>modest</application> with
+ the <symbol>-d</symbol>-flag, it will <symbol>abort</symbol> whenever
+ there is such a warning. This can be useful when running inside the
+ debugger.
+ </para>
+
+ <para>Global functions (the ones in <filename>.h</filename>-files) must
+ be commented using <systemitem>gtk-doc</systemitem>. This way, we
+ generate nice documentation. After installing
+ (under <filename>/usr/local</filename>), we can browse the results
+ with <application>DevHelp</application>. Just
+ add <systemitem>/usr/local/share/gtk-doc/html</systemitem> to the
+ <systemitem>DEVHELP_SEARCH_PATH</systemitem>-environment variable.
+ </para>
+ <para>
+ Furthermore, please follow 'conventional wisdom' for programming with
+ GLib/GTK+/GObject. Some things to remember:
+ <itemizedlist>
+ <listitem> <function>g_new</function>, <function>g_malloc</function> and
+ friends <emphasis>never</emphasis> return <function>NULL</function>. They terminate
+ the application if it happens (normally). No need to check
+ for <function>NULL</function> returns;</listitem>
+ <listitem> <function>g_return_if_fail</function> and friends may be
+ 'turned off', ie. they are to be used for error checking,
+ but <emphasis>not</emphasis> for your programming logic
+ </listitem>
+ </itemizedlist>
+ </para>
+ </part>
\ No newline at end of file
--- /dev/null
+ <part>
+ <title>Design</title>
+ <partintro>
+ <para>In this part, we'll discuss the design of various parts of
+ <application>modest</application>. We'll not go into the details of
+ various APIs in this chapter. Please consult the documentation generated
+ from the source code (<systemitem>gtk-doc</systemitem>) for that.
+ </para>
+ </partintro>
+
+ <chapter>
+ <title>Configuration</title>
+ <para>Configuration is the part of <application>modest</application>
+ that deals with storing all settings. While the design allows for
+ alternative implementations, currently
+ only <systemitem>GConf</systemitem> is supported as a backend.
+ </para>
+
+ <para>
+ All dealing with configuration is done with
+ the <classname>ModestConf</classname>-class. It is declared
+ in <filename> modest-conf.h</filename>, and
+ the <systemitem>GConf</systemitem>-based implementation in
+ <filename>modest-conf.c</filename>. As said, there could be
+ different implementations --
+ nothing <systemitem>GConf</systemitem>-specific is visible in the
+ <classname>ModestConf</classname>-<abbrev>API</abbrev>.
+ </para>
+ </chapter>
+
+ <chapter>
+ <title>Account Management</title>
+ <para>
+ Account Management is the part of <application>modest</application>
+ that deals with the setting related to sending and receiving of
+ e-mail. We will follow the libcamel-convention of using the
+ term <emphasis>store</emphasis> for an e-mail storage/retrieval
+ server, and a <emphasis>transport</emphasis> for a server that
+ transports mail to its destination.
+ </para>
+
+ <para>
+ In practice, the following types are available:
+ <itemizedlist>
+ <listitem><emphasis>stores</emphasis>: <abbrev>POP</abbrev>
+ and <abbrev>IMAP</abbrev>; </listitem>
+ <listitem> <emphasis>transports</emphasis>: <systemitem>sendmail</systemitem>
+ and <abbrev>SMTP</abbrev>.</listitem>
+ </itemizedlist>
+ </para>
+
+ <sect1>
+ <title>Definitions</title>
+ <itemizedlist>
+ <listitem>An <emphasis>account</emphasis> is a named entity
+ consisting of a <emphasis>store</emphasis> and
+ a <emphasis>transport</emphasis>. Note: For our mobile use-cases,
+ the <emphasis>transport</emphasis> cannot be a static entity, but
+ may depend on the network connection. That is however not part of
+ Account Management, so not discussed here</listitem>
+ <listitem>A <emphasis>server account</emphasis> is account
+ describing the connection with a specific server. Server accounts
+ come in two type:
+ <itemizedlist>
+ <listitem>A <emphasis>transport</emphasis> describes the connection information
+ (servername, username, password etc.) for a transport
+ server;</listitem>
+ <listitem>A <emphasis>store</emphasis> describes the connection information for
+ a store server;</listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1>
+ <title>Code</title>
+ <para>The functions to deal with account and server accounts are
+ located in <classname>ModestAccountMgr</classname>, ie. in
+ <filename>modest-account-mgr.[ch]</filename>. There function to add
+ specific values for both, to list the available ones, etc. Please
+ refer to the source code documentation for details.
+ </para>
+ </sect1>
+
+ <sect1>
+ <title>Location in configuration database</title>
+ <para>
+ <emphasis>Accounts</emphasis> can be found
+ in <systemitem>/apps/modest/accounts</systemitem>,
+ while <emphasis>server accounts</emphasis> can be found
+ in <systemitem>/app/modest/server_accounts</systemitem>.
+ </para>
+
+ <para>
+ The following image show an
+ account <systemitem>accountstest</systemitem> with server accounts
+ <systemitem>mystore</systemitem>
+ and <systemitem>mytransport</systemitem>.
+ <imagedata fileref="modest-account-mgr.png"/>
+ </para>
+
+ <para>
+ For each of the stores, there are number of parameters specified:
+ <itemizedlist>
+ <listitem><emphasis>hostname</emphasis> - the place where the server resides;</listitem>
+ <listitem><emphasis>username</emphasis> - the username;</listitem>
+ <listitem><emphasis>password</emphasis> - the password;</listitem>
+ <listitem><emphasis>proto</emphasis> - the protocal for communication with this server - for
+ now these are the following valid values (literal strings):
+ <itemizedlist>
+ <listitem><emphasis>sendmail</emphasis>;</listitem>
+ <listitem><emphasis>smtp</emphasis>;</listitem>
+ <listitem><emphasis>pop</emphasis></listitem>
+ <listitem><emphasis>imap</emphasis>.</listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>In <filename>modest-proto.[ch]</filename> there are various
+ functions to check whether something is a valid protocol, and
+ whether it is a transport of a store.
+ </para>
+
+ <para>Note that server accounts and accounts are relatively independent. While
+ accounts refer to two server accounts, these server accounts can be
+ used by other accounts as well.
+ </para>
+
+ <para>The reason two keep accounts and server accounts separately, is a bit of
+ flexibility. In mobile use-cases, quite often it's desirable to use a
+ network-specific smtp-server. The chosen structure makes it easy to iterate
+ over all smtp-servers and find the right one.
+ </para>
+ </sect1>
+
+ <sect1>
+ <title>Account Management and Tinymail</title>
+ <para>
+ Tinymail needs the information about all configured accounts - and the
+ mechanism that it uses for that
+ is <interface>TnyAccountStoreIface</interface>. We don't want to use
+ the tinymail-provided <classname>TnyAccountStore</classname>, but
+ provide our own implementation
+ instead: <classname>ModestTnyAccountStore</classname>. This class
+ implements the <interface>TnyAccountStoreIface</interface>-interace in
+ terms of the aforementioned <classname>ModestAccountMgr</classname>.
+ </para>
+
+ <para>
+ One unexpected function
+ that <classname>ModestTnyAccountStore</classname> needs to implement
+ is <symbol>tny account_store get_session</symbol> (to get the
+ Camel-session). This function must be provided as a public function,
+ with that exact name.
+ </para>
+ </sect1>
+ </chapter>
+
+ <chapter>
+ <title>Finding the right transport</title>
+ <para>
+ One of the interesting topics in designing a mobile e-mail client is
+ to deal with transports (in
+ particular, <acronym>SMTP</acronym>). The reason for that is that
+ the majority of <acronym>SMTP</acronym>-servers only allow e-mail
+ from the same network. That means that for example <systemitem>
+ smtp.some-isp.com</systemitem> will only accept mail from
+ (<command>MAIL FROM:</command>) <systemitem>
+ user@some-isp.com</systemitem>, and refuse mail
+ from <systemitem>user@some-other-isp.com</systemitem>, unless the
+ recipient (<command>RCPT TO:</command>) is on the same network.
+ </para>
+ </chapter>
+ </part>
\ No newline at end of file
<!ENTITY index-Object-Tree SYSTEM "xml/tree_index.sgml">
+<!ENTITY preface SYSTEM "modest-preface.sgml">
+<!ENTITY architecture SYSTEM "modest-architecture.sgml">
+<!ENTITY design SYSTEM "modest-design.sgml">
+<!ENTITY coding-guidelines SYSTEM "modest-coding-guidelines.sgml">
+
]>
<book id="index">
</copyright>
</bookinfo>
- <preface>
- <title>Introduction</title>
- <para><application>modest</application> is a mail user agent
- (<abbrev>MUA</abbrev>) targetting small devices, in particular Nokia's
- <productname>Nokia 770 Internet Tablet</productname>. This document
- describes the design and implementation of this software.
- </para>
-
- <para><application>modest</application> lives at the top of a extensive
- stack of software. It is built on top
- of <application>tinymail</application>, and uses its libcamel
- backend. It strives to the be a simple yet powerful program, geared
- towards small devices, for example (but not limited
- to) <productname>Nokia's 770 internet tablet</productname>. An important
- goal is to minimize memory usage while still being able to handle
- significant amounts of email quickly; much of that is achieved simply by
- using <application>tinymail</application>, which uses a number of clever
- tricks for that, such as the proxy design pattern for listing email
- headers, and not needing memory for headers which are not currently
- visible.
- </para>
-
- <para>
- <application>modest</application>, in turn, also tries to be efficient,
- fast and scalable. That means that the <abbrev>MUA</abbrev> should
- support multiple user-interfaces, perhaps making it even possible to
- switch between them during runtime.
- </para>
-
- <para>To summarize the goals for <application>modest</application>:
- <itemizedlist>
- <listitem>target devices with limited amounts of memory ('limited' in 2006
- terms means less than 64Mb, and of which only part can be used for
- e-mail);</listitem>
- <listitem>target Linux/Unix-like environments with GLib/GTK+-based
- support;</listitem>
- <listitem>support multiple user-interface (UIs) with as much code
- sharing as possible between the different UIs.</listitem>
- </itemizedlist></para>
-
- <para>Like <application>tinymail</application>
- and <application>libcamel</application>, <application>modest</application>
- is programmed in C, using the <package>GObject</package>-system for
- object-oriented (OO) features. For now, it specifically targets \gtk based
- UIs (and derivatives like 'Hildon').</para>
-
- </preface>
+ &preface;
- <part>
- <title>Architecture</title>
- <partintro>
- <para><application>modest</application> tries to be quite flexible in its
- design. However, it's always important not to make things too
- generic. Both for reasons of time limitations and keeping the software
- understandable and 'modest', it's important to limit the scope.
- </para>
-
- <para>
- For <application>modest</application>, the following:
- <itemizedlist>
- <listitem><application>modest</application> is a e-mail program
- using the <package>tinymail</package> and <package>camel</package>
- libraries;</listitem>
- <listitem><application>modest</application> targets gtk and
- gconf-based user-interfaces, including the Hildon
- environment;</listitem>
- <listitem><application>modest</application> main use-case is in
- small, mobile device such as the <productname>Nokia 770 Internet
- Tablet</productname>;</listitem>
- <listitem>However, effort is made also to
- make <application>modest</application> usable as a general-purpose
- e-mail client on normal desktop computer.</listitem>
- </itemizedlist>
- </para>
- </partintro>
- </part>
+ &architecture;
- <part>
- <title>Design</title>
- <partintro>
- <para>In this part, we'll discuss the design of various parts of
- <application>modest</application>. We'll not go into the details of
- various APIs in this chapter. Please consult the documentation generated
- from the source code (<systemitem>gtk-doc</systemitem>) for that.
- </para>
- </partintro>
-
- <chapter>
- <title>Configuration</title>
- <para>Configuration is the part of <application>modest</application>
- that deals with storing all settings. While the design allows for
- alternative implementations, currently
- only <systemitem>GConf</systemitem> is supported as a backend.
- </para>
-
- <para>
- All dealing with configuration is done with
- the <classname>ModestConf</classname>-class. It is declared
- in <filename> modest-conf.h</filename>, and
- the <systemitem>GConf</systemitem>-based implementation in
- <filename>modest-conf.c</filename>. As said, there could be
- different implementations --
- nothing <systemitem>GConf</systemitem>-specific is visible in the
- <classname>ModestConf</classname>-<abbrev>API</abbrev>.
- </para>
- </chapter>
-
- <chapter>
- <title>Account Management</title>
- <para>
- Account Management is the part of <application>modest</application>
- that deals with the setting related to sending and receiving of
- e-mail. We will follow the libcamel-convention of using the
- term <emphasis>store</emphasis> for an e-mail storage/retrieval
- server, and a <emphasis>transport</emphasis> for a server that
- transports mail to its destination.
- </para>
-
- <para>
- In practice, the following types are available:
- <itemizedlist>
- <listitem><emphasis>stores</emphasis>: <abbrev>POP</abbrev>
- and <abbrev>IMAP</abbrev>; </listitem>
- <listitem> <emphasis>transports</emphasis>: <systemitem>sendmail</systemitem>
- and <abbrev>SMTP</abbrev>.</listitem>
- </itemizedlist>
- </para>
-
- <sect1>
- <title>Definitions</title>
- <itemizedlist>
- <listitem>An <emphasis>account</emphasis> is a named entity
- consisting of a <emphasis>store</emphasis> and
- a <emphasis>transport</emphasis>. Note: For our mobile use-cases,
- the <emphasis>transport</emphasis> cannot be a static entity, but
- may depend on the network connection. That is however not part of
- Account Management, so not discussed here</listitem>
- <listitem>A <emphasis>server account</emphasis> is account
- describing the connection with a specific server. Server accounts
- come in two type:
- <itemizedlist>
- <listitem>A <emphasis>transport</emphasis> describes the connection information
- (servername, username, password etc.) for a transport
- server;</listitem>
- <listitem>A <emphasis>store</emphasis> describes the connection information for
- a store server;</listitem>
- </itemizedlist>
- </listitem>
- </itemizedlist>
- </sect1>
-
- <sect1>
- <title>Code</title>
- <para>The functions to deal with account and server accounts are
- located in <classname>ModestAccountMgr</classname>, ie. in
- <filename>modest-account-mgr.[ch]</filename>. There function to add
- specific values for both, to list the available ones, etc. Please
- refer to the source code documentation for details.
- </para>
- </sect1>
-
- <sect1>
- <title>Location in configuration database</title>
- <para>
- <emphasis>Accounts</emphasis> can be found
- in <systemitem>/apps/modest/accounts</systemitem>,
- while <emphasis>server accounts</emphasis> can be found
- in <systemitem>/app/modest/server_accounts</systemitem>.
- </para>
-
- <para>
- The following image show an
- account <systemitem>accountstest</systemitem> with server accounts
- <systemitem>mystore</systemitem>
- and <systemitem>mytransport</systemitem>.
- <imagedata fileref="modest-account-mgr.png"/>
- </para>
-
- <para>
- For each of the stores, there are number of parameters specified:
- <itemizedlist>
- <listitem><emphasis>hostname</emphasis> - the place where the server resides;</listitem>
- <listitem><emphasis>username</emphasis> - the username;</listitem>
- <listitem><emphasis>password</emphasis> - the password;</listitem>
- <listitem><emphasis>proto</emphasis> - the protocal for communication with this server - for
- now these are the following valid values (literal strings):
- <itemizedlist>
- <listitem><emphasis>sendmail</emphasis>;</listitem>
- <listitem><emphasis>smtp</emphasis>;</listitem>
- <listitem><emphasis>pop</emphasis></listitem>
- <listitem><emphasis>imap</emphasis>.</listitem>
- </itemizedlist>
- </listitem>
- </itemizedlist>
- </para>
-
- <para>In <filename>modest-proto.[ch]</filename> there are various
- functions to check whether something is a valid protocol, and
- whether it is a transport of a store.
- </para>
-
- <para>Note that server accounts and accounts are relatively independent. While
- accounts refer to two server accounts, these server accounts can be
- used by other accounts as well.
- </para>
-
- <para>The reason two keep accounts and server accounts separately, is a bit of
- flexibility. In mobile use-cases, quite often it's desirable to use a
- network-specific smtp-server. The chosen structure makes it easy to iterate
- over all smtp-servers and find the right one.
- </para>
- </sect1>
-
- <sect1>
- <title>Account Management and Tinymail</title>
- <para>
- Tinymail needs the information about all configured accounts - and the
- mechanism that it uses for that
- is <interface>TnyAccountStoreIface</interface>. We don't want to use
- the tinymail-provided <classname>TnyAccountStore</classname>, but
- provide our own implementation
- instead: <classname>ModestTnyAccountStore</classname>. This class
- implements the <interface>TnyAccountStoreIface</interface>-interace in
- terms of the aforementioned <classname>ModestAccountMgr</classname>.
- </para>
-
- <para>
- One unexpected function
- that <classname>ModestTnyAccountStore</classname> needs to implement
- is <symbol>tny account_store get_session</symbol> (to get the
- Camel-session). This function must be provided as a public function,
- with that exact name.
- </para>
- </sect1>
- </chapter>
-
- <chapter>
- <title>Finding the right transport</title>
- <para>
- One of the interesting topics in designing a mobile e-mail client is
- to deal with transports (in
- particular, <acronym>SMTP</acronym>). The reason for that is that
- the majority of <acronym>SMTP</acronym>-servers only allow e-mail
- from the same network. That means that for example <systemitem>
- smtp.some-isp.com</systemitem> will only accept mail from
- (<command>MAIL FROM:</command>) <systemitem>
- user@some-isp.com</systemitem>, and refuse mail
- from <systemitem>user@some-other-isp.com</systemitem>, unless the
- recipient (<command>RCPT TO:</command>) is on the same network.
- </para>
- </chapter>
- </part>
+ &design;
- <chapter>
- <title>Coding guidelines</title>
- <para>
- When hacking on modest, please honour these time-tested coding guidelines.
- First, please follow the <emphasis>Linux CodingStyle guidelines</emphasis>
- (<filename>/usr/src/linux/Documentation/CodingStyle</filename>).
- </para>
-
- <para>
- Here are only some additional notes.
- </para>
-
- <para>
- Your editor may help you with this, for example for <application>emacs</application>:
- <programlisting>
- (c-set-style "K&R")
- (setq tab-width 8)
- (setq indent-tabs-mode t)
- (setq c-basic-offset 8)
- </programlisting>
-
- Or the equivalent in your favourite editor.
- </para>
-
- <para>
- Lines must not exceed 100 characters.
- </para>
-
- <para>
- Functions should do one thing, and do it well. In general, functions
- should not be much longer than 20-30 lines (except for, say, handling
- many different cases in a 'switch'-statement). Files should not get to
- big either; if there are more than, say, 800 lines, it's a sign that
- some refactoring should take place.
- </para>
-
- <para>
- Code should compile cleanly
- with <command>gcc</command>'s <symbol>-Wall</symbol> compile option. Of
- course this might not always be possible due to problems in dependent
- libraries and/or compiler version. Therefore, do not
- include <symbol>-Werror</symbol> in the standard compile options; but
- do use it when building / testing things yourself.
- </para>
-
- <para>
- Code should also run cleanly. GTK+/GLib warnings and errors must be
- taken very seriously. If you run <application>modest</application> with
- the <symbol>-d</symbol>-flag, it will <symbol>abort</symbol> whenever
- there is such a warning. This can be useful when running inside the
- debugger.
- </para>
-
- <para>Global functions (the ones in <filename>.h</filename>-files) must
- be commented using <systemitem>gtk-doc</systemitem>. This way, we
- generate nice documentation. After installing
- (under <filename>/usr/local</filename>), we can browse the results
- with <application>DevHelp</application>. Just
- add <systemitem>/usr/local/share/gtk-doc/html</systemitem> to the
- <systemitem>DEVHELP_SEARCH_PATH</systemitem>-environment variable.
- </para>
- <para>
- Furthermore, please follow 'conventional wisdom' for programming with
- GLib/GTK+/GObject. Some things to remember:
- <itemizedlist>
- <listitem> <function>g_new</function>, <function>g_malloc</function> and
- friends <emphasis>never</emphasis> return <function>NULL</function>. They terminate
- the application if it happens (normally). No need to check
- for <function>NULL</function> returns;</listitem>
- <listitem> <function>g_return_if_fail</function> and friends may be
- 'turned off', ie. they are to be used for error checking,
- but <emphasis>not</emphasis> for your programming logic
- </listitem>
- </itemizedlist>
- </para>
- </chapter>
+ &coding-guidelines;
<reference>
<title>Object Index</title>
--- /dev/null
+ <preface>
+ <title>Introduction</title>
+ <para><application>modest</application> is a mail user agent
+ (<abbrev>MUA</abbrev>) targetting small devices, in particular Nokia's
+ <productname>Nokia 770 Internet Tablet</productname>. This document
+ describes the design and implementation of this software.
+ </para>
+
+ <para><application>modest</application> lives at the top of a extensive
+ stack of software. It is built on top
+ of <application>tinymail</application>, and uses its libcamel
+ backend. It strives to the be a simple yet powerful program, geared
+ towards small devices, for example (but not limited
+ to) <productname>Nokia's 770 internet tablet</productname>. An important
+ goal is to minimize memory usage while still being able to handle
+ significant amounts of email quickly; much of that is achieved simply by
+ using <application>tinymail</application>, which uses a number of clever
+ tricks for that, such as the proxy design pattern for listing email
+ headers, and not needing memory for headers which are not currently
+ visible.
+ </para>
+
+ <para>
+ <application>modest</application>, in turn, also tries to be efficient,
+ fast and scalable. That means that the <abbrev>MUA</abbrev> should
+ support multiple user-interfaces, perhaps making it even possible to
+ switch between them during runtime.
+ </para>
+
+ <para>To summarize the goals for <application>modest</application>:
+ <itemizedlist>
+ <listitem>target devices with limited amounts of memory ('limited' in 2006
+ terms means less than 64Mb, and of which only part can be used for
+ e-mail);</listitem>
+ <listitem>target Linux/Unix-like environments with GLib/GTK+-based
+ support;</listitem>
+ <listitem>support multiple user-interface (UIs) with as much code
+ sharing as possible between the different UIs.</listitem>
+ </itemizedlist></para>
+
+ <para>Like <application>tinymail</application>
+ and <application>libcamel</application>, <application>modest</application>
+ is programmed in C, using the <package>GObject</package>-system for
+ object-oriented (OO) features. For now, it specifically targets \gtk based
+ UIs (and derivatives like 'Hildon').</para>
+
+ </preface>
\ No newline at end of file
ModestTransportWidget
modest_transport_widget_new
modest_transport_widget_get_remember_password
+modest_transport_widget_get_requires_auth
modest_transport_widget_get_username
modest_transport_widget_get_servername
modest_transport_widget_get_proto
</SECTION>
<SECTION>
+<FILE>modest-account-view</FILE>
+<TITLE>ModestAccountView</TITLE>
+ModestAccountView
+modest_account_view_new
+modest_account_view_get_selected_account
+<SUBSECTION Standard>
+MODEST_ACCOUNT_VIEW
+MODEST_IS_ACCOUNT_VIEW
+MODEST_TYPE_ACCOUNT_VIEW
+modest_account_view_get_type
+MODEST_ACCOUNT_VIEW_CLASS
+MODEST_IS_ACCOUNT_VIEW_CLASS
+MODEST_ACCOUNT_VIEW_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>modest-header-view</FILE>
+MODEST_HEADER_VIEW_COLUMN
+ModestHeaderViewColumn
+ModestHeaderViewStyle
+ModestItemType
+<TITLE>ModestHeaderView</TITLE>
+ModestHeaderView
+modest_header_view_new
+modest_header_view_set_folder
+modest_header_view_get_folder
+modest_header_view_set_columns
+modest_header_view_get_columns
+modest_header_view_set_style
+modest_header_view_get_style
+modest_header_view_get_selected_headers
+<SUBSECTION Standard>
+MODEST_HEADER_VIEW
+MODEST_IS_HEADER_VIEW
+MODEST_TYPE_HEADER_VIEW
+modest_header_view_get_type
+MODEST_HEADER_VIEW_CLASS
+MODEST_IS_HEADER_VIEW_CLASS
+MODEST_HEADER_VIEW_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>modest-toolbar</FILE>
+ModestToolbarButton
+<TITLE>ModestToolbar</TITLE>
+ModestToolbar
+modest_toolbar_new
+<SUBSECTION Standard>
+MODEST_TOOLBAR
+MODEST_IS_TOOLBAR
+MODEST_TYPE_TOOLBAR
+modest_toolbar_get_type
+MODEST_TOOLBAR_CLASS
+MODEST_IS_TOOLBAR_CLASS
+MODEST_TOOLBAR_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>modest-folder-view</FILE>
+<TITLE>ModestFolderView</TITLE>
+ModestFolderView
+modest_folder_view_new
+modest_folder_view_set_title
+modest_folder_view_is_empty
+modest_folder_view_guess_folder_type
+modest_folder_view_get_selected_account
+<SUBSECTION Standard>
+MODEST_FOLDER_VIEW
+MODEST_IS_FOLDER_VIEW
+MODEST_TYPE_FOLDER_VIEW
+modest_folder_view_get_type
+MODEST_FOLDER_VIEW_CLASS
+MODEST_IS_FOLDER_VIEW_CLASS
+MODEST_FOLDER_VIEW_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>modest-combo-box</FILE>
+<TITLE>ModestComboBox</TITLE>
+ModestComboBox
+modest_combo_box_new
+modest_combo_box_get_active_id
+modest_combo_box_get_active_display_name
+<SUBSECTION Standard>
+MODEST_COMBO_BOX
+MODEST_IS_COMBO_BOX
+MODEST_TYPE_COMBO_BOX
+modest_combo_box_get_type
+MODEST_COMBO_BOX_CLASS
+MODEST_IS_COMBO_BOX_CLASS
+MODEST_COMBO_BOX_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>modest-msg-view</FILE>
+<TITLE>ModestMsgView</TITLE>
+ModestMsgView
+modest_msg_view_new
+modest_msg_view_set_message
+<SUBSECTION Standard>
+MODEST_MSG_VIEW
+MODEST_IS_MSG_VIEW
+MODEST_TYPE_MSG_VIEW
+modest_msg_view_get_type
+MODEST_MSG_VIEW_CLASS
+MODEST_IS_MSG_VIEW_CLASS
+MODEST_MSG_VIEW_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>modest-account-assistant</FILE>
+<TITLE>ModestAccountAssistant</TITLE>
+ModestAccountAssistant
+modest_account_assistant_new
+<SUBSECTION Standard>
+MODEST_ACCOUNT_ASSISTANT
+MODEST_IS_ACCOUNT_ASSISTANT
+MODEST_TYPE_ACCOUNT_ASSISTANT
+modest_account_assistant_get_type
+MODEST_ACCOUNT_ASSISTANT_CLASS
+MODEST_IS_ACCOUNT_ASSISTANT_CLASS
+MODEST_ACCOUNT_ASSISTANT_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>modest-account-view-window</FILE>
+<TITLE>ModestAccountViewWindow</TITLE>
+ModestAccountViewWindow
+modest_account_view_window_new
+<SUBSECTION Standard>
+MODEST_ACCOUNT_VIEW_WINDOW
+MODEST_IS_ACCOUNT_VIEW_WINDOW
+MODEST_TYPE_ACCOUNT_VIEW_WINDOW
+modest_account_view_window_get_type
+MODEST_ACCOUNT_VIEW_WINDOW_CLASS
+MODEST_IS_ACCOUNT_VIEW_WINDOW_CLASS
+MODEST_ACCOUNT_VIEW_WINDOW_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>modest-transport-widget</FILE>
+<TITLE>ModestTransportWidget</TITLE>
+ModestTransportWidget
+modest_transport_widget_new
+modest_transport_widget_get_remember_password
+modest_transport_widget_get_requires_auth
+modest_transport_widget_get_username
+modest_transport_widget_get_servername
+modest_transport_widget_get_proto
+<SUBSECTION Standard>
+MODEST_TRANSPORT_WIDGET
+MODEST_IS_TRANSPORT_WIDGET
+MODEST_TYPE_TRANSPORT_WIDGET
+modest_transport_widget_get_type
+MODEST_TRANSPORT_WIDGET_CLASS
+MODEST_IS_TRANSPORT_WIDGET_CLASS
+MODEST_TRANSPORT_WIDGET_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>modest-store-widget</FILE>
+<TITLE>ModestStoreWidget</TITLE>
+ModestStoreWidget
+modest_store_widget_new
+modest_store_widget_get_remember_password
+modest_store_widget_get_username
+modest_store_widget_get_servername
+modest_store_widget_get_proto
+<SUBSECTION Standard>
+MODEST_STORE_WIDGET
+MODEST_IS_STORE_WIDGET
+MODEST_TYPE_STORE_WIDGET
+modest_store_widget_get_type
+MODEST_STORE_WIDGET_CLASS
+MODEST_IS_STORE_WIDGET_CLASS
+MODEST_STORE_WIDGET_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>modest-edit-msg-window</FILE>
+<TITLE>ModestEditMsgWindow</TITLE>
+ModestEditMsgWindow
+ModestEditType
+modest_edit_msg_window_new
+modest_edit_msg_window_set_msg
+<SUBSECTION Standard>
+MODEST_EDIT_MSG_WINDOW
+MODEST_IS_EDIT_MSG_WINDOW
+MODEST_TYPE_EDIT_MSG_WINDOW
+modest_edit_msg_window_get_type
+MODEST_EDIT_MSG_WINDOW_CLASS
+MODEST_IS_EDIT_MSG_WINDOW_CLASS
+MODEST_EDIT_MSG_WINDOW_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>modest-main-window</FILE>
+<TITLE>ModestMainWindow</TITLE>
+ModestMainWindow
+modest_main_window_new
+<SUBSECTION Standard>
+MODEST_MAIN_WINDOW
+MODEST_IS_MAIN_WINDOW
+MODEST_TYPE_MAIN_WINDOW
+modest_main_window_get_type
+MODEST_MAIN_WINDOW_CLASS
+MODEST_IS_MAIN_WINDOW_CLASS
+MODEST_MAIN_WINDOW_GET_CLASS
+</SECTION>
+
+<SECTION>
<FILE>modest-tny-attachment</FILE>
<TITLE>ModestTnyAttachment</TITLE>
ModestTnyAttachment
<SECTION>
<FILE>modest-tny-account-store</FILE>
ModestTnyGetPassFunc
-<TITLE>ModestTnyAccountStore</TITLE>
-ModestTnyAccountStore
-modest_tny_account_store_new
-tny_account_store_get_session
-<SUBSECTION Standard>
-MODEST_TNY_ACCOUNT_STORE
-MODEST_IS_TNY_ACCOUNT_STORE
-MODEST_TYPE_TNY_ACCOUNT_STORE
-modest_tny_account_store_get_type
-MODEST_TNY_ACCOUNT_STORE_CLASS
-MODEST_IS_TNY_ACCOUNT_STORE_CLASS
-MODEST_TNY_ACCOUNT_STORE_GET_CLASS
-</SECTION>
-
-<SECTION>
-<FILE>modest-account-assistant</FILE>
-<TITLE>ModestAccountAssistant</TITLE>
-ModestAccountAssistant
-modest_account_assistant_new
-<SUBSECTION Standard>
-MODEST_ACCOUNT_ASSISTANT
-MODEST_IS_ACCOUNT_ASSISTANT
-MODEST_TYPE_ACCOUNT_ASSISTANT
-modest_account_assistant_get_type
-MODEST_ACCOUNT_ASSISTANT_CLASS
-MODEST_IS_ACCOUNT_ASSISTANT_CLASS
-MODEST_ACCOUNT_ASSISTANT_GET_CLASS
-</SECTION>
-
-<SECTION>
-<FILE>modest-account-view-window</FILE>
-<TITLE>ModestAccountViewWindow</TITLE>
-ModestAccountViewWindow
-modest_account_view_window_new
-<SUBSECTION Standard>
-MODEST_ACCOUNT_VIEW_WINDOW
-MODEST_IS_ACCOUNT_VIEW_WINDOW
-MODEST_TYPE_ACCOUNT_VIEW_WINDOW
-modest_account_view_window_get_type
-MODEST_ACCOUNT_VIEW_WINDOW_CLASS
-MODEST_IS_ACCOUNT_VIEW_WINDOW_CLASS
-MODEST_ACCOUNT_VIEW_WINDOW_GET_CLASS
-</SECTION>
-
-<SECTION>
-<FILE>modest-transport-widget</FILE>
-<TITLE>ModestTransportWidget</TITLE>
-ModestTransportWidget
-modest_transport_widget_new
-modest_transport_widget_get_remember_password
-modest_transport_widget_get_username
-modest_transport_widget_get_servername
-modest_transport_widget_get_proto
-<SUBSECTION Standard>
-MODEST_TRANSPORT_WIDGET
-MODEST_IS_TRANSPORT_WIDGET
-MODEST_TYPE_TRANSPORT_WIDGET
-modest_transport_widget_get_type
-MODEST_TRANSPORT_WIDGET_CLASS
-MODEST_IS_TRANSPORT_WIDGET_CLASS
-MODEST_TRANSPORT_WIDGET_GET_CLASS
-</SECTION>
-
-<SECTION>
-<FILE>modest-store-widget</FILE>
-<TITLE>ModestStoreWidget</TITLE>
-ModestStoreWidget
-modest_store_widget_new
-modest_store_widget_get_remember_password
-modest_store_widget_get_username
-modest_store_widget_get_servername
-modest_store_widget_get_proto
-<SUBSECTION Standard>
-MODEST_STORE_WIDGET
-MODEST_IS_STORE_WIDGET
-MODEST_TYPE_STORE_WIDGET
-modest_store_widget_get_type
-MODEST_STORE_WIDGET_CLASS
-MODEST_IS_STORE_WIDGET_CLASS
-MODEST_STORE_WIDGET_GET_CLASS
-</SECTION>
-
-<SECTION>
-<FILE>modest-edit-msg-window</FILE>
-<TITLE>ModestEditMsgWindow</TITLE>
-ModestEditMsgWindow
-ModestEditType
-modest_edit_msg_window_new
-modest_edit_msg_window_set_msg
-<SUBSECTION Standard>
-MODEST_EDIT_MSG_WINDOW
-MODEST_IS_EDIT_MSG_WINDOW
-MODEST_TYPE_EDIT_MSG_WINDOW
-modest_edit_msg_window_get_type
-MODEST_EDIT_MSG_WINDOW_CLASS
-MODEST_IS_EDIT_MSG_WINDOW_CLASS
-MODEST_EDIT_MSG_WINDOW_GET_CLASS
-</SECTION>
-
-<SECTION>
-<FILE>modest-main-window</FILE>
-<TITLE>ModestMainWindow</TITLE>
-ModestMainWindow
-modest_main_window_new
+<TITLE>ModestTnyAccountStore</TITLE>
+ModestTnyAccountStore
+modest_tny_account_store_new
+tny_account_store_get_session
<SUBSECTION Standard>
-MODEST_MAIN_WINDOW
-MODEST_IS_MAIN_WINDOW
-MODEST_TYPE_MAIN_WINDOW
-modest_main_window_get_type
-MODEST_MAIN_WINDOW_CLASS
-MODEST_IS_MAIN_WINDOW_CLASS
-MODEST_MAIN_WINDOW_GET_CLASS
+MODEST_TNY_ACCOUNT_STORE
+MODEST_IS_TNY_ACCOUNT_STORE
+MODEST_TYPE_TNY_ACCOUNT_STORE
+modest_tny_account_store_get_type
+MODEST_TNY_ACCOUNT_STORE_CLASS
+MODEST_IS_TNY_ACCOUNT_STORE_CLASS
+MODEST_TNY_ACCOUNT_STORE_GET_CLASS
</SECTION>
<SECTION>
ModestTransportWidget
modest_transport_widget_new
modest_transport_widget_get_remember_password
+modest_transport_widget_get_requires_auth
modest_transport_widget_get_username
modest_transport_widget_get_servername
modest_transport_widget_get_proto
ModestEditMsgWindow
ModestEditType
modest_edit_msg_window_new
+modest_edit_msg_window_set_msg
<SUBSECTION Standard>
MODEST_EDIT_MSG_WINDOW
MODEST_IS_EDIT_MSG_WINDOW
</SECTION>
<SECTION>
-<FILE>modest-account-view</FILE>
-<TITLE>ModestAccountView</TITLE>
-ModestAccountView
-modest_account_view_new
-modest_account_view_get_selected_account
-<SUBSECTION Standard>
-MODEST_ACCOUNT_VIEW
-MODEST_IS_ACCOUNT_VIEW
-MODEST_TYPE_ACCOUNT_VIEW
-modest_account_view_get_type
-MODEST_ACCOUNT_VIEW_CLASS
-MODEST_IS_ACCOUNT_VIEW_CLASS
-MODEST_ACCOUNT_VIEW_GET_CLASS
-</SECTION>
-
-<SECTION>
-<FILE>modest-header-view</FILE>
-MODEST_HEADER_VIEW_COLUMN
-ModestHeaderViewColumn
-ModestHeaderViewStyle
-ModestItemType
-<TITLE>ModestHeaderView</TITLE>
-ModestHeaderView
-modest_header_view_new
-modest_header_view_set_folder
-modest_header_view_get_folder
-modest_header_view_set_columns
-modest_header_view_get_columns
-modest_header_view_set_style
-modest_header_view_get_style
-modest_header_view_get_selected_headers
-<SUBSECTION Standard>
-MODEST_HEADER_VIEW
-MODEST_IS_HEADER_VIEW
-MODEST_TYPE_HEADER_VIEW
-modest_header_view_get_type
-MODEST_HEADER_VIEW_CLASS
-MODEST_IS_HEADER_VIEW_CLASS
-MODEST_HEADER_VIEW_GET_CLASS
-</SECTION>
-
-<SECTION>
-<FILE>modest-toolbar</FILE>
-ModestToolbarButton
-<TITLE>ModestToolbar</TITLE>
-ModestToolbar
-modest_toolbar_new
-<SUBSECTION Standard>
-MODEST_TOOLBAR
-MODEST_IS_TOOLBAR
-MODEST_TYPE_TOOLBAR
-modest_toolbar_get_type
-MODEST_TOOLBAR_CLASS
-MODEST_IS_TOOLBAR_CLASS
-MODEST_TOOLBAR_GET_CLASS
-</SECTION>
-
-<SECTION>
-<FILE>modest-folder-view</FILE>
-<TITLE>ModestFolderView</TITLE>
-ModestFolderView
-modest_folder_view_new
-modest_folder_view_set_title
-modest_folder_view_is_empty
-modest_folder_view_guess_folder_type
-modest_folder_view_get_selected_account
-<SUBSECTION Standard>
-MODEST_FOLDER_VIEW
-MODEST_IS_FOLDER_VIEW
-MODEST_TYPE_FOLDER_VIEW
-modest_folder_view_get_type
-MODEST_FOLDER_VIEW_CLASS
-MODEST_IS_FOLDER_VIEW_CLASS
-MODEST_FOLDER_VIEW_GET_CLASS
-</SECTION>
-
-<SECTION>
-<FILE>modest-combo-box</FILE>
-<TITLE>ModestComboBox</TITLE>
-ModestComboBox
-modest_combo_box_new
-modest_combo_box_get_active_id
-modest_combo_box_get_active_display_name
-<SUBSECTION Standard>
-MODEST_COMBO_BOX
-MODEST_IS_COMBO_BOX
-MODEST_TYPE_COMBO_BOX
-modest_combo_box_get_type
-MODEST_COMBO_BOX_CLASS
-MODEST_IS_COMBO_BOX_CLASS
-MODEST_COMBO_BOX_GET_CLASS
-</SECTION>
-
-<SECTION>
-<FILE>modest-msg-view</FILE>
-<TITLE>ModestMsgView</TITLE>
-ModestMsgView
-modest_msg_view_new
-modest_msg_view_set_message
-<SUBSECTION Standard>
-MODEST_MSG_VIEW
-MODEST_IS_MSG_VIEW
-MODEST_TYPE_MSG_VIEW
-modest_msg_view_get_type
-MODEST_MSG_VIEW_CLASS
-MODEST_IS_MSG_VIEW_CLASS
-MODEST_MSG_VIEW_GET_CLASS
-</SECTION>
-
-<SECTION>
<FILE>modest-account-assistant</FILE>
<TITLE>ModestAccountAssistant</TITLE>
ModestAccountAssistant
ModestEditMsgWindow
ModestEditType
modest_edit_msg_window_new
-modest_edit_msg_window_set_msg
<SUBSECTION Standard>
MODEST_EDIT_MSG_WINDOW
MODEST_IS_EDIT_MSG_WINDOW
MODEST_ACCOUNT_USERNAME
MODEST_ACCOUNT_PROTO
MODEST_ACCOUNT_ENABLED
+MODEST_ACCOUNT_TYPE
MODEST_ACCOUNT_LEAVE_ON_SERVER
MODEST_ACCOUNT_PREFERRED_CNX
MODEST_ACCOUNT_OPTIONS
</SECTION>
<SECTION>
+<FILE>modest-widget-memory</FILE>
+modest_widget_memory_save
+modest_widget_memory_restore
+</SECTION>
+
+<SECTION>
+<FILE>modest-tny-msg-actions</FILE>
+modest_tny_msg_actions_find_body_part
+modest_tny_msg_actions_find_nth_part
+modest_tny_msg_actions_find_body
+</SECTION>
+
+<SECTION>
<FILE>modest-marshal</FILE>
modest_marshal_VOID__POINTER_POINTER
modest_marshal_VOID__POINTER_POINTER_POINTER
</SECTION>
<SECTION>
-<FILE>modest-widget-memory</FILE>
-modest_widget_memory_save
-modest_widget_memory_restore
-</SECTION>
-
-<SECTION>
-<FILE>modest-tny-msg-actions</FILE>
-modest_tny_msg_actions_find_body_part
-modest_tny_msg_actions_find_nth_part
-modest_tny_msg_actions_find_body
-</SECTION>
-
-<SECTION>
<FILE>modest-error</FILE>
ModestErrorDomain
ModestErrorCode
</SECTION>
<SECTION>
+<FILE>modest-header-view-priv</FILE>
+</SECTION>
+
+<SECTION>
+<FILE>modest-icon-names</FILE>
+PIXMAP_PREFIX
+MODEST_APP_ICON
+MODEST_HEADER_ICON_READ
+MODEST_HEADER_ICON_UNREAD
+MODEST_HEADER_ICON_DELETED
+MODEST_HEADER_ICON_ATTACH
+MODEST_FOLDER_ICON_OPEN
+MODEST_FOLDER_ICON_CLOSED
+MODEST_FOLDER_ICON_ACCOUNT
+MODEST_FOLDER_ICON_INBOX
+MODEST_FOLDER_ICON_OUTBOX
+MODEST_FOLDER_ICON_SENT
+MODEST_FOLDER_ICON_TRASH
+MODEST_FOLDER_ICON_JUNK
+MODEST_FOLDER_ICON_DRAFTS
+MODEST_FOLDER_ICON_NORMAL
+MODEST_FOLDER_ICON_CONTACTS
+MODEST_FOLDER_ICON_NOTES
+MODEST_FOLDER_ICON_CALENDAR
+MODEST_TOOLBAR_ICON_MAIL_SEND
+MODEST_TOOLBAR_ICON_NEW_MAIL
+MODEST_TOOLBAR_ICON_SEND_RECEIVE
+MODEST_TOOLBAR_ICON_REPLY
+MODEST_TOOLBAR_ICON_REPLY_ALL
+MODEST_TOOLBAR_ICON_FORWARD
+MODEST_TOOLBAR_ICON_DELETE
+MODEST_TOOLBAR_ICON_NEXT
+MODEST_TOOLBAR_ICON_PREV
+MODEST_TOOLBAR_ICON_STOP
+</SECTION>
+
+<SECTION>
<FILE>modest-tny-store-actions</FILE>
modest_tny_store_actions_create_folder
modest_tny_store_actions_remove_folder
MODEST_ACCOUNT_USERNAME
MODEST_ACCOUNT_PROTO
MODEST_ACCOUNT_ENABLED
+MODEST_ACCOUNT_TYPE
MODEST_ACCOUNT_LEAVE_ON_SERVER
MODEST_ACCOUNT_PREFERRED_CNX
MODEST_ACCOUNT_OPTIONS
</SECTION>
<SECTION>
+<FILE>modest-widget-memory</FILE>
+modest_widget_memory_save
+modest_widget_memory_restore
+</SECTION>
+
+<SECTION>
+<FILE>modest-tny-msg-actions</FILE>
+modest_tny_msg_actions_find_body_part
+modest_tny_msg_actions_find_nth_part
+modest_tny_msg_actions_find_body
+</SECTION>
+
+<SECTION>
<FILE>modest-marshal</FILE>
modest_marshal_VOID__POINTER_POINTER
modest_marshal_VOID__POINTER_POINTER_POINTER
</SECTION>
<SECTION>
-<FILE>modest-widget-memory</FILE>
-modest_widget_memory_save
-modest_widget_memory_restore
-</SECTION>
-
-<SECTION>
-<FILE>modest-tny-msg-actions</FILE>
-modest_tny_msg_actions_find_body_part
-modest_tny_msg_actions_find_nth_part
-modest_tny_msg_actions_find_body
-</SECTION>
-
-<SECTION>
<FILE>modest-error</FILE>
ModestErrorDomain
ModestErrorCode
<FILE>modest-header-view-priv</FILE>
</SECTION>
-<SECTION>
-<FILE>modest-icon-names</FILE>
-PIXMAP_PREFIX
-MODEST_APP_ICON
-MODEST_HEADER_ICON_READ
-MODEST_HEADER_ICON_UNREAD
-MODEST_HEADER_ICON_DELETED
-MODEST_HEADER_ICON_ATTACH
-MODEST_FOLDER_ICON_OPEN
-MODEST_FOLDER_ICON_CLOSED
-MODEST_FOLDER_ICON_ACCOUNT
-MODEST_FOLDER_ICON_INBOX
-MODEST_FOLDER_ICON_OUTBOX
-MODEST_FOLDER_ICON_SENT
-MODEST_FOLDER_ICON_TRASH
-MODEST_FOLDER_ICON_JUNK
-MODEST_FOLDER_ICON_DRAFTS
-MODEST_FOLDER_ICON_NORMAL
-MODEST_FOLDER_ICON_CONTACTS
-MODEST_FOLDER_ICON_NOTES
-MODEST_FOLDER_ICON_CALENDAR
-MODEST_TOOLBAR_ICON_MAIL_SEND
-MODEST_TOOLBAR_ICON_NEW_MAIL
-MODEST_TOOLBAR_ICON_SEND_RECEIVE
-MODEST_TOOLBAR_ICON_REPLY
-MODEST_TOOLBAR_ICON_REPLY_ALL
-MODEST_TOOLBAR_ICON_FORWARD
-MODEST_TOOLBAR_ICON_DELETE
-MODEST_TOOLBAR_ICON_NEXT
-MODEST_TOOLBAR_ICON_PREV
-MODEST_TOOLBAR_ICON_STOP
-</SECTION>
-
-<SECTION>
-<FILE>modest-header-view-priv</FILE>
-</SECTION>
-
ModestAccountAssistant
<!-- ##### SECTION Short_Description ##### -->
-A widget that displays a wizard to create new accounts
+
<!-- ##### SECTION Long_Description ##### -->
<para>
+<!-- ##### MACRO MODEST_ACCOUNT_TYPE ##### -->
+<para>
+
+</para>
+
+
+
<!-- ##### MACRO MODEST_ACCOUNT_LEAVE_ON_SERVER ##### -->
<para>
</para>
-@:
-@:
-@:
-@:
+@modestaccountmgr: the object which received the signal.
+@arg1:
+@arg2:
+@arg3:
<!-- ##### SIGNAL ModestAccountMgr::account-removed ##### -->
<para>
</para>
-@:
-@:
-@:
-
-<!-- ##### SIGNAL ModestAccountMgr::account-changed ##### -->
-<para>
-
-</para>
-
-@:
-@:
-@:
-@:
-
-<!-- ##### SIGNAL ModestAccountMgr::account-removed ##### -->
-<para>
-
-</para>
-
-@:
-@:
-@:
+@modestaccountmgr: the object which received the signal.
+@arg1:
+@arg2:
<!-- ##### STRUCT ModestServerAccountData ##### -->
<para>
ModestAccountViewWindow
<!-- ##### SECTION Short_Description ##### -->
-A window that shows the list of available accounts
+
<!-- ##### SECTION Long_Description ##### -->
<para>
ModestAccountView
<!-- ##### SECTION Short_Description ##### -->
-A widget that shows a list with the available accounts
+
<!-- ##### SECTION Long_Description ##### -->
<para>
ModestComboBox
<!-- ##### SECTION Short_Description ##### -->
-A wrapper for a #GtkComboBox that shows lists of #ModestPair objects
+
<!-- ##### SECTION Long_Description ##### -->
<para>
</para>
-@:
-@:
-@:
-
-<!-- ##### SIGNAL ModestConf::key-changed ##### -->
-<para>
-
-</para>
-
-@:
-@:
-@:
+@modestconf: the object which received the signal.
+@arg1:
+@arg2:
<!-- ##### FUNCTION modest_conf_new ##### -->
<para>
ModestEditMsgWindow
<!-- ##### SECTION Short_Description ##### -->
-A window used for composing messages
+
<!-- ##### SECTION Long_Description ##### -->
<para>
@Returns:
-<!-- ##### FUNCTION modest_edit_msg_window_set_msg ##### -->
-<para>
-
-</para>
-
-@self:
-@msg:
-
-
modest-error
<!-- ##### SECTION Short_Description ##### -->
-Modest error stuff
+
<!-- ##### SECTION Long_Description ##### -->
<para>
ModestFolderView
<!-- ##### SECTION Short_Description ##### -->
-A widget that shows the list of folders of email accounts
+
<!-- ##### SECTION Long_Description ##### -->
<para>
ModestFormatter
<!-- ##### SECTION Short_Description ##### -->
-An object that creates new emails from others
+
<!-- ##### SECTION Long_Description ##### -->
<para>
ModestHeaderView
<!-- ##### SECTION Short_Description ##### -->
-A widget that shows a list of email headers
+
<!-- ##### SECTION Long_Description ##### -->
<para>
modest-icon-factory
<!-- ##### SECTION Short_Description ##### -->
-A factory that creates the icons for Modest
+
<!-- ##### SECTION Long_Description ##### -->
<para>
modest-icon-names
<!-- ##### SECTION Short_Description ##### -->
-Definitions for the Modest icons
+
<!-- ##### SECTION Long_Description ##### -->
<para>
ModestMailOperationQueue
<!-- ##### SECTION Short_Description ##### -->
-An object that stores a queue of #ModestMailOperation
+
<!-- ##### SECTION Long_Description ##### -->
<para>
ModestMailOperation
<!-- ##### SECTION Short_Description ##### -->
-An object that performs mail operations
+
<!-- ##### SECTION Long_Description ##### -->
<para>
@self:
@header:
@folder:
+@Returns:
<!-- ##### FUNCTION modest_mail_operation_move_msg ##### -->
@self:
@header:
@folder:
+@Returns:
<!-- ##### FUNCTION modest_mail_operation_remove_msg ##### -->
ModestMsgView
<!-- ##### SECTION Short_Description ##### -->
-A widget that shows the body of a message
+
<!-- ##### SECTION Long_Description ##### -->
<para>
</para>
-@modestmsgview: the object which received the signal.
-@arg1:
+@:
+@:
<!-- ##### SIGNAL ModestMsgView::link-clicked ##### -->
<para>
</para>
-@modestmsgview: the object which received the signal.
-@arg1:
+@:
+@:
<!-- ##### SIGNAL ModestMsgView::link-hover ##### -->
<para>
</para>
-@modestmsgview: the object which received the signal.
-@arg1:
+@:
+@:
<!-- ##### FUNCTION modest_msg_view_new ##### -->
<para>
modest-pair
<!-- ##### SECTION Short_Description ##### -->
-An object that stores pairs of related objects
+
<!-- ##### SECTION Long_Description ##### -->
<para>
modest-presets
<!-- ##### SECTION Short_Description ##### -->
-An object that manages Modest presest
+
<!-- ##### SECTION Long_Description ##### -->
<para>
ModestProtocolMgr
<!-- ##### SECTION Short_Description ##### -->
-An object that manages the email protocols
+
<!-- ##### SECTION Long_Description ##### -->
<para>
ModestStoreWidget
<!-- ##### SECTION Short_Description ##### -->
-A widget that shows the server information for a store account
+
<!-- ##### SECTION Long_Description ##### -->
<para>
</para>
+<!-- ##### SIGNAL ModestStoreWidget::data-changed ##### -->
+<para>
+
+</para>
+
+@modeststorewidget: the object which received the signal.
+
+<!-- ##### SIGNAL ModestStoreWidget::data-changed ##### -->
+<para>
+
+</para>
+
+@modeststorewidget: the object which received the signal.
+
<!-- ##### FUNCTION modest_store_widget_new ##### -->
<para>
modest-text-utils
<!-- ##### SECTION Short_Description ##### -->
-A library with text utility functions
+
<!-- ##### SECTION Long_Description ##### -->
<para>
</para>
-@:
-@:
-
-<!-- ##### SIGNAL ModestTnyAccountStore::password-requested ##### -->
-<para>
-
-</para>
-
-@:
-@:
-@:
-@:
-@Param5:
-
-<!-- ##### SIGNAL ModestTnyAccountStore::account-update ##### -->
-<para>
-
-</para>
-
-@:
-@:
+@modesttnyaccountstore: the object which received the signal.
+@arg1:
<!-- ##### SIGNAL ModestTnyAccountStore::password-requested ##### -->
<para>
</para>
@:
-@:
-@:
-@:
+@Param2:
+@Param3:
+@Param4:
@Param5:
<!-- ##### FUNCTION modest_tny_account_store_new ##### -->
ModestTnyPlatformFactory
<!-- ##### SECTION Short_Description ##### -->
-An implementation of a #TnyPlatformFactory
+
<!-- ##### SECTION Long_Description ##### -->
<para>
ModestTnyStreamGtkhtml
<!-- ##### SECTION Short_Description ##### -->
-An implementation of a #TnyStream that uses a #GtkHTMLStream
+
<!-- ##### SECTION Long_Description ##### -->
<para>
ModestToolbar
<!-- ##### SECTION Short_Description ##### -->
-A widgets that shows a toolbar in the Modest main window
+
<!-- ##### SECTION Long_Description ##### -->
<para>
ModestTransportWidget
<!-- ##### SECTION Short_Description ##### -->
-A widget that shows the server information for a transport account
+
<!-- ##### SECTION Long_Description ##### -->
<para>
ModestWidgetFactory
<!-- ##### SECTION Short_Description ##### -->
-A factory that creates the widgets of the UI
+
<!-- ##### SECTION Long_Description ##### -->
<para>
modest-widget-memory
<!-- ##### SECTION Short_Description ##### -->
-An object that stores preferences of the widgets
+
<!-- ##### SECTION Long_Description ##### -->
<para>
* modest_account_mgr_remove_account:
* @self: a ModestAccountMgr instance
* @name: the name of the account to remove
- * @err: a GError ptr, or NULL to ignore.
+ * @server_account: TRUE if the account to remove is a server account
+ * @err: a #GError ptr, or NULL to ignore.
*
* remove an existing account. the account with @name should already exist
*
* Original message
* ----------------
* Date: 1970/01/01
- * From: somemail@modest.org
+ * From: somemailATmodest.org
* Body: "This is the body of the text"
* </para><para>
* Cited message
* -------------
* Body:
- * On 1970/01/01 somemail@modest.org wrote:
+ * On 1970/01/01 somemailATmodest.org wrote:
* This is the body of the text
* </para></programlisting>
*
* Original message
* ----------------
* Date: 1970/01/01
- * From: somemail@modest.org
+ * From: somemailATmodest.org
* Body: "This is the body of the text"
* </para><para>
* Quoted message
* -------------
* Body:
- * On 1970/01/01 somemail@modest.org wrote:
+ * On 1970/01/01 somemailATmodest.org wrote:
* > This is the body of the text
* </para></programlisting>
*
* Original message
* ----------------
* Date: 1970/01/01
- * From: somemail@modest.org
- * To: mymail@modest.org
+ * From: somemailATmodest.org
+ * To: mymailATmodest.org
* Subject: Mail subject
* Body: "This is the body of the text"
* </para><para>
* -------------
* Body:
* -----Forwarded Message-----
- * From: somemail@modest.org
+ * From: somemailATmodest.org
* Sent: 1970/01/01
- * To: mymail@modest.org
+ * To: mymailATmodest.org
* Subject: Fw: Mail subject
- * On 1970/01/01 somemail@modest.org wrote:
+ * On 1970/01/01 somemailATmodest.org wrote:
* This is the body of the text
* </para></programlisting>
*
TnyFolderStore *parent,
gboolean delete_original);
-static void modest_mail_operation_xfer_msg (ModestMailOperation *self,
- TnyHeader *header,
- TnyFolder *folder,
- gboolean delete_original);
+static gboolean modest_mail_operation_xfer_msg (ModestMailOperation *self,
+ TnyHeader *header,
+ TnyFolder *folder,
+ gboolean delete_original);
static TnyFolder * modest_mail_operation_find_trash_folder (ModestMailOperation *self,
TnyStoreAccount *store_account);
/* ************************** MSG ACTIONS ************************* */
/* ******************************************************************* */
-void
+gboolean
modest_mail_operation_copy_msg (ModestMailOperation *self,
TnyHeader *header,
TnyFolder *folder)
{
- g_return_if_fail (TNY_IS_HEADER (header));
- g_return_if_fail (TNY_IS_FOLDER (folder));
+ g_return_val_if_fail (TNY_IS_HEADER (header), FALSE);
+ g_return_val_if_fail (TNY_IS_FOLDER (folder), FALSE);
- modest_mail_operation_xfer_msg (self, header, folder, FALSE);
+ return modest_mail_operation_xfer_msg (self, header, folder, FALSE);
}
-void
+gboolean
modest_mail_operation_move_msg (ModestMailOperation *self,
TnyHeader *header,
TnyFolder *folder)
{
- g_return_if_fail (TNY_IS_HEADER (header));
- g_return_if_fail (TNY_IS_FOLDER (folder));
+ g_return_val_if_fail (TNY_IS_HEADER (header), FALSE);
+ g_return_val_if_fail (TNY_IS_FOLDER (folder), FALSE);
- modest_mail_operation_xfer_msg (self, header, folder, TRUE);
+ return modest_mail_operation_xfer_msg (self, header, folder, TRUE);
}
void
}
static void
+transfer_msgs_cb (TnyFolder *folder, GError **err, gpointer user_data)
+{
+ ModestMailOperationPrivate *priv;
+
+ priv = MODEST_MAIL_OPERATION_GET_PRIVATE(user_data);
+ priv->done = 1;
+ priv->status = MODEST_MAIL_OPERATION_STATUS_SUCCESS;
+
+ g_signal_emit (G_OBJECT (user_data), signals[PROGRESS_CHANGED_SIGNAL], 0, NULL);
+}
+
+static gboolean
modest_mail_operation_xfer_msg (ModestMailOperation *self,
TnyHeader *header,
TnyFolder *folder,
gboolean delete_original)
{
+ ModestMailOperationPrivate *priv;
TnyFolder *src_folder;
TnyList *headers;
src_folder = tny_header_get_folder (header);
headers = tny_simple_list_new ();
- /* Move */
+ priv = MODEST_MAIL_OPERATION_GET_PRIVATE(self);
+ priv->total = 1;
+ priv->done = 0;
+ priv->status = MODEST_MAIL_OPERATION_STATUS_IN_PROGRESS;
+
tny_list_prepend (headers, G_OBJECT (header));
- tny_folder_transfer_msgs (src_folder, headers, folder, delete_original, NULL); /* FIXME */
+ tny_folder_transfer_msgs_async (src_folder, headers, folder,
+ delete_original, transfer_msgs_cb, self);
/* Free */
g_object_unref (headers);
g_object_unref (folder);
+
+ return TRUE;
}
typedef struct _ModestMailOperation ModestMailOperation;
typedef struct _ModestMailOperationClass ModestMailOperationClass;
-/* typedef enum _ModestMailOperationForwardType ModestMailOperationForwardType; */
-/* typedef enum _ModestMailOperationReplyType ModestMailOperationReplyType; */
-/* typedef enum _ModestMailOperationReplyMode ModestMailOperationReplyMode; */
-/* typedef enum _ModestMailOperationStatus ModestMailOperationStatus; */
-
+/**
+ * ModestMailOperationForwardType:
+ *
+ * How the original message will be forwarded to the recipient
+ */
typedef enum _ModestMailOperationForwardType {
MODEST_MAIL_OPERATION_FORWARD_TYPE_INLINE = 1,
MODEST_MAIL_OPERATION_FORWARD_TYPE_ATTACHMENT
} ModestMailOperationForwardType;
+/**
+ * ModestMailOperationReplyType:
+ *
+ * How the original message will be forwarded to the recipient
+ */
typedef enum _ModestMailOperationReplyType {
MODEST_MAIL_OPERATION_REPLY_TYPE_CITE = 1,
MODEST_MAIL_OPERATION_REPLY_TYPE_QUOTE
} ModestMailOperationReplyType;
+/**
+ * ModestMailOperationReplyMode:
+ *
+ * Who will be the recipients of the replied message
+ */
typedef enum _ModestMailOperationReplyMode {
MODEST_MAIL_OPERATION_REPLY_MODE_SENDER,
MODEST_MAIL_OPERATION_REPLY_MODE_LIST,
MODEST_MAIL_OPERATION_REPLY_MODE_ALL
} ModestMailOperationReplyMode;
+/**
+ * ModestMailOperationStatus:
+ *
+ * The state of a mail operation
+ */
typedef enum _ModestMailOperationStatus {
MODEST_MAIL_OPERATION_STATUS_INVALID,
MODEST_MAIL_OPERATION_STATUS_SUCCESS,
* <informalexample><programlisting>
* queue = modest_tny_platform_factory_get_modest_mail_operation_queue_instance (fact)
* mail_op = modest_mail_operation_new ();
- * g_signal_connect (G_OBJECT (mail_op), "progress_changed", G_CALLBACK (on_progress_changed), queue);
+ * g_signal_connect (G_OBJECT (mail_op), "progress_changed", G_CALLBACK(on_progress_changed), queue);
* if (modest_mail_operation_update_account (mail_op, account))
* {
* modest_mail_operation_queue_add (queue, mail_op);
* @header: the #TnyHeader of the message to copy
* @folder: the #TnyFolder where the message will be copied
*
- * Copies a message from its current folder to another one. This
- * operation is synchronous, so the #ModestMailOperation should not be
- * added to any #ModestMailOperationQueue
+ * Asynchronously copies a message from its current folder to another
+ * one. The caller should add the #ModestMailOperation to a
+ * #ModestMailOperationQueue and then free it. The caller will be
+ * notified by the "progress_changed" when the operation is completed.
+ *
+ * Example
+ * <informalexample><programlisting>
+ * queue = modest_tny_platform_factory_get_modest_mail_operation_queue_instance (fact);
+ * mail_op = modest_mail_operation_new ();
+ * if (modest_mail_operation_copy_msg (mail_op, account))
+ * {
+ * g_signal_connect (G_OBJECT (mail_op), "progress_changed", G_CALLBACK(on_progress_changed), queue);
+ * modest_mail_operation_queue_add (queue, mail_op);
+ * }
+ * g_object_unref (G_OBJECT (mail_op));
+ * </programlisting></informalexample>
+ *
+ * Returns: TRUE if the mail operation could be started, or FALSE otherwise
**/
-void modest_mail_operation_copy_msg (ModestMailOperation *self,
+gboolean modest_mail_operation_copy_msg (ModestMailOperation *self,
TnyHeader *header,
TnyFolder *folder);
* @header: the #TnyHeader of the message to move
* @folder: the #TnyFolder where the message will be moved
*
- * Moves a message from its current folder to another one. This
- * operation is synchronous, so the #ModestMailOperation should not be
- * added to any #ModestMailOperationQueue
+ * Asynchronously moves a message from its current folder to another
+ * one. The caller should add the #ModestMailOperation to a
+ * #ModestMailOperationQueue and then free it. The caller will be
+ * notified by the "progress_changed" when the operation is completed.
+ *
+ * Example
+ * <informalexample><programlisting>
+ * queue = modest_tny_platform_factory_get_modest_mail_operation_queue_instance (fact);
+ * mail_op = modest_mail_operation_new ();
+ * if (modest_mail_operation_move_msg (mail_op, account))
+ * {
+ * g_signal_connect (G_OBJECT (mail_op), "progress_changed", G_CALLBACK(on_progress_changed), queue);
+ * modest_mail_operation_queue_add (queue, mail_op);
+ * }
+ * g_object_unref (G_OBJECT (mail_op));
+ * </programlisting></informalexample>
+ *
+ * Returns: TRUE if the mail operation could be started, or FALSE otherwise
**/
-void modest_mail_operation_move_msg (ModestMailOperation *self,
+gboolean modest_mail_operation_move_msg (ModestMailOperation *self,
TnyHeader *header,
TnyFolder *folder);
projects / modest / commitdiff