EOComponentController

Inherits from:

EOController : Object

Implements:

NSInlineObservable

(Inherited from EOController)

NSDisposable (Inherited from EOController)

com.apple.client.eocontrol.EOKeyValueCodingAdditions (Inherited

from EOController)

EOAction.Enabling (Inherited from EOController)

com.apple.client.eocontrol.EOKeyValueCoding (Inherited from EOKeyValueCodingAdditions)

com.apple.client.foundation.NSKeyValueCoding (Inherited from EOKeyValueCoding)

Package:

com.apple.client.eoapplication

Class Description

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 supercontrollers user interface.

By default, a controller's integration component is simply the controller's component. In other words, a supercontroller adds its subcontrollers' 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 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 subcontrollers' user interfaces. 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 method component. 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.

To see if a controller's component has 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.

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 switch controller 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. 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 derives one from its subcontrollers.

Layout

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

In addition to horizontal/vertical layout behavior, a component can align its components or not. For example, consider a controller that uses vertical layout and contains several EOTextFieldControllers. If the controller aligns components, it left aligns the text fields. The default alignment behavior aligns components by making their corresponding labels identically sized. The width of the labels is known as the alignment width.

To specify a component's alignment behavior, use the method setAlignsComponents. To set the alignment width, use setAlignmentWidth.

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.

Rule System and XML Description

The following tables identify the controllerType, XML tag, and XML attributes used by the rule system and EOXMLUnarchiver to generate a controller hierarchy. For more information, see the section "Rule System and XML Description" in the package introduction.

Interfaces Implemented

NSInlineObservable (Inherited from EOController)

NSDisposable (Inherited from EOController)

dispose

EOKeyValueCodingAdditions (Inherited from EOController)

EOAction.Enabling (Inherited from EOController)

EOKeyValueCoding (Inherited from EOKeyValueCodingAdditions)

handleQueryWithUnboundKey

handleTakeValueForUnboundKey

storedValueForKey

takeStoredValueForKey

unableToSetNullForKey

NSKeyValueCoding (Inherited from EOKeyValueCoding)

Method Types

Constructors

EOComponentController

Managing the component

generateComponent

prepareComponent

setComponent

component

isComponentPrepared

Managing the integration component

integration ComponentDidBecomeInvisible

integrationComponentDidBecomeVisible

integrationComponent

Managing the subcontroller area

setSubcontrollerArea

subcontrollerArea

addComponentOfSubcontroller

removeComponentOfSubcontroller

Managing component visibility

showInSupercontroller

makeVisible

componentDidBecomeVisible

showSubcontroller

hideInSupercontroller

makeInvisible

componentDidBecomeInvisible

hideSubcontroller

setVisible

isVisible

Setting component appearance

setPrefersIconOnly

prefersIconOnly

setIcon

icon

setLabel

label

Layout behavior

setUsesHorizontalLayout

usesHorizontalLayout

setAlignsComponents

alignsComponents

setAlignmentWidth

alignmentWidth

Resizing behavior

setCanResizeHorizontally

canResizeHorizontally

setCanResizeVertically

canResizeVertically

Configuring user interface sizes

setDefaultComponentSize

defaultComponentSize

ensureMinimumComponentSizeWithoutSubcontrollers

ensureMinimumSubcontrollerAreaSize

subcontrollerMinimumSizeDidChange

minimumComponentSize

minimumComponentSizeWithoutSubcontrollers

minimumIntegrationComponentSize

minimumSubcontrollerAreaSize

Determining the root component controller

isRootComponentController

Methods inherited from EOController

canBeTransient

removeTransientSubcontroller

subcontrollerWasAdded

subcontrollerWasRemoved

Methods inherited from Object

toString

Constructors

EOComponentController

public EOController()

public EOComponentController(EOXMLUnarchiver unarchiver)

Creates a new component controller. For information on how these constructors are used and on what they do, see the method description for the EOController constructors in the EOController class specification.

Instance Methods

addComponentOfSubcontroller

protected void addComponentOfSubcontroller(EOComponentController controller)

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

alignmentWidth

public int alignmentWidth()

Returns the receiver's alignment width.

See Also: "Layout"

alignsComponents

public boolean alignsComponents()

Returns true if the receiver aligns its components, false otherwise.

See Also: "Layout"

canBeTransient

