Class AwtUIHost

public class AwtUIHost extends Panel
{
  // Constructors
  public AwtUIHost();
  public AwtUIHost(IUIComponent comp);

  // Methods
  public IUIComponent add(IUIComponent comp);
  public IUIComponent add(IUIComponent comp, int index);
  public IUIComponent add(String name, IUIComponent comp);
  public IUIComponent add(IUIComponent comp, Object constraints);
  public IUIComponent add(IUIComponent comp, Object constraints,
        int index);
  public synchronized void addComponentListener(
        ComponentListener l);
  public synchronized void addContainerListener(
        ContainerListener l);
  public synchronized void addFocusListener(FocusListener l);
  public synchronized void addKeyListener(KeyListener l);
  public synchronized void addMouseListener(MouseListener l);
  public synchronized void addMouseMotionListener(
        MouseMotionListener l);
  public void addNotify();
  public void disable();
  protected final void disableHostEvents(long eventsToDisable);
  public void enable();
  protected final void enableHostEvents(long eventsToEnable);
  public IUIComponent getComponent(IUIComponent comp);
  public int getComponentIndex(IUIComponent comp);
  public IUIComponent getHeader();
  public Dimension getPreferredSize();
  public UIRoot getRoot();
  public IUIComponent getUIComponent(int index);
  public int getUIComponentCount();
  public boolean handleEvent(Event evt);
  public void hide();
  public void invalidate();
  public void layout();
  public void paint(Graphics g);
  public void paintAll(Graphics g);
  public boolean postEvent(Event e);
  public Dimension preferredSize();
  protected final void preProcessHostEvent(Event e);
  protected void processComponentEvent(ComponentEvent e);
  protected void processContainerEvent(ContainerEvent e);
  protected void processEvent(AWTEvent e);
  protected void processFocusEvent(FocusEvent e);
  protected void processHostEvent(AWTEvent e);
  protected void processKeyEvent(KeyEvent e);
  protected void processMouseEvent(MouseEvent e);
  protected void processMouseMotionEvent(MouseEvent e);
  public synchronized void remove(Component comp);
  public void remove(int index);
  public void remove(IUIComponent comp);
  public void remove(int index);
  public void remove(IUIComponent comp);
  public void removeAll();
  public synchronized void removeComponentListener(
        ComponentListener l);
  public synchronized void removeContainerListener(
        ContainerListener l);
  public synchronized void removeFocusListener(FocusListener l);
  public synchronized void removeKeyListener(KeyListener l);
  public synchronized void removeMouseListener(MouseListener l);
  public synchronized void removeMouseMotionListener(
        MouseMotionListener l);
  public void removeNotify();
  public void setBackground(Color clr);
  public void setFont(Font fnt);
  public void setForeground(Color clr);
  public void setHeader(IUIComponent header);
  public void setLayout(IUILayoutManager lm);
  public void show();
  public void show(boolean on);
  public void update(Graphics g);
  public void validate();
  protected void validateTree();
}

This class links AWT with AFC. AwtUIHost extends the Panel class in AWT and is associated with a UIRoot container. (UIRoot extends the UIPanel class in AFC.) Every host is associated with a root container, and every root container is associated with a host.

AwtUIHost also provides the base support for the AwtUI and UI classes. For example, an AwtUITree object is an AWT-based control that hosts a UITree object. The AwtUITree object integrates AFC with AWT.

Panel
  |
  +--AwtUIHost

Constructors

AwtUIHost

public AwtUIHost();

Creates a host.

Remarks:

By default, the host's associated root container is created without a header component. However, you can set a header at any time by calling setHeader. To add other components to the root container, call add.

For more information about the root container, see the AwtUIHost overview. For more information about header components, see the UIPanel overview.

AwtUIHost

public AwtUIHost(IUIComponent comp);

Creates a host using the specified component.

Parameter	Description
comp	The component to be used for the root container's header.

Remarks:

The host's associated root container is created using the specified component for its header. Later, you can change the header component by calling setHeader. To add other components to the root container, call add.

For more information about the root container, see the AwtUIHost overview. For more information about header components, see the UIPanel overview.

Methods

add

