Previous
Contents
Index
Next
| Package com.ms.ui |
Previous |
Contents |
Index |
Next |
public class UIScrollViewer extends UIPanel implements IUIPosition
{
// Fields
public final static int SCROLL_LEFT;
public final static int SCROLL_TOP;
public final static int HEADER_RIGHT;
public final static int HEADER_BOTTOM;
public final static int CONTENT;
public final static int SCROLL_VERT;
public final static int SCROLL_HORZ;
public final static int SCROLL_CORNER;
public final static int HEADER_VERT;
public final static int HEADER_HORZ;
public final static int HEADER_CORNER;
// Constructors
public UIScrollViewer(Component comp);
public UIScrollViewer(Component comp, int style);
public UIScrollViewer(Component comp, int hLine, int vLine);
public UIScrollViewer(Component comp, int hLine, int vLine, int style);
public UIScrollViewer(Component comp, int hLine, int vLine, int style,
int scrollStyle);
public UIScrollViewer(Component comp, int hLine, int vLine, int style,
int hstyle, int vstyle);
// Methods
public Component add(int index, Component comp);
public void remove(Component comp);
public Component getContent();
public Component setContent(Component content);
public Point getPosition();
public int getXPosition();
public int getYPosition();
public Point setPosition(Point pt);
public Point setPosition(int x, int y);
public int setXPosition(int x);
public int setYPosition(int y);
public int getHLine();
public Point getLine();
public int getVLine();
public void setHLine(int line);
public void setLine(int hLine, int vLine);
public void setVLine(int line);
public Component getLayoutComponent(int index);
public int continueInvalidate();
public boolean continueInvalidate(Component check);
public void layout();
public boolean ensureVisible(Rectangle rect);
public void fullValidate(Component comp);
public Dimension minimumSize();
public Dimension preferredSize();
public int getRoleCode();
public boolean keyDown(Event e, int key);
public boolean handleEvent(Event e);
}
A class that manages a scroll viewer control. UIScrollViewer typically uses a UIViewer object for content, which displays another component. The scroll viewer control additionally displays other components, such as scroll bars and header bars.
When creating a UIScrollViewer object, you specify the content component, optional scroll line increments, and optional style flags. You can pass any bitwise combination of the following flags for the scroll viewer's style.
| Scroll Viewer Style | Description |
| SCROLL_TOP | Places the horizontal scroll bar on the top of the scroll viewer panel. The default position is on the bottom. |
| SCROLL_LEFT | Places the vertical scroll bar on the left side of the scroll viewer panel. The default position is on the right. |
| HEADER_BOTTOM | Places the horizontal header bar on the bottom of the scroll viewer panel. The default position is on the top. |
| HEADER_RIGHT | Places the vertical header bar on the right side of the scroll viewer panel. The default position is on the left. |
The following example shows different ways of constructing UIScrollViewer objects.
// Construct a scroll viewer that displays the graphical // image stored in the variable myImage. Accept the default // scroll line increments and the default style. UIScrollViewer sv1 = new UIScrollViewer(new UIGraphic(myImage)); // Construct a scroll viewer that displays the UIList // object myList. Specify scroll line increments of // 15 pixels. Position the horizontal scroll bar on // the top of the scroll viewer panel. UIScrollViewer sv2 = new UIScrollViewer(myList, 15, 15, UIScrollViewer.SCROLL_TOP); // Now add sv1 and sv2 to the container. add(sv1); add(sv2);
Note that you can also specify a style for each scroll bar. The following flags define valid scroll bar styles.
| Scroll Bar Style | Description |
| UIScroll.NOHIDE | Always displays the scroll bar; the scroll bar is disabled if it is not needed. By default, scroll bars are displayed only when necessary. |
| UIScroll.NOSHOW | Always hides the scroll bar. By default, scroll bars are displayed only when necessary. |
The following example shows how to construct a UIScrollViewer object with scroll bar styles. You can specify a style for both scroll bars in one parameter, or you can specify a separate style for each scroll bar in two parameters.
// Construct a scroll viewer that displays the UITree
// object myTree1. Always show both scroll bars.
UIScrollViewer sv3 =
new UIScrollViewer(myTree1, 15, 15, UIScrollViewer.SCROLL_TOP,
UIScroll.NOHIDE);
// Construct a scroll viewer that displays the UITree
// object myTree2. Always show the horizontal scroll
// bar and always hide the vertical scroll bar.
UIScrollViewer sv4 =
new UIScrollViewer(myTree2, 15, 15, UIScrollViewer.SCROLL_TOP,
UIScroll.NOHIDE, UIScroll.NOSHOW);
// Add sv3 and sv4 to the container.
add(sv3);
add(sv4);
When a UIScrollViewer object is created, it contains only content and scroll bar components. To add other components, or replace existing components, call the add method. Each type of component that can be displayed is identified by a layout index, defined as follows.
| Layout Index | Component |
| CONTENT | The content component. |
| SCROLL_HORZ | The horizontal scroll bar (by default, a UIScrollBar object). |
| SCROLL_VERT | The vertical scroll bar (by default, a UIScrollBar object). |
| SCROLL_CORNER | The corner component between the scroll bars. |
| HEADER_HORZ | The horizontal header bar. |
| HEADER_VERT | The vertical header bar. |
| HEADER_CORNER | The corner component between the header bars. |
Note that the SCROLL_HORZ and SCROLL_VERT components must implement the IUIScroll interface; otherwise, they cannot be added. The CONTENT, HEADER_HORZ, and HEADER_VERT components must implement IUIPosition; if they do not, add first converts them to UIViewer objects before adding them to the scroll viewer control. Note that to set the content, you can also call the setContent method, which returns the previous content component. The following example shows how to add (or replace) components.
// Construct a scroll viewer that displays the UIList // object myList. When a UIScrollViewer object is created, // the content is first added to a UIViewer object, which // is then added to the scroll viewer. UIScrollViewer sv = new UIScrollViewer(myList); add(sv); // Add sv to the container. // Now add the component myHeader to sv as a horizontal // header bar. If myHeader does not implement IUIPosition, // it is first converted to a UIViewer object. sv.add(UIScrollViewer.HEADER_HORZ, myHeader); // Replace the content in sv with the UITree object myTree. sv.add(UIScrollViewer.CONTENT, myTree); // Call setContent to replace the content in sv with the // graphical image stored in myImage. Save the previous content // component in the variable oldContents. Component oldContents = sv.setContent(new UIGraphic(myImage));
Class UIColumnViewer extends UIScrollViewer.
public UIScrollViewer(Component comp);Creates a scroll viewer control using the specified component for content.
Parameter Description comp The component to be displayed within the scroll viewer control. Remarks:
By default, the content component's horizontal and vertical scroll line increments are defined to be 10 pixels each. The scroll viewer will display scroll bars only when they are needed to view the content component.
public UIScrollViewer(Component comp, int style);Creates a scroll viewer control using the specified component for content and the specified style.
Parameter Description comp The component to be displayed within the scroll viewer control. style The style of the scroll viewer control. For a list of valid styles, see the UIScrollViewer overview. Remarks:
By default, the content component's horizontal and vertical scroll line increments are defined to be 10 pixels each. If any undefined style bits are specified, an IllegalArgumentException is thrown.
public UIScrollViewer(Component comp, int hLine, int vLine);Creates a scroll viewer control using the specified component for content and the specified scroll line increments.
Parameter Description comp The component to be displayed within the scroll viewer control. hLine The horizontal scroll line increment (in pixels) for the content component. vLine The vertical scroll line increment (in pixels) for the content component. Remarks:
By default, the scroll viewer will display scroll bars only when they are needed to view the content component.
public UIScrollViewer(Component comp, int hLine, int vLine, int style);Creates a scroll viewer control using the specified component, the specified scroll line increments, and the specified style.
Parameter Description comp The component to be displayed within the scroll viewer control. hLine The horizontal scroll line increment (in pixels) for the content component. vLine The vertical scroll line increment (in pixels) for the content component. style The style of the scroll viewer control. For a list of valid styles, see the UIScrollViewer overview. Remarks:
If any undefined style bits are specified, an IllegalArgumentException is thrown.
public UIScrollViewer(Component comp, int hLine, int vLine, int style, int scrollStyle);Creates a scroll viewer control using the specified component, the specified scroll line increments, and the specified styles.
Parameter Description comp The component to be displayed within the scroll viewer control. hLine The horizontal scroll line increment (in pixels) for the content component. vLine The vertical scroll line increment (in pixels) for the content component. style The style of the scroll viewer control. For a list of valid styles, see the UIScrollViewer overview. scrollStyle The style of both scroll bars. Specify UIScroll.NOHIDE or UIScroll.NOSHOW. NOHIDE always displays the scroll bars, disabling them if they are unnecessary. NOSHOW always hides the scroll bars. Remarks:
If any undefined style bits are specified, an IllegalArgumentException is thrown.
public UIScrollViewer(Component comp, int hLine, int vLine, int style, int hstyle, int vstyle);Creates a scroll viewer control using the specified component, the specified scroll line increments, and the specified styles.
Parameter Description comp The component to be displayed within the scroll viewer control. hLine The horizontal scroll line increment (in pixels) for the content component. vLine The vertical scroll line increment (in pixels) for the content component. style The style of the scroll viewer control. For a list of valid styles, see the UIScrollViewer overview. hstyle The style of the horizontal scroll bar. Specify UIScroll.NOHIDE or UIScroll.NOSHOW. NOHIDE always displays the scroll bar, disabling it if the scroll bar is unnecessary. NOSHOW always hides the scroll bar. vstyle The style of the vertical scroll bar. Specify UIScroll.NOHIDE or UIScroll.NOSHOW. See hstyle for descriptions of these styles. Remarks:
If any undefined style bits are specified, an IllegalArgumentException is thrown.
public Component add(int index, Component comp);Adds the specified component at the specified layout index. If a component already exists at this index, it is replaced with the specified component.
Return Value:
Returns the component that was added, or null if the component could not be added.
Parameter Description index The layout index of the component to be added or replaced. For a list of possible values, see the UIScrollViewer overview. If an undefined layout index is specified, an IllegalArgumentException is thrown. comp The new component to use. Remarks:
When adding components, the SCROLL_HORZ and SCROLL_VERT components must implement the IUIScroll interface; otherwise, they cannot be added. The CONTENT, HEADER_HORZ, and HEADER_VERT components must implement IUIPosition; if they do not, add first converts them to UIViewer objects before adding them to the scroll viewer control. Note that to set the content, you can also call the setContent method, which returns the previous content component. For examples of how to call add and setContent, see the UIScrollViewer overview.
public int continueInvalidate();Determines whether the container should be invalidated when a child component is invalidated.
Return Value:
Returns 0 to indicate that each component must be queried to determine whether the container should be invalidated.
Remarks:
To query a child component, call continueInvalidate with the specified component as a parameter.
public boolean continueInvalidate(Component check);Determines whether the container should be invalidated when the specified child component is invalidated.
Return Value:
Returns true if the container should be invalidated; otherwise, returns false.
Parameter Description check The component to be invalidated. Remarks:
This method returns true if the specified component is a header bar or a scroll bar. If the component is the header bar corner, scroll bar corner, or content component, this method returns false.
public boolean ensureVisible(Rectangle rect);Brings the area identified by the specified rectangle into view.
Return Value:
Returns true if any component was moved or resized to make the rectangle visible; otherwise, returns false.
Parameter Description rect The rectangle identifying the area to be made visible. Remarks:
This method is called when the scroll viewer control has focus. If the entire rectangle does not fit inside the viewer control, the top-right corner of the rectangle is favored.
public void fullValidate(Component comp);Performs a validation from the root container on the specified component.
Return Value:
No return value.
Parameter Description comp The component to be validated.
public Component getContent();Retrieves the component currently being displayed in the scroll viewer control.
Return Value:
Returns the content component. If the scroll viewer's content is a UIViewer object, the content component of the UIViewer object is returned.
Remarks:
To retrieve other components in the scroll viewer (such as scroll bars and header bars), call the getLayoutComponent method. Note that calling getContent is different than calling getLayoutComponent with the CONTENT index. If the scroll viewer's content is a UIViewer object, getLayoutComponent returns the UIViewer object, while getContent returns the content of the UIViewer object.
For more information about scroll viewers and their content, see the UIScrollViewer overview.
public int getHLine();Retrieves the number of pixels associated with a horizontal scroll position.
Return Value:
Returns the number of pixels in the horizontal scroll bar's scroll line.
public Component getLayoutComponent(int index);Retrieves the component at the specified layout index.
Return Value:
Returns the specified component, or null if no such component exists.
Parameter Description index The layout index of the component to be retrieved. For a list of possible values, see the UIScrollViewer overview. If an undefined layout index is specified, an IllegalArgumentException is thrown. Remarks:
Note that calling getLayoutComponent with the CONTENT index is different than calling getContent. If the scroll viewer's content is a UIViewer object, getLayoutComponent returns the UIViewer object, while getContent returns the content of the UIViewer object.
For more information about scroll viewers and their content, see the UIScrollViewer overview.
public Point getLine();Retrieves the number of pixels associated with horizontal and vertical scroll positions.
Return Value:
Returns a Point containing the number of pixels in a scroll line. The point's x coordinate specifies the horizontal scroll line; the y coordinate specifies the vertical scroll line.
public int getRoleCode();Retrieves the role of the scroll viewer control.
Return Value:
Returns the ROLE_SYSTEM code that best describes the role of the control.
Remarks:
This method returns the ROLE_SYSTEM_PANE code.
public Point getPosition();Retrieves the current position of the scroll viewer's content.
Return Value:
Returns a Point object containing the content component's position. The x and y coordinates of the point specify the horizontal and vertical positions (in pixels), respectively.
Remarks:
This method implements getPosition in the IUIPosition interface.
public int getVLine();Retrieves the number of pixels associated with a vertical scroll position.
Return Value:
Returns the number of pixels in the vertical scroll bar's scroll line.
public int getXPosition();Retrieves the horizontal position of the scroll viewer's content component.
Return Value:
Returns the horizontal position (in pixels).
Remarks:
This method implements getXPosition in the IUIPosition interface.
public int getYPosition();Retrieves the vertical position of the scroll viewer's content component.
Return Value:
Returns the vertical position (in pixels).
Remarks:
This method implements getYPosition in the IUIPosition interface.
public boolean handleEvent(Event e);Responds to scroll events sent from the horizontal and vertical scroll bars by adjusting the content, header, and scroll bar components.
Return Value:
Returns true if the event was handled; otherwise, returns false.
Parameter Description e The event.
public boolean keyDown(Event e, int key);Responds to certain keys being pressed by scrolling the content component accordingly.
Return Value:
Returns true if the event was handled; otherwise, returns false.
Parameter Description e The event posted to the scroll viewer control. key The key that has been pressed. Remarks:
This method is called when the control has focus and a key is pressed. keyDown responds to the following key values.
Key Action HOME, END, PAGEUP, PAGEDOWN, UP ARROW, DOWN ARROW Adjusts the vertical scroll bar and the vertical position of the content component accordingly. The content component's horizontal position is set to 0. LEFT ARROW, RIGHT ARROW Adjusts the horizontal scroll bar and the horizontal position of the content component accordingly. The content component's vertical position is set to 0.
public void layout();Lays out the scroll viewer control and its components.
Return Value:
No return value.
Remarks:
When laying out the scroll bar components, this method adjusts the position of each scroll bar to reflect the current scroll position of the content component.
public Dimension minimumSize();Determines the minimum size of the scroll viewer control, based on the minimum size of each component.
Return Value:
Returns a Dimension object containing the minimum size (in pixels).
public Dimension preferredSize();Determines the preferred size of the scroll viewer control, based on the preferred size of each component.
Return Value:
Returns a Dimension object containing the preferred size (in pixels).
public void remove(Component comp);Removes the specified component from the scroll viewer control.
Return Value:
No return value.
Parameter Description comp The component to be removed. Remarks:
You can use the getLayoutComponent method to specify the component to be removed, as shown in the following example.
// Remove the horizontal scroll bar from // the UIScrollViewer object sv. sv.remove(sv.getLayoutComponent(UIScrollViewer.SCROLL_HORZ));To add a component to the scroll viewer control, call the add method.
public Component setContent(Component content);Sets the scroll viewer control's content to the specified component.
Return Value:
Returns the previous content component.
Parameter Description comp The component to be displayed within the scroll viewer control. Remarks:
To set the other components in the scroll viewer (such as scroll bars and header bars), call the add method. Note that calling setContent is different than calling add with the CONTENT index. setContent automatically converts the specified component to a UIViewer object, while add converts the component only if it does not implement the IUIPosition interface.
For more information about scroll viewers and their content, see the UIScrollViewer overview.
public void setHLine(int line);Sets the number of pixels associated with a horizontal scroll position.
Return Value:
No return value.
Parameter Description line The number of pixels for the horizontal scroll bar's scroll line.
public void setLine(int hLine, int vLine);Sets the number of pixels associated with horizontal and vertical scroll positions.
Return Value:
No return value.
Parameter Description hLine The number of pixels for the horizontal scroll bar's scroll line. vLine The number of pixels for the vertical scroll bar's scroll line.
public Point setPosition(Point pt);Moves the scroll viewer's content to the scroll position given by the specified point.
Return Value:
Returns a Point object containing the new position.
Parameter Description pt Identifies the position (in pixels) for the content component. The x coordinate of pt specifies the horizontal position; the y coordinate specifies the vertical position. Remarks:
This method implements setPosition in the IUIPosition interface.
public Point setPosition(int x, int y);Moves the scroll viewer's content to the position given by the specified values.
Return Value:
Returns a Point object containing the new position.
Parameter Description x The horizontal position for the content component (in pixels). y The vertical position for the content component (in pixels). Remarks:
This method implements setPosition in the IUIPosition interface.
public void setVLine(int line);Sets the number of pixels associated with a vertical scroll position.
Return Value:
No return value.
Parameter Description line The number of pixels for the vertical scroll bar's scroll line.
public int setXPosition(int x);Moves the scroll viewer's content in the horizontal direction by the specified amount.
Return Value:
Returns the new horizontal position.
Parameter Description x The horizontal position for the content component (in pixels). Remarks:
This method implements setXPosition in the IUIPosition interface.
public int setYPosition(int y);Moves the scroll viewer's content in the vertical direction by the specified amount.
Return Value:
Returns the new vertical position.
Parameter Description y The vertical scroll position for the content component (in pixels). Remarks:
This method implements setYPosition in the IUIPosition interface.
© 1997 Microsoft Corporation. All rights reserved. Legal Notices.