com.webobjects.eoapplication
Class EOComponentController

java.lang.Object
  |
  +--com.webobjects.eoapplication.EOController
        |
        +--com.webobjects.eoapplication.EOComponentController

All Implemented Interfaces:

EOAction.Enabling, NSDisposable, NSKeyValueCoding, NSKeyValueCoding.ErrorHandling, NSKeyValueCodingAdditions

Direct Known Subclasses:

EOActionTrigger, EOActionWidgetController, EOAppletController, EOArchiveController, EOBoxController, EOSplitController, EOStaticIconController, EOStaticLabelController, EOSwitchController, EOWidgetController, EOWindowController

public class EOComponentController

extends EOController

The EOComponentController class provides behavior for controllers that manage user interface components. A component controller has a component that represents the user interface for the controller itself (not for its subcontrollers), a subcontroller area for displaying the user interfaces for its subcontrollers, and an integration component -- a component that represents the controller when its shown in its supercontroller's user interface.

By default, a controller's integration component is simply the controller's component. In other words, a supercontroller adds its subcontroller's components to the subcontroller area of its component. However, the integration component can be a completely separate component. For example, the integration component for a window controller is a button that, when pushed, opens the window controller's window.

Also by default, a controller's subcontroller area is simply the controller's component. In the simplest case, a component controller doesn't have its own special user interface, but only serves to display the user interfaces of its subcontrollers. For example, EOComponentController's component is simply an EOView. It puts nothing in the view except its subcontroller's components. Thus, the subcontroller area is the controller's component -- the EOView. However, the subcontroller area can be a subcomponent of the controller's component. For example, an EOBoxController's component contains a border (etched or bezel, for example) which is the box controller's user interface. Its subcontroller area is a component located inside the border. This is where the box controller displays its subcontrollers.

Managing the Component

To access a component controller's component, use the component method. If the component hasn't yet been created, component creates it by invoking prepareComponent. And prepareComponent, in turn, invokes generateComponent to dynamically create the component. Subclasses should override generateComponent. The EOEntityController class provides an additional way to create user interfaces by loading interface file archives.

To see if a controller's component has already been created, use the method isComponentPrepared. Sometimes you need to know if a component has been created, because you can't configure its behavior after its creation. For example, if you want to set a component's alignment behavior, you have to set it with the EOComponentController method setAlignsComponents before the component controller creates its component.

All methods which return objects that might be created dynamically with the user interface of the controller (or loaded from an interface file archive) should invoke prepareComponent first. Example:

  private void JComponent _specialComponent;
  public void setSpecialComponent(JComponent component) {
      _specialComponent = component;
  }
  public JComponent specialComponent() {
      if (_specialComponent == null) {
          prepareComponent();
      }
      return _specialComponent;
  }
 

Visibility

A component controller is visible when its component is visible on screen. When a controller becomes visible, it ensures that it's connected to its supercontroller. However, a controller that's connected to its supercontroller isn't necessarily visible. For example, you might connect an invisible controller when you need to prepare it with data before making it visible.

Similarly, a controller can be "shown" or "hidden" in its supercontroller without changing the controller's visibility. The method showInSupercontroller ensures that the receiver's integration component is displayed in its supercontroller's component. This doesn't necessarily change the visibility of the controller. For example, a tab switch controller might switch to another view, but if the tab view itself isn't visible when the change occurs, the subcontroller doesn't become visible.

Component Appearance

A component controller's component can have an icon and a label. The component can be represented in the user interface with icon only, label only, or with both icon and label. A component specifies which representation it prefers. A controller can prefer to be represented with an icon only, but can't require it. This is because the controller might not have an icon or a supercontroller trying to represent a subcontroller cannot deal with icons. If the controller prefers icon only and has an icon, then the controller is represented with the icon only. If the controller doesn't prefer icon only and has an icon, then the controller is represented with its icon and label. If the controller doesn't have an icon, the controller is represented with the label only.

A controller always has a label. If the controller's label hasn't been explicitly set, the controller tries to derive one from the entity and property information it has or derives one from its subcontrollers.

Layout

Subclasses of EOComponentController have complete control over how they lay out their subcontroller components. EOComponentController's implementation can lay out subcontrollers in a row or a column (the default). To change the layout direction, use the method setUsesHorizontalLayout.

