summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-oo.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-oo.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-oo.tex818
1 files changed, 403 insertions, 415 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-oo.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-oo.tex
index 7f11f1d06e0..bd1f11d01f6 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-oo.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-oo.tex
@@ -8,114 +8,104 @@
% See the file doc/generic/pgf/licenses/LICENSE for more details.
-
\section{Object-Oriented Programming}
-
\label{section-oop}
This section describes the |oo| module.
\begin{pgfmodule}{oo}
- 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 module defines a relatively small set of \TeX\ commands for defining
+ classes, methods, attributes and objects in the sense of object-oriented
+ programming.
\end{pgfmodule}
-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.
-
+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.
\subsection{Overview}
-\TeX\ 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 \TeX\ often seem overly
-complicated. The object-oriented programming module of \pgfname\ may
-help here. It is written completely using simple \TeX\ 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 \emph{classes} (in the
-object-oriented sense, this has nothing to do with \LaTeX-classes),
-\emph{methods}, \emph{constructors}, \emph{attributes},
-\emph{objects}, \emph{object identities}, and (thanks to Sa\v o \v
-Zivanovi\'c) \emph{inheritance} and \emph{overloading.}
-
-The first step is to define a class, using the macro |\pgfooclass|
-(all normal macros in \pgfname's object-oriented system start with
-|\pgfoo|). This macro gets the name of a class and in its body a
-number of \emph{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 \emph{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 \TeX\ 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.
+\TeX\ 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 \TeX\ often seem overly complicated. The object-oriented
+programming module of \pgfname\ may help here. It is written completely using
+simple \TeX\ 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 \emph{classes} (in the object-oriented sense,
+this has nothing to do with \LaTeX-classes), \emph{methods},
+\emph{constructors}, \emph{attributes}, \emph{objects}, \emph{object
+identities}, and (thanks to Sa\v o \v Zivanovi\'c) \emph{inheritance} and
+\emph{overloading.}
+
+The first step is to define a class, using the macro |\pgfooclass| (all normal
+macros in \pgfname's object-oriented system start with |\pgfoo|). This macro
+gets the name of a class and in its body a number of \emph{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
+\emph{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 \TeX\ 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.
+
\subsection{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.
+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 \pgfname\ 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 \pgfname).
+Such stamps are similar to many things present in \pgfname\ 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 \pgfname).
\subsection{Classes}
-We start with the definition of the |stamp| class. This is done using
-the |\pgfooclass| macro:
+We start with the definition of the |stamp| class. This is done using the
+|\pgfooclass| macro:
\begin{command}{\pgfooclass\opt{|(|\meta{list of superclasses}|)|}\marg{class name}\marg{body}}
- This command defines a class named \meta{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 \meta{list of superclasses} is
- optional just like the parenthesis around it.
-
- The \meta{body} is actually just executed, so any
- normal \TeX-code is permissible here. However, while the \meta{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 command defines a class named \meta{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
+ \meta{list of superclasses} is optional just like the parenthesis around
+ it.
+
+ The \meta{body} is actually just executed, so any normal \TeX-code is
+ permissible here. However, while the \meta{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.
+ %
\begin{codeexample}[code only]
\pgfooclass{stamp}{
% This is the class stamp
@@ -135,47 +125,45 @@ the |\pgfooclass| macro:
% We can now create objects of type "stamp"
\end{codeexample}
- Concerning the list of base classes, the Method Resolution Order
- (\textsc{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 \textsc{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 \textsc{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 \textsc{mro}
- of $C$ which declares attribute |attr|.
+ Concerning the list of base classes, the Method Resolution Order
+ (\textsc{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 \textsc{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 \textsc{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 \textsc{mro} of $C$ which
+ declares attribute |attr|.
\end{command}
The \meta{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.
-
+|\attribute| and |\method|, which will be discussed in more detail in later
+sections.
\subsection{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:
+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:
-\begin{command}{\pgfoonew\opt{\meta{object handle or attribute}|=|}|new |\meta{class
- name}|(|\meta{constructor arguments}|)|}
- Causes a new object to be created. The class of the object will be
- \meta{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
- \meta{constructor arguments}.
+\begin{command}{\pgfoonew\opt{\meta{object handle or attribute}|=|}|new |\meta{class name}|(|\meta{constructor arguments}|)|}
+ Causes a new object to be created. The class of the object will be
+ \meta{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 \meta{constructor
+ arguments}.
- The resulting object is stored internally and its lifetime will
- end exactly at the end of the current scope.
+ 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.
+ Here is an example in which three stamp objects are created.
+ %
\begin{codeexample}[code only]
-\pgfoonew \firststamp = new stamp()
-\pgfoonew \secondstamp = new stamp()
+\pgfoonew \firststamp=new stamp()
+\pgfoonew \secondstamp=new stamp()
{
- \pgfoonew \thirdstamp = new stamp()
+ \pgfoonew \thirdstamp=new stamp()
...
}
% \thirdstamp no longer exists, but \firststamp and \secondstamp do
@@ -183,108 +171,100 @@ peculiar syntax:
% to access it will result in an error.
\end{codeexample}
- The optional \meta{object handle or attribute} can either be an
- \meta{object handle} or an \meta{attribute}. When an \meta{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~\ref{section-identities}). You can use this macro to call
- methods of the object as discussed in the following section. When an
- \meta{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.
+ The optional \meta{object handle or attribute} can either be an
+ \meta{object handle} or an \meta{attribute}. When an \meta{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~\ref{section-identities}). You can use this macro to call methods
+ of the object as discussed in the following section. When an
+ \meta{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.
+ %
\begin{codeexample}[code only]
\pgfooclass{foo}
{
\attribute stamp obj;
\attribute another object;
- \method \foo() {
+ \method foo() {
\pgfoonew{stamp obj}=new stamp()
\pgfoonew{another object}=new bar()
}
...
}
\end{codeexample}
+ %
\end{command}
\begin{command}{\pgfoogc}
- 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 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.
\end{command}
\subsection{Methods}
-Methods are defined inside the body of classes using the following
-command:
+Methods are defined inside the body of classes using the following command:
\begin{command}{\method \meta{method name}|(|\meta{parameter list}|)|\marg{method body}}
- This macro, which is only defined inside a class definition, defines
- a new method named \meta{method name}. Just like class names, method
- names can contain spaces and other characters, so \meta{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
- \emph{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~\ref{section-identities}.
-
- 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 \meta{method name} must be followed by a \meta{parameter list}
- in parentheses, which must be present even when the \meta{parameter
- list} is empty. The \meta{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 \meta{body} of
- the method will be executed. The main difference to a normal macro
- is that while the \meta{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 macro, which is only defined inside a class definition, defines a new
+ method named \meta{method name}. Just like class names, method names can
+ contain spaces and other characters, so \meta{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 \emph{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~\ref{section-identities}.
+
+ 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 \meta{method name} must be followed by a \meta{parameter list} in
+ parentheses, which must be present even when the \meta{parameter list} is
+ empty. The \meta{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 \meta{body} of the method will be executed.
+ The main difference to a normal macro is that while the \meta{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.
\end{command}
-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:
+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:
\begin{pgfmanualentry}
- \pgfmanualentryheadline{\meta{object handle}\opt{|.|\meta{super
- class}}|.|\meta{method name}|(|\meta{parameters}|)|}%
- \pgfmanualbody
- This causes the method \meta{method name} to be called for the
- object referenced by the \meta{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 \meta{super class} is specified, the method
- implementation of that class will be used rather than the
- implementation in the object's class. The \meta{parameters}
- are matched against the parameters of the method and, then, the
- method body is executed. The execution of the method body is
- \emph{not} done inside a scope, so the effects of a method body
- persist.
-
+ \pgfmanualentryheadline{\meta{object handle}\opt{|.|\meta{super class}}|.|\meta{method name}|(|\meta{parameters}|)|}%
+ \pgfmanualbody
+ This causes the method \meta{method name} to be called for the object
+ referenced by the \meta{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 \meta{super
+ class} is specified, the method implementation of that class will be used
+ rather than the implementation in the object's class. The \meta{parameters}
+ are matched against the parameters of the method and, then, the method body
+ is executed. The execution of the method body is \emph{not} done inside a
+ scope, so the effects of a method body persist.
+ %
\begin{codeexample}[code only]
\pgfooclass{stamp}{
% This is the class stamp
@@ -306,17 +286,17 @@ Java or C++ syntax:
\end{tikzpicture}
\end{codeexample}
- 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|.
-
- \begin{command}{\pgfoothis}
- This object handle is defined only when a method is being
- executed. There, it is then set to point to the object for which
- the method is being called, which allows you to call another
- method for the same object.
-
+ 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|.
+
+ \begin{command}{\pgfoothis}
+ This object handle is well-defined only when a method is being executed.
+ There, it is then set to point to the object for which the method is
+ being called, which allows you to call another method for the same
+ object.
+ %
\begin{codeexample}[code only]
\pgfooclass{stamp}{
% This is the class stamp
@@ -336,49 +316,45 @@ Java or C++ syntax:
}
}
\end{codeexample}
- \end{command}
+ \end{command}
\end{pgfmanualentry}
-
-\begin{command}{\pgfoosuper|(|\meta{class},\meta{object
- handle}|).|\meta{method name}|(|\meta{arguments}|)|}
- This macro gives you finer control over which method gets invoked in
- case of multiple inheritance. This macro calls \meta{method name} of
- the object specified by \meta{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 \meta{class} that defines \meta{method
- name}.
+\begin{command}{\pgfoosuper|(|\meta{class},\meta{object handle}|).|\meta{method name}|(|\meta{arguments}|)|}
+ This macro gives you finer control over which method gets invoked in case
+ of multiple inheritance. This macro calls \meta{method name} of the object
+ specified by \meta{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 \meta{class} that
+ defines \meta{method name}.
\end{command}
+
\subsection{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.
+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 \emph{not} local to the
-current \TeX\ group. Changes will persist till the end
-of the object's life or until the attribute is changed once more.
+When an attribute is changed, this change is \emph{not} local to the current
+\TeX\ 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:
-\begin{command}{\attribute \meta{attribute name}\opt{|=|\meta{initial
- value}}|;|}
- This command can only be given inside the body of an |\pgfooclass|
- command. It declares the attribute named \meta{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 \meta{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.
-
+%
+\begin{command}{\attribute \meta{attribute name}\opt{|=|\meta{initial value}}|;|}
+ This command can only be given inside the body of an |\pgfooclass| command.
+ It declares the attribute named \meta{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 \meta{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.
+ %
\begin{codeexample}[code only]
\pgfooclass{stamp}{
% This is the class stamp
@@ -405,43 +381,60 @@ To declare an attribute you should use the |\attribute| command:
}
}
\end{codeexample}
+ %
\end{command}
-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.
+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
-\emph{only be used inside methods}.
+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 \emph{only be used inside methods}.
\begin{command}{\pgfooset\marg{attribute}\marg{value}}
- Sets the \meta{attribute} of the current object to
- \meta{value}.
+ Sets the \meta{attribute} of the current object to \meta{value}.
+ %
\begin{codeexample}[code only]
\method set rotation (#1) {
\pgfooset{rotation angle}{#1}
}
\end{codeexample}
+ %
+\end{command}
+
+\begin{command}{\pgfooeset\marg{attribute}\marg{value}}
+ Performs the same action as |\pgfooset| but in an |\edef| full expansion
+ context.
+\end{command}
+
+\begin{command}{\pgfooappend\marg{attribute}\marg{value}}
+ This method adds the given \meta{value} to the \meta{attribute} at the end.
+\end{command}
+
+\begin{command}{\pgfooprefix\marg{attribute}\marg{value}}
+ This method adds the given \meta{value} to the \meta{attribute} at the
+ beginning.
\end{command}
\begin{command}{\pgfoolet\marg{attribute}\marg{macro}}
- Sets the \meta{attribute} of the current value to the current value
- of \meta{macro} using \TeX's |\let| command.
+ Sets the \meta{attribute} of the current value to the current value of
+ \meta{macro} using \TeX's |\let| command.
+ %
\begin{codeexample}[code only]
\method foo () {
\pgfoolet{my func}\myfunc
% Changing \myfunc now has no effect on the value of attribute my func
}
\end{codeexample}
+ %
\end{command}
\begin{command}{\pgfoovalueof\marg{attribute}}
- Expands (eventually) to the current value of \meta{attribute} of
- the current object.
+ Expands (eventually) to the current value of \meta{attribute} of the
+ current object.
+ %
\begin{codeexample}[code only]
\method apply(#1,#2) {
\pgfoothis.shift origin(#1,#2)
@@ -450,11 +443,13 @@ reasons. Instead, a set of special macros is used, all of which can
{\pgfoovalueof{text}};
}
\end{codeexample}
+ %
\end{command}
\begin{command}{\pgfooget\marg{attribute}\marg{macro}}
- Reads the current value of \meta{attribute} and stores the result in
- \meta{macro}.
+ Reads the current value of \meta{attribute} and stores the result in
+ \meta{macro}.
+ %
\begin{codeexample}[code only]
...
\method get rotation (#1) {
@@ -465,37 +460,39 @@ reasons. Instead, a set of special macros is used, all of which can
\mystamp.get rotation(\therotation)
``\therotation'' is now ``20'' (or whatever).
\end{codeexample}
+ %
\end{command}
\subsection{Identities}
\label{section-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.
+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:
+%
\begin{enumerate}
-\item Calling |\pgfoonew|\meta{object handle}|=...| will cause
- \meta{object handle} to be a handle to the newly created object.
-\item 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.
-\item |\pgfooobj|\marg{id} can be used as an object handle to the
- object with the given \meta{id}.
-\item Using the |get handle| method to create a handle to a given object.
+ \item Calling |\pgfoonew|\meta{object handle}|=...| will cause \meta{object
+ handle} to be a handle to the newly created object.
+ \item 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.
+ \item |\pgfooobj|\marg{id} can be used as an object handle to the object
+ with the given \meta{id}.
+ \item Using the |get handle| method to create a handle to a given object.
\end{enumerate}
Let us have a look at the last two methods.
\begin{command}{\pgfooobj\marg{id}}
- Provided that \meta{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:
+ Provided that \meta{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:
+ %
\begin{codeexample}[code only]
% Create a new object:
\pgfoonew \mystamp=new stamp()
@@ -507,137 +504,129 @@ Let us have a look at the last two methods.
\mystamp.apply(1,1)
\pgfooobj{\myid}.apply(1,1)
\end{codeexample}
+ %
\end{command}
-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.
+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.
\begin{predefinedmethod}{get id(\meta{macro})}
- Calling \meta{obj}|.get id(|\meta{macro}|)| stores the id \meta{obj} in
- \meta{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 \meta{obj}|.get id(|\meta{macro}|)| stores the id \meta{obj} in
+ \meta{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.
\end{predefinedmethod}
-There is a second predefined method, called |get handle|, which is also
-used to create object handles.
+There is a second predefined method, called |get handle|, which is also used to
+create object handles.
\begin{predefinedmethod}{get handle(\marg{macro name})}
- Calling this method for an object will cause \meta{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:
- \begin{enumerate}
- \item |\let|\meta{macro name}|=\obj|
- \item |\obj.get handle(|\meta{macro name}|)|
- \end{enumerate}
-
- The first method is simpler and faster. However, for |\pgfoothis|
- there is a difference: The call |\pgfoothis.get handle(|\meta{macro name}|)| will
- cause \meta{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|\meta{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.
+ Calling this method for an object will cause \meta{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:
+ %
+ \begin{enumerate}
+ \item |\let|\meta{macro name}|=\obj|
+ \item |\obj.get handle(|\meta{macro name}|)|
+ \end{enumerate}
+
+ The first method is simpler and faster. However, for |\pgfoothis| there is
+ a difference: The call |\pgfoothis.get handle(|\meta{macro name}|)| will
+ cause \meta{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|\meta{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.
\end{predefinedmethod}
-
-
\subsection{The Object Class}
-
\label{section-object}
-The object-oriented module predefines a basic class |object| that can
-be used as a base class in different context.
+The object-oriented module predefines a basic class |object| that can be used
+as a base class in different context.
\begin{ooclass}{object}
- This class current only implements one method:
-
- \begin{method}{copy(\meta{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.
- \end{method}
+ This class current only implements one method:
+
+ \begin{method}{copy(\meta{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.
+ \end{method}
\end{ooclass}
\subsection{The Signal Class}
-
\label{section-signals}
-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.
+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.
\begin{ooclass}{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 \emph{connecting}
- one of their methods (then called a \emph{slot}) to the
- signal. Then, whenever the signal is \emph{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 before the objects that are
- listening to them.
-
- \begin{method}{signal()}
- The constructor does nothing.
- \end{method}
-
- \begin{method}{connect(\meta{object handle},\meta{method name})}
- This method gets an \meta{object handle} as parameter and a
- \meta{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 \meta{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:
+ 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 \emph{connecting} one of
+ their methods (then called a \emph{slot}) to the signal. Then, whenever the
+ signal is \emph{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.
+
+ \begin{method}{signal()}
+ The constructor does nothing.
+ \end{method}
+
+ \begin{method}{connect(\meta{object handle},\meta{method name})}
+ This method gets an \meta{object handle} as parameter and a
+ \meta{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 \meta{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:
+ %
\begin{codeexample}[code only]
\pgfooclass{some class}{
\method some class() {
@@ -651,52 +640,51 @@ signal--slot mechanism.
\pgfoonew \objA=new some class()
\pgfoonew \objB=new some class()
\end{codeexample}
- \end{method}
-
- \begin{method}{emit(\meta{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 \meta{arguments}.
+ \end{method}
+
+ \begin{method}{emit(\meta{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 \meta{arguments}.
+ %
\begin{codeexample}[code only]
\anothersignal.emit(1,2)
% will call \objA.bar(1,2) and \objB.bar(1,2)
\end{codeexample}
- \end{method}
+ \end{method}
\end{ooclass}
\subsection{Implementation Notes}
-For the curious, here are some notes on how the oo-system is
-implemented:
-
+For the curious, here are some notes on how the oo-system is implemented:
+%
\begin{itemize}
-\item 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.
-\item 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.
-\item 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|.
-\item 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.
-\item An object handle contains just the code to set up and restore the
- current object number to the number of the object being called.
+ \item 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.
+ \item 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.
+ \item 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|.
+ \item 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.
+ \item An object handle contains just the code to set up and restore the
+ current object number to the number of the object being called.
\end{itemize}