| 1 |
% Copyright 2018 by Till Tantau |
| 2 |
% |
| 3 |
% This file may be distributed and/or modified |
| 4 |
% |
| 5 |
% 1. under the LaTeX Project Public License and/or |
| 6 |
% 2. under the GNU Free Documentation License. |
| 7 |
% |
| 8 |
% See the file doc/generic/pgf/licenses/LICENSE for more details. |
| 9 |
|
| 10 |
|
| 11 |
\section{Object-Oriented Programming} |
| 12 |
\label{section-oop} |
| 13 |
|
| 14 |
This section describes the |oo| module. |
| 15 |
|
| 16 |
\begin{pgfmodule}{oo} |
| 17 |
This module defines a relatively small set of \TeX\ commands for defining |
| 18 |
classes, methods, attributes and objects in the sense of object-oriented |
| 19 |
programming. |
| 20 |
\end{pgfmodule} |
| 21 |
|
| 22 |
In this chapter it is assumed that you are familiar with the basics of a |
| 23 |
typical object-oriented programming language like Java, C++ or Eiffel. |
| 24 |
|
| 25 |
|
| 26 |
\subsection{Overview} |
| 27 |
|
| 28 |
\TeX\ does not support object-oriented programming, presumably because it was |
| 29 |
written at a time when this style of programming was not yet ``en vogue''. When |
| 30 |
one is used to the object-oriented style of thinking, some programming |
| 31 |
constructs in \TeX\ often seem overly complicated. The object-oriented |
| 32 |
programming module of \pgfname\ may help here. It is written completely using |
| 33 |
simple \TeX\ macros and is, thus, perfectly portable. This also means, however, |
| 34 |
that it is not particularly fast (but not too slow either), so you should use |
| 35 |
it only for non-time-critical things. |
| 36 |
|
| 37 |
Basically, the oo-system supports \emph{classes} (in the object-oriented sense, |
| 38 |
this has nothing to do with \LaTeX-classes), \emph{methods}, |
| 39 |
\emph{constructors}, \emph{attributes}, \emph{objects}, \emph{object |
| 40 |
identities}, and (thanks to Sa\v so \v Zivanovi\'c) \emph{inheritance} and |
| 41 |
\emph{overloading.} |
| 42 |
|
| 43 |
The first step is to define a class, using the macro |\pgfooclass| (all normal |
| 44 |
macros in \pgfname's object-oriented system start with |\pgfoo|). This macro |
| 45 |
gets the name of a class and in its body a number of \emph{methods} are |
| 46 |
defined. These are defined using the |\method| macro (which is defined only |
| 47 |
inside such a class definition) and they look a bit like method definitions in, |
| 48 |
say, Java. Object attributes are declared using the |\attribute| command, which |
| 49 |
is also defined only inside a class definition. |
| 50 |
|
| 51 |
Once a class has been defined, you can create objects of this class. Objects |
| 52 |
are created using |\pgfoonew|. Such an object has many characteristics of |
| 53 |
objects in a normal object-oriented programming language: Each object has a |
| 54 |
\emph{unique identity}, so when you create another object, this object is |
| 55 |
completely distinct from all other objects. Each object also has a set of |
| 56 |
private attributes, which may change over time. Suppose, for instance, that we |
| 57 |
have a |point| class. Then creating a new object (called an instance) of this |
| 58 |
class would typically have an |x|-attribute and a |y|-attribute. These can be |
| 59 |
changed over time. Creating another instance of the |point| class creates |
| 60 |
another object with its own |x|- and |y|-attributes. |
| 61 |
|
| 62 |
Given an object, you can call a method for this object. Inside the method the |
| 63 |
attributes of the object for which the method is being called can be accessed. |
| 64 |
|
| 65 |
The life of an object always ends with the end of the \TeX\ scope in which it |
| 66 |
was created. However, changes to attribute values are not local to scopes, so |
| 67 |
when you change an attribute anywhere, this change persists till the end of the |
| 68 |
life of the object or until the attribute is changed again. |
| 69 |
|
| 70 |
|
| 71 |
\subsection{A Running Example: The Stamp Class} |
| 72 |
|
| 73 |
As a running example we will develop a |stamp| class and |stamp| objects. The |
| 74 |
idea is that a stamp object is able to ``stamp something'' on a picture. This |
| 75 |
means that a stamp object has an attribute storing the ``stamp text'' and there |
| 76 |
is a method that asks the object to place this text somewhere on a canvas. The |
| 77 |
method can be called repeatedly and there can be several different stamp |
| 78 |
objects, each producing a different text. Stamp objects can either be created |
| 79 |
dynamically when needed or a library might define many such objects in an outer |
| 80 |
scope. |
| 81 |
|
| 82 |
Such stamps are similar to many things present in \pgfname\ such as arrow tips, |
| 83 |
patterns, or shadings and, indeed, these could all have been implemented in |
| 84 |
this object-oriented fashion (which might have been better, but the |
| 85 |
object-oriented subsystem is a fairly new addition to \pgfname). |
| 86 |
|
| 87 |
|
| 88 |
\subsection{Classes} |
| 89 |
|
| 90 |
We start with the definition of the |stamp| class. This is done using the |
| 91 |
|\pgfooclass| macro: |
| 92 |
|
| 93 |
\begin{command}{\pgfooclass\opt{|(|\meta{list of superclasses}|)|}\marg{class name}\marg{body}} |
| 94 |
This command defines a class named \meta{class name}. The name of the class |
| 95 |
can contain spaces and most other characters, but no periods. So, valid |
| 96 |
class names are |MyClass| or |my class| or |Class_C++_emulation??1|. The |
| 97 |
\meta{list of superclasses} is optional just like the parenthesis around |
| 98 |
it. |
| 99 |
|
| 100 |
The \meta{body} is actually just executed, so any normal \TeX-code is |
| 101 |
permissible here. However, while the \meta{body} is being executed, the |
| 102 |
macros |\method| and |\attribute| are set up so that they can be used to |
| 103 |
define methods and attributes for this class (the original meanings are |
| 104 |
restored afterward). |
| 105 |
|
| 106 |
The definition of a class is local to the scope where the class has been |
| 107 |
defined. |
| 108 |
% |
| 109 |
\begin{codeexample}[code only] |
| 110 |
\pgfooclass{stamp}{ |
| 111 |
% This is the class stamp |
| 112 |
|
| 113 |
\attribute text; |
| 114 |
\attribute rotation angle=20; |
| 115 |
|
| 116 |
\method stamp(#1) { % The constructor |
| 117 |
... |
| 118 |
} |
| 119 |
|
| 120 |
\method apply(#1,#2) { % Causes the stamp to be shown at coordinate (#1,#2) |
| 121 |
... |
| 122 |
} |
| 123 |
} |
| 124 |
|
| 125 |
% We can now create objects of type "stamp" |
| 126 |
\end{codeexample} |
| 127 |
|
| 128 |
Concerning the list of base classes, the Method Resolution Order |
| 129 |
(\textsc{mro}) is computed using the C3 algorithm also used in Python, v2.3 |
| 130 |
and higher. The linearization computed by the algorithm respects both |
| 131 |
local precedence ordering and monotonicity. Resolution of both methods and |
| 132 |
attributes depends on the \textsc{mro}: when a method method name is called |
| 133 |
on an object of class $C$, the system invokes method method name from the |
| 134 |
first class in the \textsc{mro} of $C$ which defines method method name; |
| 135 |
when an object is created, each attribute |attr| is initialized to the |
| 136 |
value specified in the first class in the \textsc{mro} of $C$ which |
| 137 |
declares attribute |attr|. |
| 138 |
\end{command} |
| 139 |
|
| 140 |
The \meta{body} of a class usually just consists of calls to the macros |
| 141 |
|\attribute| and |\method|, which will be discussed in more detail in later |
| 142 |
sections. |
| 143 |
|
| 144 |
|
| 145 |
\subsection{Objects} |
| 146 |
|
| 147 |
Once a class has been declared, we can start creating objects for this class. |
| 148 |
For this the |\pgfoonew| command can be used, which has a peculiar syntax: |
| 149 |
|
| 150 |
\begin{command}{\pgfoonew\opt{\meta{object handle or attribute}|=|}|new |\meta{class name}|(|\meta{constructor arguments}|)|} |
| 151 |
Causes a new object to be created. The class of the object will be |
| 152 |
\meta{class name}, which must previously have been declared using |
| 153 |
|\pgfooclass|. Once the object has been created, the constructor method of |
| 154 |
the object will be called with the parameter list set to \meta{constructor |
| 155 |
arguments}. |
| 156 |
|
| 157 |
The resulting object is stored internally and its lifetime will end exactly |
| 158 |
at the end of the current scope. |
| 159 |
|
| 160 |
Here is an example in which three stamp objects are created. |
| 161 |
% |
| 162 |
\begin{codeexample}[code only] |
| 163 |
\pgfoonew \firststamp=new stamp() |
| 164 |
\pgfoonew \secondstamp=new stamp() |
| 165 |
{ |
| 166 |
\pgfoonew \thirdstamp=new stamp() |
| 167 |
... |
| 168 |
} |
| 169 |
% \thirdstamp no longer exists, but \firststamp and \secondstamp do |
| 170 |
% even if you try to store \thirdstamp in a global variable, trying |
| 171 |
% to access it will result in an error. |
| 172 |
\end{codeexample} |
| 173 |
|
| 174 |
The optional \meta{object handle or attribute} can either be an |
| 175 |
\meta{object handle} or an \meta{attribute}. When an \meta{object handle} |
| 176 |
is given, it must be a normal \TeX\ macro name that will ``point'' to the |
| 177 |
object (handles are discussed in more detail in |
| 178 |
Section~\ref{section-identities}). You can use this macro to call methods |
| 179 |
of the object as discussed in the following section. When an |
| 180 |
\meta{attribute} is given, it must be given in curly braces (the curly |
| 181 |
braces are used to detect the presence of an attribute). In this case, a |
| 182 |
handle to the newly created object is stored in this attribute. |
| 183 |
% |
| 184 |
\begin{codeexample}[code only] |
| 185 |
\pgfooclass{foo} |
| 186 |
{ |
| 187 |
\attribute stamp obj; |
| 188 |
\attribute another object; |
| 189 |
|
| 190 |
\method foo() { |
| 191 |
\pgfoonew{stamp obj}=new stamp() |
| 192 |
\pgfoonew{another object}=new bar() |
| 193 |
} |
| 194 |
... |
| 195 |
} |
| 196 |
\end{codeexample} |
| 197 |
% |
| 198 |
\end{command} |
| 199 |
|
| 200 |
\begin{command}{\pgfoogc} |
| 201 |
This command causes the ``garbage collector'' to be invoked. The job of |
| 202 |
this garbage collector is to free the global \TeX-macros that are used by |
| 203 |
``dead'' objects (objects whose life-time has ended). This macro is called |
| 204 |
automatically after every scope in which an object has been created, so you |
| 205 |
normally do not need to call this macro yourself. |
| 206 |
\end{command} |
| 207 |
|
| 208 |
|
| 209 |
\subsection{Methods} |
| 210 |
|
| 211 |
Methods are defined inside the body of classes using the following command: |
| 212 |
|
| 213 |
\begin{command}{\method \meta{method name}|(|\meta{parameter list}|)|\marg{method body}} |
| 214 |
This macro, which is only defined inside a class definition, defines a new |
| 215 |
method named \meta{method name}. Just like class names, method names can |
| 216 |
contain spaces and other characters, so \meta{method names} like |
| 217 |
|put_stamp_here| or |put stamp here| are both legal. |
| 218 |
|
| 219 |
Three method names are special: First, a method having either the same name |
| 220 |
as the class or having the name |init| is called the \emph{constructor} of |
| 221 |
the class. There are (currently) no destructors; objects simply become |
| 222 |
``undefined'' at the end of the scope in which they have been created. The |
| 223 |
other two methods are called |get id| and |get handle|, which are always |
| 224 |
automatically defined and which you cannot redefine. They are discussed in |
| 225 |
Section~\ref{section-identities}. |
| 226 |
|
| 227 |
Overloading of methods by differing numbers of parameters is not possible, |
| 228 |
that is, it is illegal to have two methods inside a single class with the |
| 229 |
same name (despite possibly different parameter lists). However, two |
| 230 |
different classes may contain a method with the same name, that is, classes |
| 231 |
form namespaces for methods. Also, a class can (re)implement a method from |
| 232 |
a superclass. |
| 233 |
|
| 234 |
The \meta{method name} must be followed by a \meta{parameter list} in |
| 235 |
parentheses, which must be present even when the \meta{parameter list} is |
| 236 |
empty. The \meta{parameter list} is actually a normal \TeX\ parameter list |
| 237 |
that will be matched against the parameters inside the parentheses upon |
| 238 |
method invocation and, thus, could be something like |#1#2 foo #3 bar.|, |
| 239 |
but a list like |#1,#2,#3| is more customary. By setting the parameter list |
| 240 |
to just |#1| and then calling, say, |\pgfkeys{#1}| at the beginning of a |
| 241 |
method, you can implement Objective-C-like named parameters. |
| 242 |
|
| 243 |
When a method is called, the \meta{body} of the method will be executed. |
| 244 |
The main difference to a normal macro is that while the \meta{body} is |
| 245 |
executed, a special macro called |\pgfoothis| is set up in such a way that |
| 246 |
it references the object for which the method is executed. |
| 247 |
\end{command} |
| 248 |
|
| 249 |
In order to call a method for an object, you first need to create the object |
| 250 |
and you need a handle for this object. In order to invoke a method for this |
| 251 |
object, a special syntax is used that is similar to Java or C++ syntax: |
| 252 |
|
| 253 |
\begin{pgfmanualentry} |
| 254 |
\pgfmanualentryheadline{\meta{object handle}\opt{|.|\meta{super class}}|.|\meta{method name}|(|\meta{parameters}|)|}% |
| 255 |
\pgfmanualbody |
| 256 |
This causes the method \meta{method name} to be called for the object |
| 257 |
referenced by the \meta{object handle}. The method is the one defined in |
| 258 |
the class of the object or, if it is not defined there, the method defined |
| 259 |
in the superclasses of the object's class (if there are several |
| 260 |
superclasses that define the same method, the method resolution order is |
| 261 |
used to determine which one gets called). If the optional \meta{super |
| 262 |
class} is specified, the method implementation of that class will be used |
| 263 |
rather than the implementation in the object's class. The \meta{parameters} |
| 264 |
are matched against the parameters of the method and, then, the method body |
| 265 |
is executed. The execution of the method body is \emph{not} done inside a |
| 266 |
scope, so the effects of a method body persist. |
| 267 |
% |
| 268 |
\begin{codeexample}[code only] |
| 269 |
\pgfooclass{stamp}{ |
| 270 |
% This is the class stamp |
| 271 |
|
| 272 |
\method stamp() { % The constructor |
| 273 |
} |
| 274 |
|
| 275 |
\method apply(#1,#2) { % Causes the stamp to be shown at coordinate (#1,#2) |
| 276 |
% Draw the stamp: |
| 277 |
\node [rotate=20,font=\huge] at (#1,#2) {Passed}; |
| 278 |
} |
| 279 |
} |
| 280 |
|
| 281 |
\pgfoonew \mystamp=new stamp() |
| 282 |
|
| 283 |
\begin{tikzpicture} |
| 284 |
\mystamp.apply(1,2) |
| 285 |
\mystamp.apply(3,4) |
| 286 |
\end{tikzpicture} |
| 287 |
\end{codeexample} |
| 288 |
|
| 289 |
Inside a method, you can call other methods. If you have a handle for |
| 290 |
another object, you can simply call it in the manner described above. In |
| 291 |
order to call a method of the current object, you can use the special |
| 292 |
object handle |\pgfoothis|. |
| 293 |
|
| 294 |
\begin{command}{\pgfoothis} |
| 295 |
This object handle is well-defined only when a method is being executed. |
| 296 |
There, it is then set to point to the object for which the method is |
| 297 |
being called, which allows you to call another method for the same |
| 298 |
object. |
| 299 |
% |
| 300 |
\begin{codeexample}[code only] |
| 301 |
\pgfooclass{stamp}{ |
| 302 |
% This is the class stamp |
| 303 |
|
| 304 |
\method stamp() {} |
| 305 |
|
| 306 |
\method apply(#1,#2) { |
| 307 |
\pgfoothis.shift origin(#1,#2) |
| 308 |
|
| 309 |
% Draw the stamp: |
| 310 |
\node [rotate=20,font=\huge] {Passed}; |
| 311 |
} |
| 312 |
|
| 313 |
% Private method: |
| 314 |
\method shift origin(#1,#2) { |
| 315 |
\tikzset{xshift=#1,yshift=#2} |
| 316 |
} |
| 317 |
} |
| 318 |
\end{codeexample} |
| 319 |
\end{command} |
| 320 |
\end{pgfmanualentry} |
| 321 |
|
| 322 |
\begin{command}{\pgfoosuper|(|\meta{class},\meta{object handle}|).|\meta{method name}|(|\meta{arguments}|)|} |
| 323 |
This macro gives you finer control over which method gets invoked in case |
| 324 |
of multiple inheritance. This macro calls \meta{method name} of the object |
| 325 |
specified by \meta{object handle}, but which implementation of the method |
| 326 |
is called is determined as follows: it will be the implementation in the |
| 327 |
first class (in the method resolution order) after \meta{class} that |
| 328 |
defines \meta{method name}. |
| 329 |
\end{command} |
| 330 |
|
| 331 |
|
| 332 |
\subsection{Attributes} |
| 333 |
|
| 334 |
Every object has a set of attributes, which may change over time. Attributes |
| 335 |
are declared using the |\attribute| command, which, like the |\method| command, |
| 336 |
is defined only inside the scope of |\pgfooclass|. Attributes can be modified |
| 337 |
(only) by methods. To take the |stamp| example, an attribute of a |stamp| |
| 338 |
object might be the text that should be stamped when the |apply| method is |
| 339 |
called. |
| 340 |
|
| 341 |
When an attribute is changed, this change is \emph{not} local to the current |
| 342 |
\TeX\ group. Changes will persist till the end of the object's life or until |
| 343 |
the attribute is changed once more. |
| 344 |
|
| 345 |
To declare an attribute you should use the |\attribute| command: |
| 346 |
% |
| 347 |
\begin{command}{\attribute \meta{attribute name}\opt{|=|\meta{initial value}}|;|} |
| 348 |
This command can only be given inside the body of an |\pgfooclass| command. |
| 349 |
It declares the attribute named \meta{attribute name}. This name, like |
| 350 |
method or class names, can be quite arbitrary, but should not contain |
| 351 |
periods. Valid names are |an_attribute?| or |my attribute|. |
| 352 |
|
| 353 |
You can optionally specify an \meta{initial value} for the attribute; if |
| 354 |
none is given, the empty string is used automatically. The initial value is |
| 355 |
the value that the attribute will have just after the object has been |
| 356 |
created and before the constructor is called. |
| 357 |
% |
| 358 |
\begin{codeexample}[code only] |
| 359 |
\pgfooclass{stamp}{ |
| 360 |
% This is the class stamp |
| 361 |
|
| 362 |
\attribute text; |
| 363 |
\attribute rotation angle = 20; |
| 364 |
|
| 365 |
\method stamp(#1) { |
| 366 |
\pgfooset{text}{#1} % Set the text |
| 367 |
} |
| 368 |
|
| 369 |
\method apply(#1,#2) { |
| 370 |
\pgfoothis.shift origin(#1,#2) |
| 371 |
|
| 372 |
% Draw the stamp: |
| 373 |
\node [rotate=\pgfoovalueof{rotation angle},font=\huge] |
| 374 |
{\pgfoovalueof{text}}; |
| 375 |
} |
| 376 |
|
| 377 |
\method shift origin(#1,#2) { ... } |
| 378 |
|
| 379 |
\method set rotation (#1) { |
| 380 |
\pgfooset{rotation angle}{#1} |
| 381 |
} |
| 382 |
} |
| 383 |
\end{codeexample} |
| 384 |
% |
| 385 |
\end{command} |
| 386 |
|
| 387 |
Attributes can be set and read only inside methods, it is not possible to do so |
| 388 |
using an object handle. Spoken in terms of traditional object-oriented |
| 389 |
programming, attributes are always private. You need to define getter and |
| 390 |
setter methods if you wish to read or modify attributes. |
| 391 |
|
| 392 |
Reading and writing attributes is not done using the ``dot-notation'' that is |
| 393 |
used for method calls. This is mostly due to efficiency reasons. Instead, a set |
| 394 |
of special macros is used, all of which can \emph{only be used inside methods}. |
| 395 |
|
| 396 |
\begin{command}{\pgfooset\marg{attribute}\marg{value}} |
| 397 |
Sets the \meta{attribute} of the current object to \meta{value}. |
| 398 |
% |
| 399 |
\begin{codeexample}[code only] |
| 400 |
\method set rotation (#1) { |
| 401 |
\pgfooset{rotation angle}{#1} |
| 402 |
} |
| 403 |
\end{codeexample} |
| 404 |
% |
| 405 |
\end{command} |
| 406 |
|
| 407 |
\begin{command}{\pgfooeset\marg{attribute}\marg{value}} |
| 408 |
Performs the same action as |\pgfooset| but in an |\edef| full expansion |
| 409 |
context. |
| 410 |
\end{command} |
| 411 |
|
| 412 |
\begin{command}{\pgfooappend\marg{attribute}\marg{value}} |
| 413 |
This method adds the given \meta{value} to the \meta{attribute} at the end. |
| 414 |
\end{command} |
| 415 |
|
| 416 |
\begin{command}{\pgfooprefix\marg{attribute}\marg{value}} |
| 417 |
This method adds the given \meta{value} to the \meta{attribute} at the |
| 418 |
beginning. |
| 419 |
\end{command} |
| 420 |
|
| 421 |
\begin{command}{\pgfoolet\marg{attribute}\marg{macro}} |
| 422 |
Sets the \meta{attribute} of the current value to the current value of |
| 423 |
\meta{macro} using \TeX's |\let| command. |
| 424 |
% |
| 425 |
\begin{codeexample}[code only] |
| 426 |
\method foo () { |
| 427 |
\pgfoolet{my func}\myfunc |
| 428 |
% Changing \myfunc now has no effect on the value of attribute my func |
| 429 |
} |
| 430 |
\end{codeexample} |
| 431 |
% |
| 432 |
\end{command} |
| 433 |
|
| 434 |
\begin{command}{\pgfoovalueof\marg{attribute}} |
| 435 |
Expands (eventually) to the current value of \meta{attribute} of the |
| 436 |
current object. |
| 437 |
% |
| 438 |
\begin{codeexample}[code only] |
| 439 |
\method apply(#1,#2) { |
| 440 |
\pgfoothis.shift origin(#1,#2) |
| 441 |
|
| 442 |
\node [rotate=\pgfoovalueof{rotation angle},font=\huge] |
| 443 |
{\pgfoovalueof{text}}; |
| 444 |
} |
| 445 |
\end{codeexample} |
| 446 |
% |
| 447 |
\end{command} |
| 448 |
|
| 449 |
\begin{command}{\pgfooget\marg{attribute}\marg{macro}} |
| 450 |
Reads the current value of \meta{attribute} and stores the result in |
| 451 |
\meta{macro}. |
| 452 |
% |
| 453 |
\begin{codeexample}[code only] |
| 454 |
... |
| 455 |
\method get rotation (#1) { |
| 456 |
\pgfooget{rotation angle}{#1} |
| 457 |
} |
| 458 |
... |
| 459 |
|
| 460 |
\mystamp.get rotation(\therotation) |
| 461 |
``\therotation'' is now ``20'' (or whatever). |
| 462 |
\end{codeexample} |
| 463 |
% |
| 464 |
\end{command} |
| 465 |
|
| 466 |
|
| 467 |
\subsection{Identities} |
| 468 |
\label{section-identities} |
| 469 |
|
| 470 |
Every object has a unique identity, which is simply an integer. It is possible |
| 471 |
to retrieve the object id using the |get id| method (discussed below), but |
| 472 |
normally you will not need to do so because the id itself cannot be used to |
| 473 |
access an object. Rather, you access objects via their methods and these, in |
| 474 |
turn, can only be called via object handles. |
| 475 |
|
| 476 |
Object handles can be created in four ways: |
| 477 |
% |
| 478 |
\begin{enumerate} |
| 479 |
\item Calling |\pgfoonew|\meta{object handle}|=...| will cause \meta{object |
| 480 |
handle} to be a handle to the newly created object. |
| 481 |
\item Using |\let| to create an alias of an existing object handle: If |
| 482 |
|\mystamp| is a handle, saying |\let\myotherstamp=\mystamp| creates a |
| 483 |
second handle to the same object. |
| 484 |
\item |\pgfooobj|\marg{id} can be used as an object handle to the object |
| 485 |
with the given \meta{id}. |
| 486 |
\item Using the |get handle| method to create a handle to a given object. |
| 487 |
\end{enumerate} |
| 488 |
|
| 489 |
Let us have a look at the last two methods. |
| 490 |
|
| 491 |
\begin{command}{\pgfooobj\marg{id}} |
| 492 |
Provided that \meta{id} is the id of an existing object (an object whose |
| 493 |
life-time has not expired), calling this command yields a handle to this |
| 494 |
object. The handle can then be used to call methods: |
| 495 |
% |
| 496 |
\begin{codeexample}[code only] |
| 497 |
% Create a new object: |
| 498 |
\pgfoonew \mystamp=new stamp() |
| 499 |
|
| 500 |
% Get the object's id and store it in \myid: |
| 501 |
\mystamp.get id(\myid) |
| 502 |
|
| 503 |
% The following two calls have the same effect: |
| 504 |
\mystamp.apply(1,1) |
| 505 |
\pgfooobj{\myid}.apply(1,1) |
| 506 |
\end{codeexample} |
| 507 |
% |
| 508 |
\end{command} |
| 509 |
|
| 510 |
The |get id| method can be used to retrieve the id of an object. This method is |
| 511 |
predefined for every class and you should not try to define a method of this |
| 512 |
name yourself. |
| 513 |
|
| 514 |
\begin{predefinedmethod}{get id(\meta{macro})} |
| 515 |
Calling \meta{obj}|.get id(|\meta{macro}|)| stores the id \meta{obj} in |
| 516 |
\meta{macro}. This is mainly useful when you wish to store an object for a |
| 517 |
longer time and you cannot guarantee that any handle that you happen to |
| 518 |
have for this object will be available later on. |
| 519 |
|
| 520 |
The only way to use the retrieved id later on is to call |\pgfooobj|. |
| 521 |
|
| 522 |
Different object that are alive (that are still within the scope in which |
| 523 |
they were created) will always have different ids, so you can use the id to |
| 524 |
test for equality of objects. However, after an object has been destroyed |
| 525 |
because its scope has ended, the same id may be used again for newly |
| 526 |
created objects. |
| 527 |
|
| 528 |
Here is a typical application where you need to call this method: You wish |
| 529 |
to collect a list of objects for which you wish to call a specific method |
| 530 |
from time to time. For the collection process you wish to offer a macro |
| 531 |
called |\addtoobjectlist|, which takes an object handle as parameter. It is |
| 532 |
quite easy to store this handle somewhere, but a handle is, well, just a |
| 533 |
handle. Typically, shortly after the call to |\addtoobjectlist| the handle |
| 534 |
will no longer be valid or even exist, even though the object still exists. |
| 535 |
In this case, you wish to store the object id somewhere instead of the |
| 536 |
handle. Thus, for the object passed to |\addtoobjectlist| you call the |
| 537 |
|get id| method and store the resulting id, rather than the handle. |
| 538 |
\end{predefinedmethod} |
| 539 |
|
| 540 |
There is a second predefined method, called |get handle|, which is also used to |
| 541 |
create object handles. |
| 542 |
|
| 543 |
\begin{predefinedmethod}{get handle(\marg{macro name})} |
| 544 |
Calling this method for an object will cause \meta{macro name} to become a |
| 545 |
handle to the given object. For any object handle |\obj| -- other than |
| 546 |
|\pgfoothis| -- the following two have the same effect: |
| 547 |
% |
| 548 |
\begin{enumerate} |
| 549 |
\item |\let|\meta{macro name}|=\obj| |
| 550 |
\item |\obj.get handle(|\meta{macro name}|)| |
| 551 |
\end{enumerate} |
| 552 |
|
| 553 |
The first method is simpler and faster. However, for |\pgfoothis| there is |
| 554 |
a difference: The call |\pgfoothis.get handle(|\meta{macro name}|)| will |
| 555 |
cause \meta{macro name} to be an object handle to the current object and |
| 556 |
will persist to be so even after the method is done. By comparison, |
| 557 |
|\let|\meta{macro name}|=\pgfoothis| causes |\obj| to be the same as the |
| 558 |
very special macro |\pgfoothis|, so |\obj| will always refer to the current |
| 559 |
object, which may change over time. |
| 560 |
\end{predefinedmethod} |
| 561 |
|
| 562 |
|
| 563 |
\subsection{The Object Class} |
| 564 |
\label{section-object} |
| 565 |
|
| 566 |
The object-oriented module predefines a basic class |object| that can be used |
| 567 |
as a base class in different context. |
| 568 |
|
| 569 |
\begin{ooclass}{object} |
| 570 |
This class current only implements one method: |
| 571 |
|
| 572 |
\begin{method}{copy(\meta{handle})} |
| 573 |
Creates a new object and initializes the values of its (declared) |
| 574 |
attributes to the values of the original. The method takes one |
| 575 |
argument: a control sequence which receives the handle of the copy. |
| 576 |
\end{method} |
| 577 |
\end{ooclass} |
| 578 |
|
| 579 |
|
| 580 |
\subsection{The Signal Class} |
| 581 |
\label{section-signals} |
| 582 |
|
| 583 |
In addition to the basic mechanism for defining and using classes and object, |
| 584 |
the class |signal| is predefined. It implements a so-called signal--slot |
| 585 |
mechanism. |
| 586 |
|
| 587 |
\begin{ooclass}{signal} |
| 588 |
This class is used to implement a simple signal--slot mechanism. The idea |
| 589 |
is the following: From time to time special things happen about which a |
| 590 |
number of objects need to be informed. Different things can happen and |
| 591 |
different object will be interested in these things. A |signal| object can |
| 592 |
be used to signal that such special things of a certain kind have happened. |
| 593 |
For example, one signal object might be used to signal the event that ``a |
| 594 |
page has been shipped out''. Another signal might be used to signal that |
| 595 |
``a figure is about to be typeset'', and so on. |
| 596 |
|
| 597 |
Objects can ``tune in'' to signals. They do so by \emph{connecting} one of |
| 598 |
their methods (then called a \emph{slot}) to the signal. Then, whenever the |
| 599 |
signal is \emph{emitted}, the method of the connected object(s) get called. |
| 600 |
Different objects can connect different slots to the same signal as long as |
| 601 |
the argument lists will fit. For example, the object that is used to signal |
| 602 |
the ``end of page has been reached'' might emit signals that have, say, the |
| 603 |
box number in which the finished page can be found as a parameter |
| 604 |
(actually, the finished page is always in box 255). Then one object could |
| 605 |
connect a method |handle page(#1)| to this signal, another might connect |
| 606 |
the method |emergency action(#1)| to this signal, and so on. |
| 607 |
|
| 608 |
Currently, it is not possible to ``unregister'' or ``detach'' a slot from a |
| 609 |
signal, that is, once an object has been connect to a signal, it will |
| 610 |
continue to receive emissions of this signal till the end of the life-time |
| 611 |
of the signal. This is even true when the object no longer exists (but the |
| 612 |
signal does), so care must be taken that signal objects are always created |
| 613 |
after the objects that are listening to them. |
| 614 |
|
| 615 |
\begin{method}{signal()} |
| 616 |
The constructor does nothing. |
| 617 |
\end{method} |
| 618 |
|
| 619 |
\begin{method}{connect(\meta{object handle},\meta{method name})} |
| 620 |
This method gets an \meta{object handle} as parameter and a |
| 621 |
\meta{method name} of this object. It will queue the object-method pair |
| 622 |
in an internal list and each time the signal emits something, this |
| 623 |
object's method is called. |
| 624 |
|
| 625 |
Be careful not to pass |\pgfoothis| as \meta{object handle}. This would |
| 626 |
cause the signal object to connect to itself. Rather, if you wish to |
| 627 |
connect a signal to a method of the current object you first need to |
| 628 |
create an alias using the |get handle| method: |
| 629 |
% |
| 630 |
\begin{codeexample}[code only] |
| 631 |
\pgfooclass{some class}{ |
| 632 |
\method some class() { |
| 633 |
\pgfoothis.get handle(\me) |
| 634 |
\somesignal.connect(\me,foo) |
| 635 |
\anothersignal.connect(\me,bar) |
| 636 |
} |
| 637 |
\method foo () {} |
| 638 |
\method bar (#1,#2) {} |
| 639 |
} |
| 640 |
\pgfoonew \objA=new some class() |
| 641 |
\pgfoonew \objB=new some class() |
| 642 |
\end{codeexample} |
| 643 |
\end{method} |
| 644 |
|
| 645 |
\begin{method}{emit(\meta{arguments})} |
| 646 |
This method emits a signal to all connected slots. This means that for |
| 647 |
all objects that have previously been connected via a call of |
| 648 |
|connect|, the method (slot) that was specified during the call of |
| 649 |
|connect| is invoked with given \meta{arguments}. |
| 650 |
% |
| 651 |
\begin{codeexample}[code only] |
| 652 |
\anothersignal.emit(1,2) |
| 653 |
% will call \objA.bar(1,2) and \objB.bar(1,2) |
| 654 |
\end{codeexample} |
| 655 |
\end{method} |
| 656 |
\end{ooclass} |
| 657 |
|
| 658 |
|
| 659 |
\subsection{Implementation Notes} |
| 660 |
|
| 661 |
For the curious, here are some notes on how the oo-system is implemented: |
| 662 |
% |
| 663 |
\begin{itemize} |
| 664 |
\item There is an object id counter that gets incremented each time an |
| 665 |
object is created. However, this counter is local to the current scope, |
| 666 |
which means that it is reset at the end of each scope, corresponding to |
| 667 |
the fact that at the end of a scope all objects created in this scope |
| 668 |
become invalid. Newly created objects will then have the same id as |
| 669 |
``deleted'' objects. |
| 670 |
\item Attributes are stored globally. For each attribute of each object |
| 671 |
there is a macro whose name is composed of the object's id and the |
| 672 |
attribute name. Changes to object attributes are always global. |
| 673 |
\item A call to the garbage collector causes a loop to be executed that |
| 674 |
tries to find objects whose object number is larger than the current |
| 675 |
maximum alive objects. The global attributes of these objects are then |
| 676 |
freed (set to |\relax|) by calling a special internal method of these |
| 677 |
(dead) objects. |
| 678 |
|
| 679 |
The garbage collector is automatically called after each group in |
| 680 |
which an object was created using |\aftergroup|. |
| 681 |
\item When a method is called, before the method call some code is executed |
| 682 |
that sets a global counter storing the current object id to the object |
| 683 |
id of the object being called. After the method call some code is |
| 684 |
inserted that restores the global counter to its original value. This |
| 685 |
is done without scopes, so some tricky |\expandafter| magic is needed. |
| 686 |
Note that, because of this process, you cannot use commands like |
| 687 |
|\pgfutil@ifnextchar| at the end of a method. |
| 688 |
\item An object handle contains just the code to set up and restore the |
| 689 |
current object number to the number of the object being called. |
| 690 |
\end{itemize} |