Dialog Callback Functions Manual

Table of Contents

1. Introduction
2. Callback Registration
3. Callback Types
   • 3.1. After Value Changed Callback
   • 3.2. Before OK Action Callback
   • 3.3. On Error Callback
   • 3.4. After OK Action Callback
4. Warning Box Defaults
5. Recorder Files

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

• after-value-changed
  • Called after every parameter input (if check-function and must-variables-check are satisfied)
  • Has access to dialog variables
  • Checks model and user input parameters
  • Provides feedbacks, attaches attributes
  • Does not prompt the error itself, but indicates them to caller
  • Intended for fast checks (typically < 1 sec)
• before-ok-action
  • Called when user hits the "OK" button
  • Otherwise similar to after-value-changed callback
  • If the callback check is okay the ok-action is performed.
    If the callback check is not okay, the user can then decide to defer the execution of the ok-action (and to remain in the dialog) or to proceed with the execution of the ok-action.
  • Costly checks to be performed here
• on-error
  • Called after the before-ok-action or after-value-changed callback returns one or more error issues
  • Called twice for each error issue:
    1. the first call is before the display of the warning box to create temporary feedback
    2. the second call is after the user responds to the warning box to cleanup temporary feedback
• after-ok-action
  • Called after the execution of the ok-action when
    • the before-ok-action callback returned an error and when
    • the user decided to proceed with the execution of the ok-action (thus triggering the on-error callback before entering the ok-action)
  • Provides permanent feedbacks or permanent attributes, log issues...

All callbacks can use any combination of

• LISP/IKIT functionality
• .NET API (via LISP)
• .NET add-in functionality

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:

• The "Yes" button tells the dialog to start with the execution of the ok-action. In this case the dialog will typically terminate after the execution of the ok-action. However, if the ok-action fails and calls sd-return-from-ok-action, the dialog will not terminate and will enter the top prompt state or the variable specified by the options :prompt-variable or :ok-action-next-variable.

• The "No" button tells the dialog to defer the ok-action execution and to remain active. In this case the dialog will enter the same state as just mentioned above.

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.

2. Callback Registration

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

• sd-register-dialog-callback
• sd-unregister-dialog-callback

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*)

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:

• The :check-function of the input variable is satisfied, and
• The must variable check condition is satisfied, that is either
  • The must variable check is disabled (by means of the function sd-disable-must-variable-check), or
  • If the must variable check is enabled, it must be satisfied. By default, this means that no input fields are yellow.
    If :ok-action-precondition is specified, the return value of this option must return either :ok or :default. In the latter case, the default must variable check must be satisfied.
• The after input actions of the input variable, such as :after-input, :end-input-feedback and :next-variable, have been executed.

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:

• The after-value-changed callback function requires three arguments:
  1. Dialog [STRING] - The dialog that triggered the callback.
  2. Variable [KEYWORD]- The variable that triggered the callback.
  3. Input-Variables [PLIST]- A property list containing the dialog variables and their values.

• The return value of the after-value-changed callback function must adhere to the following rules:
  1. If the check was successful the function must return :ok
  2. If the check was unsuccessful the function must return a list of issues. Each issue is specified via a property list with the following properties in any order
     • :message specifying the text to be displayed in the warning box.
     • :error-info specifying any LISP object. This error info will be passed to the on-error function.
     • :help-action specifying a LISP form. This form will be evaluated when the help button is pressed.
     • :title specifying the title of the warning box
     • :yes-label specifying the yes button in the warning box
     • :yes-to-all-label specifying the yes-to-all button in the warning box
     • :severity specifying additional colored emphasis in the warning box. The possible values are :none (default), :high, :low and :medium.

(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:

• The must variable check is disabled (by means of the function sd-disable-must-variable-check), or
• If the must variable check is enabled, it must be satisfied. By default, this means that no input fields are yellow.
  If :ok-action-precondition is specified, the return value of this option must return either :ok or :default. In the latter case, the default must variable check must be 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:

• The before-ok-action callback function requires two arguments:
  1. Dialog [STRING]- The dialog that triggered the callback.
  2. Input-Variables [PLIST] - A property list containing the dialog variables and their values.

• The return value of the before-ok-action callback function must adhere to the following rules:
  1. If the check was successful the function must return :ok
  2. If the check was unsuccessful the function must return a list of issues. Each issue is specified via a property list with the following properties in any order
     • :message specifying the text to be displayed in the warning box.
     • :error-info specifying any LISP object. This error info will be passed to the on-error function.
     • :help-action specifying a LISP form. This form will be evaluated when the help button is pressed.
     • :title specifying the title of the warning box
     • :yes-label specifying the yes button in the warning box
     • :yes-to-all-label specifying the yes-to-all button in the warning box
     • :severity specifying additional colored emphasis in the warning box. The possible values are :none (default), :high, :low and :medium.

(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:

• before the display of the warning box and
• after the user has confirmed the warning box.

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:

• The on-error callback function requires 5 arguments:
  1. Dialog [STRING] - The dialog that triggered the callback.
  2. Callback-Context [:after-value-changed | :before-ok-action]
  3. Response [:yes | :yes-to-all | :no] - Answer selected by the user in the warning box.
  4. Mode [:before-warning | :after-warning] - Indicates whether the on-error callback has been triggered before or after the display of the warning box.
  5. Error-Info [LISP Object] - Custom data from the following sources:
     • when mode = :before-warning, then error-info is the error-info returned by the after-value-changed or before-ok-action. This data will allow the generation of temporary feedback.
     • when mode = :after-warning, then error-info is the return value of the previous call to on-error. This data will allow the removal of the previously created temporary feedback.

• The return value of the on-error callback depends on the mode argument. If
  • mode = :before-warning, the function should return all created feedback objects. This return value will be passed into the second call to the on-error function.
  • mode = :after-warning, the return value is irrelevant.

(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 before-ok-action callback has returned an error, and
• the user has confirmed the warning box with "Yes" (or previously selected the "Yes to all" button in the case of multiple callback registrations to the dialog), and
• the on-error callback has been executed, and
• the ok-action has been executed.

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

• The after-ok-action callback function requires 4 arguments:
  1. Dialog [STRING] - The dialog that triggered the callback.
  2. Input-Variables [PLIST] - A property list containing the dialog variables and their values.
  3. Callback-Context [:completion | :deferred-completion | :exception]
     The ok-action can be exited in 3 ways:
     • :completion - the ok-action completed successfully and the dialog is will terminate.
     • :deferred-completion - the ok-action exited via a call to sd-return-from-ok-action, thus deferring the termination of the dialog.
     • :exception - the ok-action reached an exception and the dialog will terminate.
  4. Error-Info [LISP Object] - Custom data returned by the previously called before-ok-action callback function.

• The return value of the after-ok-action callback is irrelevant.

(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.

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")

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*)