Class Canvas

All Implemented Interfaces:
HasAttachHandlers, HasHandlers, EventListener, HasVisibility, IsWidget, LogicalStructure, HasClearHandlers, HasClickHandlers, HasDoubleClickHandlers, HasDragMoveHandlers, HasDragRepositionMoveHandlers, HasDragRepositionStartHandlers, HasDragRepositionStopHandlers, HasDragResizeMoveHandlers, HasDragResizeStartHandlers, HasDragResizeStopHandlers, HasDragStartHandlers, HasDragStopHandlers, HasDropHandlers, HasDropMoveHandlers, HasDropOutHandlers, HasDropOverHandlers, HasFocusChangedHandlers, HasHoverHandlers, HasHoverHiddenHandlers, HasKeyDownHandlers, HasKeyPressHandlers, HasMouseDownHandlers, HasMouseMoveHandlers, HasMouseOutHandlers, HasMouseOverHandlers, HasMouseStillDownHandlers, HasMouseUpHandlers, HasMouseWheelHandlers, HasMovedHandlers, HasParentMovedHandlers, HasResizedHandlers, HasRightMouseDownHandlers, HasRuleContextChangedHandlers, HasScrolledHandlers, HasShowContextMenuHandlers, HasVisibilityChangedHandlers
Direct Known Subclasses:
AceEditor, BrowserPlugin, Calendar, DetailViewer, DrawKnob, DrawPane, DynamicForm, EdgedCanvas, EditPane, GridRenderer, HTMLFlow, Layout, LayoutSpacer, PrintCanvas, RangeSlider, RowRangeDisplay, Slider, StatefulCanvas, TabSet, TileLayout, WidgetCanvas

Base class for all Smart GWT visual components (except FormItems).

