cde/lib/DtHelp/HelpUtilI.h

   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: HelpUtilI.h /main/5 1995/10/26 12:26:30 rswiston $ */
  24 /*************************************<+>*************************************
  25  *****************************************************************************
  26  **
  27  **  File:   HelpUtilI.h
  28  **
  29  **  Project:  Rivers Project,
  30  **
  31  **  Description:  Internal header file for our HelpUtil module.
  32  **  -----------
  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 #ifndef _HelpUtilI_h
  45 #define _HelpUtilI_h
  46
  47
  48 #include "HelpDialogP.h"
  49
  50 /* default help4help volume */
  51 extern char _DtHelpDefaultHelp4HelpVolume[];
  52 extern char _DtHelpDefaultLocationId[];
  53
  54 /*
  55
  56  *****************************************************************************
  57  * Function:    void _DtHelpErrorDialog(parent, message, helpLocationId)
  58  *
  59  * Parameters:      widget      Specifies the application's top level widget
  60  *                  message     Specifies the desired error message to
  61  *                              display.
  62  *
  63  * Return Value:    None
  64  *
  65  * Purpose:         To display and error message in a motif error dialog.
  66  *
  67  *****************************************************************************
  68  */
  69 void _DtHelpErrorDialog(
  70     Widget                   parent,
  71     char *                   message);
  72
  73 /*****************************************************************************
  74  * Function: _DtHelpFilterExecCmdStr
  75  *
  76  *   Args:
  77  *    helpWidget:       help widget requesting to exec the command
  78  *    pDisplayStuff:    ptr to the DisplayWidget stuff of the help widget
  79  *    commandStr:       command string to execute
  80  *    ret_cmdStr:       the screened & possibly rewritten command is put here
  81  *    ret_cmdWasAlias:  was the command an alias?
  82  *    ret_execPermitted: if executionPolicy permit exec & ret_cmdStr is valid
  83  *    ret_queryNeeded:  if executionPolicy requires a query before exec
  84  *
  85  * Description:
  86  *    ret_cmdStr gets memory owned by the calling function; it should be
  87  *    freed when no longer needed.  The string will be the same as the
  88  *    commandStr if commandStr was not an alias.  If the commandStr
  89  *    is an alias and if the alias is defined, the ret_cmdStr will be the
  90  *    value of the alias.  If the alias isn't defined, the ret_cmdStr will
  91  *    be the default command if available, or the alias name otherwise.
  92  *
  93  *    ret_cmdWasAlias will be True if the alias was defined or if the
  94  *    alias was undefined AND no default command was given.
  95  *    It will be False if no alias was used or if the alias was undefined
  96  *    and a default command was present.
  97  *
  98  * Returns:
  99  *    True:  if execPermitted and a valid command string
 100  *    False: if if execPermitted is False or invalid command string
 101  *
 102  * Comments:
 103  *    This code is written such that we don't need nor want to know
 104  *    whether it is a general or quick help widget.
 105  *
 106  * Warning:
 107  *    command string must be writable; it is written, but left
 108  *    unchanged when the function exits.
 109  *
 110  *****************************************************************************/
 111 Boolean _DtHelpFilterExecCmdStr(
 112     Widget                   helpWidget,
 113     unsigned char            executionPolicy,
 114     const char *             commandStr,
 115     char * *                 ret_cmdStr,
 116     Boolean *                ret_cmdWasAlias,
 117     Boolean *                ret_execPermitted,
 118     Boolean *                ret_queryNeeded,
 119     char    *                hv_path);
 120
 121 typedef Boolean (*_DtHelpCeWaitProc)(Widget w,void * clientData);
 122
 123 /*********************************************************************
 124  * _DtHelpCeWaitAndProcessEvents
 125  *
 126  *  Purpose:
 127  *    _DtHelpCeWaitAndProcessEvents will process events and call
 128  *    the waitProc until waitProc returns False.   This function
 129  *    is useful to put up modal dialogs that must be reponded to
 130  *    in the midst of executing code that must remain on the call stack.
 131  *
 132  *  Warning:
 133  *    This function should only be used on modal dialogs.
 134  *
 135  *********************************************************************/
 136
 137 void
 138 _DtHelpCeWaitAndProcessEvents (
 139     Widget             w,
 140     _DtHelpCeWaitProc  waitProc,
 141     void *             clientData);
 142
 143 /*****************************************************************************
 144  * Function: _DtHelpFilterExecCmd
 145  *
 146  *   Args:
 147  *    helpWidget:       help widget requesting to exec the command
 148  *    command:          command string to execute
 149  *                      DtHELP_EXECUTE_???
 150  *    execPolicy:       current policy setting
 151  *    ret_filteredCmdStr: filtered command string
 152  *****************************************************************************/
 153 int _DtHelpFilterExecCmd(
 154     Widget        helpWidget,
 155     const char *  commandStr,
 156     unsigned char executionPolicy,
 157     Boolean       useQueryDialog,
 158     _DtHelpCommonHelpStuff * pHelpStuff,
 159     char * *      ret_filteredCmdStr,
 160     char *        hv_path);
 161
 162 /*****************************************************************************
 163  * Function: _DtHelpExecFilteredCmd
 164  *
 165  *   Args:
 166  *    helpWidget:       help widget requesting to exec the command
 167  *    command:          command string to execute
 168  *    modal:            is the execution modal (sync) or modeless (async)
 169  *    helpLocationId:   helpOnHelp file location for Help btn in error dialog
 170  *    pDisplayStuff:    ptr to the DisplayWidget stuff of the help widget
 171  *    pHelpStuff:       ptr to the CommonHelp stuff of the help widget
 172  *
 173  * Comments:
 174  *    This code is written such that we don't need nor want to know
 175  *    whether it is a general or quick help widget.
 176  *
 177  * Warning:
 178  *    command string must be writable; it is written, but left
 179  *    unchanged whent the function exits.
 180  *
 181  * Called by:
 182  *****************************************************************************/
 183 void _DtHelpExecFilteredCmd(
 184     Widget                   helpWidget,
 185     char *                   commandStr,
 186     char *                   helpLocationId,
 187     _DtHelpDisplayWidgetStuff * pDisplayStuff,
 188     _DtHelpCommonHelpStuff * pHelpStuff);
 189
 190 /*****************************************************************************
 191  * Function:       Boolean _DtHelpExpandHelpVolume(DtHelpDialogWidget nw);
 192  *
 193  *
 194  * Parameters:     nw  Specifies the current help dialog widget.
 195  *
 196  * Return Value:    Boolean.
 197  *
 198
 199  * Description: _DtHelpExpandHelpVolume looks for a $LANG variable in the
 200  *              helpAccesFile string and if found, replaces it with the
 201  *              current lang variable.
 202  *
 203  *****************************************************************************/
 204 Boolean _DtHelpExpandHelpVolume(
 205    Widget                       widget,
 206    _DtHelpDisplayWidgetStuff * display,
 207    _DtHelpCommonHelpStuff *    help,
 208    _DtHelpPrintStuff *         print);
 209
 210 /*****************************************************************************
 211  * Function:       char *_DtHelpParseIdString(char * specification);
 212  *
 213  *
 214  * Parameters:     specification  Specifies an author defined help topic.
 215  *
 216  * Return Value:    Void.
 217  *
 218  * Description:   This function copies the locationId portion of the
 219  *                specification and retruns it to the calling routine.
 220  *
 221  *****************************************************************************/
 222 extern char *_DtHelpParseIdString(
 223    char *specification);
 224
 225 /*****************************************************************************
 226  * Function:       char *_DtHelpParseAccessFile(char * specification);
 227  *
 228  *
 229  * Parameters:     specification  Specifies an author defined help topic.
 230  *
 231  * Return Value:    Void.
 232  *
 233  * Description:   This function copies the helpAccessFile portion of the
 234  *                specification and retruns it to the calling routine.
 235  *
 236  *****************************************************************************/
 237 extern char *_DtHelpParseAccessFile(
 238    char *specification);
 239
 240 /*****************************************************************************
 241  * Function:        void _DtHelpTopicListAddToHead(
 242  *                                       char *locationId,
 243  *                                       char *topicTitle,
 244  *                                       int topicType,
 245  *                                       int maxNodex,
 246  *                                       char *accessPath,
 247  *                                       DtTopicListStruct **pHead,
 248  *                                       DtTopicListStruct **pTale,
 249  *                                       int *totalNodes)
 250  *
 251  *
 252  * Parameters:
 253  *
 254  * Return Value:    Void.
 255  *
 256  * Purpose:         Adds an element to the top of the given topicList.
 257  *
 258  *****************************************************************************/
 259 extern void _DtHelpTopicListAddToHead(
 260     char *locationId,
 261     XmString topicTitle,
 262     int topicType,
 263     int maxNodes,
 264     char *accessPath,
 265     DtTopicListStruct **pHead,
 266     DtTopicListStruct **pTale,
 267     int *totalNodes,
 268     int scrollPosition);
 269
 270 /*****************************************************************************
 271  * Function:        void _DtTopicListDelUeteHead(
 272  *                                       DtTopicListStruct *pHead,
 273  *                                       DtTopicListStruct *pTale,
 274  *                                       totalNodes)
 275  *
 276  *
 277  * Parameters:
 278  *
 279  * Return Value:    Void.
 280  *
 281  * Purpose:         Delets an element from the top of the given topicList.
 282  *
 283  *****************************************************************************/
 284 extern void _DtHelpTopicListDeleteHead(
 285     DtTopicListStruct **pHead,
 286     DtTopicListStruct **pTale,
 287     int *totalNodes);
 288
 289 /*****************************************************************************
 290  * Function:        void _DtHelpMapCB(
 291  *
 292  *
 293  *
 294  * Parameters:
 295  *
 296  * Return Value:    Void.
 297  *
 298  * Purpose:         Determins where a new child dialog should be mapped in
 299  *                  relation to its parent.
 300  *
 301  *****************************************************************************/
 302 extern XtCallbackProc _DtHelpMapCB(
 303     Widget w,
 304     XtPointer client_data,
 305     XtPointer call_data );
 306
 307 \f
 308 /*****************************************************************************
 309  * Function:        void _DtHelpMapCenteredCB(
 310  *
 311  *
 312  *
 313  * Parameters:
 314  *
 315  * Return Value:    Void.
 316  *
 317  * Purpose:         Determins where the center of our help dialog is and sets
 318  *                  where new child dialog should be mapped such that its centered.
 319  *
 320  *****************************************************************************/
 321 extern XtCallbackProc _DtHelpMapCenteredCB(
 322     Widget w,
 323     XtPointer client_data,
 324     XtPointer call_data);
 325
 326 /*****************************************************************************
 327  * Function:       Boolean _DtHelpResolvePathname(
 328  *
 329  *
 330  * Parameters:
 331  *
 332  * Return Value:    Boolean.
 333  *
 334  *
 335  * Description: _DtHelpResolvePathname attempts to validate and expand a path
 336  *              to a Cache Creek help access file.
 337  *
 338  *****************************************************************************/
 339 extern Boolean _DtHelpResolvePathname(
 340    Widget widget,
 341    char **fileName,
 342    _DtHelpVolumeHdl *volumeHandle,
 343    char *sysVolumeSearchPath,
 344    char *userVolumeSearchPath);
 345
 346
 347 /*****************************************************************************
 348  * Function:       void _DtHelpDisplayDefinitionBox(
 349  *                            Widget parent,
 350  *                            Widget definitionBox,
 351  *                            char * path,
 352  *                            char * locationId);
 353  *
 354  * Parameters:
 355  *
 356  * Return Value:
 357  *
 358  * Purpose:        This routine will create and post the definition box.
 359  *                 (e.g. the Quick Help Dialog widget)
 360  *
 361  ****************************************************************************/
 362 extern void _DtHelpDisplayDefinitionBox(
 363     Widget parent,
 364     Widget **definitionBox,
 365     char * path,
 366     char * locationId);
 367
 368 /*****************************************************************************
 369  * Function:       void _DtHelpDisplayFormatError()
 370   *
 371  * Parameters:
 372  *
 373  * Return Value:
 374  *
 375  * Purpose:        This routine generate and display the proper errror
 376  *                 message to the display area as well as send the proper
 377  *                 error to XmWarning() function.
 378  *
 379  ****************************************************************************/
 380 void _DtHelpDisplayFormatError(
 381     XtPointer displayArea,
 382     Widget widget,
 383     char *userError,
 384     char *systemError);
 385
 386 /*****************************************************************************
 387  * Function:       void _DtHelpCommonHelpInit()
 388   *
 389  * Parameters:
 390  *
 391  * Return Value:
 392  *
 393  * Purpose:        This routine inits common help stuff
 394  *
 395  ****************************************************************************/
 396 void _DtHelpCommonHelpInit(
 397     _DtHelpCommonHelpStuff * help);
 398
 399 /*****************************************************************************
 400  * Function:       void _DtHelpCommonHelpClean()
 401   *
 402  * Parameters:
 403  *
 404  * Return Value:
 405  *
 406  * Purpose:        This routine cleans up common help stuff
 407  *
 408  ****************************************************************************/
 409 void _DtHelpCommonHelpClean(
 410     _DtHelpCommonHelpStuff * help,
 411     Boolean                 destroy);
 412
 413 /*****************************************************************************
 414  * Function:       void _DtHelpSetDlgButtonsWidth
 415  *
 416  * Parameters:
 417  *
 418  * Return Value:
 419  *
 420  * Purpose:        This routine cleans up common help stuff
 421  *
 422  ****************************************************************************/
 423 void _DtHelpSetButtonPositions(
 424     Widget     btnList[],
 425     int        numBtns,
 426     Dimension  minFormWidth,
 427     Dimension  btnMargins,
 428     Dimension  minBetweenBtnSpace);
 429
 430 /*****************************************************************************
 431  * Function:       _DtHelpXmFontListGetPropertyMax
 432  *
 433  * Parameters:
 434  *     fontList:  an XmFontList
 435  *     atom:      an XA_xxx value (see Vol 1, chpt 6.2.9)
 436  *     ret_propertyValue: ptr to long value that will hold the max value
 437  *
 438  * Return Value:
 439  *     True: got at least one value
 440  *     False: unable to get any value
 441  *
 442  * Purpose:
 443  *    This function returns the max value of XGetFontProperty calls
 444  *    for each font in the XmFontList
 445  *
 446  ****************************************************************************/
 447 Boolean _DtHelpXmFontListGetPropertyMax(
 448         XmFontList fontList,
 449         Atom atom,
 450         unsigned long *ret_propertyValue);
 451
 452 #endif /* _HelpUtilI_h */
 453 /* Do not add anything after this endif. */
 454
 455