public boolean canBeTransient()

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

See Also: canBeTransient (EOController)

canResizeHorizontally

public boolean canResizeHorizontally()

Returns true if the receiver can resize its component horizontally, or false otherwise.

See Also: "Resizing"

canResizeVertically

public boolean canResizeVertically()

Returns true if the receiver can resize its component vertically, or false otherwise.

See Also: "Resizing"

component

public javax.swing.JComponent component()

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

See Also: "Managing the Component" , prepareComponent, generateComponent

componentDidBecomeInvisible

protected void componentDidBecomeInvisible()

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

componentDidBecomeVisible

protected void componentDidBecomeVisible()

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

defaultComponentSize

public java.awt.Dimension defaultComponentSize()

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

See Also: "Resizing"

dispose

public void dispose()

Conformance to NSDisposable. See the method description of dispose in the interface specification for NSDisposable.

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.

See Also: "Resizing"

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.

See Also: "Resizing"

generateComponent

protected void generateComponent()

Creates the receiver's component, including setting up the subcontroller area. Implementations of these methods usually invoke setComponent and if necessary setSubcontrollerArea. EOComponentController creates an EOView.

See Also: "Managing the Component"

handleTakeValueForUnboundKey

public void handleTakeValueForUnboundKey( Object value, String key)

Conformance to EOKeyValueCoding. See the method description of handleTakeValueForUnboundKey in the interface specification for EOKeyValueCoding.

hideInSupercontroller

public boolean hideInSupercontroller()

Invokes hideSubcontroller on the receiver's supercontroller to hide the receiver's component if the component (or integration component) appears in the supercontroller's user interface. Returns true on success, false otherwise. If the receiver doesn't have a supercontroller, then this method simply makes the receiver invisible. For example, a window controller which is the root component controller simply closes.

This method is invoked automatically (for example, from makeInvisible). You should never need to invoke it yourself.

See Also: "Visibility"

hideSubcontroller

protected boolean hideSubcontroller(EOComponentController controller)

Hides controller's user interface in the interface of the receiver. Returns true if the subcontroller was successfully hidden, false otherwise. EOComponentController's implementation simply returns false. This is because most controllers can't hide their subcontrollers. Examples of controllers that can hide their subcontrollers are tab view controllers, which hide a subcontroller by making another subcontroller visible. Don't invoke this method directly; invoke hideInSupercontroller instead.

See Also: "Visibility"

icon

public javax.swing.Icon icon()

Returns the receiver's icon, or null if it has none.

See Also: "Component Appearance"

integrationComponent

public javax.swing.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.

See Also: "Class Description"

integration ComponentDidBecomeInvisible

protected void integrationComponentDidBecomeInvisible()

Invoked by the receiver's supercontroller when the receiver's integration component becomes invisible, giving the receiver a chance to respond. 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 respond. 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 true if the receiver is prepared, false otherwise.

See Also: "Managing the Component"

isRootComponentController

protected boolean isRootComponentController()

Returns true if the receiver is a root component controller, false otherwise. A component controller is the root component controller if its supercontroller is not an instance of EOComponentController.

isVisible

public boolean isVisible()

Returns true if the receiver is visible, false otherwise. 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.

See Also: "Visibility"

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 it's subcontrollers.

See Also: "Component Appearance"

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 method succeeds in making the receiver 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 method succeeds in making the receiver visible, false otherwise.

See Also: "Visibility"

minimumComponentSize

public java.awt.Dimension minimumComponentSize()

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

See Also: "Resizing"

minimumComponentSizeWithoutSubcontrollers

public java.awt.Dimension minimumComponentSizeWithoutSubcontrollers()

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

See Also: "Resizing"

minimumIntegrationComponentSize

public java.awt.Dimension minimumIntegrationComponentSize()

Returns the minimum size required to display the receiver's integration component.

See Also: "Resizing"

minimumSubcontrollerAreaSize

public java.awt.Dimension minimumSubcontrollerAreaSize()

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

See Also: "Resizing"

prefersIconOnly

public boolean prefersIconOnly()

Returns true if the receiver prefers to represent itself with only an icon, false otherwise.

See Also: "Component Appearance"

prepareComponent

protected void prepareComponent()

If the receiver's component is not already prepared, it generates the component.

See Also: "Managing the Component"

