dialog.js

javascript 很酷的类库

}

//>	@classMethod	isc.warn()
// Show a modal dialog with a message, icon, and "OK" button.
// <P>
// The callback will receive boolean true for an OK button click, or null if the Dialog is
// dismissed via the close button.
//
//	@param	message			(string)	message to display
//  @param  [callback]      (Callback)  Optional Callback to fire when the user 
//                                      dismisses the dialog. This has the single parameter
//                                      'value', indicating the value returned by the Warn
//                                      dialog from 'okClick()' etc.
//	@param	[properties]	(object)	additional properties for the Dialog.
//                                      To set +link{Dialog.toolbarButtons,custom buttons} for
//                                      the Dialog, set properties.buttons to an array of buttons
//										eg:	{ buttons : [Dialog.OK, Dialog.CANCEL] }
// @group Prompting
// @visibility external
// @see classAttr:Dialog.Warn
// @see classMethod:isc.say()
// @see classMethod:isc.ask()
// @see method:Dialog.okClick()
// @see classAttr:Dialog.WARN_TITLE
//<
isc.addGlobal("warn", function (message, callback, properties) {
    isc.showMessage(message, "warn", callback, properties);
});

//>	@classMethod	isc.say()
// Show a modal dialog with a message, icon, and "OK" button.  Intended for notifications which
// are not really warnings (default icon is less severe).
// <P>
// The callback will receive boolean true for an OK button click, or null if the Dialog is
// dismissed via the close button.
//
//	@param	message			(string)	message to display
//  @param  [callback]      (Callback)  Optional Callback to fire when the user 
//                                      dismisses the dialog. This has the single parameter
//                                      'value', indicating the value returned by the Warn
//                                      dialog from 'okClick()' etc.
//	@param	[properties]	(object)	additional properties for the Dialog.
//                                      To set +link{Dialog.toolbarButtons,custom buttons} for
//                                      the Dialog, set properties.buttons to an array of buttons
//										eg:	{ buttons : [Dialog.OK, Dialog.CANCEL] }
// @group Prompting
// @visibility external
// @see classAttr:Dialog.Warn
// @see classMethod:isc.warn()
// @see classMethod:isc.ask()
// @see method:Dialog.okClick()
// @see classAttr:Dialog.SAY_TITLE
//<
isc.addGlobal("say", function (message, callback, properties) {
    isc.showMessage(message, "say", callback, properties);
});


//>	@classMethod	isc.ask()
// Show a modal dialog with a message, icon, and "Yes" and "No" buttons.
// <P>
// The callback will receive boolean true for an OK button click, boolean false for a No button
// click, or null if the Dialog is dismissed via the close button.
//
//	@param	message			(string)	message to display
//  @param  [callback]      (Callback)  Callback to fire when the 
//                                      user clicks a button to dismiss the dialog.
//                                      This has the single parameter 'value', indicating the 
//                                      value returned by the Warn dialog from 'okClick()' etc.
//	@param	[properties]	(object)	additional properties for the Dialog.
//                                      To set +link{Dialog.toolbarButtons,custom buttons} for
//                                      the Dialog, set properties.buttons to an array of buttons
//										eg:	{ buttons : [Dialog.OK, Dialog.CANCEL] }
//
// @group Prompting
// @visibility external
// @see Dialog.Warn
// @see classMethod:isc.warn()
// @see method:Dialog.yesClick()
// @see method:Dialog.noClick()
// @see classAttr:Dialog.ASK_TITLE
// @example dialogs
//<
isc.addGlobal("ask", function (message, callback, properties) {
    isc.showMessage(message, "ask", callback, properties);
});

//>	@classMethod	isc.confirm()
// Show a modal dialog with a message, icon, and "OK" and "Cancel" buttons.
// <P>
// The callback will receive boolean true for an OK button click, or null for a Cancel click or
// if the Dialog is dismissed via the close button.
// <P>
// Note: this does not override the native window.confirm() method.
//
//	@param	message			(string)	message to display
//  @param  [callback]      (Callback)  Callback to fire when the 
//                                      user clicks a button to dismiss the dialog.
//                                      This has the single parameter 'value', indicating the 
//                                      value returned by the Warn dialog from 'okClick()' etc.
//	@param	[properties]	(object)	additional properties for the Dialog.
//                                      To set +link{Dialog.toolbarButtons,custom buttons} for
//                                      the Dialog, set properties.buttons to an array of buttons
//										eg:	{ buttons : [Dialog.OK, Dialog.CANCEL] }
//
// @group Prompting
// @visibility external
// @see Dialog.Warn
// @see classMethod:isc.warn()
// @see method:Dialog.okClick()
// @see method:Dialog.cancelClick()
// @see classAttr:Dialog.CONFIRM_TITLE
// @example dialogs
//<
isc.confirm = function (message, callback, properties) {
    isc.showMessage(message, "confirm", callback, properties);
}

