com.sssw.shr.page
Class AgpTextField

java.lang.Object
 |
 +--com.sssw.shr.page.AgpTag
       |
       +--com.sssw.shr.page.AgpControlBase
             |
             +--com.sssw.shr.page.AgpTextField

All Implemented Interfaces:

AgiJavaScriptEnhanced, AgiPageControl, Cloneable, Externalizable, Serializable

public class AgpTextField

extends AgpControlBase

Single-line Text Field HTML form control. This control lets the user enter a single line of text.

Properties:

Data Column, Data Type, Display Format, Enable HTML Generation, Max Length, Name, Size, Submit On Change, Type, Validation Rules, Value

Events:

validationFailed, validationTest, valueChanged

See Also:

Serialized Form

Fields inherited from class com.sssw.shr.page.AgpTag

UNIT_PERCENT, UNIT_PIXEL

Constructor Summary

AgpTextField()

Method Summary

String	format(Object ob, String pattern, int style1, int style2) Callback to format the object according to the specified pattern or style.
BigDecimal	getBigDecimalValue() Get the field value.
char	getDatatype() Gets the data type for a text field.
Date	getDateValue() Get the field value.
String	getDisplayPattern() Returns a String that identifies the pattern that the control uses to display the data.
int	getDisplayStyle() Obtains the control's display style.
Double	getDoubleValue() Get the field value.
boolean	getEmptyStringIsNull() Returns whether the value of an empty text control is null.
Integer	getIntegerValue() Get the field value.
int	getMaxLength() Returns the maximum number of characters that a user can enter in this field, as determined by its "Max Length" property.
Object	getObjectValue() Get the field value as an Object.
int	getSize() Returns the width of the control as a number of characters.
boolean	getSubmitOnChange() Returns the "Submit On Change" property of this control.
String	getText() Returns the text of the control.
Timestamp	getTimestampValue() Get the field value.
Time	getTimeValue() Get the field value.
String	getType() Returns a string indicating the Type property of this control.
String	getValue() Deprecated. to getText(). Use getObjectValue() to get the parsed value (e.g. a Double object if the field's datatype is TYPE_DOUBLE).
Object	parse(int datatype, String parseStr, String pattern, int style1, int style2) Callback to parse the string according to the specified pattern or style.
void	setBigDecimalValue(BigDecimal value) Set the field value.
void	setDatatype(char datatype) Sets the data type for a text field.
void	setDateValue(Date value) Set the field value.
void	setDisplayPattern(String pattern) Assigns the control's display format.
void	setDisplayStyle(int style) Assigns the control's display style.
void	setDoubleValue(Double value) Set the field value.
void	setEmptyStringIsNull(boolean b) Specifies whether the value of an empty text control is null.
void	setIntegerValue(Integer value) Set the field value.
void	setMaxLength(int maxlength) Sets the Max Length property of the control.
void	setObjectValue(Object value) Set the field value as an Object.
void	setSize(int size) Sets the Size property of the control.
void	setSubmitOnChange(boolean submit_on_change) Sets the Submit On Change property of this control.
void	setText(String text) Sets the text of the control.
void	setTimestampValue(Timestamp value) Set the field value.
void	setTimeValue(Time value) Set the field value.
void	setType(String type) Sets the Type property of the control.
void	setValue(String value) Deprecated. to setText(). Use setObjectValue() to set the parsed value (e.g. a Double object if the field's datatype is TYPE_DOUBLE).

Methods inherited from class com.sssw.shr.page.AgpControlBase

getName

Methods inherited from class com.sssw.shr.page.AgpTag

getBoolProperty, getEnableHTMLGeneration, getIntArrayProperty, getIntProperty, getIntPropertyUnit, getProperty, getStringArrayProperty, invalidateHTML, removeProperty, setEnableHTMLGeneration, setIntProperty, setProperty

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods implemented from interface com.sssw.shr.page.AgiJavaScriptEnhanced

generateFunction, generateRepaintScript, generateScriptInitializers, getFunctionNameForMethod, getFunctionNames, getMethodNames, getScriptObjectName, isHTMLRepaintPending, isJavaScriptRepaintPending

Methods implemented from interface com.sssw.shr.page.AgiPageControl

generateHTML, getPrefix, notifyPageLoaded, notifyPageRequestBegin, notifyPageRequestEnd, notifyPostValue, notifyPostValues

Methods implemented from interface java.io.Externalizable

readExternal, writeExternal

Constructor Detail

AgpTextField

public AgpTextField()

Method Detail

getMaxLength

public int getMaxLength()

Returns the maximum number of characters that a user can enter in this field, as determined by its "Max Length" property. If no limit has been set, getMaxLength() returns 0.

Example:

 	int maxlen = Field1.getMaxLength();
 

See Also:

Max Length property, AgpTextField.setMaxLength(int maxlength)

setMaxLength

public void setMaxLength(int maxlength)

Sets the Max Length property of the control. It is the maximum number of characters the user is allowed to enter.

Parameters:

maxlength - the maximum number of characters allowed for user entry.

Example:

See Also:

Max Length property, AgpTextField.getMaxLength()

getSize

public int getSize()

Returns the width of the control as a number of characters. This width can be set at design time using the Size field of the Property Inspector or at run time with the setSize() method.

Usage:

The width of the control shown in the Page Designer is an approximation. The control as displayed to the user in the browser may vary slightly from its design-time appearance.

Example:

 		// if there isn't enough room for a particular string
 		// try to make this text field bigger
 		int len = myString.length();
 		if (Field1.getSize() < len)
 		{
 			Field1.setSize(len);
 		}
 

See Also:

Size property, AgpTextField.setSize(int size)

setSize

public void setSize(int size)

Sets the Size property of the control. It is expressed as a number of characters.

Parameters:

size - the number of characters in the control's width.

Usage:

The width of the control shown in the Page Designer is an approximation. The control as displayed to the user in the browser may vary slightly from its design-time appearance.

Example:

 		// if there isn't enough room for a particular string
 		// try to make this text field bigger
 		int len = myString.length();
 		if (Field1.getSize() < len)
 		{
 			Field1.setSize(len);
 		}
 

See Also:

Size property, AgpTextField.getSize()

getType

public String getType()

Returns a string indicating the Type property of this control. The string may be "TEXT", "PASSWORD", or "HIDDEN". A "Text" field is the standard text input field. A "Password" field accepts user input, but displays it as asterisks. A "Hidden" field does not appear to the user; it can be useful for maintaining application-internal information on the page.

This property can be set at design time using the Type field of the Property Inspector, or at run time using the setType method.

Example:

 		String fieldType = Field1.getType();
 

See Also:

Type property, AgpTextField.setType(String type)

setType

public void setType(String type)

Sets the Type property of the control. The three types of Text Fields are Text, Password and Hidden. The default value of the Type property is "Text". A "Text" field is the standard text input field. A "Password" field accepts user input, but displays it as asterisks. A "Hidden" field does not appear to the user; it can be useful for maintaining application-internal information on the page.

This property can be set at design time using the Type field of the Property Inspector, or at run time using the setType method.

Parameters:

type - One of three strings: "TEXT", "PASSWORD", or "HIDDEN"

Example:

 		if (cloakMe)
 			Field1.setType("PASSWORD");
 		else
 			Field1.setType("TEXT");
 
 

See Also:

Type property, AgpTextField.getType()

getText

public String getText()

Returns the text of the control. This method never returns null. If the control's value is null, getText() returns the empty string.

Specified by:

getText in interface com.sssw.rt.util.AgiValueHelperCallback

Example:

 		// Insert the string "NEW: " at the beginning of the field.
 		String fieldText = Field1.getText();
 		Field1.setText("NEW: "+fieldText);
 

See Also:

AgpTextField.setEmptyStringIsNull(boolean b), AgpTextField.setText(String text)

setText

public void setText(String text)

Sets the text of the control.

Parameters:

text - the new text string.

Example:

 		// Insert the string "NEW: " at the beginning of the field.
 		String fieldText = Field1.getText();
 		Field1.setText("NEW: "+fieldText);
 

See Also:

AgpTextField.getEmptyStringIsNull(), AgpTextField.getText(), AgpTextField.setEmptyStringIsNull(boolean b)

getValue

public String getValue()

Deprecated. to getText(). Use getObjectValue() to get the parsed value (e.g. a Double object if the field's datatype is TYPE_DOUBLE).

Returns the value of the control, as a string. The value may be null. If the control is bound to a database field, this is the value that will be stored.

Example:

 		// if this field has a null value, display a warning label
 		if (Field1.getValue() == null)
 		{
 			lblWarning.setText("The first field must be filled in: ");
 			lblWarning.setEnableHTMLGeneration(true);
 		}
 		else
 		{
 			// hide the label
 			lblWarning.setEnableHTMLGeneration(false);
 		}
 
 

See Also:

AgpTextField.getEmptyStringIsNull(), AgpTextField.setEmptyStringIsNull(boolean b), AgpTextField.setValue(String value)

setValue

public void setValue(String value)

Deprecated. to setText(). Use setObjectValue() to set the parsed value (e.g. a Double object if the field's datatype is TYPE_DOUBLE).

Sets the value of the control. If the control is bound to a database field, this is the value that will be stored.

Parameters:

value - a string that should appear in the text field, or null.

Usage:

Example:

 		// Clear out the first text field, and initialize the second one
 		Field1.setValue(null);
 		Field2.setValue("Untitled");
 
 

See Also:

AgpTextField.getValue()

getSubmitOnChange

public boolean getSubmitOnChange()

Returns the "Submit On Change" property of this control. This property can be set at design time using the "Submit on Change" field of the Property Inspector, or at run time using the setSubmitOnChange method. If this property is true, then the control will send a Submit request to the server when the end user has entered text.

Example:

 		// Display or hide a "Submit" button on the page, depending on whether the control
 		// named Field1 is going to handle its own submits
 		if (Field1.getSubmitOnChange())
 		{
 			// Field1 will submit, don't show the button
 			btnSubmit.setEnableHTMLGeneration(false);
 		}
 		else
 		{
 			// Field1 will not submit, so we need the button
 			btnSubmit.setEnableHTMLGeneration(true);
 		}
 
 

See Also:

Submit On Change property, AgpTextField.setSubmitOnChange(boolean submit_on_change)

setSubmitOnChange

public void setSubmitOnChange(boolean submit_on_change)

Sets the Submit On Change property of this control.

Parameters:

submit_on_change - true to send a Submit request to the server when the value changes, otherwise false.

Usage:

This functionality depends on JavaScript. It will not work in all browsers.

Example:

 		// depending on an application flag, set this text field to automatically
 		// submit a request to the server when the user enters text.
 		if (g_JavaScriptOK)
 		{
 			Field1.setSubmitOnChange(true);
 		}
 
 

See Also:

Submit On Change property, AgpTextField.getSubmitOnChange()

getEmptyStringIsNull

public boolean getEmptyStringIsNull()

Returns whether the value of an empty text control is null.

A text field containing no characters can be interpreted in two ways: either its value is null or it is the empty string, "". The null value is generally more appropriate when the field is bound to a database column that can contain a null value, so as to avoid storing a value of "" in the database. Some applications will require that the text field contain a valid String object at all times, so they will use the empty string value for an empty field.

The default value of this property is false. If true, then the value of an empty text control is null instead of the empty string. This property can be set programmatically using the setEmptyStringIsNull method.

Example:

 		boolean emptyIsNull = Field1.getEmptyStringIsNull();
 

See Also:

AgpTextField.getText(), AgpTextField.setEmptyStringIsNull(boolean b)

setEmptyStringIsNull

public void setEmptyStringIsNull(boolean b)

Specifies whether the value of an empty text control is null. The default setting is false.

A text field containing no characters can be interpreted in two ways: either its value is null or it is the empty string, "". The null value is generally more appropriate when the field is bound to a database column that can contain a null value, so as to avoid storing a value of "" in the database. Some applications will require that the text field contain a valid String object at all times, so they will use the empty string value for an empty field.

Parameters:

b - true if the value of an empty text control should be null instead of the empty string; otherwise false.

Usage:

Note that getText() on an empty text field will always return the empty string.

Example:

 		// Indicate that this text field should return a null value if
 		// the user deletes its contents
 		Field1.setEmptyStringIsNull(true);
 

See Also:

AgpTextField.getEmptyStringIsNull(), AgpTextField.getText()

getDatatype

public char getDatatype()

Gets the data type for a text field.

See Also:

AgpTextField.setDatatype(char datatype)

setDatatype

public void setDatatype(char datatype)

Sets the data type for a text field. The data type is a constant from com.sssw.rt.util.DatatypeCodes.
It must be one of DatatypeCodes.TYPE_STRING, TYPE_LONG, TYPE_DOUBLE, TYPE_BIGDECIMAL TYPE_DATE, TYPE_TIME, or TYPE_TIMESTAMP.

Note that patterns and styles are not currently supported for BigDecimals. For information on display patterns and styles, see Formatting Patterns and Styles in the online General Reference.

getDisplayPattern

public String getDisplayPattern()

Returns a String that identifies the pattern that the control uses to display the data.

Usage:

For information on display patterns and styles, see Formatting Patterns and Styles in the online General Reference.

Use the AgpTextField.setDisplayPattern(String pattern) method to assign this value at runtime.

Note that a display pattern overrides a display style. If the display pattern is null, then the display style is used.

Example:

  String pattern;
  pattern = ControlName1.getDisplayPattern();
 

See Also:

Display Format property, AgpTextField.getDisplayStyle(), AgpTextField.setDisplayStyle(int style)

setDisplayPattern

public void setDisplayPattern(String pattern)

Assigns the control's display format.

Parameters:

pattern - specifies the pattern

Usage:

For information on display patterns and styles, see Formatting Patterns and Styles in the online General Reference. For Integer and Floating Point fields, see also DecimalFormat. For Time, Date and Timestamp field, see also SimpleDateFormat.

Note that a display pattern overrides a display style. If the display pattern is null, then the display style is used.

Use the AgpTextField.getDisplayPattern() method to determine the current value.

Example:

 ControlName1.setDisplayPattern("$#,##0.00;($#,##0.00)");
 

See Also:

Display Format property, AgpTextField.setDisplayStyle(int style)

getDisplayStyle

public int getDisplayStyle()

Obtains the control's display style.

Usage:

For information on display patterns and styles, see Formatting Patterns and Styles in the online General Reference.

Note that a display pattern overrides a display style. If the display pattern is null, then the display style is used.

Use the AgpTextField.setDisplayStyle(int style) method to assign this value at runtime.

Example:

  int style;
  style = ControlName1.getDisplayStyle();
 
See Also: 
Display Format property, 
AgpTextField.getDisplayPattern()

setDisplayStyle

public void setDisplayStyle(int style)

Assigns the control's display style.

Parameters:

style - specifies a Style constant.

Usage:

For information on display patterns and styles, see Formatting Patterns and Styles in the online General Reference.

About the numeric style PERCENTSTYLE:
"63%" represents a value of .63, not 63. So this style makes little sense for integer fields (it could only display 100%, 200%, etc).

A display pattern overrides a display style. If the display pattern is null, then the display style is used.

Use the getDisplayStyle() method to retrieve this value at runtime.

Example:

  ControlName1.setDisplayStyle(AgFormat.CURRENCYSTYLE);
 
See Also: 
Display Format property, 
AgpTextField.getDisplayStyle(), 
AgpTextField.setDisplayPattern(String)

getObjectValue

public Object getObjectValue()

Get the field value as an Object.

setObjectValue

public void setObjectValue(Object value)

Set the field value as an Object.

getIntegerValue

public Integer getIntegerValue()
                        throws AgoApiException

Get the field value.

setIntegerValue

public void setIntegerValue(Integer value)

Set the field value.

getDoubleValue

public Double getDoubleValue()
                      throws AgoApiException

Get the field value.

setDoubleValue

public void setDoubleValue(Double value)

Set the field value.

getBigDecimalValue

public BigDecimal getBigDecimalValue()
                              throws AgoApiException

Get the field value.

setBigDecimalValue

public void setBigDecimalValue(BigDecimal value)

Set the field value.

getDateValue

public Date getDateValue()

Get the field value.

setDateValue

public void setDateValue(Date value)

Set the field value.

getTimeValue

public Time getTimeValue()

Get the field value.

setTimeValue

public void setTimeValue(Time value)

Set the field value.

getTimestampValue

public Timestamp getTimestampValue()

Get the field value.

setTimestampValue

public void setTimestampValue(Timestamp value)

Set the field value.

format

public String format(Object ob,
                     String pattern,
                     int style1,
                     int style2)

Callback to format the object according to the specified pattern or style. Default implementation simply calls
AgFormat.format(ob, pattern, style1, style2)

This method is not useful for developers using standard SilverStream classes. It is provided as a mechanism for developers who wish to create their own classes that extend the SilverStream classes and support some additional formatting/parsing rules.

Specified by:

format in interface com.sssw.rt.util.AgiValueHelperCallback

parse

public Object parse(int datatype,
                    String parseStr,
                    String pattern,
                    int style1,
                    int style2)
             throws IllegalArgumentException

Callback to parse the string according to the specified pattern or style. Default implementation simply calls
AgParse.parse(datatype, parseStr, pattern, style1, style2)

This method is not useful for developers using standard SilverStream classes. It is provided as a mechanism for developers who wish to create their own classes that extend the SilverStream classes and support some additional formatting/parsing rules.

Specified by:

parse in interface com.sssw.rt.util.AgiValueHelperCallback