cde/lib/DtHelp/HelpAccess.c

   1 /*
   2  * CDE - Common Desktop Environment
   3  *
   4  * Copyright (c) 1993-2012, The Open Group. All rights reserved.
   5  *
   6  * These libraries and programs are free software; you can
   7  * redistribute them and/or modify them under the terms of the GNU
   8  * Lesser General Public License as published by the Free Software
   9  * Foundation; either version 2 of the License, or (at your option)
  10  * any later version.
  11  *
  12  * These libraries and programs are distributed in the hope that
  13  * they will be useful, but WITHOUT ANY WARRANTY; without even the
  14  * implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  15  * PURPOSE. See the GNU Lesser General Public License for more
  16  * details.
  17  *
  18  * You should have received a copy of the GNU Lesser General Public
  19  * License along with these librararies and programs; if not, write
  20  * to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
  21  * Floor, Boston, MA 02110-1301 USA
  22  */
  23 /* $XConsortium: HelpAccess.c /main/6 1996/08/28 16:46:12 drk $ */
  24 /************************************<+>*************************************
  25  ****************************************************************************
  26  **
  27  **   File:        HelpAccess.c
  28  **
  29  **   Project:     Cache Creek (Rivers) Project
  30  **
  31  **   Description: This module handles all the help requests within a given
  32  **                help dialog widget.
  33  **
  34  **  (c) Copyright 1987, 1988, 1989, 1990, 1991, 1992 Hewlett-Packard Company
  35  **
  36  **  (c) Copyright 1993, 1994 Hewlett-Packard Company
  37  **  (c) Copyright 1993, 1994 International Business Machines Corp.
  38  **  (c) Copyright 1993, 1994 Sun Microsystems, Inc.
  39  **  (c) Copyright 1993, 1994 Novell, Inc.
  40  **
  41  **
  42  **
  43  ****************************************************************************
  44  ************************************<+>*************************************/
  45
  46 #include <stdio.h>
  47 #include <signal.h>
  48
  49 #include <X11/Intrinsic.h>
  50 #include <X11/Shell.h>
  51
  52 #include <Xm/RowColumnP.h>
  53 #include <Xm/LabelG.h>
  54 #include <Xm/PushBG.h>
  55 #include <Xm/CascadeB.h>
  56 #include <Xm/CascadeBG.h>
  57
  58 /* Help Library  Includes */
  59 #include "DisplayAreaI.h"
  60 #include "Access.h"
  61 #include "StringFuncsI.h"
  62 #include "HelpDialogI.h"
  63 #include "HelpDialogP.h"
  64
  65 #include <Dt/Help.h>
  66 #include "HelpI.h"
  67 #include "HelposI.h"
  68 #include "HelpUtilI.h"
  69 #include "HelpQuickD.h"
  70 #include "HelpQuickDP.h"
  71 #include "HelpQuickDI.h"
  72
  73
  74
  75 /********    Static Function Declarations    ********/
  76 static void  CloseOnHelpCB(
  77     Widget w,
  78     XtPointer client_data,
  79     XtPointer call_data);
  80 static void SetupHelpDialog(
  81     Widget parent,
  82     char *helpOnHelpVolume,
  83     Widget *helpWidget,
  84     char *locationId);
  85
  86 /********    End Static Function Declarations    ********/
  87
  88
  89
  90 \f
  91 /*****************************************************************************
  92  * Function:       static void CloseOnHelpCB(
  93  *                            Widget w,
  94  *                            XtPointer client_data,
  95  *                            XtPointer call_data);
  96  *
  97  * Parameters:
  98  *
  99  * Return Value:
 100  *
 101  * Purpose:        This routine closes the onhelp dialog Widget that we
 102  *                 created for our help on help stuff.
 103  *
 104  ****************************************************************************/
 105 static void  CloseOnHelpCB(
 106     Widget w,
 107     XtPointer client_data,
 108     XtPointer call_data )
 109 {
 110
 111   XtUnmanageChild(w);
 112
 113
 114 }
 115
 116
 117 \f
 118 /****************************************************************************
 119  * Function:          void  _DtHelpCB ()
 120  *
 121  * Parameters:           widget
 122  *                       clientData
 123  *                       callData
 124  *
 125  *
 126  * Return Value:    Void.
 127  *
 128  * Purpose:         Called when any "F1" key is pressed in a help dialog
 129  *                  widget, or a user selects any of the help buttons in
 130  *                  any of the help dialogs dialogs.
 131  *
 132  ***************************************************************************/
 133 void  _DtHelpCB(
 134     Widget widget,
 135     XtPointer clientData,
 136     XtPointer callData)
 137 {
 138   char *errorStr;
 139
 140   DtHelpListStruct * pHelpInfo = (DtHelpListStruct *) clientData;
 141   _DtHelpCommonHelpStuff * help = pHelpInfo->help;
 142
 143   /* If helpOnHelp resource is set use it, else post an error dialog */
 144   if (help->helpOnHelpVolume != NULL)
 145     {
 146        SetupHelpDialog((Widget)pHelpInfo->widget, help->helpOnHelpVolume,
 147                      &(help->onHelpDialog), pHelpInfo->locationId);
 148     }
 149   else
 150     {
 151        /* We have no help available for the help stuff so generate an error */
 152        /* Do NOT EVER provide a help button */
 153        /* ??? ERROR */
 154        errorStr = XtNewString(((char *) _DTGETMESSAGE(6, 4,
 155                           "Help On Help not provided for this application!")));
 156        _DtHelpErrorDialog(XtParent(pHelpInfo->widget), errorStr);
 157        XtFree(errorStr);
 158     }
 159
 160 }
 161
 162
 163
 164 \f
 165 /*****************************************************************************
 166  * Function:        void SetupHelpDialog ();
 167  *
 168  *
 169  * Parameters:
 170  *
 171  * Return Value:    Void.
 172  *
 173  * Purpose:         Creates or re-uses a help on help quick help widget.
 174  *
 175  *****************************************************************************/
 176 static void SetupHelpDialog(
 177     Widget parent,
 178     char *helpOnHelpVolume,
 179     Widget *helpDialog,
 180     char *locationId)
 181 {
 182   Arg  args[10];
 183   int    n;
 184   XmString printString;
 185   XmString closeString;
 186   XmString backString;
 187   XmString helpString;
 188   char *title;
 189
 190
 191       if (*helpDialog ==  NULL)
 192         {
 193           /* Create the QuickHelpDialog widget for help on help */
 194           title = XtNewString(((char *)_DTGETMESSAGE(6, 1, "Help On Help")));
 195           printString = XmStringCreateLocalized(((char *)_DTGETMESSAGE
 196                             (6, 2,"Print ...")));
 197           closeString = XmStringCreateLocalized(((char *)_DTGETMESSAGE
 198                             (6, 3,"Close")));
 199           backString = XmStringCreateLocalized(((char *)_DTGETMESSAGE
 200                             (6, 5,"Backtrack")));
 201
 202           helpString = XmStringCreateLocalized(((char *)_DTGETMESSAGE
 203                             (6, 6,"Help ...")));
 204
 205           n =0;
 206           XtSetArg (args[n], DtNhelpType, DtHELP_TYPE_TOPIC);   n++;
 207           XtSetArg (args[n], XmNtitle, title);                  n++;
 208           XtSetArg (args[n], DtNprintLabelString, printString); n++;
 209           XtSetArg (args[n], DtNcloseLabelString, closeString); n++;
 210           XtSetArg (args[n], DtNbackLabelString, backString);   n++;
 211           XtSetArg (args[n], DtNhelpLabelString, helpString);   n++;
 212           XtSetArg (args[n], DtNhelpVolume,helpOnHelpVolume);   n++;
 213           XtSetArg (args[n], DtNlocationId, locationId);        n++;
 214           *helpDialog = DtCreateHelpQuickDialog((Widget)parent,
 215                                                 "onHelpDialog", args, n);
 216           XmStringFree(printString);
 217           XmStringFree(closeString);
 218           XmStringFree(backString);
 219           XmStringFree(helpString);
 220           XtFree((char*) title);
 221
 222           /* Catch the close callback so we can destroy the widget */
 223           XtAddCallback(*helpDialog, DtNcloseCallback,
 224                       CloseOnHelpCB, (XtPointer) NULL);
 225
 226           /* Add the popup position callback to our history dialog */
 227           XtAddCallback (XtParent(*helpDialog), XmNpopupCallback,
 228                         (XtCallbackProc)_DtHelpMapCB,
 229                         (XtPointer)XtParent(parent));
 230
 231
 232         }
 233       else
 234         {
 235            n = 0;
 236            XtSetArg (args[n], DtNhelpType, DtHELP_TYPE_TOPIC);  n++;
 237            XtSetArg (args[n], DtNhelpVolume,helpOnHelpVolume);   n++;
 238            XtSetArg (args[n], DtNlocationId, locationId);        n++;
 239            XtSetValues(*helpDialog, args, n);
 240
 241          }
 242
 243       /* Display the dialog */
 244       XtManageChild(*helpDialog);
 245       XtMapWidget(XtParent((Widget)*helpDialog));
 246 }
 247
 248
 249 \f
 250 /*****************************************************************************
 251  * Function:        void _DtHelpListFree (DtHelpListStruct * * pHead);
 252  *
 253  *
 254  * Parameters:      pHead   Specifies the head pointer to the help list.
 255  *
 256  * Return Value:    Void.
 257  *
 258  * Purpose:         Frees all elements in a Help List.
 259  *
 260  *****************************************************************************/
 261 void _DtHelpListFree(
 262     DtHelpListStruct * * pHead)
 263 {
 264   DtHelpListStruct *pTemp = NULL;
 265   DtHelpListStruct *pTmpHead = *pHead;
 266
 267    while (pTmpHead != NULL)
 268      {
 269        /* Free up each element in the current node */
 270        pTemp            = pTmpHead;
 271        pTmpHead         = pTmpHead->pNext;
 272        pTemp->pNext     = NULL;
 273
 274        /* Free the id String */
 275        XtFree(pTemp->locationId);
 276
 277        /* Now, free the whole node */
 278        XtFree((char *)pTemp);
 279     }
 280     *pHead = NULL;   /* reset pointer */
 281 }
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291 \f
 292 /*****************************************************************************
 293  * Function:        DtHelpListStruct * _DtHelpListAdd(
 294  *                                       char *locationId,
 295  *                                       Widget new,
 296  *                                       DtHelpListStruct **pHead)
 297  *
 298  *
 299  *
 300  * Parameters:
 301  *
 302  * Return Value:    Void.
 303  *
 304  * Purpose:         Adds an element to the top of the given topicList.
 305  *
 306  *****************************************************************************/
 307 DtHelpListStruct * _DtHelpListAdd(
 308     char *locationId,
 309     Widget widget,
 310     _DtHelpCommonHelpStuff * help,
 311     DtHelpListStruct **pHead)
 312 {
 313   DtHelpListStruct *pTemp=NULL;
 314
 315   /* Add locationId as first element if pHead = NULL */
 316   if (*pHead == NULL)
 317     {
 318       *pHead = (DtHelpListStruct *) XtMalloc((sizeof(DtHelpListStruct)));
 319
 320       /* Assign the passed in values to our first element */
 321       (*pHead)->locationId      = XtNewString(locationId);
 322       (*pHead)->widget          = widget;
 323       (*pHead)->help            = help;
 324       (*pHead)->pNext           = NULL;
 325       (*pHead)->pPrevious       = NULL;
 326
 327     }
 328   else
 329     {  /* We have a list so add the new Help item to the top */
 330      pTemp = (DtHelpListStruct *) XtMalloc((sizeof(DtHelpListStruct)));
 331
 332      pTemp->pNext            = (*pHead);
 333      pTemp->pPrevious        = NULL;
 334
 335      (*pHead)->pPrevious     = pTemp;
 336
 337      pTemp->locationId       = XtNewString(locationId);
 338      pTemp->widget           = widget;
 339      pTemp->help             = help;
 340
 341      /* Re-Assign our head pointer to point to the new head of the list */
 342      (*pHead) = pTemp;
 343     }
 344
 345   return (*pHead);
 346 }
 347