scrn-hlp.mklx /size: 4937 b    last modification: 2023-12-21 09:44
1%D \module
2%D   [       file=scrn-hlp,
3%D        version=1998.10.10,
4%D          title=\CONTEXT\ Screen Macros,
5%D       subtitle=Help (Experimental),
6%D         author={Hans Hagen \& Ton Otten},
7%D           date=\currentdate,
8%D      copyright={PRAGMA ADE \& \CONTEXT\ Development Team}]
9%C
10%C This module is part of the \CONTEXT\ macro||package and is
11%C therefore copyrighted by \PRAGMA. See mreadme.pdf for
12%C details.
13
14\writestatus{loading}{ConTeXt Screen Macros / Help popups}
15
16%D As this functionality was in the core and as I don't know how often it is used,
17%D we'll keep it around. However, it is upgraded and usage has changed a bit. We
18%D also use some \LUA\ magic in order to avoid multiple passes.
19
20\registerctxluafile{scrn-hlp}{}
21
22%D Using help boils down to plugging the placement macro someplace visible, like:
23%D
24%D \starttyping
25%D \setuptexttexts[\centerbox{\placehelp}]
26%D \stoptyping
27%D
28%D When this is done, the following should work out okay:
29%D
30%D \starttyping
31%D test \helptext{word}{tip top 1 is somewhat longer} test
32%D test \helptext{word}{tip top 2} test
33%D
34%D \starthelptext[oeps]
35%D \input tufte
36%D \stophelptext
37%D
38%D test test \showhelp{some help}[oeps] test
39%D test test \button[location=depth]{\helpsignal{oeps}OEPS}[oeps] test
40%D
41%D test test \button[location=depth]{next}[page(2)] test
42%D
43%D \page
44%D
45%D test \helptext{word}{tip top one} test
46%D test \helptext{word}{tip top two} test
47%D \stoptyping
48%D
49%D Currently you need to use the signal in custom macros but that might change at
50%D some point.
51
52\unprotect
53
54% also status
55
56\newbox    \b_scrn_help_box
57\newinteger\c_scrn_help_n
58
59\definesystemattribute[help][public]
60
61\installcorenamespace{popuphelp}
62
63\installframedcommandhandler \??popuphelp {help} \??popuphelp
64
65\setuphelp
66  [\c!frame=\v!off,
67   \c!align=\v!normal,
68   \c!background=\v!color,
69   \c!backgroundcolor=gray]
70
71\appendtoks
72    \frozen\instance\protected\edefcsname        \currenthelp\endcsname{\scrn_help_argument{\currenthelp}}%
73    \frozen\instance\protected\edefcsname\e!start\currenthelp\endcsname{\scrn_help_start   {\currenthelp}}%
74    \frozen\instance\protected\edefcsname\e!stop \currenthelp\endcsname{\scrn_help_stop                  }%
75\to \everydefinehelp
76
77\mutable\lettonothing\currenthelpreference
78\mutable\lettonothing\currenthelpname
79
80\protected\def\scrn_help_argument#category%
81  {\cdef\currenthelp{#category}%
82   \global\advanceby\c_scrn_help_n\plusone
83   \edef\currenthelpname{help:\the\c_scrn_help_n}%
84   \doifelselocation\scrn_help_argument_indeed\scrn_help_argument_ignore}
85
86\tolerant\def\scrn_help_argument_indeed[#reference]#:#text#target%
87  {\edef\currenthelpreference{#reference}%
88   \dontleavehmode \hbox \bgroup
89     \dontcomplain
90     \setbox\b_scrn_help_box\hbox{\strut#text}%
91     \scrn_help_register{#target}%
92   \egroup % can be usernode instead
93   \goto
94     {\helpsignal{\the\c_scrn_help_n}#target}%
95     [\helpaction{\the\c_scrn_help_n}]}
96
97\tolerant\def\scrn_help_argument_ignore[#reference]#:#text#target%
98  {#target}
99
100\tolerant\protected\def\scrn_help_start#category#spacer[#reference]%
101  {\global\advanceby\c_scrn_help_n\plusone
102   \cdef\currenthelp{#category}%
103   \edef\currenthelpreference{#reference}%
104   \edef\currenthelpname{help:\the\c_scrn_help_n}%
105   \grabbufferdatadirect\currenthelp{\e!start\currenthelp}{\e!stop\currenthelp}}
106
107\protected\def\scrn_help_stop
108  {\iflocation
109     \scrn_help_register{\getbuffer[\currenthelp]}%
110   \fi}
111
112\def\scrn_help_register#text%
113  {\setbox\b_scrn_help_box\hbox{\inheritedhelpframed{#text}}% \hpack ?
114   \definesymbol
115     [\currenthelpname]
116     [\copy\b_scrn_help_box]%
117   \definefieldbody
118     [\currenthelpname]
119     [\c!type=push,
120      \c!width=\wd\b_scrn_help_box,
121      \c!height=\ht\b_scrn_help_box,
122      \c!depth=\dp\b_scrn_help_box,
123      \c!option=\v!hidden,
124      \c!clickin=action(hide{\currenthelpname}),
125      \c!closepage=action(hide{\currenthelpname}),
126      \c!values=\currenthelpname]%
127   \setbox\b_scrn_help_box\hbox
128     {\fieldbody[\currenthelpname]}%
129   \clf_registerhelp
130     number \c_scrn_help_n
131     name   {\currenthelpreference}%
132     box    \b_scrn_help_box
133   \relax}
134
135\permanent\protected\def\doifelsehelp
136  {\ifcase\c_scrn_help_n
137     \expandafter\firstoftwoarguments
138   \else
139     \expandafter\secondoftwoarguments
140   \fi}
141
142\aliased\let\doifhelpelse\doifelsehelp
143
144\permanent\protected\def\placehelp % was \helpdata
145  {\ifinpagebody\ifcase\c_scrn_help_n\else
146     \clf_collecthelp\normalpagebox
147   \fi\fi}
148
149\permanent\def\helpreference#category{\clf_helpreference{#category}} % could be public implementors
150\permanent\def\helpaction   #category{\clf_helpaction   {#category}} % could be public implementors
151
152\permanent\protected\def\helpsignal#category%
153  {\hbox attr \helpattribute \helpreference{#category}{}}
154
155\permanent\protected\def\showhelp#target[#category]%
156  {\goto{\helpsignal{#category}#target}[#category]}
157
158\definehelp[\v!helptext]
159
160\protect \endinput
161