In addition to horizontal/vertical layout behavior, a component can align its label components or not. For example, consider a controller that uses vertical layout and contains several widget controllers like EOTextFieldControllers. If the controller aligns components, it attempts to left align the widgets by giving all label components the same width. The width of the labels is known as the alignment width.

To specify that a controller should align components (like labels), use the method setAlignsComponents.

Resizing

EOComponentController implements complex resizing behavior. For example, if a controller's component changes in a way that might affect its minimum size, the controller's supercontroller is notified and the supercontroller ensures that its subcontroller area is at least as big as the minimum size required to show all its subcontrollers.

Using the default behavior, the user interface doesn't automatically shrink. EOComponentController only resizes up to meet the minimum requirements. As much as possible it resizes components to fill the available space. A component controller can specify both horizontal and vertical resizing behavior for its component to accommodate this scheme.

Inner Class Summary

static interface	EOComponentController.ActionCollector The EOComponentController.ActionCollector interface identifies controllers that display actions of subcontrollers collectively (for example in tool bars).
static interface	EOComponentController.Activation The EOComponentController.Activation interface identifies controllers that which have components can be explicitly activated (for example window controllers).
static interface	EOComponentController.EndEditing The EOComponentController.EndEditing interface identifies controllers that edit data objects and might need to flush uncommitted user changes.
static interface	EOComponentController.Modal The EOComponentController.Modal interface identifies controllers that can run modal user interfaces (modal dialogs).
static interface	EOComponentController.ResetUserInterface The EOComponentController.ResetUserInterface interface identifies controllers that have components that can reset their interface to an original state (for example switch controllers).

Inner classes inherited from class com.webobjects.eoapplication.EOController

EOController.Enumeration

Inner classes inherited from class com.webobjects.foundation.NSKeyValueCoding

NSKeyValueCoding.DefaultImplementation, NSKeyValueCoding.ErrorHandling, NSKeyValueCoding.Null, NSKeyValueCoding.UnknownKeyException, NSKeyValueCoding.Utility, NSKeyValueCoding.ValueAccessor

Inner classes inherited from class com.webobjects.foundation.NSKeyValueCodingAdditions

NSKeyValueCodingAdditions.DefaultImplementation, NSKeyValueCodingAdditions.Utility

Field Summary

static int	Bottom The constant describing a bottom position.
static int	BottomLeft The constant describing a bottom-left position.
static int	BottomRight The constant describing a bottom-right position.
static int	Center The constant describing a center position.
static int	Left The constant describing a left position.
static int	Right The constant describing a right position.
static int	Top The constant describing a top position.
static int	TopLeft The constant describing a top-left position.
static int	TopRight The constant describing a top-right position.

Fields inherited from class com.webobjects.eoapplication.EOController

ControllerAndSubcontrollersEnumeration, ControllerAndSupercontrollersEnumeration, SubcontrollersEnumeration, SupercontrollersEnumeration

Fields inherited from interface com.webobjects.foundation.NSKeyValueCoding

NullValue

Fields inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions

KeyPathSeparator

Constructor Summary

EOComponentController()
Creates a new component controller with default parameters.

EOComponentController(EOXMLUnarchiver unarchiver)
Creates a new component controller with parameters retrieved from the EOXMLUnarchiver.

Method Summary

