Class CanvasItem
- All Implemented Interfaces:
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
,ShuttleItem
,SliderItem
,ToggleItem
,ToolbarItem
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
-
Constructor Summary
ConstructorDescriptionCanvasItem
(JavaScriptObject jsObj) CanvasItem
(String name) CanvasItem
(String name, String title) -
Method Summary
Modifier and TypeMethodDescriptionAdd a canEditChanged handler.Add a readOnlyDisplayChanged handler.addShowValueHandler
(ShowValueHandler handler) Add a showValue handler.static void
changeAutoChildDefaults
(String autoChildName, Canvas defaults) Changes the defaults for Canvas AutoChildren namedautoChildName
.static void
changeAutoChildDefaults
(String autoChildName, FormItem defaults) Changes the defaults for FormItem AutoChildren namedautoChildName
.static void
changePickerIconDefaults
(FormItemIcon defaults) protected Canvas
This method is called to dynamically create a canvas for this CanvasItem.IfFormItem.prompt
is specified for this item, should the prompt be applied to thecanvas
for this item?Should this item'scanvas
be automatically destroyed when the item is destroyed? Form items are destroyed automatically when a call toDynamicForm.setItems()
removes them from their parent form, or if their parent form is destroyed.The canvas that will be displayed inside this item.Flag to disable the criteria editing overrides described insetCriterionGetter()
whereby if this item contains a DynamicForm as its canvas, it will be used to edit nested AdvancedCriteria automatically.int
Height of the Canvas.Height of the Canvas.Maximum valid height for this CanvasItem in pixels.Minimum valid height for this CanvasItem in pixels.Whether this CanvasItem is intended to hold multiple values.static CanvasItem
getOrCreateRef
(JavaScriptObject jsObj) CanvasItems support specifying overflow for the Canvas directly on the item.This text is shown as a tooltip prompt when the cursor hovers over this item.Should this item's value be saved in the form's values and hence returned fromDynamicForm.getValues()
?Overridden to return true ifcanvas
is a dynamicForm.Does this CanvasItem have keyboard focus.setApplyPromptToCanvas
(Boolean applyPromptToCanvas) IfFormItem.prompt
is specified for this item, should the prompt be applied to thecanvas
for this item?setAutoDestroy
(Boolean autoDestroy) Should this item'scanvas
be automatically destroyed when the item is destroyed? Form items are destroyed automatically when a call toDynamicForm.setItems()
removes them from their parent form, or if their parent form is destroyed.void
AdvancedCriteria objects may be edited via nested dynamicForms as described inCanvasItem.setCriterionGetter
.The canvas that will be displayed inside this item.void
The standard formItem criteria editing APIs have been overridden in the canvasItem class to simplify the editing of complexAdvancedCriteria
objects using nested DynamicForms.void
Provide asetCriterion()
implementation to display aCriterion
object in this item for editing.static void
setDefaultProperties
(CanvasItem canvasItemProperties) Class level method to set the default properties of this class.setEditCriteriaInInnerForm
(Boolean editCriteriaInInnerForm) Flag to disable the criteria editing overrides described insetCriterionGetter()
whereby if this item contains a DynamicForm as its canvas, it will be used to edit nested AdvancedCriteria automatically.setHeight
(int height) Height of the Canvas.Height of the Canvas.setMaxHeight
(Integer maxHeight) Maximum valid height for this CanvasItem in pixels.setMinHeight
(Integer minHeight) Minimum valid height for this CanvasItem in pixels.setMultiple
(Boolean multiple) Whether this CanvasItem is intended to hold multiple values.setOverflow
(Overflow overflow) CanvasItems support specifying overflow for the Canvas directly on the item.This text is shown as a tooltip prompt when the cursor hovers over this item.void
Sets theShouldDisableCanvasCustomizer
that is called to determine whether thecanvas
should bedisabled
when thisCanvasItem
is disabled or itseditability changes
.setShouldSaveValue
(Boolean shouldSaveValue) Should this item's value be saved in the form's values and hence returned fromDynamicForm.getValues()
?protected void
void
storeValue
(Record value) Store a value for this form item.void
storeValue
(RecordList value) Store a value for this form item.void
storeValue
(Object value) Store a value for this form item.void
This method will place an entry for thecanvas
under this item in theTabIndexManager
.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, checkFormItemType, 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, getCanHover, getCanSelectText, getCanTabToIcons, getCanvasAutoChild, getCellHeight, getCellStyle, getChangeOnKeypress, getClassName, getClipStaticValue, getClipTitle, getConfig, getContainerWidget, getControlStyle, getCriteriaField, getCriterion, getCriterion, getCursorPosition, getCustomState, getDataPath, getDateFormatter, getDecimalPad, getDecimalPrecision, getDefaultIconSrc, getDefaultOperator, getDefaultValue, getDestroyed, getDisabled, getDisabledHover, getDisableIconsOnReadOnly, getDisplayField, getDisplayFieldName, getDisplayValue, getDisplayValue, getEditorTypeConfig, getEditPendingCSSText, getEditProxyConstructor, getEmptyDisplayValue, getEmptyValueIcon, getEndRow, getErrorIconHeight, getErrorIconProperties, getErrorIconSrc, getErrorIconWidth, getErrorMessageWidth, getErrors, getEscapeHTML, getExportFormat, getFetchMissingValues, getFieldName, getFilterLocally, getForeignDisplayField, getForm, getFormat, getFormItemAutoChild, getFormula, getFullDataPath, getGlobalTabIndex, getGridColNum, getGridRowNum, getHidden, getHint, getHintStyle, getHoverAlign, getHoverDelay, getHoverFocusKey, getHoverHeight, getHoverHeightAsString, getHoverOpacity, getHoverPersist, getHoverStyle, getHoverVAlign, getHoverWidth, getHoverWidthAsString, getIcon, getIconBaseStyle, getIconHeight, getIconHSpace, getIconPageRect, getIconPrompt, getIconRect, getIcons, getIconTabPosition, getIconVAlign, getIconWidth, getID, getImageURLPrefix, getImageURLSuffix, getImplicitSave, getImplicitSaveOnBlur, getInputFormat, getLeft, getLinearColSpan, getLinearColSpanAsString, getLinearEndRow, getLinearEndRowAsString, getLinearStartRow, getLinearStartRowAsString, getLinearWidth, getLinearWidthAsString, getListGrid, getLoadingDisplayValue, getLocateItemBy, getMinHintWidth, getMultipleValueSeparator, getName, getNullOriginalValueText, getOperator, getOptionCriteria, getOptionDataSource, getOptionDataSourceAsString, getOptionFilterContext, getOptionOperationId, getOptionTextMatchStyle, getOriginalValueMessage, getPageLeft, getPageRect, getPageTop, getPaletteDefaults, getPicker, getPickerIcon, getPickerIcon, getPickerIconHeight, getPickerIconName, getPickerIconPrompt, getPickerIconProperties, getPickerIconSrc, getPickerIconStyle, getPickerIconTabPosition, getPickerIconWidth, getPixelHeight, getPixelWidth, getPrintReadOnlyTextBoxStyle, getPrintTextBoxStyle, getPrintTitleStyle, getReadOnlyCanSelectText, getReadOnlyControlStyle, getReadOnlyDisplay, getReadOnlyHover, getReadOnlyTextBoxStyle, getReadOnlyWhen, getRect, getRedrawOnChange, getRejectInvalidValueOnChange, getRequired, getRequiredMessage, getRequiredWhen, getRowSpan, getSaveOnEnter, getScClassName, getSelectedRecord, getSelectOnClick, getSelectOnFocus, getShowClippedTitleOnHover, getShowClippedValueOnHover, getShowDeletions, getShowDisabled, getShowDisabledIconsOnFocus, getShowDisabledPickerIconOnFocus, getShowErrorIcon, getShowErrorIconInline, getShowErrorStyle, getShowErrorText, getShowFocused, getShowFocusedErrorState, getShowFocusedIcons, getShowFocusedPickerIcon, getShowHint, getShowIcons, getShowIconsOnFocus, getShowImageAsURL, getShowOldValueInHover, getShowOver, getShowOverIcons, getShowPending, getShowPickerIcon, getShowPickerIconOnFocus, getShowRTL, getShowTitle, getShowValueIconOnly, getStartRow, getStaticHeight, getStopOnError, getStoreDisplayValues, 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, getValueAsFloat, getValueAsInteger, getValueAsLong, getValueAsRecordList, getValueDeselectedCSSText, getValueField, getValueFieldName, getValueIconHeight, getValueIconLeftPadding, getValueIconRightPadding, getValueIconSize, getValueIconWidth, getValueMap, getValueMapAsArray, getVisible, getVisibleHeight, getVisibleTitleWidth, getVisibleWhen, getVisibleWidth, getWarnOnEditorTypeConversion, getWarnOnEditorTypeConversionDefault, getWidth, getWidthAsString, getWrapHintText, getWrapStaticValue, getWrapTitle, handleWarnOnEditorTypeConversion, hasErrors, hide, hideIcon, invalidateDisplayValueCache, isAssignableFrom, isConfigOnly, isCreated, isCutEvent, isDisabled, isDrawn, isInGrid, isPasteEvent, isVisible, linkToInstanceUponCreate, mapDisplayToValue, mapValueToDisplay, mapValueToDisplay, mapValueToDisplay, redraw, redraw, removeIcon, selectedRecordChanged, 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, setCanHover, setCanSelectText, setCanTabToIcons, setCellHeight, setCellStyle, setChangeOnKeypress, setClipStaticValue, setClipTitle, setColSpan, setColSpan, setConfigOnly, setControlStyle, setCriteriaField, setCriterion, setCustomStateGetter, setDataPath, setDateFormatter, setDecimalPad, setDecimalPrecision, setDefaultIconSrc, setDefaultOperator, setDefaultProperties, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDisabled, setDisabledHover, setDisableIconsOnReadOnly, setDisplayField, setDisplayFormat, setDisplayFormat, setEditorProperties, setEditorType, setEditorType, setEditorType, setEditorValueFormatter, setEditorValueParser, setEditPendingCSSText, setEditProxyConstructor, setEmptyDisplayValue, setEmptyValueIcon, setEndRow, setErrorFormatter, setErrorIconHeight, setErrorIconProperties, setErrorIconSrc, setErrorIconWidth, setErrorMessageWidth, setErrorOrientation, setErrors, setErrors, setEscapeHTML, setExportFormat, setFetchMissingValues, setFilterLocally, setForeignDisplayField, setFormat, setFormula, setGlobalTabIndex, setHidden, setHint, setHintStyle, setHoverAlign, setHoverDelay, setHoverFocusKey, setHoverHeight, setHoverHeight, setHoverOpacity, setHoverPersist, setHoverStyle, setHoverVAlign, setHoverWidth, setHoverWidth, setIconBaseStyle, setIconDisabled, setIconHeight, setIconHSpace, setIconPrompt, setIcons, setIconShowOnFocus, setIconVAlign, setIconWidth, setID, setImageURLPrefix, setImageURLSuffix, setImplicitSave, setImplicitSaveOnBlur, setInitHandler, setInputFormat, setInputTransformer, setItemHoverFormatter, setItemTitleHoverFormatter, setItemValueHoverFormatter, setJavaScriptObject, setLeft, setLinearColSpan, setLinearColSpan, setLinearEndRow, setLinearEndRow, setLinearStartRow, setLinearStartRow, setLinearWidth, setLinearWidth, setLoadingDisplayValue, setLocateItemBy, setMinHintWidth, setMultipleValueSeparator, setName, setNullOriginalValueText, setNullProperty, setOperator, setOptionCriteria, setOptionDataSource, setOptionDataSource, setOptionFilterContext, setOptionOperationId, setOptionTextMatchStyle, setOriginalValueMessage, setPickerIconHeight, setPickerIconName, setPickerIconPrompt, setPickerIconProperties, setPickerIconSrc, setPickerIconStyle, setPickerIconWidth, setPrintReadOnlyTextBoxStyle, setPrintTextBoxStyle, setPrintTitleStyle, setProperty, setProperty, setProperty, setProperty, setProperty, setReadOnlyCanSelectText, setReadOnlyControlStyle, setReadOnlyDisplay, setReadOnlyHover, setReadOnlyTextBoxStyle, setReadOnlyWhen, setRedrawOnChange, setRejectInvalidValueOnChange, setRequired, setRequiredMessage, setRequiredWhen, setRowSpan, setSaveOnEnter, setScClassName, setSelectOnClick, setSelectOnFocus, setShowClippedTitleOnHover, setShowClippedValueOnHover, setShowDeletions, setShowDisabled, setShowDisabledIconsOnFocus, setShowDisabledPickerIconOnFocus, setShowErrorIcon, setShowErrorIconInline, setShowErrorStyle, setShowErrorText, setShowFocused, setShowFocusedErrorState, setShowFocusedIcons, setShowFocusedPickerIcon, setShowHint, setShowIcons, setShowIconsOnFocus, setShowIfCondition, setShowImageAsURL, setShowOldValueInHover, setShowOver, setShowOverIcons, setShowPending, setShowPickerIcon, setShowPickerIconOnFocus, setShowRTL, setShowTitle, setShowValueIconOnly, setStartRow, setStateCustomizer, setStaticHeight, setStopOnError, setStoreDisplayValues, setSupportsCutPasteEvents, setSuppressValueIcon, setSynchronousValidation, setTabIndex, setTextAlign, setTextBoxStyle, setTextFormula, setTimeFormatter, setTitle, setTitleAlign, setTitleColSpan, setTitleHoverFormatter, setTitleOrientation, setTitleStyle, setTitleVAlign, setTooltip, setTop, setType, setUpdateControlOnOver, setUpdatePickerIconOnOver, setUpdateTextBoxOnOver, setUseAdvancedCriteria, setUseDisabledHintStyleForReadOnly, setUseLocalDisplayFieldValue, setUseObjectFactoryForTypeFallback, 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, setWrapStaticValue, setWrapTitle, shouldApplyHeightToTextBox, shouldFetchMissingValue, shouldSaveOnEnter, shouldStopKeyPressBubbling, show, showIcon, showPicker, stopHover, storeValue, updateState, validate, valueClipped
Methods inherited from class com.smartgwt.client.data.Field
getCanExport, getExportTitle, getSortByField, setCanExport, setExportTitle, setSortByField
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, getAttributeAsElement, getAttributeAsIntArray, getAttributeAsLong, getAttributeAsMap, getAttributeAsObject, getAttributeAsRecord, getAttributeAsStringArray, getAttributes, getHandlerCount, isFactoryCreated, setAttribute, setAttribute, setAttribute, setAttributeAsJavaObject, setFactoryCreated
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 Details
-
CanvasItem
public CanvasItem() -
CanvasItem
-
CanvasItem
-
CanvasItem
-
-
Method Details
-
getOrCreateRef
-
changeAutoChildDefaults
Changes the defaults for Canvas AutoChildren namedautoChildName
.- 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, seeSGWTProperties
.- See Also:
-
changeAutoChildDefaults
Changes the defaults for FormItem AutoChildren namedautoChildName
.- 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, seeSGWTProperties
.- See Also:
-
changePickerIconDefaults
-
setApplyPromptToCanvas
IfFormItem.prompt
is specified for this item, should the prompt be applied to thecanvas
for this item?- Parameters:
applyPromptToCanvas
- New applyPromptToCanvas value. Default value is true- Returns:
CanvasItem
instance, for chaining setter calls
-
getApplyPromptToCanvas
IfFormItem.prompt
is specified for this item, should the prompt be applied to thecanvas
for this item?- Returns:
- Current applyPromptToCanvas value. Default value is true
-
setAutoDestroy
Should this item'scanvas
be automatically destroyed when the item is destroyed? Form items are destroyed automatically when a call toDynamicForm.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 bedestroyed
.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 explicitsetCanvas()
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- Returns:
CanvasItem
instance, for chaining setter calls
-
getAutoDestroy
Should this item'scanvas
be automatically destroyed when the item is destroyed? Form items are destroyed automatically when a call toDynamicForm.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 bedestroyed
.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 explicitsetCanvas()
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
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 viasetCanvas()
, the canvas for this item will be auto-created as configured by the methodssetAutoChildProperties()
andsetAutoChildConstructor()
.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 thecanvas
at runtime- Parameters:
canvas
- New canvas to display. Default value is null- Returns:
CanvasItem
instance, for chaining setter calls
-
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 viasetCanvas()
, the canvas for this item will be auto-created as configured by the methodssetAutoChildProperties()
andsetAutoChildConstructor()
.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
Flag to disable the criteria editing overrides described insetCriterionGetter()
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- Returns:
CanvasItem
instance, for chaining setter calls
-
getEditCriteriaInInnerForm
Flag to disable the criteria editing overrides described insetCriterionGetter()
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
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 theFormLayout
overview for details.Height may also be explicitly specified on the
canvas
. In this anycanvasItem.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 inFormLayout
- Overrides:
setHeight
in classFormItem
- Parameters:
height
- New height value. Default value is null- Returns:
CanvasItem
instance, for chaining setter calls- See Also:
-
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 theFormLayout
overview for details.Height may also be explicitly specified on the
canvas
. In this anycanvasItem.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 inFormLayout
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. -
setHeight
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 theFormLayout
overview for details.Height may also be explicitly specified on the
canvas
. In this anycanvasItem.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 inFormLayout
- Overrides:
setHeight
in classFormItem
- Parameters:
height
- New height value. Default value is null- Returns:
CanvasItem
instance, for chaining setter calls- See Also:
-
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 theFormLayout
overview for details.Height may also be explicitly specified on the
canvas
. In this anycanvasItem.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 inFormLayout
- Overrides:
getHeightAsString
in classFormItem
- Returns:
- Current height value. Default value is null
- See Also:
-
setMaxHeight
Maximum valid height for this CanvasItem in pixels. Used in calculating the row heights of the containingDynamicForm
if the item has a flexibleheight
.- Parameters:
maxHeight
- New maxHeight value. Default value is null- Returns:
CanvasItem
instance, for chaining setter calls
-
getMaxHeight
Maximum valid height for this CanvasItem in pixels. Used in calculating the row heights of the containingDynamicForm
if the item has a flexibleheight
.- Returns:
- Current maxHeight value. Default value is null
-
setMinHeight
Minimum valid height for this CanvasItem in pixels. Used in calculating the row heights of the containingDynamicForm
if the item has a flexibleheight
.- Parameters:
minHeight
- New minHeight value. Default value is null- Returns:
CanvasItem
instance, for chaining setter calls
-
getMinHeight
Minimum valid height for this CanvasItem in pixels. Used in calculating the row heights of the containingDynamicForm
if the item has a flexibleheight
.- Returns:
- Current minHeight value. Default value is null
-
setMultiple
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 eitherList
orRecordList
.- Overrides:
setMultiple
in classFormItem
- Parameters:
multiple
- New multiple value. Default value is false- Returns:
CanvasItem
instance, for chaining setter calls- See Also:
-
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 eitherList
orRecordList
.- Overrides:
getMultiple
in classFormItem
- Returns:
- Current multiple value. Default value is false
- See Also:
-
setOverflow
CanvasItems support specifying overflow for the Canvas directly on the item.- Parameters:
overflow
- New overflow value. Default value is null- Returns:
CanvasItem
instance, for chaining setter calls
-
getOverflow
CanvasItems support specifying overflow for the Canvas directly on the item.- Returns:
- Current overflow value. Default value is null
-
setPrompt
This text is shown as a tooltip prompt when the cursor hovers over this item.When the item is
read-only
a different hover can be shown withFormItem.readOnlyHover
. Or, when the item isdisabled
or read-only withreadOnlyDisplay:disabled
a different hover can be shown withFormItem.disabledHover
.Note that when the form is
disabled
, or when this itemsuppresses hovers
, this prompt will not be shown.
If this method is called after the component has been drawn/initialized: Set theFormItem.prompt
for this item. Default implementation will also apply the prompt tocanvas
ifapplyPromptToCanvas
is true.- Overrides:
setPrompt
in classFormItem
- Parameters:
prompt
- new prompt for the item. Default value is null- Returns:
CanvasItem
instance, for chaining setter calls- See Also:
-
getPrompt
This text is shown as a tooltip prompt when the cursor hovers over this item.When the item is
read-only
a different hover can be shown withFormItem.readOnlyHover
. Or, when the item isdisabled
or read-only withreadOnlyDisplay:disabled
a different hover can be shown withFormItem.disabledHover
.Note that when the form is
disabled
, or when this itemsuppresses hovers
, this prompt will not be shown. -
setShouldSaveValue
Should this item's value be saved in the form's values and hence returned fromDynamicForm.getValues()
?Note that by default,
shouldSaveValue
is false for CanvasItems, meaning that no value from the CanvasItem will be present inDynamicForm.getValues()
and no value for the CanvasItem will be saved whenDynamicForm.saveData()
is called. See theCanvasItem
class overview for a discussion of values handling in CanvasItems.- Overrides:
setShouldSaveValue
in classFormItem
- Parameters:
shouldSaveValue
- New shouldSaveValue value. Default value is false- Returns:
CanvasItem
instance, for chaining setter calls
-
getShouldSaveValue
Should this item's value be saved in the form's values and hence returned fromDynamicForm.getValues()
?Note that by default,
shouldSaveValue
is false for CanvasItems, meaning that no value from the CanvasItem will be present inDynamicForm.getValues()
and no value for the CanvasItem will be saved whenDynamicForm.saveData()
is called. See theCanvasItem
class overview for a discussion of values handling in CanvasItems.- Overrides:
getShouldSaveValue
in classFormItem
- Returns:
- Current shouldSaveValue value. Default value is false
-
addCanEditChangedHandler
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 thecanvas
.The default behavior is:
- If
canvas
is aDynamicForm
, the form'sDynamicForm.canEdit
setting is set tocanEdit
. CanvasItem.shouldDisableCanvas()
is called to determine if thecanvas
should be disabled.
Standard
CanvasItem
-based form items may customize the default behavior. For example, aMultiComboBoxItem
will hide itscomboForm
if thereadOnlyDisplay
isReadOnlyDisplayAppearance.READONLY
orReadOnlyDisplayAppearance.STATIC
and also disable the buttons when made read-only.- Specified by:
addCanEditChangedHandler
in interfaceHasCanEditChangedHandlers
- Parameters:
handler
- the canEditChanged handler- Returns:
HandlerRegistration
used to remove this handler
- If
-
hasAdvancedCriteria
Overridden to return true ifcanvas
is a dynamicForm. SeesetCriterionGetter()
for details of editing advanced criteria using nested dynamicForms.- Overrides:
hasAdvancedCriteria
in classFormItem
- Returns:
- true if this item's canvas is a DynamicForm
- See Also:
-
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
-
addReadOnlyDisplayChangedHandler
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 thecanvas
.The default behavior is: when the
canvas
is aDynamicForm
, the form'sDynamicForm.readOnlyDisplay
setting is set toappearance
.Standard
CanvasItem
-based form items may customize the default behavior.- Specified by:
addReadOnlyDisplayChangedHandler
in interfaceHasReadOnlyDisplayChangedHandlers
- Parameters:
handler
- the readOnlyDisplayChanged handler- Returns:
HandlerRegistration
used to remove this handler
-
addShowValueHandler
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()
orFormItem.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 interfaceHasShowValueHandlers
- Parameters:
handler
- the showValue handler- Returns:
HandlerRegistration
used to remove this handler
-
updateCanvasTabPosition
public void updateCanvasTabPosition()This method will place an entry for thecanvas
under this item in theTabIndexManager
. This ensures the user can tab into the canvas (and its descendants) in the expected position within this item's DynamicForm.See also
DynamicForm.updateChildTabPositions()
. -
setDefaultProperties
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:
-
setupCanvasConstructor
protected void setupCanvasConstructor() -
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
Sets theShouldDisableCanvasCustomizer
that is called to determine whether thecanvas
should bedisabled
when thisCanvasItem
is disabled or itseditability changes
.Setting a
ShouldDisableCanvasCustomizer
is the Smart GWT equivalent of overriding theCanvasItem.shouldDisableCanvas()
method in SmartClient.- Parameters:
customizer
- theShouldDisableCanvasCustomizer
to use.
-
storeValue
Store a value for this form item.This method will fire standard
FormItem.change
andFormItem.changed
handlers, and store the value passed in such that subsequent calls toFormItem.getValue
orDynamicForm.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 classFormItem
- Parameters:
value
- value to save for this item- See Also:
-
storeValue
Store a value for this form item. This method will fire standardFormItem.change
andFormItem.changed
handlers, and store out the method passed in such that subsequent calls toFormItem.getValue
orDynamicForm.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
Store a value for this form item. This method will fire standardFormItem.change
andFormItem.changed
handlers, and store out the method passed in such that subsequent calls toFormItem.getValue
orDynamicForm.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
AdvancedCriteria objects may be edited via nested dynamicForms as described inCanvasItem.setCriterionGetter
.The default
canEditCriterion()
predicate is overridden to return true if this item's canvas is a DynamicForm, where theoperator
matches the operator of the criterion passed in and dynamicForm contains items where the registeredFormItemCanEditCriterionPredicate
'scanEditCriterion
method returns true for each sub-criterion in the object passed in.- Overrides:
setCanEditCriterionPredicate
in classFormItem
- Parameters:
predicate
- the predicate to determine the form items that can edit the criterion in question- See Also:
-
setCriterionGetter
The standard formItem criteria editing APIs have been overridden in the canvasItem class to simplify the editing of complexAdvancedCriteria
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:AdvancedCriteria criteria = new AdvancedCriteria(OperatorId.AND, new Criterion[] { new Criterion("field1", OperatorId.ICONTAINS, "value1"), new AdvancedCriteria(OperatorId.OR, new Criterion[] { new Criterion("innerField1", OperatorId.EQUALS, "value1"), new Criterion("innerField2", OperatorId.ICONTAINS, "value2") }) });
To create a form capable of editing the above criteria without providing a customFormItemCriterionGetter
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:DynamicForm form = new DynamicForm(); DynamicForm innerForm = new DynamicForm(); innerForm.setOperator(OperatorId.OR); TextItem innerField1 = new TextItem(); innerField1.setOperator(OperatorId.EQUALS); TextItem innerField2 = new TextItem(); innerForm.setFields(innerField1, innerField2); TextItem field1 = new TextItem(); CanvasItem nestedItem = new CanvasItem(); nestedItem.setShouldSaveValue(true); nestedItem.setCanvas(innerForm); form.setFields(field1, nestedItem);
This form would be able to edit the above advanced criteria object viaDynamicForm.setValuesAsCriteria
. Edited values would be retrieved viaDynamicForm.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 classFormItem
- Parameters:
getter
- provides a method to get a criterion object based on this field's current edited value(s).- See Also:
-
setCriterionSetter
Provide asetCriterion()
implementation to display aCriterion
object in this item for editing. The default implementation is overridden fromFormItem.setCriterionSetter
in order to support editing nested criteria using nested dynamicForms as described inCanvasItem.setCriterionGetter
.Implementation checks for this.canvas being specified as a DynamicForm, and applies criterion directly to the embedded form via setValuesAsCriteria().
- Overrides:
setCriterionSetter
in classFormItem
- Parameters:
setter
- provides a method to update this field with the edited criterion
-