Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-oo.tex

raw
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}