void	activateFirstFocusComponent() Puts the keyboard focus on the component returned by firstFocusComponent.
protected void	addComponentOfSubcontroller(EOComponentController controller) Adds the integration component for the receiver's subcontroller, controller, to the user interface for the receiver.
boolean	alignsComponents() Returns whether the receiver attempts to align all text labels in its component (and its integrated subcontroller components).
boolean	canBeTransient() Returns whether the controller can be transient.
boolean	canResizeHorizontally() Returns whether the receiver's component can resize horizontally.
boolean	canResizeVertically() Returns whether the receiver's component can resize vertically.
JComponent	component() Returns the receiver's component, creating and preparing it first if it doesn't already exist.
protected void	componentDidBecomeInvisible() Invoked when the receiver's component becomes invisible, giving the receiver a chance to react.
protected void	componentDidBecomeVisible() Invoked when the receiver's component becomes visible, giving the receiver a chance to react.
Dimension	defaultComponentSize() Returns the receiver's default component size.
void	dispose() Prepares the receiver so it is disposed when Java performs garbage collection.
void	ensureMinimumComponentSizeWithoutSubcontrollers(int width, int height) Ensures that the size of the receiver's component, not including the subcontroller area, is at least as large as the area specified by width and height.
void	ensureMinimumSubcontrollerAreaSize(int width, int height) Ensures that the size of the receiver's subcontroller area is at least as large as the area specified by width and height.
JComponent	firstFocusComponent() Returns the JComponent that should get the keyboard focus first.
protected void	generateComponent() Invoked when it's necessary to create the receiver's component, including setting up the subcontroller area.
void	handleTakeValueForUnboundKey(Object value, String key) Handles a special case for components assigned through key-value coding.
boolean	hideInSupercontroller() Invokes hideSubcontroller on the supercontroller to deactivate the receiver's user interface.
protected boolean	hideSubcontroller(EOComponentController controller) This method is used to attempt to hide a subcontroller's user interface inside the component of the receiver.
Icon	icon() Returns the receiver's icon.
Insets	insets() Returns the inset area around this controller's component.
JComponent	integrationComponent() Returns the component used as the integration component in the receiver's supercontroller to represent the receiver.
protected void	integrationComponentDidBecomeInvisible() Invoked by the receiver's supercontroller when the receiver's integration component becomes invisible, giving the receiver a chance to react.
protected void	integrationComponentDidBecomeVisible() Invoked by the receiver's supercontroller when the receiver's integration component becomes visible, giving the receiver a chance to react.
protected boolean	isComponentPrepared() Returns whether the receiver's component is prepared.
boolean	isRootComponentController() Returns whether the receiver is a root component controller.
boolean	isVisible() Returns whether the receiver's component is visible or not.
String	label() Returns the receiver's label.
JComponent	lastFocusComponent() Returns the JComponent that will get the keyboard focus last during focus traversal.
boolean	makeInvisible() Makes the receiver's user interface invisible.
boolean	makeVisible() Makes the receiver's user interface visible.
Dimension	minimumComponentSize() Returns the current minimum size required to display the receiver's component, including the size required for its subcontroller area.
Dimension	minimumComponentSizeWithoutSubcontrollers() Returns the current minimum size required to display the receiver's component, excluding the subcontroller area.
Dimension	minimumIntegrationComponentSize() Returns the minimum size required to display the receiver's integration component.
Dimension	minimumSubcontrollerAreaSize() Returns the minimum size of the subcontroller area to display the receiver's subcontrollers.
boolean	prefersIconOnly() Returns whether the receiver prefers to represent itself with only an icon or with an icon and a label.
protected void	prepareComponent() Prepares the receiver's component for display.
protected void	removeComponentOfSubcontroller(EOComponentController controller) Removes the user interface for the receiver's subcontroller, controller, from the receiver's user interface and informs controller that its integration component became invisible.
protected boolean	removeTransientSubcontroller(EOController controller) See the method description for removeTransientSubcontroller in the EOController class specification.
void	setAlignsComponents(boolean flag) Sets whether the receiver attempts to align all text labels in its component (and its integrated subcontroller components).
void	setCanResizeHorizontally(boolean flag) Sets whether the receiver's component can resize horizontally.
void	setCanResizeVertically(boolean flag) Sets whether the receiver's component can resize vertically.
void	setComponent(Component component) Sets the receiver's component.
void	setDefaultComponentSize(Dimension size) Sets the receiver's default component size.
void	setFirstFocusComponent(JComponent component) Sets the JComponent that should get the keyboard focus during activateFirstFocusComponent.
void	setIcon(Icon icon) Sets the receiver's icon.
void	setInsets(Insets insets) Sets the inset area around this controller's component.
void	setLabel(String string) Sets the receiver's label.
void	setLastFocusComponent(JComponent component) Sets the JComponent that will get the keyboard focus last during focus traversal.
void	setPrefersIconOnly(boolean flag) Sets whether the receiver prefers to represent itself with only an icon or with an icon and a label.
void	setSubcontrollerArea(JComponent component) Sets the receiver's subcontroller area, the component that holds the subcontroller integration comonents.
void	setToolTip(String toolTip) Sets the tool tip text used for the controller's component.
void	setUsesHorizontalLayout(boolean flag) Sets whether the receiver uses horizontal or vertical layout.
void	setVisible(boolean flag) Sets the visibility of the receiver according to flag.
boolean	showInSupercontroller() Invokes showSubcontroller on the supercontroller to activate the receiver's user interface.
protected boolean	showSubcontroller(EOComponentController controller) This method is used to ensure that a subcontroller's user interface is shown inside the component of the receiver (which does not necessarily mean that it's visible on the screen).
JComponent	subcontrollerArea() Returns the receiver's subcontroller area.
void	subcontrollerMinimumSizeDidChange(EOComponentController controller, JComponent component, Dimension updateMinimumSize) Updates the receiver's user interface to accommodate a change to a subcontroller's minimum size.
protected void	subcontrollerWasAdded(EOController controller) Invoked from addSubcontroller when a subcontroller is added to a controller.
protected void	subcontrollerWasRemoved(EOController controller) Invoked from removeSubcontroller when a subcontroller is removed from a controller.
String	toolTip() Returns the tool tip text used for the controller's component.
protected JComponent	toolTipComponent() Returns the component that will be used to display tool tip text.
String	toString() Returns the receiver as a string that states the receiver's class name and type name, whether the receiver is connected, the number of subcontrollers, whether or not the receiver has been prepared, whether or not the receiver is visible, information about widget sizing and alignment behavior, and so on.
boolean	usesHorizontalLayout() Returns whether the receiver uses horizontal or vertical layout.

