com.smartgwt.client.widgets.form.fields

Class CanvasItem

java.lang.Object

com.smartgwt.client.core.JsObject

com.smartgwt.client.core.DataClass

com.smartgwt.client.core.RefDataClass

com.smartgwt.client.widgets.form.fields.FormItem

com.smartgwt.client.widgets.form.fields.CanvasItem

All Implemented Interfaces:

com.google.gwt.event.shared.HasHandlers, HasBlurHandlers, HasCanEditChangedHandlers, HasChangedHandlers, HasChangeHandlers, HasClickHandlers, HasDoubleClickHandlers, HasEditorEnterHandlers, HasEditorExitHandlers, HasFocusHandlers, HasIconClickHandlers, HasIconKeyPressHandlers, HasItemHoverHandlers, HasKeyDownHandlers, HasKeyPressHandlers, HasKeyUpHandlers, HasPendingStatusChangedHandlers, HasPickerIconClickHandlers, HasReadOnlyDisplayChangedHandlers, HasShowContextMenuHandlers, HasShowValueHandlers, HasTitleClickHandlers, HasTitleDoubleClickHandlers, HasTitleHoverHandlers, HasValueHoverHandlers, HasValueIconClickHandlers

Direct Known Subclasses:

ButtonItem, DateRangeItem, FileItem, MultiComboBoxItem, MultiFileItem, PickTreeItem, RelativeDateItem, RichTextItem, SectionItem, SliderItem, ToolbarItem

public class CanvasItem
extends FormItem
implements HasCanEditChangedHandlers, HasReadOnlyDisplayChangedHandlers, HasShowValueHandlers

FormItem which renders a Canvas inline in a DynamicForm instance.

CanvasItem is shouldSaveValue:false by default, meaning that no value from the CanvasItem will be present in DynamicForm.getValues() and no value will be saved when DynamicForm.saveData() is called. This is appropriate if the Canvas does not participate in editing a value of the form and is embedded in the form for layout or UI purposes only (e.g. ButtonItem, SectionItem). Note that some built-in CanvasItem types override the shouldSaveValue default to true (e.g. MultiComboBoxItem, RichTextItem).

If you set shouldSaveValue:true, a showValue event will be raised to provide a value that your item should display. Handle this event by calling methods on the Canvas you've created to cause the value to be displayed.

The showValue event will be triggered in various situations where the form receives data, including a call to DynamicForm.setValues(), DynamicForm.editRecord(), or if DynamicForm.fetchData() is called and a Record is returned. Bear in mind that the showValue event can be called when the form and your item have not yet been drawn; in this case, store the value for later display.

To provide a value to the form, call storeValue() whenever the user changes the value in your Canvas. Generally, if storeValue() is called then shouldSaveValue should be overridden to true. Note that the form will not call getValue() in order to discover your item's value, so there is no purpose in overriding this method; instead, call storeValue() to proactively inform the form about changes to the value. This approach is necessary in order to enable change events.

If you cannot easily detect changes to values in your Canvas, a workaround is to call storeValue right before the form saves.

Nested Class Summary

Nested classes/interfaces inherited from class com.smartgwt.client.widgets.form.fields.FormItem

FormItem.CustomStateGetter, FormItem.StateCustomizer

Field Summary

Fields inherited from class com.smartgwt.client.widgets.form.fields.FormItem

configOnly, scClassName, warnOnEditorTypeConversion, warnOnEditorTypeConversionDefault

Fields inherited from class com.smartgwt.client.core.RefDataClass

id

Fields inherited from class com.smartgwt.client.core.DataClass

factoryCreated, factoryProperties

Fields inherited from class com.smartgwt.client.core.JsObject

jsObj

Constructor Summary

Constructors

Constructor and Description
CanvasItem()
CanvasItem(com.google.gwt.core.client.JavaScriptObject jsObj)
CanvasItem(java.lang.String name)
CanvasItem(java.lang.String name, java.lang.String title)

Method Summary

