/*
 * Java
 *
 * Copyright 2010-2024 MicroEJ Corp. All rights reserved.
 * This library is provided in source code for use, modification and test, subject to license terms.
 * Any modification of the source code will break MicroEJ Corp. warranties on the whole library.
 * This document has been released and published by E-S-R consortium, a non-profit entity.
 * To learn more about E-S-R consortium, please visit http://www.e-s-r.net/.
 * The matter contained in this document is not subject to copyright; you are free to use it for any purpose, for more information see E-S-R consortium policies.
 */
package ej.microui.display;

import ej.microui.event.EventHandler;

/**
 * <code>Displayable</code> is an abstract class which defines the very objects that can be shown on the
 * <code>Display</code>.<br>
 * A <code>Displayable</code> may be shown or hidden, but at most one <code>Displayable</code> is shown on the
 * <code>Display</code>.<br>
 * <br>
 * Subclasses should define the <code>Displayable</code> contents and their possible interactions with the user.<br>
 * <br>
 * By default, a new <code>Displayable</code> object is not visible on the display.
 *
 * @see Display
 */
public abstract class Displayable implements EventHandler {

    /**
     * Requests a rendering for the entire displayable. Calling this method may result in subsequent call to
     * {@link #render(GraphicsContext)} on the displayable.
     * <p>
     * The call to {@link #render(GraphicsContext)} occurs asynchronously to this call. That is, this method will not
     * block waiting for {@link #render(GraphicsContext)} to finish. After render action (after call to
     * {@link #render(GraphicsContext)}), a call to {@link Display#flush()} is synchronously performed.
     * <p>
     * This call may have no effect under certain conditions:
     * <ul>
     * <li>if the displayable is not visible on the display (see {@link Display#isShown(Displayable)}): the request is
     * refused.</li>
     * <li>if the displayable is not visible on the display when the event is executed (a call to
     * {@link Display#requestShow(Displayable)} has been performed with another displayable): the request is abandoned
     * (this displayable is no longer the current displayable).</li>
     * <li>if a request is already available in the events queue <b>and</b> if the request is called from the MicroUI
     * pump: the request is useless because this request has been already added and cannot be executed until the end of
     * current caller method. The request is not added into the queue.</li>
     * </ul>
     */
    public void requestRender() {
        throw new RuntimeException();
    }

    /**
     * This method is called by system as soon as the displayable becomes visible. Application should override this
     * method to control its own displayables. Default behavior does nothing.
     *
     * @see Display#requestShow(Displayable)
     */
    protected void onShown() {
        throw new RuntimeException();
    }

    /**
     * This method is called by system as soon as the displayable becomes hidden. Application should override this
     * method to control its own displayables. Default behavior does nothing.
     *
     * @see Display#requestHide(Displayable)
     */
    protected void onHidden() {
        throw new RuntimeException();
    }

    /**
     * Renders the displayable. This method is called by system as soon as the displayable has be rendered. Caller
     * ensures the graphics context's clip and translate are reseted.
     *
     * @param gc
     *            the graphics context of display.
     */
    protected abstract void render(GraphicsContext gc);
}