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, HasPickerIconClickHandlers, HasShowValueHandlers, HasTitleClickHandlers, HasTitleDoubleClickHandlers, HasTitleHoverHandlers, HasValueHoverHandlers
  Direct Known Subclasses:
    ButtonItem, DateRangeItem, FileItem, MultiComboBoxItem, MultiFileItem, PickTreeItem, RelativeDateItem, RichTextItem, SectionItem, SliderItem, ToolbarItem, ViewFileItem

      public class CanvasItem
      extends FormItem
      implements HasCanEditChangedHandlers, 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.RefDataClass

      `id`

    - ### 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

    Methods
    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` | `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 `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.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 `form.getValues()`?
    `java.lang.Boolean` | `hasAdvancedCriteria()` Overridden to return true if `canvas` is a dynamicForm.
    `void` | `readOnlyDisplayChanged(ReadOnlyDisplayAppearance readOnlyDisplay)` Notification method called when `readOnlyDisplay` is modified.
    `void` | `setApplyPromptToCanvas(java.lang.Boolean applyPromptToCanvas)` If `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` | `setJavaScriptObject(com.google.gwt.core.client.JavaScriptObject jsObj)`
    `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` | `setShouldSaveValue(java.lang.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(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.

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

      `_getValue, addBlurHandler, addChangedHandler, addChangeHandler, addClickHandler, addDoubleClickHandler, addEditorEnterHandler, addEditorExitHandler, addFocusHandler, addIconClickHandler, addIconKeyPressHandler, addItemHoverHandler, addKeyDownHandler, addKeyPressHandler, addKeyUpHandler, addPickerIconClickHandler, addTitleClickHandler, addTitleDoubleClickHandler, addTitleHoverHandler, addValueHoverHandler, asSGWTComponent, blurItem, canEditCriterion, clearValue, disable, enable, focusInItem, getAccessKey, getAlign, getAllowExpressions, getAlwaysFetchMissingValues, getApplyHeightToTextBox, getAriaRole, getAttribute, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsFloat, getAttributeAsInt, getAttributeAsJavaScriptObject, getAttributeAsString, getBrowserSpellCheck, getCanEdit, getCanFocus, getCanvasAutoChild, getCellHeight, getCellStyle, getClassName, getClipStaticValue, getClipTitle, getConfig, getContainerWidget, getCriteriaField, getCriterion, getCriterion, getDataPath, getDateFormatter, getDecimalPad, getDecimalPrecision, getDefaultIconSrc, getDisabled, getDisableIconsOnReadOnly, getDisplayField, getDisplayFieldName, getDisplayValue, getDisplayValue, getEditorTypeConfig, getEditPendingCSSText, getEmptyDisplayValue, getEmptyValueIcon, getEndRow, getErrorIconHeight, getErrorIconSrc, getErrorIconWidth, getErrorMessageWidth, getFetchMissingValues, getFieldName, getFilterLocally, getForm, getFormItemAutoChild, getFullDataPath, getGlobalTabIndex, getHint, getHintStyle, getHoverAlign, getHoverDelay, getHoverHeight, getHoverOpacity, getHoverStyle, getHoverVAlign, getHoverWidth, getIcon, getIconHeight, getIconHSpace, getIconPageRect, getIconPrompt, getIconRect, getIconVAlign, getIconWidth, getImageURLPrefix, getImageURLSuffix, getImplicitSave, getImplicitSaveOnBlur, getInputFormat, getLeft, getLocateItemBy, getMultipleValueSeparator, getName, getOperator, getOptionCriteria, getOptionFilterContext, getOptionOperationId, getPageLeft, getPageRect, getPageTop, getPicker, getPickerIconHeight, getPickerIconName, getPickerIconPrompt, getPickerIconProperties, getPickerIconSrc, getPickerIconStyle, getPickerIconWidth, getPrintTextBoxStyle, getPrintTitleStyle, getReadOnlyDisplay, getReadOnlyTextBoxStyle, getRect, getRedrawOnChange, getRejectInvalidValueOnChange, getRequired, getRequiredMessage, getRowSpan, getSaveOnEnter, getSelectedRecord, getSelectOnClick, getSelectOnFocus, getShowClippedTitleOnHover, getShowClippedValueOnHover, getShowDisabled, getShowErrorIcon, getShowErrorStyle, getShowErrorText, getShowFocused, getShowFocusedErrorState, getShowFocusedIcons, getShowFocusedPickerIcon, getShowHint, getShowIcons, getShowOverIcons, getShowPickerIcon, getShowRTL, getShowTitle, getShowValueIconOnly, getStartRow, getStopOnError, getSuppressValueIcon, getSynchronousValidation, getTabIndex, getTextAlign, getTextBoxStyle, getTimeFormatter, getTitle, getTitleAlign, getTitleColSpan, getTitleOrientation, getTitleStyle, getTitleVAlign, getTooltip, getTop, getType, getValidateOnChange, getValidateOnExit, getValidOperators, getVAlign, getValue, getValueAsRecordList, getValueField, getValueFieldName, getValueIconHeight, getValueIconLeftPadding, getValueIconRightPadding, getValueIconSize, getValueIconWidth, getVisible, getVisibleHeight, getVisibleWidth, getWidth, getWrapTitle, hide, hideIcon, invalidateDisplayValueCache, isCreated, isDisabled, isDrawn, isVisible, redraw, setAccessKey, setAlign, setAllowExpressions, setAlwaysFetchMissingValues, setApplyHeightToTextBox, setAriaRole, setAriaState, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAutoChildConstructor, setAutoChildProperties, setAutoChildProperties, setAutoChildVisibility, setBrowserSpellCheck, setCanEdit, setCanFocus, setCellHeight, setCellStyle, setClipStaticValue, setClipTitle, setColSpan, setColSpan, setCriteriaField, setCriterion, 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, setEmptyDisplayValue, setEmptyValueIcon, setEndRow, setErrorFormatter, setErrorIconHeight, setErrorIconSrc, setErrorIconWidth, setErrorMessageWidth, setErrorOrientation, setFetchMissingValues, setFilterLocally, setGlobalTabIndex, setHeight, setHeight, setHint, setHintStyle, setHoverAlign, setHoverDelay, setHoverHeight, setHoverOpacity, setHoverStyle, setHoverVAlign, setHoverWidth, setIconHeight, setIconHSpace, setIconPrompt, setIcons, setIconVAlign, setIconWidth, setImageURLPrefix, setImageURLSuffix, setImplicitSave, setImplicitSaveOnBlur, setInitHandler, setInputFormat, setInputTransformer, setItemHoverFormatter, setItemTitleHoverFormatter, setItemValueHoverFormatter, setLeft, setLocateItemBy, setMultipleValueSeparator, setName, setOperator, setOptionCriteria, setOptionDataSource, setOptionFilterContext, setOptionOperationId, setPickerIconHeight, setPickerIconName, setPickerIconPrompt, setPickerIconProperties, setPickerIconSrc, setPickerIconStyle, setPickerIconWidth, setPrintTextBoxStyle, setPrintTitleStyle, setProperty, setProperty, setProperty, setProperty, setProperty, setReadOnlyDisplay, setReadOnlyTextBoxStyle, setRedrawOnChange, setRejectInvalidValueOnChange, setRequired, setRequiredMessage, setRowSpan, setSaveOnEnter, setSelectOnClick, setSelectOnFocus, setShowClippedTitleOnHover, setShowClippedValueOnHover, setShowDisabled, setShowErrorIcon, setShowErrorStyle, setShowErrorText, setShowFocused, setShowFocusedErrorState, setShowFocusedIcons, setShowFocusedPickerIcon, setShowHint, setShowIcons, setShowIfCondition, setShowOverIcons, setShowPickerIcon, setShowRTL, setShowTitle, setShowValueIconOnly, setStartRow, setStopOnError, setSuppressValueIcon, setSynchronousValidation, setTabIndex, setTextAlign, setTextBoxStyle, setTimeFormatter, setTitle, setTitleAlign, setTitleColSpan, setTitleHoverFormatter, setTitleOrientation, setTitleStyle, setTitleVAlign, setTooltip, setTop, setType, setValidateOnChange, setValidateOnExit, setValidators, setValidOperators, setVAlign, setValue, setValue, setValue, setValue, setValue, setValue, setValueField, setValueFormatter, setValueHoverFormatter, setValueIconHeight, setValueIconLeftPadding, setValueIconMapper, setValueIconRightPadding, setValueIcons, setValueIconSize, setValueIconWidth, setValueMap, setValueMap, setVisible, setWidth, setWidth, setWrapTitle, shouldApplyHeightToTextBox, shouldFetchMissingValue, shouldSaveOnEnter, show, showIcon, showPicker, stopHover, updateState, validate, valueClipped`

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

      `getRef, getRef, internalSetID`

    - ### 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, setAttributeAsJavaObject`

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

      `equals, 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)

    - #### setJavaScriptObject

          public void setJavaScriptObject(com.google.gwt.core.client.JavaScriptObject jsObj)

      Overrides:
        `setJavaScriptObject` in class `FormItem`

    - #### 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.
      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.
      See Also:
        `AutoChildUsage`

    - #### changePickerIconDefaults

          public static void changePickerIconDefaults(FormItemIcon defaults)

    - #### setApplyPromptToCanvas

          public void setApplyPromptToCanvas(java.lang.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 java.lang.Boolean getApplyPromptToCanvas()

      If `prompt` is specified for this item, should the prompt be applied to the `canvas` for this item?
      Returns:
        Boolean

    - #### 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`.

      Setting this property to true is typically appropriate for cases where a custom CanvasItem automatically creates its canvas as part of its initialization flow. 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` - autoDestroy 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`.

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

      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.
      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. 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(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` - editCriteriaInInnerForm 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:
        Boolean

    - #### 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`.

      Parameters:
        `multiple` - multiple Default value is null

    - #### 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`.

      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(java.lang.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.. See `String`. Default value is null
      See Also:
        `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.
      Overrides:
        `getPrompt` in class `FormItem`
      Returns:
        . See `String`
      See Also:
        `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 `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 java.lang.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

    - #### addCanEditChangedHandler

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

      Add a canEditChanged handler.

      Notification method called when `canEdit` is modified. Developers may make use of this to toggle between an editable and a read-only appearance for custom FormItems.

      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`

    - #### readOnlyDisplayChanged

          public void readOnlyDisplayChanged(ReadOnlyDisplayAppearance readOnlyDisplay)

      Notification method called when `readOnlyDisplay` is modified. Developers may make use of this to alter the read-only appearance of custom FormItems.
      Parameters:
        `readOnlyDisplay` - New readOnlyDisplay value

    - #### addShowValueHandler

          public com.google.gwt.event.shared.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

    - #### setDefaultProperties

          public static void setDefaultProperties(CanvasItem canvasItemProperties)

      Class level method to set the default properties of this class. If set, then all subsequent instances of this class will automatically have the default properties that were set when this method was called. 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 effect 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.

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

    - #### 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`

      Overrides:
        `getHeight` in class `FormItem`
      Returns:
        Integer
      See Also:
        `FormLayout overview and related methods`, Filling Example

    - #### 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(java.lang.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

    - #### 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