The TikZ and PGF Packages
Manual for version 3.1.10

This module defines a relatively small set of TeX commands for defining classes, methods, attributes and objects in the sense of object-oriented programming.

This command defines a class named ⟨class name⟩. The name of the class can contain spaces and most other characters, but no periods. So, valid class names are MyClass or my class or Class_C++_emulation??1. The ⟨list of superclasses⟩ is optional just like the parenthesis around it.

The ⟨body⟩ is actually just executed, so any normal TeX-code is permissible here. However, while the ⟨body⟩ is being executed, the macros \method and \attribute are set up so that they can be used to define methods and attributes for this class (the original meanings are restored afterward).

The definition of a class is local to the scope where the class has been defined.

Concerning the list of base classes, the Method Resolution Order (mro) is computed using the C3 algorithm also used in Python, v2.3 and higher. The linearization computed by the algorithm respects both local precedence ordering and monotonicity. Resolution of both methods and attributes depends on the mro: when a method method name is called on an object of class \(C\), the system invokes method method name from the first class in the mro of \(C\) which defines method method name; when an object is created, each attribute attr is initialized to the value specified in the first class in the mro of \(C\) which declares attribute attr.

Causes a new object to be created. The class of the object will be ⟨class name⟩, which must previously have been declared using \pgfooclass. Once the object has been created, the constructor method of the object will be called with the parameter list set to ⟨constructor arguments⟩.

The resulting object is stored internally and its lifetime will end exactly at the end of the current scope.

Here is an example in which three stamp objects are created.

The optional ⟨object handle or attribute⟩ can either be an ⟨object handle⟩ or an ⟨attribute⟩. When an ⟨object handle⟩ is given, it must be a normal TeX macro name that will “point” to the object (handles are discussed in more detail in Section 98.7). You can use this macro to call methods of the object as discussed in the following section. When an ⟨attribute⟩ is given, it must be given in curly braces (the curly braces are used to detect the presence of an attribute). In this case, a handle to the newly created object is stored in this attribute.

This command causes the “garbage collector” to be invoked. The job of this garbage collector is to free the global TeX-macros that are used by “dead” objects (objects whose life-time has ended). This macro is called automatically after every scope in which an object has been created, so you normally do not need to call this macro yourself.

This macro, which is only defined inside a class definition, defines a new method named ⟨method name⟩. Just like class names, method names can contain spaces and other characters, so ⟨method names⟩ like put_stamp_here or put stamp here are both legal.

Three method names are special: First, a method having either the same name as the class or having the name init is called the constructor of the class. There are (currently) no destructors; objects simply become “undefined” at the end of the scope in which they have been created. The other two methods are called get id and get handle, which are always automatically defined and which you cannot redefine. They are discussed in Section 98.7.

Overloading of methods by differing numbers of parameters is not possible, that is, it is illegal to have two methods inside a single class with the same name (despite possibly different parameter lists). However, two different classes may contain a method with the same name, that is, classes form namespaces for methods. Also, a class can (re)implement a method from a superclass.

The ⟨method name⟩ must be followed by a ⟨parameter list⟩ in parentheses, which must be present even when the ⟨parameter list⟩ is empty. The ⟨parameter list⟩ is actually a normal TeX parameter list that will be matched against the parameters inside the parentheses upon method invocation and, thus, could be something like #1#2 foo #3 bar., but a list like #1,#2,#3 is more customary. By setting the parameter list to just #1 and then calling, say, \pgfkeys{#1} at the beginning of a method, you can implement Objective-C-like named parameters.

When a method is called, the ⟨body⟩ of the method will be executed. The main difference to a normal macro is that while the ⟨body⟩ is executed, a special macro called \pgfoothis is set up in such a way that it references the object for which the method is executed.

This causes the method ⟨method name⟩ to be called for the object referenced by the ⟨object handle⟩. The method is the one defined in the class of the object or, if it is not defined there, the method defined in the superclasses of the object’s class (if there are several superclasses that define the same method, the method resolution order is used to determine which one gets called). If the optional ⟨super class⟩ is specified, the method implementation of that class will be used rather than the implementation in the object’s class. The ⟨parameters⟩ are matched against the parameters of the method and, then, the method body is executed. The execution of the method body is not done inside a scope, so the effects of a method body persist.

Inside a method, you can call other methods. If you have a handle for another object, you can simply call it in the manner described above. In order to call a method of the current object, you can use the special object handle \pgfoothis.

