PATH |
EOComponentController
Inherits from: EOController : Object
Implements: NSDisposable (Inherited from EOController) com.webobjects.eocontrol.EOKeyValueCodingAdditions (Inherited from EOController) EOAction.Enabling (Inherited from EOController) com.webobjects.eocontrol.EOKeyValueCoding (Inherited from EOKeyValueCodingAdditions) com.webobjects.foundation.NSKeyValueCoding (Inherited from EOKeyValueCoding)
Package: com.webobjects.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" (page 8) in the package introduction.
Default Rule System Controller Type |
groupingController |
XML Tag |
COMPONENTCONTROLLER |
XML Attribute | Value | Description |
alignmentWidth |
integer | See "Layout" (page 97). |
alignsComponents |
"true" or "false" | See "Layout" (page 97). |
horizontallyResizable |
"true" or "false" | See "Resizing" (page 97). |
iconName |
string | The filename of the component's icon. Uses standard resource location behavior to find the icon by name. See "Component Appearance" (page 97) for more information. |
iconURL |
string | The URL from which the icon is downloaded. See "Component Appearance" (page 97) for more information. |
label |
string | See "Component Appearance" (page 97). |
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" (page 97). |
usesHorizontalLayout |
"true" or "false" | See "Layout" (page 97). |
verticallyResizable |
"true" or "false" | See "Resizing" (page 97). |
Constants
Constant | Description |
Bottom | Description forthcoming. |
BottomLeft | Description forthcoming. |
BottomRight | Description forthcoming. |
Center | Description forthcoming. |
Left | Description forthcoming. |
Right | Description forthcoming. |
Top | Description forthcoming. |
TopLeft | Description forthcoming. |
TopRight | Description forthcoming. |
Interfaces Implemented
NSDisposable (Inherited from EOController) dispose EOKeyValueCodingAdditions (Inherited from EOController) EOAction.Enabling (Inherited from EOController) EOKeyValueCoding (Inherited from EOKeyValueCodingAdditions) handleQueryWithUnboundKey handleTakeValueForUnboundKey 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 EOComponentController(EOXMLUnarchiver unarchiver)
public EOComponentController()
Instance Methods
addComponentOfSubcontroller
protected void addComponentOfSubcontroller(EOComponentController controller)
alignmentWidth
public int alignmentWidth()
See Also: "Layout" (page 97)
alignsComponents
public boolean alignsComponents()
true
if the receiver aligns its components, false
otherwise.
See Also: "Layout" (page 97)
canBeTransient
public boolean canBeTransient()
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()
true
if the receiver can resize its component horizontally, or false
otherwise.
See Also: "Resizing" (page 97)
canResizeVertically
public boolean canResizeVertically()
true
if the receiver can resize its component vertically, or false
otherwise.
See Also: "Resizing" (page 97)
component
public javax.swing.JComponent component()
See Also: "Managing the Component" (page 96), prepareComponent, generateComponent
componentDidBecomeInvisible
protected void componentDidBecomeInvisible()
componentDidBecomeVisible
protected void componentDidBecomeVisible()
defaultComponentSize
public java.awt.Dimension defaultComponentSize()
See Also: "Resizing" (page 97)
dispose
public void dispose()
ensureMinimumComponentSizeWithoutSubcontrollers
public void ensureMinimumComponentSizeWithoutSubcontrollers( int width, int height)
See Also: "Resizing" (page 97)
ensureMinimumSubcontrollerAreaSize
public void ensureMinimumSubcontrollerAreaSize( int width, int height)
See Also: "Resizing" (page 97)
generateComponent
protected void generateComponent()
See Also: "Managing the Component" (page 96)
handleTakeValueForUnboundKey
public void handleTakeValueForUnboundKey( Object value, String key)
hideInSupercontroller
public boolean hideInSupercontroller()
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" (page 96)
hideSubcontroller
protected boolean hideSubcontroller(EOComponentController controller)
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" (page 96)
icon
public javax.swing.Icon icon()
null
if it has none.
See Also: "Component Appearance" (page 97)
integrationComponent
public javax.swing.JComponent integrationComponent()
See Also: "Class Description" (page 96)
integration ComponentDidBecomeInvisible
protected void integrationComponentDidBecomeInvisible()
false
, because by default the integration component is identical to the component.
integrationComponentDidBecomeVisible
protected void integrationComponentDidBecomeVisible()
true
, because by default the integration component is identical to the component.
isComponentPrepared
protected boolean isComponentPrepared()
true
if the receiver is prepared, false
otherwise.
See Also: "Managing the Component" (page 96)
isRootComponentController
public boolean isRootComponentController()
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()
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" (page 96)
label
public String label()
See Also: "Component Appearance" (page 97)
makeInvisible
public boolean makeInvisible()
true
if the method succeeds in making the receiver invisible, false
otherwise.
makeVisible
public boolean makeVisible()
true
if the method succeeds in making the receiver visible, false
otherwise.
See Also: "Visibility" (page 96)
minimumComponentSize
public java.awt.Dimension minimumComponentSize()
See Also: "Resizing" (page 97)
minimumComponentSizeWithoutSubcontrollers
public java.awt.Dimension minimumComponentSizeWithoutSubcontrollers()
See Also: "Resizing" (page 97)
minimumIntegrationComponentSize
public java.awt.Dimension minimumIntegrationComponentSize()
See Also: "Resizing" (page 97)
minimumSubcontrollerAreaSize
public java.awt.Dimension minimumSubcontrollerAreaSize()
See Also: "Resizing" (page 97)
prefersIconOnly
public boolean prefersIconOnly()
true
if the receiver prefers to represent itself with only an icon, false
otherwise.
See Also: "Component Appearance" (page 97)
prepareComponent
protected void prepareComponent()
See Also: "Managing the Component" (page 96)
removeComponentOfSubcontroller
protected void removeComponentOfSubcontroller(EOComponentController controller)
removeTransientSubcontroller
protected boolean removeTransientSubcontroller(EOController controller)
setAlignmentWidth
public void setAlignmentWidth(int alignmentWidgth)
See Also: "Layout" (page 97)
setAlignsComponents
public void setAlignsComponents(boolean flag)
See Also: "Layout" (page 97)
setCanResizeHorizontally
public void setCanResizeHorizontally(boolean flag)
See Also: "Resizing" (page 97)
setCanResizeVertically
public void setCanResizeVertically(boolean flag)
See Also: "Resizing" (page 97)
setComponent
public void setComponent(java.awt.Component component)
See Also: "Managing the Component" (page 96)
setDefaultComponentSize
public void setDefaultComponentSize(java.awt.Dimension dimension)
See Also: "Resizing" (page 97)
setIcon
public void setIcon(javax.swing.Icon icon)
See Also: "Component Appearance" (page 97)
setLabel
public void setLabel(String label)
See Also: "Component Appearance" (page 97)
setPrefersIconOnly
public void setPrefersIconOnly(boolean flag)
See Also: "Component Appearance" (page 97)
setSubcontrollerArea
public void setSubcontrollerArea(javax.swing.JComponent component)
See Also: "Class Description" (page 96)
setUsesHorizontalLayout
public void setUsesHorizontalLayout(boolean flag)
See Also: "Layout" (page 97)
setVisible
public void setVisible(boolean flag)
If flag is true
, this method disposes of transient receivers after making them visible.
See Also: "Visibility" (page 96)
showInSupercontroller
public boolean showInSupercontroller()
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" (page 96)
showSubcontroller
protected boolean showSubcontroller(EOComponentController controller)
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" (page 96)
subcontrollerArea
public javax.swing.JComponent subcontrollerArea()
See Also: "Class Description" (page 96)
subcontrollerMinimumSizeDidChange
public void subcontrollerMinimumSizeDidChange( EOComponentController controller, javax.swing.JComponent component, java.awt.Dimension dimension)
See Also: "Resizing" (page 97)
subcontrollerWasAdded
protected void subcontrollerWasAdded(EOController controller)
subcontrollerWasRemoved
protected void subcontrollerWasRemoved(EOController controller)
toString
public String toString()
usesHorizontalLayout
public boolean usesHorizontalLayout()
true
if the receiver uses a horizontal layout, false
otherwise.
See Also: "Layout" (page 97)
© 2001 Apple Computer, Inc. (Last Published April 14, 2001)