Methods inherited from class com.webobjects.eoapplication.EOController

actionNames, actions, actionWithName, additionalActions, additionalKeyValuePairs, addSubcontroller, breakConnection, breakConnectionToSubcontrollers, canAccessFieldsDirectly, canPerformActionNamed, connectionWasBroken, connectionWasEstablished, controllerEnumeration, controllersInEnumeration, controllersWithKeyValuePair, controllersWithKeyValuePairs, controllerWithKeyValuePair, controllerWithKeyValuePairs, defaultActions, disableActionNamed, disposableRegistry, disposeIfTransient, enableActionNamed, enabledActions, establishConnection, establishConnectionToSupercontrollers, handleQueryWithUnboundKey, hierarchicalControllerForKey, hierarchicalValueForKey, invokeMethod, isActionNamedEnabled, isAncestorOfController, isConnected, isSupercontrollerOfController, isTransientExplicitlyForbidden, prepareForNewTask, removeFromSupercontroller, removeSubcontroller, resetActions, setAdditionalActions, setAdditionalKeyValuePair, setAdditionalKeyValuePairs, setConnected, setSupercontroller, setTransientExplicitlyForbidden, setTypeName, subcontrollers, supercontroller, supercontroller, takeValueForKey, takeValueForKeyPath, typeName, unableToSetNullForKey, valueForKey, valueForKeyPath

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

Bottom

public static final int Bottom

The constant describing a bottom position.

BottomLeft

public static final int BottomLeft

The constant describing a bottom-left position.

BottomRight

public static final int BottomRight

The constant describing a bottom-right position.

Center

public static final int Center

The constant describing a center position.

Left

public static final int Left

The constant describing a left position.

Right

public static final int Right

The constant describing a right position.

Top

public static final int Top

The constant describing a top position.

TopLeft

public static final int TopLeft

The constant describing a top-left position.

TopRight

public static final int TopRight

The constant describing a top-right position.

Constructor Detail

EOComponentController

public EOComponentController()

Creates a new component controller with default parameters.

EOComponentController

public EOComponentController(EOXMLUnarchiver unarchiver)

Creates a new component controller with parameters retrieved from the EOXMLUnarchiver.

Parameters:

unarchiver - the EOXMLUnarchiver providing XML arguments

Method Detail

activateFirstFocusComponent

public void activateFirstFocusComponent()

Puts the keyboard focus on the component returned by firstFocusComponent.

See Also:

firstFocusComponent()

addComponentOfSubcontroller

protected void addComponentOfSubcontroller(EOComponentController controller)

Adds the integration component for the receiver's subcontroller, controller, to the user interface for the receiver.

Parameters:

controller - the subcontroller to be added