public IUIComponent add(IUIComponent comp);

Adds the specified component to the associated root container.

Return Value:

Returns the component that was added, if successful; otherwise, returns null.

Parameter	Description
comp	The component to be added.

See Also: remove, setHeader

add

public IUIComponent add(IUIComponent comp, int index);

Adds the specified component to the associated root container at the specified index.

Return Value:

Returns the component that was added, if successful; otherwise, returns null.

Parameter	Description
comp	The component to be added.
index	The zero-based index at which to insert the component. To add the component at the end, pass -1. If the root container has a header component, the header is at index 0, and the first child begins at index 1. Otherwise, the first child begins at index 0. For more information about header components, see the UIPanel overview.

See Also: remove, setHeader

add

public IUIComponent add(String name, IUIComponent comp);

Adds the specified component to the associated root container, according to the specified layout location.

Return Value:

Returns the component that was added, if successful; otherwise, returns null.

Parameter	Description
name	The layout name identifying where to add the component. This value depends on the root container's current layout manager.
comp	The component to be added.

See Also: remove, setHeader

add

public IUIComponent add(IUIComponent comp, Object constraints);

Adds the specified component to the associated root container according to the specified layout constraints.

Return Value:

Returns the component that was added, if successful; otherwise, returns null.

Parameter	Description
comp	The component to be added.
constraints	The layout constraints identifying where to add the component. This value depends on the root container's current layout manager.

See Also: remove, setHeader

add

public IUIComponent add(IUIComponent comp, Object constraints, int index);

Adds the specified component to the associated root container according to the specified layout constraints and index.

Return Value:

Returns the component that was added, if successful; otherwise, returns null.

Parameter	Description
comp	The component to be added.
constraints	The layout constraints identifying where to add the component. This value depends on the root container's current layout manager.
index	The zero-based index at which to insert the component. To add the component at the end, pass -1. If the root container has a header component, the header is at index 0, and the first child begins at index 1. Otherwise, the first child begins at index 0. For more information about header components, see the UIPanel overview.

See Also: remove, setHeader

addComponentListener

public synchronized void addComponentListener(ComponentListener l);

Adds the specified component listener. The listener receives all component events generated for the control.

Return Value:

No return value.

Parameter	Description
l	The component listener to be added.

See Also: removeComponentListener

addContainerListener

public synchronized void addContainerListener(ContainerListener l);

Adds the specified container listener. The listener receives all container events generated for the control.

Return Value:

No return value.

Parameter	Description
l	The container listener to be added.

See Also: removeContainerListener

addFocusListener

public synchronized void addFocusListener(FocusListener l);

Adds the specified focus listener. The listener receives all focus events generated for the control.

Return Value:

No return value.

Parameter	Description
l	The focus listener to be added.

See Also: removeFocusListener

addKeyListener

public synchronized void addKeyListener(KeyListener l);

Adds the specified key listener. The listener receives all key events generated for the control.

Return Value:

No return value.

Parameter	Description
l	The key listener to be added.

See Also: removeKeyListener

addMouseListener

public synchronized void addMouseListener(MouseListener l);

Adds the specified mouse listener. The listener receives all mouse events generated for the control.

Return Value:

No return value.

Parameter	Description
l	The mouse listener to be added.

See Also: removeMouseListener

addMouseMotionListener

public synchronized void addMouseMotionListener(MouseMotionListener l);

Adds the specified mouse motion listener. The listener receives all mouse motion events generated for the control.

Return Value:

No return value.

Parameter	Description
l	The mouse motion listener to be added.

See Also: removeMouseMotionListener

addNotify

public void addNotify();

Invokes addNotify for each component in the associated root container.

Return Value:

No return value.

See Also: removeNotify

disable

public void disable();

Disables the host.

Return Value:

No return value.

Remarks:

If the associated root container has a header component, this method also disables the root's header.

disableHostEvents

protected final void disableHostEvents(long eventsToDisable);

Disables the events defined by the specified event mask parameter from being delivered to this component.

Return Value:

No return value.

Parameter	Description
eventsToDisable	the event mask defining the event types.

enable

public void enable();

Enables the host.

Return Value:

No return value.

Remarks:

