Package com.smartgwt.client.widgets

Class FieldPicker

java.lang.Object
com.google.gwt.user.client.ui.UIObject
com.google.gwt.user.client.ui.Widget
com.smartgwt.client.widgets.BaseWidget
com.smartgwt.client.widgets.Canvas
com.smartgwt.client.widgets.layout.Layout
com.smartgwt.client.widgets.layout.VLayout
com.smartgwt.client.widgets.FieldPicker
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, HasMembersChangedHandlers
public class FieldPicker extends VLayout
FieldPicker provides a configuration dialog that displays, side-by-side, the available and currently-displayed fields of a DataBoundComponent. It allows for easy customization of the order in which the fields of a DataBoundComponent are displayed, and of which are visible. If so configured, it also allows for convenient launching of the HiliteEditor, FormulaBuilder, and SummaryBuilder. A FieldPicker instance runs in its own window, a FieldPickerWindow

  • Constructor Details

    • FieldPicker

      public FieldPicker()

    • FieldPicker

      public FieldPicker(JavaScriptObject jsObj)

  • Method Details

    • getOrCreateRef

      public static FieldPicker getOrCreateRef(JavaScriptObject jsObj)

    • 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 VLayout

    • setAddCustomFieldsButtonTitle

      public FieldPicker setAddCustomFieldsButtonTitle(String addCustomFieldsButtonTitle) throws IllegalStateException
      The title displayed for the Add Custom Fields Button
      Parameters:
      addCustomFieldsButtonTitle - New addCustomFieldsButtonTitle value. Default value is "Add Custom Fields"
      Returns:
      FieldPicker instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getAddCustomFieldsButtonTitle

      public String getAddCustomFieldsButtonTitle()
      The title displayed for the Add Custom Fields Button
      Returns:
      Current addCustomFieldsButtonTitle value. Default value is "Add Custom Fields"

    • getAvailableFieldsGrid

      public ListGrid getAvailableFieldsGrid() throws IllegalStateException
      A ListGrid showing the list of available fields.

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

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

    • setAvailableFieldsHeaderControls

      public FieldPicker setAvailableFieldsHeaderControls(Canvas... availableFieldsHeaderControls) throws IllegalStateException
      Provides a set of controls to appear as section header controls above the available fields grid.
      Parameters:
      availableFieldsHeaderControls - New availableFieldsHeaderControls value. Default value is null
      Returns:
      FieldPicker instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getAvailableFieldsHeaderControls

      public Canvas[] getAvailableFieldsHeaderControls()
      Provides a set of controls to appear as section header controls above the available fields grid.
      Returns:
      Current availableFieldsHeaderControls value. Default value is null

    • setAvailableFieldsTitle

      public FieldPicker setAvailableFieldsTitle(String availableFieldsTitle) throws IllegalStateException
      Parameters:
      availableFieldsTitle - New availableFieldsTitle value. Default value is "Available Fields"
      Returns:
      FieldPicker instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getAvailableFieldsTitle

      public String getAvailableFieldsTitle()
      Returns:
      Current availableFieldsTitle value. Default value is "Available Fields"

    • setAvailableTitleTitle

      public FieldPicker setAvailableTitleTitle(String availableTitleTitle) throws IllegalStateException
      The title displayed for the title property of the available fields
      Parameters:
      availableTitleTitle - New availableTitleTitle value. Default value is "Name"
      Returns:
      FieldPicker instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getAvailableTitleTitle

      public String getAvailableTitleTitle()
      The title displayed for the title property of the available fields
      Returns:
      Current availableTitleTitle value. Default value is "Name"

    • getButtonLayout

      public HLayout getButtonLayout() throws IllegalStateException
      A horizontal layout used to show the Save and Cancel buttons.

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

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

    • setCancelButtonTitle

      public FieldPicker setCancelButtonTitle(String cancelButtonTitle) throws IllegalStateException
      The title shown on the Cancel button
      Parameters:
      cancelButtonTitle - New cancelButtonTitle value. Default value is "Cancel"
      Returns:
      FieldPicker instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getCancelButtonTitle

      public String getCancelButtonTitle()
      The title shown on the Cancel button
      Returns:
      Current cancelButtonTitle value. Default value is "Cancel"

    • getCancelChangesButton

      public IButton getCancelChangesButton() throws IllegalStateException
      An AutoChild button that saves the current field-set and exits the Field Picker.

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

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

    • setCanFilterSampleValue

      public FieldPicker setCanFilterSampleValue(Boolean canFilterSampleValue) throws IllegalStateException
      Whether the current fields' filter row allows the sample value column to be filtered.
      Parameters:
      canFilterSampleValue - New canFilterSampleValue value. Default value is false
      Returns:
      FieldPicker instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getCanFilterSampleValue

      public Boolean getCanFilterSampleValue()
      Whether the current fields' filter row allows the sample value column to be filtered.
      Returns:
      Current canFilterSampleValue value. Default value is false
      See Also:

    • setConfirmText

      public FieldPicker setConfirmText(String confirmText) throws IllegalStateException
      Parameters:
      confirmText - New confirmText value. Default value is "Must save pending changes to proceed. OK?"
      Returns:
      FieldPicker instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getConfirmText

      public String getConfirmText()
      Returns:
      Current confirmText value. Default value is "Must save pending changes to proceed. OK?"

    • getCurrentFieldsGrid

      public ListGrid getCurrentFieldsGrid() throws IllegalStateException
      A ListGrid showing the list of currently selected fields.

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

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

    • setCurrentFieldsTitle

      public FieldPicker setCurrentFieldsTitle(String currentFieldsTitle) throws IllegalStateException
      Parameters:
      currentFieldsTitle - New currentFieldsTitle value. Default value is "Visible Fields"
      Returns:
      FieldPicker instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getCurrentFieldsTitle

      public String getCurrentFieldsTitle()
      Returns:
      Current currentFieldsTitle value. Default value is "Visible Fields"

    • setCurrentTitleTitle

      public FieldPicker setCurrentTitleTitle(String currentTitleTitle) throws IllegalStateException
      The title displayed for the title property of the current fields
      Parameters:
      currentTitleTitle - New currentTitleTitle value. Default value is "Field Title"
      Returns:
      FieldPicker instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getCurrentTitleTitle

      public String getCurrentTitleTitle()
      The title displayed for the title property of the current fields
      Returns:
      Current currentTitleTitle value. Default value is "Field Title"

    • setDataBoundComponent

      public FieldPicker setDataBoundComponent(Canvas dataBoundComponent) throws IllegalStateException
      The component whose fields should be edited.

      Note that if DataBoundComponent.useAllDataSourceFields is set on the component, it will be cleared when the FieldPicker applies the requested ordering since that setting imposes a fixed ordering on the fields.

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

    • getDataBoundComponent

      public Canvas getDataBoundComponent()
      The component whose fields should be edited.

      Note that if DataBoundComponent.useAllDataSourceFields is set on the component, it will be cleared when the FieldPicker applies the requested ordering since that setting imposes a fixed ordering on the fields.

      Returns:
      Current dataBoundComponent value. Default value is null

    • setDataSource

      public FieldPicker setDataSource(DataSource dataSource) throws IllegalStateException
      An optional DataSource that is used to create a disposable dataBoundComponent if none is provided. Has no effect if a dataBoundComponent is specified.
      Parameters:
      dataSource - New dataSource value. Default value is null
      Returns:
      FieldPicker instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getDataSource

      public DataSource getDataSource()
      An optional DataSource that is used to create a disposable dataBoundComponent if none is provided. Has no effect if a dataBoundComponent is specified.
      Returns:
      Current dataSource value. Default value is null

    • setEmptyTitleHint

      public FieldPicker setEmptyTitleHint(String emptyTitleHint) throws IllegalStateException
      The hint shown when editing a field with no title defined.
      Parameters:
      emptyTitleHint - New emptyTitleHint value. Default value is "[No title specified]"
      Returns:
      FieldPicker instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getEmptyTitleHint

      public String getEmptyTitleHint()
      The hint shown when editing a field with no title defined.
      Returns:
      Current emptyTitleHint value. Default value is "[No title specified]"

    • setHilitesText

      public FieldPicker setHilitesText(String hilitesText) throws IllegalStateException
      Parameters:
      hilitesText - New hilitesText value. Default value is "Highlights..."
      Returns:
      FieldPicker instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getHilitesText

      public String getHilitesText()
      Returns:
      Current hilitesText value. Default value is "Highlights..."

    • getInstructionLabel

      public Label getInstructionLabel() throws IllegalStateException
      A label displaying the text assigned as the FieldPicker's instructions. Shown across the top of the widget.

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

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

    • setInstructions

      public FieldPicker setInstructions(String instructions) throws IllegalStateException
      Parameters:
      instructions - New instructions value. Default value is "Drag and drop or use arrows to move fields. Drag reorder to change field order."
      Returns:
      FieldPicker instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getInstructions

      public String getInstructions()
      Returns:
      Current instructions value. Default value is "Drag and drop or use arrows to move fields. Drag reorder to change field order."
      See Also:

    • setRemoveItemTitle

      public FieldPicker setRemoveItemTitle(String removeItemTitle) throws IllegalStateException
      The title shown on the 'Visible Fields' grid's context menu item, whose click handler puts the selected item back in the 'Available Fields' collection.
      Parameters:
      removeItemTitle - New removeItemTitle value. Default value is "Remove"
      Returns:
      FieldPicker instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getRemoveItemTitle

      public String getRemoveItemTitle()
      The title shown on the 'Visible Fields' grid's context menu item, whose click handler puts the selected item back in the 'Available Fields' collection.
      Returns:
      Current removeItemTitle value. Default value is "Remove"

    • setRemoveText

      public FieldPicker setRemoveText(String removeText) throws IllegalStateException
      Parameters:
      removeText - New removeText value. Default value is "You are about to remove the field. Are you sure?"
      Returns:
      FieldPicker instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getRemoveText

      public String getRemoveText()
      Returns:
      Current removeText value. Default value is "You are about to remove the field. Are you sure?"

    • setSampleRecord

      public FieldPicker setSampleRecord(Record sampleRecord) throws IllegalStateException
      If a sampleRecord is provided, the FieldPicker will show a second column in the Current Fields dialog showing the cell value that will appear for that field given the provided sample record.
      A value of "first" means the first record. If the underlying dataBoundComponent is a TreeGrid, you can specify "firstOpenLeaf" to use the first open leaf as the sampleRecord (this is often desirable in trees where the first record may be a folder that's used for organizational purposes only and hence would have no actual data for columns other than the tree column).
      Parameters:
      sampleRecord - New sampleRecord value. Default value is "first"
      Returns:
      FieldPicker instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getSampleRecord

      public Record getSampleRecord()
      If a sampleRecord is provided, the FieldPicker will show a second column in the Current Fields dialog showing the cell value that will appear for that field given the provided sample record.
      A value of "first" means the first record. If the underlying dataBoundComponent is a TreeGrid, you can specify "firstOpenLeaf" to use the first open leaf as the sampleRecord (this is often desirable in trees where the first record may be a folder that's used for organizational purposes only and hence would have no actual data for columns other than the tree column).
      Returns:
      Current sampleRecord value. Default value is "first"

    • setSampleRecord

      public FieldPicker setSampleRecord(DefaultSampleRecord sampleRecord) throws IllegalStateException
      If a sampleRecord is provided, the FieldPicker will show a second column in the Current Fields dialog showing the cell value that will appear for that field given the provided sample record.
      A value of "first" means the first record. If the underlying dataBoundComponent is a TreeGrid, you can specify "firstOpenLeaf" to use the first open leaf as the sampleRecord (this is often desirable in trees where the first record may be a folder that's used for organizational purposes only and hence would have no actual data for columns other than the tree column).
      Parameters:
      sampleRecord - New sampleRecord value. Default value is "first"
      Returns:
      FieldPicker instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getSampleRecordAsDefaultSampleRecord

      public DefaultSampleRecord getSampleRecordAsDefaultSampleRecord()
      If a sampleRecord is provided, the FieldPicker will show a second column in the Current Fields dialog showing the cell value that will appear for that field given the provided sample record.
      A value of "first" means the first record. If the underlying dataBoundComponent is a TreeGrid, you can specify "firstOpenLeaf" to use the first open leaf as the sampleRecord (this is often desirable in trees where the first record may be a folder that's used for organizational purposes only and hence would have no actual data for columns other than the tree column).
      Returns:
      Current sampleRecord value. Default value is "first"

    • setSampleValueTitle

      public FieldPicker setSampleValueTitle(String sampleValueTitle) throws IllegalStateException
      The title displayed for the sample value property of the current fields
      Parameters:
      sampleValueTitle - New sampleValueTitle value. Default value is "Sample Value"
      Returns:
      FieldPicker instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getSampleValueTitle

      public String getSampleValueTitle()
      The title displayed for the sample value property of the current fields
      Returns:
      Current sampleValueTitle value. Default value is "Sample Value"

    • getSaveAndExitButton

      public IButton getSaveAndExitButton() throws IllegalStateException
      An AutoChild button that saves the current field-set and exits the Field Picker.

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

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

    • setSaveAndExitButtonTitle

      public FieldPicker setSaveAndExitButtonTitle(String saveAndExitButtonTitle) throws IllegalStateException
      The title shown on the Save and Exit button
      Parameters:
      saveAndExitButtonTitle - New saveAndExitButtonTitle value. Default value is "Apply"
      Returns:
      FieldPicker instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getSaveAndExitButtonTitle

      public String getSaveAndExitButtonTitle()
      The title shown on the Save and Exit button
      Returns:
      Current saveAndExitButtonTitle value. Default value is "Apply"

    • setShowFieldOrderButtons

      public FieldPicker setShowFieldOrderButtons(boolean showFieldOrderButtons) throws IllegalStateException
      When set to false, hides the right-most set of buttons, used for re-ordering fields in the Visible Fields list.
      Parameters:
      showFieldOrderButtons - New showFieldOrderButtons value. Default value is true
      Returns:
      FieldPicker instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getShowFieldOrderButtons

      public boolean getShowFieldOrderButtons()
      When set to false, hides the right-most set of buttons, used for re-ordering fields in the Visible Fields list.
      Returns:
      Current showFieldOrderButtons value. Default value is true

    • setShowHilitesButton

      public FieldPicker setShowHilitesButton(boolean showHilitesButton) throws IllegalStateException
      Shows a "Highlights..." button that shows an interface for editing hilites in the attached DataBoundComponent.
      Parameters:
      showHilitesButton - New showHilitesButton value. Default value is true
      Returns:
      FieldPicker instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getShowHilitesButton

      public boolean getShowHilitesButton()
      Shows a "Highlights..." button that shows an interface for editing hilites in the attached DataBoundComponent.
      Returns:
      Current showHilitesButton value. Default value is true

    • setAvailableFields

      public void setAvailableFields(DataSourceField... newFields)
      Provides a new set of available fields.
      Parameters:
      newFields -

    • setDefaultProperties

      public static void setDefaultProperties(FieldPicker fieldPickerProperties)
      Class level method to set the default properties of this class. If set, then all existing and subsequently created instances of this class will automatically have default properties corresponding to the properties set on the SmartGWT class instance passed to this function before its underlying SmartClient JS object was created. This is a powerful feature that eliminates the need for users to create a separate hierarchy of subclasses that only alter the default properties of this class. Can also be used for skinning / styling purposes.

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

      Parameters:
      fieldPickerProperties - properties that should be used as new defaults when instances of this class are created
      See Also:

    • setCallbackCustomizer

      public void setCallbackCustomizer(FieldPickerCallbackCustomizer customizer)
      This method is called during rendering for all events in the visible range - those which would be rendered by default. The customizer should return false to prevent the passed event from appearing in the passed view.
      Parameters:
      customizer - the customizer to execute.

    • setLogicalStructure

      public LogicalStructureObject setLogicalStructure(FieldPickerLogicalStructure s)
      Setter implementing the LogicalStructure interface, which supports Eclipse's logical structure debugging facility.

    • getLogicalStructure

      public LogicalStructureObject getLogicalStructure()
      Getter implementing the LogicalStructure interface, which supports Eclipse's logical structure debugging facility.
      Specified by:
      getLogicalStructure in interface LogicalStructure
      Overrides:
      getLogicalStructure in class VLayout