- 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
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.
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.
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.
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.
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.
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.
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.
| Default Rule System Controller Type |
groupingController |
| XML Tag |
COMPONENTCONTROLLER |
| XML Attribute | Value | Description |
alignmentWidth |
integer | See "Layout" . |
alignsComponents |
"true" or "false" | See "Layout" . |
horizontallyResizable |
"true" or "false" | See "Resizing" . |
iconName |
string | The filename of the component's icon. Uses standard resource location behavior to find the icon by name. See "Component Appearance" for more information. |
iconURL |
string | The URL from which the icon is downloaded. See "Component Appearance" for more information. |
label |
string | See "Component Appearance" . |
minimumHeight |
integer | The minimum height of the controller's component, not including its subcontroller area. |
minimumWidth |
integer | The minimum width of the controller's component, not including its subcontroller area. |
prefersIconOnly |
"true" or "false" | See "Component Appearance" . |
usesHorizontalLayout |
"true" or "false" | See "Layout" . |
verticallyResizable |
"true" or "false" | See "Resizing" . |
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)
- 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
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.
protected void addComponentOfSubcontroller(EOComponentController controller)
Adds the integration component for the receiver's subcontroller, controller, to the user interface for the receiver.
public int alignmentWidth()
Returns the receiver's alignment width.
See Also: "Layout"
public boolean alignsComponents()
Returns true if
the receiver aligns its components, false otherwise.
See Also: "Layout"
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)
public boolean canResizeHorizontally()
Returns true if
the receiver can resize its component horizontally, or false otherwise.
See Also: "Resizing"
public boolean canResizeVertically()
Returns true if
the receiver can resize its component vertically, or false otherwise.
See Also: "Resizing"
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
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.
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.
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"
public void dispose()
Conformance to NSDisposable. See the method description of dispose in the interface specification for NSDisposable.
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"
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"
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"
public void handleTakeValueForUnboundKey(
Object value,
String key)
Conformance to EOKeyValueCoding. See the method description of handleTakeValueForUnboundKey in the interface specification for EOKeyValueCoding.
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"
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"
public javax.swing.Icon icon()
Returns the receiver's icon,
or null if it has none.
See Also: "Component Appearance"
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"
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.
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.
protected boolean isComponentPrepared()
Returns true if
the receiver is prepared, false otherwise.
See Also: "Managing the Component"
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.
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"
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"
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.
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"
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"
public java.awt.Dimension minimumComponentSizeWithoutSubcontrollers()
Returns the current minimum size required to display the receiver's component, excluding the subcontroller area.
See Also: "Resizing"
public java.awt.Dimension minimumIntegrationComponentSize()
Returns the minimum size required to display the receiver's integration component.
See Also: "Resizing"
public java.awt.Dimension minimumSubcontrollerAreaSize()
Returns the minimum size of the subcontroller area to display the receiver's subcontrollers.
See Also: "Resizing"
public boolean prefersIconOnly()
Returns true if
the receiver prefers to represent itself with only an icon, false otherwise.
See Also: "Component Appearance"
protected void prepareComponent()
If the receiver's component is not already prepared, it generates the component.
See Also: "Managing the Component"
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.
protected boolean removeTransientSubcontroller(EOController controller)
See the method description for removeTransientSubcontroller in the EOController class specification.
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"
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"
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"
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"
public void setComponent(java.awt.Component component)
Sets the receiver's component to component.
See Also: "Managing the Component"
public void setDefaultComponentSize(java.awt.Dimension dimension)
Sets the default size of the receiver's component to dimension.
See Also: "Resizing"
public void setIcon(javax.swing.Icon icon)
Sets the receiver's icon to icon.
See Also: "Component Appearance"
public void setLabel(String label)
Sets the receiver's label to label.
See Also: "Component Appearance"
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"
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"
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"
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"
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"
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"
public javax.swing.JComponent subcontrollerArea()
Returns the component that holds the user interface for the receiver's subcontrollers.
See Also: "Class Description"
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"
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.
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.
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.
public boolean usesHorizontalLayout()
Returns true if
the receiver uses a horizontal layout, false otherwise.
See Also: "Layout"
DRAFT