You see the Properties window for a Listbox component when you select the component on a page that you are editing in the Visual Designer.
This JavaServer Faces 1.2 component has the following properties.
General
id. Type: String
The name of the component in the page bean and the JSP file. In the JSP file, this name is the value of the component's id attribute. In the page bean, this property's value is the name of the HtmlSelectOneListbox object.
Appearance
label. Type: String
If text is specified for this property, a label showing the text is displayed with the component.
The label property is not as flexible as the Label component. You can use the Label component if you want more control over the label's appearance, such as positioning of the label relative to the component.
labelLevel. Type: int
A number that affects the appearance of the label. 1 (Strong) is larger and bold. 2 (Medium), the default, is smaller and bold. 3 (Weak) is smaller and normal (not bold). This property takes effect only if the label property is set.
labelOnTop. Type: boolean
If this property is selected, the label is rendered above the component. By default, the property is not selected and the label is rendered beside the component.
monospace. Type: boolean
If this property is selected, the label is rendered in a monospace font.
rows. Type: int
The number of options to show at one time, by default 12 options.
If there are more options to show than indicated in this
property, a scrollbar is added to the listbox. If this
property is not set, all options are shown.
separators. Type: boolean
If this property is selected, each option group in the list is separated from the other option groups with a visible separator. For the separators to display, the list options must be defined as subclasses of the com.sun.webui.jsf.model.OptionGroup class. This property is selected by default.
style. Type: String
Cascading Style Sheet rules (CSS level 2) to be applied to the component. For example:
position: absolute; left: 288px; top: 312px
You can enter values directly or click the ellipsis (...) button to use the Style Editor.
This property overrides any settings in the theme or the project CSS file for this component. If a style specified in this property does not appear to take effect, it is because an area of the component is obscured by a child component that has different style settings.
For a list of CSS2 style attributes, see the web page at
styleClass. Type: String A space-separated list of CSS2 style classes to be applied when the component is rendered. The style classes must be defined in the project's style sheet or in the theme's CSS file. If you click the ellipsis button (...), you see a list of all styles you can add to this property. For information on adding CSS classes and rules to the project's cascading style sheet, see CSS Editor.
See the note above under the style property description for an explanation of why a class added to this property might appear to have no effect on the component.
If you add a CSS style class from the current theme to your project CSS file and you redefine the style class, the change affects all components that use this style class. However, you can add your own style classes to the project CSS file that redefine the default style classes, and then when you add them to this property, the changes affect only this instance of this component.
Data
converter. Type: Converter
A JavaServer Faces converter that produces the correct type of value for the value property. If the user enters the wrong type of value, such as a word instead of a number for an Integer converter, the converter sends a message that you can display in a Message component.
If you use an Enum converter with this component, you must edit the converter's Java declaration to use an enum class as a parameter, as described in Enum Converter.
items. Type: Object
Specifies an object that supplies the items for the list. The IDE creates a default object for you when you add the listbox to the page. For example, for a listbox named listBox1, there is a listBox1DefaultOptions object that the IDE displays as a node in the Navigator window. You can bind this property to a data provider or an object by right-clicking the component and choosing Bind to Data. If you bind to an object, the object you choose must be an array, Map, or Collection whose members are all subclasses of com.sun.webui.jsf.model.Option.
multiple. Type: boolean
Indicates whether or not the user can select multiple items in the list at once.
required. Type: boolean
If selected, the user must select an item in the list before the page can be submitted. If you add a Message component to the page and link its for property to this component, an error message will be displayed if the user tries to submit the page without selecting an item.
selected. Type: Object
Picks up the currently selected list element and sends it to the server when the page is submitted. This property does not control the list that displays in the component. The list that displays in the component is controlled by the items property, described above. You can bind this property to a data provider or an object by clicking the ellipsis button (...) and using the property editor.
validatorExpression. Type: MethodExpression
Indicates the JavaServer Faces validator expression that is used when the value is submitted. A validator ensures
that the correct value is entered by a user. If the conditions defined by the validator are not met, the validator sends a message that you can display in a Message component.
Choose a validator from the drop down list. If you choose (null), no validator is called. If you choose a validator, you might also want to select the required property to ensure that the user enters a value.
You can define your own validate method, for example, by right-clicking the component and choosing Edit Event Handler > validate. If you define your own method, any value you might have set in this property is overridden.
Events
Set the event properties by right-clicking the component in the Visual Designer and choosing Edit Event Handler > eventname.
valueChange. Indicates the name of the component value change listener method that is called when the value of the component changes. If this method is not defined, the value of this property is null. You typically define this method in the page bean by right-clicking the component in the Visual Designer and choosing Edit Event Handler > processValueChange. The default name for the method is component-id_processValueChange, where component-id is the value of the component's id property.
validate. Indicates the name of the method that is called to validate the value of the component.
If you want to code a validate method rather than choosing a JavaServer Faces validator for the validatorExpression property, right-click the component and choose Edit Event Handler > validate. The default name for the method is component-id_validate, where component-id is the value of the component's id property. When you define this method in this way, the validator and validate properties are automatically set for you. If you define a validator, you might also want to select the required property to ensure that the user enters a value.
Setting this property also sets the value of the validatorExpression property. If you define your own validate method, do not separately change the value of the validatorExpression property, or you could lose the connection to your validate method.
Behavior
disabled. Type: boolean
If selected, indicates that the component should never receive focus or be included in a submit. Use this property when the component does not apply to the page. See the note under the readOnly property concerning the effects of using the disabled property versus the effects of using the readOnly property.
toolTip. Type: String
Advisory title information about the component, which is readable by a screen reader and can be displayed as a tool tip.
If the component is disabled, the tooltip will not display in most browsers.
visible. Type: boolean
Indicates whether or not the component can be seen by the user on the rendered HTML page. This property is selected by default. If you deselect this property, the component's HTML code is rendered on the page, but the component is not visible in the browser because it is hidden by a style setting. Because the HTML code is rendered, the component can still be processed on form submissions, and users who view source in the browser can see the HTML code. In addition, your web application can use client-side JavaScript to show or hide the component.
If you need to completely hide the component, for example, because it contains sensitive information that certain users should not see, deselect the rendered property.
Accessibility
tabIndex. Type: String
Optionally specifies the position of the component in the tab order of the document, determining when the component will get focus if the user tabs through the document. The value must be an integer between 0 and 32767.
JavaScript
onBlur. Type: String
JavaScript to be executed when the component loses focus.
onChange. Type: String
JavaScript to be executed when the component loses focus and its value was modified after it gained focus.
onClick. Type: String
JavaScript to be executed when the user clicks the component.
onDblClick. Type: String
JavaScript to be executed when the user double-clicks the component.
onFocus. Type: String
JavaScript to be executed when the component gains focus.
onKeyDown. Type: String
JavaScript to be executed when the component has focus and a key is pressed.
onKeyPress. Type: String
JavaScript to be executed when the component has focus and a key is pressed and released.
onKeyUp. Type: String
JavaScript to be executed when the component has focus and a key is released.
onMouseDown. Type: String
JavaScript to be executed when the mouse cursor is over the component and the user presses down on the mouse button.
onMouseMove. Type: String
JavaScript to be executed when the user moves the mouse cursor within the component.
onMouseOut. Type: String
JavaScript to be executed when the user moves the mouse cursor away from the component after it has been over the component.
onMouseOver. Type: String
JavaScript to be executed when the user moves the mouse cursor onto the component.
onMouseUp. Type: String
JavaScript to be executed when the mouse cursor is over the component and the user releases the mouse button.
Advanced
immediate. Type: boolean
If this property is selected, when the user activates the component, the code in the page bean is executed before the validation, updating of model values, and so on. Essentially, code execution happens right away on the server, which then returns the page.
A simpler way of getting this functionality is to associate the component with a virtual form, and then right-click the component and choose Auto-Submit on Change.
The most common example of an immediate action is a Cancel button. You can make it immediate so that the normal validation and update steps can be skipped, but the action handler can still do whatever is necessary. Typically, the action handler will navigate back to some previous page. In some designs the action handler might also enqueue an informational message like "Transaction cancelled". It is possible to do more: for example, an application might record the fact that the user cancelled the current operation.
rendered. Type: boolean
If selected, the component is to be rendered and processed on any subsequent page submission. If not selected, the component does not appear on the page at all, not even as a hidden component. If you need the component to be hidden but still processed when the page is submitted, deselect the visible property instead of this property.
You can bind this property to a JavaBeans property that determines when the component does get rendered. For example, an airline reservation form might show a component for frequent flyers and not show it for the general public. To bind this property, click the ellipsis button (...) to the right of the property and choose Use Binding in the dialog box.