StarUML documentation
Search…
v3
User Guide
Working with Diagrams
Defining Preferences
In this chapter, we're going to learn how to define preferences. When you developing your own extensions, you may want to allow users to make preferred settings.
To define your own preferences, use
app.preferences.Defining preference schema
Before we get in detail, it's better to take a look at an example. Following is a part of preference schema of Java extension.
1
var javaPreferences = {
2
id: "java",
3
name: "Java",
4
schema: {
5
"java.gen": {
6
text: "Java Code Generation",
7
type: "section"
8
},
9
"java.gen.useTab": {
10
text: "Use Tab",
11
description: "Use Tab for indentation instead of spaces.",
12
type: "check",
13
default: false
14
},
15
"java.gen.indentSpaces": {
16
text: "Indent Spaces",
17
description: "Number of spaces for indentation.",
18
type: "number",
19
default: 4
20
},
21
...
22
}
23
}
24
...
25
app.preferences.register(javaPreferences)
Copied!
This preference schema will be shown in Preferences Dialog as the below image.
PreferenceDialog
As shown in the above example, a preference schema have a unique ID, name, and a set of preference items. You can register a preference schema by
app.preferences.register function.A preference item should have the following properties.
- key : Unique identifier of preference item. It should be unique in all of the preference schemas, so it's strongly recommend to include all the IDs of preference schema and section (e.g.
java.gen.useTab,java.gen.indentSpaces). - text : Name of preference item. It will be shown in Preferences Dialog instead of
key. - description : Short description of preference item.
- type : Type of preference item. Available types will be described later.
- default : Default value of preference item.
- width (optional) : Width of widget for preference item in Preferences Dialog.
- options (optional) : Options users can select one of. This property is mandatory for
ComboorDropdownpreference items. This property should be defined as an array of objects having two fields:valueandtext. (e.g.[ { value: 0, text: "female" }, { value: 1, text: "male" } ])
Available types of preference item are as follow.
- section : Just for grouping preference items, so it has no actual preference value.
- string : Allows users can edit a text (a string value).
- check : Allows users can check or uncheck (a boolean value).
- number : Allows users can edit a number value (an integer value).
- combo : Allows users can edit or select a value from the defined options.
- dropdown : Allows users can select from the defined options.
- color : Allows users can select a color value. This type of preference item allow to set
defaultproperty value tonull. It means nothing selected. Additionally, allow to definedefaultButtonproperty like asdefaultButton: { text: "Use Default Color" }. When it defined, a button is shown in front of color widget in Preferences Dialog and changes to default color when it pressed.
Reading preference values
You can read value of a particular preference item by calling
get function with key of the preference item. It returns user selected value or default value. If passed undefined key, it returns null value.1
app.preferences.get("java.gen.useTab") // false
2
app.preferences.get("java.gen.indentSpaces") // 4
3
app.preferences.get("java.gen.undefined-item") // null
Copied!
Writing preference values
You can also write value for a particular preference item by calling
set function with key and value. Note that you have to pass value of correct type conform to the type of preference item. For example, do not pass string value to a preference item of check type.1
app.preferences.set("java.gen.useTab", true)
2
app.preferences.set("java.gen.indentSpaces", 2)
3
app.preferences.get("java.gen.useTab") // true
4
app.preferences.get("java.gen.indentSpaces") // 2
Copied!