//> @classMethod isc.askForValue()
// Show a modal dialog with a text entry box, asking the user to enter a value.
// <P>
// As with other convenience methods that show Dialogs, such as +link{classMethod:isc.warn()},
// the dialog is shown and the function immediately returns.  When the user responds, the
// provided callback is called.
// <P>
// If the user clicks OK, the value typed in is passed to the callback (including the empty
// string ("") if nothing was entered.  If the user clicks cancel, the value passed to the
// callback is null.
// <P>
// A default value for the text field can be passed via <code>properties.defaultValue</code>.
// <P>
// Keyboard focus is automatically placed in the text entry field, and hitting the enter key is
// the equivalent of pressing OK.
//
//	@param	message			(string)	message to display
//  @param  [callback]      (Callback)  Callback to fire when the 
//                                      user clicks a button to dismiss the dialog.
//                                      This has the single parameter 'value', indicating the 
//                                      user entry, or null if cancel was pressed or the window
//                                      closed
//	@param	[properties]	(object)	additional properties for the Dialog.
//                                      To set +link{Dialog.toolbarButtons,custom buttons} for
//                                      the Dialog, set properties.buttons to an array of buttons
//										eg:	{ buttons : [Dialog.OK, Dialog.CANCEL] }
//
// @see method:Dialog.okClick()
// @see method:Dialog.cancelClick()
// @see classAttr:Dialog.ASK_FOR_VALUE_TITLE
// @group Prompting
// @visibility external
//<
isc.askForValue = function (message, callback, properties) {
    properties = properties || isc.emptyObject;

    var askDialog = isc.Dialog.Ask
    if (!askDialog) {
        var askForm = isc.DynamicForm.create({
            numCols:1, 
            padding:3,
            items: [
                { name:"message", type:"blurb" },
                { name:"value", showTitle:false, width:"*" }
            ],  
            // fire okClick on enter
            saveOnEnter:true,
            submit : function () { this.askDialog.okClick(); }
        });
        askDialog = isc.Dialog.Ask = isc.Dialog.create({
            items : [ askForm ],
            askForm: askForm,
            autoCenter:false,
            canDragReposition:true,
            isModal:true,
            // accomplishes vertical autoSizing
            bodyProperties : {overflow:"visible"},
            overflow:"visible"
        });
        askForm.askDialog = askDialog;

        // return the form value to the callback on okClick
        askDialog._okClickFunction = function () {
            this.clear();
            this.returnValue(this.askForm.getValue("value"));
        }
    }

    // copy properties and install defaults
    properties = isc.addProperties({
        callback: callback,
        title: properties.title || isc.Dialog.ASK_FOR_VALUE_TITLE,
        left: properties.left || "10%", 
        top: properties.top || "20%", 
        width: properties.width || "80%", 
        height: properties.height || 20,
        buttons: properties.buttons || [ isc.Dialog.OK, isc.Dialog.CANCEL ],
        okClick : properties.okClick || askDialog._okClickFunction
    }, properties);
    
    // have standard handlers added to properties
    isc._applyDialogHandlers(properties);

    askDialog.setProperties(properties);

    askDialog.askForm.setValues({ 
        message : message || "Please enter a value:", 
        value : properties.defaultValue || "" 
    });
    askDialog.show();
    askDialog.askForm.focusInItem("value");
}