If the associated root container has a header component, this method also enables the root's header.

enableHostEvents

protected final void enableHostEvents(long eventsToEnable);

Enables the events defined by the specified event mask parameter to be delivered to this component.

Return Value:

No return value.

Parameter	Description
eventsToEnable	the event mask defining the event types.

Remarks:

Event types are automatically enabled when a listener for that type is added to the component. Therefore, this method only needs to be invoked by subclasses of a component requiring the specified event types delivered to processHostEvent, regardless of whether a listener is registered.

getComponent

public IUIComponent getComponent(IUIComponent comp);

Retrieves the component contained in the associated root container that is the ancestor of the specified component. The header component or any child component can be retrieved.

Return Value:

Returns the root container's immediate child or header component that is the ancestor of the specified component. If the specified component is itself an immediate child (or header) of the root container, this component is returned. If the root container is not an ancestor of the specified component, null is returned.

Parameter	Description
comp	The component to find the ancestor for.

getComponentIndex

public int getComponentIndex(IUIComponent comp);

Retrieves the index of the specified component within the associated root container.

Return Value:

Returns the zero-based index of the component (if the component belongs to the root container); otherwise, returns -1.

Parameter	Description
comp	The component to retrieve the index for. This component can be the header component or any child component.

Remarks:

If the root container has a header component, the header is at index 0, and the first child begins at index 1. Otherwise, the first child begins at index 0.

getHeader

public IUIComponent getHeader();

Retrieves the header component of the associated root container.

Return Value:

Returns the current header component (if the root container has a header); otherwise, returns null.

Remarks:

Header components are used by containers to represent the container itself. For example, the text displayed on a button is used as its header component. For more information about headers, see the UIPanel overview.

If the frame was constructed with an IUIComponent object, the root container initially uses this component for its header.

See Also: setHeader

getPreferredSize

public Dimension getPreferredSize();

Retrieves the preferred dimensions (in pixels) for displaying the associated root container and its components.

Return Value:

Returns a Dimension object containing the preferred size.

See Also: preferredSize

getRoot

public UIRoot getRoot();

Retrieves the host's root container.

Return Value:

Returns the UIRoot object associated with the host.

getUIComponent

public IUIComponent getUIComponent(int index);

Retrieves the component at the specified index in the associated root container.

Return Value:

Returns the specified component.

Parameter	Description
index	The zero-based index of the component to be retrieved. If the root container has a header component, the header is at index 0 and the first child begins at index 1. Otherwise, the first child begins at index 0.

getUIComponentCount

public int getUIComponentCount();

Retrieves the number of components (including the header) contained in the associated root container.

Return Value:

Returns the total number of components.

handleEvent

public boolean handleEvent(Event evt);

Handles the specified event.

Return Value:

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

Parameter	Description
evt	The event.

Remarks:

If a listener has been added through a call to addXXXListener, this method calls processHostEvent to handle the event. Otherwise, the event is handled by one of the event methods (such as action or mouseDown).

hide

public void hide();

Hides the host and its root container.

Return Value:

No return value.

invalidate

public void invalidate();

Invalidates the host, and then updates the layout of the associated root container.

Return Value:

No return value.

layout

public void layout();

Lays out the components in the associated root container.

Return Value:

No return value.

paint

public void paint(Graphics g);

Draws the associated root container.

Return Value:

No return value.

Parameter	Description
g	The graphics context.

paintAll

public void paintAll(Graphics g);

Draws the associated root container and its components.

Return Value:

No return value.

Parameter	Description
g	The graphics context.

postEvent

public boolean postEvent(Event e);

Posts the specified event.

Return Value:

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

Parameter	Description
e	The event.

Remarks:

This method is called by processEvent. If the event's target is the host itself, the event is forwarded to the associated root container for handling. Otherwise, handleEvent is invoked.

preferredSize

public Dimension preferredSize();

Retrieves the preferred dimensions (in pixels) for displaying the associated root container and its components.

Return Value:

Returns a Dimension object containing the preferred size.

See Also: getPreferredSize

preProcessHostEvent

protected final void preProcessHostEvent(Event e);

Called by handleEvent to process the specified event.

Return Value:

No return value.

