Tcl8.6a2/Tk8.6a2 Documentation > TclCmd > define

Tcl/Tk Applications | Tcl Commands | Tk Commands | Tcl Library | Tk Library

NAME
oo::define, oo::objdefine - define and configure classes and objects
SYNOPSIS
DESCRIPTION
CONFIGURING CLASSES
constructor argList bodyScript
deletemethod name ?name ...
destructor bodyScript
export name ?name ...?
filter ?methodName ...?
forward name cmdName ?arg ...?
method name argList bodyScript
mixin ?className ...?
renamemethod fromName toName
self subcommand arg ...
self script
superclass className ?className ...?
unexport name ?name ...?
CONFIGURING OBJECTS
class className
deletemethod name ?name ...
export name ?name ...?
filter ?methodName ...?
forward name cmdName ?arg ...?
method name argList bodyScript
mixin ?className ...?
renamemethod fromName toName
unexport name ?name ...?
EXAMPLES
SEE ALSO
KEYWORDS

NAME

oo::define, oo::objdefine - define and configure classes and objects

SYNOPSIS

package require TclOO

oo::define class defScript
oo::define class subcommand arg ?arg ...?
oo::objdefine object defScript
oo::objdefine object subcommand arg ?arg ...?

DESCRIPTION

The oo::define command is used to control the configuration of classes, and the oo::objdefine command is used to control the configuration of objects (including classes as instance objects), with the configuration being applied to the entity named in the class or the object argument. Configuring a class also updates the configuration of all subclasses of the class and all objects that are instances of that class or which mix it in (as modified by any per-instance configuration). The way in which the configuration is done is controlled by either the defScript argument or by the subcommand and following arg arguments; when the second is present, it is exactly as if all the arguments from subcommand onwards are made into a list and that list is used as the defScript argument.

CONFIGURING CLASSES

The following commands are supported in the defScript for oo::define, each of which may also be used in the subcommand form:

constructor argList bodyScript
This creates or updates the constructor for a class. The formal arguments to the constructor (defined using the same format as for the Tcl proc command) will be argList, and the body of the constructor will be bodyScript. When the body of the constructor is evaluated, the current namespace of the constructor will be a namespace that is unique to the object being constructed. Within the constructor, the next command should be used to call the superclasses' constructors. If bodyScript is the empty string, the constructor will be deleted.

deletemethod name ?name ...
This deletes each of the methods called name from a class. The methods must have previously existed in that class. Does not affect the superclasses of the class, nor does it affect the subclasses or instances of the class (except when they have a call chain through the class being modified).

destructor bodyScript
This creates or updates the destructor for a class. Destructors take no arguments, and the body of the destructor will be bodyScript. The destructor is called when objects of the class are deleted, and when called will have the object's unique namespace as the current namespace. Destructors should use the next command to call the superclasses' destructors. Note that destructors are not called in all situations (e.g. if the interpreter is destroyed). If bodyScript is the empty string, the destructor will be deleted.
Note that errors during the evaluation of a destructor are not returned to the code that causes the destruction of an object. Instead, they are passed to the currently-defined bgerror handler.

