%---------------- Functions ------------

\chapter{Popstring.mui/Popstring.mui}
\rule{\textwidth}{1mm}
\vspace{0.5cm}
\begin{deflist}{MMMMMMMM}
\item[\bf FUNCTION]
Popstring class is the base class for creating so called
popup objects. Usually, a popup consists of a string or
text gadget, followed by a little button. Pressing this
button brings up a little window with a listview and lets
the user choose an entry with the mouse.

Popstring class features the basic functions for creating
such objects. Given a string object and a button object,
it places them horizontally and sets up some notification.
Whenever the popup button is pressed, a hook will be called
which itself should open and prepare the popup window.

The string and the button object are not created by popstring
class, they have to be supplied as attributes during object
creation time. This makes popstring class very flexible,
one could e.g. use a text object instead of a string or
a popup button with some text in it.

However, creating simple popups with popstring class would
be too much overhead. Instead of using it directly, you
should have a look at one of its subclasses. They offer
a more specialized set of popups and are a lot easier
to use.
\end{deflist}


\subsection{Popstring.mui/MUIA\_Popstring\_Button}
\rule{\textwidth}{1mm}
\vspace{0.5cm}
\begin{deflist}{MMMMMMMM}
\item[\bf NAME]
\begin{description}
\item[MUIA\_Popstring\_Button]  -- (V7 ) [I.G], Object *
\end{description}

\item[\bf FUNCTION]
Specify the button object to be used in the popup. Depending
on the type of your popup, you should use an image button
with MUII\_PopUp, MUII\_PopFile or MUII\_PopDrawer here.
However, its also possible to have a button with some
text or other things in it.

When the popstring object is disposed, the string
and the button objects are disposed as well.

\item[\bf EXAMPLE]
\begin{flushleft}
\begin{verbatim}
pop = PopstringObject,
   MUIA_Popstring_String, KeyString(0,60,'n'),
   MUIA_Popstring_Button, PopButton(MUII_PopUp),
   MUIA_Popstring_OpenHook, &OpenHook,
   MUIA_Popstring_CloseHook, &CloseHook,
   End;
\end{verbatim}
\end{flushleft}
\item[\bf SEE ALSO]
MUIA\_Popstring\_String, MUIA\_Popstring\_OpenHook, MUIA\_Popstring\_CloseHook
\end{deflist}


\subsection{Popstring.mui/MUIA\_Popstring\_CloseHook}
\rule{\textwidth}{1mm}
\vspace{0.5cm}
\begin{deflist}{MMMMMMMM}
\item[\bf NAME]
\begin{description}
\item[MUIA\_Popstring\_CloseHook]  -- (V7 ) [ISG], struct Hook *
\end{description}

\item[\bf FUNCTION]
Whenever the popup receives a MUIM\_Popstring\_Close method and
the popup is currently opened, this hook will be called.
It will receive a pointer to itself in register A0, a pointer
to the complete popup object in A2 and a pointer to a
struct
\{
   Object *stringobject;
   LONG success;
\},
in A1. The success parameter is a copy of the methods success
parameter and indicates whether the popup was closed successfully
(e.g. with a double click in a listview) or was just cancelled
(e.g. by pressing the popup button again for toggle popups).

Due to internal message handling issues, calling the close hook is
delayed until the next MUIM\_HandleInput method is called. This
allows you to remove and dispose windows without danger.

\item[\bf SEE ALSO]
MUIA\_Popstring\_OpenHook, MUIM\_Popstring\_Open, MUIM\_Popstring\_Close
\end{deflist}


\subsection{Popstring.mui/MUIA\_Popstring\_OpenHook}
\rule{\textwidth}{1mm}
\vspace{0.5cm}
\begin{deflist}{MMMMMMMM}
\item[\bf NAME]
\begin{description}
\item[MUIA\_Popstring\_OpenHook]  -- (V7 ) [ISG], struct Hook *
\end{description}

\item[\bf FUNCTION]
Whenever the popup receives a MUIM\_Popstring\_Open method,
this hook will be called. It will receive a pointer to itself in
register A0, a pointer to the complete popup object in A2 and
a pointer to a pointer (!) to the string object contained in
the popup object in A1.

When this hook returns TRUE, MUI assumes the popup was opened
succesfully and will disabled the popup button (as long as
MUIA\_Popstring\_Toggle is not set). Return FALSE to indicate
that something went wrong and the popup could not be opened.

