Class UISplitViewer

public class UISplitViewer extends UIPanel
{
  // Fields
  public final static int HORIZONTAL;

  // Constructors
  public UISplitViewer();
  public UISplitViewer(IUIComponent nw, IUIComponent se);
  public UISplitViewer(IUIComponent nw, IUIComponent se, int style);
  public UISplitViewer(IUIComponent nw, IUIComponent se, int style,
        int size);
  public UISplitViewer(IUIComponent nw, IUIComponent se, int style,
        int size, boolean addScroll);

  // Methods
  public IUIComponent getComponent(String name);
  public IUIComponent getFloater();
  public int getPos();
  public int getStyle();
  public boolean mouseDown(Event e, int x, int y);
  public boolean mouseDrag(Event e, int x, int y);
  public boolean mouseUp(Event e, int x, int y);
  public void setPos(int pos);
}

This class implements a split viewer control. UISplitViewer uses UISplitLayout to manage three components, identified as follows.

Component	Description
"nw"	The component in the top (north) pane if the split is horizontal, or the left (west) pane if the split is vertical.
"se"	The component in the bottom (south) pane if the split is horizontal, or the right (east) pane if the split is vertical.
"0" for a vertical split and HORIZONTAL for a horizontal split.	The component that divides the two panes. By default, UISplitViewer uses UIThumb to implement the split.

When you create a UISplitViewer object, you can specify whether the split will be vertical (the default) or horizontal. You can also set the size of the "nw" component by specifying its height (if the split is horizontal) or its width (if the split is vertical). A negative size means the height or width is a percentage of the split viewer's total height or width. A positive size specifies the height or width as an absolute value in pixels. The remainder of the split viewer control is filled with the splitter and "se" components.

You can also specify that scroll bars be added to each pane when they are needed. The following example shows different ways to construct UISplitViewer objects.

UISplitViewer sv1, sv2;
UIList lst1, lst2;
UIGraphic gr1, gr2;

... // Construct lst1, lst2, gr1, and gr2.

// Construct a horizontal split viewer where the height of 
// the "nw" component is 40% of the viewer's total height.
// By default, no scroll bars will be added to the top
// and bottom panes.
sv1 = new UISplitViewer(lst1, gr1, UISplitViewer.HORIZONTAL, -40);

// Construct a vertical split viewer where the width of 
// the "nw" component is 75 pixels. Allow scroll bars to
// be added to each pane when necessary.
sv2 = new UISplitViewer(lst2, gr2, 0, 75, true);

// Add sv1 and sv2 to the container.
add(sv1);
add(sv2);

UIComponent
  |
  +--UIContainer
    |
    +--UIStateContainer
      |
      +--UIPanel
        |
        +--UISplitViewer

Constructors

UISplitViewer

public UISplitViewer();

Creates a vertical split viewer control with no content.

Remarks:

To add components to the control, call the add method (inherited through UIPanel), as shown in the following example:

UISplitViewer sv = new UISplitViewer();
add(sv);  // Add sv to the container.

// Add components to the left and right panes.
// The layout constraints passed to add are
// defined by the layout manager, UISplitLayout.
sv.add(new UIText("Left component"), "nw");
sv.add(new UIText("Right component"), "se");

By default, the size of the left component is -50 and neither pane displays scroll bars. For more information about component sizes, see the UISplitViewer overview.

UISplitViewer

public UISplitViewer(IUIComponent nw, IUIComponent se);

Creates a vertical split viewer control with the specified components.

Parameter	Description
nw	The content component for the left (west) pane of the control.
se	The content component for the right (east) pane of the control.

Remarks:

By default, the size of the nw component is -50 and neither pane displays scroll bars. For more information about component sizes, see the UISplitViewer overview.

UISplitViewer

public UISplitViewer(IUIComponent nw, IUIComponent se, int style);

Creates a split viewer control with the specified components and style.

Parameter	Description
nw	The content component for the top (north) or left (west) pane of the control.
se	The content component for the bottom (south) or right (east) pane of the control.
style	The style of the control. Possible values include HORIZONTAL for a horizontal split, or 0 for a vertical split.

Remarks:

By default, the size of the nw component is -50 and neither pane displays scroll bars. For more information about component sizes, see the UISplitViewer overview.

UISplitViewer

public UISplitViewer(IUIComponent nw, IUIComponent se, int style, int size);

Creates a split viewer control with the specified components, style, and size.

Parameter	Description
nw	The content component for the top (north) or left (west) pane of the control.
se	The content component for the right (east) pane of the control.
style	The style of the control. Possible values include HORIZONTAL for a horizontal split, or 0 for a vertical split.
size	The size of the nw component. A negative value means the height or width is a percentage of the split viewer's total height or width. A positive value specifies the absolute height or width in pixels. For more information, see the UISplitViewer overview.

