# com.bea.ide.ui.frame Package

The frame service class 'com.bea.ide.frame.FrameSvc' provides access to the application's main JFrame, and it's auxiliary views, docked and floating.

A 'frame view' is a view that participates in the application level docking layout, as opposed to a 'document view' which shows a visual representation of a specific document, and participates only in the layout defined by the document service, in the central document area of the IDE.

To add a frame view to the IDE, you must specify it in an 'extension-xml' section of your extension.xml file:

        <extension-xml id="urn:com-bea-ide:frame">
            <frame-set>
                <frame-view class="workshop.shell.workspace.WorkspaceTreeContainer"
                    label="Workspace" />
                <frame-view class="workshop.shell.workspace.WorkspaceFilesContainer"
                    label="Files" />
            </frame-set>
            ...
        </extension-xml>

Note: In production code you would use the localization escaping mechanism to specify the labels.

The class specified in the 'frame-view' tag must extend 'Component', or implement 'com.bea.ide.frame.IFrameView', or both.

Perhaps the simplest test frame view would be:

        public class MyView extends JLabel
        {
            public MyView()
            {
                super("Hello World!");

                setBorder(new TopBorder());
                setHorizontalAlignment(CENTER);
            }
        }

This combined with the extension.xml file:

        <extension-xml id="urn:com-bea-ide:frame">
            <frame-view-set>
                <frame-view class="com.mydomain.MyView" label="Salutation" />
            </frame-view-set>
        </extension-xml>

Achieves one of the simplest IDE extensions possible.

Once the IDE is started, however, you would still need to choose the 'Test' menu item from the View/Windows menu in order to make the view visible. In order for your view to show at start-up, it must participate in a 'frame-layout'.

Note that the view class will not actually be instantiated until the view is made visible for the first time.

There are 2 ways to participate more fully in the overall window layout of the IDE.

- Using 'application-layout' and 'frame-layout' tags.
- Using the 'location' child tag with 'frame-view'.

The following is an example of how to use 'frame-layout' to specify a floating layout containing several of the simple test views described above:

        <extension-xml id="urn:com-bea-ide:frame">
        <frame-view-set>
            <frame-view class="com.mydomain.MyView" id="v1" label="Salutation" />
            <frame-view class="com.mydomain.MyView" id="v2" label="Salutation" />
            <frame-view class="com.mydomain.MyView" id="v3" label="Salutation" />
            <frame-view class="com.mydomain.MyView" id="v4" label="Salutation" />
        </frame-view-set>

        <application-layout id="main">
            <frame-layout>
                <frame-container orientation="horizontal">
                    <frame-view-ref class="com.mydomain.MyView" id="v1" proportion="50%" />
                    <frame-container width="50%">
                        <frame-view-ref class="com.mydomain.MyView" id="v2" proportion="25%" />
                        <frame-container height="75%">
                            <frame-view-ref class="com.mydomain.MyView" id="v3" proportion="50%" />
                            <frame-view-ref class="com.mydomain.MyView" id="v4" proportion="50%" />
                        </frame-container>
                    </frame-container>
                </frame-container>
            </frame-view-layout>
        </application-layout>
        </extension-xml>

This yields the a floating window that looks like:

Note that this specification only applies to the default layout. Once the user has started the IDE for the first time, and exited, a user specific layout is saved, and all extension.xml layouts are ignored in the next session. If you are playing with layouts, you will need to delete %USER_PROFILES%/.workshop.pref between IDE invocations to see your changes.

In any such 'frame-layout' specification, only the 'orientation' attribute of the root 'frame-container' is enforced. Any 'orientation' attributes in sub-nodes are ignored. Orientation alternates between horizontal and vertical at each level of the generated tree structure. Each level may also have an arbitrary number of child nodes.

Frame-container nodes in the main frame start with a set of root nodes, each with an orientation of 'north', 'south', 'east', or 'west'. The following XML places a sub-layout, identical to the floating layout above, at the bottom of the main frame window:

        <extension-xml id="urn:com-bea-ide:frame">

        ...

        <application-layout id="main">
            <frame-layout id="main">
                <frame-container orientation="south" proportion="20%">
                    <frame-view-ref class="com.mydomain.MyView" id="v1" proportion="50%" />
                    <frame-container width="50%">
                        <frame-view-ref class="com.mydomain.MyView" id="v2" proportion="25%" />
                        <frame-container height="75%">
                            <frame-view-ref class="com.mydomain.MyView" id="v3" proportion="50%" />
                            <frame-view-ref class="com.mydomain.MyView" id="v4" proportion="50%" />
                        </frame-container>
                    </frame-container>
                </frame-container>
            </frame-view-layout>
        </application-layout>
        </extension-xml>