Canvas provides:

  • Constructor Details

  • Method Details

    • getOrCreateRef

      public static Canvas getOrCreateRef(JavaScriptObject jsObj)
    • getPaletteDefaults

      public Map getPaletteDefaults()
      This method returns a Map of config properties suitable for use as the "defaults" attribute of a PaletteNode. Use it when you need to work with PaletteNodes indirectly, such when setting up TileRecords that will be used in a TilePalette. See the dev tools overview for examples of how to assemble and acquire a suitable defaults object when you are creating a PaletteNode indirectly
    • changeAutoChildDefaults

      public static void changeAutoChildDefaults(String autoChildName, Canvas defaults)
      Changes the defaults for Canvas AutoChildren named autoChildName.
      Parameters:
      autoChildName - name of an AutoChild to customize the defaults for.
      defaults - Canvas defaults to apply. These defaults override any existing properties without destroying or wiping out non-overridden properties. For usage tips on this param, see SGWTProperties.
      See Also:
    • changeAutoChildDefaults

      public static void changeAutoChildDefaults(String autoChildName, FormItem defaults)
      Changes the defaults for FormItem AutoChildren named autoChildName.
      Parameters:
      autoChildName - name of an AutoChild to customize the defaults for.
      defaults - FormItem defaults to apply. These defaults override any existing properties without destroying or wiping out non-overridden properties. For usage tips on this param, see SGWTProperties.
      See Also:
    • create

      protected JavaScriptObject create()
      Overrides:
      create in class BaseWidget
    • setAccessKey

      public Canvas setAccessKey(String accessKey)
      If specified this governs the HTML accessKey for the widget.

      This should be set to a character - when a user hits the html accessKey modifier for the browser, plus this character, focus will be given to the widget in question. The accessKey modifier can vary by browser and platform.

      The following list of default behavior is for reference only, developers should also consult browser documentation for additional information.

      • Internet Explorer (all platforms): Alt + accessKey
      • Mozilla Firefox (Windows, Unix): Alt+Shift + accessKey
      • Mozilla Firefox (Mac): Ctrl+Opt + accessKey
      • Chrome and Safari (Windows, Unix): Alt + accessKey
      • Chrome and Safari (Mac): Ctrl+Opt + accessKey


      If this method is called after the component has been drawn/initialized: Set the accessKey for this canvas.

      The accessKey can be set to any alphanumeric character (symbols not supported) Having set an accessKey, the canvas will be given focus when the user hits Alt+[accessKey], or in Mozilla Firefox 2.0 and above, Shift+Alt+[accessKey].

      Note : This is an advanced setting

      Parameters:
      accessKey - Character to use as an accessKey for this widget. Case Insensitive. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getAccessKey

      public String getAccessKey()
      If specified this governs the HTML accessKey for the widget.

      This should be set to a character - when a user hits the html accessKey modifier for the browser, plus this character, focus will be given to the widget in question. The accessKey modifier can vary by browser and platform.

      The following list of default behavior is for reference only, developers should also consult browser documentation for additional information.

      • Internet Explorer (all platforms): Alt + accessKey
      • Mozilla Firefox (Windows, Unix): Alt+Shift + accessKey
      • Mozilla Firefox (Mac): Ctrl+Opt + accessKey
      • Chrome and Safari (Windows, Unix): Alt + accessKey
      • Chrome and Safari (Mac): Ctrl+Opt + accessKey
      Returns:
      Current accessKey value. Default value is null
      See Also:
    • setAdaptiveHeightPriority

      public Canvas setAdaptiveHeightPriority(Integer adaptiveHeightPriority) throws IllegalStateException
      Parameters:
      adaptiveHeightPriority - New adaptiveHeightPriority value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
    • getAdaptiveHeightPriority

      public Integer getAdaptiveHeightPriority()
      Returns:
      Current adaptiveHeightPriority value. Default value is null
    • setAdaptiveWidthPriority

      public Canvas setAdaptiveWidthPriority(Integer adaptiveWidthPriority) throws IllegalStateException
      If multiple widgets in the same Layout have adaptive width, adaptiveWidthPriority can be set to indicate which of the components should be given priority access to space.

      The widget with the highest priority setting will be offered surplus space first, and asked to give up space last. Lack of a priority setting is treated as zero. Any adaptive widgets with the same priority setting will be asked to give up or release space according to their order in Layout.members.

      Parameters:
      adaptiveWidthPriority - New adaptiveWidthPriority value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:
    • getAdaptiveWidthPriority

      public Integer getAdaptiveWidthPriority()
      If multiple widgets in the same Layout have adaptive width, adaptiveWidthPriority can be set to indicate which of the components should be given priority access to space.

      The widget with the highest priority setting will be offered surplus space first, and asked to give up space last. Lack of a priority setting is treated as zero. Any adaptive widgets with the same priority setting will be asked to give up or release space according to their order in Layout.members.

      Returns:
      Current adaptiveWidthPriority value. Default value is null
      See Also:
    • setAlwaysManageFocusNavigation

      public Canvas setAlwaysManageFocusNavigation(Boolean alwaysManageFocusNavigation) throws IllegalStateException
      Should focus navigation for this canvas and its descendents be handled explicitly by intercepting "Tab" key events and calling the TabIndexManager.shiftFocus() API?

      Setting this property to true will cause the registered TabIndexManager entry for this canvas to be marked as useExplicitFocusNavigation:true, and will cause standard event handling for the canvas and its descendents to intercept Tab keystrokes and explicitly call TabIndexManager.shiftFocus() rather than relying on native browser Tab navigation

      Parameters:
      alwaysManageFocusNavigation - New alwaysManageFocusNavigation value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
    • getAlwaysManageFocusNavigation

      public Boolean getAlwaysManageFocusNavigation()
      Should focus navigation for this canvas and its descendents be handled explicitly by intercepting "Tab" key events and calling the TabIndexManager.shiftFocus() API?

      Setting this property to true will cause the registered TabIndexManager entry for this canvas to be marked as useExplicitFocusNavigation:true, and will cause standard event handling for the canvas and its descendents to intercept Tab keystrokes and explicitly call TabIndexManager.shiftFocus() rather than relying on native browser Tab navigation

      Returns:
      Current alwaysManageFocusNavigation value. Default value is null
    • setAlwaysShowScrollbars

      public Canvas setAlwaysShowScrollbars(Boolean alwaysShowScrollbars) throws IllegalStateException
      Should this browser always show custom scrollbars if showCustomScrollbars is true?

      On touch devices that support native touch scrolling, if showCustomScrollbars is true and touch scrolling has not been disabled by the useTouchScrolling and/or disableTouchScrollingForDrag settings, should custom scrollbars and native touch scrolling be enabled for this component? If false or unset, then only native touch scrolling will be enabled. If true, then both scrolling mechanisms will be enabled.

      NOTE: Because native touch scrolling (also called momentum scrolling) is computationally intensive, some mobile browsers implement an optimization where the state of the DOM for the element being scrolled will be frozen or partially frozen during the scroll animation. This results in a delay between when the scroll position reaches a certain point in the animation and when the positions of the custom scrollbar thumbs are updated to reflect that scroll position.

      For non-touch devices, setting this property to true will override nativeAutoHideScrollbars, and ensure custom scrollbars are shown for the component

      Note : This is an advanced setting

      Parameters:
      alwaysShowScrollbars - New alwaysShowScrollbars value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:
    • getAlwaysShowScrollbars

      public Boolean getAlwaysShowScrollbars()
      Should this browser always show custom scrollbars if showCustomScrollbars is true?

      On touch devices that support native touch scrolling, if showCustomScrollbars is true and touch scrolling has not been disabled by the useTouchScrolling and/or disableTouchScrollingForDrag settings, should custom scrollbars and native touch scrolling be enabled for this component? If false or unset, then only native touch scrolling will be enabled. If true, then both scrolling mechanisms will be enabled.

      NOTE: Because native touch scrolling (also called momentum scrolling) is computationally intensive, some mobile browsers implement an optimization where the state of the DOM for the element being scrolled will be frozen or partially frozen during the scroll animation. This results in a delay between when the scroll position reaches a certain point in the animation and when the positions of the custom scrollbar thumbs are updated to reflect that scroll position.

      For non-touch devices, setting this property to true will override nativeAutoHideScrollbars, and ensure custom scrollbars are shown for the component

      Returns:
      Current alwaysShowScrollbars value. Default value is null
      See Also:
    • setAnimateAcceleration

      public Canvas setAnimateAcceleration(AnimationAcceleration animateAcceleration)
      Default acceleration effect to apply to all animations on this Canvas. Can be overridden by setting animationAcceleration for specific animations or by passing an acceleration function directly into the appropriate method.

      Note : This is an advanced setting

      Parameters:
      animateAcceleration - New animateAcceleration value. Default value is "smoothEnd"
      Returns:
      Canvas instance, for chaining setter calls
    • getAnimateAcceleration

      public AnimationAcceleration getAnimateAcceleration()
      Default acceleration effect to apply to all animations on this Canvas. Can be overridden by setting animationAcceleration for specific animations or by passing an acceleration function directly into the appropriate method.
      Returns:
      Current animateAcceleration value. Default value is "smoothEnd"
    • setAnimateFadeTime

      public Canvas setAnimateFadeTime(Integer animateFadeTime)
      Default time for performing an animated fade. If unset, this.animateTime will be used by default instead

      Note : This is an advanced setting

      Parameters:
      animateFadeTime - New animateFadeTime value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
    • getAnimateFadeTime

      public Integer getAnimateFadeTime()
      Default time for performing an animated fade. If unset, this.animateTime will be used by default instead
      Returns:
      Current animateFadeTime value. Default value is null
    • setAnimateHideAcceleration

      public Canvas setAnimateHideAcceleration(AnimationAcceleration animateHideAcceleration)
      Default acceleration function for performing an animated hide. If unset, this.animateAcceleration will be used by default instead

      Note : This is an advanced setting

      Parameters:
      animateHideAcceleration - New animateHideAcceleration value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
    • getAnimateHideAcceleration

      public AnimationAcceleration getAnimateHideAcceleration()
      Default acceleration function for performing an animated hide. If unset, this.animateAcceleration will be used by default instead
      Returns:
      Current animateHideAcceleration value. Default value is null
    • setAnimateHideTime

      public Canvas setAnimateHideTime(Integer animateHideTime)
      Default time for performing an animated hide. If unset, this.animateTime will be used by default instead

      Note : This is an advanced setting

      Parameters:
      animateHideTime - New animateHideTime value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
    • getAnimateHideTime

      public Integer getAnimateHideTime()
      Default time for performing an animated hide. If unset, this.animateTime will be used by default instead
      Returns:
      Current animateHideTime value. Default value is null
    • setAnimateMoveAcceleration

      public Canvas setAnimateMoveAcceleration(AnimationAcceleration animateMoveAcceleration)
      Default acceleration effect for performing an animated move. If unset, this.animateAcceleration will be used by default instead

      Note : This is an advanced setting

      Parameters:
      animateMoveAcceleration - New animateMoveAcceleration value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
    • getAnimateMoveAcceleration

      public AnimationAcceleration getAnimateMoveAcceleration()
      Default acceleration effect for performing an animated move. If unset, this.animateAcceleration will be used by default instead
      Returns:
      Current animateMoveAcceleration value. Default value is null
    • setAnimateMoveTime

      public Canvas setAnimateMoveTime(Integer animateMoveTime)
      Default time for performing an animated move. If unset, this.animateTime will be used by default instead

      Note : This is an advanced setting

      Parameters:
      animateMoveTime - New animateMoveTime value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
    • getAnimateMoveTime

      public Integer getAnimateMoveTime()
      Default time for performing an animated move. If unset, this.animateTime will be used by default instead
      Returns:
      Current animateMoveTime value. Default value is null
    • setAnimateRectAcceleration

      public Canvas setAnimateRectAcceleration(AnimationAcceleration animateRectAcceleration)
      Default acceleration function for performing an animated move and resize. If unset, this.animateAcceleration will be used by default instead

      Note : This is an advanced setting

      Parameters:
      animateRectAcceleration - New animateRectAcceleration value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
    • getAnimateRectAcceleration

      public AnimationAcceleration getAnimateRectAcceleration()
      Default acceleration function for performing an animated move and resize. If unset, this.animateAcceleration will be used by default instead
      Returns:
      Current animateRectAcceleration value. Default value is null
    • setAnimateRectTime

      public Canvas setAnimateRectTime(Integer animateRectTime)
      Default time for performing an animated setRect. If unset, this.animateTime will be used by default instead

      Note : This is an advanced setting

      Parameters:
      animateRectTime - New animateRectTime value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
    • getAnimateRectTime

      public Integer getAnimateRectTime()
      Default time for performing an animated setRect. If unset, this.animateTime will be used by default instead
      Returns:
      Current animateRectTime value. Default value is null
    • setAnimateResizeAcceleration

      public Canvas setAnimateResizeAcceleration(AnimationAcceleration animateResizeAcceleration)
      Default acceleration function for performing an animated resize. If unset, this.animateAcceleration will be used by default instead

      Note : This is an advanced setting

      Parameters:
      animateResizeAcceleration - New animateResizeAcceleration value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
    • getAnimateResizeAcceleration

      public AnimationAcceleration getAnimateResizeAcceleration()
      Default acceleration function for performing an animated resize. If unset, this.animateAcceleration will be used by default instead
      Returns:
      Current animateResizeAcceleration value. Default value is null
    • setAnimateResizeLayoutMode

      public Canvas setAnimateResizeLayoutMode(AnimationLayoutMode animateResizeLayoutMode)
      When to update the child layout for a size animation. Updating the child layout more often may improve appearance, but risks prohibitive overhead with more complicated widget hierarchies.

      Note : This is an advanced setting

      Parameters:
      animateResizeLayoutMode - New animateResizeLayoutMode value. Default value is "atEnd"
      Returns:
      Canvas instance, for chaining setter calls
    • getAnimateResizeLayoutMode

      public AnimationLayoutMode getAnimateResizeLayoutMode()
      When to update the child layout for a size animation. Updating the child layout more often may improve appearance, but risks prohibitive overhead with more complicated widget hierarchies.
      Returns:
      Current animateResizeLayoutMode value. Default value is "atEnd"
    • setAnimateResizeTime

      public Canvas setAnimateResizeTime(Integer animateResizeTime)
      Default time for performing an animated resize. If unset, this.animateTime will be used by default instead

      Note : This is an advanced setting

      Parameters:
      animateResizeTime - New animateResizeTime value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
    • getAnimateResizeTime

      public Integer getAnimateResizeTime()
      Default time for performing an animated resize. If unset, this.animateTime will be used by default instead
      Returns:
      Current animateResizeTime value. Default value is null
    • setAnimateScrollAcceleration

      public Canvas setAnimateScrollAcceleration(AnimationAcceleration animateScrollAcceleration)
      Default acceleration function for performing an animated scroll. If unset, this.animateAcceleration will be used by default instead

      Note : This is an advanced setting

      Parameters:
      animateScrollAcceleration - New animateScrollAcceleration value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
    • getAnimateScrollAcceleration

      public AnimationAcceleration getAnimateScrollAcceleration()
      Default acceleration function for performing an animated scroll. If unset, this.animateAcceleration will be used by default instead
      Returns:
      Current animateScrollAcceleration value. Default value is null
    • setAnimateScrollTime

      public Canvas setAnimateScrollTime(Integer animateScrollTime)
      Default time for performing an animated scroll. If unset, this.animateTime will be used by default instead

      Note : This is an advanced setting

      Parameters:
      animateScrollTime - New animateScrollTime value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
    • getAnimateScrollTime

      public Integer getAnimateScrollTime()
      Default time for performing an animated scroll. If unset, this.animateTime will be used by default instead
      Returns:
      Current animateScrollTime value. Default value is null
    • setAnimateShowAcceleration

      public Canvas setAnimateShowAcceleration(AnimationAcceleration animateShowAcceleration)
      Default acceleration function for performing an animated show. If unset, this.animateAcceleration will be used by default instead

      Note : This is an advanced setting

      Parameters:
      animateShowAcceleration - New animateShowAcceleration value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
    • getAnimateShowAcceleration

      public AnimationAcceleration getAnimateShowAcceleration()
      Default acceleration function for performing an animated show. If unset, this.animateAcceleration will be used by default instead
      Returns:
      Current animateShowAcceleration value. Default value is null
    • setAnimateShowTime

      public Canvas setAnimateShowTime(Integer animateShowTime)
      Default time for performing an animated show. If unset, this.animateTime will be used by default instead

      Note : This is an advanced setting

      Parameters:
      animateShowTime - New animateShowTime value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
    • getAnimateShowTime

      public Integer getAnimateShowTime()
      Default time for performing an animated show. If unset, this.animateTime will be used by default instead
      Returns:
      Current animateShowTime value. Default value is null
    • setAnimateTime

      public Canvas setAnimateTime(int animateTime)
      Default total duration of animations. Can be overridden by setting animation times for specific animations, or by passing a duration parameter into the appropriate animate...() method.

      Note : This is an advanced setting

      Parameters:
      animateTime - New animateTime value. Default value is 300
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getAnimateTime

      public int getAnimateTime()
      Default total duration of animations. Can be overridden by setting animation times for specific animations, or by passing a duration parameter into the appropriate animate...() method.
      Returns:
      Current animateTime value. Default value is 300
      See Also:
    • setAppImgDir

      public Canvas setAppImgDir(String appImgDir)
      Default directory for app-specific images, relative to the Page-wide appImgDir.

      Note : This is an advanced setting

      Parameters:
      appImgDir - New appImgDir value. Default value is ""
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getAppImgDir

      public String getAppImgDir()
      Default directory for app-specific images, relative to the Page-wide appImgDir.
      Returns:
      Current appImgDir value. Default value is ""
      See Also:
    • setAriaRole

      public Canvas setAriaRole(String ariaRole) throws IllegalStateException
      ARIA role of this component. Usually does not need to be manually set - see Accessibility.
      Parameters:
      ariaRole - New ariaRole value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:
    • getAriaRole

      public String getAriaRole()
      ARIA role of this component. Usually does not need to be manually set - see Accessibility.
      Returns:
      Current ariaRole value. Default value is null
      See Also:
    • setAutoMaskComponents

      public Canvas setAutoMaskComponents(Boolean autoMaskComponents) throws IllegalStateException
      Deprecated.
      As of Smart GWT version 10.0, deprecated in favor of EditProxy.autoMaskChildren
      When nodes are added to an EditContext, should they be masked by setting EditProxy.useEditMask true if not explicitly set?
      Parameters:
      autoMaskComponents - New autoMaskComponents value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
    • getAutoMaskComponents

      public Boolean getAutoMaskComponents()
      Deprecated.
      As of Smart GWT version 10.0, deprecated in favor of EditProxy.autoMaskChildren
      When nodes are added to an EditContext, should they be masked by setting EditProxy.useEditMask true if not explicitly set?
      Returns:
      Current autoMaskComponents value. Default value is null
    • setAutoParent

      public Canvas setAutoParent(String autoParent) throws IllegalStateException
      This initialization property allows developers to create a canvas using the Class.addAutoChild() method, and have it added as a child to some other component. This property may be set to the childName of another already-created auto-child, or "none" to cause the component to be created without being added as a child to any other widget.
      If unset, the canvas will be added as a child to the component on which addAutoChild(...) was called.

      See autoChildren for an overview of the autoChild subsystem.

      Note : This is an advanced setting

      Parameters:
      autoParent - New autoParent value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
    • getAutoParent

      public String getAutoParent()
      This initialization property allows developers to create a canvas using the Class.addAutoChild() method, and have it added as a child to some other component. This property may be set to the childName of another already-created auto-child, or "none" to cause the component to be created without being added as a child to any other widget.
      If unset, the canvas will be added as a child to the component on which addAutoChild(...) was called.

      See autoChildren for an overview of the autoChild subsystem.

      Returns:
      Current autoParent value. Default value is null
    • setAutoPopulateData

      public Canvas setAutoPopulateData(Boolean autoPopulateData) throws IllegalStateException
      If a dataContext is provided, should subcomponents automatically bind to the data?

      In general, if you provide a primaryKey value for a record, that specific record will be shown or edited, or have its related records loaded. If you provide other field values without the primaryKey value, those values will be treated as either criteria (for a grid) or as initial values (for a form).

      Components will respond to dataContext differently depending on whether they typically work with just a single record (such as form or a DetailViewer), or whether they usually work with lists of records (such as ListGrid or TileGrid, which have component.dataArity set to multipe by default).

      Specifically, the following rules are used:

      1. for a singular component (eg forms, detailViewers):
        • if only the PK (primary key) value is provided, the component will fetch the singular record and display or edit it
        • if the PK is provided along with other values, the component will assume it has a complete record, and display or edit it
        • if only non-PK values are provided, the component will assume these are initial values
      2. for a multiple component (eg listGrid, tileGrid):
        • if only non-PK values are provided, the component will use these as criteria. For example, a grid bound to an Orders DataSource with dataContext of Status:"In Process" would fetch records with that status
        • if the PK is provided, and the component's DataSource is related to one of the DataSources in the dataContext, related records will be fetched, using the PK value (similarly to if fetchRelatedData() had been called. For example, if an orderNumber value was provided, a grid bound to OrderDetail would fetch line items for that orderNumber.
        • if an array of multiple records is provided, that data is used as if setData() had been called on the component
      If any of these behaviors is not desired, you can just set autoPopulateData to false on the specific component that should not be auto-populated.

      Specific examples, using the Order and OrderDetail sample DataSources, where OrderDetail records are associated (many-to-1) with Order records, and the PK of Order is orderNumber:

      1. a form or DetailViewer bound to Order and a ListGrid bound to OrderDetail:
        • if an orderNumber is provided, the form or DetailViewer would show that order, and the grid would show related OrderDetail records
        • if only orderNumber is provided (no additional fields), the full Order record is automatically fetched for the form or DetailViewer

        This fulfills a common use case of viewing or editing an Order and its related OrderDetail records.

      2. a grid bound to Order and a second grid bound to OrderDetail
        • if values such as orderStatus : "On Hold" were provided, the Order grid uses those as criteria
        • the OrderDetail grid does nothing

        This fulfills a common use case of viewing Order records that match certain criteria. The OrderDetail grid would generally be populated only by an event handler installed on the Order grid, which would call fetchRelatedData.

      3. a grid and form both bound to Order
        • if values such as orderStatus : "On Hold" were provided, the Order grid uses those as criteria, and the form uses those as initial values

        This fulfills two possible use cases:

        • the form is a SearchForm for searching the grid, so it should show the same criteria as are applied to the grid
        • the form is for editing the selected record in the grid, or adding new ones. It is ready to either add a new record, or for the user to select a record to show in the form, typically via logic added to the grid (e.g. recordClick -> form.editSelectedData().

      By default, autoPopulateData is true for any component that is contained with a "screen" RPCManager.createScreen() and false for any component that is an com.smartgwt.client.types.AutoChild.

      Note that, if there is a non-DBC in your screen that wants to access fields in the expected dataContext, the DynamicProperty can refer to properties that auto-populated DBCs will place into the ruleContext. For example, with a DynamicForm "itemEditor" bound to "supplyItem", a header above could use itemEditor.values.itemName to display the name of the item. The header will then show the expected value as soon as the DynamicForm is auto-populated.

      Similarly, the DataView.drawn() StringMethod fires after auto-population has occurred, so any startup actions in a screen will likewise be able to utilize data from the dataContext by just referring to it via ruleScope.

      Parameters:
      autoPopulateData - New autoPopulateData value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
    • getAutoPopulateData

      public Boolean getAutoPopulateData()
      If a dataContext is provided, should subcomponents automatically bind to the data?

      In general, if you provide a primaryKey value for a record, that specific record will be shown or edited, or have its related records loaded. If you provide other field values without the primaryKey value, those values will be treated as either criteria (for a grid) or as initial values (for a form).

      Components will respond to dataContext differently depending on whether they typically work with just a single record (such as form or a DetailViewer), or whether they usually work with lists of records (such as ListGrid or TileGrid, which have component.dataArity set to multipe by default).

      Specifically, the following rules are used:

      1. for a singular component (eg forms, detailViewers):
        • if only the PK (primary key) value is provided, the component will fetch the singular record and display or edit it
        • if the PK is provided along with other values, the component will assume it has a complete record, and display or edit it
        • if only non-PK values are provided, the component will assume these are initial values
      2. for a multiple component (eg listGrid, tileGrid):
        • if only non-PK values are provided, the component will use these as criteria. For example, a grid bound to an Orders DataSource with dataContext of Status:"In Process" would fetch records with that status
        • if the PK is provided, and the component's DataSource is related to one of the DataSources in the dataContext, related records will be fetched, using the PK value (similarly to if fetchRelatedData() had been called. For example, if an orderNumber value was provided, a grid bound to OrderDetail would fetch line items for that orderNumber.
        • if an array of multiple records is provided, that data is used as if setData() had been called on the component
      If any of these behaviors is not desired, you can just set autoPopulateData to false on the specific component that should not be auto-populated.

      Specific examples, using the Order and OrderDetail sample DataSources, where OrderDetail records are associated (many-to-1) with Order records, and the PK of Order is orderNumber:

      1. a form or DetailViewer bound to Order and a ListGrid bound to OrderDetail:
        • if an orderNumber is provided, the form or DetailViewer would show that order, and the grid would show related OrderDetail records
        • if only orderNumber is provided (no additional fields), the full Order record is automatically fetched for the form or DetailViewer

        This fulfills a common use case of viewing or editing an Order and its related OrderDetail records.

      2. a grid bound to Order and a second grid bound to OrderDetail
        • if values such as orderStatus : "On Hold" were provided, the Order grid uses those as criteria
        • the OrderDetail grid does nothing

        This fulfills a common use case of viewing Order records that match certain criteria. The OrderDetail grid would generally be populated only by an event handler installed on the Order grid, which would call fetchRelatedData.

      3. a grid and form both bound to Order
        • if values such as orderStatus : "On Hold" were provided, the Order grid uses those as criteria, and the form uses those as initial values

        This fulfills two possible use cases:

        • the form is a SearchForm for searching the grid, so it should show the same criteria as are applied to the grid
        • the form is for editing the selected record in the grid, or adding new ones. It is ready to either add a new record, or for the user to select a record to show in the form, typically via logic added to the grid (e.g. recordClick -> form.editSelectedData().

      By default, autoPopulateData is true for any component that is contained with a "screen" RPCManager.createScreen() and false for any component that is an com.smartgwt.client.types.AutoChild.

      Note that, if there is a non-DBC in your screen that wants to access fields in the expected dataContext, the DynamicProperty can refer to properties that auto-populated DBCs will place into the ruleContext. For example, with a DynamicForm "itemEditor" bound to "supplyItem", a header above could use itemEditor.values.itemName to display the name of the item. The header will then show the expected value as soon as the DynamicForm is auto-populated.

      Similarly, the DataView.drawn() StringMethod fires after auto-population has occurred, so any startup actions in a screen will likewise be able to utilize data from the dataContext by just referring to it via ruleScope.

      Returns:
      Current autoPopulateData value. Default value is null
    • setAutoShowParent

      public Canvas setAutoShowParent(Boolean autoShowParent)
      If set to true, the widget's parent (if any) will automatically be shown whenever the widget is shown.

      Note : This is an advanced setting

      Parameters:
      autoShowParent - New autoShowParent value. Default value is false
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getAutoShowParent

      public Boolean getAutoShowParent()
      If set to true, the widget's parent (if any) will automatically be shown whenever the widget is shown.
      Returns:
      Current autoShowParent value. Default value is false
      See Also:
    • setBackgroundColor

      public Canvas setBackgroundColor(String backgroundColor)
      The background color for this widget. It corresponds to the CSS background-color attribute. You can set this property to an RGB value (e.g. #22AAFF) or a named color (e.g. red) from a list of browser supported color names.

      If this method is called after the component has been drawn/initialized: Sets the background color of this component to newColor.
      Parameters:
      backgroundColor - new background color, or null to remove the current background color. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getBackgroundColor

      public String getBackgroundColor()
      The background color for this widget. It corresponds to the CSS background-color attribute. You can set this property to an RGB value (e.g. #22AAFF) or a named color (e.g. red) from a list of browser supported color names.
      Returns:
      Current backgroundColor value. Default value is null
      See Also:
    • setBackgroundImage

      public Canvas setBackgroundImage(String backgroundImage)
      URL for a background image for this widget (corresponding to the CSS "background-image" attribute).

      If this method is called after the component has been drawn/initialized: Sets the background to an image file given by newImage. This URL should be given as a string relative to the image directory for the page (./images by default).
      Parameters:
      backgroundImage - new URL (local to Page image directory) for background image. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getBackgroundImage

      public String getBackgroundImage()
      URL for a background image for this widget (corresponding to the CSS "background-image" attribute).
      Returns:
      Current backgroundImage value. Default value is null
      See Also:
    • setBackgroundPosition

      public Canvas setBackgroundPosition(String backgroundPosition) throws IllegalStateException
      Specifies how the background image should be positioned on the widget. It corresponds to the CSS background-position attribute. If unset, no background-position attribute is specified if a background image is specified.
      Parameters:
      backgroundPosition - New backgroundPosition value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:
    • getBackgroundPosition

      public String getBackgroundPosition()
      Specifies how the background image should be positioned on the widget. It corresponds to the CSS background-position attribute. If unset, no background-position attribute is specified if a background image is specified.
      Returns:
      Current backgroundPosition value. Default value is null
      See Also:
    • setBackgroundRepeat

      public Canvas setBackgroundRepeat(BackgroundRepeat backgroundRepeat)
      Specifies how the background image should be tiled if this widget is larger than the image. It corresponds to the CSS background-repeat attribute.

      The default of null means no background-repeat CSS will be written out. See BackgroundRepeat type for details on other settings.

      NOTE: this setting directly sets the CSS property background-repeat but does not attempt to work around various known bugs with this setting, or lack of support in IE6. If you need to apply CSS-based workarounds for browser limitations with this setting, it's best to do so via setting styleName.

      Parameters:
      backgroundRepeat - New backgroundRepeat value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getBackgroundRepeat

      public BackgroundRepeat getBackgroundRepeat()
      Specifies how the background image should be tiled if this widget is larger than the image. It corresponds to the CSS background-repeat attribute.

      The default of null means no background-repeat CSS will be written out. See BackgroundRepeat type for details on other settings.

      NOTE: this setting directly sets the CSS property background-repeat but does not attempt to work around various known bugs with this setting, or lack of support in IE6. If you need to apply CSS-based workarounds for browser limitations with this setting, it's best to do so via setting styleName.

      Returns:
      Current backgroundRepeat value. Default value is null
      See Also:
    • setBorder

      public Canvas setBorder(String border)
      Set the CSS border of this component, as a CSS string including border-width, border-style, and/or color (eg "2px solid blue").

      This property applies the same border to all four sides of this component. Different per-side borders can be set in a CSS style and applied via styleName.

      If a grouping frame is being shown then border is derived from the groupBorderCSS attribute, not from the explicit border property.

      If this method is called after the component has been drawn/initialized: Set the CSS border of this component, as a CSS string including border-width, border-style, and/or color (eg "2px solid blue").

      This property applies the same border to all four sides of this component. Different per-side borders can be set in a CSS style and applied via styleName.

      Parameters:
      border - new border to set to (eg: "2px solid black"). Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getBorder

      public String getBorder()
      Set the CSS border of this component, as a CSS string including border-width, border-style, and/or color (eg "2px solid blue").

      This property applies the same border to all four sides of this component. Different per-side borders can be set in a CSS style and applied via styleName.

      If a grouping frame is being shown then border is derived from the groupBorderCSS attribute, not from the explicit border property.

      Returns:
      Current border value. Default value is null
      See Also:
    • setBorderRadius

      public Canvas setBorderRadius(String borderRadius)
      The CSS border-radius for this widget. The value can be any variant of a CSS border-radius value - that is, from 1 to 4 space-separated px values, where one value affects all corners and 4 values affects individual corners. For example "10px" applies a 10px radius to all corners, where "5px 10px 15px 20px" applies a different radius to each corner, clockwise from Top-Left: "TL TR BR BL".
      Parameters:
      borderRadius - New borderRadius value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getBorderRadius

      public String getBorderRadius()
      The CSS border-radius for this widget. The value can be any variant of a CSS border-radius value - that is, from 1 to 4 space-separated px values, where one value affects all corners and 4 values affects individual corners. For example "10px" applies a 10px radius to all corners, where "5px 10px 15px 20px" applies a different radius to each corner, clockwise from Top-Left: "TL TR BR BL".
      Returns:
      Current borderRadius value. Default value is null
      See Also:
    • setCanAcceptDrop

      public Canvas setCanAcceptDrop(Boolean canAcceptDrop)
      Indicates that this object can receive dropped widgets (i.e. other widgets can be dropped on top of it).

      Note : This is an advanced setting

      Parameters:
      canAcceptDrop - New canAcceptDrop value. Default value is false
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getCanAcceptDrop

      public Boolean getCanAcceptDrop()
      Indicates that this object can receive dropped widgets (i.e. other widgets can be dropped on top of it).
      Returns:
      Current canAcceptDrop value. Default value is false
      See Also:
    • setCanAdaptHeight

      public Canvas setCanAdaptHeight(Boolean canAdaptHeight)
      Parameters:
      canAdaptHeight - New canAdaptHeight value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
    • getCanAdaptHeight

      public Boolean getCanAdaptHeight()
      Returns:
      Current canAdaptHeight value. Default value is null
    • setCanAdaptWidth

      public Canvas setCanAdaptWidth(Boolean canAdaptWidth)
      Indicates that this component is able to render itself at multiple possible sizes, in order to fit into less space when very little space is available, or to display more information or provide more immediate access to functionality when more space is available.

      Unlike simply indicating a flexible size via width:"*", setting canAdaptWidth indicates that a component has 2 (or more) different ways of rendering itself with different discrete sizes, but does not have the ability to use every additional available pixel.

      For example, a menu embedded in a toolbar might show as only a fixed-size icon which reveals menu options when clicked, or if enough space is available, could show all of the menu options directly in the toolbar. In this example, the menu should either be allocated just enough space for an icon, or enough space for all options to appear inline; any other amount of space being allocated is just a waste.

      When a component with canAdaptWidth is part of a Layout, AdaptWidthByCustomizer.adaptWidthBy() will be called every time component sizes are being calculated, passing a positive or negative pixel value:

      • a positive pixel value indicates a surplus - all other component's minimum sizes can be accommodated, including any minWidth declared on the canAdaptWidth component itself
      • a negative pixel value indicates that the containing layout is going to be forced to Overflow (introduce scrollbars, clip content, etc) unless some component or set of components gives up at least this many pixels

      If a non-zero value is returned from adaptWidthBy, this means that the component is willing to shrink or expand by that many pixels. Returning 0 means that the component is unable to reduce size further, or for a surplus, cannot make good use of the surplus space.

      • A call to AdaptWidthByCustomizer.adaptWidthBy() may surrender as many pixels as desired (as long as the widget won't drop below its minimum allowed width), no matter whether a positive (surplus) or negative (overflow) pixel value is supplied, but
      • A call to AdaptWidthByCustomizer.adaptWidthBy() may not increase its size by more than the number of offered pixels - so if an overflow is present, it may not increase its size at all.

      Note that when the initial width is specified as a stretch size (e.g. "*"), then after AdaptWidthByCustomizer.adaptWidthBy() is called, the Framework will stretch (but not shrink) the member like any other stretch-size Layout member, but the unadaptedWidth argument will always reflect the unstretched width requested by the previous call to AdaptWidthByCustomizer.adaptWidthBy(). This behavior may be disabled by specifying the initial width as a number, or leaving it unspecified.

      Behavior is slightly different for overflow: "visible" members - in this case the unadaptedWidth passed in will reflect the current visible width of the member, rather than the last width requested by the previous call to AdaptWidthByCustomizer.adaptWidthBy() or the specified width (on the first call). However, note that the visible length will match your requested width unless the member is actually overflowed. Stretch sizing is not supported for adaptive-width members with overflow: "visible".

      Caution: you must either determine the current size of the canvas by maintaining your own internal state, or use the unadaptedWidth parameter passed to AdaptWidthByCustomizer.adaptWidthBy(). You must not call getWidth() or getVisibleWidth() on the canvas itself inside AdaptWidthByCustomizer.adaptWidthBy() as the size is in the processing of being determined, but you may draw children or call getVisibleWidth() on them, as we guarantee that the adaptive-width canvas is drawn before the first call to AdaptWidthByCustomizer.adaptWidthBy(). An example of drawing children in AdaptWidthByCustomizer.adaptWidthBy() to compute overall width may be seen in the Inlined Menu Mobile Sample.

      Note that reasonable settings for minWidth should be applied to all other flexible-sized members of a layout where a canAdaptWidth component appears, because when too little space is available, a canAdaptWidth component will absorb all available space until minimums for other components are hit (or the canAdaptWidth component reaches its maximum size). If more than one canAdaptWidth component is present, adaptiveWidthPriority to give priority to a particular component when allocating space.

      All of the above behaviors are exactly the same for height, using canAdaptHeight and AdaptHeightByCustomizer.adaptHeightBy().

      Parameters:
      canAdaptWidth - New canAdaptWidth value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getCanAdaptWidth

      public Boolean getCanAdaptWidth()
      Indicates that this component is able to render itself at multiple possible sizes, in order to fit into less space when very little space is available, or to display more information or provide more immediate access to functionality when more space is available.

      Unlike simply indicating a flexible size via width:"*", setting canAdaptWidth indicates that a component has 2 (or more) different ways of rendering itself with different discrete sizes, but does not have the ability to use every additional available pixel.

      For example, a menu embedded in a toolbar might show as only a fixed-size icon which reveals menu options when clicked, or if enough space is available, could show all of the menu options directly in the toolbar. In this example, the menu should either be allocated just enough space for an icon, or enough space for all options to appear inline; any other amount of space being allocated is just a waste.

      When a component with canAdaptWidth is part of a Layout, AdaptWidthByCustomizer.adaptWidthBy() will be called every time component sizes are being calculated, passing a positive or negative pixel value:

      • a positive pixel value indicates a surplus - all other component's minimum sizes can be accommodated, including any minWidth declared on the canAdaptWidth component itself
      • a negative pixel value indicates that the containing layout is going to be forced to Overflow (introduce scrollbars, clip content, etc) unless some component or set of components gives up at least this many pixels

      If a non-zero value is returned from adaptWidthBy, this means that the component is willing to shrink or expand by that many pixels. Returning 0 means that the component is unable to reduce size further, or for a surplus, cannot make good use of the surplus space.

      • A call to AdaptWidthByCustomizer.adaptWidthBy() may surrender as many pixels as desired (as long as the widget won't drop below its minimum allowed width), no matter whether a positive (surplus) or negative (overflow) pixel value is supplied, but
      • A call to AdaptWidthByCustomizer.adaptWidthBy() may not increase its size by more than the number of offered pixels - so if an overflow is present, it may not increase its size at all.

      Note that when the initial width is specified as a stretch size (e.g. "*"), then after AdaptWidthByCustomizer.adaptWidthBy() is called, the Framework will stretch (but not shrink) the member like any other stretch-size Layout member, but the unadaptedWidth argument will always reflect the unstretched width requested by the previous call to AdaptWidthByCustomizer.adaptWidthBy(). This behavior may be disabled by specifying the initial width as a number, or leaving it unspecified.

      Behavior is slightly different for overflow: "visible" members - in this case the unadaptedWidth passed in will reflect the current visible width of the member, rather than the last width requested by the previous call to AdaptWidthByCustomizer.adaptWidthBy() or the specified width (on the first call). However, note that the visible length will match your requested width unless the member is actually overflowed. Stretch sizing is not supported for adaptive-width members with overflow: "visible".

      Caution: you must either determine the current size of the canvas by maintaining your own internal state, or use the unadaptedWidth parameter passed to AdaptWidthByCustomizer.adaptWidthBy(). You must not call getWidth() or getVisibleWidth() on the canvas itself inside AdaptWidthByCustomizer.adaptWidthBy() as the size is in the processing of being determined, but you may draw children or call getVisibleWidth() on them, as we guarantee that the adaptive-width canvas is drawn before the first call to AdaptWidthByCustomizer.adaptWidthBy(). An example of drawing children in AdaptWidthByCustomizer.adaptWidthBy() to compute overall width may be seen in the Inlined Menu Mobile Sample.

      Note that reasonable settings for minWidth should be applied to all other flexible-sized members of a layout where a canAdaptWidth component appears, because when too little space is available, a canAdaptWidth component will absorb all available space until minimums for other components are hit (or the canAdaptWidth component reaches its maximum size). If more than one canAdaptWidth component is present, adaptiveWidthPriority to give priority to a particular component when allocating space.

      All of the above behaviors are exactly the same for height, using canAdaptHeight and AdaptHeightByCustomizer.adaptHeightBy().

      Returns:
      Current canAdaptWidth value. Default value is null
      See Also:
    • setCanDrag

      public Canvas setCanDrag(Boolean canDrag)
      Indicates whether this widget can initiate custom drag-and-drop operations (other than reposition or resize). Normally canDragReposition or canDragResize would be used instead of this property.

      Note: this property may be manipulated by higher-level dragging semantics.

      If useNativeDrag is true and this widget has been drawn, then this widget must be redrawn in order for a change of the value of this attribute to take effect.

      Note : This is an advanced setting

      Parameters:
      canDrag - New canDrag value. Default value is false
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getCanDrag

      public Boolean getCanDrag()
      Indicates whether this widget can initiate custom drag-and-drop operations (other than reposition or resize). Normally canDragReposition or canDragResize would be used instead of this property.

      Note: this property may be manipulated by higher-level dragging semantics.

      If useNativeDrag is true and this widget has been drawn, then this widget must be redrawn in order for a change of the value of this attribute to take effect.

      Returns:
      Current canDrag value. Default value is false
      See Also:
    • setCanDragReposition

      public Canvas setCanDragReposition(Boolean canDragReposition)
      Indicates whether this widget can be moved by a user of your application by simply dragging with the mouse.

      Note : This is an advanced setting

      Parameters:
      canDragReposition - New canDragReposition value. Default value is false
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getCanDragReposition

      public Boolean getCanDragReposition()
      Indicates whether this widget can be moved by a user of your application by simply dragging with the mouse.
      Returns:
      Current canDragReposition value. Default value is false
      See Also:
    • setCanDragResize

      public Canvas setCanDragResize(Boolean canDragResize)
      Indicates whether this widget can be resized by dragging on the edges and/or corners of the widget with the mouse.

      Note : This is an advanced setting

      Parameters:
      canDragResize - New canDragResize value. Default value is false
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getCanDragResize

      public Boolean getCanDragResize()
      Indicates whether this widget can be resized by dragging on the edges and/or corners of the widget with the mouse.
      Returns:
      Current canDragResize value. Default value is false
      See Also:
    • setCanDragScroll

      public Canvas setCanDragScroll(boolean canDragScroll)
      If this Canvas is canAcceptDrop:true, when the user drags a droppable widget over an edge of the widget, should we scroll to show the rest of the widget's content? Returned from canvas.shouldDragScroll() if there are scrollbars.

      Note : This is an advanced setting

      Parameters:
      canDragScroll - New canDragScroll value. Default value is true
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getCanDragScroll

      public boolean getCanDragScroll()
      If this Canvas is canAcceptDrop:true, when the user drags a droppable widget over an edge of the widget, should we scroll to show the rest of the widget's content? Returned from canvas.shouldDragScroll() if there are scrollbars.
      Returns:
      Current canDragScroll value. Default value is true
      See Also:
    • setCanDrop

      public Canvas setCanDrop(Boolean canDrop)
      Indicates that this object can be dropped on top of other widgets. Only valid if canDrag or canDragReposition is true.

      Note : This is an advanced setting

      Parameters:
      canDrop - New canDrop value. Default value is false
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getCanDrop

      public Boolean getCanDrop()
      Indicates that this object can be dropped on top of other widgets. Only valid if canDrag or canDragReposition is true.
      Returns:
      Current canDrop value. Default value is false
      See Also:
    • setCanDropBefore

      public Canvas setCanDropBefore(Boolean canDropBefore)
      When explicitly set to false, disallows drop before this member in the Layout.

      Note : This is an advanced setting

      Parameters:
      canDropBefore - New canDropBefore value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getCanDropBefore

      public Boolean getCanDropBefore()
      When explicitly set to false, disallows drop before this member in the Layout.
      Returns:
      Current canDropBefore value. Default value is null
      See Also:
    • setCanFocus

      public Canvas setCanFocus(Boolean canFocus)
      Can this widget be allowed to become the target of keyboard events?

      If canFocus is unset (the default), only scrollable widgets with visible scrollbars are focusable, to allow for keyboard scrolling.

      A widget normally receives focus by being clicked on or tabbed to.

      If this method is called after the component has been drawn/initialized: Change whether a widget can accept keyboard focus.

      Note : This is an advanced setting

      Parameters:
      canFocus - whether the widget should now accept focus. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getCanFocus

      public Boolean getCanFocus()
      Can this widget be allowed to become the target of keyboard events?

      If canFocus is unset (the default), only scrollable widgets with visible scrollbars are focusable, to allow for keyboard scrolling.

      A widget normally receives focus by being clicked on or tabbed to.

      Returns:
      Current canFocus value. Default value is null
      See Also:
    • setCanHover

      public Canvas setCanHover(Boolean canHover)
      Will this Canvas fire hover events when the user hovers over it, or one of its children?
      Parameters:
      canHover - New canHover value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getCanHover

      public Boolean getCanHover()
      Will this Canvas fire hover events when the user hovers over it, or one of its children?
      Returns:
      Current canHover value. Default value is null
      See Also:
    • setCanSelectText

      public Canvas setCanSelectText(Boolean canSelectText)
      Whether native drag selection of contained text is allowed within this Canvas.

      Note that setting this property to false will not avoid text selection which is initiated outside this Canvas from continuing into this Canvas, even if text selection began in another Canvas.

      Note : This is an advanced setting

      Parameters:
      canSelectText - New canSelectText value. Default value is false
      Returns:
      Canvas instance, for chaining setter calls
    • getCanSelectText

      public Boolean getCanSelectText()
      Whether native drag selection of contained text is allowed within this Canvas.

      Note that setting this property to false will not avoid text selection which is initiated outside this Canvas from continuing into this Canvas, even if text selection began in another Canvas.

      Returns:
      Current canSelectText value. Default value is false
    • getCanvasItem

      public CanvasItem getCanvasItem() throws IllegalStateException
      If this canvas is being displayed in a CanvasItem, this property will be set to point at the item. Otherwise this property will be null.

      Note : This method should be called only after the widget has been rendered.

      Returns:
      Current canvasItem value. Default value is null
      Throws:
      IllegalStateException - if this widget has not yet been rendered.
    • getChildren

      public Canvas[] getChildren()
      Array of all Canvii that are immediate children of this Canvas.

      Use addChild() and removeChild() to add and remove children after a Canvas has been created/drawn.

      See Containment for an overview of parent/child relationships.

      Returns:
      Current children value. Default value is null
      See Also:
    • setChildrenResizeSnapAlign

      public Canvas setChildrenResizeSnapAlign(Boolean childrenResizeSnapAlign)
      Flag to disable snapping to alignment when children of this Canvas are resized
      Parameters:
      childrenResizeSnapAlign - New childrenResizeSnapAlign value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getChildrenResizeSnapAlign

      public Boolean getChildrenResizeSnapAlign()
      Flag to disable snapping to alignment when children of this Canvas are resized
      Returns:
      Current childrenResizeSnapAlign value. Default value is null
      See Also:
    • setChildrenSnapAlign

      public Canvas setChildrenSnapAlign(Boolean childrenSnapAlign)
      If enabled while childrenSnapToGrid is enabled, children dragged within this Canvas will also snap to positions where their edges or center lines would be aligned with the edges or centers of other components, and lines will be shown to point out the possible alignment (with appearance controlled by snapAlignCenterLineStyle and snapAlignEdgeLineStyle respectively.

      By default, edge- or center-snapping is enabled for all components, but the set of eligible components can be explicitly set via snapAlignCandidates.

      See also childrenSnapCenterAlign and childrenSnapEdgeAlign for enabling or disabling center alignment or edge alignment individually.

      Parameters:
      childrenSnapAlign - New childrenSnapAlign value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getChildrenSnapAlign

      public Boolean getChildrenSnapAlign()
      If enabled while childrenSnapToGrid is enabled, children dragged within this Canvas will also snap to positions where their edges or center lines would be aligned with the edges or centers of other components, and lines will be shown to point out the possible alignment (with appearance controlled by snapAlignCenterLineStyle and snapAlignEdgeLineStyle respectively.

      By default, edge- or center-snapping is enabled for all components, but the set of eligible components can be explicitly set via snapAlignCandidates.

      See also childrenSnapCenterAlign and childrenSnapEdgeAlign for enabling or disabling center alignment or edge alignment individually.

      Returns:
      Current childrenSnapAlign value. Default value is null
      See Also:
    • setChildrenSnapCenterAlign

      public Canvas setChildrenSnapCenterAlign(Boolean childrenSnapCenterAlign)
      See childrenSnapAlign. This setting enables or disables snapping on center alignment only.
      Parameters:
      childrenSnapCenterAlign - New childrenSnapCenterAlign value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getChildrenSnapCenterAlign

      public Boolean getChildrenSnapCenterAlign()
      See childrenSnapAlign. This setting enables or disables snapping on center alignment only.
      Returns:
      Current childrenSnapCenterAlign value. Default value is null
      See Also:
    • setChildrenSnapEdgeAlign

      public Canvas setChildrenSnapEdgeAlign(Boolean childrenSnapEdgeAlign)
      See childrenSnapAlign. This setting enables or disables snapping on edge alignment only.
      Parameters:
      childrenSnapEdgeAlign - New childrenSnapEdgeAlign value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getChildrenSnapEdgeAlign

      public Boolean getChildrenSnapEdgeAlign()
      See childrenSnapAlign. This setting enables or disables snapping on edge alignment only.
      Returns:
      Current childrenSnapEdgeAlign value. Default value is null
      See Also:
    • setChildrenSnapResizeToGrid

      public Canvas setChildrenSnapResizeToGrid(Boolean childrenSnapResizeToGrid)
      If true, causes this canvas's children to snap to its grid when resizing. This behavior can be overridden on a per-child basis by setting the snapToGrid or snapResizeToGrid value on the child.
      Parameters:
      childrenSnapResizeToGrid - New childrenSnapResizeToGrid value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getChildrenSnapResizeToGrid

      public Boolean getChildrenSnapResizeToGrid()
      If true, causes this canvas's children to snap to its grid when resizing. This behavior can be overridden on a per-child basis by setting the snapToGrid or snapResizeToGrid value on the child.
      Returns:
      Current childrenSnapResizeToGrid value. Default value is null
      See Also:
    • setChildrenSnapToGrid

      public Canvas setChildrenSnapToGrid(Boolean childrenSnapToGrid)
      If true, causes this canvas's children to snap to its grid when dragging. This behavior can be overridden on a per-child basis by setting the snapToGrid value on the child.
      Parameters:
      childrenSnapToGrid - New childrenSnapToGrid value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getChildrenSnapToGrid

      public Boolean getChildrenSnapToGrid()
      If true, causes this canvas's children to snap to its grid when dragging. This behavior can be overridden on a per-child basis by setting the snapToGrid value on the child.
      Returns:
      Current childrenSnapToGrid value. Default value is null
      See Also:
    • getComponentMask

      public Canvas getComponentMask() throws IllegalStateException
      Automatically generated mask canvas displayed when showComponentMask() is called.

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

      Returns:
      Current componentMask value. Default value is null
      Throws:
      IllegalStateException - if this widget has not yet been rendered.
      See Also:
    • setComponentMaskDefaults

      public Canvas setComponentMaskDefaults(Canvas componentMaskDefaults) throws IllegalStateException
      Defaults for the componentMask autoChild. Default properties include backgroundColor being set to "black" and opacity being set to 20.
      Parameters:
      componentMaskDefaults - New componentMaskDefaults value. Default value is {...}
      Returns:
      Canvas instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:
    • getComponentMaskDefaults

      public Canvas getComponentMaskDefaults()
      Defaults for the componentMask autoChild. Default properties include backgroundColor being set to "black" and opacity being set to 20.
      Returns:
      Current componentMaskDefaults value. Default value is {...}
    • setContents

      public Canvas setContents(String contents)
      The contents of a canvas or label widget. Any HTML string is acceptable.

      If this method is called after the component has been drawn/initialized: Changes the contents of a widget to newContents, an HTML string.

      When dynamicContents is set, setContents() can also be called with no arguments to cause contents to be re-evaluated.

      Note : This is an advanced setting

      Parameters:
      contents - an HTML string to be set as the contents of this widget. Default value is " "
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getContents

      public String getContents()
      The contents of a canvas or label widget. Any HTML string is acceptable.
      Returns:
      Returns the contents of a Canvas. The contents are an HTML string. Default value is " "
      See Also:
    • setContextMenu

      public Canvas setContextMenu(Menu contextMenu)
      Context menu to show for this object, an instance of the Menu widget.

      Note: if destroy() is called on a canvas, any specified context menu is not automatically destroyed as well. This is in contrast to MenuButtons which automatically destroy their specified MenuButton.menu by default. The behavior is intentional as context menus are commonly reused across components.

      Note : This is an advanced setting

      Parameters:
      contextMenu - New contextMenu value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getContextMenu

      public Menu getContextMenu()
      Context menu to show for this object, an instance of the Menu widget.

      Note: if destroy() is called on a canvas, any specified context menu is not automatically destroyed as well. This is in contrast to MenuButtons which automatically destroy their specified MenuButton.menu by default. The behavior is intentional as context menus are commonly reused across components.

      Returns:
      Current contextMenu value. Default value is null
      See Also:
    • setCorrectZoomOverflow

      public Canvas setCorrectZoomOverflow(Boolean correctZoomOverflow)
      Whether the Framework should correct for erroneous scrollHeight and scrollWidth values reported by the browser when zoomed (via browser or OS-level zoom) by allowing maxZoomOverflowError of overflow before enabling scrolling and displaying custom scrollbars. Only relevant when overflow is "auto".

      This property is defaulted to true in the Canvas prototype for those browsers where the situation has been observed, except for Firefox, where a better solution is applied that doesn't rely on maxZoomOverflowError and never clips any content. Setting this property false will disable the workaround for all browsers, including Firefox. Without a workaround, scrollbars may oscillate rapidly when the browser or OS is zoomed.

      Note : This is an advanced setting

      Parameters:
      correctZoomOverflow - New correctZoomOverflow value. Default value is varies
      Returns:
      Canvas instance, for chaining setter calls
    • getCorrectZoomOverflow

      public Boolean getCorrectZoomOverflow()
      Whether the Framework should correct for erroneous scrollHeight and scrollWidth values reported by the browser when zoomed (via browser or OS-level zoom) by allowing maxZoomOverflowError of overflow before enabling scrolling and displaying custom scrollbars. Only relevant when overflow is "auto".

      This property is defaulted to true in the Canvas prototype for those browsers where the situation has been observed, except for Firefox, where a better solution is applied that doesn't rely on maxZoomOverflowError and never clips any content. Setting this property false will disable the workaround for all browsers, including Firefox. Without a workaround, scrollbars may oscillate rapidly when the browser or OS is zoomed.

      Returns:
      Current correctZoomOverflow value. Default value is varies
    • setCursor

      public Canvas setCursor(Cursor cursor)
      Specifies the css cursor image to display when the mouse pointer is over this component. See Cursor for valid values.

      Note that the cursor may also be controlled by the following attributes in various cases:

      If no cursor is explicitly specified for a component, the cursor will be derived from the component's ancestors. If cursor is not explicitly set in the ancestor chain, "default" will be used.

      If this method is called after the component has been drawn/initialized: Sets the cursor for this widget to cursor. See the cursor property for possible values.

      Note : This is an advanced setting

      Parameters:
      cursor - new cursor. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getCursor

      public Cursor getCursor()
      Specifies the css cursor image to display when the mouse pointer is over this component. See Cursor for valid values.

      Note that the cursor may also be controlled by the following attributes in various cases:

      If no cursor is explicitly specified for a component, the cursor will be derived from the component's ancestors. If cursor is not explicitly set in the ancestor chain, "default" will be used.

      Returns:
      Current cursor value. Default value is null
      See Also:
    • setDataContext

      public Canvas setDataContext(DataContext dataContext)
      A mapping from DataSource IDs to specific Records from those DataSources, that DataBoundComponents contained within this Canvas should automatically bind to if a DataSource is provided but data is not provided (directly or indirectly, for example, indirectly via setting ListGrid.autoFetchData.

      See autoPopulateData for details on how this is done.

      DataSources included in the dataContext are immediately provided to rule context when used if no other component has done so already. These records are found in rule context 'dataContext' section (ex. dataContext.Customer for a Customer record in dataContext) so they do not conflict with normal DataSource records.

      If this method is called after the component has been drawn/initialized: Provides a new DataContext to the Canvas. If the DataContext is new, DataBoundComponents contained within this Canvas will be automatically bound as described in dataContext. If the DataContext replaces an existing one, any contained components that were originally bound against the DataContext will be re-bound.

      Parameters:
      dataContext - dataContext to use for automatic binding. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
    • getDataContext

      public DataContext getDataContext()
      A mapping from DataSource IDs to specific Records from those DataSources, that DataBoundComponents contained within this Canvas should automatically bind to if a DataSource is provided but data is not provided (directly or indirectly, for example, indirectly via setting ListGrid.autoFetchData.

      See autoPopulateData for details on how this is done.

      DataSources included in the dataContext are immediately provided to rule context when used if no other component has done so already. These records are found in rule context 'dataContext' section (ex. dataContext.Customer for a Customer record in dataContext) so they do not conflict with normal DataSource records.

      Returns:
      Current dataContext value. Default value is null
    • setDataPath

      public Canvas setDataPath(String dataPath)
      A dataPath may be specified on any canvas. This provides a straightforward way to display or edit complex nested data.

      NOTE: the dataPath feature is intended to help certain legacy architectures, such as systems that work in terms of exchanging large messages with several different entity types in one message, and are incapable of providing separate access to each entity type.
      See the DataPath overview for more information.

      For components which support displaying or editing data values, (such as DynamicForm or ListGrid components), the dataPath may be set to specify how the components data is accessed. In this case the dataPath essentially specifies a nested object to edit - typically a path to a field value within a dataSource record. Note that a ValuesManager will be required to handle connecting the dataBoundcomponent to the appropriate sub object. This may be explicitly specified on the component, or a parent of the component, or automatically generated if a DataSource is specified on either the component or a parent thereof.

      To provide a simple example - if a complex object existed with the following format:

             Map values = new HashMap();
             values.put("companyName", "Some company");
             Map addressMap = new HashMap();
             addressMap.put("street", "123 Main Street");
             addressMap.put("city", "New York");
             addressMap.put("state", "NY");
             values.put("address", addressMap);
        
      a developer could specify a DynamicForm instance with 'dataPath' set to "address" to edit the nested address object:
             ValuesManager vm = new ValuesManager();
             Map values = new HashMap();
             values.put("companyName", "Some company");
             Map addressMap = new HashMap();
             addressMap.put("street", "123 Main Street");
             addressMap.put("city", "New York");
             addressMap.put("state", "NY");
             values.put("address", addressMap);
             vm.setValues(values);
       
             DynamicForm form = new DynamicForm();
             form.setValuesManager(vm);
             form.setDataPath("address");  
             TextItem streetField = new TextItem("street");
             TextItem cityField = new TextItem("city");
             TextItem stateField = new TextItem("state");
             form.setItems(streetField, cityField, stateField);
        
      If a component is specified with a dataPath attribute but does not have an explicitly specified valuesManager, it will check its parent element chain for a specified valuesManager and automatically bind to that. This simplifies binding multiple components used to view or edit a nested data structure as the valuesManager needs only be defined once at a reasonably high level component. Here's an example of this approach:
             ValuesManager vm = new ValuesManager();
             Map values = new HashMap();
             values.put("companyName", "Some company");
             Map addressMap = new HashMap();
             addressMap.put("street", "123 Main Street");
             addressMap.put("city", "New York");
             addressMap.put("state", "NY");
             values.put("address", addressMap);
             vm.setValues(values);
       
             Layout layout = new Layout();
             layout.setValuesManager(vm);
       
             DynamicForm form = new DynamicForm();
             form.setDataPath("/");  
             TextItem companyNameField = new TextItem("companyName");
             form.setItems(companyNameField);
       
             DynamicForm form1 = new DynamicForm();
             form1.setDataPath("address");  
             TextItem streetField = new TextItem("street");
             TextItem cityField = new TextItem("city");
             TextItem stateField = new TextItem("state");
             form1.setItems(streetField, cityField, stateField);
       
             layout.addMember(form);
             layout.addMember(form1);
        
      Note that in this case the valuesManager is specified on a Layout, which has no 'values' management behavior of its own, but contains items with a specified dataPath which do. In this example you'd see 2 forms allowing editing of the nested data structure.

      dataPaths from multiple nested components may also be combined. For example:

             ValuesManager vm = new ValuesManager();
       
             Map values = new HashMap();
             values.put("companyName", "Some company");
             Map addressMap = new HashMap();
             addressMap.put("street", "123 Main Street");
             addressMap.put("city", "New York");
             addressMap.put("state", "NY");
             values.put("address", addressMap);
       
             Map values1 = new HashMap();
             values1.put("companyName", "Some Corporation");
             Map addressMap1 = new HashMap();
             addressMap1.put("street", "1 High Street");
             addressMap1.put("city", "New York");
             addressMap1.put("state", "NY");
             values1.put("address", addressMap1);
             values.put("parentCompany", values1);
       
             vm.setValues(values);
             Layout layout = new Layout();
             layout.setValuesManager(vm);
       
             DynamicForm form = new DynamicForm();
             form.setDataPath("/");  
             TextItem companyNameField = new TextItem("companyName");
             form.setItems(companyNameField);
       
             DynamicForm form1 = new DynamicForm();
             form1.setDataPath("address");  
             TextItem streetField = new TextItem("street");
             TextItem cityField = new TextItem("city");
             TextItem stateField = new TextItem("state");
             form1.setItems(streetField, cityField, stateField);
       
             Layout innerlayout = new Layout();
             innerlayout.setDataPath("parentCompany");
       
             DynamicForm form3 = new DynamicForm();
             form3.setDataPath("");  
             StaticTextItem companyNameField1 = new StaticTextItem("companyName");
             form3.setItems(companyNameField1);
       
             DetailViewer detailViewer = new DetailViewer();
             detailViewer.setDataPath("address");  
             DetailViewerField streetDVField = new DetailViewerField("street");
             DetailViewerField cityDVField = new DetailViewerField("city");
             DetailViewerField stateDVField = new DetailViewerField("state");
             detailViewer.setFields(streetDVField, cityDVField, stateDVField);
       
             innerlayout.addMember(form3);
             innerlayout.addMember(detailViewer);
       
             layout.addMember(form);
             layout.addMember(form1);
             layout.addMember(innerlayout);
        
      In this example the detailViewer will display data from the parentCompany.address object within the base record.

      Note that if a component has a specified dataSource and shows child components with a specified dataPath, there is no need to explicitly declare a valuesManager at all. If a component with a dataPath has a dataSource, or an ancestor with a dataSource specified, it will, a valuesManager will automatically be generated on the higher level component (and be available as component.valuesManager).

      Difference between "" and "/" - relative and absolute datapaths

      In the above example, note how the form for entering the "main" company name is given a dataPath of "/", while the form for entering the parent company name is given a dataPath of "". The difference here is exactly the same as you would find in a filesystem path: a dataPath starting with "/" is absolute, so "/" by itself means "root". A dataPath that does not start with "/" is relative, and the empty string indicates that dataPaths for items below this one in the hierarchy should apply the dataPath so far from the hierarchy above.

      If that isn't clear, consider the form for entering the parent company name in the above example. The correct dataPath to the field is /parentCompany/companyName. We have the "parentCompany" part of that path provided by the containing Layout, so we cannot reiterate it on the form itself. However, if we omit the dataPath property altogether, the framework will not seek to apply dataPath at all. So, we specify the empty string, which tells Smart GWT to use dataPath and to retain the portion of the path derived so far from the containment hierarchy.

      One further clarification: relative paths are only different from absolute paths if they are relative to something other than the root. So in the above example, although we specify "/" as the dataPath of the "main" company name form, we would get exactly the same behavior by specifying it as "", because the correct dataPath for the companyName field is "/companyName" - ie, it is relative to the root.

      If this method is called after the component has been drawn/initialized: Setter for the dataPath attribute. This method may be called directly at runtime to set the dataPath on a component, and will also be re-run automatically whenever a canvas' parent changes due to a call to addChild(). This method handles automatically binding the component to the appropriate valuesManager if necessary.

      Note : This is an advanced setting

      Parameters:
      dataPath - new dataPath. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getDataPath

      public String getDataPath()
      A dataPath may be specified on any canvas. This provides a straightforward way to display or edit complex nested data.

      NOTE: the dataPath feature is intended to help certain legacy architectures, such as systems that work in terms of exchanging large messages with several different entity types in one message, and are incapable of providing separate access to each entity type.
      See the DataPath overview for more information.

      For components which support displaying or editing data values, (such as DynamicForm or ListGrid components), the dataPath may be set to specify how the components data is accessed. In this case the dataPath essentially specifies a nested object to edit - typically a path to a field value within a dataSource record. Note that a ValuesManager will be required to handle connecting the dataBoundcomponent to the appropriate sub object. This may be explicitly specified on the component, or a parent of the component, or automatically generated if a DataSource is specified on either the component or a parent thereof.

      To provide a simple example - if a complex object existed with the following format:

             Map values = new HashMap();
             values.put("companyName", "Some company");
             Map addressMap = new HashMap();
             addressMap.put("street", "123 Main Street");
             addressMap.put("city", "New York");
             addressMap.put("state", "NY");
             values.put("address", addressMap);
        
      a developer could specify a DynamicForm instance with 'dataPath' set to "address" to edit the nested address object:
             ValuesManager vm = new ValuesManager();
             Map values = new HashMap();
             values.put("companyName", "Some company");
             Map addressMap = new HashMap();
             addressMap.put("street", "123 Main Street");
             addressMap.put("city", "New York");
             addressMap.put("state", "NY");
             values.put("address", addressMap);
             vm.setValues(values);
       
             DynamicForm form = new DynamicForm();
             form.setValuesManager(vm);
             form.setDataPath("address");  
             TextItem streetField = new TextItem("street");
             TextItem cityField = new TextItem("city");
             TextItem stateField = new TextItem("state");
             form.setItems(streetField, cityField, stateField);
        
      If a component is specified with a dataPath attribute but does not have an explicitly specified valuesManager, it will check its parent element chain for a specified valuesManager and automatically bind to that. This simplifies binding multiple components used to view or edit a nested data structure as the valuesManager needs only be defined once at a reasonably high level component. Here's an example of this approach:
             ValuesManager vm = new ValuesManager();
             Map values = new HashMap();
             values.put("companyName", "Some company");
             Map addressMap = new HashMap();
             addressMap.put("street", "123 Main Street");
             addressMap.put("city", "New York");
             addressMap.put("state", "NY");
             values.put("address", addressMap);
             vm.setValues(values);
       
             Layout layout = new Layout();
             layout.setValuesManager(vm);
       
             DynamicForm form = new DynamicForm();
             form.setDataPath("/");  
             TextItem companyNameField = new TextItem("companyName");
             form.setItems(companyNameField);
       
             DynamicForm form1 = new DynamicForm();
             form1.setDataPath("address");  
             TextItem streetField = new TextItem("street");
             TextItem cityField = new TextItem("city");
             TextItem stateField = new TextItem("state");
             form1.setItems(streetField, cityField, stateField);
       
             layout.addMember(form);
             layout.addMember(form1);
        
      Note that in this case the valuesManager is specified on a Layout, which has no 'values' management behavior of its own, but contains items with a specified dataPath which do. In this example you'd see 2 forms allowing editing of the nested data structure.

      dataPaths from multiple nested components may also be combined. For example:

             ValuesManager vm = new ValuesManager();
       
             Map values = new HashMap();
             values.put("companyName", "Some company");
             Map addressMap = new HashMap();
             addressMap.put("street", "123 Main Street");
             addressMap.put("city", "New York");
             addressMap.put("state", "NY");
             values.put("address", addressMap);
       
             Map values1 = new HashMap();
             values1.put("companyName", "Some Corporation");
             Map addressMap1 = new HashMap();
             addressMap1.put("street", "1 High Street");
             addressMap1.put("city", "New York");
             addressMap1.put("state", "NY");
             values1.put("address", addressMap1);
             values.put("parentCompany", values1);
       
             vm.setValues(values);
             Layout layout = new Layout();
             layout.setValuesManager(vm);
       
             DynamicForm form = new DynamicForm();
             form.setDataPath("/");  
             TextItem companyNameField = new TextItem("companyName");
             form.setItems(companyNameField);
       
             DynamicForm form1 = new DynamicForm();
             form1.setDataPath("address");  
             TextItem streetField = new TextItem("street");
             TextItem cityField = new TextItem("city");
             TextItem stateField = new TextItem("state");
             form1.setItems(streetField, cityField, stateField);
       
             Layout innerlayout = new Layout();
             innerlayout.setDataPath("parentCompany");
       
             DynamicForm form3 = new DynamicForm();
             form3.setDataPath("");  
             StaticTextItem companyNameField1 = new StaticTextItem("companyName");
             form3.setItems(companyNameField1);
       
             DetailViewer detailViewer = new DetailViewer();
             detailViewer.setDataPath("address");  
             DetailViewerField streetDVField = new DetailViewerField("street");
             DetailViewerField cityDVField = new DetailViewerField("city");
             DetailViewerField stateDVField = new DetailViewerField("state");
             detailViewer.setFields(streetDVField, cityDVField, stateDVField);
       
             innerlayout.addMember(form3);
             innerlayout.addMember(detailViewer);
       
             layout.addMember(form);
             layout.addMember(form1);
             layout.addMember(innerlayout);
        
      In this example the detailViewer will display data from the parentCompany.address object within the base record.

      Note that if a component has a specified dataSource and shows child components with a specified dataPath, there is no need to explicitly declare a valuesManager at all. If a component with a dataPath has a dataSource, or an ancestor with a dataSource specified, it will, a valuesManager will automatically be generated on the higher level component (and be available as component.valuesManager).

      Difference between "" and "/" - relative and absolute datapaths

      In the above example, note how the form for entering the "main" company name is given a dataPath of "/", while the form for entering the parent company name is given a dataPath of "". The difference here is exactly the same as you would find in a filesystem path: a dataPath starting with "/" is absolute, so "/" by itself means "root". A dataPath that does not start with "/" is relative, and the empty string indicates that dataPaths for items below this one in the hierarchy should apply the dataPath so far from the hierarchy above.

      If that isn't clear, consider the form for entering the parent company name in the above example. The correct dataPath to the field is /parentCompany/companyName. We have the "parentCompany" part of that path provided by the containing Layout, so we cannot reiterate it on the form itself. However, if we omit the dataPath property altogether, the framework will not seek to apply dataPath at all. So, we specify the empty string, which tells Smart GWT to use dataPath and to retain the portion of the path derived so far from the containment hierarchy.

      One further clarification: relative paths are only different from absolute paths if they are relative to something other than the root. So in the above example, although we specify "/" as the dataPath of the "main" company name form, we would get exactly the same behavior by specifying it as "", because the correct dataPath for the companyName field is "/companyName" - ie, it is relative to the root.

      Returns:
      Current dataPath value. Default value is null
      See Also:
    • setDefaultHeight

      public Canvas setDefaultHeight(int defaultHeight)
      For custom components, establishes a default height for the component.

      For a component that should potentially be sized automatically by a Layout, set this property rather than height directly, because Layouts regard a height setting as an explicit size that shouldn't be changed.

      Note : This is an advanced setting

      Parameters:
      defaultHeight - New defaultHeight value. Default value is 100
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getDefaultHeight

      public int getDefaultHeight()
      For custom components, establishes a default height for the component.

      For a component that should potentially be sized automatically by a Layout, set this property rather than height directly, because Layouts regard a height setting as an explicit size that shouldn't be changed.

      Returns:
      Current defaultHeight value. Default value is 100
      See Also:
    • setDefaultWidth

      public Canvas setDefaultWidth(int defaultWidth)
      For custom components, establishes a default width for the component.

      For a component that should potentially be sized automatically by a Layout, set this property rather than width directly, because Layouts regard a width setting as an explicit size that shouldn't be changed.

      Note : This is an advanced setting

      Parameters:
      defaultWidth - New defaultWidth value. Default value is 100
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getDefaultWidth

      public int getDefaultWidth()
      For custom components, establishes a default width for the component.

      For a component that should potentially be sized automatically by a Layout, set this property rather than width directly, because Layouts regard a width setting as an explicit size that shouldn't be changed.

      Returns:
      Current defaultWidth value. Default value is 100
      See Also:
    • setDefiningProperty

      public Canvas setDefiningProperty(String definingProperty)
      This attribute denotes the name of a property to use as a getDefiningPropertyName() for this property when generating and resolving AutoTest locators with search segments.

      Note : This is an advanced setting

      Parameters:
      definingProperty - New definingProperty value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
    • getDefiningProperty

      public String getDefiningProperty()
      This attribute denotes the name of a property to use as a getDefiningPropertyName() for this property when generating and resolving AutoTest locators with search segments.
      Returns:
      Current definingProperty value. Default value is null
    • setDefiningPropertyNameOptions

      public Canvas setDefiningPropertyNameOptions(String... definingPropertyNameOptions)
      If no explicit definingProperty was specified for this component, this array denotes a list of options to use as a defining property when generating and resolving AutoTest locators with search segments. The first attribute in this array that is non-null for this component will be used as the defining property for locator search segments.

      The default set of options are as follows:

        [
         "locatorName",
         "dataSource"
        ]
        

      Note : This is an advanced setting

      Parameters:
      definingPropertyNameOptions - New definingPropertyNameOptions value. Default value is [...]
      Returns:
      Canvas instance, for chaining setter calls
    • getDefiningPropertyNameOptions

      public String[] getDefiningPropertyNameOptions()
      If no explicit definingProperty was specified for this component, this array denotes a list of options to use as a defining property when generating and resolving AutoTest locators with search segments. The first attribute in this array that is non-null for this component will be used as the defining property for locator search segments.

      The default set of options are as follows:

        [
         "locatorName",
         "dataSource"
        ]
        
      Returns:
      Current definingPropertyNameOptions value. Default value is [...]
    • getDestroyed

      public Boolean getDestroyed() throws IllegalStateException
      If this property is set to true, the destroy() method has been called on this canvas. This implies the canvas is no longer valid. Its ID has been removed from global scope, and calling standard canvas APIs on it is likely to result in errors.

      Note : This method should be called only after the widget has been rendered.

      Returns:
      Current destroyed value. Default value is null
      Throws:
      IllegalStateException - if this widget has not yet been rendered.
      See Also:
    • getDestroying

      public Boolean getDestroying() throws IllegalStateException
      This property is set to true when the destroy() method is called on a widget. If this property is true, but destroyed is not, this indicates the canvas is in the process of being destroyed.

      Note : This method should be called only after the widget has been rendered.

      Returns:
      Current destroying value. Default value is null
      Throws:
      IllegalStateException - if this widget has not yet been rendered.
      See Also:
    • setDisabledCursor

      public Canvas setDisabledCursor(Cursor disabledCursor)
      Specifies the cursor image to display when the mouse pointer is over this widget if this widget is disabled. It corresponds to the CSS cursor attribute. See Cursor type for different cursors.

      Note : This is an advanced setting

      Parameters:
      disabledCursor - New disabledCursor value. Default value is Canvas.DEFAULT
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getDisabledCursor

      public Cursor getDisabledCursor()
      Specifies the cursor image to display when the mouse pointer is over this widget if this widget is disabled. It corresponds to the CSS cursor attribute. See Cursor type for different cursors.
      Returns:
      Current disabledCursor value. Default value is Canvas.DEFAULT
      See Also:
    • setDisableTouchScrollingForDrag

      public Canvas setDisableTouchScrollingForDrag(Boolean disableTouchScrollingForDrag) throws IllegalStateException
      Disables useTouchScrolling whenever a built-in drag operation has been enabled which is known to be non-functional if touch scrolling is enabled. Default behavior is to leave touch scrolling enabled even if it makes other enabled drag operations non-functional, since any accessible application must provide an alternative way to perform drag and drop operations anyway.

      disableTouchScrollingForDrag exists so that applications can change the default setting on a per-component basis (via setDefaultProperties), in order to make a system-wide or per-component-type decision about whether to favor touch scrolling vs retaining the ability to drag and drop via finger drags, instead of having to set useTouchScrolling on each individual instance.

      See the Mobile Development overview for more background information.

      Parameters:
      disableTouchScrollingForDrag - New disableTouchScrollingForDrag value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:
    • getDisableTouchScrollingForDrag

      public Boolean getDisableTouchScrollingForDrag()
      Disables useTouchScrolling whenever a built-in drag operation has been enabled which is known to be non-functional if touch scrolling is enabled. Default behavior is to leave touch scrolling enabled even if it makes other enabled drag operations non-functional, since any accessible application must provide an alternative way to perform drag and drop operations anyway.

      disableTouchScrollingForDrag exists so that applications can change the default setting on a per-component basis (via setDefaultProperties), in order to make a system-wide or per-component-type decision about whether to favor touch scrolling vs retaining the ability to drag and drop via finger drags, instead of having to set useTouchScrolling on each individual instance.

      See the Mobile Development overview for more background information.

      Returns:
      Current disableTouchScrollingForDrag value. Default value is null
      See Also:
    • setDoubleClickDelay

      public Canvas setDoubleClickDelay(int doubleClickDelay)
      Amount of time (in milliseconds) between which two clicks are considered a single click

      Note : This is an advanced setting

      Parameters:
      doubleClickDelay - New doubleClickDelay value. Default value is 250
      Returns:
      Canvas instance, for chaining setter calls
    • getDoubleClickDelay

      public int getDoubleClickDelay()
      Amount of time (in milliseconds) between which two clicks are considered a single click
      Returns:
      Current doubleClickDelay value. Default value is 250
    • setDragAppearance

      public Canvas setDragAppearance(DragAppearance dragAppearance)
      Visual appearance to show when the object is being dragged. May be overridden for dragResize or dragReposition events via dragResizeAppearance and dragRepositionAppearance.

      Note : This is an advanced setting

      Parameters:
      dragAppearance - New dragAppearance value. Default value is EventHandler.OUTLINE
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getDragAppearance

      public DragAppearance getDragAppearance()
      Visual appearance to show when the object is being dragged. May be overridden for dragResize or dragReposition events via dragResizeAppearance and dragRepositionAppearance.
      Returns:
      Current dragAppearance value. Default value is EventHandler.OUTLINE
      See Also:
    • setDragIntersectStyle

      public Canvas setDragIntersectStyle(DragIntersectStyle dragIntersectStyle)
      This indicates how the system will test for droppable targets: either by intersection with the mouse or intersection with the rectangle of the dragMoveTarget.

      Note : This is an advanced setting

      Parameters:
      dragIntersectStyle - New dragIntersectStyle value. Default value is "mouse"
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getDragIntersectStyle

      public DragIntersectStyle getDragIntersectStyle()
      This indicates how the system will test for droppable targets: either by intersection with the mouse or intersection with the rectangle of the dragMoveTarget.
      Returns:
      Current dragIntersectStyle value. Default value is "mouse"
      See Also:
    • setDragMaskType

      public Canvas setDragMaskType(DragMaskType dragMaskType)
      This property controls what kind of mask is used in case useDragMask is enabled.
      Parameters:
      dragMaskType - New dragMaskType value. Default value is "div"
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getDragMaskType

      public DragMaskType getDragMaskType()
      This property controls what kind of mask is used in case useDragMask is enabled.
      Returns:
      Current dragMaskType value. Default value is "div"
      See Also:
    • setDragMaxHeight

      public Canvas setDragMaxHeight(int dragMaxHeight)
      Sets maximum height that this Canvas can be resized to by a user. Actual limit will be minimum of dragMaxHeight and maxHeight.

      Note : This is an advanced setting

      Parameters:
      dragMaxHeight - New dragMaxHeight value. Default value is 10000
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getDragMaxHeight

      public int getDragMaxHeight()
      Sets maximum height that this Canvas can be resized to by a user. Actual limit will be minimum of dragMaxHeight and maxHeight.
      Returns:
      Current dragMaxHeight value. Default value is 10000
      See Also:
    • setDragMaxWidth

      public Canvas setDragMaxWidth(int dragMaxWidth)
      Maximum width that this Canvas can be resized to by a user. Actual limit will be minimum of dragMaxWidth and maxWidth.

      Note : This is an advanced setting

      Parameters:
      dragMaxWidth - New dragMaxWidth value. Default value is 10000
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getDragMaxWidth

      public int getDragMaxWidth()
      Maximum width that this Canvas can be resized to by a user. Actual limit will be minimum of dragMaxWidth and maxWidth.
      Returns:
      Current dragMaxWidth value. Default value is 10000
      See Also:
    • setDragMinHeight

      public Canvas setDragMinHeight(int dragMinHeight)
      Minimum height that this Canvas can be resized to by a user. See dragMinWidth for details of behavior.

      Note : This is an advanced setting

      Parameters:
      dragMinHeight - New dragMinHeight value. Default value is 10
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getDragMinHeight

      public int getDragMinHeight()
      Minimum height that this Canvas can be resized to by a user. See dragMinWidth for details of behavior.
      Returns:
      Current dragMinHeight value. Default value is 10
      See Also:
    • setDragMinWidth

      public Canvas setDragMinWidth(int dragMinWidth)
      Minimum width that this Canvas can be resized to by a user. Actual limit will be maximum of dragMinWidth and minWidth.

      Note that a Canvas with overflow:"visible" has an implicit minimize size based on it's contents.

      Note that dragMinWidth affects only user-initiated drag resizes. To set the minimum width of a Canvas embedded in a Layout, you can set +{minWidth}, or Layout.minMemberLength to constrain the minimum size along the length axis of all members of the Layout.

      Note : This is an advanced setting

      Parameters:
      dragMinWidth - New dragMinWidth value. Default value is 10
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getDragMinWidth

      public int getDragMinWidth()
      Minimum width that this Canvas can be resized to by a user. Actual limit will be maximum of dragMinWidth and minWidth.

      Note that a Canvas with overflow:"visible" has an implicit minimize size based on it's contents.

      Note that dragMinWidth affects only user-initiated drag resizes. To set the minimum width of a Canvas embedded in a Layout, you can set +{minWidth}, or Layout.minMemberLength to constrain the minimum size along the length axis of all members of the Layout.

      Returns:
      Current dragMinWidth value. Default value is 10
      See Also:
    • setDragOpacity

      public Canvas setDragOpacity(Integer dragOpacity)
      If this widget has dragAppearance "target", this value specifies the opacity to render the target while it is being dragged. A null value implies we do not modify the opacity.

      Note : This is an advanced setting

      Parameters:
      dragOpacity - New dragOpacity value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getDragOpacity

      public Integer getDragOpacity()
      If this widget has dragAppearance "target", this value specifies the opacity to render the target while it is being dragged. A null value implies we do not modify the opacity.
      Returns:
      Current dragOpacity value. Default value is null
      See Also:
    • setDragRepositionAppearance

      public Canvas setDragRepositionAppearance(DragAppearance dragRepositionAppearance)
      If canDragReposition is true, this attribute specifies the visual appearance to show during drag reposition. If unset dragAppearance will be used.

      Note : This is an advanced setting

      Parameters:
      dragRepositionAppearance - New dragRepositionAppearance value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getDragRepositionAppearance

      public DragAppearance getDragRepositionAppearance()
      If canDragReposition is true, this attribute specifies the visual appearance to show during drag reposition. If unset dragAppearance will be used.
      Returns:
      Current dragRepositionAppearance value. Default value is null
      See Also:
    • setDragRepositionCursor

      public Canvas setDragRepositionCursor(Cursor dragRepositionCursor)
      Cursor to switch to if the mouse is over a widget that is drag repositionable.

      Note : This is an advanced setting

      Parameters:
      dragRepositionCursor - New dragRepositionCursor value. Default value is Canvas.MOVE
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getDragRepositionCursor

      public Cursor getDragRepositionCursor()
      Cursor to switch to if the mouse is over a widget that is drag repositionable.
      Returns:
      Current dragRepositionCursor value. Default value is Canvas.MOVE
      See Also:
    • setDragResizeAppearance

      public Canvas setDragResizeAppearance(DragAppearance dragResizeAppearance)
      If canDragResize is true, this attribute specifies the visual appearance to show during drag resize. If unset dragAppearance will be used.

      Note : This is an advanced setting

      Parameters:
      dragResizeAppearance - New dragResizeAppearance value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getDragResizeAppearance

      public DragAppearance getDragResizeAppearance()
      If canDragResize is true, this attribute specifies the visual appearance to show during drag resize. If unset dragAppearance will be used.
      Returns:
      Current dragResizeAppearance value. Default value is null
      See Also:
    • setDragScrollDelay

      public Canvas setDragScrollDelay(int dragScrollDelay)
      If this widget supports drag-scrolling, This property specifies how many ms the user must hover over the drag-scroll threshold before scrolling begins.

      Note : This is an advanced setting

      Parameters:
      dragScrollDelay - New dragScrollDelay value. Default value is 100
      Returns:
      Canvas instance, for chaining setter calls
    • getDragScrollDelay

      public int getDragScrollDelay()
      If this widget supports drag-scrolling, This property specifies how many ms the user must hover over the drag-scroll threshold before scrolling begins.
      Returns:
      Current dragScrollDelay value. Default value is 100
    • setDragStartDistance

      public Canvas setDragStartDistance(int dragStartDistance)
      Number of pixels the cursor needs to move before the EventHandler starts a drag operation.

      Note : This is an advanced setting

      Parameters:
      dragStartDistance - New dragStartDistance value. Default value is 5
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getDragStartDistance

      public int getDragStartDistance()
      Number of pixels the cursor needs to move before the EventHandler starts a drag operation.
      Returns:
      Current dragStartDistance value. Default value is 5
      See Also:
    • setDragTarget

      public Canvas setDragTarget(Canvas dragTarget)
      A different widget that should be actually dragged when dragging initiates on this widget. One example of this is to have a child widget that drags its parent, as with a drag box. Because the parent automatically repositions its children, setting the drag target of the child to the parent and then dragging the child will result in both widgets being moved.

      Valid dragTarget values are:

      • null (default) [this widget is its own drag target]
      • another widget, or widget ID
      • "parent" drag target is this widget's parentCanvas
      • "top" drag target is this widget's topElement

      Note that for dragging to work as intended, the resizeFrom setting on the dragTarget must be null or a superset of the resizeFrom on this canvas.

      Note : This is an advanced setting

      Parameters:
      dragTarget - New dragTarget value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getDragTarget

      public Canvas getDragTarget()
      A different widget that should be actually dragged when dragging initiates on this widget. One example of this is to have a child widget that drags its parent, as with a drag box. Because the parent automatically repositions its children, setting the drag target of the child to the parent and then dragging the child will result in both widgets being moved.

      Valid dragTarget values are:

      • null (default) [this widget is its own drag target]
      • another widget, or widget ID
      • "parent" drag target is this widget's parentCanvas
      • "top" drag target is this widget's topElement

      Note that for dragging to work as intended, the resizeFrom setting on the dragTarget must be null or a superset of the resizeFrom on this canvas.

      Returns:
      Current dragTarget value. Default value is null
      See Also:
    • setDragTarget

      public Canvas setDragTarget(String dragTarget)
      A different widget that should be actually dragged when dragging initiates on this widget. One example of this is to have a child widget that drags its parent, as with a drag box. Because the parent automatically repositions its children, setting the drag target of the child to the parent and then dragging the child will result in both widgets being moved.

      Valid dragTarget values are:

      • null (default) [this widget is its own drag target]
      • another widget, or widget ID
      • "parent" drag target is this widget's parentCanvas
      • "top" drag target is this widget's topElement

      Note that for dragging to work as intended, the resizeFrom setting on the dragTarget must be null or a superset of the resizeFrom on this canvas.

      Note : This is an advanced setting

      Parameters:
      dragTarget - New dragTarget value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getDragTargetAsString

      public String getDragTargetAsString()
      A different widget that should be actually dragged when dragging initiates on this widget. One example of this is to have a child widget that drags its parent, as with a drag box. Because the parent automatically repositions its children, setting the drag target of the child to the parent and then dragging the child will result in both widgets being moved.

      Valid dragTarget values are:

      • null (default) [this widget is its own drag target]
      • another widget, or widget ID
      • "parent" drag target is this widget's parentCanvas
      • "top" drag target is this widget's topElement

      Note that for dragging to work as intended, the resizeFrom setting on the dragTarget must be null or a superset of the resizeFrom on this canvas.

      Returns:
      Current dragTarget value. Default value is null
      See Also:
    • setDragType

      public Canvas setDragType(String dragType)
      Sets a dragType for this widget used, to be compared to dropTypes on possible drop target widgets. See dropTypes for a full explanation.

      Note : This is an advanced setting

      Parameters:
      dragType - New dragType value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getDragType

      public String getDragType()
      Sets a dragType for this widget used, to be compared to dropTypes on possible drop target widgets. See dropTypes for a full explanation.
      Returns:
      Current dragType value. Default value is null
      See Also:
    • setDropTarget

      public Canvas setDropTarget(Canvas dropTarget)
      Delegates a different widget that should actually be dropped on if the cursor is over this widget when the drop completes. If you're building your own "drop indicator" widget, it may need this property set to the main canvas (receiving the drop) to avoid itself being considered a drop target (causing the indicator to flicker).

      Note : This is an advanced setting

      Parameters:
      dropTarget - New dropTarget value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getDropTarget

      public Canvas getDropTarget()
      Delegates a different widget that should actually be dropped on if the cursor is over this widget when the drop completes. If you're building your own "drop indicator" widget, it may need this property set to the main canvas (receiving the drop) to avoid itself being considered a drop target (causing the indicator to flicker).
      Returns:
      Current dropTarget value. Default value is null
      See Also:
    • setDropTarget

      public Canvas setDropTarget(String dropTarget)
      Delegates a different widget that should actually be dropped on if the cursor is over this widget when the drop completes. If you're building your own "drop indicator" widget, it may need this property set to the main canvas (receiving the drop) to avoid itself being considered a drop target (causing the indicator to flicker).

      Note : This is an advanced setting

      Parameters:
      dropTarget - New dropTarget value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getDropTargetAsString

      public String getDropTargetAsString()
      Delegates a different widget that should actually be dropped on if the cursor is over this widget when the drop completes. If you're building your own "drop indicator" widget, it may need this property set to the main canvas (receiving the drop) to avoid itself being considered a drop target (causing the indicator to flicker).
      Returns:
      Current dropTarget value. Default value is null
      See Also:
    • setDropTypes

      public Canvas setDropTypes(String... dropTypes)
      When a drag and drop interaction occurs, if a dragType is configured on the source widget, it is compared to the dropTypes configured on the target widget, and a drop is only allowed if the dragType is listed in the target widget's dropTypes array.

      The default setting means any dragType is eligible for dropping on this widget, including no dragType setting.

      See also willAcceptDrop() for dynamic determination of drop eligibility.

      Note : This is an advanced setting

      Parameters:
      dropTypes - New dropTypes value. Default value is Canvas.ANYTHING
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getDropTypes

      public String[] getDropTypes()
      When a drag and drop interaction occurs, if a dragType is configured on the source widget, it is compared to the dropTypes configured on the target widget, and a drop is only allowed if the dragType is listed in the target widget's dropTypes array.

      The default setting means any dragType is eligible for dropping on this widget, including no dragType setting.

      See also willAcceptDrop() for dynamic determination of drop eligibility.

      Returns:
      Current dropTypes value. Default value is Canvas.ANYTHING
      See Also:
    • setDropTypes

      public Canvas setDropTypes(String dropTypes)
      When a drag and drop interaction occurs, if a dragType is configured on the source widget, it is compared to the dropTypes configured on the target widget, and a drop is only allowed if the dragType is listed in the target widget's dropTypes array.

      The default setting means any dragType is eligible for dropping on this widget, including no dragType setting.

      See also willAcceptDrop() for dynamic determination of drop eligibility.

      Note : This is an advanced setting

      Parameters:
      dropTypes - New dropTypes value. Default value is Canvas.ANYTHING
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getDropTypesAsString

      public String getDropTypesAsString()
      When a drag and drop interaction occurs, if a dragType is configured on the source widget, it is compared to the dropTypes configured on the target widget, and a drop is only allowed if the dragType is listed in the target widget's dropTypes array.

      The default setting means any dragType is eligible for dropping on this widget, including no dragType setting.

      See also willAcceptDrop() for dynamic determination of drop eligibility.

      Returns:
      Current dropTypes value. Default value is Canvas.ANYTHING
      See Also:
    • setDynamicContents

      public Canvas setDynamicContents(Boolean dynamicContents)
      Dynamic contents allows the contents string to be treated as a simple but powerful template. When this attribute is set to true, JavaScript expressions may be embedded within the contents string, using the format: ${[JavaScript to evaluate]}.

      For example, to include the current date in a templated message, canvas.contents could be set to:
      "Today's date is <b>${new Date().toUSShortDate()}</b>"

      Embedded expressions will be evaluated when the canvas is drawn or redrawn, and the result of the evaluated expression will be displayed to the user. If the expression does not evaluate to a String, the toString() representation of the returned object will be displayed automatically

      Dynamic expressions are evaluated in the scope of the canvas displaying the content, so the this keyword may be used within your expression to refer to the canvas. Developers may also explicitly supply values for variables to be used within the evaluation via the dynamicContentsVars property.

      Notes:

      • Calling markForRedraw() on the canvas will evaluate any embedded expressions.
      • Multiple such expressions may be embedded within the contents string for a component.
      • If an error occurs during evaluation, a warning is logged to the Developer Console and the error string will be embedded in place of the expected value in the Canvas.

      Note : This is an advanced setting

      Parameters:
      dynamicContents - New dynamicContents value. Default value is false
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getDynamicContents

      public Boolean getDynamicContents()
      Dynamic contents allows the contents string to be treated as a simple but powerful template. When this attribute is set to true, JavaScript expressions may be embedded within the contents string, using the format: ${[JavaScript to evaluate]}.

      For example, to include the current date in a templated message, canvas.contents could be set to:
      "Today's date is <b>${new Date().toUSShortDate()}</b>"

      Embedded expressions will be evaluated when the canvas is drawn or redrawn, and the result of the evaluated expression will be displayed to the user. If the expression does not evaluate to a String, the toString() representation of the returned object will be displayed automatically

      Dynamic expressions are evaluated in the scope of the canvas displaying the content, so the this keyword may be used within your expression to refer to the canvas. Developers may also explicitly supply values for variables to be used within the evaluation via the dynamicContentsVars property.

      Notes:

      • Calling markForRedraw() on the canvas will evaluate any embedded expressions.
      • Multiple such expressions may be embedded within the contents string for a component.
      • If an error occurs during evaluation, a warning is logged to the Developer Console and the error string will be embedded in place of the expected value in the Canvas.
      Returns:
      Current dynamicContents value. Default value is false
      See Also:
      • getContents()
      • com.smartgwt.client.widgets.Canvas#getDynamicContentsVars
    • setEdgeBackgroundColor

      public Canvas setEdgeBackgroundColor(String edgeBackgroundColor) throws IllegalStateException
      Background color for the EdgedCanvas created to decorate this component. This can be used to provide an underlying "tint" color for translucent edge media
      Parameters:
      edgeBackgroundColor - New edgeBackgroundColor value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:
    • getEdgeBackgroundColor

      public String getEdgeBackgroundColor()
      Background color for the EdgedCanvas created to decorate this component. This can be used to provide an underlying "tint" color for translucent edge media
      Returns:
      Current edgeBackgroundColor value. Default value is null
      See Also:
    • setEdgeCenterBackgroundColor

      public Canvas setEdgeCenterBackgroundColor(String edgeCenterBackgroundColor) throws IllegalStateException
      Background color for the center section only. Can be used as a surrogate background color for the decorated Canvas, if the Canvas is set to partially overlap the edges and hence can't show a background color itself without occluding media.
      Parameters:
      edgeCenterBackgroundColor - New edgeCenterBackgroundColor value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:
    • getEdgeCenterBackgroundColor

      public String getEdgeCenterBackgroundColor()
      Background color for the center section only. Can be used as a surrogate background color for the decorated Canvas, if the Canvas is set to partially overlap the edges and hence can't show a background color itself without occluding media.
      Returns:
      Current edgeCenterBackgroundColor value. Default value is null
      See Also:
    • setEdgeImage

      public Canvas setEdgeImage(String edgeImage) throws IllegalStateException
      Base name of images for edges. Extensions for each corner or edge piece will be added to this image URL, before the extension. For example, with the default base name of "edge.gif", the top-left corner image will be "edge_TL.gif".

      The full list of extensions is: "_TL", "_TR", "_BL", "_BR", "_T", "_L", "_B", "_R", "_center".

      Parameters:
      edgeImage - New edgeImage value. Default value is "[SKIN]edge.gif"
      Returns:
      Canvas instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:
    • getEdgeImage

      public String getEdgeImage()
      Base name of images for edges. Extensions for each corner or edge piece will be added to this image URL, before the extension. For example, with the default base name of "edge.gif", the top-left corner image will be "edge_TL.gif".

      The full list of extensions is: "_TL", "_TR", "_BL", "_BR", "_T", "_L", "_B", "_R", "_center".

      Returns:
      Current edgeImage value. Default value is "[SKIN]edge.gif"
      See Also:
    • setEdgeMarginSize

      public Canvas setEdgeMarginSize(int edgeMarginSize)
      How far into the edge of an object do we consider the "edge" for drag resize purposes?

      Note : This is an advanced setting

      Parameters:
      edgeMarginSize - New edgeMarginSize value. Default value is 5
      Returns:
      Canvas instance, for chaining setter calls
      See Also:
    • getEdgeMarginSize

      public int getEdgeMarginSize()
      How far into the edge of an object do we consider the "edge" for drag resize purposes?
      Returns:
      Current edgeMarginSize value. Default value is 5
      See Also:
    • setEdgeOffset

      public Canvas setEdgeOffset(Integer edgeOffset) throws IllegalStateException
      Amount the contained Canvas should be offset. Defaults to edgeSize; set to less than edgeSize to allow the contained Canvas to overlap the edge and corner media.
      Parameters:
      edgeOffset - New edgeOffset value. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:
    • getEdgeOffset

      public Integer getEdgeOffset()
      Amount the contained Canvas should be offset. Defaults to edgeSize; set to less than edgeSize to allow the contained Canvas to overlap the edge and corner media.
      Returns:
      Current edgeOffset value. Default value is null
      See Also:
    • setEdgeOpacity

      public Canvas setEdgeOpacity(Integer edgeOpacity) throws IllegalStateException
      Opacity of the edges. Defaults to matching this.opacity. if setOpacity() is called on a Canvas where edgeOpacity is set, edgeOpacity will be considered a percentage of the parent's opacity (so 50% opaque parent plus edgeOpacity 50 means 25% opaque edges)

      If this method is called after the component has been drawn/initialized: Set the edgeOpacity and mark the canvas for redraw
      Parameters:
      edgeOpacity - new edge-opacity level. Default value is null
      Returns:
      Canvas instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:
    • getEdgeOpacity

      public Integer getEdgeOpacity()
      Opacity of the edges. Defaults to matching this.opacity. if setOpacity() is called on a Canvas where edgeOpacity is set, edgeOpacity will be considered a percentage of the parent's opacity (so 50% opaque parent plus edgeOpacity 50 means 25% opaque edges)
      Returns:
      Current edgeOpacity value. Default value is null
      See Also:
    • setEdgeShowCenter

      public Canvas setEdgeShowCenter(Boolean edgeShowCenter) throws