2 * CDE - Common Desktop Environment
4 * Copyright (c) 1993-2012, The Open Group. All rights reserved.
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)
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
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
23 /* $XConsortium: HelpUtilI.h /main/5 1995/10/26 12:26:30 rswiston $ */
24 /*************************************<+>*************************************
25 *****************************************************************************
29 ** Project: Rivers Project,
31 ** Description: Internal header file for our HelpUtil module.
34 ** (c) Copyright 1987, 1988, 1989, 1990, 1991, 1992 Hewlett-Packard Company
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 *************************************<+>*************************************/
48 #include "HelpDialogP.h"
50 /* default help4help volume */
51 extern char _DtHelpDefaultHelp4HelpVolume[];
52 extern char _DtHelpDefaultLocationId[];
56 *****************************************************************************
57 * Function: void _DtHelpErrorDialog(parent, message, helpLocationId)
59 * Parameters: widget Specifies the application's top level widget
60 * message Specifies the desired error message to
65 * Purpose: To display and error message in a motif error dialog.
67 *****************************************************************************
69 void _DtHelpErrorDialog(
73 /*****************************************************************************
74 * Function: _DtHelpFilterExecCmdStr
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
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.
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.
99 * True: if execPermitted and a valid command string
100 * False: if if execPermitted is False or invalid command string
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.
107 * command string must be writable; it is written, but left
108 * unchanged when the function exits.
110 *****************************************************************************/
111 Boolean _DtHelpFilterExecCmdStr(
113 unsigned char executionPolicy,
114 const char * commandStr,
116 Boolean * ret_cmdWasAlias,
117 Boolean * ret_execPermitted,
118 Boolean * ret_queryNeeded,
121 typedef Boolean (*_DtHelpCeWaitProc)(Widget w,void * clientData);
123 /*********************************************************************
124 * _DtHelpCeWaitAndProcessEvents
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.
133 * This function should only be used on modal dialogs.
135 *********************************************************************/
138 _DtHelpCeWaitAndProcessEvents (
140 _DtHelpCeWaitProc waitProc,
143 /*****************************************************************************
144 * Function: _DtHelpFilterExecCmd
147 * helpWidget: help widget requesting to exec the command
148 * command: command string to execute
150 * execPolicy: current policy setting
151 * ret_filteredCmdStr: filtered command string
152 *****************************************************************************/
153 int _DtHelpFilterExecCmd(
155 const char * commandStr,
156 unsigned char executionPolicy,
157 Boolean useQueryDialog,
158 _DtHelpCommonHelpStuff * pHelpStuff,
159 char * * ret_filteredCmdStr,
162 /*****************************************************************************
163 * Function: _DtHelpExecFilteredCmd
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
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.
178 * command string must be writable; it is written, but left
179 * unchanged whent the function exits.
182 *****************************************************************************/
183 void _DtHelpExecFilteredCmd(
186 char * helpLocationId,
187 _DtHelpDisplayWidgetStuff * pDisplayStuff,
188 _DtHelpCommonHelpStuff * pHelpStuff);
190 /*****************************************************************************
191 * Function: Boolean _DtHelpExpandHelpVolume(DtHelpDialogWidget nw);
194 * Parameters: nw Specifies the current help dialog widget.
196 * Return Value: Boolean.
199 * Description: _DtHelpExpandHelpVolume looks for a $LANG variable in the
200 * helpAccesFile string and if found, replaces it with the
201 * current lang variable.
203 *****************************************************************************/
204 Boolean _DtHelpExpandHelpVolume(
206 _DtHelpDisplayWidgetStuff * display,
207 _DtHelpCommonHelpStuff * help,
208 _DtHelpPrintStuff * print);
210 /*****************************************************************************
211 * Function: char *_DtHelpParseIdString(char * specification);
214 * Parameters: specification Specifies an author defined help topic.
216 * Return Value: Void.
218 * Description: This function copies the locationId portion of the
219 * specification and retruns it to the calling routine.
221 *****************************************************************************/
222 extern char *_DtHelpParseIdString(
223 char *specification);
225 /*****************************************************************************
226 * Function: char *_DtHelpParseAccessFile(char * specification);
229 * Parameters: specification Specifies an author defined help topic.
231 * Return Value: Void.
233 * Description: This function copies the helpAccessFile portion of the
234 * specification and retruns it to the calling routine.
236 *****************************************************************************/
237 extern char *_DtHelpParseAccessFile(
238 char *specification);
240 /*****************************************************************************
241 * Function: void _DtHelpTopicListAddToHead(
247 * DtTopicListStruct **pHead,
248 * DtTopicListStruct **pTale,
254 * Return Value: Void.
256 * Purpose: Adds an element to the top of the given topicList.
258 *****************************************************************************/
259 extern void _DtHelpTopicListAddToHead(
265 DtTopicListStruct **pHead,
266 DtTopicListStruct **pTale,
270 /*****************************************************************************
271 * Function: void _DtTopicListDelUeteHead(
272 * DtTopicListStruct *pHead,
273 * DtTopicListStruct *pTale,
279 * Return Value: Void.
281 * Purpose: Delets an element from the top of the given topicList.
283 *****************************************************************************/
284 extern void _DtHelpTopicListDeleteHead(
285 DtTopicListStruct **pHead,
286 DtTopicListStruct **pTale,
289 /*****************************************************************************
290 * Function: void _DtHelpMapCB(
296 * Return Value: Void.
298 * Purpose: Determins where a new child dialog should be mapped in
299 * relation to its parent.
301 *****************************************************************************/
302 extern XtCallbackProc _DtHelpMapCB(
304 XtPointer client_data,
305 XtPointer call_data );
308 /*****************************************************************************
309 * Function: void _DtHelpMapCenteredCB(
315 * Return Value: Void.
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.
320 *****************************************************************************/
321 extern XtCallbackProc _DtHelpMapCenteredCB(
323 XtPointer client_data,
324 XtPointer call_data);
326 /*****************************************************************************
327 * Function: Boolean _DtHelpResolvePathname(
332 * Return Value: Boolean.
335 * Description: _DtHelpResolvePathname attempts to validate and expand a path
336 * to a Cache Creek help access file.
338 *****************************************************************************/
339 extern Boolean _DtHelpResolvePathname(
342 _DtHelpVolumeHdl *volumeHandle,
343 char *sysVolumeSearchPath,
344 char *userVolumeSearchPath);
347 /*****************************************************************************
348 * Function: void _DtHelpDisplayDefinitionBox(
350 * Widget definitionBox,
352 * char * locationId);
358 * Purpose: This routine will create and post the definition box.
359 * (e.g. the Quick Help Dialog widget)
361 ****************************************************************************/
362 extern void _DtHelpDisplayDefinitionBox(
364 Widget **definitionBox,
368 /*****************************************************************************
369 * Function: void _DtHelpDisplayFormatError()
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.
379 ****************************************************************************/
380 void _DtHelpDisplayFormatError(
381 XtPointer displayArea,
386 /*****************************************************************************
387 * Function: void _DtHelpCommonHelpInit()
393 * Purpose: This routine inits common help stuff
395 ****************************************************************************/
396 void _DtHelpCommonHelpInit(
397 _DtHelpCommonHelpStuff * help);
399 /*****************************************************************************
400 * Function: void _DtHelpCommonHelpClean()
406 * Purpose: This routine cleans up common help stuff
408 ****************************************************************************/
409 void _DtHelpCommonHelpClean(
410 _DtHelpCommonHelpStuff * help,
413 /*****************************************************************************
414 * Function: void _DtHelpSetDlgButtonsWidth
420 * Purpose: This routine cleans up common help stuff
422 ****************************************************************************/
423 void _DtHelpSetButtonPositions(
426 Dimension minFormWidth,
427 Dimension btnMargins,
428 Dimension minBetweenBtnSpace);
430 /*****************************************************************************
431 * Function: _DtHelpXmFontListGetPropertyMax
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
439 * True: got at least one value
440 * False: unable to get any value
443 * This function returns the max value of XGetFontProperty calls
444 * for each font in the XmFontList
446 ****************************************************************************/
447 Boolean _DtHelpXmFontListGetPropertyMax(
450 unsigned long *ret_propertyValue);
452 #endif /* _HelpUtilI_h */
453 /* Do not add anything after this endif. */