//> @classMethod isc.showLoginDialog()
// Handle a complete login interaction with a typical login dialog asking for username and
// password credentials.
// <P>
// As with other convenience methods that show Dialogs, such as +link{classMethod:isc.warn()},
// the dialog is shown and the function immediately returns.  When the user responds, the
// provided callback function is called.
// <P>
// If the user clicks the "Log in" button, the credentials entered by the user are passed to
// the provided "loginFunc" as an Object with properties "username" and "password" (NOTE: both
// property names are all lowercase), as the variable "credentials".  For example:
// <pre>{ username: "barney", password: "rUbbL3" }</pre>
// <P>
// The "loginFunc" should then attempt to log in by whatever means is necessary.  The second
// parameter to the loginFunc, "dialogCallback", is a function, which must be called <i>whether
// login succeeds or fails</i> with a true/false value indicating whether login succeeded.
// <P>
// If the login dialog is dismissable (settable as properties.dismissable, default false) and
// the user dismisses it, the loginFunc will be fired with null for the credentials.
// <P>
// The following code shows typical usage.  This code assumes you have created a global
// function sendCredentials() that send credentials to some authentication system and fires a
// callback function with the result:
// <pre>
// isc.showLoginDialog(function (credentials, dialogCallback) {
//     if (credentials == null) return; // dismissed
//
//     // send credentials    
//     sendCredentials(credentials, function (loginSucceeded) {
//         // report success or failure
//         dialogCallback(loginSucceeded);
//     })
// })
// </pre>
// The login dialog has several built-in behaviors:
// <ul>
// <li> keyboard focus is automatically placed in the username field
// <li> hitting enter in the username field proceeds to the password field
// <li> hitting enter in the password field submits (fires the provided callback)
// </ul>
// In addition to normal properties supported by Dialog/Window, the following special
// properties can be passed:
// <ul>
// <li><code>username</code>: initial value for the username field
// <li><code>password</code>: initial value for the password field
// <li><code>usernameTitle</code>: title for the username field
// <li><code>passwordTitle</code>: title for the password field
// <li><code>errorMessage</code>: default error message on login failure
// <li><code>loginButtonTitle</code>: title for the login button
// <li><code>dismissable</code>: whether the dialog can be dismissed, default false
// <li><code>errorStyle</code>: CSS style for the error message, if shown
// </ul>
// See below for links to the default values for these properties.
//
//  @param  loginFunc       (Callback)  Function to call to attempt login.  Recieves parameters
//                                      "credentials" and "dialogCallback", described above
//	@param	[properties]	(Dialog properties)	additional properties for the Dialog
//
// @see classAttr:Dialog.LOGIN_TITLE
// @see classAttr:Dialog.USERNAME_TITLE
// @see classAttr:Dialog.PASSWORD_TITLE
// @see classAttr:Dialog.LOGIN_BUTTON_TITLE
// @see classAttr:Dialog.LOGIN_ERROR_MESSAGE
// @group Prompting
// @visibility external
//<
isc.showLoginDialog = function (loginFunc, properties) {
    properties = properties || isc.emptyObject;

    var loginDialog = isc.Dialog.Login;
    if (!loginDialog) {
        var loginForm = isc.DynamicForm.create({
            numCols: 2,
            padding: 4,
            autoDraw: false,
            fields : [
                { name:"loginFailure", type:"blurb", colSpan: 2, visible:false },
                { name:"username", 
                  keyPress : function (item, form, keyName) {
                    if (keyName == "Enter") {
                        form.focusInItem("password");
                        return false;
                    }
                }},
                { name:"password", type:"password" },
                { type:"button", name:"loginButton", type:"submit" }
            ],
            saveOnEnter:true,
            submit : function () {
                var loginForm = this,
                    params = [{
                        username : this.getValue("username"), 
                        password : this.getValue("password")
                    }];

                params[1] = function (success) {
                    if (success) {
                        loginForm.complete(); // report success
                    } else {
                        // failed login attempt - indicate failure, remain visible
                        loginForm.showItem("loginFailure");
                        loginForm.focusInItem("password");
                    }
                };
            
                this.fireCallback(this.loginFunc, "credentials,dialogCallback", params);
            },
            complete : function (dismissed) {
                this.loginDialog.hide();
                // reset for next time
                this.setValue("username", "");
                this.setValue("password", "");    
                this.hideItem("loginFailure");
                
                // if this was a dismissal, tell the loginFunc
                if (dismissed) {
                    this.fireCallback(this.loginFunc, "credentials,dialogCallback");
                }
            }
        });
        isc.Dialog.Login = loginDialog = isc.Window.create({
            autoDraw:false,
            autoCenter: true,
            autoSize: true,
            isModal: true,
            loginForm : loginForm,
            showMinimizeButton:false,
            items: [ loginForm ],
            cancelClick : function () { this.loginForm.complete(true) }
        });
        loginForm.loginDialog = loginDialog;
    }

    var loginForm = loginDialog.loginForm;

    // handle general dialog-level properties and defaults
    properties = isc.addProperties({
        title : properties.title || isc.Dialog.LOGIN_TITLE
    }, properties);
    // have standard handlers added to properties
    isc._applyDialogHandlers(properties);
    loginDialog.setProperties(properties);


    // handle dismissability
    var dismissable = properties.dismissable != null ? properties.dismissable : false;
    loginDialog.dismissOnEscape = dismissable;
    loginDialog.setShowCloseButton(dismissable);


    // handle initial value
    loginForm.setValue("username", properties.username || "");
    loginForm.setValue("password", properties.password || "");    


    // allow field retitling
    loginForm.getItem("loginFailure").cellStyle = 
            properties.errorStyle || "formCellError";
    loginForm.getItem("username").title = 
            properties.usernameTitle || isc.Dialog.USERNAME_TITLE;
    loginForm.getItem("password").title = 
            properties.passwordTitle || isc.Dialog.PASSWORD_TITLE;
    loginForm.getItem("loginButton").setTitle(
            properties.loginButtonTitle || isc.Dialog.LOGIN_BUTTON_TITLE);
    loginForm.markForRedraw();

    // set up to try login until success or dismissal
    loginForm.loginFunc = loginFunc;
    loginForm.setValue("loginFailure", properties.errorMessage || isc.Dialog.LOGIN_ERROR_MESSAGE);

    // show the dialog with initial focus in username field
    loginDialog.show(); 
    loginForm.focusInItem("username");
}


// NOTE: unfinished dialog to confirm save when closing / exiting an application, or otherwise
// dropping edits.
// Typical Windows buttons: [*Yes*, No, Cancel]
// Typical Mac buttons: [Don't Save, separator, Cancel, *Save*]
/*
isc.confirmSave = function (message, callback, properties) {
    isc.confirm(message || isc.Dialog.saveChangesMessage, {
                    buttons:[isc.Dialog.OK,
                             {title:"Save", width:75,
                              click:"this.hide();this.topElement.returnValue('save');"},
                             isc.Dialog.CANCEL]
                }
                );
}
*/