PGF/TikZ Manual

The TikZ and PGF Packages
Manual for version 3.1.10

Mathematical and Object-Oriented Engines

98 Object-Oriented Programming

This section describes the oo module.

  • \usepgfmodule{oo} % and plain and pure pgf

  • \usepgfmodule[oo] % Cont and pure pgf

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

In this chapter it is assumed that you are familiar with the basics of a typical object-oriented programming language like Java, C++ or Eiffel.

98.1 Overview

does not support object-oriented programming, presumably because it was written at a time when this style of programming was not yet “en vogue”. When one is used to the object-oriented style of thinking, some programming constructs in often seem overly complicated. The object-oriented programming module of pgf may help here. It is written completely using simple macros and is, thus, perfectly portable. This also means, however, that it is not particularly fast (but not too slow either), so you should use it only for non-time-critical things.

Basically, the oo-system supports classes (in the object-oriented sense, this has nothing to do with -classes), methods, constructors, attributes, objects, object identities, and (thanks to Sašo Živanović) inheritance and overloading.

The first step is to define a class, using the macro \pgfooclass (all normal macros in pgf’s object-oriented system start with \pgfoo). This macro gets the name of a class and in its body a number of methods are defined. These are defined using the \method macro (which is defined only inside such a class definition) and they look a bit like method definitions in, say, Java. Object attributes are declared using the \attribute command, which is also defined only inside a class definition.

Once a class has been defined, you can create objects of this class. Objects are created using \pgfoonew. Such an object has many characteristics of objects in a normal object-oriented programming language: Each object has a unique identity, so when you create another object, this object is completely distinct from all other objects. Each object also has a set of private attributes, which may change over time. Suppose, for instance, that we have a point class. Then creating a new object (called an instance) of this class would typically have an x-attribute and a y-attribute. These can be changed over time. Creating another instance of the point class creates another object with its own x- and y-attributes.

Given an object, you can call a method for this object. Inside the method the attributes of the object for which the method is being called can be accessed.

The life of an object always ends with the end of the scope in which it was created. However, changes to attribute values are not local to scopes, so when you change an attribute anywhere, this change persists till the end of the life of the object or until the attribute is changed again.

98.2 A Running Example: The Stamp Class

As a running example we will develop a stamp class and stamp objects. The idea is that a stamp object is able to “stamp something” on a picture. This means that a stamp object has an attribute storing the “stamp text” and there is a method that asks the object to place this text somewhere on a canvas. The method can be called repeatedly and there can be several different stamp objects, each producing a different text. Stamp objects can either be created dynamically when needed or a library might define many such objects in an outer scope.

Such stamps are similar to many things present in pgf such as arrow tips, patterns, or shadings and, indeed, these could all have been implemented in this object-oriented fashion (which might have been better, but the object-oriented subsystem is a fairly new addition to pgf).

98.3 Classes