This macro gives you finer control over which method gets invoked in case of multiple inheritance. This macro calls ⟨method name⟩ of the object specified by ⟨object handle⟩, but which implementation of the method is called is determined as follows: it will be the implementation in the first class (in the method resolution order) after ⟨class⟩ that defines ⟨method name⟩.

This command can only be given inside the body of an \pgfooclass command. It declares the attribute named ⟨attribute name⟩. This name, like method or class names, can be quite arbitrary, but should not contain periods. Valid names are an_attribute? or my attribute.

You can optionally specify an ⟨initial value⟩ for the attribute; if none is given, the empty string is used automatically. The initial value is the value that the attribute will have just after the object has been created and before the constructor is called.

Sets the ⟨attribute⟩ of the current object to ⟨value⟩.

Performs the same action as \pgfooset but in an \edef full expansion context.

This method adds the given ⟨value⟩ to the ⟨attribute⟩ at the end.

This method adds the given ⟨value⟩ to the ⟨attribute⟩ at the beginning.

Sets the ⟨attribute⟩ of the current value to the current value of ⟨macro⟩ using TeX’s \let command.

Expands (eventually) to the current value of ⟨attribute⟩ of the current object.

Reads the current value of ⟨attribute⟩ and stores the result in ⟨macro⟩.

Provided that ⟨id⟩ is the id of an existing object (an object whose life-time has not expired), calling this command yields a handle to this object. The handle can then be used to call methods:

Calling ⟨obj⟩.get id(⟨macro⟩) stores the id ⟨obj⟩ in ⟨macro⟩. This is mainly useful when you wish to store an object for a longer time and you cannot guarantee that any handle that you happen to have for this object will be available later on.

The only way to use the retrieved id later on is to call \pgfooobj.

Different object that are alive (that are still within the scope in which they were created) will always have different ids, so you can use the id to test for equality of objects. However, after an object has been destroyed because its scope has ended, the same id may be used again for newly created objects.

Here is a typical application where you need to call this method: You wish to collect a list of objects for which you wish to call a specific method from time to time. For the collection process you wish to offer a macro called \addtoobjectlist, which takes an object handle as parameter. It is quite easy to store this handle somewhere, but a handle is, well, just a handle. Typically, shortly after the call to \addtoobjectlist the handle will no longer be valid or even exist, even though the object still exists. In this case, you wish to store the object id somewhere instead of the handle. Thus, for the object passed to \addtoobjectlist you call the get id method and store the resulting id, rather than the handle.

Calling this method for an object will cause ⟨macro name⟩ to become a handle to the given object. For any object handle \obj – other than \pgfoothis – the following two have the same effect:

• 1. \let⟨macro name⟩=\obj

• 2. \obj.get handle(⟨macro name⟩)

The first method is simpler and faster. However, for \pgfoothis there is a difference: The call \pgfoothis.get handle(⟨macro name⟩) will cause ⟨macro name⟩ to be an object handle to the current object and will persist to be so even after the method is done. By comparison, \let⟨macro name⟩=\pgfoothis causes \obj to be the same as the very special macro \pgfoothis, so \obj will always refer to the current object, which may change over time.

This class current only implements one method:

This class is used to implement a simple signal–slot mechanism. The idea is the following: From time to time special things happen about which a number of objects need to be informed. Different things can happen and different object will be interested in these things. A signal object can be used to signal that such special things of a certain kind have happened. For example, one signal object might be used to signal the event that “a page has been shipped out”. Another signal might be used to signal that “a figure is about to be typeset”, and so on.

Objects can “tune in” to signals. They do so by connecting one of their methods (then called a slot) to the signal. Then, whenever the signal is emitted, the method of the connected object(s) get called. Different objects can connect different slots to the same signal as long as the argument lists will fit. For example, the object that is used to signal the “end of page has been reached” might emit signals that have, say, the box number in which the finished page can be found as a parameter (actually, the finished page is always in box 255). Then one object could connect a method handle page(#1) to this signal, another might connect the method emergency action(#1) to this signal, and so on.

Currently, it is not possible to “unregister” or “detach” a slot from a signal, that is, once an object has been connect to a signal, it will continue to receive emissions of this signal till the end of the life-time of the signal. This is even true when the object no longer exists (but the signal does), so care must be taken that signal objects are always created after the objects that are listening to them.