Component (ThinWire RIA Ajax Framework API [ v1.2

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

thinwire.ui
Interface Component

All Known Subinterfaces:: AlignTextComponent, CheckedComponent, Container<T>, EditorComponent, HierarchyComponent<HI>, ImageComponent, ItemChangeEventComponent, MaskEditorComponent, RangeComponent, TextComponent, Window

All Known Implementing Classes:: Button, CheckBox, DateBox, Dialog, Divider, DropDown, DropDownDateBox, DropDownGridBox, FileChooser, Frame, GridBox, Hyperlink, Image, Label, Menu, Panel, ProgressBar, RadioButton, Slider, TabFolder, TabSheet, TextArea, TextField, Tree, WebBrowser

public interface Component

Component is the foundation of all visual objects in the framework. A visual object is one that offers a user interface that can be displayed and interacted with by a user. The common capabilities of all visual objects are defined by this object. This includes methods for setting and getting common spatial and focus properites as well as support for adding event listeners that receive notification of property and keypress state changes.

Since Component is an interface, you do not actually create an instance of it directly, instead you create an instance of one of its sub-classes, such as Button, TextField or Label.

Keyboard Navigation:

KEY	RESPONSE	NOTE
Tab	Transitions to the next focus capable `Component`	See `setFocus(boolean)` for details.
Shift-Tab	Transitions to the prior focus capable `Component`	See `setFocus(boolean)` for details.

Field Summary
`static java.lang.String`	`ACTION_CLICK` Contains the formal action name for a click performed on a `Component`.
`static java.lang.String`	`ACTION_DOUBLE_CLICK` Contains the formal action name for a double click performed on a `Component`.
`static java.lang.String`	`PROPERTY_ENABLED` Contains the formal property name for the enabled state of a `Component`.
`static java.lang.String`	`PROPERTY_FOCUS` Contains the formal property name for the focus state of a `Component`.
`static java.lang.String`	`PROPERTY_FOCUS_CAPABLE` Contains the formal property name for the focus capability of a `Component`.
`static java.lang.String`	`PROPERTY_HEIGHT` Contains the formal property name for the height of a `Component`.
`static java.lang.String`	`PROPERTY_LIMIT` Contains the formal property name for the layout manager limit of a component.
`static java.lang.String`	`PROPERTY_USER_OBJECT` Contains the formal property name for the user object of a `Component`.
`static java.lang.String`	`PROPERTY_VISIBLE` Contains the formal property name for the visible state of a `Component`.
`static java.lang.String`	`PROPERTY_WIDTH` Contains the formal property name for the width of a `Component`.
`static java.lang.String`	`PROPERTY_X` Contains the formal property name for the 'X' coordinate of a `Component`.
`static java.lang.String`	`PROPERTY_Y` Contains the formal property name for the 'Y' coordinate of a `Component`.

Method Summary
`void`	`addActionListener(java.lang.String[] actions, ActionListener listener)` Adds a `ActionListener` to this component that will be notified when any of the specified actions occur.
`void`	`addActionListener(java.lang.String action, ActionListener listener)` Adds a `ActionListener` to this component that will be notified when the specified action occurs.
`void`	`addDropListener(Component[] dragSources, DropListener listener)`
`void`	`addDropListener(Component dragSource, DropListener listener)`
`void`	`addKeyPressListener(java.lang.String[] keyPressCombos, KeyPressListener listener)` Adds a `KeyPressListener` that will be notified when any of the specified key press combinations occur.
`void`	`addKeyPressListener(java.lang.String keyPressCombo, KeyPressListener listener)` Adds a `KeyPressListener` that will be notified when the specified key press combination occurs.
`void`	`addPropertyChangeListener(java.lang.String[] propertyNames, PropertyChangeListener listener)` Adds a `PropertyChangeListener` to this component that will be notified when any of the specified properties change.
`void`	`addPropertyChangeListener(java.lang.String propertyName, PropertyChangeListener listener)` Adds a `PropertyChangeListener` to this componetn that will be notified when the specified property changes.
`void`	`fireAction(ActionEvent ev)` Programmatically signals an action which triggers the appropriate listener which calls the desired method.
`void`	`fireAction(java.lang.String action)` A convenience method that is equal to this.fireAction(new ActionEvent(this, action));
`void`	`fireAction(java.lang.String action, java.lang.Object source)` A convenience method that is equal to this.fireAction(new ActionEvent(this, action));
`void`	`fireDrop(Component dragComponent)`
`void`	`fireDrop(Component dragComponent, java.lang.Object dragObject)`
`void`	`fireDrop(DropEvent ev)`
`void`	`fireKeyPress(KeyPressEvent ev)` Allows you to programmatically trigger a key press combination.
`void`	`fireKeyPress(java.lang.String keyPressCombo)` A convenience method that is equal to this.fireKeyPress(new KeyPressEvent(keyPressCombo, this));
`Container`	`getContainer()` Returns the parent `Container` of this `Component`.
`int`	`getHeight()` Returns the height of this `Component`.
`Label`	`getLabel()` Returns the `Label` assigned to this `Component`.
`java.lang.Object`	`getLimit()` Gets the layout limit that controls the bounds of this component within the context of the parent `Container`'s layout.
`java.lang.Object`	`getParent()` Returns the parent `Object` of this `Component`.
`Style`	`getStyle()` Returns a `Style` object representing this `Component`'s current style settings.
`java.lang.Object`	`getUserObject()` Returns the user defined `Object` for this `Component`.
`int`	`getWidth()` Returns the width of this `Component`.
`int`	`getX()` Returns the X coordinate of this `Component`.
`int`	`getY()` Returns the Y coordinate of this `Component`.
`boolean`	`isEnabled()` Returns whether this `Component` is enabled and therefore supports user interaction.
`boolean`	`isFocus()` Returns whether this `Component` has the input focus.
`boolean`	`isFocusCapable()` Returns whether this `Component` supports gaining focus.
`boolean`	`isVisible()` Returns a boolean value indicating whether this `Component` may be displayed in a window.
`void`	`removeActionListener(ActionListener listener)` Unregister an `ActionListener` from all action event notifications from this component.
`void`	`removeDropListener(DropListener listener)`
`void`	`removeKeyPressListener(KeyPressListener listener)` Removes the specified `KeyPressListener` from the component.
`void`	`removePropertyChangeListener(PropertyChangeListener listener)` Removes the specified `PropertyChangeListener` from the component.
`Component`	`setBounds(int x, int y, int width, int height)` Assigns the specified width, height, X and Y values to this `Component` atomically, in one operation.
`void`	`setEnabled(boolean enabled)` Assigns whether this `Component` is enabled and therefore supports user interaction.
`void`	`setFocus(boolean focus)` Assigns whether this `Component` has the input focus.
`void`	`setFocusCapable(boolean focusCapable)` Assigns whether this `Component` supports gaining focus.
`void`	`setHeight(int height)` Assigns the specified height to this `Component`. Default: 0 Events:
`Component`	`setLimit(java.lang.Object limit)` Sets a layout limit that controls the bounds of this component within the context of the parent `Container`'s layout.
`Component`	`setPosition(int x, int y)` Assigns the specified X and Y coordinates to this `Component` atomically, in one operation.
`Component`	`setSize(int width, int height)` Assigns the specified width and height to this `Component` atomically, in one operation.
`void`	`setUserObject(java.lang.Object userObject)` Assigns a user defined `Object` to this `Component`.
`void`	`setVisible(boolean visible)` Assigns a boolean value indicating whether this `Component` may be displayed in a window.
`void`	`setWidth(int width)` Assigns the specified width to this `Component`. Default: 0 Events:
`void`	`setX(int x)` Assigns the specified X coordinate to this `Component`. Default: 0 Events:
`void`	`setY(int y)` Assigns the specified Y coordinate to this `Component`. Default: 0 Events:

Field Detail

PROPERTY_X

static final java.lang.String PROPERTY_X

Contains the formal property name for the 'X' coordinate of a Component.

See Also:: setX(int), getX(), Constant Field Values

PROPERTY_Y

static final java.lang.String PROPERTY_Y

Contains the formal property name for the 'Y' coordinate of a Component.

See Also:: setY(int), getY(), Constant Field Values

PROPERTY_WIDTH

static final java.lang.String PROPERTY_WIDTH

Contains the formal property name for the width of a Component.

See Also:: setWidth(int), getWidth(), Constant Field Values

PROPERTY_HEIGHT

static final java.lang.String PROPERTY_HEIGHT

Contains the formal property name for the height of a Component.

See Also:: setHeight(int), getHeight(), Constant Field Values

PROPERTY_LIMIT

static final java.lang.String PROPERTY_LIMIT

Contains the formal property name for the layout manager limit of a component.

See Also:: setLimit(Object), getLimit(), Constant Field Values

PROPERTY_VISIBLE

static final java.lang.String PROPERTY_VISIBLE

Contains the formal property name for the visible state of a Component.

See Also:: setVisible(boolean), isVisible(), Constant Field Values

PROPERTY_ENABLED

static final java.lang.String PROPERTY_ENABLED

Contains the formal property name for the enabled state of a Component.

See Also:: setEnabled(boolean), isEnabled(), Constant Field Values

PROPERTY_FOCUS_CAPABLE

static final java.lang.String PROPERTY_FOCUS_CAPABLE

Contains the formal property name for the focus capability of a Component.

See Also:: setFocusCapable(boolean), isFocusCapable(), Constant Field Values

PROPERTY_FOCUS

static final java.lang.String PROPERTY_FOCUS

Contains the formal property name for the focus state of a Component.

See Also:: setFocus(boolean), isFocus(), Constant Field Values

PROPERTY_USER_OBJECT

static final java.lang.String PROPERTY_USER_OBJECT

Contains the formal property name for the user object of a Component.

See Also:: setUserObject(Object), getUserObject(), Constant Field Values

ACTION_CLICK

static final java.lang.String ACTION_CLICK

Contains the formal action name for a click performed on a Component.

See Also:: addActionListener(String, ActionListener), addActionListener(String[], ActionListener), removeActionListener(ActionListener), fireAction(ActionEvent), Constant Field Values

ACTION_DOUBLE_CLICK

static final java.lang.String ACTION_DOUBLE_CLICK

Contains the formal action name for a double click performed on a Component.

See Also:: addActionListener(String, ActionListener), addActionListener(String[], ActionListener), removeActionListener(ActionListener), fireAction(ActionEvent), Constant Field Values

Method Detail

addPropertyChangeListener

void addPropertyChangeListener(java.lang.String propertyName,
                               PropertyChangeListener listener)

Adds a PropertyChangeListener to this componetn that will be notified when the specified property changes. Adding a property listener to a component allows your code to react to a state change within the component.
Example:

 final TextField tf = new TextField();
 tf.setEnabled(false);
 
 CheckBox cb = new CheckBox("Check me to enable the TextField.");
 cb.addPropertyChangeListener(CheckBox.PROPERTY_CHECKED, new PropertyChangeListener() {
     public void propertyChange(PropertyChangeEvent pce) {
         if (pce.getNewValue() == Boolean.TRUE) {
             tf.setEnabled(true);
         } else {
             tf.setEnabled(false);
         }
     }
 });

Parameters:: propertyName - the name of the property that the listener will receive change events for.; listener - the listener that will receive PropertyChangeEvent objects upon the property changing.
Throws:: java.lang.IllegalArgumentException - if listener or propertyName is null or if propertyName is an empty string.
See Also:: PropertyChangeListener, PropertyChangeEvent

addPropertyChangeListener

void addPropertyChangeListener(java.lang.String[] propertyNames,
                               PropertyChangeListener listener)

Adds a PropertyChangeListener to this component that will be notified when any of the specified properties change. This method is equivalent to calling addPropertyChangeListener(String, PropertyChangeListener) once for each property you want to listen to.

Parameters:: propertyNames - a string array of property names that the listener will receive change events for.; listener - the listerner that will receive PropertyChangeEvent objects anytime one of the specified propertyNames of this component change.
Throws:: java.lang.IllegalArgumentException - if listener, propertyNames or any property name is the array is null or if any property name is an empty string.
See Also:: addPropertyChangeListener(String, PropertyChangeListener), PropertyChangeListener, PropertyChangeEvent

removePropertyChangeListener

void removePropertyChangeListener(PropertyChangeListener listener)

Removes the specified PropertyChangeListener from the component. If the listener was added for multiple properties, it will be removed for all of them. NOTE: An exception is NOT thrown if you attempt to remove a listener that does not exist on this component.

Parameters:: listener - the listener to remove from the component.
Throws:: java.lang.IllegalArgumentException - if listener is null.
See Also:: PropertyChangeListener

addActionListener

void addActionListener(java.lang.String action,
                       ActionListener listener)

Adds a ActionListener to this component that will be notified when the specified action occurs.

Parameters:: action - the action to specficially be notified of.; listener - the event listener that will receive notification.

addActionListener

void addActionListener(java.lang.String[] actions,
                       ActionListener listener)

Adds a ActionListener to this component that will be notified when any of the specified actions occur.

Parameters:: actions - the actions to specficially be notified of.; listener - the event listener that will receive notification.

removeActionListener

void removeActionListener(ActionListener listener)

Unregister an ActionListener from all action event notifications from this component.

Parameters:: listener - the listener that should no longer receive action event notifications.

fireAction

void fireAction(ActionEvent ev)

Programmatically signals an action which triggers the appropriate listener which calls the desired method.

Parameters:: ev - the event to signal

fireAction

void fireAction(java.lang.String action)

A convenience method that is equal to this.fireAction(new ActionEvent(this, action));

Parameters:: action - the action to perform on the component.

fireAction

void fireAction(java.lang.String action,
                java.lang.Object source)

A convenience method that is equal to this.fireAction(new ActionEvent(this, action));

Parameters:: action - the action to perform on the component.

addDropListener

void addDropListener(Component dragSource,
                     DropListener listener)

addDropListener

void addDropListener(Component[] dragSources,
                     DropListener listener)

removeDropListener

void removeDropListener(DropListener listener)

fireDrop

void fireDrop(DropEvent ev)

fireDrop

void fireDrop(Component dragComponent)

fireDrop

void fireDrop(Component dragComponent,
              java.lang.Object dragObject)

addKeyPressListener

void addKeyPressListener(java.lang.String keyPressCombo,
                         KeyPressListener listener)

Adds a KeyPressListener that will be notified when the specified key press combination occurs.

For a description and list of valid keyPressCombo strings, see the documentation for KeyPressEvent.encodeKeyPressCombo(boolean, boolean, boolean, String).

Establishing keyboard shortcuts for certain features can be a highly effective way to improve the efficiency of your application. If your application has a Menu, then typically the best way to establish such shortcuts is to simply set the keyPressCombo property for each Menu.Item. Second to that, using this method to establish shortcuts on the Frame or a Dialog will have a similar wide reaching effect. Occasionally, based on the requirements of your application, you may also use this method to establish shortcuts that are only valid when a given component has focus.

Details:

When a user presses a key and/or combination, the event bubbles up the component hierarchy from the component that currently has focus and is absorbed by the first Component that has a listener asking to be notified of that event. Therefore, if both a Component and a Container up the hierarchy are listening for the same event, only the Component will receive notification. There is currently no way to cause the event to continue bubbling.

Additionally, the keyboard navigation of each Component cannot be overridden and you cannot receive notification of such events. As an example, establishing a KeyPressListener for "Space" key on the CheckBox, will have no effect because the "Space" key toggles the checked state of that component.

NOTE ON WEBBROWSERS: If no Component is listening for a given key press, then the default behavior that the browser has associated with that key press will occur. Additionally, certain key press events in certain browsers cannot be entirely circumvented. In such a case, both the action defined by a listener and the browser's default behavior will occur. An example of this is the F1 key in Internet Explorer. If you establish a listener for the F1 key, the IE help file will open in addition to whatever action you may have defined.

Example:

 Application.current().getFrame().addKeyPressListener("Ctrl-Alt-M", new KeyPressListener() {
     public void keyPress(KeyPressEvent kpe) {
         MessageBox.confirm("You pressed the following key combination: " + kpe.getKeyPressCombo());
     }
 });

Parameters:: keyPressCombo - a key press combo in any dash separated format supported by KeyPressEvent.normalizeKeyPressCombo(String).; listener - the listener that will receive KeyPressEvent objects upon the key press occurring.
Throws:: java.lang.IllegalArgumentException - if listener or keyPressCombo is null, or if keyPressCombo is an empty string, or if keyPressCombo represents an invalid key combo.
See Also:: KeyPressListener, KeyPressEvent, KeyPressEvent.encodeKeyPressCombo(boolean, boolean, boolean, String), KeyPressEvent.normalizeKeyPressCombo(String)

addKeyPressListener

void addKeyPressListener(java.lang.String[] keyPressCombos,
                         KeyPressListener listener)

Adds a KeyPressListener that will be notified when any of the specified key press combinations occur.

For a description and list of valid keyPressCombo strings, see the documentation for KeyPressEvent.encodeKeyPressCombo(boolean, boolean, boolean, String).

See addKeyPressListener(String, KeyPressListener) for a full semantic description.

Parameters:: keyPressCombos - a string array of key press combos, each in any dash separated format supported by KeyPressEvent.normalizeKeyPressCombo(String).; listener - the listener that will receive KeyPressEvent objects when any of the key presses occur.
Throws:: java.lang.IllegalArgumentException - if listener or any key press combo in keyPressCombos is null, or if any key press combo in keyPressCombos is an empty string, or if any key press combo in keyPressCombos represents an invalid key combo.
See Also:: addKeyPressListener(String, KeyPressListener), KeyPressListener, KeyPressEvent, KeyPressEvent.encodeKeyPressCombo(boolean, boolean, boolean, String), KeyPressEvent.normalizeKeyPressCombo(String)

removeKeyPressListener

void removeKeyPressListener(KeyPressListener listener)

Removes the specified KeyPressListener from the component. If the listener was added for multiple key press combinations, it will be removed for all of them. NOTE: An exception is NOT thrown if you attempt to remove a listener that does not exist on this component.

Parameters:: listener - the listener to remove from the component.
Throws:: java.lang.IllegalArgumentException - if listener is null.
See Also:: KeyPressListener

fireKeyPress

void fireKeyPress(KeyPressEvent ev)

Allows you to programmatically trigger a key press combination. Passing this method a valid key press combination will result in a KeyPressEvent being generated. As a result, all KeyPressListener's that are registered on the specified keyPressCombo will be notified.

For a description and list of valid keyPressCombo strings, see the documentation for KeyPressEvent.encodeKeyPressCombo(boolean, boolean, boolean, String).

Details:

A KeyPressEvent that is generated programmatically via this mechansim may, under some circumstances, have a slightly different behavior than one generated by user activity. The reason for this is that the event is only propagated within the framework itself and does not actually occur in the client. In general, this should never be an issue because the desired response to a keypress will be expressly defined by a given KeyPressListener and therefore there would be no dependence on any such side-effect. However, an example of one such difference, is in terms of a browser's default behavior for a specific key press combination. If you use this mechanism to trigger an F1 keypress, the browser's default behavior (typically bringing up a help window), will not occur.

Parameters:: ev - a KeyPressEvent that represents the key press combo you want to signal has occured.
Throws:: java.lang.IllegalArgumentException - if keyPressCombo is null, or if keyPressCombo is an empty string, or if keyPressCombo represents an invalid key combo.

fireKeyPress

void fireKeyPress(java.lang.String keyPressCombo)

A convenience method that is equal to this.fireKeyPress(new KeyPressEvent(keyPressCombo, this));

Parameters:: keyPressCombo - a key press combo in any dash separated format supported by KeyPressEvent.normalizeKeyPressCombo(String).
See Also:: KeyPressEvent.encodeKeyPressCombo(boolean, boolean, boolean, String), KeyPressEvent.normalizeKeyPressCombo(String)

getParent

java.lang.Object getParent()

Returns the parent Object of this Component. If you specifically need the parent Container of this Component use getContainer() instead.
Details:

Under the majority of situations, the returned value is either a Container or null since a Component will either be a child of a Container or not attached to any object. However, in some cases the parent of the Component may be another Component, or a completely different kind of Object. For example, in the case of the DropDownGridBox, there is an actual GridBox that is a child of the drop down. Therefore, the parent of that GridBox would be the DropDownGridBox. Another situation exists when you use a multi-tiered GridBox, meaning a GridBox that has one or more "pop-up" child GridBox's. Under that scenario, the parent of the child's GridBox is actually an instance of GridBox.Row and the parent of the row is the GridBox.

Returns:: the parent Object of this Component, or null if no parent exists.
See Also:: getContainer()

getContainer

Container getContainer()

Returns the parent Container of this Component. Unlike getParent(), this method guarantees that if a non-null value is returned, it will be a Contaienr.

Returns:: the parent Container of this Component, or null if no parent exists.
Throws:: java.lang.IllegalStateException - if in the process of walking up the parent hierarchy, an unrecognized parent type is found.
See Also:: getParent()

getLabel

Label getLabel()

Returns the Label assigned to this Component. This property is part of a two-way relationship that is established by the Label.setLabelFor(Component) property. There is no setLabel method, instead use Label.setLabelFor(Component).

Returns:: the Label assigned to this Component.

getUserObject

java.lang.Object getUserObject()

Returns the user defined Object for this Component.
Default: null

Returns:: the user defined Object for this Component, or null if no value has been specified.
See Also:: setUserObject(Object)

setUserObject

void setUserObject(java.lang.Object userObject)

Assigns a user defined Object to this Component. This property has no direct effect on the state of the Component. Instead, it provides a general purpose storage mechanism to the developer that allows any kind of data to be associated to this Component. For complex applications, alternate methods of associating state to a Component will likely serve your design more thoroughly. However, there are a number of cases where this flexibility could be useful and therefore the framework supports the concept.
Default: null

Refer to the documenation on Application.addGlobalPropertyChangeListener(String, PropertyChangeListener) for an example of a potential use of this property.

Events:

If the prior value and new value differ, setting this property causes a PropertyChangeEvent ( propertyName = PROPERTY_USER_OBJECT ) to be generated.

Parameters:: userObject - an Object of any type that is to be associated with this Component.
See Also:: getUserObject(), Application.addGlobalPropertyChangeListener(String, PropertyChangeListener), PROPERTY_USER_OBJECT, PropertyChangeEvent

isEnabled

boolean isEnabled()

Returns whether this Component is enabled and therefore supports user interaction.
Default: true

Returns:: true if the Component supports user interaction, false otherwise.
See Also:: setEnabled(boolean)

setEnabled

void setEnabled(boolean enabled)

Assigns whether this Component is enabled and therefore supports user interaction. The form of user iteraction this property controls, depends on the specific kind of Component itself. However, in general, all keyboard interaction and mouse interaction is disabled by setting this property to false.
Default: true
Events:

If the prior value and new value differ, setting this property causes a PropertyChangeEvent ( propertyName = PROPERTY_ENABLED ) to be generated.

Parameters:: enabled - true to allow user interaction, false to disallow it.
See Also:: isEnabled(), PROPERTY_ENABLED, PropertyChangeEvent

isFocusCapable

boolean isFocusCapable()

Returns whether this Component supports gaining focus.
Default: true, except for Divider, Image and Label.

Returns:: true if this Component supports gaining focus, false otherwise.
See Also:: setFocusCapable(boolean), setFocus(boolean)

setFocusCapable

void setFocusCapable(boolean focusCapable)

Assigns whether this Component supports gaining focus.
Default: true, except for Divider, Image and Label.
Events:

If the prior value and new value differ, setting this property causes a PropertyChangeEvent ( propertyName = PROPERTY_FOCUS_CAPABLE ) to be generated.

Parameters:: focusCapable - true to allow this component to receive focus, false to disallow it.
See Also:: isFocusCapable(), PROPERTY_FOCUS_CAPABLE, setFocus(boolean), PropertyChangeEvent

isFocus

boolean isFocus()

Returns whether this Component has the input focus. If this is a Container, then this method will return true if a child Component has the focus. In such a case, you can use the Container.getChildWithFocus() method to get a reference to that child. Similarly, if you want to find the child Component that has the focus anywhere in the current Frame or Dialog, you can use the Container.getComponentWithFocus() method.

Default: false. However, at rendering time, if no component in the window has focus, the first focus capable component is given focus.

See the setFocus(boolean) method for a full description of focus details.

Returns:: true if this Component has the input focus, false otherwise.
See Also:: setFocus(boolean), Container.getComponentWithFocus(), Container.getChildWithFocus()

setFocus

void setFocus(boolean focus)

Assigns whether this Component has the input focus. When this Component has the input focus, it will receive all keyboard events generated by the user. Therefore, if this Component supports text editing and it has focus, the user can type a value into it's field. Additionally, any keyboard navigation supported by this Component or keyboard shortcuts added by a developer become available upon gaining focus. Conversely, when this Component no longer has focus, it will receive no keyboard events.

Default: false. However, at rendering time, if no component in the window has focus, the first focus capable component is given focus.

Details:

The simplest of all cases, is when this Component has not yet been added to a Container. In that scenario, the focus property is simply set to true and no other effect occurs. Later, when this Component is added to a Container it will be given the focus according to the guidelines that follow.

As a general rule, only a single Component can have the focus per Frame or Dialog container hierarchy. In terms of the user interface, only a single Component will actually have the focus regardless of whether a Dialog and the Frame have components with focus. In such a case, the actual focus is determined based on which window is currently active.

Since only one Component per window can have focus, giving this Component focus will cause the prior Component of the window to lose focus. In the most common case, both this Component and the Component losing focus will be siblings in the same Container. In that case, the focus property of the Component losing focus is simply set to false whereas the focus property of this Component is set to true.

More complex scenarios arise when the Component losing focus and this Component are not siblings in the same Container. In those cases, the order in which focus is lost and gained occurs as follows:

1. The highest level shared parent Container between both the Component losing focus and this Component is found. This shared parent and any Container above it in the hierarchy will be left alone.
2. The focus property is set to false for each Container in the hierarchy that contains the Component losing focus, as well as the component itself. This is done in top down order, so that the top most Container loses focus first, followed by every container between it and the Component losing focus next, and with the component itself losing focus last.
3. The focus property is set to truefor each Container in the hierarchy that contains this Component, as well as the component itself. This is done in top down order, so that the top most Container gains focus first, followed by every container between it and the Component gaining focus next, and with this component gaining focus last.


 
 The final case to be aware of is if you directly set this Component's focus to false.  In that case,
 the same loss of focus rules outlined above apply.  There is simply no gaining of focus that occurs by any component.
 Therefore you cause the window to have no Component with focus, with the except of the parent Container
 of this Component.
 
 Events:
 
 If the prior value and new value differ, setting this property causes a PropertyChangeEvent ( propertyName = PROPERTY_FOCUS ) to be generated. Additionally,
 similar event generation may occur for other components according to the details outlined above.

Parameters:: focus - true to give this Component and it's parent containers focus, false otherwise.
Throws:: java.lang.IllegalStateException - if this Component is not focus capable; java.lang.UnsupportedOperationException - if the parent of this Component is not null and is not a Container
See Also:: isFocus(), Container.getComponentWithFocus(), Container.getChildWithFocus()





getStyle
Style getStyle()

Returns a Style object representing this Component's current style settings. NOTE: This method
 will never return null.



Returns:
a Style object representing this Component's current style settings.
See Also:
Style





getX
int getX()

Returns the X coordinate of this Component.



Returns:
the X coordinate (in pixels) of this Component
See Also:
setX(int)





setX
void setX(int x)

Assigns the specified X coordinate to this Component.

 Default: 0
 Events:
 
 If the prior value and new value differ, setting this property causes a PropertyChangeEvent ( propertyName = PROPERTY_X ) to be generated.
 


Parameters:
x - the x coordinate (in pixels) to assign to this Component
Throws:
java.lang.IllegalArgumentException - if the x value is < -32768 or >= 32767
See Also:
getX(), 
setPosition(int, int), 
setBounds(int, int, int, int), 
PROPERTY_X, 
PropertyChangeEvent





getY
int getY()

Returns the Y coordinate of this Component.



Returns:
the Y coordinate (in pixels) of this Component
See Also:
setY(int)





setY
void setY(int y)

Assigns the specified Y coordinate to this Component.

 Default: 0
 Events:
 
 If the prior value and new value differ, setting this property causes a PropertyChangeEvent ( propertyName = PROPERTY_Y ) to be generated.
 


Parameters:
y - the y coordinate (in pixels) to assign to this Component
Throws:
java.lang.IllegalArgumentException - if the y value is < -32768 or >= 32767
See Also:
getY(), 
setPosition(int, int), 
setBounds(int, int, int, int), 
PROPERTY_Y, 
PropertyChangeEvent





setPosition
Component setPosition(int x,
                      int y)

Assigns the specified X and Y coordinates to this Component atomically, in one operation.
 Aside from the convienence provided by this method, it also guarantees that both of the provided
 X and Y coordinates are legal values before the values are committed.  The primary benefit of this
 is that no PropertyChangeEvent's will be generated until both values have been set.
 Events:
 
 This method may generate PropertyChangeEvent's. See the documenation of setX and setY for more details.
 


Parameters:
x - the x coordinate (in pixels) to assign to this Component
y - the y coordinate (in pixels) to assign to this Component
Returns:
this Component so that you can perform operations like container.getChildren().add(new Button().setPosition(x, y))
Throws:
java.lang.IllegalArgumentException - if the x or y value is < -32768 or >= 32767
See Also:
setX(int), 
setY(int), 
setBounds(int, int, int, int), 
PROPERTY_X, 
PROPERTY_Y, 
PropertyChangeEvent





getWidth
int getWidth()

Returns the width of this Component.



Returns:
the width (in pixels) of this Component
See Also:
setWidth(int)





setWidth
void setWidth(int width)

Assigns the specified width to this Component.

 Default: 0

 Events:
 
 If the prior value and new value differ, setting this property causes a PropertyChangeEvent ( propertyName = PROPERTY_WIDTH ) to be generated.
 


Parameters:
width - the width (in pixels) to assign to this Component
Throws:
java.lang.IllegalArgumentException - if the width value is < 0 or >= 32767
See Also:
getWidth(), 
setSize(int, int), 
setBounds(int, int, int, int), 
PROPERTY_WIDTH, 
PropertyChangeEvent





getHeight
int getHeight()

Returns the height of this Component.



Returns:
the height (in pixels) of this Component
See Also:
setHeight(int)





setHeight
void setHeight(int height)

Assigns the specified height to this Component.

 Default: 0

 Events:
 
 If the prior value and new value differ, setting this property causes a PropertyChangeEvent ( propertyName = PROPERTY_HEIGHT ) to be generated.
 


Parameters:
height - the height (in pixels) to assign to this Component
Throws:
java.lang.IllegalArgumentException - if the height value is < 0 or >= 32767
See Also:
getHeight(), 
setSize(int, int), 
setBounds(int, int, int, int), 
PROPERTY_HEIGHT, 
PropertyChangeEvent





setSize
Component setSize(int width,
                  int height)

Assigns the specified width and height to this Component atomically, in one operation.
 Aside from the convienence provided by this method, it also guarantees that both of the provided
 width and height are legal values before the values are committed.  The primary benefit of this
 is that no PropertyChangeEvent's will be generated until both values have been set.
 Events:
 
 This method may generate PropertyChangeEvent's. See the documenation of setWidth and setHeight for more details.
 


Parameters:
width - the width (in pixels) to assign to this Component
height - the height (in pixels) to assign to this Component
Returns:
this Component so that you can perform operations like container.getChildren().add(new Button().setSize(width, height))
Throws:
java.lang.IllegalArgumentException - if the width or height value is < 0 or >= 32767
See Also:
setWidth(int), 
setHeight(int), 
setBounds(int, int, int, int), 
PROPERTY_WIDTH, 
PROPERTY_HEIGHT, 
PropertyChangeEvent





setBounds
Component setBounds(int x,
                    int y,
                    int width,
                    int height)

Assigns the specified width, height, X and Y values to this Component atomically, in one operation.
 Aside from the convienence provided by this method, it also guarantees that all of the provided
 values are legal before they are committed.  The primary benefit of this
 is that no PropertyChangeEvent's will be generated until all values have been set.
 Events:
 
 This method may generate PropertyChangeEvent's. See the documenation of setX, setY, setWidth and setHeight for more details.
 


Parameters:
x - the x coordinate (in pixels) to assign to this Component
y - the y coordinate (in pixels) to assign to this Component
width - the width (in pixels) to assign to this Component
height - the height (in pixels) to assign to this Component
Returns:
this Component so that you can perform operations like container.getChildren().add(new Button().setBounds(x, y, width, height))
Throws:
java.lang.IllegalArgumentException - if the width or height value is < 0 or >= 32767, or if the x or y value is < -32768 or >= 32767
See Also:
setX(int), 
setY(int), 
setWidth(int), 
setHeight(int), 
setBounds(int, int, int, int), 
PROPERTY_X, 
PROPERTY_Y, 
PROPERTY_WIDTH, 
PROPERTY_HEIGHT, 
PropertyChangeEvent





getLimit
java.lang.Object getLimit()

Gets the layout limit that controls the bounds of this component within the context of the parent Container's layout.



Returns:
the layout limit that is in use by the Container's layout, or null if no limit is specified.
See Also:
setLimit(Object), 
Container.getLayout(), 
Container.setLayout(thinwire.ui.layout.Layout), 
Layout





setLimit
Component setLimit(java.lang.Object limit)

Sets a layout limit that controls the bounds of this component within the context of the parent Container's layout.
 The type of limit object that is acceptable depends on the Layout that is specified for the parent Container.
 Default: null


Parameters:
limit - a layout limit to use for the Container's layout, or null to clear the limit.
Returns:
this Component so that you can perform operations like container.getChildren().add(new Button().setLimit(...))
See Also:
PROPERTY_LIMIT, 
getLimit(), 
Container.getLayout(), 
Container.setLayout(thinwire.ui.layout.Layout), 
Layout, 
PropertyChangeEvent





isVisible
boolean isVisible()

Returns a boolean value indicating whether this Component may be displayed in a window. See
 the documentation of setVisible(boolean) for further details about this property.

 Default: true, except for the Dialog and Frame containers.



Returns:
true if this Component may be displayed, fasle otherwise
See Also:
setVisible(boolean)





setVisible
void setVisible(boolean visible)

Assigns a boolean value indicating whether this Component may be displayed in a window. 

 Default: true, except for the Dialog and Frame containers. 

 Details:
 
 This Component will not actually be displayed unless it is visible and added to a Container
 hierarchy in which all of the containers are also visible and the top-level Container is a visible
 Frame or Dialog. Once a Component has been displayed, toggling this property
 results in a light-weight operation that simply hides/shows this Component. This may sound trivial, but the
 difference is important when you need to maximize the performance of your application. For instance, it is a faster to toggle
 the visibility of components then it is to add/remove the components from a displayed Container. This is
 because the first time a Component is displayed, the entire state must be rendered. In contrast, when you
 toggle visibility, the Component remains in memory in a fully rendered form, it is just not visible to the
 user.
 
 Events:
 
 If the prior value and new value differ, setting this property causes a PropertyChangeEvent ( propertyName = PROPERTY_VISIBLE ) to be generated.
 


Parameters:
visible - true to indicate this Component may be displayed, false otherwise
See Also:
isVisible(), 
PROPERTY_VISIBLE, 
Container.getChildren(), 
PropertyChangeEvent














  
      Overview 
      Package 
    Class 
      Tree 
      Deprecated 
      Index 
      Help 
  









 PREV CLASS 
 NEXT CLASS

  FRAMES   
 NO FRAMES   
 







  SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD







				ThinWire® is a registered of Custom Credit Systems  Copyright © 2007 All rights reserved.

thinwire.ui Interface Component

PROPERTY_X

PROPERTY_Y

PROPERTY_WIDTH

PROPERTY_HEIGHT

PROPERTY_LIMIT

PROPERTY_VISIBLE

PROPERTY_ENABLED

PROPERTY_FOCUS_CAPABLE

PROPERTY_FOCUS

PROPERTY_USER_OBJECT

ACTION_CLICK

ACTION_DOUBLE_CLICK

addPropertyChangeListener

addPropertyChangeListener

removePropertyChangeListener

addActionListener

addActionListener

removeActionListener

fireAction

fireAction

fireAction

addDropListener

addDropListener

removeDropListener

fireDrop

fireDrop

fireDrop

addKeyPressListener

addKeyPressListener

removeKeyPressListener

fireKeyPress

fireKeyPress

getParent

getContainer

getLabel

getUserObject

setUserObject

isEnabled

setEnabled

isFocusCapable

setFocusCapable

isFocus

setFocus

getStyle

getX

setX

getY

setY

setPosition

getWidth

setWidth

getHeight

setHeight

setSize

setBounds

getLimit

setLimit

isVisible

setVisible

thinwire.ui
Interface Component