export name ?name ...?
This arranges for each of the named methods, name, to be exported (i.e. usable outside an instance through the instance object's command) by the class being defined. Note that the methods themselves may be actually defined by a superclass; subclass exports override superclass visibility, and may in turn be overridden by instances.

filter ?methodName ...?
This sets or updates the list of method names that are used to guard whether a method call to instances of the class may be called and what the method's results are. Each methodName names a single filtering method (which may be exposed or not exposed); it is not an error for a non-existent method to be named since they may be defined by subclasses. If no methodName arguments are present, the list of filter names is set to empty.

forward name cmdName ?arg ...?
This creates or updates a forwarded method called name. The method is defined be forwarded to the command called cmdName, with additional arguments, arg etc., added before those arguments specified by the caller of the method. Forwarded methods should be deleted using the method subcommand. The method will be exported if name starts with a lower-case letter, and non-exported otherwise.

method name argList bodyScript
This creates, updates or deletes a method. The name of the method is name, the formal arguments to the method (defined using the same format as for the Tcl proc command) will be argList, and the body of the method will be bodyScript. When the body of the method is evaluated, the current namespace of the method will be a namespace that is unique to the current object. The method will be exported if name starts with a lower-case letter, and non-exported otherwise; this behavior can be overridden via export and unexport.

mixin ?className ...?
This sets or updates the list of additional classes that are to be mixed into all the instances of the class being defined. Each className argument names a single class that is to be mixed in; if no classes are present, the list of mixed-in classes is set to be empty.

renamemethod fromName toName
This renames the method called fromName in a class to toName. The method must have previously existed in the class, and toName must not previously refer to a method in that class. Does not affect the superclasses of the class, nor does it affect the subclasses or instances of the class (except when they have a call chain through the class being modified). Does not change the export status of the method; if it was exported before, it will be afterwards.

self subcommand arg ...

self script
This command is equivalent to calling oo::objdefine on the class being defined (see CONFIGURING OBJECTS below for a description of the supported values of subcommand). It follows the same general pattern of argument handling as the oo::define and oo::objdefine commands, and “oo::define cls self subcommand ...” operates identically to “oo::objdefine cls subcommand ...”.

superclass className ?className ...?
This allows the alteration of the superclasses of the class being defined. Each className argument names one class that is to be a superclass of the defined class. Note that objects must not be changed from being classes to being non-classes or vice-versa.

unexport name ?name ...?
This arranges for each of the named methods, name, to be not exported (i.e. not usable outside the instance through the instance object's command, but instead just through the my command visible in each object's context) by the class being defined. Note that the methods themselves may be actually defined by a superclass; subclass unexports override superclass visibility, and may be overridden by instance unexports.

CONFIGURING OBJECTS

The following commands are supported in the defScript for oo::objdefine, each of which may also be used in the subcommand form:

class className
This allows the class of an object to be changed after creation. Note that the class's constructors are not called when this is done, and so the object may well be in an inconsistent state unless additional configuration work is done.

deletemethod name ?name ...
This deletes each of the methods called name from an object. The methods must have previously existed in that object. Does not affect the classes that the object is an instance of.

export name ?name ...?
This arranges for each of the named methods, name, to be exported (i.e. usable outside the object through the object's command) by the object being defined. Note that the methods themselves may be actually defined by a class or superclass; object exports override class visibility.

filter ?methodName ...?
This sets or updates the list of method names that are used to guard whether a method call to the object may be called and what the method's results are. Each methodName names a single filtering method (which may be exposed or not exposed); it is not an error for a non-existent method to be named. If no methodName arguments are present, the list of filter names is set to empty. Note that the actual list of filters also depends on the filters set upon any classes that the object is an instance of.

forward name cmdName ?arg ...?
This creates or updates a forwarded object method called name. The method is defined be forwarded to the command called cmdName, with additional arguments, arg etc., added before those arguments specified by the caller of the method. Forwarded methods should be deleted using the method subcommand. The method will be exported if name starts with a lower-case letter, and non-exported otherwise.

method name argList bodyScript
This creates, updates or deletes an object method. The name of the method is name, the formal arguments to the method (defined using the same format as for the Tcl proc command) will be argList, and the body of the method will be bodyScript. When the body of the method is evaluated, the current namespace of the method will be a namespace that is unique to the object. The method will be exported if name starts with a lower-case letter, and non-exported otherwise.

mixin ?className ...?
This sets or updates a per-object list of additional classes that are to be mixed into the object. Each argument, className, names a single class that is to be mixed in; if no classes are present, the list of mixed-in classes is set to be empty.

renamemethod fromName toName
This renames the method called fromName in an object to toName. The method must have previously existed in the object, and toName must not previously refer to a method in that object. Does not affect the classes that the object is an instance of. Does not change the export status of the method; if it was exported before, it will be afterwards.

unexport name ?name ...?
This arranges for each of the named methods, name, to be not exported (i.e. not usable outside the object through the object's command, but instead just through the my command visible in the object's context) by the object being defined. Note that the methods themselves may be actually defined by a class; instance unexports override class visibility.

EXAMPLES

This example demonstrates how to use both forms of the oo::define and oo::objdefine commands (they work in the same way), as well as illustrating four of the subcommands of them.

oo::class create c
c create o
oo::define c method foo {} {
    puts "world"
}
oo::objdefine o {
    method bar {} {
        my Foo "hello "
        my foo
    }
    forward Foo ::puts -nonewline
    unexport foo
}
o bar                 prints "hello world"
o foo                 error "unknown method foo"
o Foo Bar             error "unknown method Foo"
oo::objdefine o renamemethod bar lollipop
o lollipop            prints "hello world"

SEE ALSO

next, oo::class, oo::object

KEYWORDS

class, definition, method, object
Copyright © 1995-1997 Roger E. Critchlow Jr. Copyright © 2007 Donal K. Fellows