EOComponentController (WebObjects 5.2.3 Reference Documentation)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

WebObjects 5.2.3

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

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.

Nested 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).

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

EOController.Enumeration

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

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

Nested 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.

See Also:: Constant Field Values

BottomLeft

public static final int BottomLeft

The constant describing a bottom-left position.

See Also:: Constant Field Values

BottomRight

public static final int BottomRight

The constant describing a bottom-right position.

See Also:: Constant Field Values

Center

public static final int Center

The constant describing a center position.

See Also:: Constant Field Values

Left

public static final int Left

The constant describing a left position.

See Also:: Constant Field Values

Right

public static final int Right

The constant describing a right position.

See Also:: Constant Field Values

Top

public static final int Top

The constant describing a top position.

See Also:: Constant Field Values

TopLeft

public static final int TopLeft

The constant describing a top-left position.

See Also:: Constant Field Values

TopRight

public static final int TopRight

The constant describing a top-right position.

See Also:: Constant Field Values

Constructor Detail