Parameter	Description
e	The event.

Remarks:

This method is automatically invoked if a listener has been registered through a call to addXXXListener. The preProcessHostEvent method first converts the specified Event object to an AWTEvent object, and then calls processHostEvent(AWTEvent e) to dispatch the event to the appropriate handler. A check is made if the event has been enabled through enableHostEvent or has a listener attached before it is dispatched.

processComponentEvent

protected void processComponentEvent(ComponentEvent e);

Processes component events.

Return Value:

No return value.

Parameter	Description
e	The component event.

Remarks:

This method is called by processHostEvent and dispatches the event to a registered component listener. When overriding this method, call the super method processComponentEvent to ensure the default event processing continues normally.

See Also: addComponentListener

processContainerEvent

protected void processContainerEvent(ContainerEvent e);

Processes container events.

Return Value:

No return value.

Parameter	Description
e	The container event.

Remarks:

This method is called by processHostEvent and dispatches the event to a registered key listener. When overriding this method, call the super method processContainerEvent to ensure the default event processing continues normally.

See Also: addContainerListener

processEvent

protected void processEvent(AWTEvent e);

Called by dispatchEvent to post the specified event.

Return Value:

No return value.

Parameter	Description
e	The event that has been generated.

Remarks:

This method first converts the specified AWTEvent object to an Event object, and then calls postEvent.

processFocusEvent

protected void processFocusEvent(FocusEvent e);

Processes focus events.

Return Value:

No return value.

Parameter	Description
e	The focus event.

Remarks:

This method is called by processHostEvent and dispatches the event to a registered focus listener. When overriding this method, call the super method processFocusEvent to ensure the default event processing continues normally.

See Also: addFocusListener

processHostEvent

protected void processHostEvent(AWTEvent e);

Processes the specified event.

Return Value:

No return value.

Parameter	Description
e	The event.

Remarks:

This method is called by processHostEvent(Event e). Depending on the type of event, processHostEvent calls one of the following methods.

Event type	Method called
component event	processComponentEvent
container event	processContainerEvent
focus event	processFocusEvent
key event	processKeyEvent
mouse event	processMouseEvent
mouse motion event	processMouseMotionEvent

When overriding processHostEvent, call the super method processHostEvent to ensure the default event processing continues normally.

processKeyEvent

protected void processKeyEvent(KeyEvent e);

Processes key events.

Return Value:

No return value.

Parameter	Description
e	The key event.

Remarks:

This method is called by processHostEvent and dispatches the event to a registered key listener. When overriding this method, call the super method processKeyEvent to ensure the default event processing continues normally.

See Also: addKeyListener

processMouseEvent

protected void processMouseEvent(MouseEvent e);

Processes mouse events.

Return Value:

No return value.

Parameter	Description
e	The mouse event.

Remarks:

This method is called by processHostEvent and dispatches the event to a registered mouse listener. When overriding this method, call the super method processMouseEvent to ensure the default event processing continues normally.

See Also: addMouseListener

processMouseMotionEvent

protected void processMouseMotionEvent(MouseEvent e);

Processes mouse motion events.

Return Value:

No return value.

Parameter	Description
e	The mouse motion event.

Remarks:

This method is called by processHostEvent and dispatches the event to a registered mouse motion listener. When overriding this method, call the super method processMouseMotionEvent to ensure the default event processing continues normally.

See Also: addMouseMotionListener

remove

public synchronized void remove(Component comp);

Removes the specified AwtUI component from the control.

Return Value:

No return value.

Parameter	Description
comp	The AwtUI component to be removed. (Pure AWT components cannot be removed.)

remove

public void remove(int index);

Removes the component at the specified index from the associated root container.

Return Value:

No return value.

Parameter	Description
index	The zero-based index of the component to be removed. If the root container has a header component, the header is at index 0 and the first child begins at index 1. Otherwise, the first child begins at index 0.

See Also: removeAll, add

remove

public void remove(IUIComponent comp);

Removes the specified component from the associated root container.

Return Value:

No return value.

Parameter	Description
comp	The component to be removed.

See Also: removeAll, add

remove

public void remove(int index);

Removes the component at the specified index from the associated root container.