removeComponentOfSubcontroller

protected void removeComponentOfSubcontroller(EOComponentController controller)

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

removeTransientSubcontroller

protected boolean removeTransientSubcontroller(EOController controller)

See the method description for removeTransientSubcontroller in the EOController class specification.

setAlignmentWidth

public void setAlignmentWidth(int alignmentWidgth)

Sets the receiver's alignment width to alignmentWidth. Throws an IllegalStateException if the receiver is already prepared. In other words, you can only set the alignment width before the component is generated.

See Also: "Layout"

setAlignsComponents

public void setAlignsComponents(boolean flag)

Sets according to flag whether the receiver aligns the components in its user interface. Throws an IllegalStateException if the receiver is already prepared. In other words, you can only set the alignment behavior before the component is generated.

See Also: "Layout"

setCanResizeHorizontally

public void setCanResizeHorizontally(boolean flag)

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

See Also: "Resizing"

setCanResizeVertically

public void setCanResizeVertically(boolean flag)

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

See Also: "Resizing"

setComponent

public void setComponent(java.awt.Component component)

Sets the receiver's component to component.

See Also: "Managing the Component"

setDefaultComponentSize

public void setDefaultComponentSize(java.awt.Dimension dimension)

Sets the default size of the receiver's component to dimension.

See Also: "Resizing"

setIcon

public void setIcon(javax.swing.Icon icon)

Sets the receiver's icon to icon.

See Also: "Component Appearance"

setLabel

public void setLabel(String label)

Sets the receiver's label to label.

See Also: "Component Appearance"

setPrefersIconOnly

public void setPrefersIconOnly(boolean flag)

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

See Also: "Component Appearance"

setSubcontrollerArea

public void setSubcontrollerArea(javax.swing.JComponent component)

Sets the component that holds the user interface for the receiver's subcontrollers to component.

See Also: "Class Description"

setUsesHorizontalLayout

public void setUsesHorizontalLayout(boolean flag)

Sets according to flag whether the receiver uses horizontal layout. Throws an IllegalStateException if the receiver is already prepared. In other words, you can only set the layout direction before the component is generated.

See Also: "Layout"

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

See Also: "Visibility"

showInSupercontroller

public boolean showInSupercontroller()

Invokes showSubcontroller to add the receiver's user interface to its supercontroller's receiver. Returns true on success, false otherwise. If the supercontroller is null, this method also makes the receiver visible.

Note: 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.

This method is invoked automatically (for example, from makeVisible). You should never need to invoke it yourself.

See Also: "Visibility"

showSubcontroller

protected boolean showSubcontroller(EOComponentController controller)

Adds controller's user interface to the interface of the receiver. Returns true if the subcontroller was successfully shown, false otherwise. EOComponentController's implementation simply returns true: Since the integration components for subcontrollers are added to a controller's user interface automatically, the subcontrollers are already shown. EOTabSwitchController is an example of a subclass that overrides this method in a meaningful way. To show one subcontroller, the tab switch controller hides another.

See Also: "Visibility"

subcontrollerArea

public javax.swing.JComponent subcontrollerArea()

Returns the component that holds the user interface for the receiver's subcontrollers.

See Also: "Class Description"

subcontrollerMinimumSizeDidChange

public void subcontrollerMinimumSizeDidChange( EOComponentController controller, javax.swing.JComponent component, java.awt.Dimension dimension)

Updates the receiver's user interface to accommodate a change to the 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.

See Also: "Resizing"

subcontrollerWasAdded

protected void subcontrollerWasAdded(EOController controller)

Invokes addComponentOfSubcontroller to add the integration component (if any) for the receiver's subcontroller, controller, to the receiver's user interface. Invoked from addSubcontroller to notify the receiver that its subcontroller controller has been added to the controller hierarchy.

subcontrollerWasRemoved

protected void subcontrollerWasRemoved(EOController controller)

Invokes removeComponentOfSubcontroller to remove the integration component (if any) for the receiver's subcontroller, controller, from the receiver's user interface. Invoked from removeSubcontroller to notify the receiver that its subcontroller controller has been removed from the controller hierarchy.

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.

usesHorizontalLayout

public boolean usesHorizontalLayout()

Returns true if the receiver uses a horizontal layout, false otherwise.

See Also: "Layout"

DRAFT