[Integration Kit Contents] [Integration Kit What's New] [Integration Kit Function Index] [More Documentation] [PTC]

Dialog Callback Functions Manual

Table of Contents

  1. Introduction
  2. Callback Registration
  3. Callback Types
  4. Warning Box Defaults
  5. Recorder Files

Function Index Top of Page

1. Introduction

Dialog callbacks can be hooked to existing dialogs to perform extended modeling checks. A dialog callback is triggered after interactive input is entered into the dialog and it can generate an advisor message when it detects an issue that needs to be brought to the attention of the user.

Dialog callbacks can respond immediately to issues of interest as they arise. Dialog callbacks can execute dedicated checks that are relevant to the dialog at hand. By contrast, a general post-checking dialog needs to be launched manually by the user and typically activates a wider range of tests, thereby possibly raising performance issues.

This document assumes an in-depth understanding of the dialog generator, as described in the Integration Kit document Dialog Generator Manual.

Four types of callbacks are provided

All callbacks can use any combination of

When a dialog is executed, it will call the dialog callbacks that have been registered to that dialog. If more than one callback has been registered to a dialog, then the callback functions will be executed in the order in which they were registered.

Dialog callbacks have access to the current values of dialog input variables and can use these values to investigate the current state of the model.

A brief and up-to-date description of the currently valid dialog input variables is provided in the online reference manual.

If an error situation is detected within an after-value-changed or before-ok-action dialog callback, the function should return a list of all the found issues. Each issue specifies the information that needs to be presented to the user in a warning box, such as title, message, help action, severity and button labels. In addition, the issue specification should contain error information that will later be passed on to the on-error and after-ok-action callback functions.

The dialog callback system will loop through the returned issues. For each issue it will

  1. call the on-error callback in a :before-warning mode to allow the creation of temporary feedback. The on-error function will receive the error information that has been provided in the issue specification.
  2. display the warning box according the issue specification.
  3. call the on-error callback in an :after-warning mode after the user responded to the warning box to allow the cleanup of temporary feedback. In this case, the on-error function will receive the return value of the on-error call in step 1.

If further error issues need to be displayed to the user, the warning box will provide an additional button labeled "Yes to all". If this button is chosen, then all remaining issues will be triggered (including the associated on-error callback) without further user interaction. If "Yes" or "No" is chosen, then the next issue will be displayed. This procedure is repeated until all issues have been executed.

If several before-ok-action issues occur, the ok-action will only be executed if all warnings have been confirmed with "Yes" or "Yes to all".

The warning box displays a "?" button if a help action was specified in the issue specification or if a default help action has been specified.

The warning box is modal, that is, all other windows in the application are blocked until the warning box has been confirmed by the user.

Issues generated by the after-value-changed callback function must be confirmed via the "Yes" button.

Issues generated by the before-ok-action callback function must be confirmed either by the "Yes" or the "No" button:

Dialog callbacks are called when the dialog is used interactively or is being replayed within a recorder file. Since the warning box generated by a callback function is modal, special care is required during the replay, as described in section 5. Recorder Files.

Dialog callbacks are not triggered when the dialog is called within the scope of sd-call-cmds.

Warning: Dialog callbacks have access to dialog input variables. These variables may be subject to modification from one release to another and may change without notice. It is therefore important to verify the validity of a dialog callback when upgrading to a new release.

Function Index Top of Page

2. Callback Registration

The following functions can be used to register and unregister dialog callback functions:


SD-REGISTER-DIALOG-CALLBACK [global function]

(sd-register-dialog-callback
                    :dialog-name         dialog-name
                    :after-value-changed after-value-changed-function-name
                    :before-ok-action    before-ok-action-function-name
                    :on-error            on-error-function-name
                    :after-ok-action     after-ok-action-function-name)
Description:
Registers the specified dialog callback functions.

Parameters:
Dialog-Name {STRING [""]}
Dialog that will trigger the specified callback functions.
If this argument is omitted or if the dialog "" is specified, then the callback functions will be applied to all dialogs.
Callbacks cannot be hooked to the following kinds of dialogs:
  • a dialog with :dialog-type set to :interrupt
  • a dialog with :dialog-control set to :sequential or :sequential-loop
  • an action routine that was not created via sd-defdialog
After-Value-Changed {SYMBOL [no-effect]}
Specifies the name of the after-value-changed callback function.
If this argument is omitted, then no after-value-changed callback will be triggered.
Before-OK-Action {SYMBOL [no-effect]}
Specifies the name of the before-ok-action callback function.
If this argument is omitted, then no before-ok-action callback will be triggered.
On-Error {SYMBOL [no-effect]}
Specifies the name of the on-error callback function.
If this argument is omitted, then no on-error callback will be triggered.
After-OK-Action {SYMBOL [no-effect]}
Specifies the name of the after-ok-action callback function.
If this argument is omitted, then no after-ok-action callback will be triggered.

Return Value:
A cookie if the callback registration was successful or nil if it was unsuccessful.

Example:
(setq *my-cookie*
      (sd-register-dialog-callback
         :dialog-name "SHA_PUNCH"
         :after-value-changed 'punch-after-value-changed-function
         :before-ok-action 'punch-before-ok-action-function
         :on-error 'punch-on-error-function
         :after-ok-action 'punch-after-ok-action))


SD-UNREGISTER-DIALOG-CALLBACK [global function]

(sd-unregister-dialog-callback cookie)
Description:
Removes the callbacks associated with the specified cookie.

Parameters:
Cookie {Cookie}
A dialog callback cookie, generated by sd-register-dialog-callback.

Return Value:
t
Example:
(sd-unregister-dialog-callback *my-cookie*)

Function Index Top of Page

3. Callback Types

3.1. After-Value-Changed Callback

The after-value-changed callback is triggered after the input of a user value.

The dialog callback will be called if the :check-function of the input variable is satisfied, thus avoiding unnecessary callback calls for illegal user inputs. Furthermore, the must-variable-check of the dialog variables must be satisfied, thus avoiding callback calls before all relevant input data has been collected. This must-variable-check typically does not generate an error message for the user.

In more detail, the dialog callback will be called as soon as the following conditions are satisfied:

Warning: The existence and details of the check functions and must-variable-checks of a Creo Elements/Direct Modeling dialog are not accessible to a callback developer. The above triggering conditions serve as a guideline when to expect an after-value-changed callback to trigger.

The after-value-changed callback must adhere to the following conventions:

(defun punch-after-value-changed-function (dialog variable input-variables)
  (if (some-test (getf input-variables :my_variable))
    :ok
    (list (list :message "push error occured")))
)

(defun punch-after-value-changed-function (dialog variable input-variables)
  (if (some-test (getf input-variables :my_variable))
    :ok
    (list 
      (list :message          "punch error occured"
            :error-info       (create-punch-error-info "AFTER-VALUE-PUNCH-CHANGED-ERROR-INFO")
            :help-action      `(punch-help "after value changed 1" ,variable)
            :title            "My Title"
            :yes-label        "My Yes"
            :yes-to-all-label "My Yes to all"
            :severity         :high)))
)


3.2. Before-OK-Action Callback

The before-ok-action callback is triggered when the user clicks on the "OK" button.

The callback will be called if the must-variable-check of the dialog variables is satisfied. Typically the must-variable-check will generate an error message if it is not satisfied.

In more detail, this dialog callback is called if either of the following two conditions are satisfied:

Warning: The existence and details of must-variable-checks of a Creo Elements/Direct Modeling dialog are not accessible to a callback developer. The above triggering conditions serve as a guideline when to expect a before-ok-action callback to trigger.

The before-ok-action callback must adhere to the following conventions:

(defun punch-before-ok-action-function (dialog input-variables)
  (if (some-test (getf input-variable :my_variable))
    :ok
    (list (list :message "push error occured")))
)

(defun punch-before-ok-action-function (dialog input-variables)
  (if (some-test (getf input-variable :my_variable))
     :ok
     (list
       (list :message          "punch error occured"
             :error-info       (create-punch-error-info "BEFORE-OK-ACTION-PUNCH-ERROR-INFO-")
             :help-action      `(punch-help "before ok action 1")
             :title            "My Title"
             :yes-label        "My Yes"
             :yes-to-all-label "My Yes to all"
             :no-label         "My No"
             :severity         :high)))
)


3.3. On-Error Callback

The on-error callback is triggered after an after-value-changed or a before-ok-action callback has returned error issues. It is triggered twice for each issue:

If several issues exist, the warning box will display a "Yes to all" button. If the user selects this "Yes to all" button, all remaining issues will be processed silently (that is without displaying a warning box). The on-error callbacks of the remaining issues will be called.

The on-error callback must adhere to the following conventions:

(defun my_punch-on-error-1 (dialog callback-context response mode error-info)
  (format t "~%my punch on error 1 called with ~A ~A ~A ~A ~A"
            dialog callback-context response mode error-info))

3.4. After-OK-Action Callback

The after-ok-action callback is triggered when

The after-ok-action callback must adhere to the following conventions:

(defun my_punch-after-ok-action-1 (dialog input-variables callback-context error-info)
  (format t "~%my punch after ok action 1 called with ~A ~A ~A ~A"
            dialog input-variables callback-context error-info))

If the callback-context is :completion, then it is feasible to create model changes via calls to sd-call-cmds within the after-ok-action callback. For example, the attachment of a permanent 3D note or a dimension to the model via a Creo Elements/Direct Modeling command will generate a model state change. These additional model states will be merged into the resulting undo step of the dialog that triggered the callback.

The callback-contexts :deferred-completion and :exception are provided for the sake of completeness and for experimental purposes only.

Warning: It is not recommended to change the model state within the other diallog callbacks, i.e. within after-value-changed, before-ok-action and on-error. Some dialogs monitor the model state and may not be tolerant to model state changes within these callbacks.

Function Index Top of Page

4. Warning Box Defaults

A default warning box option will be used if a dialog callback does not specify that option. These defaults can be specified by means of the function sd-set-dialog-callback-warning-default.


SD-SET-DIALOG-CALLBACK-WARNING-DEFAULT [global function]

(sd-set-dialog-callback-warning-default key value)
Description:
Sets the default value for a particular key of the dialog callback warning box.

Parameters:
Key {:message | :title | :yes-label | :yes-to-all-label | :no-label | :severity | :help-action}
A keyword
Value {STRING | KEYWORD| LISP-form}
A string must be supplied for all keys except :severity and :help-action.
The key :severity requires one of the following keyword values {:none | :low | :medium |:high}.
The key :help-action requires a LISP form as value. This form will be evaluated when the help button is pressed.

Return Value:
The supplied value

Example:
(sd-set-dialog-callback-warning-default :yes-label "Continue")
        => "Continue"

(sd-set-dialog-callback-warning-default :help-action '(my-help "case 23"))
        => (my-help "case 23")

Function Index Top of Page

5. Recorder Files

Most confirmation warnings that occur in Creo Elements/Direct Modeling dialogs are non-modal. They do not block other Creo Elements/Direct Modeling windows. The user response is inserted into the recorder file during the generation of the recorder file and is read from the recorder file during the replay of the recorder file. These warnings are not displayed on the screen during the replay of the recorder file.

By contrast, a dialog callback warning box is modal and thus blocks all Creo Elements/Direct Modeling windows. The user response to a modal warning box is not inserted into the recorder file during recording.

If a dialog callback warning box is reached during the replay of the recorder file, the warning box will be displayed on the screen, block all Creo Elements/Direct Modeling windows and again request a user response. The user response cannot be read from the recorder file, even if it existed in the recorder file.

In the above respect, a dialog callback warning box behaves in the same as an error box.

After creating a recorder file that activates a dialog callback error it is therefore useful to add special code to the recorder file. This additional code could redefine the function sd-display-warning in such a way that it returns the desired user response.

Assume, for example, that an input ":width 100" generates an after-value-changed callback warning in the the following recorder file

;;; Begin of recorder file ;;;;;;;;;;;;;;;;;;
...
:width 100
...
;;; End of recorder file ;;;;;;;;;;;;;;;;;;;;

and that the user responded with :yes while generating the recorder file.

Then we could wrap the contents of this recorder file as follows

;;; Set aside the original code of the function sd-display-warning.
(defvar *sd-display-warning-function* (symbol-function 'oli:sd-display-warning))

;;; Redefine the function sd-display-warning to return the value :yes.
(defun oli:sd-display-warning (msg &key title push-1 push-2 push-other severity help-action)
  :yes)

;;; Begin of recorder file ;;;;;;;;;;;;;;;;;;
...
:width 100
...
;;; End of recorder file ;;;;;;;;;;;;;;;;;;;;

;;; Reset the function sd-display-warning to its original form.
(setf (symbol-function 'oli::sd-display-warning)
      *sd-display-warning-function*)

[Integration Kit Contents] [Integration Kit What's New] [Integration Kit Function Index] [More Documentation] [PTC]
© 2023 Parametric Technology GmbH
(a subsidiary of PTC Inc.), All Rights Reserved