Modifier and Type	Method and Description
com.google.gwt.event.shared.HandlerRegistration	addCanEditChangedHandler(CanEditChangedHandler handler) Add a canEditChanged handler.
com.google.gwt.event.shared.HandlerRegistration	addReadOnlyDisplayChangedHandler(ReadOnlyDisplayChangedHandler handler) Add a readOnlyDisplayChanged handler.
com.google.gwt.event.shared.HandlerRegistration	addShowValueHandler(ShowValueHandler handler) Add a showValue handler.
static void	changeAutoChildDefaults(java.lang.String autoChildName, Canvas defaults) Changes the defaults for Canvas AutoChildren named autoChildName.
static void	changeAutoChildDefaults(java.lang.String autoChildName, FormItem defaults) Changes the defaults for FormItem AutoChildren named autoChildName.
static void	changePickerIconDefaults(FormItemIcon defaults)
protected Canvas	createCanvas() This method is called to dynamically create a canvas for this CanvasItem.
java.lang.Boolean	getApplyPromptToCanvas() If FormItem.prompt is specified for this item, should the prompt be applied to the canvas for this item?
java.lang.Boolean	getAutoDestroy() Should this item's canvas be automatically destroyed when the item is destroyed? Form items are destroyed automatically when a call to DynamicForm.setItems() removes them from their parent form, or if their parent form is destroyed.
Canvas	getCanvas() The canvas that will be displayed inside this item.
java.lang.Boolean	getEditCriteriaInInnerForm() Flag to disable the criteria editing overrides described in setCriterionGetter() whereby if this item contains a DynamicForm as its canvas, it will be used to edit nested AdvancedCriteria automatically.
int	getHeight() Height of the Canvas.
java.lang.String	getHeightAsString() Height of the Canvas.
java.lang.Integer	getMaxHeight() Maximum valid height for this CanvasItem in pixels.
java.lang.Integer	getMinHeight() Minimum valid height for this CanvasItem in pixels.
java.lang.Boolean	getMultiple() Whether this CanvasItem is intended to hold multiple values.
static CanvasItem	getOrCreateRef(com.google.gwt.core.client.JavaScriptObject jsObj)
Overflow	getOverflow() CanvasItems support specifying overflow for the Canvas directly on the item.
java.lang.String	getPrompt() This text is shown as a tooltip prompt when the cursor hovers over this item.
java.lang.Boolean	getShouldSaveValue() Should this item's value be saved in the form's values and hence returned from DynamicForm.getValues()?
java.lang.Boolean	hasAdvancedCriteria() Overridden to return true if canvas is a dynamicForm.
java.lang.Boolean	isFocused() Does this CanvasItem have keyboard focus.
void	setApplyPromptToCanvas(java.lang.Boolean applyPromptToCanvas) If FormItem.prompt is specified for this item, should the prompt be applied to the canvas for this item?
void	setAutoDestroy(java.lang.Boolean autoDestroy) Should this item's canvas be automatically destroyed when the item is destroyed? Form items are destroyed automatically when a call to DynamicForm.setItems() removes them from their parent form, or if their parent form is destroyed.
void	setCanEditCriterionPredicate(FormItemCanEditCriterionPredicate predicate) AdvancedCriteria objects may be edited via nested dynamicForms as described in CanvasItem.setCriterionGetter.
void	setCanvas(Canvas canvas) The canvas that will be displayed inside this item.
void	setCriterionGetter(FormItemCriterionGetter getter) The standard formItem criteria editing APIs have been overridden in the canvasItem class to simplify the editing of complex AdvancedCriteria objects using nested DynamicForms.
void	setCriterionSetter(FormItemCriterionSetter setter) Provide a setCriterion() implementation to display a Criterion object in this item for editing.
static void	setDefaultProperties(CanvasItem canvasItemProperties) Class level method to set the default properties of this class.
void	setEditCriteriaInInnerForm(java.lang.Boolean editCriteriaInInnerForm) Flag to disable the criteria editing overrides described in setCriterionGetter() whereby if this item contains a DynamicForm as its canvas, it will be used to edit nested AdvancedCriteria automatically.
void	setHeight(int height) Height of the Canvas.
void	setHeight(java.lang.String height) Height of the Canvas.
void	setMaxHeight(java.lang.Integer maxHeight) Maximum valid height for this CanvasItem in pixels.
void	setMinHeight(java.lang.Integer minHeight) Minimum valid height for this CanvasItem in pixels.
void	setMultiple(java.lang.Boolean multiple) Whether this CanvasItem is intended to hold multiple values.
void	setOverflow(Overflow overflow) CanvasItems support specifying overflow for the Canvas directly on the item.
void	setPrompt(java.lang.String prompt) This text is shown as a tooltip prompt when the cursor hovers over this item.
void	setShouldDisableCanvasCustomizer(ShouldDisableCanvasCustomizer customizer) Sets the ShouldDisableCanvasCustomizer that is called to determine whether the canvas should be disabled when this CanvasItem is disabled or its editability changes.
void	setShouldSaveValue(java.lang.Boolean shouldSaveValue) Should this item's value be saved in the form's values and hence returned from DynamicForm.getValues()?
protected void	setupCanvasConstructor()
void	storeValue(java.lang.Object value) Store a value for this form item.
void	storeValue(Record value) Store a value for this form item.
void	storeValue(RecordList value) Store a value for this form item.
void	updateCanvasTabPosition() This method will place an entry for the canvas under this item in the TabIndexManager.

Methods inherited from class com.smartgwt.client.widgets.form.fields.FormItem

