1. Types of Validations
2. Snapper Implementation
   • Example
3. System Validation Dialog
4. Additional Info on Validations
   • Info Callback
   • Zoom Changed Callback

Snapper Validations are used to highlight something from a particular Snapper or group of Snappers to the end-user.

There are four different types of validations you can convey, which are Error, Invalid, Warning, and Note, each type listed as ordered in a System Validation Dialog:

Types of Validations

Snapper Implementation

You'll find the appendInvalidation() in the Snapper class:

extend public void appendInvalidation(InvalidList list) { }

This method will be called in construction or refresh of the System Validation Dialog. Therefore, your implementation would add to the list argument of this method whenever there is a condition is met.

The 4 different types of validations need to accept a unique key to uniquely identify a validation, the invalidation description, and the list of Snappers involved in the validation.

Example

    /**
     * Append invalidation.
     */
    public void appendInvalidation(InvalidList list) {
        super(..);

        if (putNote == true)
          list.putNote("noteValidation", $noteValidationDescription, {Snapper: this});

        if (putWarning == true)
          list.putWarning("warningValidation", $warningValidationDescription, {Snapper: this});

        if (putInvalid == true)
          list.putInvalid("invalidValidation", $invalidValidationDescription, {Snapper: this});

        if (putError == true)
          list.putError("errorValidation", $errorValidationDescription, {Snapper: this});
    }

System Validation Dialog

This dialog is a singleton that exists in cm/core/ui/invalidListDialog.cm, and can be created with showInvalidListDialog() in the same cm file.

On creation or refresh, it will gather all Snappers in the mainSpace and call appendInvalidation() of each Snapper. Adding into the list of all invalid configurations of each Snapper within mainSpace to this single dialog.

Additional Info on Validations

Info Callback

If the description of the validation is not enough, or perhaps you want something extra to be done from a validation, you can additionally add an info button for users to click into that triggers a callback function. This can be done by adding a function into the infoCallback argument:

    /**
     * Append invalidation.
     */
    public void appendInvalidation(InvalidList list) {
        super(..);
        list.putNote("infoCallbackExample", "Info Callback Example", {Snapper: this},
                     infoCallback=function infoCallbackCB);
    }

Since it is usually understood as "Info" to the end-user, the common usage of such a callback function would be to inform the user of extra detail in a text box:

/**
 * Info Callback function.
 */
private void infoCallbackCB(Control c) {
    makeMessageBox(session.mainWindow, "infoCallback Dialog",
                   "*Insert more information of the invalidation here*");
}

Zoom Changed Callback

This callback is triggered when a Note, Warning, or an Invalid validation has an Info Callback, and using the Next and Previous buttons to switch between Snappers with the same validation.

This is usually used to bring up more information based on the specific selected Snapper(s) in the same validation. 

1. Select the Validation
   
   
   
2. Click on one of the navigation buttons.
   
   
   
3. The zoomChanged callback is triggered, referring to the current selection.
   
   
   
   
4. Clicking on the navigational buttons again will cycle through the Snappers that have that same validation, each time triggering the zoomChanged callback.
   

    /**
     * Append invalidation.
     */
    public void appendInvalidation(InvalidList list) {
        super(..);
        list.putNote("zoomChangedExample", "Zoom Changed Example", {Snapper: this},
                     infoCallback=function infoCallbackCB,
                     zoomChangedCallback=function zoomChangedCB);
    }

/**
 * Zoom changed callback function.
 */
private void zoomChangedCB(Control c) {
    if (c as ScrollableGridWindow) {
        InvalidListDialog d = invalidListDialog();
        if (d.list and InvalidItem item = d.list.getFromIndex(c.currentR).InvalidItem) {
            str snapIds;
            for (snap in d.zoomObjs[d.lastZoom]) snapIds #= snap.id.toS # "\n";
            makeMessageBox(session.mainWindow, "zoomChanged Dialog", "Snapper ids = " # snapIds);
        }
    }
}