com.holonplatform.vaadin7.components.ComposableComponent Maven / Gradle / Ivy

/*
 * Copyright 2000-2017 Holon TDCN.
 * 
 * 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;

import java.util.function.Consumer;

import com.holonplatform.vaadin7.internal.components.DefaultComponentContainerComposer;
import com.vaadin.ui.Component;
import com.vaadin.ui.ComponentContainer;

/**
 * A {@link Component} which supports a {@link Composer} delegate to compose a set of components into its content
 * component.
 * 
 * @since 5.0.0
 */
public interface ComposableComponent extends Component {

	/**
	 * Get the form content component
	 * @return Form content component
	 */
	Component getContent();

	/**
	 * Compose the components into the content component using the previously configured {@link Composer}.
	 * @throws IllegalStateException If the content component or the {@link Composer} are not configured (null)
	 */
	void compose();

	/**
	 * Delegate interface to compose a set of components from a component source into a {@link Component} type content.
	 * 
	 * @param  Content component type
	 * @param  Components source
	 */
	@FunctionalInterface
	public interface Composer {

		/**
		 * Compose the components provided by given source into given content component.
		 * @param content Content on which to compose the components (never null)
		 * @param source Components source (never null)
		 */
		void compose(C content, S source);

	}

	/**
	 * Base {@link ComposableComponent} builder.
	 *
	 * @param  Components source type
	 * @param  Content component type
	 * @param  Concrete builder type
	 */
	public interface Builder> {

		/**
		 * Set a content initializer to setup the content component. This initiliazer is called every time the content
		 * composition is triggered.
		 * @param initializer Content initializer (not null)
		 * @return this
		 */
		B initializer(Consumer initializer);

		/**
		 * Set the {@link Composer} to be used to compose the components into the content component.
		 * @param composer The composer to set (not null)
		 * @return this
		 */
		B composer(Composer composer);

		/**
		 * Set whether to compose the components into the content component when the content is attached to a parent
		 * component, only if the component was not already composed using {@link ComposableComponent#compose()}.
		 * 
		 * Default is true.
		 * 
		 * @param composeOnAttach true to compose the components when the content is attached to a parent
		 *        component. If false, the {@link ComposableComponent#compose()} method must be invoked to
		 *        compose the components.
		 * @return this
		 */
		B composeOnAttach(boolean composeOnAttach);

	}

	/**
	 * Create a {@link Composer} which uses a {@link ComponentContainer} as composition layout and adds the property
	 * components to layout in the order they are returned from the {@link PropertyValueComponentSource}.
	 * @return A new {@link ComponentContainer} composer
	 */
	static Composer componentContainerComposer() {
		return componentContainerComposer(false);
	}

	/**
	 * Create a {@link Composer} which uses a {@link ComponentContainer} as composition layout and adds the property
	 * components to layout in the order they are returned from the {@link PropertyValueComponentSource}.
	 * @param fullWidthComponents true to set the width of all composed components to 100%
	 * @return A new {@link ComponentContainer} composer
	 */
	static Composer componentContainerComposer(
			boolean fullWidthComponents) {
		return new DefaultComponentContainerComposer(fullWidthComponents);
	}

}