_getValue, addBlurHandler, addChangedHandler, addChangeHandler, addClickHandler, addDoubleClickHandler, addEditorEnterHandler, addEditorExitHandler, addFocusHandler, addIcon, addIcon, addIconClickHandler, addIconKeyPressHandler, addItemHoverHandler, addKeyDownHandler, addKeyPressHandler, addKeyUpHandler, addPendingStatusChangedHandler, addPickerIconClickHandler, addShowContextMenuHandler, addTitleClickHandler, addTitleDoubleClickHandler, addTitleHoverHandler, addValueHoverHandler, addValueIconClickHandler, applyFormula, asSGWTComponent, blurItem, canEditCriterion, clearErrors, clearValue, disable, disableIcon, enable, enableIcon, error, error, errorIfNotCreated, focusAfterItem, focusInItem, getAccessKey, getAlign, getAllowExpressions, getAlwaysFetchMissingValues, getAlwaysShowControlBox, getApplyAlignToText, getApplyHeightToTextBox, getAriaRole, getAttribute, getAttributeAsBoolean, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsFloat, getAttributeAsInt, getAttributeAsJavaScriptObject, getAttributeAsObject, getAttributeAsString, getAutoComplete, getAutoCompleteKeywords, getBrowserInputType, getBrowserSpellCheck, getCanEdit, getCanEditOpaqueValues, getCanFocus, getCanSelectText, getCanTabToIcons, getCanvasAutoChild, getCellHeight, getCellStyle, getChangeOnKeypress, getClassName, getClipStaticValue, getClipTitle, getConfig, getContainerWidget, getControlStyle, getCriteriaField, getCriterion, getCriterion, getCursorPosition, getCustomState, getDataPath, getDateFormatter, getDecimalPad, getDecimalPrecision, getDefaultIconSrc, getDisabled, getDisableIconsOnReadOnly, getDisplayField, getDisplayFieldName, getDisplayValue, getDisplayValue, getEditorTypeConfig, getEditPendingCSSText, getEditProxyConstructor, getEmptyDisplayValue, getEmptyValueIcon, getEndRow, getErrorIconHeight, getErrorIconSrc, getErrorIconWidth, getErrorMessageWidth, getErrors, getExportFormat, getFetchMissingValues, getFieldName, getFilterLocally, getForeignDisplayField, getForm, getFormat, getFormItemAutoChild, getFormula, getFullDataPath, getGlobalTabIndex, getGridColNum, getGridRowNum, getHidden, getHint, getHintStyle, getHoverAlign, getHoverDelay, getHoverHeight, getHoverOpacity, getHoverStyle, getHoverVAlign, getHoverWidth, getIcon, getIconHeight, getIconHSpace, getIconPageRect, getIconPrompt, getIconRect, getIcons, getIconTabPosition, getIconVAlign, getIconWidth, getID, getImageURLPrefix, getImageURLSuffix, getImplicitSave, getImplicitSaveOnBlur, getInputFormat, getLeft, getListGrid, getLoadingDisplayValue, getLocateItemBy, getMinHintWidth, getMultipleValueSeparator, getName, getOperator, getOptionCriteria, getOptionDataSource, getOptionDataSourceAsString, getOptionFilterContext, getOptionOperationId, getOriginalValueMessage, getPageLeft, getPageRect, getPageTop, getPaletteDefaults, getPicker, getPickerIcon, getPickerIcon, getPickerIconHeight, getPickerIconName, getPickerIconPrompt, getPickerIconProperties, getPickerIconSrc, getPickerIconStyle, getPickerIconTabPosition, getPickerIconWidth, getPixelHeight, getPixelWidth, getPrintTextBoxStyle, getPrintTitleStyle, getReadOnlyDisplay, getReadOnlyHover, getReadOnlyTextBoxStyle, getReadOnlyWhen, getRect, getRedrawOnChange, getRejectInvalidValueOnChange, getRequired, getRequiredMessage, getRequiredWhen, getRowSpan, getSaveOnEnter, getScClassName, getSelectedRecord, getSelectOnClick, getSelectOnFocus, getShowClippedTitleOnHover, getShowClippedValueOnHover, getShowDeletions, getShowDisabled, getShowDisabledIconsOnFocus, getShowDisabledPickerIconOnFocus, getShowErrorIcon, getShowErrorStyle, getShowErrorText, getShowFocused, getShowFocusedErrorState, getShowFocusedIcons, getShowFocusedPickerIcon, getShowHint, getShowIcons, getShowIconsOnFocus, getShowOldValueInHover, getShowOver, getShowOverIcons, getShowPending, getShowPickerIcon, getShowPickerIconOnFocus, getShowRTL, getShowTitle, getShowValueIconOnly, getStartRow, getStaticHeight, getStopOnError, getSupportsCutPasteEvents, getSuppressValueIcon, getSynchronousValidation, getTabIndex, getTextAlign, getTextBoxStyle, getTextFormula, getTimeFormatter, getTitle, getTitleAlign, getTitleColSpan, getTitleOrientation, getTitleStyle, getTitleVAlign, getTooltip, getTop, getType, getUpdateControlOnOver, getUpdatePickerIconOnOver, getUpdateTextBoxOnOver, getUseAdvancedCriteria, getUseDisabledHintStyleForReadOnly, getUseLocalDisplayFieldValue, getValidateOnChange, getValidateOnExit, getValidOperators, getVAlign, getValue, getValueAsRecordList, getValueDeselectedCSSText, getValueField, getValueFieldName, getValueIconHeight, getValueIconLeftPadding, getValueIconRightPadding, getValueIconSize, getValueIconWidth, getValueMap, getValueMapAsArray, getVisible, getVisibleHeight, getVisibleTitleWidth, getVisibleWhen, getVisibleWidth, getWarnOnEditorTypeConversion, getWarnOnEditorTypeConversionDefault, getWidth, getWidthAsString, getWrapHintText, getWrapTitle, handleWarnOnEditorTypeConversion, hasErrors, hide, hideIcon, invalidateDisplayValueCache, isConfigOnly, isCreated, isCutEvent, isDisabled, isDrawn, isInGrid, isPasteEvent, isVisible, linkToInstanceUponCreate, mapDisplayToValue, mapValueToDisplay, mapValueToDisplay, mapValueToDisplay, redraw, redraw, removeIcon, setAccessKey, setAlign, setAllowExpressions, setAlwaysFetchMissingValues, setAlwaysShowControlBox, setApplyAlignToText, setApplyHeightToTextBox, setAriaRole, setAriaState, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAutoChildConstructor, setAutoChildProperties, setAutoChildProperties, setAutoChildProperties, setAutoChildVisibility, setAutoComplete, setAutoCompleteKeywords, setBrowserInputType, setBrowserSpellCheck, setCanEdit, setCanEditOpaqueValues, setCanFocus, setCanSelectText, setCanTabToIcons, setCellHeight, setCellStyle, setChangeOnKeypress, setClipStaticValue, setClipTitle, setColSpan, setColSpan, setConfigOnly, setControlStyle, setCriteriaField, setCriterion, setCustomStateGetter, setDataPath, setDateFormatter, setDecimalPad, setDecimalPrecision, setDefaultIconSrc, setDefaultProperties, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDisabled, setDisableIconsOnReadOnly, setDisplayField, setDisplayFormat, setDisplayFormat, setEditorProperties, setEditorType, setEditorType, setEditorType, setEditorValueFormatter, setEditorValueParser, setEditPendingCSSText, setEditProxyConstructor, setEmptyDisplayValue, setEmptyValueIcon, setEndRow, setErrorFormatter, setErrorIconHeight, setErrorIconSrc, setErrorIconWidth, setErrorMessageWidth, setErrorOrientation, setErrors, setErrors, setExportFormat, setFetchMissingValues, setFilterLocally, setForeignDisplayField, setFormat, setFormula, setGlobalTabIndex, setHidden, setHint, setHintStyle, setHoverAlign, setHoverDelay, setHoverHeight, setHoverOpacity, setHoverStyle, setHoverVAlign, setHoverWidth, setIconDisabled, setIconHeight, setIconHSpace, setIconPrompt, setIcons, setIconShowOnFocus, setIconVAlign, setIconWidth, setID, setImageURLPrefix, setImageURLSuffix, setImplicitSave, setImplicitSaveOnBlur, setInitHandler, setInputFormat, setInputTransformer, setItemHoverFormatter, setItemTitleHoverFormatter, setItemValueHoverFormatter, setJavaScriptObject, setLeft, setLoadingDisplayValue, setLocateItemBy, setMinHintWidth, setMultipleValueSeparator, setName, setNullProperty, setOperator, setOptionCriteria, setOptionDataSource, setOptionDataSource, setOptionFilterContext, setOptionOperationId, setOriginalValueMessage, setPickerIconHeight, setPickerIconName, setPickerIconPrompt, setPickerIconProperties, setPickerIconSrc, setPickerIconStyle, setPickerIconWidth, setPrintTextBoxStyle, setPrintTitleStyle, setProperty, setProperty, setProperty, setProperty, setProperty, setReadOnlyDisplay, setReadOnlyHover, setReadOnlyTextBoxStyle, setReadOnlyWhen, setRedrawOnChange, setRejectInvalidValueOnChange, setRequired, setRequiredMessage, setRequiredWhen, setRowSpan, setSaveOnEnter, setScClassName, setSelectOnClick, setSelectOnFocus, setShowClippedTitleOnHover, setShowClippedValueOnHover, setShowDeletions, setShowDisabled, setShowDisabledIconsOnFocus, setShowDisabledPickerIconOnFocus, setShowErrorIcon, setShowErrorStyle, setShowErrorText, setShowFocused, setShowFocusedErrorState, setShowFocusedIcons, setShowFocusedPickerIcon, setShowHint, setShowIcons, setShowIconsOnFocus, setShowIfCondition, setShowOldValueInHover, setShowOver, setShowOverIcons, setShowPending, setShowPickerIcon, setShowPickerIconOnFocus, setShowRTL, setShowTitle, setShowValueIconOnly, setStartRow, setStateCustomizer, setStaticHeight, setStopOnError, setSupportsCutPasteEvents, setSuppressValueIcon, setSynchronousValidation, setTabIndex, setTextAlign, setTextBoxStyle, setTextFormula, setTimeFormatter, setTitle, setTitleAlign, setTitleColSpan, setTitleHoverFormatter, setTitleOrientation, setTitleStyle, setTitleVAlign, setTooltip, setTop, setType, setUpdateControlOnOver, setUpdatePickerIconOnOver, setUpdateTextBoxOnOver, setUseAdvancedCriteria, setUseDisabledHintStyleForReadOnly, setUseLocalDisplayFieldValue, setValidateOnChange, setValidateOnExit, setValidators, setValidOperators, setVAlign, setValue, setValue, setValue, setValue, setValue, setValue, setValueDeselectedCSSText, setValueField, setValueFormatter, setValueHoverFormatter, setValueIconHeight, setValueIconLeftPadding, setValueIconMapper, setValueIconRightPadding, setValueIcons, setValueIconSize, setValueIconWidth, setValueMap, setValueMap, setVisible, setVisibleWhen, setWarnOnEditorTypeConversion, setWarnOnEditorTypeConversionDefault, setWidth, setWidth, setWrapHintText, setWrapTitle, shouldApplyHeightToTextBox, shouldFetchMissingValue, shouldSaveOnEnter, shouldStopKeyPressBubbling, show, showIcon, showPicker, stopHover, storeValue, updateState, validate, valueClipped