Remarks:

By default, neither pane displays scroll bars.

Exceptions:

IllegalArgumentException if the size parameter was less than -100.

UISplitViewer

public UISplitViewer(IUIComponent nw, IUIComponent se, int style, int size,
        boolean addScroll);

Creates a split viewer control with the specified components, style, and size, and optional scroll bar support.

Parameter	Description
nw	The content component for the top (north) or left (west) pane of the control.
se	The content component for the right (east) pane of the control.
style	The style of the control. Possible values include HORIZONTAL for a horizontal split, or 0 for a vertical split.
size	The size of the nw component. A negative value means the height or width is a percentage of the split viewer's total height or width. A positive value specifies the absolute height or width in pixels. For more information, see the UISplitViewer overview.
addScroll	If true, scroll bars will be added to each pane when they are needed; otherwise, neither pane will provide scroll bars.

Exceptions:

IllegalArgumentException if the size parameter was less than -100.

Methods

getComponent

public IUIComponent getComponent(String name);

Retrieves the component at the specified layout position.

Return Value:

Returns the specified component.

Parameter	Description
name	The layout name that identifies the component to be retrieved. You can pass one of the following values: "nw" Retrieves the component in the top (north) or left (west) pane. "se" Retrieves the component in the bottom (south) or right (east) pane. "splitter" Retrieves the component that divides the two panes.

Remarks:

The name parameter is not case-sensitive.

Exceptions:

IllegalArgumentException if an undefined name was specified.

getFloater

public IUIComponent getFloater();

Retrieves the floating component in this container, if there is one. The floating component is the component that is superceding the standard z-order of the container's children by being first in the z-order. This method is most commonly used when a component is being dragged, such as a column header or a scroll thumb.

Return Value:

Returns the current floating component, or null if there is none.

getPos

public int getPos();

Retrieves the current split position.

Return Value:

Returns the split position that is used by the layout manager.

Remarks:

This method retrieves the split position of the control's layout manager, which is based on the size of the "nw" component. For more information about split positions, see the UISplitLayout overview.

See Also: setPos

getStyle

public int getStyle();

Retrieves the style of the split viewer control.

Return Value:

Returns an integer that contains the current style setting. Possible style values include HORIZONTAL for a horizontal split, or 0 for a vertical split.

mouseDown

public boolean mouseDown(Event e, int x, int y);

Responds to the mouse button being pressed while it is over the splitter component.

Return Value:

Returns true if the event was handled; otherwise, returns false.

Parameter	Description
e	The event posted to the split viewer control.
x	The x coordinate of the event.
y	The y coordinate of the event.

Remarks:

This method darkens the splitter component's background color. The color remains darkened while the mouse button is pressed or dragged. When the mouse button is released, the original color is restored.

See Also: mouseUp, mouseDrag

mouseDrag

public boolean mouseDrag(Event e, int x, int y);

Responds to the splitter component being dragged with the mouse.

Return Value:

Returns true if the event was handled; otherwise, returns false.

Parameter	Description
e	The event posted to the split viewer control.
x	The x coordinate of the event.
y	The y coordinate of the event.

Remarks:

As the splitter component is dragged, this method adjusts its position accordingly. When the mouse button is released, the layout of all components is updated to reflect the new position of the splitter component.

See Also: mouseDown, mouseUp

mouseUp

public boolean mouseUp(Event e, int x, int y);

Responds to the mouse button being released while it is over the splitter component.

Return Value:

Returns true if the event was handled; otherwise, returns false.

Parameter	Description
e	The event posted to the split viewer control.
x	The x coordinate of the event.
y	The y coordinate of the event.

Remarks:

This method compares the position of the splitter component when the mouse button was first pressed to its position when the mouse button is released. If the position has changed, mouseUp sets the new split position and validates the control to update the layout of all components.

When the mouse button is first pressed, the mouseDown method darkens the splitter component's background color. mouseUp restores the original color.

See Also: mouseDrag

setPos

public void setPos(int pos);

Sets the current split position.

Return Value:

No return value.

Parameter	Description
pos	The split position to be used by the layout manager.

Remarks:

This method sets the split position of the control's layout manager, which is based on the size of the "nw" component. The "nw" and "se" components are then invalidated to reflect the new split position. For more information about split positions, see the UISplitLayout overview.

Exceptions:

IllegalArgumentException if the specified position was less than -100.

See Also: getPos

Fields

HORIZONTAL

Specifies that the split layout manager will create a horizontal split, where the container consists of top (north) and bottom (south) panes. The default style is a vertical split with left (west) and right (east) panes.