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:

HasHandlers, HasBlurHandlers, HasChangedHandlers, HasChangeHandlers, HasClickHandlers, HasDoubleClickHandlers, HasFocusHandlers, HasIconClickHandlers, HasIconKeyPressHandlers, HasItemHoverHandlers, HasKeyDownHandlers, HasKeyPressHandlers, HasKeyUpHandlers, HasShowValueHandlers, HasTitleClickHandlers, HasTitleDoubleClickHandlers, HasTitleHoverHandlers

Direct Known Subclasses:

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

public class CanvasItem
extends FormItem
implements 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 values and no value will be saved when DynamicForm.saveData is called. This is appropriate if your Canvas does not participate in displaying or editing the values of the form and is embedded in the form for layout purposes only.

If you set shouldSaveValue:true, CanvasItem.showValue will be called to provide a value that your item should display. Implement showValue() and call methods on the Canvas you've created to cause the value to be displayed.

showValue() will be called 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 showValue() 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 CanvasItem.storeValue whenever the user changes the value in your Canvas. Note that the form will not call canvasItem.getValue() in order to discover your item's value, so there is no purpose in overriding this method - use storeValue to proactively inform the form about changes instead. 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.

Field Summary

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

jsObj

Constructor Summary

CanvasItem()

CanvasItem(JavaScriptObject jsObj)

CanvasItem(String name)

CanvasItem(String name, String title)

Method Summary