Methods inherited from class com.smartgwt.client.core.RefDataClass

getRef, getRef, internalSetID

Methods inherited from class com.smartgwt.client.core.DataClass

applyFactoryProperties, doAddHandler, fireEvent, getAttributeAsDoubleArray, getAttributeAsIntArray, getAttributeAsLong, getAttributeAsMap, getAttributeAsObject, getAttributeAsRecord, getAttributeAsStringArray, getAttributes, getHandlerCount, isFactoryCreated, setAttribute, setAttribute, setAttribute, setAttributeAsJavaObject, setFactoryCreated

Methods inherited from class com.smartgwt.client.core.JsObject

equals, getJsObj, hashCode, setJsObj

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.google.gwt.event.shared.HasHandlers

fireEvent

Constructor Detail

CanvasItem

public CanvasItem()

CanvasItem

public CanvasItem(com.google.gwt.core.client.JavaScriptObject jsObj)

CanvasItem

public CanvasItem(java.lang.String name)

CanvasItem

public CanvasItem(java.lang.String name,
                  java.lang.String title)

Method Detail

getOrCreateRef

public static CanvasItem getOrCreateRef(com.google.gwt.core.client.JavaScriptObject jsObj)

changeAutoChildDefaults

public static void changeAutoChildDefaults(java.lang.String autoChildName,
                                           Canvas defaults)

Changes the defaults for Canvas AutoChildren named autoChildName.

Parameters:

autoChildName - name of an AutoChild to customize the defaults for.

defaults - Canvas defaults to apply. These defaults override any existing properties without destroying or wiping out non-overridden properties. For usage tips on this param, see SGWTProperties.

See Also:

AutoChildUsage

changeAutoChildDefaults

public static void changeAutoChildDefaults(java.lang.String autoChildName,
                                           FormItem defaults)

Changes the defaults for FormItem AutoChildren named autoChildName.

Parameters:

