Mindwrapper API

Version 0.3.4
October 2004

Contents
Introduction
- Mindwrapper is an object-oriented application development framework that relies heavily on both composition and inheritance hierarchies. Mindwrapper itself exhibits a rich inheritance structure, which the user-developer extends by routinely subclassing the public Mindwrapper classes that make up the API. At the base of this hierarchy is the Item class. Every structural object in a Mindwrapper application is an item. In the abstraction layer each item is an instance of the Model subclass, and in the presentation layer each item is an instance of the Presenter subclass. These two layers make up the so called abstraction-presentation (AP) or model-view-presenter (MVP) framework. The only Mindwrapper classes not derived from Item are: (1) Transaction with its subclasses and (2) the Application class at the top of the composition hierarchy.
  
  The composition of a Mindwrapper application is defined by the user-developer using the assemble-add notation. Each composite class has a concrete add() method, and an abstract assemble() method that must be implemented, primarily by calling self.add(...), to define the composition at design time. The syntax for the abstraction layer and the presentation layer is essentially identical.
  
  Many of the public methods described in the API are primarily for testing purposes. The user-developer does not usually need to invoke these methods, which are called from other objects or methods in the process of instantiating the application. This makes for a more declarative style of programming, as opposed to imperative style.
  
  Version 0.3 is an "unstable" version, meaning that the API is subject to change. Once version 0.4 is released, the public terms and their semantics are guaranteed not to change for any 0.4.n micro-version. Many public terms are not needed by the user-developer, but are made public for testing purposed. Public terms commonly invoked by the user-developer are considered keywords, some of which are abstract to be defined at design-time. Keywords also include properties. Named parameters that are more typically supplied as ~~positional~~ arguments are currently considered public terms but may not be in the future.

Item Class

Item(object):
- Item is an abstract class, the base class for Model in the abstraction layer, and Presenter in the presentation layer. Every object in a Mindwrapper application (except for the application object itself) is either an item or a transaction between items.
- specifiers
  - For any subclass of Item, class attributes are specifiers . The base class defines one specifier:
  - refs = []
    - This specifier is a list of references to external items needed by the item. If given as a class attribute, this list contains only classes. If provided as an instance specifier via __init__(), the list may contain either item classes or instances or both. During instantiation, instances of the external items specified by class are created at the same time.
- __init__(self, parent=None, name='', *references, **specifiers)
  - The initializer generally requires two positional arguments for parent and name. Additional positional arguments are collected as references to external items. Keyword arguments are collected as specifiers.
  - ~~parent~~
    - The parent item is provided by the add() method of the container item (the parent). For testing purposes, however, the parent can be passed to the initializer directly. The default is None.
  - ~~name~~
    - The name string is provided by the add() method of the parent. For testing purposes, however, the name can be passed to the initializer directly. The default is an empty string, ''.
  - *references
    - Positional arguments other than parent and name are assumed to be references to external items necessary for an instance of the subclass of item to function properly. For any such exernal item, if a particular instance is not known at any particular stage, the class of the item may be passed here.
  - **specifiers
    - Keyword arguments are specifiers for this item (instance). In this class and all subclasses, the API for instance specifiers is the same as for the class specifiers (refs).
- add (self, name='', item=None, *references, **specifiers)
  - add() is a method that is considered abstract in Item, but is implemented in Map and the composite subclasses of Presenter. This is the method that takes care of all the details necessary to add a child item to the parent item.
  - name
    - The name string is given at design time if a name or label for the item is desired. This name is used to locate the item within the hierarchy (via compound keys). If no name is needed, the dafault is an empty string, '', which is converted to a unique, random name.
  - item
    - The "item" paramenter is typically an item class, which is instantiated by the add() method. If an item instance is given, however, a link to the given item is created instead.
  - *references
    - Positional arguments other than name and item are references to external items needed by the added item. These arguments are typically item instances.
  - **specifiers
    - Keyword arguments are specifiers for the added item instance.
- assemble (self, ...)
  - assemble() is an abstract method that must be defined by any subclass that is a composite defined at design-time. The signature can vary, but it must match the references passed to the initializer by the parent via the add() method.
- get_parent(self)
  - Although public, this method is typically not invoked by the user-developer. Part of the introspection interface, it returns the immediate parent item in the object tree.
- get_name(self)
  - Although public, this method is typically not invoked by the user-developer. Part of the introspection interface, it returns the name of this item in the parent.
- get_top(self)
  - Although public, this method is typically not invoked by the user-developer. Part of the introspection interface, it returns the top item (or root node) of the object tree.
- get_key(self)
  - Although public, this method is typically not invoked by the user-developer. Part of the introspection interface, it returns the key in dot notation of this item within the object tree from 'top'.
- update (self, message)
  - update() is an abstract method that must be defined for any subclass (abstraction layer or presentation layer) that is to be an observer. The message parameter may be a string or another object (usually an item).