12. Base Classes

Asside from eieio-default-superclass, EIEIO comes with some additional classes that you can use. By using multiple inheritance, it is possible to use several features at the same time.

12.1 eieio-instance-inheritor

This class is in package `eieio-base'.

Instance inheritance is a mechanism whereby the value of a slot in object instance can reference the parent instance. If the parent's slot value is changed, then the child instance is also changed. If the child's slot is set, then the parent's slot is not modified.

Class: eieio-instance-inheritor parent-instance

A class whose instances are enabled with instance inheritance. The parent-instance slot indicates the instance which is considered the parent of the current instance. Default is nil.

To use this class, inherit from it with your own class. To make a new instance that inherits from and existing instance of your class, use the clone method with additional parameters to specify local values.

The eieio-instance-inheritor class works by causing cloned objects to have all slots unbound. This class' slot-unbound method will cause references to unbound slots to be redirected to the parent instance. If the parent slot is also unbound, then slot-unbound will throw an slot-unbound signal.

This class is in package `eieio-base'.

Sometimes it is useful to keep a master list of all instances of a given class. The class eieio-instance-tracker performs this task.

Class: eieio-instance-tracker tracker-symbol

Enable instance tracking for this class. The field tracker-symbol should be initialized in inheritors of this class to a symbol created with defvar. This symbol will serve as the variable used as a master list of all objects of the given class.

Method: eieio-instance-tracker initialize-instance obj fields

This method is defined as an :AFTER method. It adds new instances to the master list. Do not overload this method unless you use call-next-method.

Method: eieio-instance-tracker delete-instance obj

Remove obj from the master list of instances of this class. This may let the garbage collector nab this instance.

eieio-instance-tracker-find: key field list-symbol

This convenience function lets you find instances. key is the value to search for. FIELD is the field to compare KEY against. The function equal is used for comparison. The paramter list-symbol is the variable symbol which contains the list of objects to be searched.

12.2 eieio-singleton

This class is in package `eieio-base'.

Class: eieio-singleton

Inheriting from the singleton class will guarantee that there will only ever be one instance of this class. Multiple calls to make-instance will always return the same object.

12.3 eieio-persistent

This class is in package `eieio-base'.

If you want an object, or set of objects to be persistent, meaning the slot values are important to keep saved between sessions, then you will want your top level object to inherit from eieio-persistent.

To make sure your persistent object can be moved, make sure all file names stored to disk are made relative with eieio-persistent-path-relative.

Class: eieio-persistent file file-header-line

Enables persistence for instances of this class. Slot file with initarg :file is the file name in which this object will be saved. Class allocated slot file-header-line is used with method object-write as a header comment.

All objects can write themselves to a file, but persistent objects have several additional methods that aid in maintaining them.

Method: eieio-persistent eieio-persistent-save obj &optional file

Write the object obj to its file. If optional argument file is specified, use that file name instead.

Method: eieio-persistent eieio-persistent-path-relative obj file

Return a file name derived from file which is relative to the stored location of OBJ. This method should be used to convert file names so that they are relative to the save file, making any system of files movable from one location to another.

Method: eieio-persistent object-write obj &optional comment

Like object-write for standard-object, but will derive a header line comment from the class allocated slot if one is not provided.

Function: eieio-persistent-read filename

Read filename which contains an eieio-persistent object previously written with eieio-persistent-save.

12.4 eieio-named

This class is in package `eieio-base'.

Class: eieio-named

Object with a name. Name storage already occurs in an object. This object provides get/set access to it.

12.5 eieio-speedbar

This class is in package `eieio-speedbar'.

If a series of class instances map to a tree structure, it is possible to cause your classes to be displayable in Speedbar. @xref{Top,,,speedbar}. Inheriting from these classes will enable a speedbar major display mode with a minimum of effort.

Class: eieio-speedbar buttontype buttonface

Enables base speedbar display for a class. The slot buttontype is any of the symbols allowed by the function speedbar-make-tag-line for the exp-button-type argument @xref{Extending,,,speedbar}. The slot buttonface is the face to use for the text of the string displayed in speedbar. The slots buttontype and buttonface are class allocated slots, and do not take up space in your instances.

Class: eieio-speedbar-directory-button buttontype buttonface

This class inherits from eieio-speedbar and initializes buttontype and buttonface to appear as directory level lines.

Class: eieio-speedbar-file-button buttontype buttonface

This class inherits from eieio-speedbar and initializes buttontype and buttonface to appear as file level lines.

To use these classes, inherit from one of them in you class. You can use multiple inheritance with them safely. To customize your class for speedbar display, override the default values for buttontype and buttonface to get the desired effects.

Useful methods to define for your new class include:

Method: eieio-speedbar eieio-speedbar-derive-line-path obj depth

Return a string representing a directory associated with an instance of obj. depth can be used to indice how many levels of indentation have been opened by the user where obj is shown.

Method: eieio-speedbar eieio-speedbar-description obj

Return a string description of OBJ. This is shown in the minibuffer or tooltip when the mouse hovers over this instance in speedbar.

Method: eieio-speedbar eieio-speedbar-child-description obj

Return a string representing a description of a child node of obj when that child is not an object. It is often useful to just use item info helper functions such as speedbar-item-info-file-helper.

Method: eieio-speedbar eieio-speedbar-object-buttonname obj

Return a string which is the text displayed in speedbar for obj.

Method: eieio-speedbar eieio-speedbar-object-children obj

Return a list of children of obj.

Method: eieio-speedbar eieio-speedbar-child-make-tag-lines obj depth

This method inserts a list of speedbar tag lines for obj to represent its children. Implement this method for your class if your children are not objects themselves. You still need to implement eieio-speedbar-object-children.

In this method, use techniques specified in the Speedbar manual. @xref{Extending,,,speedbar}.

Some other functions you will need to learn to use are:

eieio-speedbar-create: make-map key-map menu name toplevelfn

Register your object display mode with speedbar. make-map is a function which initialized you keymap. key-map is a symbol you keymap is installed into. menu is an easy menu vector representing menu items specific to your object display. name is a short string to use as a name identifying you mode. toplevelfn is a function called which must return a list of objects representing those in the instance system you wish to browse in speedbar.

Read the Extending chapter in the speedbar manual for more information on how speedbar modes work @xref{Extending,,,speedbar}.

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.