autoChildName - name of an AutoChild to customize the defaults for.

defaults - FormItem defaults to apply. These defaults override any existing properties without destroying or wiping out non-overridden properties. For usage tips on this param, see SGWTProperties.

See Also:

AutoChildUsage

changePickerIconDefaults

public static void changePickerIconDefaults(FormItemIcon defaults)

setApplyPromptToCanvas

public void setApplyPromptToCanvas(java.lang.Boolean applyPromptToCanvas)

If FormItem.prompt is specified for this item, should the prompt be applied to the canvas for this item?

Parameters:

applyPromptToCanvas - New applyPromptToCanvas value. Default value is true

getApplyPromptToCanvas

public java.lang.Boolean getApplyPromptToCanvas()

If FormItem.prompt is specified for this item, should the prompt be applied to the canvas for this item?

Returns:

Current applyPromptToCanvas value. Default value is true

setAutoDestroy

public void setAutoDestroy(java.lang.Boolean autoDestroy)

Should this item's canvas be automatically destroyed when the item is destroyed? Form items are destroyed automatically when a call to DynamicForm.setItems() removes them from their parent form, or if their parent form is destroyed. This property governs whether, when this occurs, the item's canvas should also be destroyed.

This property has no effect for canvases automatically created via the "autoChild" pattern, using canvasProperties, canvasDefaults etc. CanvasItems which create their canvas in this way will always destroy the canvas when the item is destroyed or on an explicit setCanvas() call, regardless of this property's value.

Setting this property to true is typically appropriate for cases where a custom CanvasItem automatically creates its canvas as part of its initialization flow, and the canvas will not be re-used outside the item.
Note that once a canvas has been destroyed it can not be re-used elsewhere within an application.

Note : This is an advanced setting

Parameters:

autoDestroy - New autoDestroy value. Default value is false

getAutoDestroy

public java.lang.Boolean getAutoDestroy()

Should this item's canvas be automatically destroyed when the item is destroyed? Form items are destroyed automatically when a call to DynamicForm.setItems() removes them from their parent form, or if their parent form is destroyed. This property governs whether, when this occurs, the item's canvas should also be destroyed.

This property has no effect for canvases automatically created via the "autoChild" pattern, using canvasProperties, canvasDefaults etc. CanvasItems which create their canvas in this way will always destroy the canvas when the item is destroyed or on an explicit setCanvas() call, regardless of this property's value.

Setting this property to true is typically appropriate for cases where a custom CanvasItem automatically creates its canvas as part of its initialization flow, and the canvas will not be re-used outside the item.
Note that once a canvas has been destroyed it can not be re-used elsewhere within an application.

Returns:

Current autoDestroy value. Default value is false

setCanvas

public void setCanvas(Canvas canvas)

The canvas that will be displayed inside this item. You can pass an instance you've already created, or its global ID as a String.

If a canvas hasn't been specified via setCanvas(), the canvas for this item will be auto-created as configured by the methods setAutoChildProperties() and setAutoChildConstructor().

Note that subclasses of CanvasItem may use a different AutoChild name than just "canvas". For example, SliderItem uses "slider", and in that case, you need to use the specific APIs provided by the subclass.

Note that Canvas.canvasItem will be set on the canvas to point back to this item.

If this method is called after the component has been drawn/initialized: Setter to update the canvas at runtime

Parameters:

canvas - New canvas to display. Default value is null

getCanvas

public Canvas getCanvas()

The canvas that will be displayed inside this item. You can pass an instance you've already created, or its global ID as a String.

If a canvas hasn't been specified via setCanvas(), the canvas for this item will be auto-created as configured by the methods setAutoChildProperties() and setAutoChildConstructor().

Note that subclasses of CanvasItem may use a different AutoChild name than just "canvas". For example, SliderItem uses "slider", and in that case, you need to use the specific APIs provided by the subclass.

Note that Canvas.canvasItem will be set on the canvas to point back to this item.

This component is an AutoChild named "canvas". For an overview of how to use and configure AutoChildren, see Using AutoChildren.

Returns:

Current canvas value. Default value is null

setEditCriteriaInInnerForm

public void setEditCriteriaInInnerForm(java.lang.Boolean editCriteriaInInnerForm)

Flag to disable the criteria editing overrides described in setCriterionGetter() whereby if this item contains a DynamicForm as its canvas, it will be used to edit nested AdvancedCriteria automatically.

This flag is required for cases where a canvasItem contains a DynamicForm, but the form is not set up to show inner field values of nested objects, and therefore should not attempt to apply nested advanced criteria directly to the form.

Note : This is an advanced setting

Parameters:

editCriteriaInInnerForm - New editCriteriaInInnerForm value. Default value is true

getEditCriteriaInInnerForm

public java.lang.Boolean getEditCriteriaInInnerForm()

Flag to disable the criteria editing overrides described in setCriterionGetter() whereby if this item contains a DynamicForm as its canvas, it will be used to edit nested AdvancedCriteria automatically.

This flag is required for cases where a canvasItem contains a DynamicForm, but the form is not set up to show inner field values of nested objects, and therefore should not attempt to apply nested advanced criteria directly to the form.

Returns:

Current editCriteriaInInnerForm value. Default value is true

setHeight

public void setHeight(int height)

Height of the Canvas. Can be either a number indicating a fixed height in pixels, a percentage indicating a percentage of the overall form's height, or "*" indicating take whatever remaining space is available. See the FormLayout overview for details.

Height may also be explicitly specified on the canvas. In this any canvasItem.height will be ignored in favor of the value applied to the canvas directly. In either case, percentage values will be resolved using standard formItem sizing rules as described in FormLayout

Overrides:

setHeight in class FormItem

Parameters:

height - New height value. Default value is null

See Also:

