Java Doc for Component.java in  » Web-Framework » ThinWire » thinwire » ui » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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 Component.setFocus(boolean) for details.
Shift-Tab	Transitions to the prior focus capable Component	See Component.setFocus(boolean) for details.

For a description and list of valid keyPressCombo strings, see the documentation for thinwire.ui.event.KeyPressEvent.encodeKeyPressCombo(booleanbooleanbooleanString) .

Establishing keyboard shortcuts for certain features can be a highly effective way to improve the efficiency of your application.

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

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

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

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

For a description and list of valid keyPressCombo strings, see the documentation for thinwire.ui.event.KeyPressEvent.encodeKeyPressCombo(booleanbooleanbooleanString) .

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.

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.

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

For a description and list of valid keyPressCombo strings, see the documentation for thinwire.ui.event.KeyPressEvent.encodeKeyPressCombo(booleanbooleanbooleanString) .

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

 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);
 }
 }
 });
 

For a description and list of valid keyPressCombo strings, see the documentation for thinwire.ui.event.KeyPressEvent.encodeKeyPressCombo(booleanbooleanbooleanString) .

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.

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.

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

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

This method may generate PropertyChangeEvent's. See the documenation of setX, setY, setWidth and setHeight for more details.

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

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

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 true for 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.

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

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

This method may generate PropertyChangeEvent's. See the documenation of setX and setY for more details.

This method may generate PropertyChangeEvent's. See the documenation of setWidth and setHeight for more details.

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

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

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.

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

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

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

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