This results in a layout that looks like:

The second method of placing a frame view is more flexible, and will impact an existing saved layout, the first time a new frame view is seen. The following is an example that uses the 'location' child tag on a 'frame-view' to place a custom output window tabbed with the standard 'Build' output window:

      <frame-view-set>
        <frame-view class="workshop.shell.output.OutputWindow" id="Hello" label="&Salutations">
            <location classDest="workshop.shell.output.OutputWindow"
                    idDest="Build" orientation="tabbed" visible="true" />
        </frame-view>
      </frame-view-set>

This same technique can be used to place a new view in any relationship to an existing view, using the orientations 'north', 'south', 'west', and 'east'.

### Reference

The following section lists all the valid attributes of the tags introduced above:

fame-view-set
scope - Valid values include a layout name ('main' or 'urn:com-bea-ide:debug'), a document class ('workshop.xml.xmlmap.documentmodels.xq.XqDocument'), or a view class ('workshop.pageflow.ui.view.FlowView').
frame-view
class - The fully qualified class name of the frame view implementation. id - An optional qualifier used to distinguish between multiple instances of the implementation class. label - The label used in the view tab, and in the 'View' menu. icon - An optional resource path to a 16x16 .gif file, used in the 'View' menu. hasaction - If true, indicates that a menuitem for this view should not be shown in any generated frame view menu. hasmenu - If true, indicates that a menuitem for this view should not be shown in the View/Windows menu. askavailable - If true, indicates that the view implements IFrameView, and that its isAvailable() method should be called to determine whether the frame can be shown. Note that using this attribute can have significant perf impact. Consider using the frame-view-set 'scope' attribute to limit how frequently the view gets asked about its availability.
location
classDest - An optional fully qualified class name of the frame view relative to which this view is to be located. idDest - An optional id to uniquely identify the frame view relative to which this view is to be located. orientation - Any of the values 'tabbed', 'horizontal', 'vertical', if classDest is specified, or 'root', 'north', 'south', 'west', or 'east' for placement relative to the main frame. insert - Optional attribute for modifying the meaning of the 'orientation' attribute: 'root': n/a 'north', 'south', 'east', 'west': closest to the app frame edge, v. closest to the document. 'horizontal': above v. below 'vertical': left v. right 'tabbed': first v. last in the current set exact - If true, position exactly based on destination view, for TABBED placement only. False or omitted will cause the new view to be positioned either at the beginning, or the end of the tab set. only with exact=true can you position between existing tabs. proportion - Proportional dimension to comsume in split direction (n/a to 'tabbed' and 'root' orientations). visible - If true, make the view visible to the user. Make it the active tab, if it is tabbed with other views. activate - If true, set focus to the added view immediately. (n/a if 'visible' is false)
application-layout
id - Id of the application layout to which the children should be applied. Valid values are 'main' and 'urn:com-bea-ide:debug'.
frame-layout
id - Id of the frame layout to which the children should be applied. Valid values are 'main' and omitted.
frame-container
orientation - Any of the values 'tabbed', 'root', 'north', 'south', 'west', or 'east'. Valid only on the root container in a frame-layout. proportion - Any value ##%. Similar to HTML tables, proportions need not add up to 100%.
frame-view-ref
class - The fully qualified class name of the frame view implementation. id - An optional qualifier used to distinguish between multiple instances of the implementation class. orientation - Any of the values 'tabbed', 'root', 'north', 'south', 'west', or 'east'. Valid only on the root container in a frame-layout. proportion - Any value ##%. Similar to HTML tables, proportions need not add up to 100%. visible - If false, the view is initially hidden.

## Interface Summary

FrameSvc.I |
IFrameView | Implement this interface, or derive from JComponent for all classes specified in the 'class' attribute of a <frame-view> tag in your extension.xml.

## Class Summary

FrameSvc | This class provides access to the main frame of the application, and its associated docking views.
FrameSvc.LayoutConstraints | Constraints used to add a view to the application layout.