alignsComponents

public boolean alignsComponents()

Returns whether the receiver attempts to align all text labels in its component (and its integrated subcontroller components).

Returns:

true if the controller's attempts to align text labels; false otherwise

canBeTransient

public boolean canBeTransient()

Returns whether the controller can be transient. By default, a component controller is transient only if it's an instance of EOComponentController, not an instance of a subclass.

Overrides:

canBeTransient in class EOController

Returns:

true if the receiver can be transient; false otherwise

canResizeHorizontally

public boolean canResizeHorizontally()

Returns whether the receiver's component can resize horizontally.

Returns:

true if the controller's component can resize horizontally; false otherwise

canResizeVertically

public boolean canResizeVertically()

Returns whether the receiver's component can resize vertically.

Returns:

true if the controller's component can resize vertically; false otherwise

component

public JComponent component()

Returns the receiver's component, creating and preparing it first if it doesn't already exist.

Returns:

the controller's component

componentDidBecomeInvisible

protected void componentDidBecomeInvisible()

Invoked when the receiver's component becomes invisible, giving the receiver a chance to react. EOComponentController's implementation invokes breakConnection to break the receiver's connection to the controller hierarchy.

componentDidBecomeVisible

protected void componentDidBecomeVisible()

Invoked when the receiver's component becomes visible, giving the receiver a chance to react. EOComponentController's implementation invokes establishConnection to ensure the receiver is connected to the controller hierarchy.

defaultComponentSize

public Dimension defaultComponentSize()

Returns the receiver's default component size. This is also the size the component is set to when it's created.

Returns:

the default component size

dispose

public void dispose()

Prepares the receiver so it is disposed when Java performs garbage collection.

Overrides:

dispose in class EOController

ensureMinimumComponentSizeWithoutSubcontrollers

public void ensureMinimumComponentSizeWithoutSubcontrollers(int width,
                                                            int height)

Ensures that the size of the receiver's component, not including the subcontroller area, is at least as large as the area specified by width and height. If it isn't, the receiver resizes its component to width and height. This method is invoked by the receiver itself when its component is changed in a way that might affect the component's minimum size. For example, suppose a label is changed and requires a larger space.

Parameters:

width - the minimum width of the receiver's component

height - the minimum height of the receiver's component

ensureMinimumSubcontrollerAreaSize

public void ensureMinimumSubcontrollerAreaSize(int width,
                                               int height)

Ensures that the size of the receiver's subcontroller area is at least as large as the area specified by width and height. If it isn't, the receiver resizes its subcontroller area to width and height. This method is invoked when a subcontroller's component changes in a way that might affect its minimum size.

Parameters:

width - the minimum width of the receiver's subcontroller area

height - the minimum height of the receiver's subcontroller area

firstFocusComponent

public JComponent firstFocusComponent()

Returns the JComponent that should get the keyboard focus first.

Returns:

the JComponent that should get the keyboard focus first

See Also:

lastFocusComponent(), #setFirstFocusComponent()

generateComponent

protected void generateComponent()

Invoked when it's necessary to create the receiver's component, including setting up the subcontroller area. Subclass implementations of this method usually invoke setComponent and if necessary setSubcontrollerArea. EOComponentController's default implementation creates an empty EOView to hold subcontroller components.

The layout mechanisms used to integrate the components of controllers expect that the component is generated with the minimum size possible.

handleTakeValueForUnboundKey

public void handleTakeValueForUnboundKey(Object value,
                                         String key)

Handles a special case for components assigned through key-value coding.

Overrides:

handleTakeValueForUnboundKey in class EOController

Parameters:

value - the key-value coding value

key - the key-value coding key

hideInSupercontroller

public boolean hideInSupercontroller()

Invokes hideSubcontroller on the supercontroller to deactivate the receiver's user interface. Returns whether the controller was successfully hidden or not. If the receiver is a root component controller, this method also makes the receiver invisible. For example, a window controller which is a root component controller simply closes.

Returns:

true if the controller was successfully hidden by the supercontroller; false otherwise

hideSubcontroller

protected boolean hideSubcontroller(EOComponentController controller)

This method is used to attempt to hide a subcontroller's user interface inside the component of the receiver. Returns whether the subcontroller was successfully hidden or not. EOComponentController's implementation simply returns false. This is because most controllers can't hide their subcontrollers.

