%D \module
%D   [       file=scrn-hlp,
%D        version=1998.10.10,
%D          title=\CONTEXT\ Screen Macros,
%D       subtitle=Help (Experimental),
%D         author={Hans Hagen \& Ton Otten},
%D           date=\currentdate,
%D      copyright={PRAGMA ADE \& \CONTEXT\ Development Team}]
%C
%C This module is part of the \CONTEXT\ macro||package and is
%C therefore copyrighted by \PRAGMA. See mreadme.pdf for
%C details.

\writestatus{loading}{ConTeXt Screen Macros / Help popups}

%D As this functionality was in the core and as I don't know how often it is used,
%D we'll keep it around. However, it is upgraded and usage has changed a bit. We
%D also use some \LUA\ magic in order to avoid multiple passes.

\registerctxluafile{scrn-hlp}{}

%D Using help boils down to plugging the placement macro someplace visible, like:
%D
%D \starttyping
%D \setuptexttexts[\centerbox{\placehelp}]
%D \stoptyping
%D
%D When this is done, the following should work out okay:
%D
%D \starttyping
%D test \helptext{word}{tip top 1 is somewhat longer} test
%D test \helptext{word}{tip top 2} test
%D
%D \starthelptext[oeps]
%D \input tufte
%D \stophelptext
%D
%D test test \showhelp{some help}[oeps] test
%D test test \button[location=depth]{\helpsignal{oeps}OEPS}[oeps] test
%D
%D test test \button[location=depth]{next}[page(2)] test
%D
%D \page
%D
%D test \helptext{word}{tip top one} test
%D test \helptext{word}{tip top two} test
%D \stoptyping
%D
%D Currently you need to use the signal in custom macros but that might change at
%D some point.

\unprotect

% also status

\newbox    \b_scrn_help_box
\newinteger\c_scrn_help_n

\definesystemattribute[help][public]

\installcorenamespace{popuphelp}

\installframedcommandhandler \??popuphelp {help} \??popuphelp

\setuphelp
  [\c!frame=\v!off,
   \c!align=\v!normal,
   \c!background=\v!color,
   \c!backgroundcolor=gray]

\appendtoks
    \protected\frozen\instance\edefcsname        \currenthelp\endcsname{\scrn_help_argument{\currenthelp}}%
    \protected\frozen\instance\edefcsname\e!start\currenthelp\endcsname{\scrn_help_start   {\currenthelp}}%
    \protected\frozen\instance\edefcsname\e!stop \currenthelp\endcsname{\scrn_help_stop                  }%
\to \everydefinehelp

\mutable\lettonothing\currenthelpreference
\mutable\lettonothing\currenthelpname

\protected\def\scrn_help_argument#category%
  {\cdef\currenthelp{#category}%
   \global\advanceby\c_scrn_help_n\plusone
   \edef\currenthelpname{help:\the\c_scrn_help_n}%
   \doifelselocation\scrn_help_argument_indeed\scrn_help_argument_ignore}

\tolerant\def\scrn_help_argument_indeed[#reference]#:#text#target%
  {\edef\currenthelpreference{#reference}%
   \dontleavehmode \hbox \bgroup
     \dontcomplain
     \setbox\b_scrn_help_box\hbox{\strut#text}%
     \scrn_help_register{#target}%
   \egroup % can be usernode instead
   \goto
     {\helpsignal{\the\c_scrn_help_n}#target}%
     [\helpaction{\the\c_scrn_help_n}]}

\tolerant\def\scrn_help_argument_ignore[#reference]#:#text#target%
  {#target}

\tolerant\protected\def\scrn_help_start#category#spacer[#reference]%
  {\global\advanceby\c_scrn_help_n\plusone
   \cdef\currenthelp{#category}%
   \edef\currenthelpreference{#reference}%
   \edef\currenthelpname{help:\the\c_scrn_help_n}%
   \grabbufferdatadirect\currenthelp{\e!start\currenthelp}{\e!stop\currenthelp}}

\protected\def\scrn_help_stop
  {\iflocation
     \scrn_help_register{\getbuffer[\currenthelp]}%
   \fi}

\def\scrn_help_register#text%
  {\setbox\b_scrn_help_box\hbox{\inheritedhelpframed{#text}}% \hpack ?
   \definesymbol
     [\currenthelpname]
     [\copy\b_scrn_help_box]%
   \definefieldbody
     [\currenthelpname]
     [\c!type=push,
      \c!width=\wd\b_scrn_help_box,
      \c!height=\ht\b_scrn_help_box,
      \c!depth=\dp\b_scrn_help_box,
      \c!option=\v!hidden,
      \c!clickin=action(hide{\currenthelpname}),
      \c!closepage=action(hide{\currenthelpname}),
      \c!values=\currenthelpname]%
   \setbox\b_scrn_help_box\hbox
     {\fieldbody[\currenthelpname]}%
   \clf_registerhelp
     number \c_scrn_help_n
     name   {\currenthelpreference}%
     box    \b_scrn_help_box
   \relax}

\permanent\protected\def\doifelsehelp
  {\ifcase\c_scrn_help_n
     \expandafter\firstoftwoarguments
   \else
     \expandafter\secondoftwoarguments
   \fi}

\aliased\let\doifhelpelse\doifelsehelp

\permanent\protected\def\placehelp % was \helpdata
  {\ifinpagebody\ifcase\c_scrn_help_n\else
     \clf_collecthelp\normalpagebox
   \fi\fi}

\permanent\def\helpreference#category{\clf_helpreference{#category}} % could be public implementors
\permanent\def\helpaction   #category{\clf_helpaction   {#category}} % could be public implementors

\permanent\protected\def\helpsignal#category%
  {\hbox attr \helpattribute \helpreference{#category}{}}

\permanent\protected\def\showhelp#target[#category]%
  {\goto{\helpsignal{#category}#target}[#category]}

\definehelp[\v!helptext]

\protect \endinput