\begin{page}{HTXAdvPage4}{Patch and Paste}
\centerline{\fbox{{\tt \thispage}}}\newline
\begin{scroll}


A powerful \HyperName{} feature is
the ability to {\it replace}
part of a displayed page with another part
when an active area is clicked. The group commands
{\it patch} and {\it paste} offer this facility.
A {\it paste} region can appear anywhere
within a page or a {\it patch}. A {\it patch} region must be defined
outside a page definition.

We need a few  objects to define the {\it paste}
region. These are a {\it name} with which to
refer to it, some way of specifying what it
is to be replaced by and a {\it trigger} for the
replacement. A {\it patch} is how we specify the
second of these objects.
The {\it patch} is generally a sequence of \HyperName{}
text.

If we want to have the option of returning to the original
(or ,indeed, proceeding to a {\it third} alternative)
we clearly must include a {\it paste} in the {\it patch}.

Let us start with a simple example. We wish to
have the word {\tt initial} somewhere on the page replaced by the
word {\tt final} at a click of a button.
Let us first define the {\it patch}. It will just contain
the word {\tt final}. Here is a definition of a
patch called {\tt patch1} (note that
the actual definition must be outside this page's definition).
\beginImportant
\newline
{\tt \\begin\{patch\}\{patch1\}} \newline
{\tt final}\newline
{\tt \\end\{patch\}}
\endImportant
We now define a {\it paste} region exactly where we
want the word {\tt initial} to appear.
\beginImportant
\newline
{\tt \\begin\{paste\}\{paste1\}\{patch1\}}\newline
{\tt initial}\newline
{\tt \\end\{paste\}}
\centerline{{\it results in}}
\begin{paste}{paste1}{patch1}
initial
\end{paste}
\endImportant
We have specified first the name of the {\it paste} region
which is {\tt paste1} and then the name of the
replacement {\it patch} which is {\tt patch1}.
Something is missing -- the trigger.
To include a trigger we write
\beginImportant
\newline
{\tt \\pastebutton\{paste1\}\{trigger\}
\centerline{{\it results in}}
\pastebutton{paste1}{trigger}
\endImportant
This new command {\tt \\pastebutton} displays the second argument
as an active area. The first argument specifies the {\it paste}
region it refers to. Clicking on {\tt trigger} above will
replace the word {\tt initial} with the word {\tt final}.

We can, if we like, include the {\tt \\pastebutton} in the {\it paste}
region.
Let us improve on the situation by providing a way
of going back to the original word {\tt initial} on the page.
The {\it patch} must itself include a {\it paste}.
What will the replacement {\it patch} for this new {\it paste}
be ? Well, we  have to define a second {\it patch}
that contains all the stuff in the original {\it paste}
region. Here is the updated {\it patch} for the first replacement.
The {\tt \\MenuDotBitmap} macro is defined in {\bf util.ht}.
It displays a button bitmap.
This time we put the {\tt \\pastebutton}
inside the {\it paste}.
\beginImportant
\newline
{\tt \\begin\{patch\}\{Patch1\}}\newline
{\tt \\begin\{paste\}\{Paste2\}\{Patch2\}}\newline
{\tt \\pastebutton\{Paste2\}\{\\MenuDotBitmap\}}\newline
{\tt final}\newline
{\tt \\end\{paste\}}\newline
{\tt \\end\{patch\}}\newline
\endImportant
and the new {\tt Patch2} {\it patch}
\beginImportant
\newline
{\tt \\begin\{patch\}\{Patch2\}}\newline
{\tt \\begin\{paste\}\{Paste3\}\{Patch1\}}\newline
{\tt \\pastebutton\{Paste3\}\{\\MenuDotBitmap\}}\newline
{\tt initial}\newline
{\tt \\end\{paste\}}\newline
{\tt \\end\{patch\}}\newline
\endImportant

Remember that these {\it patch} definitons must
occur outside a {\tt \\begin\{page\} - \\end\{page\}} group.
What is left now is to define the starting {\it paste}
region.
\beginImportant
\newline
{\tt \\begin\{paste\}\{Paste1\}\{Patch1\}}\newline
{\tt \\pastebutton\{Paste1\}\{\\MenuDotBitmap\}}\newline
{\tt initial}\newline
{\tt \\end\{paste\}}
\centerline{{\it results in}}
\begin{paste}{Paste1}{Patch1}
\pastebutton{Paste1}{\MenuDotBitmap}
initial
\end{paste}
\endImportant

Clicking on the button above next to {\tt initial}
will replace the {\tt Paste1} region with
{\tt Patch1}. That {\it patch}
also contains a {\it paste} region ({\tt Paste2}).
Clicking on {\it its} button will put up
{\tt Patch2} which has a {\it paste} region ({\tt Paste3}).
Clicking on {\it its} button will put up {\tt Patch1}
again. In that way, we close the chain of replacements.




\end{scroll}
\beginmenu
\menulink{Next Page --- \Language{} paste-ins}{HTXAdvPage5}
\endmenu

\end{page}




\begin{patch}{patch1}
final
\end{patch}

\begin{patch}{Patch1}
\begin{paste}{Paste2}{Patch2}
\pastebutton{Paste2}{\MenuDotBitmap}
final
\end{paste}
\end{patch}

\begin{patch}{Patch2}
\begin{paste}{Paste3}{Patch1}
\pastebutton{Paste3}{\MenuDotBitmap}
initial
\end{paste}
\end{patch}