com.holonplatform.vaadin7.components.builders.SelectInputBuilder Maven / Gradle / Ivy

/*
 * Copyright 2016-2017 Axioma srl.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 * 
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */
package com.holonplatform.vaadin7.components.builders;

import java.util.Arrays;

import com.holonplatform.core.i18n.Localizable;
import com.holonplatform.core.internal.utils.ObjectUtils;
import com.holonplatform.vaadin7.components.Input;
import com.holonplatform.vaadin7.components.ItemSet.ItemCaptionGenerator;

/**
 * Builder to create selection {@link Input}s.
 * 
 * @param  Value type
 * @param  Input type
 * @param  Selection type
 * @param  Selection items type
 * @param  Concrete builder type
 * 
 * @since 5.0.0
 */
public interface SelectInputBuilder, S, ITEM, B extends SelectInputBuilder>
		extends BaseSelectInputBuilder {

	/**
	 * Set the given items as selection item set.
	 * 
	 * When selection items are explicitly setted, any item data source is ignored.
	 * 
	 * @param items Items to set (not null)
	 * @return this
	 */
	B items(Iterable items);

	/**
	 * Set the given items as selection item set.
	 * 
	 * When selection items are explicitly setted, any item data source is ignored.
	 * 
	 * @param items Items to set (not null)
	 * @return this
	 */
	@SuppressWarnings("unchecked")
	default B items(ITEM... items) {
		ObjectUtils.argumentNotNull(items, "Items must be not null");
		return items(Arrays.asList(items));
	}

	/**
	 * Add a selection item to current selection item set.
	 * 
	 * When selection items are explicitly setted, any item data source is ignored.
	 * 
	 * @param item Item to add (not null)
	 * @return this
	 */
	B addItem(ITEM item);

	/**
	 * Add a selection item to current selection item set, providing an explicit item caption.
	 * 
	 * When selection items are explicitly setted, any item data source is ignored.
	 * 
	 * 
	 * Note that if an {@link ItemCaptionGenerator} is setted, the explicit caption is overridden by the caption
	 * provided by the generator.
	 * 
	 * @param item Item to add (not null)
	 * @param caption Localizable item caption
	 * @return this
	 */
	default B addItem(ITEM item, Localizable caption) {
		addItem(item);
		return itemCaption(item, caption);
	}

	/**
	 * Add a selection item to current selection item set, providing an explicit item caption.
	 * 
	 * When selection items are explicitly setted, any item data source is ignored.
	 * 
	 * 
	 * Note that if an {@link ItemCaptionGenerator} is setted, the explicit caption is overridden by the caption
	 * provided by the generator.
	 * 
	 * @param item Item to add (not null)
	 * @param caption Item caption
	 * @param messageCode Item caption translation code
	 * @return this
	 */
	default B addItem(ITEM item, String caption, String messageCode) {
		return addItem(item, Localizable.builder().message(caption).messageCode(messageCode).build());
	}

	/**
	 * Add a selection item to current selection item set, providing an explicit item caption.
	 * 
	 * When selection items are explicitly setted, any item data source is ignored.
	 * 
	 * 
	 * Note that if an {@link ItemCaptionGenerator} is setted, the explicit caption is overridden by the caption
	 * provided by the generator.
	 * 
	 * @param item Item to add (not null)
	 * @param caption Item caption
	 * @return this
	 */
	default B addItem(ITEM item, String caption) {
		return addItem(item, Localizable.builder().message(caption).build());
	}

}