chiark - git - mdw - ssr/blob - StraySrc/Libraries/Steel/c/help

   1 /*
   2  * Help
   3  *  Provides support for the !Help application
   4  *
   5  * v. 1.00 (25 July 1993)
   6  *
   7  * © 1993-1998 Straylight
   8  */
   9
  10 /*----- Licensing note ----------------------------------------------------*
  11  *
  12  * This file is part of Straylight's Steel library.
  13  *
  14  * Steel is free software; you can redistribute it and/or modify
  15  * it under the terms of the GNU General Public License as published by
  16  * the Free Software Foundation; either version 2, or (at your option)
  17  * any later version.
  18  *
  19  * Steel is distributed in the hope that it will be useful,
  20  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  21  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  22  * GNU General Public License for more details.
  23  *
  24  * You should have received a copy of the GNU General Public License
  25  * along with Steel.  If not, write to the Free Software Foundation,
  26  * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  27  */
  28
  29 #include "wimp.h"
  30 #include "wimpt.h"
  31 #include "help.h"
  32 #include "msgs.h"
  33 #include "werr.h"
  34 #include <string.h>
  35 #include <stdarg.h>
  36 #include <stdio.h>
  37
  38 static wimp_msgstr help__msg;
  39 static wimp_t help__hisHandle;
  40 static wimp_w help__window;
  41 static wimp_i help__icon;
  42
  43 static char *help__transString=
  44    "-0123456789"
  45    "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
  46    "abcdefghijklmnopqrstuvwxyz";
  47
  48 #define help__TRANSLEN 62
  49
  50 /*
  51  * void help_startHelp(void)
  52  *
  53  * Use
  54  *  This call sets up a new message to bundle off to !Help.
  55  */
  56
  57 void help_startHelp(void)
  58 {
  59   wimp_eventstr *e=wimpt_last_event();
  60   help__msg.hdr.size=256;
  61   help__msg.hdr.your_ref=e->data.msg.hdr.my_ref;
  62   help__msg.hdr.action=wimp_MHELPREPLY;
  63   help__msg.data.helpreply.text[0]='\0';
  64   help__hisHandle=e->data.msg.hdr.task;
  65   help__window=e->data.msg.data.helprequest.m.w;
  66   help__icon=e->data.msg.data.helprequest.m.i;
  67 }
  68
  69 /*
  70  * void help_addLine(char *line,...)
  71  *
  72  * Use
  73  *  This call adds a line of text to the current help message.  If the
  74  *  message starts off blank, then the line will become the current message,
  75  *  otherwise the message will have a '|m' followed by the new line appended
  76  *  on the end.
  77  *
  78  * Parameters
  79  *  char *line == a printf()-style format string.
  80  */
  81
  82 void help_addLine(char *line,...)
  83 {
  84   va_list ap;
  85   char buffer[255];
  86   va_start(ap,line);
  87   vsprintf(buffer,line,ap);
  88   va_end(ap);
  89   if (help__msg.data.helpreply.text[0]=='\0')
  90     strcpy(help__msg.data.helpreply.text,buffer);
  91   else
  92   {
  93     strcat(help__msg.data.helpreply.text,"|m");
  94     strcat(help__msg.data.helpreply.text,buffer);
  95   }
  96 }
  97
  98 /*
  99  * void help_endHelp(void)
 100  *
 101  * Use
 102  *  This call bundles off the current help message to the application.
 103  */
 104
 105 void help_endHelp(void)
 106 {
 107   help__msg.hdr.size=((sizeof(wimp_msghdr)+strlen(help__msg.data.helpreply.text)+1)&(~3))+4;
 108   wimpt_noerr(wimp_sendmessage(wimp_ESEND,&help__msg,help__hisHandle));
 109 }
 110
 111 /*
 112  * void help_readFromIcon(void)
 113  *
 114  * Use
 115  *  This call will read a help message from the icon the help system is
 116  *  interested in, and tack it on the end of the message.  The help message
 117  *  should be stored in the icon's validation string with the command 'H'
 118  *  (e.g. validation string == "A0-9;B3;HType a number in this icon."
 119  *  Alternatively, you can use a message-file tag, which will be looked up.
 120  */
 121
 122 void help_readFromIcon(void)
 123 {
 124   wimp_icon icn;
 125   char *vs;
 126   int i;
 127   char msg[255];
 128   BOOL foundMsg=FALSE;
 129   BOOL doneMsg=FALSE;
 130   int msgIndex=0;
 131   char *mfl;
 132   if (help__icon<0)
 133     return;
 134   wimpt_noerr(wimp_get_icon_info(help__window,help__icon,&icn));
 135   if
 136   (
 137     (icn.flags&wimp_INDIRECT)==0 ||
 138     (icn.flags&(wimp_ITEXT|wimp_ISPRITE))==wimp_ISPRITE ||
 139     ((wimpt_options() & wimpt_ONOWIMPSHADE) &&
 140      (icn.flags & 0x001f0000)==0x001f0000) ||
 141     icn.data.indirecttext.validstring==(char *)-1
 142   )
 143     return;
 144   vs=icn.data.indirecttext.validstring;
 145   if (vs[0]=='H' || vs[0]=='h')
 146   {
 147     foundMsg=TRUE;
 148     vs++;
 149   }
 150   for (i=0;vs[i]>31;i++)
 151   {
 152     switch (vs[i])
 153     {
 154       case '\\':
 155         if (vs[i+1]>31)
 156         {
 157           i++;
 158           if (foundMsg)
 159             msg[msgIndex++]=vs[i];
 160         }
 161         break;
 162       case ';':
 163         if (foundMsg)
 164         {
 165           foundMsg=FALSE;
 166           doneMsg=TRUE;
 167         }
 168         if (vs[i+1]>31)
 169         {
 170           i++;
 171           switch (vs[i])
 172           {
 173             case 'H':
 174             case 'h':
 175               if (!doneMsg)
 176                 foundMsg=TRUE;
 177               break;
 178           }
 179         }
 180         break;
 181       default:
 182         if (foundMsg)
 183           msg[msgIndex++]=vs[i];
 184         break;
 185     }
 186   }
 187   msg[msgIndex]='\0';
 188   if (msg[0])
 189   {
 190     mfl=msgs_lookup(msg);
 191     if (mfl)
 192       help_addLine("%s",mfl);
 193     else
 194       help_addLine("%s",msg);
 195   }
 196 }
 197
 198 /*
 199  * BOOL help_wasHelp(void)
 200  *
 201  * Use
 202  *  Informs caller if the last event was a help request.
 203  *
 204  * Returns
 205  *  TRUE if it was.
 206  */
 207
 208 BOOL help_wasHelp(void)
 209 {
 210   wimp_eventstr *e=wimpt_last_event();
 211   if
 212   (
 213     (e->e==wimp_ESEND ||
 214     e->e==wimp_ESENDWANTACK) &&
 215     e->data.msg.hdr.action==wimp_MHELPREQUEST
 216   )
 217     return (TRUE);
 218   else
 219     return (FALSE);
 220 }
 221
 222 /*
 223  * void help_readFromMenu(char *prefix,int hit[])
 224  *
 225  * Use
 226  *  Converts the menu hit structure into a message tag and then reads the
 227  *  message and adds it to the help message being constructed.
 228  *  The message tag is constructed from the prefix, followed by a character
 229  *  for each entry in the hit structure.  The characters are in order (first
 230  *  to last) 0-9,A-Z,a-z, giving 62 entries.  This WILL be enough for any
 231  *  *reasonable* menu...
 232  *
 233  * Parameters
 234  *  char *prefix ==
 235  *  int hit[] == a menu hit structure as passed to a menu handler.
 236  */
 237
 238 void help_readFromMenu(char *prefix,int hit[])
 239 {
 240   char tag[20];
 241   int i=0;
 242   char *p;
 243   strcpy(tag,prefix);
 244   p=tag+strlen(tag);
 245   while (hit[i])
 246   {
 247     if (hit[i]>=help__TRANSLEN)
 248       werr(TRUE,msgs_lookup("(help_readFromMenu, caller fault): menu event array out of range."));
 249     *(p++)=help__transString[hit[i++]];
 250   }
 251   *p=0;
 252   help_addLine("%s",msgs_lookup(tag));
 253 }