com.vaadin.v7.client.widget.grid.EditorHandler Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of vaadin-compatibility-client Show documentation
Vaadin 7 compatibility package for Vaadin 8
There is a newer version: 8.27.3
Show newest version
/*
 * Copyright (C) 2000-2024 Vaadin Ltd
 *
 * This program is available under Vaadin Commercial License and Service Terms.
 *
 * See  for the full
 * license.
 */
package com.vaadin.v7.client.widget.grid;

import java.util.Collection;

import com.google.gwt.user.client.ui.Widget;
import com.vaadin.v7.client.widgets.Grid;

/**
 * An interface for binding widgets and data to the grid row editor. Used by the
 * editor to support different row types, data sources and custom data binding
 * mechanisms.
 *
 * @param 
 *            the row data type
 *
 * @since 7.4
 * @author Vaadin Ltd
 */
public interface EditorHandler {

    /**
     * A request class passed as a parameter to the editor handler methods. The
     * request is callback-based to facilitate usage with remote or otherwise
     * asynchronous data sources.
     * 
     * An implementation must call either {@link #success()} or {@link #fail()},
     * according to whether the operation was a success or failed during
     * execution, respectively.
     *
     * @param 
     *            the row data type
     */
    public interface EditorRequest {
        /**
         * Returns the index of the row being requested.
         *
         * @return the row index
         */
        public int getRowIndex();

        /**
         * Returns the DOM index of the column being focused.
         *
         * @return the column index (excluding hidden columns)
         */
        public int getColumnIndex();

        /**
         * Returns the row data related to the row being requested.
         *
         * @return the row data
         */
        public T getRow();

        /**
         * Returns the grid instance related to this editor request.
         *
         * @return the grid instance
         */
        public Grid getGrid();

        /**
         * Returns the editor widget used to edit the values of the given
         * column.
         *
         * @param column
         *            the column whose widget to get
         * @return the widget related to the column
         */
        public Widget getWidget(Grid.Column column);

        /**
         * Informs Grid that the editor request was a success.
         */
        public void success();

        /**
         * Informs Grid that an error occurred while trying to process the
         * request.
         *
         * @param errorMessage
         *            and error message to show to the user, or
         *            null to not show any message.
         * @param errorColumns
         *            a collection of columns for which an error indicator
         *            should be shown, or null if no columns should
         *            be marked as erroneous.
         */
        public void failure(String errorMessage,
                Collection> errorColumns);

        /**
         * Checks whether the request is completed or not.
         *
         * @return true if the request is completed
         */
        public boolean isCompleted();
    }

    /**
     * Binds row data to the editor widgets. Called by the editor when it is
     * opened for editing.
     * 

     * The implementation must call either
     * {@link EditorRequest#success()} or
     * {@link EditorRequest#failure(String, Collection)} to signal a successful
     * or a failed (respectively) bind action.
     *
     * @param request
     *            the data binding request
     *
     * @see Grid#editRow(int)
     */
    public void bind(EditorRequest request);

    /**
     * Called by the editor when editing is cancelled. This method may have an
     * empty implementation in case no special processing is required.
     * 

     * In contrast to {@link #bind(EditorRequest)} and
     * {@link #save(EditorRequest)}, any calls to
     * {@link EditorRequest#success()} or
     * {@link EditorRequest#failure(String, Collection)} have no effect on the
     * outcome of the cancel action. The editor is already closed when this
     * method is called.
     *
     * @param request
     *            the cancel request
     *
     * @see Grid#cancelEditor()
     */
    public void cancel(EditorRequest request);

    /**
     * Commits changes in the currently active edit to the data source. Called
     * by the editor when changes are saved.
     * 
     * The implementation must call either
     * {@link EditorRequest#success()} or {@link EditorRequest#fail()} to signal
     * a successful or a failed (respectively) save action.
     *
     * @param request
     *            the save request
     *
     * @see Grid#saveEditor()
     */
    public void save(EditorRequest request);

    /**
     * Returns a widget instance that is used to edit the values in the given
     * column. A null return value means the column is not editable.
     *
     * @param column
     *            the column whose values should be edited
     * @return the editor widget for the column or null if the column is not
     *         editable
     */
    public Widget getWidget(Grid.Column column);
}