For example switch controllers override this method in a meaningful way: They can simply activate another subcontroller. Do not invoke this method directly, use hideInSupercontroller instead.

Parameters:

controller - the controller to be hidden

Returns:

true if the controller succeeded in hiding the subcontroller's component; false otherwise

icon

public Icon icon()

Returns the receiver's icon. The icon is usually used by supercontrollers which integrate the controller to create a representation of the controller.

Returns:

the icon

insets

public Insets insets()

Returns the inset area around this controller's component.

Returns:

Insets the Insets value for the controller's component

integrationComponent

public JComponent integrationComponent()

Returns the component used as the integration component in the receiver's supercontroller to represent the receiver. EOComponentController returns its component by default. Subclasses can override this method to return a placeholder component, for example an activation button.

Returns:

the integration component

integrationComponentDidBecomeInvisible

protected void integrationComponentDidBecomeInvisible()

Invoked by the receiver's supercontroller when the receiver's integration component becomes invisible, giving the receiver a chance to react. EOComponentController's implementation sets the receiver's visibility to be false, because by default the integration component is identical to the component.

integrationComponentDidBecomeVisible

protected void integrationComponentDidBecomeVisible()

Invoked by the receiver's supercontroller when the receiver's integration component becomes visible, giving the receiver a chance to react. EOComponentController's implementation sets the receiver's visibility to be true, because by default the integration component is identical to the component.

isComponentPrepared

protected boolean isComponentPrepared()

Returns whether the receiver's component is prepared.

Returns:

true if the component is already prepared; false otherwise

isRootComponentController

public boolean isRootComponentController()

Returns whether the receiver is a root component controller. A component controller is a root component controller if its supercontroller is not an instance of EOComponentController.

Returns:

true if the receiver is a root component controller; false otherwise

isVisible

public boolean isVisible()

Returns whether the receiver's component is visible or not. A component controller is visible if its component is on the screen. Note, showing a subcontroller in its supercontroller doesn't necessarily mean that it is visible. For example, you can show a component in a tab view, but the component won't be visible unless the tab view is visible.

Returns:

true if the controller's component is visible; false otherwise

label

public String label()

Returns the receiver's label. If the label is not explicitly set, EOComponentController's implementation attempts to derive a label from its subcontrollers. The label is usually used by supercontrollers which integrate the controller to create a representation of the controller.

Returns:

the label

lastFocusComponent

public JComponent lastFocusComponent()

Returns the JComponent that will get the keyboard focus last during focus traversal.

Returns:

the JComponent that should get the keyboard focus last

See Also:

firstFocusComponent(), #setLastFocusComponent()

makeInvisible

public boolean makeInvisible()

Makes the receiver's user interface invisible. If the receiver's supercontroller is a component controller, makes the receiver invisible by making the receiver's supercontroller invisible. Otherwise, invokes hideInSupercontroller.

Returns:

true if the controller succeeded in becoming invisible; false otherwise

makeVisible

public boolean makeVisible()

Makes the receiver's user interface visible. Establishes the receiver's connection to its supercontrollers and invokes showInSupercontroller. If the receiver's supercontroller is a component controller, it also attempts to make the supercontroller visible.

Returns:

true if the controller succeeded in becoming visible; false otherwise

minimumComponentSize

public Dimension minimumComponentSize()

Returns the current minimum size required to display the receiver's component, including the size required for its subcontroller area.

Returns:

the minimum size of the controller's component

minimumComponentSizeWithoutSubcontrollers

public Dimension minimumComponentSizeWithoutSubcontrollers()

Returns the current minimum size required to display the receiver's component, excluding the subcontroller area.

Returns:

the minimum size of the controller's component, excluding the subcontroller area

minimumIntegrationComponentSize

public Dimension minimumIntegrationComponentSize()

Returns the minimum size required to display the receiver's integration component. EOComponentController returns its minimum component size by default. Subclasses can override this method to return the minimum size of a placeholder component, for example an activation button.

Returns:

the minimum integration component size

minimumSubcontrollerAreaSize

public Dimension minimumSubcontrollerAreaSize()

Returns the minimum size of the subcontroller area to display the receiver's subcontrollers.

