Dojo-0.3.1debug版本部分翻譯

 

沒事的時候翻譯的，當閱讀做了。倒～！！

if(typeof dojo == "undefined"){

/**
* @文件 bootstrap1.js
*
* 摘要:  整套Dojo庫載入的第一個文件。
// ****************************************************************
// note:  必須運行於hostenv_*.js文件之前。 (說的是src目錄下的文件，它們從都是從此文檔的分割出去的)
// ****************************************************************
*
* @作者  Copyright 2004 Mark D. Anderson ([email protected])
* TODOC: 可以在Dojo基礎上做改動嗎?
* @許可協議 在Academic Free License 2.1 (http://www.opensource.org/licenses/afl-2.1.php)許可協議下。
*
* $Id: bootstrap1.js 4342 2006-06-11 23:03:30Z alex $
*/

// TODOC: HOW TO DOC THE BELOW?
// @全局: djConfig
// 摘要:  
//        載入庫時，應用程序代碼可以先設置全局變量"djConfig"來取消某個Dojo運作方式的全局設定。
// 說明:  可以設定如下全局變量:
//            - isDebug: false
//            - allowQueryConfig: false
//            - baseScriptUri: ""
//            - baseRelativePath: ""
//            - libraryScriptUri: ""
//            - iePreventClobber: false
//            - ieClobberMinimal: true
//            - preventBackButtonFix: true
//            - searchIds: []
//            - parseWidgets: true
// TODOC: HOW TO DOC THESE VARIABLES?
// TODOC: IS THIS A COMPLETE LIST?
// 注意:
//      在有"dojo.*"時，"djConfig"不存在。因此，在"dojo"變量存在前可以被設定。
// 注意:
//        在載入庫之後設定這些變量，都不起任何作用。
// TODOC: 現在仍然如此嗎?  版本0.3的發行說明指出載入後仍可設定。.
//



//TODOC:  HOW TO DOC THIS?
// @全局: dj_global
// 摘要: 
//        主環境的頂層全局對象的別名
//        (例如:瀏覽器的window對象)。
// 說明:  
//        使用"dj_global"而不是window對象，是爲了保證你的代碼在上下文中可以正確運行，而不是指哪些瀏覽器。(eg: Rhino on a server).
var dj_global = this;



function dj_undef(/*String*/ name, /*Object?*/ object){
    //摘要: 如果在"object"對象上定義了爲參數"name"的屬性，返回false (或者在全局範圍，"object"對象爲null)。
    //說明: 注意定義和存在是兩個不同的概念。
    if(object==null){ object = dj_global; }
    // 如果object不是一個對象時發生異常。
    return (typeof object[name] == "undefined");    // Boolean
}


// 確保定義了djConfig
if(dj_undef("djConfig")){ 
    var djConfig = {}; 
}


//TODOC:  HOW TO DOC THIS?
// dojo是我們使用庫中幾乎所有公共標誌的根變量 —— 確保定義
if(dj_undef("dojo")){ 
    var dojo = {}; 
}

//TODOC:  HOW TO DOC THIS?
dojo.version = {
    // 摘要: 當前dojo實例的版本號。
    major: 0, minor: 3, patch: 1, flag: "",
    revision: Number("$Rev: 4342 $".match(/[0-9]+/)[0]),    // 找到字符串中的數字匹配返回的字符串數組的第1個元素，並轉化成數值類型
    toString: function(){
        with(dojo.version){
            return major + "." + minor + "." + patch + flag + " (" + revision + ")";    // String
        }
    }
}

dojo.evalProp = function(/*String*/ name, /*Object*/ object, /*Boolean?*/ create){
    // 摘要: 返回"object[name]".  如果沒有定義並且"create"爲true, 會返回一個新對象。
    // 說明: 
    //        如果沒有定義"object[name]"並且"create"不爲true，返回null。
    //         注意: 定義和存在是兩個不同的概念。
    // 注意: 對象的屬性也是對象。
    return (object && !dj_undef(name, object) ? object[name] : (create ? (object[name]={}) : undefined));    // mixed
}


dojo.parseObjPath = function(/*String*/ path, /*Object?*/ context, /*Boolean?*/ create){
    // 摘要: 解析字符串path併成返回一個對象，它帶有對應的對象引用及屬性名稱。
    // 說明: 
    //      返回一個帶有"obj"和"prop"兩個屬性的對象。
    //      參照"path"指出"obj[prop]"。
    // path: 一個對象的Path是以"A.B.C"的形式。     
    // context: 作用類似根目錄的對象，默認是"dj_global"。
    // create: 如果爲true，就會沿"path"，爲那些沒有定義的點創建一些新對象。
    var object = (context != null ? context : dj_global);
    var names = path.split('.');
    var prop = names.pop();    // 彈出數組的最後一個元素並返回，並將數組長度減1。
    for (var i=0,l=names.length;i<l && object;i++){
        object = dojo.evalProp(names[i], object, create);
    }
    return {obj: object, prop: prop};    // Object: {obj: Object, prop: String}
}


dojo.evalObjPath = function(/*String*/ path, /*Boolean?*/ create){
    // 摘要: Return the value of object at 'path' in the global scope, without using 'eval()'.
    // 摘要: 返回全局範圍內在"path"上的對象的值，沒有使用"eval()"。
    // path: 一個對象的Path是以"A.B.C"的形式。
    // create: 如果爲true，就會沿"path"，爲那些沒有定義的點創建一些新對象。
    if(typeof path != "string"){ 
        return dj_global; 
    }
    // 沒有句點號的快速路徑
    if(path.indexOf('.') == -1){
        return dojo.evalProp(path, dj_global, create);        // mixed
    }

    //MOW: 過去的"with"句法有些混亂。並且，如果parseObjPath返回了null，還會拋出一個錯誤。
    var ref = dojo.parseObjPath(path, dj_global, create);
    if(ref){
        return dojo.evalProp(ref.prop, ref.obj, create);    // mixed
    }
    return null;
}

// ****************************************************************
// global public utils (全局公有調用)
// TODOC: DO WE WANT TO NOTE THAT THESE ARE GLOBAL PUBLIC UTILS?    (我們需要記住這些是公有調用嗎？) 
// ****************************************************************

dojo.errorToString = function(/*Error*/ exception){
    // 摘要: 返回異常的 'message', 'note' or text.
     // TODO: 如果沒有Error.prototype.toString將不能實現嗎？
     //         ... 因爲這是生來造成的錯誤，所以對象不就總是招來這些事嗎？
    if(!dj_undef("message", exception)){
        return exception.message;        // String
    }else if(!dj_undef("note", exception)){
        return exception.note;    // String
    }else{
        return exception;                // Error
    }
}


dojo.raise = function(/*String*/ message, /*Error?*/ exception){
    // 摘要: 拋出一個錯誤消息。如果被支持，還在文字的後面附加上"exception"的內容。
    // 注意: 還會使用"dojo.hostenv.println"向用戶打出消息的內容。
    if(exception){
        message = message + ": "+dojo.errorToString(exception);
    }

    // 如果使用"dojo.hostenv.println"，能向用戶打出消息。
    try {    dojo.hostenv.println("FATAL: "+message); } catch (e) {}

    throw Error(message);
}

//已經廢除的一些方法，所以不起作用了
//TODOC:  HOW TO DOC THESE?
dojo.debug = function(){}
dojo.debugShallow = function(obj){}
dojo.profile = { start: function(){}, end: function(){}, stop: function(){}, dump: function(){} };


function dj_eval(/*String*/ scriptFragment){ 
    // 摘要: 使用全局範圍內的評估方法。這沒有直接調用"eval()"。
    // 說明: 放在一個單獨的方法裏，減小評估上下文的大小。
    // 注意:
    //   - JSC eval() 給出了可選的第二個參數,可以取"unsafe"。
    //     - Mozilla/SpiderMonkey eval() 給出了一個可選的第二個參數，作爲新代碼符號所屬的特定範圍的對象。
    return dj_global.eval ? dj_global.eval(scriptFragment) : eval(scriptFragment);     // mixed
}



dojo.unimplemented = function(/*String*/ funcname, /*String?*/ extra){
    // 摘要: 拋出由於某個方法沒有實現而產生的異常
    // extra: 附加在異常消息message後的內容。
    var message = "'" + funcname + "' not implemented";
    if (extra != null) { message += " " + extra; }
    dojo.raise(message);
}


dojo.deprecated = function(/*String*/ behaviour, /*String?*/ extra, /*String?*/ removal){
    // 摘要: 記錄指出一個已經被反對的做法的調試信息。
    // extra: 附加在異常消息message後的內容。
    // removal: 指出會在將來什麼時候移除這個做法。
    var message = "DEPRECATED: " + behaviour;
    if(extra){ message += " " + extra; }
    if(removal){ message += " -- will be removed in version: " + removal; }
    dojo.debug(message);
}



dojo.inherits = function(/*Function*/ subclass, /*Function*/ superclass){
    // 摘要: 在兩個類間建立繼承。
    if(typeof superclass != 'function'){ 
        dojo.raise("dojo.inherits: superclass argument ["+superclass+"] must be a function (subclass: [" + subclass + "']");
    }
    subclass.prototype = new superclass();
    subclass.prototype.constructor = subclass;
    subclass.superclass = superclass.prototype;
    // 被反對的: super是一個保留字, 使用 'superclass'
    subclass['super'] = superclass.prototype;
}

dojo.render = (function(){
    //TODOC: HOW TO DOC THIS?
    // 摘要: 描述當前環境的支持、操作系統和瀏覽器的細節。
    // TODOC: 這是許多人要交互的一些東西嗎？ 如果是， 我們也許應該給出建有結構的文檔...
    function vscaffold(prefs, names){
        var tmp = {
            capable: false,
            support: {
                builtin: false,
                plugin: false
            },
            prefixes: prefs
        };
        for(var prop in names){
            tmp[prop] = false;
        }
        return tmp;
    }

    return {
        name: "",
        ver: dojo.version,
        os: { win: false, linux: false, osx: false },
        html: vscaffold(["html"], ["ie", "opera", "khtml", "safari", "moz"]),
        svg: vscaffold(["svg"], ["corel", "adobe", "batik"]),
        vml: vscaffold(["vml"], ["ie"]),
        swf: vscaffold(["Swf", "Flash", "Mm"], ["mm"]),
        swt: vscaffold(["Swt"], ["ibm"])
    };
})();

// ****************************************************************
// dojo.hostenv methods that must be defined in hostenv_*.js    (dojo.hostenv 的這些方法必須在hostenv_*.js被定義)
// ****************************************************************

/**
 * The interface definining the interaction with the EcmaScript host environment.
 * 定義ECMAScript主機環境的交互接口
*/

/*
 * 所有這些方法都不能被庫的用戶所直接調用。
 * 作爲替代，應該調用如"loadModule"這樣的公共方法。
 */
dojo.hostenv = (function(){
    // TODOC:  HOW TO DOC THIS?
    // 摘要: Provides encapsulation of behavior that changes across different 'host environments' 
    // 摘要: 提供在不同"主機環境"(如不同的瀏覽器，server via Rhino等)下,會有所變化的行爲的簡化信息。
    // 說明: 所有這寫方法都不能被庫的用戶所直接調用。
    //                調用如"loadModule"這樣的公共方法。
    
    // 默認的配置選項
    var config = {
        isDebug: false,
        allowQueryConfig: false,
        baseScriptUri: "",
        baseRelativePath: "",
        libraryScriptUri: "",
        iePreventClobber: false,
        ieClobberMinimal: true,
        preventBackButtonFix: true,
        searchIds: [],
        parseWidgets: true
    };

    if (typeof djConfig == "undefined") { djConfig = config; }
    else {
        for (var option in config) {
            if (typeof djConfig[option] == "undefined") {
                djConfig[option] = config[option];
            }
        }
    }

    return {
        name_: '(unset)',
        version_: '(unset)',


        getName: function(){ 
            // 摘要: 返回主機環境的名稱.
            return this.name_;     // String
        },


        getVersion: function(){ 
            // 摘要: 返回主機環境的版本.
            return this.version_; // String
        },

        getText: function(/*String*/ uri){
            // 摘要:    讀取指定的"uri"上的純文本內容。
            // 說明: 
            //            If 'getText()' is not implemented, then it is necessary to override 
            //            'loadUri()' with an implementation that doesn't rely on it.
            //            如果"getText()"沒有被實現，那就需要去除不需依賴"loadUri()"的實現。

            dojo.unimplemented('getText', "uri=" + uri);
        }
    };
})();


dojo.hostenv.getBaseScriptUri = function(){
    // 摘要: 返回與找到其他腳本文件相聯繫的基本腳本文件的URI。
    // TODOC: 啊?  我不明白這個註釋。  什麼其他的腳本? 這個文件是其他Dojo庫文件的路徑?
    //        MAYBE:  返回Dojo庫的腳本文件的基本URI     ???
    // 返回: 空字符串或者以"/"結尾的路徑。
    if(djConfig.baseScriptUri.length){ 
        return djConfig.baseScriptUri;
    }

    // MOW: 爲什麼不這樣:
    //            uri = djConfig.libraryScriptUri || djConfig.baseRelativePath
    //        ??? 而是 new String(...)'
    var uri = new String(djConfig.libraryScriptUri||djConfig.baseRelativePath);
    if (!uri) { dojo.raise("Nothing returned by getLibraryScriptUri(): " + uri); }

    // MOW: URI好像沒有被真的使用。是不是作了djConfig.baseRelativePath的硬性編碼(hard-coding )... ???
    var lastslash = uri.lastIndexOf('/');        // MOW ???
    djConfig.baseScriptUri = djConfig.baseRelativePath;
    return djConfig.baseScriptUri;    // String
}

 

以後再補上。呵呵