diff options
Diffstat (limited to 'help')
| -rw-r--r-- | help/.cvsignore | 2 | ||||
| -rw-r--r-- | help/C/evo_book_0.1.sgml | 449 | ||||
| -rw-r--r-- | help/Camel-Classes | 24 | ||||
| -rw-r--r-- | help/ChangeLog | 58 | ||||
| -rw-r--r-- | help/Design | 201 | ||||
| -rw-r--r-- | help/white-papers/calendar/calendar.sgml | 209 | ||||
| -rw-r--r-- | help/white-papers/mail/camel.sgml | 339 | ||||
| -rw-r--r-- | help/white-papers/mail/ibex.sgml | 158 | ||||
| -rw-r--r-- | help/white-papers/widgets/e-table.sgml | 279 |
9 files changed, 0 insertions, 1719 deletions
diff --git a/help/.cvsignore b/help/.cvsignore deleted file mode 100644 index 550bd25cdb..0000000000 --- a/help/.cvsignore +++ /dev/null @@ -1,2 +0,0 @@ -Makefile - diff --git a/help/C/evo_book_0.1.sgml b/help/C/evo_book_0.1.sgml deleted file mode 100644 index 357da80224..0000000000 --- a/help/C/evo_book_0.1.sgml +++ /dev/null @@ -1,449 +0,0 @@ -<!DOCTYPE book PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.0//EN"> - -<book> -<bookinfo> - <title>Evolution Users Guide</title> - <author><firstname>Aaron</firstname><surname>Weber</surname></author> - <copyright><year>2000</year><holder>Aaron Weber and Helix Code, inc.</holder></copyright> - - <legalnotice> -PUT THE RIGHT LEGALNOTICE IN HERE - - <para> Windows, Exchange, and Outlook are trademarks of Microsoft Corp.</para> - <para> Lotus and Lotus Notes are trademarks of The Louts Corporation.</para> - <para> Macintosh and Apple are trademarks of Apple Computer, Inc.</para> - <para> All other trademarks are property of their respective owners.</para> - </legalnotice> - - <releaseinfo> - This is version 0.0 of Evolution manual. - </releaseinfo> <!-- this is version of manual, not application --> - -</bookinfo> - -<preface> -<!-- =============Introduction ============================= --> - <title>Introduction</title> - - <section> <title> What is Evolution?</title> - <para> - <application>Evolution</application> is a suite of groupware applications - for mail, contact management, and calendaring. It is - included in the package <filename>Evolution</filename>, which is a - part of the GNOME desktop environment. This document describes - version &version; of <application>Evolution</application> - </para> - - <para> - What that means is that Evolution is your personal secretary. It can keep track of - memos, emails, - and appointments for you and for everyone in your office. - </para> - - <para><application>Evolution</application> can be started by - selecting <guimenuitem>Evolution</guimenuitem> from - <guisubmenu>SUBMENU</guisubmenu> submenu of the <guimenu>Main - Menu</guimenu>, or by running the command - <command>evolution</command> on the commandline. - </para> - - -</preface> - -<part id="usage"> -<title>Using Evolution</title> - - <partintro> - <para> - As was said before, <application>Evolution</application> can be - used to send and recieve email, manage address and other contact information, - and maintain This section describes basic usage of - <application>Evolution</application> in each of those functions. As with most of Linux, - there's more than one way to do things, and you should pick whichever one strikes you as most - appropriate. - </para> - </partintro> - - - <chapter id="basics"> - <title>Basic usage</title> - <para> - When you first start <application>Evolution</application>, you see - the <interface>Main window</interface>, as shown in - <xref linkend="mainshot">the following figure. - From there, you should select which features you wish to - use by clicking on their icons in the left-hand navigational column. - The Mail features can be accessed by clicking on the <guibutton>Mail</guibutton>, - and likewise for other features. -<!-- ==============Figure=================================== --> - <figure id="mainshot"> - <title>Evolution Main Window</title> - <screenshot> - <screeninfo>Evolution Main Window</screeninfo> - <graphic fileref="SCREENSHOT" format="png" - srccredit="Aaron Weber"> - </graphic> - </screenshot> - </figure> -<!-- ==============End of Figure=================================== --> - </para> - - </chapter> - - <chapter id="mailer"> - <title>The Evolution Mailer</title> - <abstract> - <para> - This chapter covers the use of the Evolution Mailer. - Configuration of the mail client is discussed in <xref linkend="customization">. - If you are already accustomed to other email programs, - you can probably skip the mail sending and checking sections. - The more complex functions, such as filtering, organizing, and searching mail, - have some features that are not found in other email programs, and - even power users may wish to review these sections of the guide. - <!--those function descr's should be xrefs to sections of the chapter--> - </para> - </abstract> - - <sect1 id="mailsending"> - <title>Sending and Recieving Mail</title> - <para> - You can start writing a new email message by selecting <guimenuitem>New Mail</guimenuitem> from - the <guimenu>FilMenu</guimenu>, or by pressing <KeyCombo>NEW-MESSAGE-COMBO</KeyCombo>. - When you do so, the <interface>New Message</interface> window will open, as shown in - <xref linkend="evolution-newmsg">. - - -<!-- ==============Figure=================================== --> - <figure id="evolution-newmsg"> - <title>New Message Window</title> - <screenshot> - <screeninfo>Evolution Main Window</screeninfo> - <graphic fileref="evolution_newmsg" format="png" - srccredit="Aaron Weber"> - </graphic> - </screenshot> - </figure> -<!-- ==============End of Figure=================================== --> - - </para> - - <para> - You can pick recipients in several ways: - The <guilabel>TO:</guilabel> field is for the primary recipients of the message your are going to send. - It is considered bad form to have more than a few email addresses in this form. - </para> - <para> - If you want to send a copy of the message to someone, you may also use the <guilabel>Cc:</guilabel> field. - "Cc" stands for "Carbon Copy"-- Those people will recieve a copy of the message. They will see - the rest of the message list, and are noted as secondary recipients of the message. - </para> - - <para> - If you have a large number of recipients, or if you want to send mail to several people without - telling them that it's gone to multiple people, you should use <guilabel>BCC.</guilabel> BCC stands - for "Blind Carbon Copy". Addresses entered into this field will recieve the message - but the message headers will not see the rest of the recipient list. - </para> - - <para> - Enter a subject into the <guilabel>Subject:</guilabel> field. - - Enter the text of your message into the <guilabel>Message:</guilabel> text area. - </para> - - <para> - If you want to attach a document to your email message, you can do so by - <!--describe process here-->. If the people you are sending a message to - can read HTML mail, you can embed an image into the mail. Otherwise, - it's best to attach images, just like other documents. Be aware that a large - attachment will take a long time to download. - </para> - - - <para> - Click <guibutton>Send</guibutton> or press <KeyCombo>SENDCOMBO</KeyCombo> to send the mail. - </para> - <tip> - <title>Send Now, Send Later</title> - <para> - Evolution will send mail immediately unless you set it to do so otherwise. It also checks for - new mail every time you send mail. If you - want, however, you can queue your messages to be sent at a later time, and also set your - preferences to check mail on a regular basis, and alert you whenever it finds new messages. - I like to use "Send Later" because it gives me a chance change my mind about a message - before it goes out, and I have Evolution set to check my mail every ten minutes, and beep - when I get mail that it thinks isn't spam. - Use the <interface>Mail Preferences</interface> to specify message queue and filter behavior. - Preferences are discussed in <xref linkend="customization">. - </para> - </tip> - </sect1> - - <sect1 id="mail-sorting"> - <title>Organizing Your Mail</title> - - <para> - If you only get a few messages a day, you probably don't need to to sort or organize them. When you get several hundred each day, - and when you want to refer to a message you've recieved six weeks ago, you want a real - organizing system. This section will cover the mail sorting and organization: folders, searches, vFolders, and filters. - <!--those last items should be links--> - - <sect2 id="mail_folders"> - <para> - You can create new folders by selecting <guimenuitem>ITEM</guimenuitem> from the <guimenu>MENU</guimenu>, or by - pressing <KeyCombo>SENDCOMBO</KeyCombo>. Move mail to them by selecting <guimenuitem>ITEM</guimenuitem> from the - <guimenu>MENU</guimenu>, or by pressing <KeyCombo>SENDCOMBO</KeyCombo>. An email message can be in only one folder at a time, - just like real mail in real folders. If you forget where an email is, you can search for it. If you find that you want - an email to be in several places at once, you should consider creating a vFolder, or virtual folder. - <para> - </sect2> - - <sect2 id="mail_searching"> - <para> - Because Evolution automatically creates an index of every email you recieve, it can search through your old - messages and present you with the results in short order. - <!--describe the way one creates a search and so forth.--> - </para> - - <para> - If you find yourself performing a search frequently, you can save it as vFolder. - </para> - </sect2> - - <sect2 id="mail_vFolders"> - <para> - Virtual Folders, or vFolders, are one of the more advanced features of <application>Evolution</application>. If they confuse you, - you don't have to use them. However, if you get a lot of mail, and find yourself referring to messages, looking for old email, - or just living in your email client, you'll probably want to use them. - Basically, a vFolder is a saved search, which you can access the same way you would a normmal folder. - There are several important differences between the two, however, which come from the fact that a conventional - folder actually contains a message, but a virtual folder is really a different view of all your email. This means that - while a message can be in several vFolders, it can be in only one conventional folder. Also, - you cannot add or delete a message from a vFolder, and when you delete a message from a conventional folder, - it will disappear from all your vFolders--a search can't find a deleted message. - </para> - </sect2> - - <example><title>Using vFolders</title> - <para> - I have a vFolder set up for all the mail about a project I'm - working on, and another one for all the mail from my friend Bernie. - If Bernie sends me mail about the project, I can see that message both in the "Bernie" folder and in the "Project" folder. - That's because when I open up the "Bernie" folder, I'm really performing a search for all the mail from Bernie, and when you open the - "Project" folder you're really performing a search for all the mail about the project. That particular message - actually resides in some other folder, - maybe just in my Inbox. I can't delete it from the vFolder, because the vFolder is really a different view of my messages. - When I delete it from - the Inbox, I have also removed it from all my vFolders, because no search can find a deleted message. - <!--this could use a cool picture of the Inbox and 2 vFolders with the message in all 3--> - </para> - </example> - - - <sect2 id="mail_filters"> - <para> - Filters sort your email for you, automatically. You can access the Filter functions of - the email client by <!--BLAH BLAH BLAH-->. - </para> - - <para> - Email starts in your Inbox. As it arrives, it is indexed and filtered from ther. Any email - that does not meet filter action criteria remains in the Inbox. To create a filter, - <!--open the menu somehow-->f you have filters enabled, - </para> - </sect2> - </chapter> - - <chapter id="calendar"> - <title>Using the Calendar</title> - <para>To begin using the calendar, select <guibutton>Calendar</guibutton> - from the main navigational frame. This will cause the calendar component of - <application>Evolution</application> to become active. This is illustrated in - the figure below: -<!-- ==============Figure=================================== --> - <figure id="contact_picture"> - <title>Evolution Contact Manager Window</title> - <screenshot> - <screeninfo>Evolution Contact Manager Window</screeninfo> - <graphic fileref="SCREENSHOT" format="png" - srccredit="ME"> - </graphic> - </screenshot> - </figure> -<!-- ==============End of Figure=================================== --> -</para> - - - - </chapter> - <chapter id="addressbook"> - -</chapter> - -<chapter> -<title>Administration and Large-scale setup</title> -</chapter> - -</part><!--end of part two, Administration and Large-Scale Setup--> - - - <appendix> ... </appendix> - <appendix> ... </appendix> -<index> ... </index> -</book> - - -</chapter> - -<chapter> -<title>Administration and Large-scale setup</title> -</chapter> - -</part><!--end of part two, Administration and Large-Scale Setup--> - - - <appendix> ... </appendix> - <appendix> ... </appendix> -<index> ... </index> -</book> - - - - </chapter> - - -</part> <!--end of part one--> - -<part id="configuration"> -<title>Configuring Evolution</title> - -<chapter> -<title>The Preferences Dialog</title> - - <para> - To change default settings, select - <guimenuitem>Preferences</guimenuitem> command in - <guimenu>Settings</guimenu> menu. This launches the - <interface>Preferences dialog</interface>, shown in <xref - linkend="shot2">. - </para> -<!-- ==============Figure=================================== --> - <figure id="shot2"> - <title>Preferences Dialog</title> - <screenshot> - <screeninfo>Preferences dialog</screeninfo> - <graphic fileref="SCREENSHOT" format="png" - srccredit="ME"> - </graphic> - </screenshot> - </figure> -<!-- ==============End of Figure=================================== --> - -<!--obviously there should be more description here.--> - -</chapter> - -<chapter> -<title>Administration and Large-scale setup</title> -</chapter> - -</part><!--end of part two, Administration and Large-Scale Setup--> - - - -<!-- =============APPENDICES============================= --> - <appendix id="bugs"> - - <title>Known bugs and limitations</title> - <abstract> - <para> - This appendix describes known bugs and limitations of - <application>Evolution</application>. Please - contact the appropriate people if you find one we have not listed, - or if you have a patch to fix one. - <para> - </abstract> - - <para> - The program currently does not work. At all. - </para> - </appendix> - - - -<!-- =============Another Appendix============================= --> - - <appendix id="authors"> - <title>Authors</title> - <para> - <application>Evolution</application> was written by: - - Seth Alves: <email>alves@helixcode.com</email> - Anders Carlsson<email>andersca@helixcode.com</email> - Damon Chaplin:<email>damon@helixcode.com</email> - Clifford R. Conover <email>rusty@zootweb.com</email> - Miguel De Icaza: <email>miguel@helixcode.com</email> - Arturo Espinoza <email>arturo@nucleu.unam.mx</email> - Larry Ewing: <email>lewing@helixcode.com</email> - Bertrand Guiheneuf: <email>bertrand@helixcode.com</email> - Tuomas Kuosmanen: <email>tigert@gimp.org</email> - Christopher J. Lahey: <email>clahey@helixcode.com</email> - Matthew Loper: <email>matt@helixcode.com</email> - Dave Mason <email>dcm@redhat.com</email> - Federico Mena: <email>federico@helixcode.com</email> - Eskil Heyn Olsen<email>deity@eski.dk</email> - Nat Friedman: <email>nat@helixcode.com</email> - Ettore Perazzoli:<email>ettore@helixcode.com</email> - Russell Steinthal: <email>rms39@columbia.edu</email> - Peter Teichman: <email>peter@helixcode.com</email> - Chris Toshok: <email>toshok@helixcode.com</email> - Radek Doulik: <email>rodo@helixcode.com</email> - Dan Winship: <email>winship@helixcode.com</email> - Michael Zucchi: <email>notzed@helixcode.com</email> - -and other dedicated GNOME programmers. -</para> - <para> - The<application>Evolution</application> code owes a great debt to - <application>GNOME-pim</application>, <application>KHTMLW</application> - and the developers of <application>Evolution</application> acknowledge the efforts and contributions of its members. - </para> - - <para> - For more information please visit <application>Evolution</application> <ulink - url="http://www.helixcode.com/apps/evolution.php3" type="http">Web page</ulink>. - Please send all comments, suggestions, and bug reports to the - <ulink url="http://bugs.gnome.org" type="http">GNOME bug - tracking database</ulink>. Instructions for submitting bug reports - can be found on-line at <ulink - url="http://bugs.gnome.org/Reporting.html" type="http"> - http://bugs.gnome.org/Reporting.html</ulink>. If you are using GNOME - 1.1 or later, you can also use command - <command>bug-buddy</command> for submitting bug reports. - </para> - <para> - This manual was written by Aaron Weber - (<email>aaron@helixcode.com</email>) with the help of the application programmers. - Please send all comments - and suggestions regarding the manual to the GNOME Documentation - Project at <email>docs@gnome.org</email>. You can also add your - comments online by using <ulink type="http" - url="http://www.gnome.org/gdp/doctable/">GNOME Documentation - Status Table</ulink>. - </para> - <!-- For translations: uncomment this: - <para> Latin translation was done by ME - (<email>MYNAME@MYADDRESS</email>). Please send all comments - and suggestions regarding this translation to SOMEWHERE. - </para> - --> - </appendix> - - - <appendix> ... </appendix> - <appendix> ... </appendix> -<index> ... </index> -</book> - - diff --git a/help/Camel-Classes b/help/Camel-Classes deleted file mode 100644 index da32d69460..0000000000 --- a/help/Camel-Classes +++ /dev/null @@ -1,24 +0,0 @@ -CamelException -CamelProvider -CamelThreadProxy -GtkObject - + CamelDataWrapper - | + CameStreamDataWrapper - | + CamelMedium - | | + CamelMimePart - | | + CamelMimeBodyPart - | | + CamelMimeMessage - | + CamelMultipart - | + CamelSimpleDataWrapper - + CamelFolder - | + CamelFolderPtProxy - + CamelFolderSummary - + CamelService - | + CamelStore - + CamelSession - + CamelStream - | + CameDataWrapperStream - | + CamelStreamFs - | + CamelStreamBufferedFs - | + CamelStreamMem - + CamelThreadProxy
\ No newline at end of file diff --git a/help/ChangeLog b/help/ChangeLog deleted file mode 100644 index 8561476fd4..0000000000 --- a/help/ChangeLog +++ /dev/null @@ -1,58 +0,0 @@ -2000-04-16 Aaron Weber <aaron@helixcode.com> - - * C/evo_book_0.1.sgml: new file (doc sgml) - - * C/ : New directory for doc sgml & graphics - -2000-03-05 Christopher James Lahey <clahey@helixcode.com> - - * white-papers/widgets/e-table.sgml: Added Miguel to the author - list for ETable. - -2000-03-03 Christopher James Lahey <clahey@helixcode.com> - - * white-papers/widgets/, white-papers/widgets/e-table.sgml: New - doc for the ETable widget. - - * ChangeLog: Created a ChangeLog file for the docs file and - integrated the individual ChangeLogs. - -2000-03-01 Dan Winship <danw@helixcode.com> - - * ibex.sgml: Ibex white paper - -2000-02-29 Federico Mena Quintero <federico@helixcode.com> - - * calendar.sgml: Sections for the calendar user agent and the - calendar client library. - -2000-02-29 Dan Winship <danw@helixcode.com> - - * camel.sgml: Reorg a bit more, make the <PRE> section narrower, - add more references to graphics (the graphics themselves are - still in beta), add a section on CamelStream. - -2000-02-28 Federico Mena Quintero <federico@helixcode.com> - - * calendar.sgml: Section for the personal calendar server. - -2000-02-28 Dan Winship <danw@helixcode.com> - - * camel.sgml: add Bertrand to authors, edit his additions - -2000-02-28 bertrand <bertrand@helixcode.com> - - * camel.sgml: add a blurb about camel offering - uniform interface. needs style and grammar corrections. - Talk about virtual folders. - Talk about lightweight messages - Talk about IMAP. - -2000-02-28 Dan Winship <danw@helixcode.com> - - * camel.sgml: Beginnings of a Camel white paper - -2000-02-25 Federico Mena Quintero <federico@helixcode.com> - - * calendar.sgml: New file for the Evolution calendaring white paper. - diff --git a/help/Design b/help/Design deleted file mode 100644 index 7b7cf6f821..0000000000 --- a/help/Design +++ /dev/null @@ -1,201 +0,0 @@ - -The Evolution Project specification -Miguel de Icaza. - - -* Introduction - - Evolution is a project aiming at providing the free software - community with a professional, high-quality tool for managing - mail, appointments, tasks and other personal information - tools. - - We want to make Evolution a system that addresses our needs - (the free software development community) and we believe that - by addressing our needs, we will provide a system that will - scale in the years to come for other users that are just - starting to use computers and the internet. - - The main objectives of Evolution are to provide these powerful - features, and to make the user interface as pretty and - polished as possible. - - Evolution is a GNOME application and a number of auxiliary - CORBA servers that act as the storage backends. - - Evolution will copy the best user interface bits and the best - ideas and features found on contemporary groupware systems. - -* Evolution internals. - - Evolution can store its information locally (files for mail, - calendar and address book) or on a remote server (imap/pop, - cap, ldap). - - Given the importance of syncing in this modern PDA world, - the Evolution GUI acts as a client to the data repository. - The data repository is a GUI-less CORBA server called Wombat. - - Wombat provides a unified access system to the calendar and - addressbook data (doing mail is a bit hard, so we are leaving - this as a TODO item for now). - - Wombat's CORBA interfaces are notifier-based. This means that - CORBA requests sent to Wombat do not return values - inmediately, but rather than for Wombat requests the user has - to provide a CORBA object that will be notified of what - happened. - - Yes, that sounds hairy. It is actually pretty simple. It - basically means that you submit requests to Wombat, and a - callback is invoked in your code when the request has been - carried away. - - This enables a Palm to sync to the repository without having - the GUI for Evolution running. It also means that volunteers - will be able to write text-based and web-based versions of - Evolution (not me though :-). - -* Evolution as a platform - - Evolution is more than a client for managing the above - information: Evolution is a platform for building groupware - applications that use the above components to get their work done. - - To achieve this Evolution is designed to be scriptable, and it - exports its internals trough CORBA/Bonobo. It is implemented - as a collection of Bonobo containers and Bonobo components. - - There is a clean separation between the views (the user - interface) and the model (the view). The views that we are - writing are GNOME based, and they talk to the Wombat CORBA - server. - - Wombat takes care of notifications to the various clients for - the data. - -* The overall organization - - A bar similar to outlook provides shortcuts for accessing the - various resources managed by Evolution: mail folders, - contacts, tasks, journal entries, notes, messages and other - user-defined destinations. - -* User interface widgets - -** The ETable package - - This package provides a way of displaying and editing tables. - - Tables are displayed based on a TableColumn definition that - defines the layout used for the display. Table Columns can be - nested, and the package does grouping of information displayed - according to the criteria defined there. - - This is used in multiple places troughout evolution: it is - used for the Mail summary display, for the TODO display and - TODO new data entry and for the address book. - - Nesting in the address book can be performed on various - fields. For example, a first level of nesting could be - "Company" and a second level would be "Country" the result is - a 2-level tree that can be collapsed expanded and contains the - information sorted/grouped by those two criteria. - - The user interface for this will be copied from Outlook: the - possibility of adding and removing fields with drag and drop - as well as grouping using drag and drop. - -* The Mail system - -** The Mail sources - - The mail system will support 4 sources of mail: - - POP3 (transfer to a local file). - IMAP - Local mbox format in $MAIL. - Local mbox format that have other delivery points. - - On top of that, it will be possible to browse existing mbox - archives (and possibly other formats in the future, like - Mailbox and Maildir). - -** Storing the mail - - Mail that gets incorporated into the system is stored in mbox - format, and summary files are provided for quick access to the - files. No modifications to the file on disk is performed (I - am not quite sure about this, perhaps we want to add the - status flags and some method for adding metadata to the mail). - - Summary files are rebuilt on demand or rebuild if the mbox - file and the summary file have got out of sync. - - A Metadata system that will enable us to attach information to - a message will have to be designed and implemented (enabling - users to add annotations to mails, and special keywords and - flags in a per-message fashion). - -** Folders - - Michael Zucchi is working on a system that will let users - easily define rules for splitting their incoming mail into - physical folders. - - A further refinement to Folders are Virtual Folders. This - basically provides a powerful search and viewing facility for - mail. It works like this: when a mail is "incorporated" into - Evolution it is scanned and indexed. - - Then users can enter queries into Evolution that will search - the entire database of messages. - -** Virtual folders - - Virtual folders will enable users to read/browse their mail in - new ways: by specifying search criterias, these folders will - contain messages that match the criteria given. - - There is more information about this in the libcamel - directory. - - We will index all headers from a message, and possible the - contents of messages and keep those on a separate file, to - enable users to query their mail database. - -** Mail summary display - - The summary will be displayed using the ETable package, to - enable users to add a number of sorting criteria and various - display methods for the summary view. - - The Outlook methods for displaying will be present on the - system. - - Message threading will be supported in Evolution. - -** Message display engine - - We are going to be using a combination of - libcamel/limime/libjamie to parse messages and render them - into an HTML buffer. - -* The HTML engine - - The GtkHTML engine will be used to display messages, and will - be extended to support a number of features that we require: - internal handling of characters will be based on Unicode - -* The message composer - - Regular features found in composers will be added: connecting - the composer to the address book, support for drag and drop - for including attachments, editing the message, archiving - drafts and archiving messages sent. - - Ettore has been working on adding editing support to the - GtkHTML and he is working currently on a Bonobo component that - will provide a ready-to-use Bonobo control for embedding into - other applications. - diff --git a/help/white-papers/calendar/calendar.sgml b/help/white-papers/calendar/calendar.sgml deleted file mode 100644 index 2cb3132e2b..0000000000 --- a/help/white-papers/calendar/calendar.sgml +++ /dev/null @@ -1,209 +0,0 @@ -<!doctype article PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [ -<!entity Evolution "<application>Evolution</application>"> -<!entity CUA "<acronym>CUA</acronym>"> -<!entity PCS "<acronym>PCS</acronym>"> -<!entity Bonobo "<application>Bonobo</application>"> -<!entity CORBA "<acronym>CORBA</acronym>"> -<!entity GTK "<acronym>GTK+</acronym>"> -]> - -<article class="whitepaper" id="calendar"> - - <artheader> - <title>&Evolution; Calendaring Framework</title> - - <authorgroup> - <author> - <firstname>Federico</firstname> - <surname>Mena Quintero</surname> - <affiliation> - <address> - <email>federico@helixcode.com</email> - </address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>2000</year> - <holder>Helix Code, Inc.</holder> - </copyright> - - <abstract> - <para> - The &Evolution; groupware suite provides a framework for - developing calendaring applications, as well as a graphical - calendar client and a personal calendar server. This white - paper describes the architecture of the &Evolution; - calendaring framework. - </para> - </abstract> - </artheader> - - <!-- Introduction --> - - <sect1 id="introduction"> - <title>Introduction</title> - - <para> - Calendaring is an important part of a groupware suite. A - calendaring framework will allow a user to keep a personal - calendar and have several applications use it. Such - applications could be a graphical calendar client that the user - employs to schedule appointments and keep track of his time, a - <productname>Palm Pilot</productname> synchronization client, or - a simple alarm or reminder utility. A comprehensive calendaring - framework will also allow multiple users to schedule - appointments between each other; for example, a project director - may want to schedule a weekly meeting with the rest of the - project members, or a person who owns a large house may want to - schedule a big party with his friends. The attendees will then - want to reply with messages such as, “I will - attend”, or “I will attend only if the proposed time - is changed”. - </para> - - <para> - The &Evolution; groupware suite provides a framework for - developing calendaring applications, as well as a graphical - calendar client or calendar user agent (&CUA;) and a personal - calendar server (&PCS;). - </para> - - <para> - The following sections explain the basic calendaring framework, - the functions of the calendar user agent and the personal - calendar server, and the relationship between the two. - </para> - </sect1> - - <!-- Personal Calendar Server --> - - <sect1 id="pcs"> - <title>Personal Calendar Server</title> - - <para> - The personal calendar server (&PCS;) provides centralized - management and storage of a user's personal calendar. Multiple - clients can connect to the &PCS; simultaneously to query and - modify the user's calendar in a synchronized fashion. The main - features of the &PCS; are as follows: - </para> - - <formalpara> - <title>Storage</title> - - <para> - The &PCS; is responsible for loading and saving calendars. - Centralizing the loading and saving functionality allows - multiple clients to use the same calendar at the same time - without having to worry about each other. - </para> - </formalpara> - - <formalpara> - <title>Basic Queries</title> - - <para> - The &PCS; provides functions to do basic queries on a - calendar, for example, a client can ask the server for a list - of all the appointments in the calendar, or for all the data - for a specific appointment. - </para> - </formalpara> - - <formalpara> - <title>Recurrence and Alarm Queries</title> - - <para> - Clients can ask the &PCS; for a list of the appointments that - occur within a specified time range; for example a graphical - client that has a per-week view could ask the &PCS; for all - the appointments that occur in a particular week. This - includes multiple occurrences of a single recurring event; for - example, the object for “a 1-hour meeting that occurs on - every Tuesday and Thursday” is represented inside the - &PCS; as a single event with a recurrence rule. Similarly, - clients can ask the &PCS; for a list of events that have - alarms that trigger within a specified time range. - </para> - </formalpara> - - <formalpara> - <title>Notification of Changes</title> - - <para> - This is the most important function of the &PCS;, as it allows - multiple calendar clients to maintain a unified view of the - calendar between the server and themselves. When a client - asks the &PCS; to modify or remove an event, the &PCS; - notifies all the clients that are connected to it about the - change. The policy is that “the server is always - right”; clients can act as dumb views onto the - calendar's data and they will be notified by the &PCS; when - something changes. - </para> - </formalpara> - </sect1> - - <!-- Calenar User Agent --> - - <sect1 id="cua"> - <title>Calendar User Agent</title> - - <para> - A calendar user agent (&CUA;) is a program that lets a user - manipulate a calendar. &Evolution; provides an attractive, - graphical calendar client that communicates with the &Evolution; - personal calendar server. - </para> - - <para> - The &Evolution; calendar client just provides a view onto the - data that is stored and managed by the personal calendar server. - The calendar client does not perform direct manipulations on a - calendar's data; instead it offloads those requests to the - calendar server, which takes care of making the appropriate - modifications in the calendar and then notifies all the clients - about the changes. - </para> - </sect1> - - <!-- Calendar Client Library --> - - <sect1 id="client-lib"> - <title>Calendar Client Library</title> - - <para> - Communication between the personal calendar server and calendar - clients is defined by a set of &Bonobo; &CORBA; interfaces. - Clients can be written by implementing the client-side - <classname>Listener</classname> interface, which defines the - notification callbacks that the PCS uses to inform clients about - changes to the calendar. - </para> - - <para> - As a convenience for >K; programmers, &Evolution; also - includes a library which provides a - <classname>CalClient</classname> class which can be used for - communication with the personal calendar server. Objects of - this class automatically contact the PCS when they are created. - <classname>CalClient</classname> provides functions to request - changes in the calendar, and it also emits signals when it gets - notification about changes from the PCS. This makes it easy and - convenient to write calendar clients for &Evolution; using - >K;. - </para> - - <para> - The implementation of the <classname>CalClient</classname> class - simply wraps the &Evolution; &CORBA; interfaces for calendaring - with a familiar-looking >K; object. Calls to the - <classname>Listener</classname> interface get translated to - signal emissions from the <classname>CalClient</classname>, thus - shielding programmers from the details of the &CORBA; - interfaces. - </para> - </sect1> -</article> diff --git a/help/white-papers/mail/camel.sgml b/help/white-papers/mail/camel.sgml deleted file mode 100644 index a339909f54..0000000000 --- a/help/white-papers/mail/camel.sgml +++ /dev/null @@ -1,339 +0,0 @@ -<!doctype article PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [ -<!entity Evolution "<application>Evolution</application>"> -<!entity Camel "Camel"> -]> - -<article class="whitepaper" id="camel"> - - <artheader> - <title>The &Camel; Messaging Library</title> - - <authorgroup> - <author> - <firstname>Dan</firstname> - <surname>Winship</surname> - <affiliation> - <address> - <email>danw@helixcode.com</email> - </address> - </affiliation> - </author> - - <author> - <firstname>Bertrand</firstname> - <surname>Guiheneuf</surname> - <affiliation> - <address> - <email>bertrand@helixcode.com</email> - </address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>2000</year> - <holder>Helix Code, Inc.</holder> - </copyright> - - </artheader> - - <sect1 id="introduction"> - <title>Introduction</title> - - <para> - &Camel; is a generic messaging library. It is being used as the - back end for the mail component of &Evolution;. The name - "&Camel;" is an acronym; it refers to the fact that the - library is capable of going several days without food or water. - It means : Camel's Acronym Makes Everyone Laugh. - </para> - - <para> - &Camel;'s initial design is heavily based on Sun's - <trademark>JavaMail</trademark> API. It uses the Gtk+ object - system, and many of its classes are direct analags of JavaMail - classes. Its design has also been influenced by the features of - IMAP, and the limitations of the standard UNIX mbox mail store, - which set some of the boundaries on its requirements and - extensibility. - </para> - - <para> - &Camel; sees all message repositories as stores containing - folders. These folders in turn contain the messages the client - actually accesses. The use of such a unified interface allows - the client applications to be very extensible. &Camel; includes - an external provider mechanism which allows applications to - dynamically load and use protocols which were not available when - the application was initially written. - </para> - - <para> - The abstract store/folder mechanism is a powerful and versatile - way of accessing messages. No particular asumptions are made on - the client side, thus allowing new ways of managing the - messages. For example, the messages stored in the folders don't - necessarily have to share some common physical location. The - folder can be a purely virtual folder, containing only - references to the actual messages. This is used by the "vFolder" - provider, which allows you select messages meeting particular - criteria and deal with them as a group. - </para> - - <para> - In addition to these possibilities, &Camel; has full MIME - support. &Camel; MIME messages are lightweight objects - representing the MIME skeleton of the actual message. The data - contained in the subparts are never stored in memory except when - they are actually needed. The application, when accessing the - various MIME objects contained in the message (text parts, - attachments, embedded binary objects ...) asks &Camel; for a - stream that it can read data from. This scheme is particularly - useful with the IMAP provider. IMAP has strong MIME support - built-in, which allows &Camel; to download only the parts of - messages that it actually needs: attachments need not be - downloaded until they are viewed, and unnecessary - "multipart/alternative" parts will never be read off the server. - </para> - </sect1> - - <sect1 id="overview"> - <title>Overview</title> - - <graphic format="gif" fileref="camel"></graphic> - - <para> - To begin using &Camel;, an application first creates a - <classname>CamelSession</classname> object. This object is used - to store application defaults, and to coordinate communication - between providers and the application. - </para> - - <para> - A <classname>CamelProvider</classname> is a dynamically-loadable - module that provides functionality associated with a specific - service. Examples of providers are IMAP and SMTP. Providers - include subclasses of the various other &Camel; classes for - accessing and manipulating messages. - </para> - - <para> - <classname>CamelService</classname> is an abstract class for - describing a connection to a local or remote service. It - currently has two subclasses: <classname>CamelStore</classname>, - for services that store messages (such as IMAP servers and mbox - files), and <classname>CamelTransport</classname>, for services - that deliver messages (such as SMTP, or a local MTA). A provider - could also be both a store and a transport, as in the case of - NNTP. - </para> - - <para> - A <classname>CamelStore</classname> contains some number of - <classname>CamelFolder</classname> objects, which in turn - contain messages. A <classname>CamelFolder</classname> provides - a <classname>CamelFolderSummary</classname> object, which - includes details about the subject, date, and sender of each - message in the folder. The folder also includes the messages - themselves, as subclasses of <classname>CamelMedium</classname>. - </para> - - <para> - Email messages are represented by the - <classname>CamelMimeMessage</classname> class, a subclass of - <classname>CamelMedium</classname>. This class includes - operations for accessing RFC822 and MIME headers, accessing - subparts of MIME messages, encoding and decoding Base64 and - Quoted-Printable, etc. - </para> - - <para> - <classname>CamelTransport</classname> includes methods for - delivering messages. While the abstract - <function>CamelTransport::send</function> method takes a - <classname>CamelMedium</classname>, its subclasses may only be - able to deliver messages of specific - <classname>CamelMedium</classname> subclasses. For instance, - <classname>CamelSendmailTransport</classname> requires a - <classname>CamelMimeMessage</classname>, because it needs a - message that includes a "To:" header. A hypothetical - <classname>CamelNNTPTransport</classname> would need a - <classname>CamelNewsMessage</classname>, which would have a - "Newsgroups:" header. - </para> - - <para> - The content of messages are referred to using - <classname>CamelStream</classname> and its subclasses. In the - case of an mbox-based store, the - <classname>CamelStream</classname> would abstract the operation - of reading the correct section of the mbox file. For IMAP, - reading off the <classname>CamelStream</classname> might result - in commands being issued to the remote IMAP server and data - being read off a socket. - </para> - - <para> - The final major class in &Camel; is - <classname>CamelException</classname>, which is used to - propagate information about errors. Many methods take a - <classname>CamelException</classname> as an argument, which the - caller can then check if an error occurs. It includes both a - numeric error code which can be interpreted by the program, and - a text error message that can be displayed to the user. - </para> - </sect1> - - <sect1 id="classes"> - <title>Major Subcomponents</title> - - <sect2 id="store"> - <title>The Message Store</title> - - <para> - A <classname>CamelStore</classname> inherits the ability to - connect and authenticate to a service from its parent class, - <classname>CamelService</classname>. It then adds the ability - to retrieve folders. A store must contain at least one folder, - which can be retrieved with - <function>CamelStore::get_default_folder</function>. There are - also methods to retrieve the "top-level" folder (for - hieararchical stores), and to retrieve an arbitrary folder by - name. - </para> - - <para> - All <classname>CamelFolder</classname>s must implement certain - core operations, most notably generating a summary and - retrieving and deleting messages. A - <classname>CamelFolder</classname> must assign a permanently - unique identifier to each message it contains. Messages can - then be retrieved via - <function>CamelFolder::get_message_by_uid</function>. Alternately, - within a single mail-reading session, messages can be referred - to by their linear position within the store using - <function>CamelFolder::get_message_by_number</function>. - </para> - - <para> - Folders must also implement the - <function>get_parent_folder</function> and - <function>list_subfolders</function> methods. For stores that - don't allow multiple folders, they would return NULL and an - empty list, respectively. Stores that do allow multiple - folders will also define methods for creating and deleting - folders, and for moving messages between them (assuming the - folders are writable). - </para> - - <para> - Folders that support searching can define the - <function>search_by_expression</function> method. For mbox - folders, this is implemented by indexing the messages with the - ibex library and using that to search them later. For IMAP - folders, this uses the IMAP SEARCH command. Other folder types - might not be able to implement this functionality, in which - case users would not be able to do full-content searches on - them. - </para> - </sect2> - - <sect2 id="messages"> - <title>Messages</title> - - <para> - As mentioned before, messages are represented by subclasses of - <classname>CamelMedium</classname>. - <classname>CamelMedium</classname> itself is a subclass of - <classname>CamelDataWrapper</classname>, a generic class for - connecting a typed data source to a data sink. - <classname>CamelMedium</classname> adds the concept of message - headers versus message body. - (<classname>CamelDataWrapper</classname> has one other - important subclass, <classname>CamelMultipart</classname>, - which is used to provide separate access to the multiple - independent parts of a multipart MIME type.) - <classname>CamelMedium</classname>'s subclasses provide more - specialized handling of various headers: - <classname>CamelMimePart</classname> adds special handling for - the &ldquot;Content-*&rdquot; headers in MIME messages, and - its subclass <classname>CamelMimeMessage</classname> adds - handling for the RFC822 headers. - </para> - - <graphic format="gif" fileref="mimemessage"></graphic> - - <para> - Consider a message with two parts: a text part (in both plain - text and HTML), and an attached image: - - <programlisting> - - From: Dan Winship <danw@helixcode.com> - To: Matt Loper <matt@helixcode.com> - Subject: the Camel white paper - MIME-Version: 1.0 - Content-Type: multipart/mixed; - boundary="jhTYrnsRrdhDFGa" - - This is a multi-part message in MIME format. - --jhTYrnsRrdhDFGa - Content-Type: multipart/alternative; - boundary="sFSenbAFDSgDfg" - - --sFSenbAFDSgDfg - Content-Type: text/plain - - Hey, Matt - - Check out this graphic... - - -- Dan - - --sFSenbAFDSgDfg - Content-Type: text/html - - Hey, Matt<br> - <br> - Check out this graphic...<br> - <br> - -- Dan<br> - <br> - --sFSenbAFDSgDfg-- - - --jhTYrnsRrdhDFGa - Content-Type: image/png - Content-Transfer-Encoding: base64 - - F4JLw0ORrkRa8AwAMQJLAaI3UDIGsco9RAaB92... - --jhTYrnsRrdhDFGa-- - </programlisting> - - <para> - In &Camel;, this would be represented as follows: - </para> - - <graphic fileref="samplemsg"></graphic> - </sect2> - - <sect2 id="streams"> - <title>Streams</title> - - <para> - Streams are a generic data transport layer. Two basic stream - classes are <classname>CamelStreamFs</classname>, for - reading and writing files, and - <classname>CamelStreamMem</classname>, for reading from and - writing to objects that are already in memory. - </para> - - <para> - Streams can also be chained together. So a CamelMimePart - containing base64-encoded data can filter its output through - a CamelStreamB64. Other parts of the application that want - to read its data will never need to even realize that the - original data was encoded. - </para> - </sect2> - -</article> diff --git a/help/white-papers/mail/ibex.sgml b/help/white-papers/mail/ibex.sgml deleted file mode 100644 index dcb8f5ca4b..0000000000 --- a/help/white-papers/mail/ibex.sgml +++ /dev/null @@ -1,158 +0,0 @@ -<!doctype article PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [ -<!entity Evolution "<application>Evolution</application>"> -<!entity Camel "Camel"> -<!entity Ibex "Ibex"> -]> - -<article class="whitepaper" id="ibex"> - - <artheader> - <title>Ibex: an Indexing System</title> - - <authorgroup> - <author> - <firstname>Dan</firstname> - <surname>Winship</surname> - <affiliation> - <address> - <email>danw@helixcode.com</email> - </address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>2000</year> - <holder>Helix Code, Inc.</holder> - </copyright> - - </artheader> - - <sect1 id="introduction"> - <title>Introduction</title> - - <para> - &Ibex; is a library for text indexing. It is being used by - &Camel; to allow it to quickly search locally-stored messages, - either because the user is looking for a specific piece of text, - or because the application is contructing a vFolder or filtering - incoming mail. - </para> - </sect1> - - <sect1 id="goals"> - <title>Design Goals and Requirements for Ibex</title> - - <para> - The design of &Ibex; is based on a number of requirements. - - <itemizedlist> - <listitem> - <para> - First, obviously, it must be fast. In particular, searching - the index must be appreciably faster than searching through - the messages themselves, and constructing and maintaining - the index must not take a noticeable amount of time. - </para> - </listitem> - - <listitem> - <para> - The indexes must not take up too much space. Many users have - limited filesystem quotas on the systems where they read - their mail, and even users who read mail on private machines - have to worry about running out of space on their disks. The - indexes should be able to do their job without taking up so - much space that the user decides he would be better off - without them. - </para> - - <para> - Another aspect of this problem is that the system as a whole - must be clever about what it does and does not index: - accidentally indexing a "text" mail message containing - uuencoded, BinHexed, or PGP-encrypted data will drastically - affect the size of the index file. Either the caller or the - indexer itself has to avoid trying to index these sorts of - things. - </para> - </listitem> - - <listitem> - <para> - The indexing system must allow data to be added to the index - incrementally, so that new messages can be added to the - index (and deleted messages can be removed from it) without - having to re-scan all existing messages. - </para> - </listitem> - - <listitem> - <para> - It must allow the calling application to explain the - structure of the data however it wants to, rather than - requiring that the unit of indexing be individual files. - This way, &Camel; can index a single mbox-format file and - treat it as multiple messages. - </para> - </listitem> - - <listitem> - <para> - It must support non-ASCII text, given that many people send - and receive non-English email, and even people who only - speak English may receive email from people whose names - cannot be written in the US-ASCII character set. - </para> - </listitem> - </itemizedlist> - - <para> - While there are a number of existing indexing systems, none of - them met all (or even most) of our requirements. - </para> - </sect1> - - <sect1 id="implementation"> - <title>The Implementation</title> - - <para> - &Ibex; is still young, and many of the details of the current - implementation are not yet finalized. - </para> - - <para> - With the current index file format, 13 megabytes of Info files - can be indexed into a 371 kilobyte index file—a bit under - 3% of the original size. This is reasonable, but making it - smaller would be nice. (The file format includes some simple - compression, but <application>gzip</application> can compress an - index file to about half its size, so we can clearly do better.) - </para> - - <para> - The implementation has been profiled and optimized for speed to - some degree. But, it has so far only been run on a 500MHz - Pentium III system with very fast disks, so we have no solid - benchmarks. - </para> - - <para> - Further optimization (of both the file format and the in-memory - data structures) awaits seeing how the library is most easily - used by &Evolution;: if the indexes are likely to be kept in - memory for long periods of time, the in-memory data structures - need to be kept small, but the reading and writing operations - can be slow. On the other hand, if the indexes will only be - opened when they are needed, reading and writing must be fast, - and memory usage is less critical. - </para> - - <para> - Of course, to be useful for other applications that have - indexing needs, the library should provide several options, so - that each application can use the library in the way that is - most suited for its needs. - </para> - </sect1> -</article> diff --git a/help/white-papers/widgets/e-table.sgml b/help/white-papers/widgets/e-table.sgml deleted file mode 100644 index 5ff4faf2ae..0000000000 --- a/help/white-papers/widgets/e-table.sgml +++ /dev/null @@ -1,279 +0,0 @@ -<!doctype article PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [ -<!entity Evolution "<application>Evolution</application>"> -<!entity ETable "<classname>ETable</classname>"> -<!entity ETableModel "<classname>ETableModel</classname>"> -<!entity ETableSimple "<classname>ETableSimple</classname>"> -<!entity ETableHeader "<classname>ETableHeader</classname>"> -<!entity ETableSpecification "<classname>ETableSpecification</classname>"> -<!entity ETableCol "<classname>ETableCol</classname>"> -]> - -<article class="whitepaper" id="e-table"> - - <artheader> - <title>The ETable Widget</title> - - <authorgroup> - <author> - <firstname>Chris</firstname> - <surname>Lahey</surname> - <affiliation> - <address> - <email>clahey@helixcode.com</email> - </address> - </affiliation> - </author> - <author> - <firstname>Miguel</firstname> - <surname>de Icaza</surname> - <affiliation> - <address> - <email>miguel@helixcode.com</email> - </address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>2000</year> - <holder>Helix Code, Inc.</holder> - </copyright> - - </artheader> - - <sect1 id="introduction"> - <title>Introduction</title> - - <para> - &ETable; is a table widget on steroids. It is intended to provide - all the table functionality needed throughout &Evolution;, and - hopefully be general purpose enough to be used in other projects. - </para> - - <para> - &ETable; provides a lot of interactive control over the data in the - table. Without any work from the programmer, &ETable; provides - rearrangeable columns and editable data. When finished, &ETable; will - also provide, again with no programmer intervention, easy interactive - sorting and grouping. - </para> - - <para> - &ETable; gives you a great deal of functionality, flexibility, and - power. Most of this power is internal to the widget, but some of - the flexibility requires a bit of work by the programmer. - However, once you learn it, &ETable; is not very hard at all to - use. - </para> - - <para> - &ETable;'s power comes from the fact that it is fully - model/view/controller based. Various models are involved into - the process of rendering the information, and various views are - provided. The programmer has a wide range of options: from the - most finely hand-tuned table to a generic all-encompasing widget - that takes over most of tasks. It is up to the programmer: he - can use the simple to use &ETable; widget that takes care of - everything in a generic way, or he can use the various - components to roll his own tabular display. - </para> - - <para> - &ETable; ships with a standard set of information renderers: - strings, bitmaps, toggle-buttons, check-boxes, and multi-line - strings. But the programmer can write and implement his own - renderer for his information. This means that by default - &ETable; provides the basic display facilities that programmers - required, but they offer the programmer a complete freedom to - incorporate new cell renderers. - </para> - - </sect1> - - <sect1 id="model"> - <title>ETableModel</title> - - <para> - The data back end for the &ETable; is an &ETableModel;. The - &ETableModel is an abstract interface that acts as the - information repository for the various &ETable components. - </para> - - <para> - To use &ETable; you have to create a subclass of the abstract - &ETableModel; class. However, to save you the work of defining - a new <classname>GtkClass</classname> every time you use - &ETable, there is a predefined subclass of &ETableModel; called - &ETableSimple; which simply takes a list of function callbacks - to perform the various operations. - </para> - - </sect1> - - <sect1 id="columns"> - <title>Columns</title> - - <para> - There are two different meanings to the word "column". The first - is the model column (defined by the &ETableCol: object). A model - column describes how it maps to the column in the &ETableModel; - as well as containing information about its properties (name, - resizability, resize dimensions, and a renderer for this - specific columns). - </para> - - <para> - &ETable; distinguishes between a model column index, and a view - column index. The former reflects the column in which the data - is stored in the &ETableModel; The later represents the actual - location at which the column is being displayed in the screen. - </para> - - <para> - Each view column index corresponds to a specific model column, - though a model column may have any number of view columns - associated with it (including zero). For example the same - column might be rendered twice, or the data from one column - could be used to display different bits of information - </para> - - <para> - The view column does not necessarily depend on only one model - column. In some cases, the view column renderer can be given a - reference to another model column to get extra information about - its display. For example, a mail program could display deleted - messages with a line through them by creating a model column - with no corresponding view column that told whether or not the - message is deleted, and then having the text column - strikethrough the display if the invisible column had a value - corresponding to "deleted". - </para> - - <para> - The view column also specifies a few other pieces of - information. One piece of information is the renderer. &ETable; - provides a number of renderers to choose from, or you can write - your own. Currently, there are renderers for text, image sets, - and checkboxes. - </para> - - <para> - The view column also includes information about the header. - There are two types of headers: text, and pixbuf. The first - allows you to specify a string which is rendered in the header. - The second allows you to specify an image to copy into the - header. - </para> - </sect1> - - <sect1 id="header"> - <title>Header</title> - - <para> - The &ETableHeader; represents the header information for the - table. The &ETableHeader; is used in two different ways. The - first is the in the <structfield>full_header</structfield> - element of an &ETable;. This is the list of possible columns in - the view. You add each of your columns to this &ETableHeader; - and then pass it into the &ETable;. - </para> - - <para> - The second use is completely internal. &ETable; uses another - &ETableHeader; to store the actual displayed columns. Many of - the &ETableHeader; functions are for this purpose. The only - functions that users of the library should need to use are - <function>e_table_header_new</function> and - <function>e_table_header_add_col</function>. - </para> - </sect1> - - <sect1 id="layout"> - <title>Layout Specification</title> - - <para> - &ETable; uses an &ETableSpecification; to layout the columns of - the widget. The &ETableSpecification; is specified as XML data - passed into the &ETable; as a string. - </para> - - <para> - The most powerful part of the &ETableSpecification; is that when - finished, &ETable; will allow you to get a copy of an - &ETableSpecification; that describes the current view of the - tree. This allows the developer to save the current view so that - next time the user opens this table, they find it in exactly the - state that they left it. - </para> - - <para> - The XML specification allows for a number of things. First, it - allows you to pick a set of default columns to be shown. Thus, - even if you had hundreds of pieces of data, you could choose to - only display a few that fit on the screen by default. - </para> - - <para> - The second major thing that the &ETableSpecification; allows you - to specify is the column grouping and sorting. &ETable; has a - powerful mechanism for allowing the user to choose columns to - group by, thus allowing multiple columns of sorting, as well as - visual grouping of similar elements and interactive selection of - what data to display. - </para> - - <para> - The grouping in &ETableSpecification; is specified as a - hierarchy of columns to group by. Each level of the hierarchy - lets you sort by a particular column, either ascending or - descending. All levels except the last cause the canvas to group - by the given column. - </para> - - <para> - An example &ETableSpecification; follows. - </para> - - <programlisting> - <ETableSpecification> - <columns-shown frozen_columns="2"> - <column> 0 </column> - <column> 1 </column> - <column> 2 </column> - <column> 3 </column> - <column> 4 </column> - </columns-shown> - <grouping> - <group column="3" ascending="1"> - <group column="4" ascending="0"> - <leaf column="2" ascending="1"/> - </group> - </group> - </grouping> - </ETableSpecification> - </programlisting> - - <para> - This example has 5 columns which are initially in order. It has - 2 levels of grouping. The first is grouped by the 4th column - (all indexes are 0 based) and sorts those groups in ascending - order. Inside those groups, the data is grouped by the fifth - column and sorted in descending order of the fifth column. - Finally, the data in those groups is sorted by the third column - in ascending order. Due to the "frozen_columns" attribute on the - columns-shown element, the user will not be - able to rearrange the first two columns. They will always be the - first two. - </para> - </sect1> - - <sect1 id="conclusion"> - <title>Conclusion</title> - - <para> - All in all, &ETable; is a very powerful widget. Once you learn - to use it, you have access to a vast amount of power requiring a - comparatively small amount of work. - </para> - </sect1> -</article> |