1\begin{page}{HTXAdvPage4}{Patch and Paste}
2\centerline{\fbox{{\tt \thispage}}}\newline
3\begin{scroll}
4
5
6A powerful \HyperName{} feature is
7the ability to {\it replace}
8part of a displayed page with another part
9when an active area is clicked. The group commands
10{\it patch} and {\it paste} offer this facility.
11A {\it paste} region can appear anywhere
12within a page or a {\it patch}. A {\it patch} region must be defined
13outside a page definition.
14
15We need a few  objects to define the {\it paste}
16region. These are a {\it name} with which to
17refer to it, some way of specifying what it
18is to be replaced by and a {\it trigger} for the
19replacement. A {\it patch} is how we specify the
20second of these objects.
21The {\it patch} is generally a sequence of \HyperName{}
22text.
23
24If we want to have the option of returning to the original
25(or ,indeed, proceeding to a {\it third} alternative)
26we clearly must include a {\it paste} in the {\it patch}.
27
28Let us start with a simple example. We wish to
29have the word {\tt initial} somewhere on the page replaced by the
30word {\tt final} at a click of a button.
31Let us first define the {\it patch}. It will just contain
32the word {\tt final}. Here is a definition of a
33patch called {\tt patch1} (note that
34the actual definition must be outside this page's definition).
35\beginImportant
36\newline
37{\tt \\begin\{patch\}\{patch1\}} \newline
38{\tt final}\newline
39{\tt \\end\{patch\}}
40\endImportant
41We now define a {\it paste} region exactly where we
42want the word {\tt initial} to appear.
43\beginImportant
44\newline
45{\tt \\begin\{paste\}\{paste1\}\{patch1\}}\newline
46{\tt initial}\newline
47{\tt \\end\{paste\}}
48\centerline{{\it results in}}
49\begin{paste}{paste1}{patch1}
50initial
51\end{paste}
52\endImportant
53We have specified first the name of the {\it paste} region
54which is {\tt paste1} and then the name of the
55replacement {\it patch} which is {\tt patch1}.
56Something is missing -- the trigger.
57To include a trigger we write
58\beginImportant
59\newline
60{\tt \\pastebutton\{paste1\}\{trigger\}
61\centerline{{\it results in}}
62\pastebutton{paste1}{trigger}
63\endImportant
64This new command {\tt \\pastebutton} displays the second argument
65as an active area. The first argument specifies the {\it paste}
66region it refers to. Clicking on {\tt trigger} above will
67replace the word {\tt initial} with the word {\tt final}.
68
69We can, if we like, include the {\tt \\pastebutton} in the {\it paste}
70region.
71Let us improve on the situation by providing a way
72of going back to the original word {\tt initial} on the page.
73The {\it patch} must itself include a {\it paste}.
74What will the replacement {\it patch} for this new {\it paste}
75be ? Well, we  have to define a second {\it patch}
76that contains all the stuff in the original {\it paste}
77region. Here is the updated {\it patch} for the first replacement.
78The {\tt \\MenuDotBitmap} macro is defined in {\bf util.ht}.
79It displays a button bitmap.
80This time we put the {\tt \\pastebutton}
81inside the {\it paste}.
82\beginImportant
83\newline
84{\tt \\begin\{patch\}\{Patch1\}}\newline
85{\tt \\begin\{paste\}\{Paste2\}\{Patch2\}}\newline
86{\tt \\pastebutton\{Paste2\}\{\\MenuDotBitmap\}}\newline
87{\tt final}\newline
88{\tt \\end\{paste\}}\newline
89{\tt \\end\{patch\}}\newline
90\endImportant
91and the new {\tt Patch2} {\it patch}
92\beginImportant
93\newline
94{\tt \\begin\{patch\}\{Patch2\}}\newline
95{\tt \\begin\{paste\}\{Paste3\}\{Patch1\}}\newline
96{\tt \\pastebutton\{Paste3\}\{\\MenuDotBitmap\}}\newline
97{\tt initial}\newline
98{\tt \\end\{paste\}}\newline
99{\tt \\end\{patch\}}\newline
100\endImportant
101
102Remember that these {\it patch} definitions must
103occur outside a {\tt \\begin\{page\} - \\end\{page\}} group.
104What is left now is to define the starting {\it paste}
105region.
106\beginImportant
107\newline
108{\tt \\begin\{paste\}\{Paste1\}\{Patch1\}}\newline
109{\tt \\pastebutton\{Paste1\}\{\\MenuDotBitmap\}}\newline
110{\tt initial}\newline
111{\tt \\end\{paste\}}
112\centerline{{\it results in}}
113\begin{paste}{Paste1}{Patch1}
114\pastebutton{Paste1}{\MenuDotBitmap}
115initial
116\end{paste}
117\endImportant
118
119Clicking on the button above next to {\tt initial}
120will replace the {\tt Paste1} region with
121{\tt Patch1}. That {\it patch}
122also contains a {\it paste} region ({\tt Paste2}).
123Clicking on {\it its} button will put up
124{\tt Patch2} which has a {\it paste} region ({\tt Paste3}).
125Clicking on {\it its} button will put up {\tt Patch1}
126again. In that way, we close the chain of replacements.
127
128
129
130
131\end{scroll}
132\beginmenu
133\menulink{Next Page --- \Language{} paste-ins}{HTXAdvPage5}
134\endmenu
135
136\end{page}
137
138
139
140
141\begin{patch}{patch1}
142final
143\end{patch}
144
145\begin{patch}{Patch1}
146\begin{paste}{Paste2}{Patch2}
147\pastebutton{Paste2}{\MenuDotBitmap}
148final
149\end{paste}
150\end{patch}
151
152\begin{patch}{Patch2}
153\begin{paste}{Paste3}{Patch1}
154\pastebutton{Paste3}{\MenuDotBitmap}
155initial
156\end{paste}
157\end{patch}
158