Returns:

the minimum size of the subcontroller area

prefersIconOnly

public boolean prefersIconOnly()

Returns whether the receiver prefers to represent itself with only an icon or with an icon and a label.

Returns:

true if the controller prefers to be represented with icon only; false otherwise

prepareComponent

protected void prepareComponent()

Prepares the receiver's component for display. If not already created, creates the component and integrates the subcontroller components.

removeComponentOfSubcontroller

protected void removeComponentOfSubcontroller(EOComponentController controller)

Removes the user interface for the receiver's subcontroller, controller, from the receiver's user interface and informs controller that its integration component became invisible.

Parameters:

controller - the subcontroller to be removed

removeTransientSubcontroller

protected boolean removeTransientSubcontroller(EOController controller)

See the method description for removeTransientSubcontroller in the EOController class specification. EOComponentController's implementation performs additional user interface cleanup for controllers that become transient.

Overrides:

removeTransientSubcontroller in class EOController

Parameters:

controller - the subcontroller becoming transient

Returns:

true if the subcontroller can be allowed to become transient; false otherwise

setAlignsComponents

public void setAlignsComponents(boolean flag)

Sets whether the receiver attempts to align all text labels in its component (and its integrated subcontroller components). Throws an IllegalStateException if the receiver's component is already prepared. In other words, you can only set the alignment behavior before the component is generated.

Parameters:

flag - true if the controller attempts to align text labels; false otherwise

setCanResizeHorizontally

public void setCanResizeHorizontally(boolean flag)

Sets whether the receiver's component can resize horizontally. Throws an IllegalStateException if the receiver's component is already prepared. In other words, you can only set the horizontal resizing behavior before the component is generated.

Parameters:

flag - true if the controller can resize horizontally; false otherwise

setCanResizeVertically

public void setCanResizeVertically(boolean flag)

Sets whether the receiver's component can resize vertically. Throws an IllegalStateException if the receiver's component is already prepared. In other words, you can only set the vertical resizing behavior before the component is generated.

Parameters:

flag - true if the controller can resize vertically; false otherwise

setComponent

public void setComponent(Component component)

Sets the receiver's component. The component has to be a JComponent or a Window (in which case the content view (excpected to be a JComponent) of the window is used as component), otherwise this method throws an IllegalArgumentException. The component is usually a Window if it is loaded from an interface file created in Interface Builder (in which case the file's owner's component outlet usually points to the window, not its content view).

Parameters:

component - the component of the controller

setDefaultComponentSize

public void setDefaultComponentSize(Dimension size)

Sets the receiver's default component size.

Parameters:

size - the default component size

setFirstFocusComponent

public void setFirstFocusComponent(JComponent component)

Sets the JComponent that should get the keyboard focus during activateFirstFocusComponent.

Parameters:

component - the JComponent that should get the keyboard focus first

See Also:

lastFocusComponent(), firstFocusComponent()

setIcon

public void setIcon(Icon icon)

Sets the receiver's icon.

Parameters:

icon - the icon

setInsets

public void setInsets(Insets insets)

Sets the inset area around this controller's component. Throws an IllegalStateException if the component is already prepared.

Parameters:

insets - the Insets value to set for the controller's component

setLabel

public void setLabel(String string)

Sets the receiver's label.

Parameters:

string - the label

setLastFocusComponent

public void setLastFocusComponent(JComponent component)

Sets the JComponent that will get the keyboard focus last during focus traversal.

Parameters:

component - the JComponent that should get the keyboard focus last

See Also:

firstFocusComponent(), lastFocusComponent()

setPrefersIconOnly

public void setPrefersIconOnly(boolean flag)

Sets whether the receiver prefers to represent itself with only an icon or with an icon and a label.

Parameters:

flag - true if the controller prefers to be represented with icon only; false otherwise

setSubcontrollerArea

public void setSubcontrollerArea(JComponent component)

Sets the receiver's subcontroller area, the component that holds the subcontroller integration comonents.

Parameters:

component - the subcontroller area

setToolTip

public void setToolTip(String toolTip)

Sets the tool tip text used for the controller's component.

Parameters:

toolTip - the tool tip text

setUsesHorizontalLayout

public void setUsesHorizontalLayout(boolean flag)