\item[\bf SEE ALSO]
MUIA\_Popstring\_CloseHook, MUIM\_Popstring\_Open, MUIM\_Popstring\_Close
\end{deflist}


\subsection{Popstring.mui/MUIA\_Popstring\_String}
\rule{\textwidth}{1mm}
\vspace{0.5cm}
\begin{deflist}{MMMMMMMM}
\item[\bf NAME]
\begin{description}
\item[MUIA\_Popstring\_String]  -- (V7 ) [I.G], Object *
\end{description}

\item[\bf FUNCTION]
Specify the string object to be used in the popup.
This does not necessarily need to be a real string
object, using text objects or even complete groups
of other objects is perfectly ok.

When the popstring object is disposed, the string
and the button objects are disposed as well.

\item[\bf EXAMPLE]
\begin{flushleft}
\begin{verbatim}
pop = PopstringObject,
   MUIA_Popstring_String, KeyString(0,60,'n'),
   MUIA_Popstring_Button, PopButton(MUII_PopUp),
   MUIA_Popstring_OpenHook, &OpenHook,
   MUIA_Popstring_CloseHook, &CloseHook,
   End;
\end{verbatim}
\end{flushleft}
\item[\bf SEE ALSO]
MUIA\_Popstring\_Button, MUIA\_Popstring\_OpenHook, MUIA\_Popstring\_CloseHook
\end{deflist}


\subsection{Popstring.mui/MUIA\_Popstring\_Toggle}
\rule{\textwidth}{1mm}
\vspace{0.5cm}
\begin{deflist}{MMMMMMMM}
\item[\bf NAME]
\begin{description}
\item[MUIA\_Popstring\_Toggle]  -- (V7 ) [ISG], BOOL
\end{description}

\item[\bf FUNCTION]
Set/Clear the toggle mode for a popstring object.
With toggling disabled, the popup button will get
disabled whenever the user hits it and the popup
opens. With toggling enabled, the popup button
always stays enabled and can be used to cancel
(== close with a FALSE return value) the popup.

\item[\bf SEE ALSO]
MUIA\_Popstring\_OpenHook
\end{deflist}


\subsection{Popstring.mui/MUIM\_Popstring\_Close}
\rule{\textwidth}{1mm}
\vspace{0.5cm}
\begin{deflist}{MMMMMMMM}
\item[\bf NAME]
MUIM\_Popstring\_Close (V7 )

\item[\bf SYNOPSIS]
\begin{flushleft}
\begin{verbatim}
DoMethod(obj,MUIM_Popstring_Close,LONG result);
\end{verbatim}
\end{flushleft}
\item[\bf FUNCTION]
This method closes the popup. In fact, it only calls the
predefined MUIA\_Popstring\_CloseHook with the supplied
success parameter.

\item[\bf EXAMPLE]
\begin{flushleft}
\begin{verbatim}
DoMethod(poplist,MUIM_Notify,MUIA_Listview_DoubeClick,TRUE,
   popobj,2,MUIM_Popstring_Close,TRUE);
\end{verbatim}
\end{flushleft}
\end{deflist}


\subsection{Popstring.mui/MUIM\_Popstring\_Open}
\rule{\textwidth}{1mm}
\vspace{0.5cm}
\begin{deflist}{MMMMMMMM}
\item[\bf NAME]
MUIM\_Popstring\_Open (V7 )

\item[\bf SYNOPSIS]
\begin{flushleft}
\begin{verbatim}
DoMethod(obj,MUIM_Popstring_Open,);
\end{verbatim}
\end{flushleft}
\item[\bf FUNCTION]
This method opens the popup. In fact, it only calls the
predefined MUIA\_Popstring\_OpenHook and checks its return
value. In case of TRUE, the popup button object is disabled
as long as MUIA\_Popstring\_Toggle is unset.

If the toggle mode is enabled, using MUIA\_Popstring\_Open on
a currently opened popup will result in closing this popup
(i.e. calling the close hook) with a success value of FALSE.

\item[\bf EXAMPLE]
\begin{flushleft}
\begin{verbatim}
DoMethod(popbutton,MUIM_Notify,MUIA_Pressed,FALSE,
   popobj,1,MUIM_Popstring_Open);
\end{verbatim}
\end{flushleft}
\end{deflist}


%---------------- End of File ----------