/*******************************************************************************
 * Copyright (c) 2000, 2004 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials 
 * are made available under the terms of the Common Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/cpl-v10.html
 * 
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.ui.views.framelist;

/**
 * A frame source is the source of frames which appear in a frame list.
 * The frame list asks for the current frame whenever it switches
 * to another frame, so that the context can be restored when the
 * frame becomes current again.
 *
 * @see FrameList
 */
public interface IFrameSource {

    /**
     * Frame constant indicating the current frame.
     */
    public static final int CURRENT_FRAME = 0x0001;

    /**
     * Frame constant indicating the frame for the selection.
     */
    public static final int SELECTION_FRAME = 0x0002;

    /**
     * Frame constant indicating the parent frame.
     */
    public static final int PARENT_FRAME = 0x0003;

    /**
     * Flag constant indicating that the full context should be captured.
     */
    public static final int FULL_CONTEXT = 0x0001;

    /**
     * Returns a new frame describing the state of the source.
     * If the <code>FULL_CONTEXT</code> flag is specified, then the full
     * context of the source should be captured by the frame.
     * Otherwise, only the visible aspects of the frame, such as the name and tool tip text,
     * will be used.
     *
     * @param whichFrame one of the frame constants defined in this interface
     * @param flags a bit-wise OR of the flag constants defined in this interface
     * @return a new frame describing the current state of the source
     */
    public Frame getFrame(int whichFrame, int flags);
}