uicontrols
Convenience functions that create user interface controls.
textField( [text], [columns], [listener], [spellingChecked] )
textArea( [text], [rows], [columns], [scroll], [spellingChecked] )
codeArea( [text], [preferredWidth], [preferredHeight] )
button( [label], [icon], [listener] )
repeaterButton( [label], [icon], [listener] )
toggleButton( [label], [icon], [selected], [listener] )
radioButton( [label], [selected], [listener] )
buttonGroup( buttons, [settingValues] )
cycleButton( labels, [settingValues] )
checkBox( [label], [selected], [listener] )
comboBox( [items], [listener] )
autocompletionField( items, [sort] )
listControl( [items], [listener], [scroll] )
label( [text], [labelFor] )
noteLabel( [text] )
separator( [vertical] )
hyperlink( [text], url )
helpButton( urlOrWikiPage )
tipButton( text )
spinner( [min], [max], [stepSize], [initialValue], [listener] )
slider( [min], [max], [initialValue], [valueLabelPairs], [listener] )
tintPanel()
portraitPanel( gc, [portraitIndex], [title] )
noMarkup( control )
These functions make it easy to create UI controls to add to a container
layout. See the plug-in authoring kit for examples that use this library.
Returns a new swing.JTextField.
| text | optional initial text for the field (default is an empty string) |
| columns | an optional number of columns for the width of the field (default is 0) |
| listener | an optional function that will be called when enter is pressed in the field (default is no listener) |
| spellingChecked | if true, live spelling checking will be performed on the contents of the field (default is true) |
returns the new text field
Returns a new JTextArea.
| text | optional initial text for the text area (default is an empty string) |
| rows | an optional number of rows for the width of the text area (default is 0) |
| columns | an optional number of columns for the width of the text area (default is 0) |
| scroll | if true, a scroll pane will be wrapped around the text area and returned |
| spellingChecked | if true, live spelling checking will be performed on the contents of the field (default is true) |
returns the new text area, or the scroll pane that contains the text area
if scroll is true
Returns a new script editor control. The code area object
includes an execute() function that will run the script code
contained in the editor.
| text | optional initial text for the code area |
| preferredWidth | an optional preferred width for the control (default is 400) |
| preferredHeight | an optional preferred height for the control (default is 300) |
returns the new code editor
Returns a new swing.JButton.
| label | an optional text label for the button |
| icon | an optional icon for the button |
| listener | an optional function that will be called when the button is pressed |
returns the new button
Returns a new button that continues to send notify the listener at intervals
as long as it is pressed down. The rate of listener notifications
increases the longer the button is held down. The button tracks the modifier
keys that are held down while repeating and passes these through the
ActionEvents that it generates. (For example, the portrait panel
nudge controls jump in bigger steps if Shift is held down.)
| label | an optional text label for the button |
| icon | an optional icon for the button |
| listener | an optional function that will be called when the button is pressed |
returns the new button
Returns a new swing.JToggleButton.
| label | an optional text label for the button |
| icon | an optional icon for the button |
| selected | if true, the box is initially selected |
| listener | an optional function that will be called when the button is pressed |
returns the new button
Returns a new swing.JRadioButton. Radio buttons are use to represent
a group of options of which only one can be selected at a time.
To define the members of such a group, first create the buttons and then
call buttonGroup( arrayOfButtonsToGroup ).
| label | an optional text label for the button |
| selected | if true, the box is initially selected |
| listener | an optional function that will be called when the button is pressed |
returns the new radio button
Returns a new button group for a group of buttons. Button groups are used
to link together a set of related toggle buttons or radio buttons so that
only one button in the group can be selected at a time. The optional
settingValues argument is a list of setting values to associate with
the buttons in the group. If it is supplied, then the returned button group
can be bound using a Bindings instance, and selecting a button
in the group will change the bound setting to the corresponding element
in settingValues. If the settingValues argument is not
supplied, then a plain button group that does not support binding is returned.
| buttons | an array of buttons to be grouped together for mutually exclusive selection |
| values | an optional array of setting values (strings) to map the buttons to |
Returns a new cycle button that will rotate through the specified labels
when pressed. Cycle buttons are suitable for use with a very small number
of options, preferably 2, when the user can easily guess what the
other options in the set are. An example of this is a button to select
a gender. If the optional setting values are provided, they will be used
to map the selected label to and from a setting value when the control
is bound using a Bindings
instance.
| buttons | an array of labels for the button to rotate through when pressed |
| values | an optional array of setting values (strings) to map the labels to |
Returns a new swing.JCheckBox.
| label | an optional text label for the button |
| selected | if true, the box is initially checked |
| listener | an optional function that will be called when the box is checked or unchecked |
returns the new check box
Returns a new swing.JComboBox containing the given list of list.
| items | an array of items for the user to choose from (default is an empty list) |
| listener | an optional listener that is called when the selected item changes |
Create a text field with a drop-down autocompletion list.
| items | an array of items that the field will use to offer autocompletion choices |
| sorted | an optional flag indicating that the item list should be sorted, which allows faster autocompletion |
returns a new, editable swing.JComboBox with autocompletion support
Returns a new swing.JList containing the given list of items.
| items | an array of items for the user to choose from (default is an empty list) |
| listener | an optional listener that is called when the selected item changes |
| scroll | if true, a scroll pane will be wrapped around the list control and returned |
returns the new list control, or the scroll pane that contains the list control
if scroll is true
Returns a new JLabel.
| text | initial label text (default is an empty string) |
| labelFor | the component that this labels; this is used to determine which |
control to activate if the label has a mnemonic key set
returns a new label
Returns a new note label, a label with a smaller than usual
font size that can be used to add remarks, tips, or other
secondary information.
| text | the text of the note label |
returns a new label with a smaller font
Returns a new separator, a dividing line that can be used to
visually separate groups of controls.
| vertical | if true the separator is a vertical line rather than the default horizontal |
returns a new separator
Returns a new hyperlink label.
This is a label with underlined blue text that opens
a URL in the user's default browser when clicked.
| text | an optional text label (default is to use url) |
| url | the URL to visit when the label is clicked |
returns the new hyperlink label
Returns a new help button. A help button displays as a small purple
help icon. When clicked on, it opens a help page in the user's default
browser. If url contains a colon (':') then it is assumed to be a
complete URL for the page to be opened. Otherwise, it is assumed to be the
title of a page in the Strange Eons Wiki.
For example, "User Manual" would open the contents page
of the user manual.
| urlOrWikiPage | the URL or the title of a Wiki page to open when the button is clicked |
returns the new help button
Returns a new tip button. A tip button displays as a small lantern icon.
When the pointer is moved over the icon, a small pop-up window displays
the tip text.
| text | the text to display when the pointer is moved over the tip icon |
returns the new tip button
Creates a new spinner control that can be set to one of
a range of integer values between min and max, inclusive.
Each click of a spinner arrow will add or subtract stepSize
from the current value.
| min | the minimum value that the spinner will allow (default is 1) |
| max | the maximum value that the spinner will allow (default is 10) |
| stepSize | the amount added to the current value by clicking an arrow button (default is 1) |
| initialValue | the initial value stored in the spinner (default is min) |
| listener | an optional listener (swing.event.ChangeListener) that will be called when the value changes |
Creates a new slider control that can be set to one of
a range of integer values between min and max, inclusive.
If valueLabelPairs is supplied, it must be an array where the
even indices are slider positions and the odd indices are labels.
The control will display the requested labels at the indicated positions.
For example: [1, "Low", 6, "Medium", 10, "High"] would display the
labels "Low", "Medium", and "High" at positions 1, 6, and 10 on the slider,
respectively.
| min | the minimum value that the slider will allow (default is 1) |
| max | the maximum value that the slider will allow (default is 10) |
| stepSize | the amount added to the current value by clicking an arrow button (default is 1) |
| valueLabelPairs | an array that associates slider positions with labels |
| listener | an optional listener (swing.event.ChangeListener) that will be called when the value changes |
Creates a new control panel for adjusting tints.
Creates a portrait panel that allows the user to choose and adjust a portrait
image. For DIY components, note that if you use the standard simple method
of adding a portrait, the portrait panel will be created and linked up for you.
If you use the custom portrait handling option, you'll need to create and
add portrait panels yourself.
| gc | the PortraitProvider (usually a game component, such as a DIY) that provides the portrait model |
| portraitIndex | the index of the portrait for a portrait provider with multiple portraits (default is 0) |
| title | an optional title for the panel; if not specified, a localized default |
title will be provided
Calling this function on a UI control will prevent that control from
becoming a markup target. Apply this function to text fields when you
do not want the user to be able to insert text into them using the Markup
menu. The function returns the control, so it can be used transparently
when creating a control:
var field = noMarkup( textField( '42', 4 ) );
| control | the UI control to prevent from accepting markup |
Contents