FormItem.setWidth(int), DynamicForm.setItemLayout(com.smartgwt.client.types.FormLayoutType), FormLayout overview and related methods, Filling Example

getHeight

public int getHeight()

Height of the Canvas. Can be either a number indicating a fixed height in pixels, a percentage indicating a percentage of the overall form's height, or "*" indicating take whatever remaining space is available. See the FormLayout overview for details.

Height may also be explicitly specified on the canvas. In this any canvasItem.height will be ignored in favor of the value applied to the canvas directly. In either case, percentage values will be resolved using standard formItem sizing rules as described in FormLayout

Note : This method will return -1 if the underlying SmartClient JavaScript attribute value cannot be expressed as a(n) int. In that case, other getters, similarly-named but ending in AsString, AsCanvas, etc., may be provided.

Overrides:

getHeight in class FormItem

Returns:

Current height value. Default value is null

See Also:

FormItem.getWidth(), DynamicForm.getItemLayout(), FormLayout overview and related methods, Filling Example

setHeight

public void setHeight(java.lang.String height)

Height of the Canvas. Can be either a number indicating a fixed height in pixels, a percentage indicating a percentage of the overall form's height, or "*" indicating take whatever remaining space is available. See the FormLayout overview for details.

Height may also be explicitly specified on the canvas. In this any canvasItem.height will be ignored in favor of the value applied to the canvas directly. In either case, percentage values will be resolved using standard formItem sizing rules as described in FormLayout

Overrides:

setHeight in class FormItem

Parameters:

height - New height value. Default value is null

See Also:

FormItem.setWidth(int), DynamicForm.setItemLayout(com.smartgwt.client.types.FormLayoutType), FormLayout overview and related methods, Filling Example

getHeightAsString

public java.lang.String getHeightAsString()

Height of the Canvas. Can be either a number indicating a fixed height in pixels, a percentage indicating a percentage of the overall form's height, or "*" indicating take whatever remaining space is available. See the FormLayout overview for details.

Height may also be explicitly specified on the canvas. In this any canvasItem.height will be ignored in favor of the value applied to the canvas directly. In either case, percentage values will be resolved using standard formItem sizing rules as described in FormLayout

Overrides:

getHeightAsString in class FormItem

Returns:

Current height value. Default value is null

See Also:

FormItem.getWidth(), DynamicForm.getItemLayout(), FormLayout overview and related methods, Filling Example

setMaxHeight

public void setMaxHeight(java.lang.Integer maxHeight)

Maximum valid height for this CanvasItem in pixels. Used in calculating the row heights of the containing DynamicForm if the item has a flexible height.

Parameters:

maxHeight - New maxHeight value. Default value is null

getMaxHeight

public java.lang.Integer getMaxHeight()

Maximum valid height for this CanvasItem in pixels. Used in calculating the row heights of the containing DynamicForm if the item has a flexible height.

Returns:

Current maxHeight value. Default value is null

setMinHeight

public void setMinHeight(java.lang.Integer minHeight)

Minimum valid height for this CanvasItem in pixels. Used in calculating the row heights of the containing DynamicForm if the item has a flexible height.

Parameters:

minHeight - New minHeight value. Default value is null

getMinHeight

public java.lang.Integer getMinHeight()

Minimum valid height for this CanvasItem in pixels. Used in calculating the row heights of the containing DynamicForm if the item has a flexible height.

Returns:

Current minHeight value. Default value is null

setMultiple

public void setMultiple(java.lang.Boolean multiple)

Whether this CanvasItem is intended to hold multiple values.

This attribute can affect the return type of getValue(). If this CanvasItem is storing multiple values, then the return type of getValue() is JavaScriptObject (a JavaScript array object) if multiple is null or false. However, if multiple is true, then the return type is either List or RecordList.

Overrides:

setMultiple in class FormItem

Parameters:

multiple - New multiple value. Default value is false

See Also:

Appearance overview and related methods

getMultiple

public java.lang.Boolean getMultiple()

Whether this CanvasItem is intended to hold multiple values.

This attribute can affect the return type of getValue(). If this CanvasItem is storing multiple values, then the return type of getValue() is JavaScriptObject (a JavaScript array object) if multiple is null or false. However, if multiple is true, then the return type is either List or RecordList.

Overrides:

getMultiple in class FormItem

Returns:

Current multiple value. Default value is false

See Also:

Appearance overview and related methods

setOverflow

public void setOverflow(Overflow overflow)

CanvasItems support specifying overflow for the Canvas directly on the item.

Parameters:

overflow - New overflow value. Default value is null

getOverflow

public Overflow getOverflow()

CanvasItems support specifying overflow for the Canvas directly on the item.

Returns:

Current overflow value. Default value is null

setPrompt

public void setPrompt(java.lang.String prompt)

This text is shown as a tooltip prompt when the cursor hovers over this item. When item is read-only a different hover can be shown with FormItem.readOnlyHover.

If this method is called after the component has been drawn/initialized: Set the FormItem.prompt for this item. Default implementation will also apply the prompt to canvas if applyPromptToCanvas is true.

Overrides:

setPrompt in class FormItem

Parameters:

prompt - new prompt for the item. Default value is null

See Also:

HTMLString, Basics overview and related methods

getPrompt

public java.lang.String getPrompt()

This text is shown as a tooltip prompt when the cursor hovers over this item. When item is read-only a different hover can be shown with FormItem.readOnlyHover.

Overrides:

getPrompt in class FormItem

Returns:

Current prompt value. Default value is null

See Also:

HTMLString, Basics overview and related methods

setShouldSaveValue

public void setShouldSaveValue(java.lang.Boolean shouldSaveValue)

Should this item's value be saved in the form's values and hence returned from DynamicForm.getValues()?

