From 01221de72a50d88eae12e08a5879c5130bd10314 Mon Sep 17 00:00:00 2001 From: Kjartan Maraas Date: Thu, 16 Aug 2001 17:18:11 +0000 Subject: Here go the white-papers svn path=/trunk/; revision=12092 --- help/white-papers/calendar/calendar.sgml | 209 ------------------ help/white-papers/mail/camel.sgml | 356 ------------------------------- help/white-papers/mail/ibex.sgml | 158 -------------- help/white-papers/widgets/e-table.sgml | 279 ------------------------ 4 files changed, 1002 deletions(-) delete mode 100644 help/white-papers/calendar/calendar.sgml delete mode 100644 help/white-papers/mail/camel.sgml delete mode 100644 help/white-papers/mail/ibex.sgml delete mode 100644 help/white-papers/widgets/e-table.sgml 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 @@ -Evolution"> -CUA"> -PCS"> -Bonobo"> -CORBA"> -GTK+"> -]> - -
- - - &Evolution; Calendaring Framework - - - - Federico - Mena Quintero - -
- federico@helixcode.com -
- - - - - - 2000 - Helix Code, Inc. - - - - - 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. - - - - - - - - Introduction - - - 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 - Palm Pilot 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”. - - - - 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;). - - - - 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. - - - - - - - Personal Calendar Server - - - 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: - - - - Storage - - - 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. - - - - - Basic Queries - - - 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. - - - - - Recurrence and Alarm Queries - - - 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. - - - - - Notification of Changes - - - 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. - - - - - - - - Calendar User Agent - - - 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. - - - - 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. - - - - - - - Calendar Client Library - - - 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 - Listener interface, which defines the - notification callbacks that the PCS uses to inform clients about - changes to the calendar. - - - - As a convenience for >K; programmers, &Evolution; also - includes a library which provides a - CalClient class which can be used for - communication with the personal calendar server. Objects of - this class automatically contact the PCS when they are created. - CalClient 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;. - - - - The implementation of the CalClient class - simply wraps the &Evolution; &CORBA; interfaces for calendaring - with a familiar-looking >K; object. Calls to the - Listener interface get translated to - signal emissions from the CalClient, thus - shielding programmers from the details of the &CORBA; - interfaces. - - -
diff --git a/help/white-papers/mail/camel.sgml b/help/white-papers/mail/camel.sgml deleted file mode 100644 index 5f5ea27a98..0000000000 --- a/help/white-papers/mail/camel.sgml +++ /dev/null @@ -1,356 +0,0 @@ -Evolution"> - -]> - -
- - - The &Camel; Messaging Library - - - - Jeffrey - Stedfast - -
- fejj@helixcode.com -
- - - - - Michael - Zucchi - -
- notzed@helixcode.com -
- - - - - Dan - Winship - -
- danw@helixcode.com -
- - - - - Bertrand - Guiheneuf - -
- bertrand@helixcode.com -
- - - - - - 2000, 2001 - Ximian, Inc. - - - - - - Introduction - - - &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. - - - - &Camel;'s initial design is heavily based on Sun's - JavaMail 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. - - - - &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. - - - - 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. - - - - 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. - - - - - Overview - - - - - To begin using &Camel;, an application first creates subclassed - CamelSession object. This object is used - to store application defaults, and to coordinate communication - between providers and the application. - - - - A CamelProvider is a dynamically-loadable - module that provides functionality associated with a specific - service. Examples of providers are POP, IMAP and SMTP. Providers - include subclasses of the various other &Camel; classes for - accessing and manipulating messages. - - - - CamelService is an abstract class for - describing a connection to a local or remote service. It - currently has two subclasses: CamelStore, - for services that store messages (such as IMAP servers and mbox - files), and CamelTransport, 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. - - - - A CamelStore contains some number of - CamelFolder objects, which in turn - contain messages. A CamelFolder provides - a CamelFolderSummary 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 CamelMedium. - - - - Email messages are represented by the - CamelMimeMessage class, a subclass of - CamelMedium. This class includes - operations for accessing RFC822 and MIME headers, accessing - subparts of MIME messages, encoding and decoding Base64 and - Quoted-Printable, etc. - - - - CamelTransport includes methods for - delivering messages. While the abstract - CamelTransport::send method takes a - CamelMedium, its subclasses may only be - able to deliver messages of specific - CamelMedium subclasses. For instance, - CamelSendmailTransport requires a - CamelMimeMessage, because it needs a - message that includes a "To:" header. A hypothetical - CamelNNTPTransport would need a - CamelNewsMessage, which would have a - "Newsgroups:" header. - - - - The content of messages are referred to using - CamelStream and its subclasses. In the - case of an mbox-based store, the - CamelStream would abstract the operation - of reading the correct section of the mbox file. For IMAP, - reading off the CamelStream might result - in commands being issued to the remote IMAP server and data - being read off a socket. - - - - The final major class in &Camel; is - CamelException, which is used to - propagate information about errors. Many methods take a - CamelException 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. - - - - - Major Subcomponents - - - The Message Store - - - A CamelStore inherits the ability to - connect and authenticate to a service from its parent class, - CamelService. It then adds the ability - to retrieve folders. A store must contain at least one folder, - which can be retrieved with - CamelStore::get_default_folder. There are - also methods to retrieve the "top-level" folder (for - hieararchical stores), and to retrieve an arbitrary folder by - name. - - - - All CamelFolders must implement certain - core operations, most notably generating a summary and - retrieving and deleting messages. A - CamelFolder must assign a permanently - unique identifier to each message it contains. Messages can - then be retrieved via - CamelFolder::get_message. - - - - Folders must also implement the - get_parent_folder and - list_subfolders 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). - - - - Folders that support searching can define the - search_by_expression 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. - - - - - Messages - - - As mentioned before, messages are represented by subclasses of - CamelMedium. - CamelMedium itself is a subclass of - CamelDataWrapper, a generic class for - connecting a typed data source to a data sink. - CamelMedium adds the concept of message - headers versus message body. - (CamelDataWrapper has one other - important subclass, CamelMultipart, - which is used to provide separate access to the multiple - independent parts of a multipart MIME type.) - CamelMedium's subclasses provide more - specialized handling of various headers: - CamelMimePart adds special handling for - the &ldquot;Content-*&rdquot; headers in MIME messages, and - its subclass CamelMimeMessage adds - handling for the RFC822 headers. - - - - - - Consider a message with two parts: a text part (in both plain - text and HTML), and an attached image: - - - - 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-- - - - - In &Camel;, this would be represented as follows: - - - - - - - Streams - - - Streams are a generic data transport layer. Two basic stream - classes are CamelStreamFs, for - reading and writing files, and - CamelStreamMem, for reading from and - writing to objects that are already in memory. - - - - Streams can also be filtered. So a CamelMimePart - containing base64-encoded data can filter its output through - CamelMimeFilterBasic. Other parts of the application that want - to read its data will never need to even realize that the - original data was encoded. - - - -
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 @@ -Evolution"> - - -]> - -
- - - Ibex: an Indexing System - - - - Dan - Winship - -
- danw@helixcode.com -
- - - - - - 2000 - Helix Code, Inc. - - - - - - Introduction - - - &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. - - - - - Design Goals and Requirements for Ibex - - - The design of &Ibex; is based on a number of requirements. - - - - - 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. - - - - - - 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. - - - - 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. - - - - - - 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. - - - - - - 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. - - - - - - 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. - - - - - - While there are a number of existing indexing systems, none of - them met all (or even most) of our requirements. - - - - - The Implementation - - - &Ibex; is still young, and many of the details of the current - implementation are not yet finalized. - - - - 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 gzip can compress an - index file to about half its size, so we can clearly do better.) - - - - 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. - - - - 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. - - - - 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. - - -
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 @@ -Evolution"> -ETable"> -ETableModel"> -ETableSimple"> -ETableHeader"> -ETableSpecification"> -ETableCol"> -]> - -
- - - The ETable Widget - - - - Chris - Lahey - -
- clahey@helixcode.com -
- - - - Miguel - de Icaza - -
- miguel@helixcode.com -
- - - - - - 2000 - Helix Code, Inc. - - - - - - Introduction - - - &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. - - - - &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. - - - - &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. - - - - &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. - - - - &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. - - - - - - ETableModel - - - 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. - - - - To use &ETable; you have to create a subclass of the abstract - &ETableModel; class. However, to save you the work of defining - a new GtkClass 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. - - - - - - Columns - - - 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). - - - - &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. - - - - 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 - - - - 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". - - - - 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. - - - - 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. - - - - - Header - - - The &ETableHeader; represents the header information for the - table. The &ETableHeader; is used in two different ways. The - first is the in the full_header - 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;. - - - - 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 - e_table_header_new and - e_table_header_add_col. - - - - - Layout Specification - - - &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. - - - - 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. - - - - 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. - - - - 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. - - - - 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. - - - - An example &ETableSpecification; follows. - - - - <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> - - - - 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. - - - - - Conclusion - - - 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. - - -
-- cgit