WebObjects 5.4.2

com.webobjects.eoapplication
Class EOComponentController

java.lang.Object
  extended by com.webobjects.eoapplication.EOController
      extended by 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/interfaces inherited from class com.webobjects.eoapplication.EOController
EOController.Enumeration
 
Nested classes/interfaces inherited from interface 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.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

Center

public static final int Center
The constant describing a center position.

See Also:
Constant Field Values

Top

public static final int Top
The constant describing a top position.

See Also:
Constant Field Values

Bottom

public static final int Bottom
The constant describing a bottom 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

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

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

dispose

public void dispose()
Prepares the receiver so it is disposed when Java performs garbage collection.

Specified by:
dispose in interface NSDisposable
Overrides:
dispose in class EOController

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

handleTakeValueForUnboundKey

public void handleTakeValueForUnboundKey(Object value,
                                         String key)
Handles a special case for components assigned through key-value coding.

Specified by:
handleTakeValueForUnboundKey in interface NSKeyValueCoding.ErrorHandling
Overrides:
handleTakeValueForUnboundKey in class EOController
Parameters:
value - the key-value coding value
key - the key-value coding key
See Also:
NSKeyValueCoding.takeValueForKey, NSKeyValueCoding.UnknownKeyException, NSKeyValueCoding.DefaultImplementation

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

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

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

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
See Also:
EOController.addSubcontroller(EOController)

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
See Also:
EOController.removeSubcontroller(EOController)

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
See Also:
EOController.disposeIfTransient()

setLabel

public void setLabel(String string)
Sets the receiver's label.

Parameters:
string - the label

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

setIcon

public void setIcon(Icon icon)
Sets the receiver's icon.

Parameters:
icon - the icon

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

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

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

setToolTip

public void setToolTip(String toolTip)
Sets the tool tip text used for the controller's component.

Parameters:
toolTip - the tool tip text

toolTip

public String toolTip()
Returns the tool tip text used for the controller's component.

Returns:
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

usesHorizontalLayout

public boolean usesHorizontalLayout()
Returns whether the receiver uses horizontal or vertical layout.

Returns:
true if the controller uses horizontal layout; 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

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

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

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

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

insets

public Insets insets()
Returns the inset area around this controller's component.

Returns:
Insets the Insets value for the controller's component

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

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

setDefaultComponentSize

public void setDefaultComponentSize(Dimension size)
Sets the receiver's default component size.

Parameters:
size - the default component size

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

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.


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

prepareComponent

protected void prepareComponent()
Prepares the receiver's component for display. If not already created, creates the component and integrates the subcontroller components.


isComponentPrepared

protected boolean isComponentPrepared()
Returns whether the receiver's component is prepared.

Returns:
true if the component is already prepared; false otherwise

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

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

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

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

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

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

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

subcontrollerArea

public JComponent subcontrollerArea()
Returns the receiver's subcontroller area. EOComponentController returns its component by default.

Returns:
the subcontroller area

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

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

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:
EOComponentController.lastFocusComponent(), EOComponentController.firstFocusComponent()

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:
EOComponentController.lastFocusComponent(), EOComponentController.setFirstFocusComponent(JComponent)

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:
EOComponentController.firstFocusComponent(), EOComponentController.lastFocusComponent()

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:
EOComponentController.firstFocusComponent(), EOComponentController.setLastFocusComponent(JComponent component)

activateFirstFocusComponent

public void activateFirstFocusComponent()
Puts the keyboard focus on the component returned by firstFocusComponent.

See Also:
EOComponentController.firstFocusComponent()

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.


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.


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.


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.


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

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

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

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

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

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

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

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

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

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

Last updated June 2008

Copyright © 2000-2008 Apple Inc.