COMSOL 6.4 - Form Object

The FormObject class has the following methods:


Name	Syntax	Description
declaration	DataSource declaration(String name)	Returns a form declaration object (Scalar, Array 1D, Array 2D, or ChoiceList) with the specified name.
expanded	void expanded(String form, boolean expanded)	Sets the expanded state of the form when using the sections type.
form	FormList form()	For a CardStack form object, returns the list of local cards.
form	Form form(String name)	For a CardStack form object, returns the local card with the specified name.
getName	String getName()	Returns the name of this form object.
getParentForm	Form getParentForm()	Returns the parent form that contains this form object.
getType	String getType()	Returns the form object type name, as defined in the following sections.
getValue	Value getValue()	Returns the current value of a FormObject when applicable. The method is supported by the following types of FormObjects: input field, toggle button, checkbox, combo box, file import, array input, radio button, selection input, text, list box, table, slider, knob.
hasProperty	boolean hasProperty(String name)	Returns true if there is a modifiable property with the specified name.
item	ItemList item()	For a Toolbar, Graphics, or Table form object, returns the list of user-defined buttons.
item	Item item(String name)	For a Toolbar, Graphics, or Table form object, return the user-defined button with the specified name.
visible	void visible(String form, boolean visible)	Sets the visible state of the form.

Most form objects have one or more of the properties listed in . A form object has a certain property if the corresponding setting is available in the Form Editor. Additional properties are supported for several types of form objects. The general properties that are supported and any additional properties for form objects are listed in the following sections.

Example Code

The following code loops over all buttons and disables them:

for (FormObject formObject : app.form("form1").formObject()) {

if ("Button".equals(formObject.getType())) {

formObject.set("enabled", false);

}

The getType method retrieves the type of form object. In the above example the type of form object is Button and the statement "Button".equals(formObject.getType()) represents a string comparison between the output of the getType method and the string "Button".

For an example of using getValue, see Data Validation.

The following table lists all form object types that can be returned by getType:


Form Object Type
ArrayInput	Hyperlink	SelectionInput
Button	Image	Slider
CardStack	InformationCardStack	Spacer
CheckBox	InputField	Table
ComboBox	Knob	Text
DataDisplay	Line	TextLabel
Equation	ListBox	ToggleButton
FileImport	Log	Toolbar
Form	MessageLog	Unit
FormCollection	ProgressBar	Video
Gauge	RadioButton	WebPage
Graphics	ResultsTable

Array Input


Property	Value	Default	Description
background enabled font fontbold fontitalic fontsize foreground visible			See General Properties.

Example Code

app.form("form1").formObject("arrayinput1").set("enabled", false);

Button


Property	Value	Default	Description
enabled font fontbold fontitalic fontsize foreground visible			See General Properties.
icon	String	""	The button icon. Valid values are images defined in the Images > Libraries node in the Application Builder.
text	String	Generated automatically	The button text. The text must not be an empty string.
tooltip	String	""	The button tooltip text.

In the Form Editor, if a button has its setting set to , it always displays its text property. If the button is , it either displays the icon or the text according to the following rule: if the icon property is empty, the text is displayed, if the icon property is not empty, the icon is displayed.

Example Code

app.form("form1").formObject("button1").set("enabled", false);

Card Stack


Property	Value	Default	Description
enabled visible			See General Properties.

Example Code

app.form("form1").formObject("cardstack1").set("visible", false);

To access objects in a local card, either use shortcuts or use the form method:

app.form("form1").formObject("cardstack1").form("card1")
.formObject("button1").set("enabled", false);

Checkbox


Property	Value	Default	Description
background enabled font fontbold fontitalic fontsize fontunderline foreground visible			See General Properties.
text	String	Generated automatically	The checkbox label text.
tooltip	String	""	The checkbox tooltip text.

Example Code

app.form("form1").formObject("checkbox1").set("tooltip", "tooltip text");

Combo Box


Property	Value	Default	Description
enabled font fontbold fontitalic fontsize foreground visible			See General Properties.

Example Code

app.form("form1").formObject("combobox1").set("foreground", "blue");

Data Display


Property	Value	Default	Description
background enabled font fontbold fontitalic fontsize foreground visible			See General Properties.
exponent	superscript \| E	superscript	When set to superscript, exponents are displayed using superscript font. When set to E, exponents are displayed using the character E followed by the exponent value.
notation	auto \| scientific \| decimal	auto	When the value is scientific, numbers are always displayed using scientific notation. When the value is decimal, numbers are never displayed using scientific notation. When the value is auto, the notation depends on the size of the number.
precision	Integer	4	The number of significant digits that are displayed.
showunit	true \| false	true	Controls if the unit is displayed in addition to numerical values.
tooltip	String	""	The tooltip text.

Example Code

app.form("form1").formObject("datadisplay1")
.setColor("background", 192, 192, 192);

Equation


Property	Value	Default	Description
enabled fontsize foreground visible			See General Properties.
equation	String		The string in LaTeX syntax defining the equation.

Example Code

app.form("form1").formObject("equation1").set("visible", false);

File Import


Property	Value	Default	Description
background enabled font fontbold fontitalic fontsize foreground visible			See General Properties.
buttontext	String	Browse...	Text to display on the button that opens the file browser.
dialogtitle	String	File import	Text to display as dialog title for the file browser dialog. Also displayed as a tooltip for the FileBrowser form object.
filetypes	String[]	{"ALLFILES"}	Defines the list of file types that can be selected in the file browser.

Example Code

app.form("form1").formObject("fileimport1")
.set("filetypes", new String[]{"ALL2DCAD"});

Form

A form used as a subform does not have any modifiable properties.

Form Collection


Property	Value	Default	Description
enabled font fontbold fontitalic fontsize foreground visible			See General Properties.
formvisible	boolean[]	Array with each entry having the value true	Defines the visible state of forms in a form collection.
sectionexpanded	boolean[]	Array with each entry having the value true	Defines the expanded state of forms in a form collection when using the sections type.

To modify the active pane, change the corresponding declaration variable.

Example Code

This line of code changes the font:

app.form("form1").formObject("collection1").set("font", "Arial");

The expanded state of sections in form collections can be controlled by:

app.form("form1").formObject("formcollection1").expanded("form2", false);

The expanded method is only supported by form collections which use sections. The first argument is the tag of the form which is represented by the section. The second argument determines if the sections should be expanded or collapsed.

Graphics


Property	Value	Default	Description
datapick	true \| false	false	If true, data picking is enabled in the graphics form object.
datapicktarget	ProbeFeature \| GraphicsData		Defines where the picked data is stored. Valid values are probe features and GraphicsData declarations.
enabled visible			See General Properties.
source	ModelEntity		Defines the type of model entity (Plot Group, Geometry, Mesh, Explicit Selection or Player Animation) used to plot in the graphics form object.
background2d	String \| RGB (0–255)		Defines the background color of the 2D graphics object. Can be set with a color name (for example, blue, black) or RGB values.
topBackground	String \| RGB (0–255)		Defines the top background color of the graphics object. Can be set with a color name or RGB values.
bottomBackground	String \| RGB (0–255)		Defines the bottom background color of the graphics object. Can be set with a color name or RGB values.
icon	String (image name) \| ""	logo_graphics.png	Defines the icon shown for the graphics form object. Valid values are images from the Libraries>Images node in the application tree, or an empty string for no icon.

Example Code

This line of code displays plot group 5 (pg5) in the graphics object graphics1 in the form with the name Temperature:

app.form("Temperature").formObject("graphics1")
.set("source", model.result("pg5"));

The following line of code using useGraphics is equivalent to the above example:

useGraphics(model.result("pg5"), "Temperature/graphics1");

Either method changes the source of the graphics form object and then plots the contents.

To clear the contents of a graphics object, use:

app.form("Temperature").formObject("graphics1")
.set("source", (ModelEntity) null);

or equivalently

useGraphics(null, "Temperature/graphics1");

The code below displays the mesh in the model tree node mesh1 in the graphics object graphics1 contained in the card of a card stack:

app.form("mesh").formObject("cardstack1").form("card1")
.formObject("graphics1").set("source", model.mesh("mesh1"));

The code below enables data picking for a graphics object and sets the data picking target to a domain point probe:

app.form("form1").formObject("graphics1").set("datapick", true);

app.form("form1").formObject("graphics1").set("datapicktarget",

model.component("comp1").probe("pdom1"));

If a shortcut graphics1 has been created for the graphics object and a shortcut pdom1 has been created for the probe object, the above can be shortened to:

graphics1.set("datapick", true);

graphics1.set("datapicktarget", pdom1);

It is possible to change the color, top color, bottom color, and icon of a form object while the app is running. The syntax for changing these properties is the same as for other color and icon options.

The color properties are named background2d, topBackground, and bottomBackground. Each property can be set either by using a color name string (for example, blue, black) or by specifying RGB values in the range 0-255.

The icon property is named icon. Valid values are images defined in the > node in the application tree, or an empty string ("") to indicate no icon. The default icon is logo_graphics.png. The code below illustrates this:

app.form("form1").formObject("graphics1").set("background2d", "blue");

app.form("form1").formObject("graphics1").set("topBackground", "black");

app.form("form1").formObject("graphics1").set("bottomBackground", "red");

app.form("form1").formObject("graphics1").setColor("background2d", 230, 236, 232);

app.form("form1").formObject("graphics1").set("icon", "compute_32.png");

Hyperlink


Property	Value	Default	Description
background enabled font fontbold fontitalic fontsize visible			See General Properties.
text	String	Generated automatically	The text to display on the HyperLink form object.
url	String	""	The URL to open when the HyperLink is activated.

Example Code

with (app.form("form1").formObject("hyperlink1"));

set("text", "COMSOL");

set("url", "www.comsol.com");

endwith();

Image


Property	Value	Default	Description
enabled visible			See General Properties.
icon	String	cube_large.png	Defines the icon name to display in the Image form object. Valid values are images defined in the Images > Libraries node in the Application Builder.

Example Code

app.form("form1").formObject("image1").set("icon", "compute.png");

Information Card Stack


Property	Value	Default	Description
background enabled font fontbold fontitalic fontsize fontunderline visible			See General Properties.

Example Code

app.form("form1").formObject("infocard1").set("fontunderline", true);

Input Field


Property	Value	Default	Description
background enabled font fontbold fontitalic fontsize foreground visible			See General Properties.
editable	true \| false	true	If true then the text in the input field can be edited by the user.
exponent	superscript \| E	superscript	When set to superscript, exponents are displayed using superscript font. When set to E, exponents are displayed using the character E followed by the exponent value.
inputformatting	on \| off	off	If the value is on, then numerical values in the input field are formatted according to the exponent, notation, and precision properties. When the user is editing the text in the input field, the formatting is temporarily disabled so that the original text can be edited.
maxdouble	double	1000	The maximum allowed double value. This property is only accessible when the Filter setting is set to Double and the corresponding checkbox is enabled in the Data Validation section.
mindouble	double	0	The minimum allowed double value. This property is only accessible when the Filter setting is set to Double and the corresponding checkbox is enabled in the Data Validation section.
maxinteger	Integer	1000	The maximum allowed integer value. This property is only accessible when the Filter setting is set to Integer and the corresponding checkbox is enabled in the Data Validation section.
mininteger	Integer	0	The minimum allowed integer value. This property is only accessible when the Filter setting is set to Integer and the corresponding checkbox is enabled in the Data Validation section.
notation	auto \| scientific \| decimal	auto	When the value is scientific, numbers are always displayed using scientific notation. When the value is decimal, numbers are never displayed using scientific notation. When the value is auto, the notation depends on the size of the number.
precision	Integer	4	The number of significant digits displayed.
tooltip	String	""	The tooltip displayed when the mouse pointer is located over the input field.

Example Code

app.form("form1").formObject("inputfield1").set("precision", 6);

Line


Property	Value	Default	Description
enabled font fontbold fontitalic fontsize foreground visible			See General Properties.
text	String	""	Text to display on the line. The text is only displayed for horizontal lines that have Include divider text enabled in the Line object Settings window.
thickness	Integer	1	The line thickness.
linecolor	String	default	The line color.

Example Code

app.form("form1").formObject("line1").set("text", "divider text");

app.form("form1").formObject("line1").set("thickness", 10);

app.form("form1").formObject("line1").set("linecolor", blue);

List Box


Property	Value	Default	Description
enabled font fontbold fontitalic fontsize foreground visible			See General Properties.

Example Code

app.form("form1").formObject("listbox1").set("foreground", "red");

To change the list box contents, modify the corresponding choice list:

app.declaration("choicelist1").appendListRow("new value", "new name");

Log


Property	Value	Default	Description
background enabled font fontbold fontitalic fontsize foreground visible			See General Properties.

Example Code

app.form("form1").formObject("log1").set("fontsize", "20");

Message Log


Property	Value	Default	Description
background enabled font fontbold fontitalic fontsize foreground visible			See General Properties.

Example Code

app.form("form1").formObject("messages1").set("background", "gray");

Progress Bar


Property	Value	Default	Description
enabled visible			See General Properties.

To create and update progress information see Progress Methods.

Example Code

app.form("form1").formObject("progressbar1").set("visible", false);

Radio Button


Property	Value	Default	Description
background enabled font fontbold fontitalic fontsize fontunderline foreground visible			See General Properties.

To change the display name for a radio button, modify the value in the corresponding choice list.

For a choice list that is used by a radio button, it is not possible to change the value of any row, or to add or remove rows. Only the display name can be changed.

Example Code

app.form("form1").formObject("radiobutton1").set("fontitalic", true);

app.declaration("choicelist1").setDisplayName("new name", 0);

Results Table


Property	Value	Default	Description
enabled font fontbold fontitalic fontsize foreground visible			See General Properties.
source	TableFeature		Set the contents of the results table.

To change the contents of the results table use the method useResultsTable or evaluateToResultsTable. See also GUI-Related Methods.

Example Code

app.form("form1").formObject("resultstable1").set("visible", true);

app.form("form1").formObject("resultstable1").set("source",

model.result().table("tbl2"));

useResultsTable(model.result().table("tbl2"), "/form1/resultstable1");

Selection Input


Property	Value	Default	Description
active	true \| false	false	The active property controls whether the Selection Input is active. Changing the property value selects or deselects the Activate Selection button in the Selection Input.
background enabled font fontbold fontitalic fontsize foreground visible			See General Properties.
graphics	FormObject		Defines the graphics form object to use when the selection form object is active.
source	SelectionFeature		Defines the model selection the selection form object is connected to.

Example Code

app.form("form1").formObject("selectioninput1").set("graphics", "graphics1");

Alternatively, if there are shortcuts sel1 and g1 to the selectioninput1 and graphics1 form objects:

sel1.set("graphics", g1);

To change the model selection, assuming sel1 is a shortcut to the selection input form object:

sel1.set("source", model.selection("sel2"));

Slider


Property	Value	Default	Description
enabled visible			See General Properties.
max	Double	1	The largest possible slider value.
min	Double	0	The smallest possible slider value.
steps	Integer	5	The number of steps between the min and max values. The number of tick marks is one more than the number of steps.
tooltip	String	""	The tooltip text.

The min value is allowed to be larger than the max value, in which case the slider behaves as if the values were swapped. The smallest value always corresponds to the left side of the slider.

Example Code

app.form("form1").formObject("slider1").set("min", 1);

app.form("form1").formObject("slider1").set("max", 12);

app.form("form1").formObject("slider1").set("steps", 11);

Knob


Property	Value	Default	Description
background enabled font fontbold fontitalic fontsize foreground visible			See General Properties.
exponent	superscript \| E	superscript	When set to superscript, exponents are displayed using superscript font. When set to E, exponents are displayed using the character E followed by the exponent value.
knobmaincolor	String	default	The main background color.
knobradius	Integer		When knobradiusmanual has the value on, this is the value of the knob. The tick marks appear outside this radius.
knobradiusmanual	on \| off	off	When the value is off the radius is calculated automatically. When the value is on, the radius is given by the knobradius property.
knobsecondarycolor	String	default	The secondary background color.
labelformatting	true \| false	false	When true this setting enables custom label formatting.
max	Double	1	The largest possible knob value.
min	Double	0	The smallest possible knob value.
mouse	distance \| vertical \| circular	distance	The kind of mouse movement to change the knob value. When set to distance, the distance the mouse is moved, either horizontally or vertically, controls the value. When set to vertical, only the vertical distance the mouse is moved controls the value. When set to circular, the value is changed using a circular motion.
needlecolor	String	default	The color of the knob’s needle.
notation	auto \| scientific \| decimal	auto	When the value is scientific, numbers are always displayed using scientific notation. When the value is decimal, numbers are never displayed using scientific notation. When the value is auto, the notation depends on the size of the number.
precision	Integer	4	The number of significant digits that are displayed.
scale	none \| marks \| markslabels \| marksalllabels	marks	To control whether the scale should have tick marks or labels. When set to none, the knob has no tick marks or labels. When set to marks, the knob has tick marks but no labels. When set to markslabels, the knob has tick marks and labels for the minimum and maximum values. When set to marksalllabels, the knob has ticks marks and all major ticks has a label.
steps	Integer	5	The number of steps between the min and max values. The number of tick marks is one more than the number of steps.
tooltip	String	""	The tooltip text.

Example Code

app.form("form1").formObject("knob1").set("min", 1);

app.form("form1").formObject("knob1").set("max", 12);

app.form("form1").formObject("knob1").set("steps", 11);

Spacer

A spacer object does not have any modifiable properties.

Table


Property	Value	Default	Description
enabled font fontbold fontitalic fontsize foreground visible			See General Properties.
headers	String[]	Generated automatically	Column headers.
showheaders	boolean	Generated automatically	Show column headers.

To change the contents of the table, change the declaration variables or model entities the table is displaying.

Example Code

app.form("form1").formObject("table1").set("enabled", false);

Text


Property	Value	Default	Description
background enabled font fontbold fontitalic fontsize foreground visible			See General Properties.
editable	on \| off	off	If the value is on, the text can be edited by the user of the application. If the value is off, the text can only be changed programmatically.
textalign	left \| center \| right	left	Defines how the text is aligned within the text area.
wrap	on \| off	on	If the value is on, word wrapping is used to break lines that are too long to fit within the text area. If the value is off, long lines may not be completely visible.

Example Code

app.form("form1").formObject("text1").set("textalign", "center");

Text Label


Property	Value	Default	Description
background enabled font fontbold fontitalic fontsize fontunderline foreground visible			See General Properties.
text	String	Generated automatically	The text to display in the label when the label is not in multiline mode.
textmulti	String	Generated automatically	The text to display in the label when the label is in multiline mode.

Example Code

app.form("form1").formObject("textlabel1").set("text", "custom text");

Toggle Button


Property	Value	Default	Description
enabled font fontbold fontitalic fontsize foreground visible			See General Properties.
icon	String	""	The button icon. Valid values are images defined in the Images > Libraries node in the Application Builder.
text	String	Generated automatically	The button text. The text must not be an empty string.
tooltip	String	""	The button tooltip text.

A button with size large always displays the text, a button with size small displays either the icon or the text. If the icon property is empty, the text is displayed. If the icon property is not empty, the icon is displayed.

Example Code

app.form("form1").formObject("togglebutton1").set("icon", "about_information.png");

Toolbar


Property	Value	Default	Description
background enabled font fontbold fontitalic fontsize foreground visible			See General Properties.

Example Code

app.form("form1").formObject("toolbar1").set("background", "gray");

Unit


Property	Value	Default	Description
background enabled font fontbold fontitalic fontsize foreground visible			See General Properties.

Example Code

app.form("form1").formObject("unit1").set("visible", false);

Video


Property	Value	Default	Description
visible			See General Properties.

Example Code

app.form("form1").formObject("video1").set("visible", false);

Web Page


Property	Value	Default	Description
file	String		The file to display. File scheme syntax is supported.
html	String	<html></html>	The HTML code to display.
report	ReportFeature or String		The report feature to display.
type	page \| url \| type \| report	page	Determines which property is used to specify the browser display contents.
url	String	www.comsol.com	The URL to display.
visible			See General Properties.