Note that by default, shouldSaveValue is false for CanvasItems, meaning that no value from the CanvasItem will be present in DynamicForm.getValues() and no value for the CanvasItem will be saved when DynamicForm.saveData() is called. See the CanvasItem class overview for a discussion of values handling in CanvasItems.

Overrides:

setShouldSaveValue in class FormItem

Parameters:

shouldSaveValue - New shouldSaveValue value. Default value is false

getShouldSaveValue

public java.lang.Boolean getShouldSaveValue()

Should this item's value be saved in the form's values and hence returned from DynamicForm.getValues()?

Note that by default, shouldSaveValue is false for CanvasItems, meaning that no value from the CanvasItem will be present in DynamicForm.getValues() and no value for the CanvasItem will be saved when DynamicForm.saveData() is called. See the CanvasItem class overview for a discussion of values handling in CanvasItems.

Overrides:

getShouldSaveValue in class FormItem

Returns:

Current shouldSaveValue value. Default value is false

addCanEditChangedHandler

public com.google.gwt.event.shared.HandlerRegistration addCanEditChangedHandler(CanEditChangedHandler handler)

Add a canEditChanged handler.

Notification method called when the canEdit setting is modified. Developers may make use of this to toggle between an editable and a read-only appearance of the canvas.

The default behavior is:

• If canvas is a DynamicForm, the form's DynamicForm.canEdit setting is set to canEdit.
• CanvasItem.shouldDisableCanvas() is called to determine if the canvas should be disabled.

Standard CanvasItem-based form items may customize the default behavior. For example, a MultiComboBoxItem will hide its comboForm if the readOnlyDisplay is ReadOnlyDisplayAppearance.READONLY or ReadOnlyDisplayAppearance.STATIC and also disable the buttons when made read-only.

Specified by:

addCanEditChangedHandler in interface HasCanEditChangedHandlers

Parameters:

handler - the canEditChanged handler

Returns:

HandlerRegistration used to remove this handler

hasAdvancedCriteria

public java.lang.Boolean hasAdvancedCriteria()

Overridden to return true if canvas is a dynamicForm. See setCriterionGetter() for details of editing advanced criteria using nested dynamicForms.

Overrides:

hasAdvancedCriteria in class FormItem

Returns:

true if this item's canvas is a DynamicForm

See Also:

CriteriaEditing overview and related methods

isFocused

public java.lang.Boolean isFocused()

Does this CanvasItem have keyboard focus.

This method will return true if this item's canvas, or any of its descendents, has keyboard focus

Overrides:

isFocused in class FormItem

Returns:

returns true if this item contains focus.

addReadOnlyDisplayChangedHandler

public com.google.gwt.event.shared.HandlerRegistration addReadOnlyDisplayChangedHandler(ReadOnlyDisplayChangedHandler handler)

Add a readOnlyDisplayChanged handler.

Notification method called when the readOnlyDisplay setting is modified. Developers may make use of this to toggle between an editable and a read-only appearance of the canvas.

The default behavior is: when the canvas is a DynamicForm, the form's DynamicForm.readOnlyDisplay setting is set to appearance.

Standard CanvasItem-based form items may customize the default behavior.

Specified by:

addReadOnlyDisplayChangedHandler in interface HasReadOnlyDisplayChangedHandlers

Parameters:

handler - the readOnlyDisplayChanged handler

Returns:

HandlerRegistration used to remove this handler

addShowValueHandler

public com.google.gwt.event.shared.HandlerRegistration addShowValueHandler(ShowValueHandler handler)

Add a showValue handler.

This method will be called whenever this FormItem's value is being set via a programmatic call to e.g: DynamicForm.setValues() or FormItem.setValue() and may be overridden by CanvasItems intended to support displaying data values to update the embedded Canvas to reflect the value passed in. Note that the first parameter will be a formatted value - while the second parameter will contain the underlying data value for the item.

Specified by:

addShowValueHandler in interface HasShowValueHandlers

Parameters:

handler - the showValue handler

Returns:

HandlerRegistration used to remove this handler

updateCanvasTabPosition

public void updateCanvasTabPosition()

This method will place an entry for the canvas under this item in the TabIndexManager. This ensures the user can tab into the canvas (and its descendants) in the expected position within this item's DynamicForm.

See also Canvas.updateChildTabPositions().

setDefaultProperties

public static void setDefaultProperties(CanvasItem canvasItemProperties)

Class level method to set the default properties of this class. If set, then all existing and subsequently created instances of this class will automatically have default properties corresponding to the properties of the class instance passed to this function. This is a powerful feature that eliminates the need for users to create a separate hierarchy of subclasses that only alter the default properties of this class. Can also be used for skinning / styling purposes.

Note: This method is intended for setting default attributes only and will affect all instances of the underlying class (including those automatically generated in JavaScript). This method should not be used to apply standard EventHandlers or override methods for a class - use a custom subclass instead. Calling this method after instances have been created can result in undefined behavior, since it bypasses any setters and a class instance may have already examined a particular property and not be expecting any changes through this route.

Parameters:

canvasItemProperties - properties that should be used as new defaults when instances of this class are created

See Also:

SGWTProperties

setupCanvasConstructor

protected void setupCanvasConstructor()

createCanvas

protected Canvas createCanvas()

This method is called to dynamically create a canvas for this CanvasItem. Overriding this method provides a mechanism to dynamically create the canvas rather than calling #setCanvas() directly.

Returns:

the canvas to be rendered inside this CanvasItem

setShouldDisableCanvasCustomizer

public void setShouldDisableCanvasCustomizer(ShouldDisableCanvasCustomizer customizer)

Sets the ShouldDisableCanvasCustomizer that is called to determine whether the canvas should be disabled when this CanvasItem is disabled or its editability changes.