Return Value:

No return value.

Parameter	Description
index	The zero-based index of the component to be removed. If the root container has a header component, the header is at index 0 and the first child begins at index 1. Otherwise, the first child begins at index 0.

See Also: removeAll, add

remove

public void remove(IUIComponent comp);

Removes the specified component from the associated root container.

Return Value:

No return value.

Parameter	Description
comp	The component to be removed.

See Also: removeAll, add

removeAll

public void removeAll();

Removes all components from the associated root container, including the header component.

Return Value:

No return value.

See Also: remove, add

removeComponentListener

public synchronized void removeComponentListener(ComponentListener l);

Removes the specified component listener. The listener no longer receives the control's component events.

Return Value:

No return value.

Parameter	Description
l	The component listener to be removed.

See Also: addComponentListener

removeContainerListener

public synchronized void removeContainerListener(ContainerListener l);

Removes the specified container listener. The listener no longer receives the control's container events.

Return Value:

No return value.

Parameter	Description
l	The container listener to be removed.

See Also: addContainerListener

removeFocusListener

public synchronized void removeFocusListener(FocusListener l);

Removes the specified focus listener. The listener no longer receives the control's focus events.

Return Value:

No return value.

Parameter	Description
l	The focus listener to be removed.

See Also: addFocusListener

removeKeyListener

public synchronized void removeKeyListener(KeyListener l);

Removes the specified key listener. The listener no longer receives the control's key events.

Return Value:

No return value.

Parameter	Description
l	The key listener to be removed.

See Also: addKeyListener

removeMouseListener

public synchronized void removeMouseListener(MouseListener l);

Removes the specified mouse listener. The listener no longer receives the control's mouse events.

Return Value:

No return value.

Parameter	Description
l	The mouse listener to be removed.

See Also: addMouseListener

removeMouseMotionListener

public synchronized void removeMouseMotionListener(MouseMotionListener l);

Removes the specified mouse motion listener. The listener no longer receives the control's mouse motion events.

Return Value:

No return value.

Parameter	Description
l	The mouse motion listener to be removed.

See Also: addMouseMotionListener

removeNotify

public void removeNotify();

Invokes removeNotify for each component in the associated root container.

Return Value:

No return value.

See Also: addNotify

setBackground

public void setBackground(Color clr);

Sets the host's background color.

Return Value:

No return value.

Parameter	Description
clr	The background color to be used by the host.

Remarks:

If the associated root container has a header component, this method also sets the background color of the header.

setFont

public void setFont(Font fnt);

Sets the host's font.

Return Value:

No return value.

Parameter	Description
fnt	The font to be used by the host.

Remarks:

If the associated root container has a header component, this method also sets the font of the header.

setForeground

public void setForeground(Color clr);

Sets the host's foreground color.

Return Value:

No return value.

Parameter	Description
clr	The foreground color to be used by the host.

Remarks:

If the associated root container has a header component, this method also sets the foreground color of the header.

setHeader

public void setHeader(IUIComponent header);

Sets the header component of the associated root container.

Parameter	Description
header	The component to be used as the root container's header component.

Remarks:

Header components are used by containers to represent the container itself. For example, the text displayed on a button is used as its header component. For more information about headers, see the UIPanel overview.

If the host was constructed with an IUIComponent object, the root container initially uses this component for its header. To add other child components, call add.

See Also: getHeader

setLayout

public void setLayout(IUILayoutManager lm);

Sets the layout manager of the associated root container.

Return Value:

No return value.

Parameter	Description
lm	The new layout manager to be used.

show

public void show();

Shows the host and its root container.

Return Value:

No return value.

show

public void show(boolean on);

Shows the host and optionally shows the root container.

Return Value:

No return value.

Parameter	Description
on	If true, the root container is made visible; otherwise, it is hidden.

update

public void update(Graphics g);

Updates the associated root container by redrawing the container and all its components.

Return Value:

No return value.

Parameter	Description
g	The graphics context.

validate

public void validate();

Validates the host and the associated root container.

Return Value:

No return value.

validateTree

protected void validateTree();

Validates the host and all of its descendants, and then validates the associated root container.

Return Value:

No return value.