We start with the definition of the stamp class. This is done using the \pgfooclass macro:

  • \pgfooclass(list of superclasses){class name}{body}

  • 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 -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.

    % This is the class stamp

    \attribute text;
    \attribute rotation angle=20;

    \method stamp(#1) { % The constructor

    \method apply(#1,#2) { % Causes the stamp to be shown at coordinate (#1,#2)

    % We can now create objects of type "stamp"

    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.

The body of a class usually just consists of calls to the macros \attribute and \method, which will be discussed in more detail in later sections.

98.4 Objects

Once a class has been declared, we can start creating objects for this class. For this the \pgfoonew command can be used, which has a peculiar syntax:

  • \pgfoonewobject handle or attribute=new class name(constructor arguments)

  • 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.

    \pgfoonew \firststamp=new stamp()
    \pgfoonew \secondstamp=new stamp()
    \pgfoonew \thirdstamp=new stamp()
    % \thirdstamp no longer exists, but \firststamp and \secondstamp do
    % even if you try to store \thirdstamp in a global variable, trying
    % to access it will result in an error.

    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 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.

    \attribute stamp obj;
    \attribute another object;

    \method foo() {
    \pgfoonew{stamp obj}=new stamp()
    \pgfoonew{another object}=new bar()

  • \pgfoogc

  • This command causes the “garbage collector” to be invoked. The job of this garbage collector is to free the global -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.

98.5 Methods

Methods are defined inside the body of classes using the following command:

  • \methodmethod name(parameter list){method body}

  • 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 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.

In order to call a method for an object, you first need to create the object and you need a handle for this object. In order to invoke a method for this object, a special syntax is used that is similar to Java or C++ syntax:

  • object handle.super class.method name(parameters)

  • 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.

    % This is the class stamp

    \method stamp() { % The constructor

    \method apply(#1,#2) { % Causes the stamp to be shown at coordinate (#1,#2)
    % Draw the stamp:
    \node [rotate=20,font=\huge] at (#1,#2) {Passed};

    \pgfoonew \mystamp=new stamp()


    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.

  • \pgfoosuper(class,object handle).method name(arguments)

  • 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.

98.6 Attributes

Every object has a set of attributes, which may change over time. Attributes are declared using the \attribute command, which, like the \method command, is defined only inside the scope of \pgfooclass. Attributes can be modified (only) by methods. To take the stamp example, an attribute of a stamp object might be the text that should be stamped when the apply method is called.

When an attribute is changed, this change is not local to the current group. Changes will persist till the end of the object’s life or until the attribute is changed once more.

To declare an attribute you should use the \attribute command:

  • \attributeattribute name=initial value;

  • 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.

    % This is the class stamp

    \attribute text;
    \attribute rotation angle = 20;

    \method stamp(#1) {
    \pgfooset{text}{#1} % Set the text

    \method apply(#1,#2) {
    \pgfoothis.shift origin(#1,#2)

    % Draw the stamp:
    \node [rotate=\pgfoovalueof{rotation angle},font=\huge]

    \method shift origin(#1,#2) { ... }

    \method set rotation (#1) {
    \pgfooset{rotation angle}{#1}

Attributes can be set and read only inside methods, it is not possible to do so using an object handle. Spoken in terms of traditional object-oriented programming, attributes are always private. You need to define getter and setter methods if you wish to read or modify attributes.

Reading and writing attributes is not done using the “dot-notation” that is used for method calls. This is mostly due to efficiency reasons. Instead, a set of special macros is used, all of which can only be used inside methods.

  • \pgfooset{attribute}{value}

  • Sets the attribute of the current object to value.

    \method set rotation (#1) {
    \pgfooset{rotation angle}{#1}

  • \pgfooeset{attribute}{value}

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

  • \pgfooappend{attribute}{value}

  • This method adds the given value to the attribute at the end.

  • \pgfooprefix{attribute}{value}

  • This method adds the given value to the attribute at the beginning.

  • \pgfoolet{attribute}{macro}

  • Sets the attribute of the current value to the current value of macro using ’s \let command.

    \method foo () {
    \pgfoolet{my func}\myfunc
    % Changing \myfunc now has no effect on the value of attribute my func

  • \pgfooget{attribute}{macro}

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

    \method get rotation (#1) {
    \pgfooget{rotation angle}{#1}

    \mystamp.get rotation(\therotation)
    ``\therotation'' is now ``20'' (or whatever).

98.7 Identities

Every object has a unique identity, which is simply an integer. It is possible to retrieve the object id using the get id method (discussed below), but normally you will not need to do so because the id itself cannot be used to access an object. Rather, you access objects via their methods and these, in turn, can only be called via object handles.

Object handles can be created in four ways:

  • 1. Calling \pgfoonewobject handle=... will cause object handle to be a handle to the newly created object.

  • 2. Using \let to create an alias of an existing object handle: If \mystamp is a handle, saying \let\myotherstamp=\mystamp creates a second handle to the same object.

  • 3. \pgfooobj{id} can be used as an object handle to the object with the given id.

  • 4. Using the get handle method to create a handle to a given object.

Let us have a look at the last two methods.

  • \pgfooobj{id}

  • 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:

    % Create a new object:
    \pgfoonew \mystamp=new stamp()

    % Get the object's id and store it in \myid:
    \mystamp.get id(\myid)

    % The following two calls have the same effect:

The get id method can be used to retrieve the id of an object. This method is predefined for every class and you should not try to define a method of this name yourself.

  • Method <<>>/kbd/spanget id(macro) (predefined for all classes)

  • 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.

There is a second predefined method, called get handle, which is also used to create object handles.

  • Method <<>>/kbd/spanget handle({macro name}) (predefined for all classes)

  • 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. \letmacro 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, \letmacro 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.

98.8 The Object Class

The object-oriented module predefines a basic class object that can be used as a base class in different context.

  • Class object

  • This class current only implements one method:

    • Method <<>>/kbd/spancopy(handle)

    • Creates a new object and initializes the values of its (declared) attributes to the values of the original. The method takes one argument: a control sequence which receives the handle of the copy.

98.9 The Signal Class

In addition to the basic mechanism for defining and using classes and object, the class signal is predefined. It implements a so-called signal–slot mechanism.

  • Class signal

  • 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.

    • Constructor <<>>/kbd/spansignal()

    • The constructor does nothing.

    • Method <<>>/kbd/spanconnect(object handle,method name)

    • This method gets an object handle as parameter and a method name of this object. It will queue the object-method pair in an internal list and each time the signal emits something, this object’s method is called.

      Be careful not to pass \pgfoothis as object handle. This would cause the signal object to connect to itself. Rather, if you wish to connect a signal to a method of the current object you first need to create an alias using the get handle method:

      \pgfooclass{some class}{
      \method some class() {
      \pgfoothis.get handle(\me)
      \method foo () {}
      \method bar (#1,#2) {}
      \pgfoonew \objA=new some class()
      \pgfoonew \objB=new some class()

    • Method <<>>/kbd/spanemit(arguments)

    • This method emits a signal to all connected slots. This means that for all objects that have previously been connected via a call of connect, the method (slot) that was specified during the call of connect is invoked with given arguments.

      % will call \,2) and \,2)

98.10 Implementation Notes

For the curious, here are some notes on how the oo-system is implemented:

  • • There is an object id counter that gets incremented each time an object is created. However, this counter is local to the current scope, which means that it is reset at the end of each scope, corresponding to the fact that at the end of a scope all objects created in this scope become invalid. Newly created objects will then have the same id as “deleted” objects.

  • • Attributes are stored globally. For each attribute of each object there is a macro whose name is composed of the object’s id and the attribute name. Changes to object attributes are always global.

  • • A call to the garbage collector causes a loop to be executed that tries to find objects whose object number is larger than the current maximum alive objects. The global attributes of these objects are then freed (set to \relax) by calling a special internal method of these (dead) objects.

    The garbage collector is automatically called after each group in which an object was created using \aftergroup.

  • • When a method is called, before the method call some code is executed that sets a global counter storing the current object id to the object id of the object being called. After the method call some code is inserted that restores the global counter to its original value. This is done without scopes, so some tricky \expandafter magic is needed. Note that, because of this process, you cannot use commands like \pgfutil@ifnextchar at the end of a method.

  • • An object handle contains just the code to set up and restore the current object number to the number of the object being called.