Source: br-component/src/br/component/Frame.js

/**
* @module br/component/Frame
*/

var Emitter = require('emitr');
var Errors = require('br/Errors');

/**
 * @beta
 * @class
 * @alias module:br/component/Frame
 * 
 * @classdesc
 * Instances of <code>Frame</code> are used to wrap components before they are displayed on the
 * screen. They are created automatically by whatever code is controlling the view and passed
 * in to the component that they are displaying.
 *
 * <p>Frame is an abstract class. The specific implementations will interface with some sort of
 * layout manager.</p>
 */
function Frame() {
	/**
	 * The width in pixels of this frame.  Will be null initially.
	 * @var {number?} width
	 * @memberof br.component.Frame
	 */
	this.width = null;

	/**
	 * The height in pixels of this frame.  Will be null initially.
	 * @var {number?} height
	 * @memberof br.component.Frame
	 */
	this.height = null;

	/**
	 * True if this Frame has focus, false otherwise.
	 * @var {boolean} isFocused
	 * @memberof br.component.Frame
	 */
	this.isFocused = false;

	/**
	 * True if the content of this frame is visible, false otherwise.
	 * @var {boolean} isContentVisible
	 * @memberof br.component.Frame
	 */
	this.isContentVisible = false;

	/**
	 * The current state of this frame.
	 *
	 * One of Frame.NOT_ATTACHED (initially), Frame.MINIMIZED, Frame.MAXIMIZED,
	 * Frame.NORMAL, Frame.CLOSED.
	 *
	 * Every change of state should be accompanied by one of the specified events.
	 * @memberof br.component.Frame
	 */
	this.state = Frame.NOT_ATTACHED;
}

Emitter.mixInto(Frame);

Frame.NOT_ATTACHED = "not attached";
Frame.MINIMIZED = "minimized";
Frame.MAXIMIZED = "maximized";
Frame.NORMAL = "normal";
Frame.CLOSED = "closed";

Frame.EVENTS = ["attach", "close", "resize", "minimize", "maximize", "restore", "show", "hide", "focus", "blur"];

/**
 * Allows the component to set an html element that contains the dom content of this component.
 *
 * May only be called once.
 *
 * @param contentElement
 */
Frame.prototype.setContent = function(contentElement) {
	throw new Errors.UnimplementedAbstractMethodError("Frame.setContent: Implementations of Frame need to provide a setContent method that the component can use to provide a dom elements that should be displayed.");
};

/**
 * Sets the title of this frame.
 *
 * <p>Implementations of Frame for layout managers that display the title should override this
 * method.
 */
Frame.prototype.setTitle = function(title) {
	this.title = title;
};

/**
 * Allows the component to request that it be given a particular amount of room.  This is only
 * a request, if the frame is resized in response to this method, then a resize event will be
 * fired.
 *
 * <p>Implementations of Frame for layout managers that can allow visual components to be
 * resized should override this method.
 */
Frame.prototype.setPreferredSize = function(width, height) {};

/**
 * Allows the component to indicate that state that it would serialize has changed.
 *
 * <p>Implementations of Frame for layout managers that can persist state should override this
 * method.
 */
Frame.prototype.setComponentModified = function() {};

/**
 * This is a method for the component to call if it wishes to be closed.
 *
 * <p>Implementations of Frame for layout managers that are prepared to remove panels should
 * override this method and ensure that they fire the appropriate events.
 *
 * <p>If a frame is closed in response to this method, then a close event will be fired.
 */
Frame.prototype.close = function() {};

/**
 * This event must be raised after the content element has been attached to the DOM.
 *
 * <p>The state must be updated to one of HIDDEN, MINIMIZED, MAXIMIZED or NORMAL before this
 * event is fired, and width and height should be set.
 *
 * <p>This event will only be fired once.
 *
 * <p>It allows the component to do any calculations that need to take sizes into account.
 *
 * @event module:br/component/Frame#attach
 */

