cde/programs/dtksh/DtFuncs.sh

   1 # $XConsortium: DtFuncs.sh /main/3 1995/11/01 15:48:57 rswiston $
   2 ###############################################################################
   3 #  (c) Copyright 1993, 1994 Hewlett-Packard Company
   4 #  (c) Copyright 1993, 1994 International Business Machines Corp.
   5 #  (c) Copyright 1993, 1994 Sun Microsystems, Inc.
   6 #  (c) Copyright 1993, 1994 Unix System Labs, Inc., a subsidiary of
   7 #      Novell, Inc.
   8 ###############################################################################
   9
  10 ###############################################################################
  11 #
  12 # DtkshAddButtons - Convenience function for adding 1 or more buttons of the
  13 #                same kind into a composite widget.  Most frequently
  14 #                used to add a collection of buttons into a menupane.
  15 #
  16 # Usages:
  17 #
  18 #   DtkshAddButtons parent widgetClass label1 callback1 [label2 callback2 ...]
  19 #
  20 #   DtkshAddButtons [-w] parent widgetClass variable1 label1 callback1 \
  21 #                   [variable2 label2 callback2 ...]
  22 #
  23 # The "-w" option indicates that the convenience function should return
  24 # the widget handle for each of the created buttons.  The widget handle
  25 # is returned in the specified environment variable.
  26 #
  27 # The widgetClass can be one of the following, and will default to the
  28 # XmPushButtonGadget class, if not specified:
  29 #
  30 #          XmPushButton
  31 #          XmPushButtonGadget
  32 #          XmToggleButton
  33 #          XmToggleButtonGadget
  34 #          XmCascadeButton
  35 #          XmCascadeButtonGadget
  36 #
  37 # Examples:
  38 #
  39 #   DtkshAddButtons $MENU XmPushButtonGadget Open do_Open Save do_Save Quit exit
  40 #
  41 #   DtkshAddButtons -w $MENU XmPushButtonGadget B1 Open do_Open B2 Save do_Save
  42 #
  43
  44 DtkshAddButtons()
  45 {
  46    typeset parent widgetClass callback returnWidget="false" TMP=""
  47    typeset -i paramCount=2
  48
  49    if [ $# -ge 1 ] && [ x"$1" = "x-w" ]; then
  50       returnWidget=true
  51       paramCount=3
  52       shift
  53    fi
  54
  55    if [ $# -lt 2 ]; then
  56       return 1
  57    fi
  58
  59    parent=$1
  60    shift
  61
  62    widgetClass=${1:-XmPushButtonGadget}
  63    shift
  64    case $widgetClass in
  65      XmPushButtonGadget)      callback=activateCallback;;
  66      XmPushButton)            callback=activateCallback;;
  67      XmToggleButtonGadget)    callback=valueChangedCallback;;
  68      XmToggleButton)          callback=valueChangedCallback;;
  69      XmCascadeButtonGadget)   callback=activateCallback;;
  70      XmCascadeButton)         callback=activateCallback;;
  71      *)                       return 1
  72    esac
  73
  74    while [ $# -ge $paramCount ]
  75    do
  76       if [ "$returnWidget" = true ]; then
  77          if [ ! "$3" = "" ]; then
  78             XtCreateManagedWidget "$1" "$1" $widgetClass "$parent" \
  79                       labelString:"$2" ${callback}:"$3"
  80          else
  81             XtCreateManagedWidget "$1" "$1" $widgetClass "$parent" \
  82                       labelString:"$2"
  83          fi
  84          shift 3
  85       else
  86          if [ ! "$2" = "" ]; then
  87             XtCreateManagedWidget Id "btn" $widgetClass "$parent" \
  88                       labelString:"$1" ${callback}:"$2"
  89          else
  90             XtCreateManagedWidget Id "btn" $widgetClass "$parent" \
  91                       labelString:"$1"
  92          fi
  93          shift 2
  94       fi
  95    done
  96    return 0
  97 }
  98
  99
 100
 101 ###############################################################################
 102 #
 103 # DtkshSetReturnKeyControls - Convenience function for configuring a text
 104 #            widget (within a form!) so that the Return key does not
 105 #            activate the default button within the form, but instead
 106 #            moves the focus to the next text widget within the form.
 107 #            This is useful if you have a window which contains a
 108 #            series of text fields, and the default button should not
 109 #            be activated until the user presses the Return key in the
 110 #            last text field.
 111 #
 112 # Usage:
 113 #
 114 #   DtkshSetReturnKeyControls textWidgetId nextTextWidgetId formWidgetId \
 115 #                          defaultButtonId
 116 #
 117 # The textWidgetId parameter specifies the widget which is to be configured
 118 # to catch the 'Return' key, and force the focus to move to the next text
 119 # widget (as indicated by the nextTextWidgetId parameter).  The formWidgetId
 120 # parameter specifies the form which contains the default button, and should
 121 # be the parent of the two text widgets.  The defaultButtonId indicates which
 122 # component is to be treated as the default button within the form.
 123 #
 124 # Examples:
 125 #
 126 #   DtkshSetReturnKeyControls $TEXT1 $TEXT2 $FORM $OK
 127 #   DtkshSetReturnKeyControls $TEXT2 $TEXT3 $FORM $OK
 128 #
 129
 130 DtkshSetReturnKeyControls()
 131 {
 132    if [ $# -ne 4 ]; then
 133       return 1
 134    fi
 135
 136    XtAddCallback $1 focusCallback "XtSetValues $3 defaultButton:NULL"
 137    XtAddCallback $1 losingFocusCallback "XtSetValues $3 defaultButton:$4"
 138
 139    XtOverrideTranslations $1 \
 140        "Ctrl<Key>Return:ksh_eval(\"XmProcessTraversal $2 TRAVERSE_CURRENT\")
 141         <Key>Return:ksh_eval(\"XmProcessTraversal $2 TRAVERSE_CURRENT\")"
 142    return 0
 143 }
 144
 145
 146
 147 ###############################################################################
 148 #
 149 # DtkshUnder
 150 # DtkshOver
 151 # DtkshRightOf
 152 # DtkshLeftOf - Convenience functions for specifying form constraints.
 153 #            This set of functions allow a component to be attached
 154 #            to one of the edges of another component.
 155 #
 156 # Usages:
 157 #
 158 #   DtkshUnder   widgetId [offset]
 159 #   DtkshOver    widgetId [offset]
 160 #   DtkshRightOf widgetId [offset]
 161 #   DtkshLeftOf  widgetId [offset]
 162 #
 163 # The widgetId parameter specifies the widget to which the current
 164 # component is to be attached.  The offset value is optional, and
 165 # defaults to 0 if not specified.
 166 #
 167 # Examples:
 168 #
 169 #   XtCreateManagedWidget BUTTON2 button2 XmPushButton $FORM \
 170 #                         labelString:"Exit" \
 171 #                         $(DtkshUnder $BUTTON1)
 172 #
 173
 174 DtkshUnder()
 175 {
 176    if [ $# -lt 1 ]; then
 177       return 1
 178    fi
 179
 180    echo "topWidget:$1 topAttachment:ATTACH_WIDGET topOffset:${2:-0}"
 181 }
 182
 183 DtkshOver()
 184 {
 185    if [ $# -lt 1 ]; then
 186       return 1
 187    fi
 188
 189    echo "bottomWidget:$1 bottomAttachment:ATTACH_WIDGET bottomOffset:${2:-0}"
 190 }
 191
 192 DtkshRightOf()
 193 {
 194    if [ $# -lt 1 ]; then
 195       return 1
 196    fi
 197
 198    echo "leftWidget:$1 leftAttachment:ATTACH_WIDGET leftOffset:${2:-0}"
 199 }
 200
 201 DtkshLeftOf()
 202 {
 203    if [ $# -lt 1 ]; then
 204       return 1
 205    fi
 206
 207    echo "rightWidget:$1 rightAttachment:ATTACH_WIDGET rightOffset:${2:-0}"
 208 }
 209
 210
 211
 212 ###############################################################################
 213 #
 214 # DtkshFloatRight
 215 # DtkshFloatLeft
 216 # DtkshFloatTop
 217 # DtkshFloatBottom - Convenience functions for specifying form constraints.
 218 #                 This set of functions allow a component to be positioned
 219 #                 independent of the other components within the form.
 220 #                 As the form grows or shrinks, the component maintains
 221 #                 its relative position within the form.  The component
 222 #                 may still grow or shrink, depending upon the other form
 223 #                 constraints which have been specified for the component.
 224 #
 225 # Usages:
 226 #
 227 #   DtkshFloatRight  [position]
 228 #   DtkshFloatLeft   [position]
 229 #   DtkshFloatTop    [position]
 230 #   DtkshFloatBottom [position]
 231 #
 232 # The optional position parameter specifies the relative position
 233 # to which the indicated edge of the component will be positioned.
 234 # A default position is used, if not specified.
 235 #
 236 # Examples:
 237 #
 238 #   XtCreateManagedWidget BUTTON1 button1 XmPushButton $FORM \
 239 #                         labelString:"Ok" \
 240 #                         $(DtkshUnder $SEPARATOR) \
 241 #                         $(DtkshFloatLeft 10) \
 242 #                         $(DtkshFloatRight 40)
 243 #
 244
 245 DtkshFloatRight()
 246 {
 247    echo "rightAttachment:ATTACH_POSITION rightPosition:${1:-0}"
 248 }
 249
 250 DtkshFloatLeft()
 251 {
 252    echo "leftAttachment:ATTACH_POSITION leftPosition:${1:-0}"
 253 }
 254
 255 DtkshFloatTop()
 256 {
 257    echo "topAttachment:ATTACH_POSITION topPosition:${1:-0}"
 258 }
 259
 260 DtkshFloatBottom()
 261 {
 262    echo "bottomAttachment:ATTACH_POSITION bottomPosition:${1:-0}"
 263 }
 264
 265
 266
 267 ###############################################################################
 268 #
 269 # DtkshAnchorRight
 270 # DtkshAnchorLeft
 271 # DtkshAnchorTop
 272 # DtkshAnchorBottom - Convenience functions for specifying form constraints.
 273 #                  This set of functions allow a component to be attached
 274 #                  to one of the edges of the form in such a fashion that
 275 #                  as the form grows or shrinks, the component's position
 276 #                  does not change.  However, depending upon the other
 277 #                  form constaints set on this component, the component
 278 #                  may still grow or shrink in size.
 279 #
 280 # Usages:
 281 #
 282 #   DtkshAnchorRight  [offset]
 283 #   DtkshAnchorLeft   [offset]
 284 #   DtkshAnchorTop    [offset]
 285 #   DtkshAnchorBottom [offset]
 286 #
 287 # The optional offset parameter specifies how far from the edge
 288 # of the form the component should be positioned.  If an offset
 289 # is not specified, then 0 is user.
 290 #
 291 # Examples:
 292 #
 293 #   XtCreateManagedWidget BUTTON1 button1 XmPushButton $FORM \
 294 #                         labelString:"Ok" \
 295 #                         $(DtkshUnder $SEPARATOR) \
 296 #                         $(DtkshAnchorLeft 10) \
 297 #                         $(DtkshAnchorBottom 10)
 298 #
 299
 300 DtkshAnchorRight()
 301 {
 302    echo "rightAttachment:ATTACH_FORM rightOffset:${1:-0}"
 303 }
 304
 305 DtkshAnchorLeft()
 306 {
 307    echo "leftAttachment:ATTACH_FORM leftOffset:${1:-0}"
 308 }
 309
 310 DtkshAnchorTop()
 311 {
 312    echo "topAttachment:ATTACH_FORM topOffset:${1:-0}"
 313 }
 314
 315 DtkshAnchorBottom()
 316 {
 317    echo "bottomAttachment:ATTACH_FORM bottomOffset:${1:-0}"
 318 }
 319
 320
 321
 322 ###############################################################################
 323 #
 324 # DtkshSpanWidth
 325 # DtkshSpanHeight - Convenience functions for specifying form constraints.
 326 #                This set of functions allow a component to be configured
 327 #                such that it spans either the full height or width of
 328 #                the form widget.  This effect is accomplished by attaching
 329 #                two edges of the component (top & bottom for DtkshSpanHeight,
 330 #                and left and right for DtkshSpanWidth) to the form.  The
 331 #                component will typically resize whenever the form is
 332 #                resized.
 333 #
 334 # Usages:
 335 #
 336 #   DtkshSpanWidth  [offset]
 337 #   DtkshSpanHeight   [offset]
 338 #
 339 # The optional offset parameter specifies how far from the edge
 340 # of the form the component should be positioned.  If an offset
 341 # is not specified, then 0 is user.
 342 #
 343 # Examples:
 344 #
 345 #   XtCreateManagedWidget SEPARATOR $FORM XmSeparator \
 346 #                         $(DtkshSpanWidth 1 1)
 347 #
 348
 349 DtkshSpanWidth()
 350 {
 351    echo "leftAttachment:ATTACH_FORM leftOffset:${1:-0} \
 352          rightAttachment:ATTACH_FORM rightOffset:${2:-0}"
 353 }
 354
 355 DtkshSpanHeight()
 356 {
 357    echo "topAttachment:ATTACH_FORM topOffset:${1:-0} \
 358          bottomAttachment:ATTACH_FORM bottomOffset:${2:-0}"
 359 }
 360
 361
 362
 363 ###############################################################################
 364 #
 365 # DtkshDisplayInformationDialog
 366 # DtkshDisplayQuestionDialog
 367 # DtkshDisplayWarningDialog
 368 # DtkshDisplayWorkingDialog
 369 # DtkshDisplayErrorDialog - Convenience functions for creating a single
 370 #                        instance of each of the flavors of the Motif
 371 #                        feedback dialog.  If an instance of the requested
 372 #                        type of dialog already exists, then it will be
 373 #                        reused.  The parent of the dialog is obtained
 374 #                        from the environment variable $TOPLEVEL, which
 375 #                        should be set by the calling shell script.  The
 376 #                        handle for the requested dialog is returned in
 377 #                        one of the following environment variables:
 378 #
 379 #                               _DT_ERROR_DIALOG_HANDLE
 380 #                               _DT_QUESTION_DIALOG_HANDLE
 381 #                               _DT_WORKING_DIALOG_HANDLE
 382 #                               _DT_WARNING_DIALOG_HANDLE
 383 #                               _DT_INFORMATION_DIALOG_HANDLE
 384 #
 385 # WARNING:  IF ATTACHING YOUR OWN CALLBACKS TO THE DIALOG
 386 #           BUTTONS, DO NOT DESTROY THE DIALOG WHEN YOU
 387 #           ARE DONE WITH IT; SIMPLY UNMANAGE THE DIALOG,
 388 #           SO THAT IT CAN BE USED AT A LATER TIME.
 389 #
 390 # Usages:
 391 #
 392 #   DtkshDisplay*Dialog title message okCallback closeCallback helpCallback \
 393 #                    dialogStyle
 394 #
 395 # The "Ok" button is always managed, and by default will simply unmanage
 396 # the dialog.  The "Cancel" and "Help" buttons are only managed when a
 397 # callback is supplied for them.
 398 #
 399 # The "dialogStyle" parameter accepts any of the standard resource settings
 400 # supported by the bulletin board widget.
 401 #
 402 # Examples:
 403 #
 404 #  DtkshDisplayErrorDialog "Read Error" "Unable to read the file" "OkCallback" \
 405 #                         "CancelCallback" "" DIALOG_PRIMARY_APPLICATION_MODAL
 406 #
 407
 408
 409 # Global feedback dialog handles
 410 _DT_ERROR_DIALOG_HANDLE=""
 411 _DT_QUESTION_DIALOG_HANDLE=""
 412 _DT_WORKING_DIALOG_HANDLE=""
 413 _DT_WARNING_DIALOG_HANDLE=""
 414 _DT_INFORMATION_DIALOG_HANDLE=""
 415 _DT_TMP_DIALOG_HANDLE=""
 416
 417 #
 418 # This function was accidentally *not* renamed to DtkshDisplayErrorDialog
 419 # when the sample implementation of dtksh was released; however, the
 420 # documentation tells users to use DtkshDisplayErrorDialog, but it did not
 421 # exist.  Therefore, to be backwards compatible, both DtDisplayErrorDialog
 422 # and DtkshDisplayErrorDialog are defined.
 423 #
 424 DtDisplayErrorDialog()
 425 {
 426    _DtkshDisplayFeedbackDialog "$_DT_ERROR_DIALOG_HANDLE" "Error" "${@:-}"
 427    if [ "$_DT_ERROR_DIALOG_HANDLE" = "" ] ; then
 428       _DT_ERROR_DIALOG_HANDLE=$_DT_TMP_DIALOG_HANDLE
 429    fi
 430    return 0
 431 }
 432
 433 DtkshDisplayErrorDialog()
 434 {
 435    _DtkshDisplayFeedbackDialog "$_DT_ERROR_DIALOG_HANDLE" "Error" "${@:-}"
 436    if [ "$_DT_ERROR_DIALOG_HANDLE" = "" ] ; then
 437       _DT_ERROR_DIALOG_HANDLE=$_DT_TMP_DIALOG_HANDLE
 438    fi
 439    return 0
 440 }
 441
 442 DtkshDisplayQuestionDialog()
 443 {
 444    _DtkshDisplayFeedbackDialog "$_DT_QUESTION_DIALOG_HANDLE" "Question" "${@:-}"
 445    if [ "$_DT_QUESTION_DIALOG_HANDLE" = "" ] ; then
 446       _DT_QUESTION_DIALOG_HANDLE=$_DT_TMP_DIALOG_HANDLE
 447    fi
 448    return 0
 449 }
 450
 451 DtkshDisplayWorkingDialog()
 452 {
 453    _DtkshDisplayFeedbackDialog "$_DT_WORKING_DIALOG_HANDLE" "Working" "${@:-}"
 454    if [ "$_DT_WORKING_DIALOG_HANDLE" = "" ] ; then
 455       _DT_WORKING_DIALOG_HANDLE=$_DT_TMP_DIALOG_HANDLE
 456    fi
 457    return 0
 458 }
 459
 460 DtkshDisplayWarningDialog()
 461 {
 462    _DtkshDisplayFeedbackDialog "$_DT_WARNING_DIALOG_HANDLE" "Warning" "${@:-}"
 463    if [ "$_DT_WARNING_DIALOG_HANDLE" = "" ] ; then
 464       _DT_WARNING_DIALOG_HANDLE=$_DT_TMP_DIALOG_HANDLE
 465    fi
 466    return 0
 467 }
 468
 469 DtkshDisplayInformationDialog()
 470 {
 471    _DtkshDisplayFeedbackDialog "$_DT_INFORMATION_DIALOG_HANDLE" "Information" \
 472                             "${@:-}"
 473    if [ "$_DT_INFORMATION_DIALOG_HANDLE" = "" ] ; then
 474       _DT_INFORMATION_DIALOG_HANDLE=$_DT_TMP_DIALOG_HANDLE
 475    fi
 476    return 0
 477 }
 478
 479
 480
 481 ###############################################################################
 482 #
 483 # DtkshDisplayQuickHelpDialog
 484 # DtkshDisplayHelpDialog - Convenience functions for creating a single
 485 #                       instance of a help dialog and a quick help
 486 #                       dialog.  If an instance of the requested type
 487 #                       of help dialog already exists, then it will be
 488 #                       reused.  The parent of the dialog is obtained
 489 #                       from the environment variable $TOPLEVEL, which
 490 #                       should be set by the calling shell script.  The
 491 #                       handle for the requested dialog is returned in
 492 #                       one of the following environment variables:
 493 #
 494 #                               _DT_HELP_DIALOG_HANDLE
 495 #                               _DT_QUICK_HELP_DIALOG_HANDLE
 496 #
 497 # WARNING:  DO NOT DESTROY THIS DIALOG, UNLESS YOU ALSO CLEAR THE
 498 #           CORRESPONDING ENVIRONMENT VARIABLE, SO THAT THIS CODE
 499 #           WILL NOT ATTEMPT TO REUSE THE DIALOG AGAIN.
 500 #
 501 # Usages:
 502 #
 503 #   DtkshDisplay*HelpDialog title helpType helpInformation [locationId]
 504 #
 505 # The meaning of the parameters is dependent upon the value specified
 506 # for the 'helpType' parameter.  There meanings are explained below:
 507 #
 508 #      helpType = HELP_TYPE_TOPIC
 509 #           helpInformation = help volume name
 510 #           locationId      = help topic location id
 511 #
 512 #      helpType = HELP_TYPE_STRING
 513 #           helpInformation = help string
 514 #           locationId      = <not used>
 515 #
 516 #      helpType = HELP_TYPE_DYNAMIC_STRING
 517 #           helpInformation = help string
 518 #           locationId      = <not used>
 519 #
 520 #      helpType = HELP_TYPE_MAN_PAGE
 521 #           helpInformation = man page name
 522 #           locationId      = <not used>
 523 #
 524 #      helpType = HELP_TYPE_FILE
 525 #           helpInformation = help file name
 526 #           locationId      = <not used>
 527 #
 528 # Examples:
 529 #
 530 #   DtkshDisplayHelpDialog "Help On Dtksh" HELP_TYPE_FILE "HelpFileName"
 531 #
 532
 533
 534 # Global help dialog handles
 535 _DT_HELP_DIALOG_HANDLE=""
 536 _DT_QUICK_HELP_DIALOG_HANDLE=""
 537
 538
 539 DtkshDisplayQuickHelpDialog()
 540 {
 541    _DtkshDisplayHelpDialog "$_DT_QUICK_HELP_DIALOG_HANDLE" "Quick" "${@:-}"
 542    if [ "$_DT_QUICK_HELP_DIALOG_HANDLE" = "" ] ; then
 543       _DT_QUICK_HELP_DIALOG_HANDLE=$_DT_TMP_DIALOG_HANDLE
 544    fi
 545 }
 546
 547
 548 DtkshDisplayHelpDialog()
 549 {
 550    _DtkshDisplayHelpDialog "$_DT_HELP_DIALOG_HANDLE" "" "${@:-}"
 551    if [ "$_DT_HELP_DIALOG_HANDLE" = "" ] ; then
 552       _DT_HELP_DIALOG_HANDLE=$_DT_TMP_DIALOG_HANDLE
 553    fi
 554 }
 555
 556
 557 ##############################################################################
 558 #
 559 # This internal shell function performs most of the work required to
 560 # create an instance of a feedback dialog (error, warning, information,
 561 # working and question).  It will reuse an existing instance of the
 562 # requested type of feedback dialog, if one has already been created;
 563 # otherwise, it will create a new one.
 564 #
 565 # The "Ok" button is always managed, and by default will simply unpost
 566 # the dialog.  The "Cancel" and "Help" buttons are only managed if the
 567 # callers specifies a callback for the butttons.  Both the "Ok" and
 568 # "Cancel" buttons rely on the fact that the 'autoUnpost' resource for
 569 # the dialog is 'True'.
 570 #
 571 # The implied parent of the dialog is identified by the environment
 572 # variable '$TOPLEVEL'.
 573 #
 574 # The incoming parameters are defined as follows (note that $1 and $2 are
 575 # defined by the convenience function which is calling us, while $3 - $8
 576 # are the parameters which were passed by the caller to the convenience
 577 # function:
 578 #
 579 #      $1 = existing dialog handle, or "" if first time
 580 #      $2 = type of feedback dialog (Information, Question, Working, ... )
 581 #      $3 = dialog title
 582 #      $4 = message string
 583 #      $5 = okCallback
 584 #      $6 = cancelCallback
 585 #      $7 = helpCallback
 586 #      $8 = dialogStyle
 587 #
 588
 589 _DtkshDisplayFeedbackDialog()
 590 {
 591    if [ "$1" = "" ]; then
 592       XmCreate${2}Dialog _DT_TMP_DIALOG_HANDLE $TOPLEVEL "$2"
 593    else
 594       _DT_TMP_DIALOG_HANDLE=$1
 595    fi
 596
 597    XtSetValues $_DT_TMP_DIALOG_HANDLE \
 598         dialogTitle:"${3:-$2}" \
 599         messageString:"${4:- }" \
 600         dialogStyle:"${8:-DIALOG_MODELESS}"
 601
 602    if [ $# -ge 5 ] && [ "$5" != "" ]; then
 603       XtSetValues $_DT_TMP_DIALOG_HANDLE okCallback:"$5"
 604    fi
 605
 606    if [ $# -lt 6 ] || [ "$6" = "" ]; then
 607       XtUnmanageChild $(XmMessageBoxGetChild "-" $_DT_TMP_DIALOG_HANDLE \
 608                         DIALOG_CANCEL_BUTTON)
 609    else
 610       XtSetValues $_DT_TMP_DIALOG_HANDLE cancelCallback:"$6"
 611    fi
 612
 613    if [ $# -lt 7 ] || [ "$7" = "" ]; then
 614       XtUnmanageChild $(XmMessageBoxGetChild "-" $_DT_TMP_DIALOG_HANDLE \
 615                         DIALOG_HELP_BUTTON)
 616    else
 617       XtSetValues $_DT_TMP_DIALOG_HANDLE helpCallback:"$7"
 618    fi
 619
 620    _DtkshPositionDialog "$1"
 621    XtManageChild $_DT_TMP_DIALOG_HANDLE
 622    return 0
 623 }
 624
 625
 626 ##############################################################################
 627 #
 628 # This internal shell function performs most of the work required to
 629 # create an instance of a help dialog (regular help or quick help)
 630 # It will reuse an existing instance of the requested type of help
 631 # dialog, if one has already been created; otherwise, it will create
 632 # a new one.
 633 #
 634 # The implied parent of the dialog is identified by the environment
 635 # variable '$TOPLEVEL'.
 636 #
 637 # The incoming parameters are defined as follows (note that $1 and $2 are
 638 # defined by the convenience function which is calling us, while $3 - $6
 639 # are the parameters which were passed by the caller to the convenience
 640 # function:
 641 #
 642 #      $1 = existing dialog handle, or "" if first time
 643 #      $2 = type of help dialog (Quick or "")
 644 #      $3 = dialog title
 645 #      $4 = help type
 646 #      $5 = help information:
 647 #              help volume (if help type = HELP_TYPE_TOPIC)
 648 #              help string (if help type = HELP_TYPE_STRING)
 649 #              help string (if help type = HELP_TYPE_DYNAMIC_STRING)
 650 #              man page name (if help type = HELP_TYPE_MAN_PAGE)
 651 #              help file name (if help type = HELP_TYPE_FILE)
 652 #      $6 = help location Id (if help type = HELP_TYPE_TOPIC)
 653 #
 654
 655 _DtkshDisplayHelpDialog()
 656 {
 657    typeset helpType ARG1="" ARG2="" ARG3=""
 658    typeset helpType VAL1="" VAL2="" VAL3=""
 659
 660    helpType="${4:-HELP_TYPE_TOPIC}"
 661    ARG1="helpType:"
 662    VAL1="$helpType"
 663
 664    case $helpType in
 665       HELP_TYPE_TOPIC)          ARG2="helpVolume:"
 666                                 VAL2="${5:-}"
 667                                 ARG3="locationId:"
 668                                 VAL3="${6:-_HOMETOPIC}";;
 669       HELP_TYPE_STRING)         ARG2="stringData:"
 670                                 VAL2="${5:-}";;
 671       HELP_TYPE_DYNAMIC_STRING) ARG2="stringData:"
 672                                 VAL2="${5:-}";;
 673       HELP_TYPE_MAN_PAGE)       ARG2="manPage:"
 674                                 VAL2="${5:-}";;
 675       HELP_TYPE_FILE)           ARG2="helpFile:"
 676                                 VAL2="${5:-}";;
 677       *)  return 1;;
 678    esac
 679
 680    if [ "$1" = "" ]; then
 681       if [ "$ARG3" != "" ]; then
 682          DtCreateHelp${2}Dialog _DT_TMP_DIALOG_HANDLE $TOPLEVEL "$2" \
 683                    "${ARG1}${VAL1}" "${ARG2}${VAL2}" "${ARG3}${VAL3}"
 684       else
 685          DtCreateHelp${2}Dialog _DT_TMP_DIALOG_HANDLE $TOPLEVEL "$2" \
 686                    "${ARG1}${VAL1}" "${ARG2}${VAL2}"
 687       fi
 688    else
 689       _DT_TMP_DIALOG_HANDLE=$1
 690       if [ "$ARG3" != "" ]; then
 691          XtSetValues $_DT_TMP_DIALOG_HANDLE \
 692                    "${ARG1}${VAL1}" "${ARG2}${VAL2}" "${ARG3}${VAL3}"
 693       else
 694          XtSetValues $_DT_TMP_DIALOG_HANDLE \
 695                    "${ARG1}${VAL1}" "${ARG2}${VAL2}"
 696       fi
 697    fi
 698
 699    if [ "$2" = "Quick" ]; then
 700       XtSetSensitive $(DtHelpQuickDialogGetChild "-" $_DT_TMP_DIALOG_HANDLE \
 701                     HELP_QUICK_HELP_BUTTON) false
 702    fi
 703    XtSetValues $(XtParent "-" $_DT_TMP_DIALOG_HANDLE) title:"${3:-Help}"
 704    _DtkshPositionDialog "$1"
 705    XtManageChild $_DT_TMP_DIALOG_HANDLE
 706    return 0
 707 }
 708
 709
 710 ##############################################################################
 711 #
 712 # This internal shell function takes care of positioning the dialog so
 713 # that it is centered over the window for which it is transient; if the
 714 # window it is transient for is not currently managed, then the window
 715 # will be positioned over in the center of the screen.
 716 #
 717 # Positioning does not occur that first time the dialog is posted; that
 718 # is taken care of automatically by Motif and the window manager.  It
 719 # only needs to happen for subsequent postings.
 720 #
 721
 722 _DtkshPositionDialog()
 723 {
 724    typeset -i WIDTH HEIGHT X_P Y_P WIDTH_P HEIGHT_P
 725    typeset -i finalX finalY
 726
 727    if [ "$1" != "" ] && ! XtIsManaged $1 && XtIsShell $TOPLEVEL ; then
 728       XtGetValues $1 width:WIDTH height:HEIGHT
 729       if XtIsRealized $TOPLEVEL; then
 730          XtGetValues $TOPLEVEL x:X_P y:Y_P width:WIDTH_P height:HEIGHT_P
 731          (( finalX=$X_P+($WIDTH_P-$WIDTH)/2 ))
 732          (( finalY=$Y_P+($HEIGHT_P-$HEIGHT)/2 ))
 733       else
 734          (( finalX=($(XWidthOfScreen "-" $(XtScreen "-" $1) )-$WIDTH)/2 ))
 735          (( finalY=($(XHeightOfScreen "-" $(XtScreen "-" $1) )-$HEIGHT)/2 ))
 736       fi
 737       XtSetValues $(XtParent "-" $1) x:$finalX y:$finalY
 738    fi
 739 }