Kupfer internals
================

This document is a Work in progress.

If you have Questions, just fire them away directly to me,
Ulrik Sverdrup <ulrik.sverdrup@gmail.com>

Kupfer's architecture is built around objects that can be acted on by
actions. Kupfer's basic concept for understanding objects is in
kupfer/objects.py. The basic building blocks are

KupferObject
------------

base class for basic user-visible constructs, this defines:

* A way to get the object's name
* A way to get the object's icon

This is the base object for the following four very important base
classes:

* Leaf
* Action
* Source
* TextSource

Below follows a summary. For complete information, you should read
kupfer's python interface documentation: go to the directory containing
the kupfer module and do:

$ python
>>> import kupfer.main
>>> import kupfer.objects
>>> help(kupfer.objects.KupferObject)
>>> help(kupfer.objects.Leaf)
>>> help(kupfer.objects.Action)
>>> help(kupfer.objects.Source)


Leaf
----

this represents an object that the user will want to summon and
act on. An example is a file, an application, a window or a Free-text
query (TextLeaf).

This defines, in addition to KupferObject:

* Leaf.object is the represented object, is
implementation-specific
* A way to get the default actions for this type
* __hash__ and __eq__ so that equivalents are recognized
* has_content() and content_source() to find out if objects contain
anything, like for example folders do

Action
------

represents and action on a Leaf, for example Show() that will open with
default viewer.

This defines, in addition to KupferObject:

* activate(leaf, obj) to act on a leaf, with optional indirect object
* is_factory if the action returns content, returns a collection of
new items.
* item_type: which items action applies to (in plugins)
* require_object: Wheter this action uses an indirect object; if it
does, some more methods have to define which items

Source
------

The Source understands specific data and delivers Leaves for it. For example
DirectorySource, that will give FileLeaves for contents of a directory.

This defines, in addition to KupferObject:

* __hash__ and __eq__ so that equivalents are recognized
* get_items That subclasses should define to return its items
* is_dynamic If there should be no caching (usually there should be)
* get_leaf_repr How to represent the source in a list, For example the
DirectorySource is represented by a FileLeaf for the directory
* provides To define which Leaf types it may contain

TextSource
----------

A text source returns items for a given text string

* get_item produce items for given string
* provides To define which Leaf types it may provide

Strings
-------

Kupfer deals with PyGTK a lot, which always returns UTF-8-encoded
strings (almost always). However Kupfer works internally with unicode
strings; only then does slicing, lowercasing etc work across other than
ascii charsets.
Kupfer accepts UTF-8-encoded strings as well as unicode
objects for the most parts, but all internals should be unicode. Note
that the gettext _() will return a unicode string.