/**
 * This event must be raised when the component is closed and will not be used again.
 *
 * <p>It should be raised after the frame has been removed from the DOM. If the content of the
 * frame is visible at the time of close, it should be preceded by a hide event.
 *
 * <p>The state must be updated to CLOSED after this event has fired.
 *
 * <p>This event will only be fired once.
 *
 * <p>It allows the component to do cleanup.
 *
 * @event module:br/component/Frame#close
 */

/**
 * This event should be raised whenever the component is resized.  A component becoming invisible
 * is not a resize.
 *
 * <p>If the resize is due to a minimize (if the minimized form has visible content), maximise
 * or restore, it should be fired after that event.
 *
 * <p>Frame.width and Frame.height should be set to the new values before the event is raised.
 *
 * @event module:br/component/Frame#resize
 */

/**
 * This event should be raised whenever the contents of the frame are becoming visible after
 * previously not being visible.
 *
 * <p>It should be raised immediately after an attach event if the attach occurs somewhere that
 * should be visible.  If in its minimized form the contents of the frame are not visible, then
 * when the frame is restored or maximised, then a show event should be raised after the restore
 * or maximise event.
 *
 * <p>If a component is resized prior to becoming visible, the show event should occur after the
 * resize.
 *
 * <p>For example - a component is normal size, then minimized so that the content becomes
 * invisible.  The sequence of events is:
 *
 * 	<ol>	<li>minimize</li>	<li>hide</li>	</ol>
 *
 * <p>Then, the component is maximised, making the content visible, but also changing its size:
 * 	<ol>	<li>maximize</li>	<li>resize</li>	<li>show</li>	</ol>
 *
 * <p>The state must be updated to one of MINIMIZED, MAXIMIZED or NORMAL before this
 * event is fired, and width and height should be set.  isContentVisible must be set to true
 * before this event is fired.
 *
 * <p>It allows the component to resume or start long running resources.
 *
 * @event module:br/component/Frame#show
 */

/**
 * This event should be raised if the contents of this frame are no longer visible after
 * previously being visible.
 *
 * <p>It should be raised immediately before a close event if the contents were visible before
 * closing.  If in its minimized form the content is not visible, it should be raised immediately
 * after a minimize event.
 *
 * <p>Width and height should be set, and isContentVisible must be set to false before this event
 * is fired.
 *
 * <p>It allows the component to pause long running resources.
 *
 * @event module:br/component/Frame#hide
 */

/**
 * This event should be raised if the layout manager supports minimize/maximize/restore and the
 * this frame has been minimized.
 *
 * <p>If minimizing the frame causes the content to no longer be visible, a hide must be fired
 * afterwards.  If minimizing causes the content to change size, a resize event should be fired
 * afterwards.
 *
 * <p> The state must be updated to MINIMIZED before this event is fired.  If the content is no
 * longer visible, isContentVisible should be set before this event is fired.
 *
 * @event module:br/component/Frame#minimize
 */

/**
 * This event should be raised if the layout manager supports minimize/maximize/restore and
 * this frame has been maximized.
 *
 * <p>If maximizing the frame causes the content to become newly visible, a show must be fired
 * afterwards.  If maximizing causes the content to change size, a resize event should be fired
 * afterwards.
 *
 * <p>The state must be updated to MAXIMIZED before this event is fired.
 *
 * @event module:br/component/Frame#maximize
 */

/**
 * This event should be raised if the layout manager supports minimize/maximize/restore and the
 * this frame has been restored.
 *
 * <p>If restoring the frame causes the content to become newly visible, a show must be fired
 * afterwards.  If restoring causes the content to change size, a resize event should be fired
 * afterwards.
 *
 * <p>The state must be updated to NORMAL before this event is fired.  If the content is newly
 * visible, isContentVisible should be set before this event is fired.
 *
 * @event module:br/component/Frame#restore
 */

/**
 * This event should be raised if the layout manager supports focusing/activating a component
 * and this frame has been activated.
 *
 * <p>isFocused should be updated before this event is fired.
 *
 * @event module:br/component/Frame#focus
 */

/**
 * This event should be raised if the layout manager supports focusing/activating a component
 * and this frame has been inactivated.
 *
 * <p>isFocused should be updated before this event is fired.
 *
 * @event module:br/component/Frame#blur
 */

module.exports = Frame;