HandlerRegistration	addShowValueHandler(ShowValueHandler handler) Add a showValue handler.
Boolean	canEditCriterion(Criterion criterion) AdvancedCriteria objects may be edited via nested dynamicForms as described in CanvasItem.getCriterion
protected Canvas	createCanvas() This method is called to dynamically create a canvas for this CanvasItem.
Boolean	getApplyPromptToCanvas() If prompt is specified for this item, should the prompt be applied to the canvas for this item?
Canvas	getCanvas() The canvas that will be displayed inside this item.
Criterion	getCriterion() The standard formItem criteria editing APIs have been overridden in the canvasItem class to simplify the editing of complex AdvancedCriteria objects using nested DynamicForms.
Boolean	getEditCriteriaInInnerForm() Flag to disable the criteria editing overrides described in CanvasItem.getCriterion whereby if this item contains a DynamicForm as its canvas, it will be used to edit nested AdvancedCriteria automatically.
static CanvasItem	getOrCreateRef(JavaScriptObject jsObj)
Overflow	getOverflow() CanvasItems support specifying overflow for the Canvas directly on the item.
String	getPrompt() This text is shown as a tooltip prompt when the cursor hovers over this item.
Boolean	getShouldSaveValue() Should this item's value be saved in the form's values and hence returned from form.getValues()?
Boolean	hasAdvancedCriteria() Overridden to return true if canvas is a dynamicForm.
void	setApplyPromptToCanvas(Boolean applyPromptToCanvas) If prompt is specified for this item, should the prompt be applied to the canvas for this item?
void	setCanvas(Canvas canvas) The canvas that will be displayed inside this item.
void	setCriterion(Criterion criterion) Display a Criterion object in this item for editing.
void	setEditCriteriaInInnerForm(Boolean editCriteriaInInnerForm) Flag to disable the criteria editing overrides described in CanvasItem.getCriterion whereby if this item contains a DynamicForm as its canvas, it will be used to edit nested AdvancedCriteria automatically.
void	setOverflow(Overflow overflow) CanvasItems support specifying overflow for the Canvas directly on the item.
void	setPrompt(String prompt) This text is shown as a tooltip prompt when the cursor hovers over this item.
void	setShouldSaveValue(Boolean shouldSaveValue) Should this item's value be saved in the form's values and hence returned from form.getValues()?
protected void	setupCanvasConstructor()
void	storeValue(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.

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

addBlurHandler, addChangedHandler, addChangeHandler, addClickHandler, addDoubleClickHandler, addFocusHandler, addIconClickHandler, addIconKeyPressHandler, addItemHoverHandler, addKeyDownHandler, addKeyPressHandler, addKeyUpHandler, addTitleClickHandler, addTitleDoubleClickHandler, addTitleHoverHandler, blurItem, clearValue, disable, enable, focusInItem, getAccessKey, getAlign, getAllowExpressions, getAlwaysFetchMissingValues, getAttribute, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsFloat, getAttributeAsInt, getAttributeAsJavaScriptObject, getAttributeAsString, getBrowserSpellCheck, getCanEdit, getCanFocus, getCellHeight, getCellStyle, getConfig, getContainerWidget, getCriteriaField, getCriterion, getDataPath, getDateFormatter, getDefaultIconSrc, getDisabled, getDisplayField, getDisplayFieldName, getDisplayValue, getDisplayValue, getEditorTypeConfig, getEmptyDisplayValue, getEmptyValueIcon, getEndRow, getErrorIconHeight, getErrorIconSrc, getErrorIconWidth, getErrorMessageWidth, getFetchMissingValues, getFieldName, getFilterLocally, getForm, getFullDataPath, getGlobalTabIndex, getHeight, getHint, getHintStyle, getHoverAlign, getHoverDelay, getHoverHeight, getHoverOpacity, getHoverStyle, getHoverVAlign, getHoverWidth, getIcon, getIconHeight, getIconPageRect, getIconPrompt, getIconRect, getIconVAlign, getIconWidth, getImageURLPrefix, getImageURLSuffix, getImplicitSave, getImplicitSaveOnBlur, getInputFormat, getLeft, getLocateItemBy, getMultipleValueSeparator, getName, getOperator, getOptionCriteria, getOptionFilterContext, getOptionOperationId, getPageLeft, getPageRect, getPageTop, getPickerIconHeight, getPickerIconName, getPickerIconSrc, getPickerIconWidth, getPrintTextBoxStyle, getPrintTitleStyle, getRect, getRejectInvalidValueOnChange, getRequired, getRequiredMessage, getRowSpan, getSelectedRecord, getSelectOnFocus, getShowDisabled, getShowErrorIcon, getShowErrorStyle, getShowErrorText, getShowFocused, getShowFocusedIcons, getShowFocusedPickerIcon, getShowHint, getShowIcons, getShowOverIcons, getShowPickerIcon, getShowTitle, getShowValueIconOnly, getStartRow, getStopOnError, getSuppressValueIcon, getSynchronousValidation, getTabIndex, getTextAlign, getTextBoxStyle, getTimeFormatter, getTitle, getTitleAlign, getTitleColSpan, getTitleOrientation, getTitleStyle, getTitleVAlign, getTooltip, getTop, getType, getValidateOnChange, getValidateOnExit, getValidOperators, getVAlign, getValue, getValueField, getValueFieldName, getValueIconHeight, getValueIconLeftPadding, getValueIconRightPadding, getValueIconSize, getValueIconWidth, getVisible, getVisibleHeight, getVisibleWidth, getWidth, getWrapTitle, hide, invalidateDisplayValueCache, isCreated, isDisabled, isDrawn, isVisible, redraw, setAccessKey, setAlign, setAllowExpressions, setAlwaysFetchMissingValues, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setBrowserSpellCheck, setCanEdit, setCanFocus, setCellHeight, setCellStyle, setColSpan, setColSpan, setCriteriaField, setDataPath, setDateFormatter, setDefaultIconSrc, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDisabled, setDisplayField, setDisplayFormat, setDisplayFormat, setEditorType, setEditorValueFormatter, setEditorValueParser, setEmptyDisplayValue, setEmptyValueIcon, setEndRow, setErrorFormatter, setErrorIconHeight, setErrorIconSrc, setErrorIconWidth, setErrorMessageWidth, setErrorOrientation, setFetchMissingValues, setFilterLocally, setGlobalTabIndex, setHeight, setHeight, setHint, setHintStyle, setHoverAlign, setHoverDelay, setHoverHeight, setHoverOpacity, setHoverStyle, setHoverVAlign, setHoverWidth, setIconHeight, setIconPrompt, setIcons, setIconVAlign, setIconWidth, setImageURLPrefix, setImageURLSuffix, setImplicitSave, setImplicitSaveOnBlur, setInitHandler, setInputFormat, setInputTransformer, setItemHoverFormatter, setItemTitleHoverFormatter, setLeft, setLocateItemBy, setMultipleValueSeparator, setName, setOperator, setOptionCriteria, setOptionDataSource, setOptionFilterContext, setOptionOperationId, setPickerIconHeight, setPickerIconName, setPickerIconSrc, setPickerIconWidth, setPrintTextBoxStyle, setPrintTitleStyle, setProperty, setProperty, setProperty, setProperty, setProperty, setRedrawOnChange, setRejectInvalidValueOnChange, setRequired, setRequiredMessage, setRowSpan, setSelectOnFocus, setShowDisabled, setShowErrorIcon, setShowErrorStyle, setShowErrorText, setShowFocused, setShowFocusedIcons, setShowFocusedPickerIcon, setShowHint, setShowIcons, setShowIfCondition, setShowOverIcons, setShowPickerIcon, setShowTitle, setShowValueIconOnly, setStartRow, setStopOnError, setSuppressValueIcon, setSynchronousValidation, setTabIndex, setTextAlign, setTextBoxStyle, setTimeFormatter, setTitle, setTitleAlign, setTitleColSpan, setTitleOrientation, setTitleStyle, setTitleVAlign, setTooltip, setTop, setType, setValidateOnChange, setValidateOnExit, setValidators, setValidOperators, setVAlign, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValueField, setValueFormatter, setValueIconHeight, setValueIconLeftPadding, setValueIconMapper, setValueIconRightPadding, setValueIcons, setValueIconSize, setValueIconWidth, setValueMap, setValueMap, setVisible, setWidth, setWidth, setWrapTitle, shouldFetchMissingValue, show, showPicker, stopHover, updateState, validate

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

getRef, getRef

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

doAddHandler, fireEvent, getAttributeAsDoubleArray, getAttributeAsIntArray, getAttributeAsLong, getAttributeAsMap, getAttributeAsObject, getAttributeAsRecord, getAttributeAsStringArray, getAttributes, getHandlerCount, getJsObj, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute

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

setJsObj

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, 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(JavaScriptObject jsObj)

CanvasItem

public CanvasItem(String name)

CanvasItem

public CanvasItem(String name,
                  String title)

Method Detail

getOrCreateRef

public static CanvasItem getOrCreateRef(JavaScriptObject jsObj)

setApplyPromptToCanvas

public void setApplyPromptToCanvas(Boolean applyPromptToCanvas)

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

Parameters:

applyPromptToCanvas - applyPromptToCanvas Default value is true

getApplyPromptToCanvas

public Boolean getApplyPromptToCanvas()

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

Returns:

Boolean

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. You can also implement CanvasItem.createCanvas to dynamically create the canvas when the FormItem is initialized.

If canvas and createCanvas() are unspecified, the canvas for this item will be auto-created using the overrideable defaults: canvasProperties and canvasConstructor

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

Parameters:

canvas - canvas 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. You can also implement CanvasItem.createCanvas to dynamically create the canvas when the FormItem is initialized.

If canvas and createCanvas() are unspecified, the canvas for this item will be auto-created using the overrideable defaults: canvasProperties and canvasConstructor

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

Returns:

Canvas

setEditCriteriaInInnerForm

public void setEditCriteriaInInnerForm(Boolean editCriteriaInInnerForm)

Flag to disable the criteria editing overrides described in CanvasItem.getCriterion 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 - editCriteriaInInnerForm Default value is true

getEditCriteriaInInnerForm

public Boolean getEditCriteriaInInnerForm()

Flag to disable the criteria editing overrides described in CanvasItem.getCriterion 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:

Boolean

setOverflow

public void setOverflow(Overflow overflow)

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

Parameters:

overflow - overflow Default value is null

getOverflow

public Overflow getOverflow()

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

Returns:

Overflow

setPrompt

public void setPrompt(String prompt)

This text is shown as a tooltip prompt when the cursor hovers over this item.

If this method is called after the component has been drawn/initialized: Set the 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:

Basics overview and related methods

getPrompt

public String getPrompt()

This text is shown as a tooltip prompt when the cursor hovers over this item.

Overrides:

getPrompt in class FormItem

Returns:

String

See Also:

Basics overview and related methods

setShouldSaveValue

public void setShouldSaveValue(Boolean shouldSaveValue)

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

See the CanvasItem class overview for a discussion of values-handling in CanvasItems

Overrides:

setShouldSaveValue in class FormItem

Parameters:

shouldSaveValue - shouldSaveValue Default value is false

getShouldSaveValue

public Boolean getShouldSaveValue()

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

See the CanvasItem class overview for a discussion of values-handling in CanvasItems

Overrides:

getShouldSaveValue in class FormItem

Returns:

Boolean

canEditCriterion

public Boolean canEditCriterion(Criterion criterion)

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

This method has been 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 FormItem.canEditCriterion returns true for each sub-criterion in the object passed in.

Overrides:

canEditCriterion in class FormItem

Parameters:

criterion - criteria to test

Returns:

returns true if the specified criterion may be edited by this item

See Also:

CriteriaEditing overview and related methods

getCriterion

public Criterion getCriterion()

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 custom overrides to FormItem.getCriterion 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:

getCriterion in class FormItem

Returns:

criterion to merge with advanced criteria returned by DynamicForm.getValuesAsCriteria

See Also:

CriteriaEditing overview and related methods

hasAdvancedCriteria

public Boolean hasAdvancedCriteria()

Overridden to return true if canvas is a dynamicForm. See CanvasItem.getCriterion 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

setCriterion

public void setCriterion(Criterion criterion)

Display a Criterion object in this item for editing. Overridden from FormItem.setCriterion in order to support editing nested criteria using nested dynamicForms as described in CanvasItem.getCriterion.

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

Overrides:

setCriterion in class FormItem

Parameters:

criterion - criteria to edit

addShowValueHandler

public HandlerRegistration addShowValueHandler(ShowValueHandler handler)

Add a showValue handler.

This method will be called whenever this form item'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.

Specified by:

addShowValueHandler in interface HasShowValueHandlers

Parameters:

handler - the showValue handler

Returns:

HandlerRegistration used to remove this handler

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

storeValue

public void storeValue(Object 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(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