Sets whether the receiver uses horizontal or vertical layout. Throws an IllegalStateException if the receiver's component is already prepared. In other words, you can only set the layout direction before the component is generated.

Parameters:

flag - true if the controller uses horizontal layout; false otherwise

setVisible

public void setVisible(boolean flag)

Sets the visibility of the receiver according to flag. Invokes componentDidBecomeVisible or componentDidBecomeInvisible to notify the receiver that its visibility changed and to give the receiver the opportunity to react appropriately. Also notifies the receiver's ancestors that a subcontroller's visibility has changed, giving the supercontrollers the opportunity to respond.

If flag is true, this method disposes of transient receivers after making them visible.

Parameters:

flag - true if the controller's component is visible; false otherwise

showInSupercontroller

public boolean showInSupercontroller()

Invokes showSubcontroller on the supercontroller to activate the receiver's user interface. Returns whether the controller was successfully shown or not. If the receiver is a root component controller, this method also makes the receiver visible.

Note that invoking this method doesn't necessarily change the visibility of the receiver. For example, a switch controller might switch the component it displays, but if the switch controller isn't visible, the subcontroller doesn't become visible when it's shown.

Returns:

true if the controller was successfully shown by the supercontroller; false otherwise

showSubcontroller

protected boolean showSubcontroller(EOComponentController controller)

This method is used to ensure that a subcontroller's user interface is shown inside the component of the receiver (which does not necessarily mean that it's visible on the screen). Returns whether the subcontroller was successfully shown or not. EOComponentController's implementation simply returns true: Since the integration components for subcontrollers are added to a controller's component automatically, the subcontrollers are already shown.

For example, switch controllers override this method in a meaningful way: To show one subcontroller, the tab switch controller hides another. Do not invoke this method directly, use showInSupercontroller instead.

Parameters:

controller - the controller to be shown

Returns:

true if the controller succeeded in showing the subcontroller's component; false otherwise

subcontrollerArea

public JComponent subcontrollerArea()

Returns the receiver's subcontroller area. EOComponentController returns its component by default.

Returns:

the subcontroller area

subcontrollerMinimumSizeDidChange

public void subcontrollerMinimumSizeDidChange(EOComponentController controller,
                                              JComponent component,
                                              Dimension updateMinimumSize)

Updates the receiver's user interface to accommodate a change to a subcontroller's minimum size. This method is invoked by subcontrollers when they change in a way that might affect their component's minimum size. A subcontroller sends this method with itself, its integration component, and its new minimum size as the arguments. The expectation is that the supercontroller will make space for the subcontroller if it needs to.

Parameters:

controller - the subcontroller which changed

component - the integration component of the subcontroller

updateMinimumSize - the new minimum size of the integration component

subcontrollerWasAdded

protected void subcontrollerWasAdded(EOController controller)

Invoked from addSubcontroller when a subcontroller is added to a controller. If the receiver's component has already been created, integrates the subcontroller's integration component (if any) to its component right away, otherwise waits until it becomes visible.

Overrides:

subcontrollerWasAdded in class EOController

Parameters:

controller - the new subcontroller just added

subcontrollerWasRemoved

protected void subcontrollerWasRemoved(EOController controller)

Invoked from removeSubcontroller when a subcontroller is removed from a controller. If the receiver's component has already been created, removes the subcontroller's integration component (if any) from its component.

Overrides:

subcontrollerWasRemoved in class EOController

Parameters:

controller - the subcontroller just removed

toString

public String toString()

Returns the receiver as a string that states the receiver's class name and type name, whether the receiver is connected, the number of subcontrollers, whether or not the receiver has been prepared, whether or not the receiver is visible, information about widget sizing and alignment behavior, and so on.

Overrides:

toString in class EOController

Returns:

the String representation of the receiver

toolTip

public String toolTip()

Returns the tool tip text used for the controller's component.

Returns:

the tool tip text

toolTipComponent

protected JComponent toolTipComponent()

Returns the component that will be used to display tool tip text.

Returns:

JComponent the tool tip component for this controller

usesHorizontalLayout

public boolean usesHorizontalLayout()

Returns whether the receiver uses horizontal or vertical layout.

Returns:

true if the controller uses horizontal layout; false otherwise