Setting a ShouldDisableCanvasCustomizer is the Smart GWT equivalent of overriding the CanvasItem.shouldDisableCanvas() method in SmartClient.

Parameters:

customizer - the ShouldDisableCanvasCustomizer to use.

storeValue

public void storeValue(java.lang.Object value)

Store a value for this form item.

This method will fire standard FormItem.change and FormItem.changed handlers, and store the value passed in such that subsequent calls to FormItem.getValue or DynamicForm.getValue will return the new value for this item.

For canvasItems that manipulate values and display them in some arbitrary canvas representation developers should call this method when the user interacts with the embedded canvas in a way that modifies the value for the item.

If you cannot easily detect changes to values in your Canvas, a workaround is to call storeValue right before the form saves.

Overrides:

storeValue in class FormItem

Parameters:

value - value to save for this item

See Also:

ListGrid Item Example

storeValue

public void storeValue(Record value)

Store a value for this form item. This method will fire standard FormItem.change and FormItem.changed handlers, and store out the method passed in such that subsequent calls to FormItem.getValue or DynamicForm.getValue will return the new value for this item.

For canvasItems that manipulate values and display them in some arbitrary canvas representation developers should call this method when the user interacts with the embedded canvas in a way that modifies the value for the item.

If you cannot easily detect changes to values in your Canvas, a workaround is to call storeValue right before the form saves.

Parameters:

value - value to save for this item

storeValue

public void storeValue(RecordList value)

Store a value for this form item. This method will fire standard FormItem.change and FormItem.changed handlers, and store out the method passed in such that subsequent calls to FormItem.getValue or DynamicForm.getValue will return the new value for this item.

For canvasItems that manipulate values and display them in some arbitrary canvas representation developers should call this method when the user interacts with the embedded canvas in a way that modifies the value for the item.

If you cannot easily detect changes to values in your Canvas, a workaround is to call storeValue right before the form saves.

Parameters:

value - value to save for this item

setCanEditCriterionPredicate

public void setCanEditCriterionPredicate(FormItemCanEditCriterionPredicate predicate)

AdvancedCriteria objects may be edited via nested dynamicForms as described in CanvasItem.setCriterionGetter.

The default canEditCriterion() predicate is overridden to return true if this item's canvas is a DynamicForm, where the operator matches the operator of the criterion passed in and dynamicForm contains items where the registered FormItemCanEditCriterionPredicate's canEditCriterion method returns true for each sub-criterion in the object passed in.

Overrides:

setCanEditCriterionPredicate in class FormItem

Parameters:

predicate - the predicate to determine the form items that can edit the criterion in question

See Also:

FormItem.setCanEditCriterionPredicate, CriteriaEditing overview and related methods

setCriterionGetter

public void setCriterionGetter(FormItemCriterionGetter getter)

The standard formItem criteria editing APIs have been overridden in the canvasItem class to simplify the editing of complex AdvancedCriteria objects using nested DynamicForms.

The following pattern is supported without need for further modification:
A complex Advanced criteria object may have nested sub criteria using the "and" or "or" operators. For example:

  { _constructor:"AdvancedCriteria",
    operator:"and",
    criteria:[
       {fieldName:"field1", value:"value1", operator:"iContains"},
       {operator:"or", criteria:[
           {fieldName:"innerField1", value:"value1", operator:"equals"},
           {fieldName:"innerField2", value:"value2", operator:"iContains"}
        ]
       }
    ]
  }
  

To create a form capable of editing the above criteria without providing a custom FormItemCriterionGetter et al, you would create a form with 2 items. The 'field1' criterion could be edited by a simple form item such as a TextItem. The nested criteria ('innerField1' and 'innerField2') could be edited by a canvasItem whose canvas property was set to a DynamicForm showing items capable of editing the 2 inner criteria, and whose operator was specified as "or".
For example:

   isc.DynamicForm.create({
       items:[
           {name:"field1", type:"TextItem"},
           {name:"nestedItem", shouldSaveValue:true, type:"CanvasItem",
               canvas:isc.DynamicForm.create({
                   operator:"or",
                   items:[
                       {name:"innerField1", type:"TextItem", operator:"equals"},
                       {name:"innerField2", type:"TextItem"}
                   ]
               })
           }
       ]
   });
   

This form would be able to edit the above advanced criteria object via DynamicForm.setValuesAsCriteria. Edited values would be retrieved via DynamicForm.getValuesAsCriteria.

Note that the canvas item has shouldSaveValue set to true - this is required to ensure the nested form is actually passed the values to edit.

The default implementation of this method checks for this.canvas being specified as a dynamicForm, and in that case simply returns the result of DynamicForm.getValuesAsAdvancedCriteria on the inner form.

Note that this functionality may be entirely bypassed by setting editCriteriaInInnerForm to false. This flag is useful when defining a dynamicForm based canvasItem which is not intended for editing nested data -- for example if a standard atomic field value is being displayed in some custom way using a DynamicForm embedded in the item.

Overrides:

setCriterionGetter in class FormItem

Parameters:

getter - provides a method to get a criterion object based on this field's current edited value(s).

See Also:

FormItem.setCriterionGetter(com.smartgwt.client.widgets.form.FormItemCriterionGetter), CriteriaEditing overview and related methods

setCriterionSetter

public void setCriterionSetter(FormItemCriterionSetter setter)

Provide a setCriterion() implementation to display a Criterion object in this item for editing. The default implementation is overridden from FormItem.setCriterionSetter in order to support editing nested criteria using nested dynamicForms as described in CanvasItem.setCriterionGetter.

Implementation checks for this.canvas being specified as a DynamicForm, and applies criterion directly to the embedded form via setValuesAsCriteria().

Overrides:

setCriterionSetter in class FormItem

Parameters:

setter - provides a method to update this field with the edited criterion