package org.litesoft.render;

import org.litesoft.logger.*;

public interface RenderHelper
{
    public static final Logger LOGGER = LoggerFactory.getLogger( RenderHelper.class );

    public static final RenderHelper[] EMPTY_ARRAY = new RenderHelper[0];

    /**
     * This is a helper method that is called to notify this Helper that any "determined"
     * state will need to be re"determined".
     * <p/>
     * Any child RenderHelpers that this Helper is holding onto should also be notified.
     *
     * @return true if the Rendering Participation State actually Changed
     */
    public boolean renderingParticipationChanged();

    public boolean isParticipatingInRendering();

    public RenderSizingApproach getSizingApproach();

    public boolean isSizable();

    public RenderDimensionAdapter getDimensionAdapter();

    public RenderHelper getParentHelper();

    /**
     * Restore the RenderableRect to its pre-Layed-out state and return the RenderHelper(s) for its children.
     *
     * @return !null array of the child RenderHelper(s) if any.
     */
    public RenderHelper[] restoreForLayout();

    /**
     * Return if this Helper is current in the Laying Out mode.
     */
    public boolean isLayingOut();

    /**
     * Set the Helper to indicate that we are in the process of Laying Out.
     */
    public void setLayingOut();

    /**
     * Request "this" RederableRect be invalidated from a layout perspective and that it and its related be layed out.
     * <p/>
     * Note: RHPs are Instance Equality Managed, so for the same underlying dependency the same RHP must be returned!
     *
     * @return null if no layout process is needed,
     *         otherwise the returned RHP's callbacks will be notified when it is complete.
     */
    public RenderHelperProcess layout();

    /**
     * Request "this" RederableRect and its' children be layed out.
     * <p/>
     * Note: RHPs are Instance Equality Managed, so for the same underlying dependency the same RHP must be returned!
     *
     * @return null if no layout process is needed,
     *         otherwise the returned RHP's callbacks will be notified when it is complete.
     */
    public RenderHelperProcess layoutFromHereDown();

    /**
     * Determine if this Helper is a Layout Ancestor.
     * <p/>
     * When going up the Parentage path, it will obviously return true at the root, but it may also return true at a Clipping Container that has been explicitly sized!
     */
    public boolean isLayoutAncestorHelper();

    /**
     * Request that the "flood" Size be set to the pRequestedSize.
     * <p/>
     * It will not set the size below the Minimum.
     * <p/>
     * Note: RHPs are Instance Equality Managed, so for the same underlying dependency the same RHP must be returned!
     *
     * @param pRequestedSize - Must be > 0
     *
     * @return !null RHP, where its callbacks will be notified when it is complete.
     *
     * @throws IllegalArgumentException      if pRequestedSize <= 0
     * @throws UnsupportedOperationException if the SizingApproach is "None"
     */
    public RenderHelperProcess floodSetSize( int pRequestedSize )
            throws IllegalArgumentException, UnsupportedOperationException;

    /**
     * Request that the "flood" Size be adjusted by pRequestedSizeChange.
     * <p/>
     * It will not set the size below the Minimum.
     * <p/>
     * Note: RHPs are Instance Equality Managed, so for the same underlying dependency the same RHP must be returned!
     *
     * @return !null RHP, where its callbacks will be notified when it is complete.
     *
     * @throws UnsupportedOperationException if the SizingApproach is "None"
     */
    public RenderHelperProcess floodAdjustSizeBy( int pRequestedSizeChange )
            throws UnsupportedOperationException;

    /**
     * Request that the "user requested" Size be set to the pRequestedSize.
     * <p/>
     * It will not set the size below the Minimum.
     * <p/>
     * Note: RHPs are Instance Equality Managed, so for the same underlying dependency the same RHP must be returned!
     *
     * @param pRequestedSize - Must be > 0
     *
     * @return !null RHP, where its callbacks will be notified when it is complete.
     *
     * @throws IllegalArgumentException      if pRequestedSize <= 0
     * @throws UnsupportedOperationException if the SizingApproach is "None"
     */
    public RenderHelperProcess setSize( int pRequestedSize )
            throws IllegalArgumentException, UnsupportedOperationException;

    /**
     * Request that the "user requested" Size be adjusted by pRequestedSizeChange.
     * <p/>
     * It will not set the size below the Minimum.
     * <p/>
     * Note: RHPs are Instance Equality Managed, so for the same underlying dependency the same RHP must be returned!
     *
     * @return !null RHP, where its callbacks will be notified when it is complete.
     *
     * @throws UnsupportedOperationException if the SizingApproach is "None"
     */
    public RenderHelperProcess adjustSizeBy( int pRequestedSizeChange )
            throws UnsupportedOperationException;

    /**
     * Get the "Natural" Size - the size something was when it first was Rendered.
     *
     * @return null means that is not "yet" available.
     */
    public Integer getNaturalSize();

    /**
     * Get the "Natural" Size RHP.
     * <p/>
     * Note: RHPs are Instance Equality Managed, so for the same underlying dependency the same RHP must be returned!
     *
     * @return !null RHP, where its callbacks will be notified when it is complete.
     */
    public RenderHelperProcess unavailableNaturalSizeRHP();

    /**
     * Get the "Current" Size.
     * <p/>
     * Renderable Objects that are not Sizable will return their "Natural" Size.
     *
     * @return null means that is not "yet" available.
     */
    public Integer getCurrentSize();

    /**
     * Get the "Current" Size RHP.
     * <p/>
     * Note: RHPs are Instance Equality Managed, so for the same underlying dependency the same RHP must be returned!
     *
     * @return !null RHP, where its callbacks will be notified when it is complete.
     */
    public RenderHelperProcess unavailableCurrentSizeRHP();

    /**
     * Get the "Minimum" Size.
     * <p/>
     * Renderable Objects that are not Sizable will return their "Natural" Size.
     *
     * @return null means that is not "yet" available.
     */
    public Integer getMinimumSize();

    /**
     * Get the "Minimum" Size RHP.
     * <p/>
     * Note: RHPs are Instance Equality Managed, so for the same underlying dependency the same RHP must be returned!
     *
     * @return !null RHP, where its callbacks will be notified when it is complete.
     */
    public RenderHelperProcess unavailableMinimumSizeRHP();
}