Changeset 12918

Timestamp:

03/05/08 19:01:39 (10 months ago)

Author:

peller

Message:

Add docs. Refs #5962 !strict

Location:

dijit/trunk/form

Files:

• DateTextBox.js (modified) (1 diff)
• TextBox.js (modified) (2 diffs)
• TimeTextBox.js (modified) (1 diff)
• ValidationTextBox.js (modified) (12 diffs)
• _DateTimeTextBox.js (modified) (4 diffs)

dijit/trunk/form/DateTextBox.js

@@ -9 +9 @@
         {
                 // summary:
-                //              A validating, serializable, range-bound date text box.
+                //              A validating, serializable, range-bound date text box with a popup calendar
 
                 popupClass: "dijit._Calendar",

dijit/trunk/form/TextBox.js

@@ -38 +38 @@
 
                 getDisplayedValue: function(){
+                        //      summary:
+                        //              returns the formatted value that the user sees in the textbox, which may be different
+                        //              from the serialized value that's actually sent to the server (see dijit.form.ValidationTextBox.serialize)
                         return this.filter(this.textbox.value);
                 },
@@ -85 +88 @@
 
                 filter: function(val){
-                        // summary: Apply various filters to textbox value
+                        // summary: Apply specified filters to textbox value
                         if(val === null || val === undefined){ return ""; }
                         else if(typeof val != "string"){ return val; }

dijit/trunk/form/TimeTextBox.js

@@ -9 +9 @@
         {
                 // summary:
-                //              A validating, serializable, range-bound time text box.
+                //              A validating, serializable, range-bound time text box with a popup time picker
 
                 popupClass: "dijit._TimePicker",

dijit/trunk/form/ValidationTextBox.js

@@ -7 +7 @@
 
 dojo.requireLocalization("dijit.form", "validate");
+
+/*=====
+        dijit.form.ValidationTextBox.__Constraints = function(){
+                // locale: String
+                //              locale used for validation, picks up value from this widget's lang attribute
+                // _flags_: anything
+                //              various flags passed to regExpGen function
+                this.locale = "";
+                this._flags_ = "";
+        }
+=====*/
 
 dojo.declare(
@@ -32 +43 @@
                 invalidMessage: "$_unset_$", // read from the message file if not overridden
 
-                // constraints: Object
+                // constraints: dijit.form.ValidationTextBox.__Constraints
                 //              user-defined object needed to pass parameters to the validator functions
                 constraints: {},
@@ -44 +55 @@
                 //              user replaceable function used to generate regExp when dependent on constraints
                 //              Do not specify both regExp and regExpGen
-                regExpGen: function(constraints){ return this.regExp; },
+                regExpGen: function(/*dijit.form.ValidationTextBox.__Constraints*/constraints){ return this.regExp; },
 
                 // state: String
@@ -59 +70 @@
                 },
 
-                validator: function(value,constraints){
+                validator: function(/*anything*/value, /*dijit.form.ValidationTextBox.__Constraints*/constraints){
                         // summary: user replaceable function used to validate the text input against the regular expression.
                         return (new RegExp("^(" + this.regExpGen(constraints) + ")"+(this.required?"":"?")+"$")).test(value) &&
@@ -66 +77 @@
                 },
 
-                isValid: function(/* Boolean*/ isFocused){
+                isValid: function(/*Boolean*/ isFocused){
                         // summary: Need to over-ride with your own validation code in subclasses
                         return this.validator(this.textbox.value, this.constraints);
@@ -76 +87 @@
                 },
 
-                getErrorMessage: function(/* Boolean*/ isFocused){
+                getErrorMessage: function(/*Boolean*/ isFocused){
                         // summary: return an error message to show if appropriate
                         return this.invalidMessage;
                 },
 
-                getPromptMessage: function(/* Boolean*/ isFocused){
+                getPromptMessage: function(/*Boolean*/ isFocused){
                         // summary: return a hint to show if appropriate
                         return this.promptMessage;
                 },
 
-                validate: function(/* Boolean*/ isFocused){
+                validate: function(/*Boolean*/ isFocused){
                         // summary:
                         //              Called by oninit, onblur, and onkeypress.
@@ -158 +169 @@
                 //              Provides a hidden input field and a serialize method to override
 
-                serialize: function(val, /*Object?*/options){
+                serialize: function(/*anything*/val, /*Object?*/options){
                         // summary: user replaceable function used to convert the getValue() result to a String
-                        return val.toString ? val.toString() : "";
+                        return val.toString ? val.toString() : ""; // String
                 },
 
@@ -166 +177 @@
                         // summary: display the widget as a printable string using the widget's value
                         var val = this.filter(this.getValue());
-                        return val != null ? (typeof val == "string" ? val : this.serialize(val, this.constraints)) : "";
+                        return val != null ? (typeof val == "string" ? val : this.serialize(val, this.constraints)) : ""; // String
                 },
 
@@ -201 +212 @@
 );
 
+/*=====
+        dijit.form.RangeBoundTextBox.__Constraints = function(){
+                // min: Number
+                //              Minimum signed value.  Default is -Infinity
+                // max: Number
+                //              Maximum signed value.  Default is +Infinity
+                this.min = min;
+                this.max = max;
+        }
+=====*/
+
 dojo.declare(
         "dijit.form.RangeBoundTextBox",
@@ -208 +230 @@
                 //              A subclass of MappedTextBox.
                 //              Tests for a value out-of-range
-                /*===== contraints object:
-                // min: Number
-                //              Minimum signed value.  Default is -Infinity
-                min: undefined,
-                // max: Number
-                //              Maximum signed value.  Default is +Infinity
-                max: undefined,
-                =====*/
-
+                //
+                // constraints: dijit.form.RangeBoundTextBox.__Constraints
+                //
                 // rangeMessage: String
                 //              The message to display if value is out-of-range
                 rangeMessage: "",
 
-                compare: function(val1, val2){
+                compare: function(/*anything*/val1, /*anything*/val2){
                         // summary: compare 2 values
                         return val1 - val2;
                 },
 
-                rangeCheck: function(/* Number */ primitive, /* Object */ constraints){
+                rangeCheck: function(/*Number*/ primitive, /*dijit.form.RangeBoundTextBox.__Constraints*/ constraints){
                         // summary: user replaceable function used to validate the range of the numeric input value
                         var isMin = (constraints.min !== undefined);
@@ -234 +250 @@
                                         (!isMax || this.compare(primitive,constraints.max) <= 0);
                         }
-                        return true;
-                },
-
-                isInRange: function(/* Boolean*/ isFocused){
+                        return true; // Boolean
+                },
+
+                isInRange: function(/*Boolean*/ isFocused){
                         // summary: Need to over-ride with your own validation code in subclasses
                         return this.rangeCheck(this.getValue(), this.constraints);
                 },
 
-                isValid: function(/* Boolean*/ isFocused){
+                isValid: function(/*Boolean*/ isFocused){
                         return this.inherited(arguments) &&
-                                ((this._isEmpty(this.textbox.value) && !this.required) || this.isInRange(isFocused));
-                },
-
-                getErrorMessage: function(/* Boolean*/ isFocused){
-                        if(dijit.form.RangeBoundTextBox.superclass.isValid.call(this, false) && !this.isInRange(isFocused)){ return this.rangeMessage; }
+                                ((this._isEmpty(this.textbox.value) && !this.required) || this.isInRange(isFocused)); // Boolean
+                },
+
+                getErrorMessage: function(/*Boolean*/ isFocused){
+                        if(dijit.form.RangeBoundTextBox.superclass.isValid.call(this, false) && !this.isInRange(isFocused)){ return this.rangeMessage; } // String
                         return this.inherited(arguments);
                 },
@@ -270 +286 @@
                 },
                 
-                setValue: function(/*Number*/ value, /*Boolean, optional*/ priorityChange){
+                setValue: function(/*Number*/ value, /*Boolean?*/ priorityChange){
                         dijit.setWaiState(this.focusNode, "valuenow", value);
                         this.inherited('setValue', arguments);

dijit/trunk/form/_DateTimeTextBox.js

@@ -6 +6 @@
 dojo.require("dijit.form.ValidationTextBox");
 
+/*=====
+dojo.declare(
+        "dijit.form._DateTimeTextBox.__Constraints",
+        [dijit.form.RangeBoundTextBox.__Constraints, dojo.date.locale.__FormatOptions],
+        {}
+);
+=====*/
+
 dojo.declare(
         "dijit.form._DateTimeTextBox",
@@ -12 +20 @@
                 // summary:
                 //              A validating, serializable, range-bound date or time text box.
+                //
+                // constraints: dijit.form._DateTimeTextBox.__Constraints 
 
-                // constraints object: min, max
                 regExpGen: dojo.date.locale.regexp,
                 compare: dojo.date.compare,
-                format: function(/*Date*/ value, /*Object*/ constraints){
+                format: function(/*Date*/ value, /*dijit.form._DateTimeTextBox.__Constraints*/ constraints){
                         if(!value){ return ''; }
                         return dojo.date.locale.format(value, constraints);
                 },
-                parse: function(/*String*/ value, /*Object*/ constraints){
+                parse: function(/*String*/ value, /*dijit.form._DateTimeTextBox.__Constraints*/ constraints){
                         return dojo.date.locale.parse(value, constraints) || undefined; /* can't return null to getValue since that's special */
                 },
@@ -72 +81 @@
 
                         if(!this._picker){
-                                var popupProto=dojo.getObject(this.popupClass, false);
-                                this._picker = new popupProto({
+                                var PopupProto=dojo.getObject(this.popupClass, false);
+                                this._picker = new PopupProto({
                                         onValueSelected: function(value){
 
@@ -144 +153 @@
                 },
 
-                _onKeyPress: function(e){
+                _onKeyPress: function(/*Event*/e){
                         if(dijit.form._DateTimeTextBox.superclass._onKeyPress.apply(this, arguments)){
                                 if(this._opened && e.keyCode == dojo.keys.ESCAPE && !e.shiftKey && !e.ctrlKey && !e.altKey){