xw:ask,
xw:clear-all,
xw:create-<kind>,
xw:export,
xw:get,
xw:import,
xw:<kinds>,
xw:of,
xw:on-<property>-change,
xw:<property>,
xw:remove,
xw:select-tab,
xw:set,
xw:set-<property>,
xw:widgets,
xw:with
- xw:ask widget-key [ commands ]
- xw:ask widget-keys [ commands ]
Asks one widget (identified by widget-key) or many widgets (identified by a list of widget-keys) to run some commands. The commands are run in the context of each given widget.
xw:clear-all
Removes all tabs and all widgets on them. As it stands now, this is the equivalent of foreach xw:tabs xw:remove, but xw:clear-all is shorter and makes the intent clearer. It could also potentially do more in the future (if containers other than tabs were added to the extension, for example).
Note that NetLogo's clear-all command does not clear the extra widgets and tabs.
- xw:create-<kind> widget-key
- xw:create-<kind> widget-key [ commands ]
Creates a widget of the specified kind. It can be one the widget kinds bundled with the extension or a widget kind potentially developed by a third party.
The widget-key must be unique across all widget and tab keys. (You should usually call xw:clear-all before creating your interface.)
If commands are provided, they will be run in the context of the newly created widget.
By default, all new widgets are placed on the last created tab. If you want the widget to appear on a different tab, you need to explicitly set its tab property:
xw:create-tab "t1"
xw:create-tab "t2" ; "t2" is the last created tab
xw:create-slider "s1" [
xw:set-tab "t1" ; without this line, "s1" would go on "t2"
]
- xw:export filename
Exports the all properties of all extra tabs and widgets to a JSON formatted text file that can later be re-imported with xw:import.
Using xw:export and looking at the content of the file is a good way to see all your widgets and the value of their properties, especially if you use a JSON pretty printer (like this one, for example).
Note that some types of values (agents, anonymous procedures and extension objects, namely) can only be exported as strings. If you try to import them back, you won't get the original object back. As of now, items in a chooser of multi-chooser are the only things that can potentially cause this problem.
- xw:get widget-key
Reports the value of the default property for the widget identified by the string widget-key.
The default property can be different (or even undefined) from one widget kind to another, but it is usually the one that you would consider to be the "value" of the widget, i.e. value for a slider, selected-item for a chooser, selected? for a checkbox, etc. Please refer to the widget kinds bundled with the extension to learn about their default properties.
Note that, unlike the xw:<property> getter primitives, xw:get does not operate in a widget context (which is why you need to specify a widget-key).
- xw:import filename
Loads the content of an interface saved with xw:export. You can use xw:import to import multiple interfaces in the same model. You just need to make sure that all widget and tab keys are unique.
Example:
xw:create-tab "t1"
xw:export "t1.json"
xw:clear-all
xw:create-tab "t2"
xw:export "t2.json"
xw:clear-all
xw:import "t1.json"
xw:import "t2.json"
print xw:tabs ; will print: ["t1" "t2"]
- xw:<kinds>
Reports the list of keys of all widgets of the specified kind (where <kinds> is the plural form of the desired kind, e.g.: xw:tabs, xw:buttons, xw:checkboxes, etc.)
Widgets keys are listed in alphabetical order.
- [ reporter ] xw:of widget-key
- [ reporter ] xw:of widget-keys
Reports the value of the reporter for one widget (identified by widget-key), or a list of values for many widgets (identified by a list of widget-keys). The reporter is run in the context of each given widget.
- xw:on-<property>-change command
Registers an event listener on <property>: each time the value of property changes, command gets executed, with the new value as an argument to the command. (Note that xw:<property> may have changed again by the time the event listener fires, thus the need for the command argument.) The command is executed in the context of the widget whose property just changed.
Example:
xw:create-chooser "c1" [
xw:set-items base-colors
xw:on-selected-item-change [ xw:set-color ? ]
]
- xw:<property>
Reports the value of <property> for the current widget context.
You will typically use this in the reporter block of xw:of:
print [ xw:color ] xw:of xw:widgets
or xw:with:
print xw:widgets xw:with [ xw:color = red ]
but sometimes also in the command blocks of xw:ask:
xw:create-slider "population" [ xw:set-label xw:key ]
or xw:create-<kind>:
xw:ask xw:widgets [ xw:set-width xw:height * 5 ]
It is an error to use xw:<property> in the context of a widget that does not support this particular property. Please refer to [[Kinds]] and [[Properties]] pages to learn all about the properties supported by different widget kinds.
- xw:remove widget-key
Removes the tab or widget identified by widget-key.
If xw:remove is used on a tab, all the widgets on that tab are removed as well.
If you want to remove multiple widgets at once, you can use this primitive in combination with foreach. For example, to remove all widgets, but keep the tabs:
foreach xw:widgets xw:remove
- xw:select-tab tab-key
- xw:select-tab tab-index
Gives the focus to the specified tab (just like if the user had clicked on the title of the tab).
If you want to select one of the extra tabs that you have created, you can use the tab's key:
xw:create-tab "my-tab"
xw:select-tab "my-tab"
If you want to select regular NetLogo tabs, you can do it by using their "tab index", which is basically the order that they appear on the screen, starting at 1. You can look at NetLogo's Tabs menu to see the index that you need to use: it is the same as the one you use in combination with the Ctrl key to active a tab. For example, before creating an extra tab: Ctrl+1 for the Interface tab, Ctrl+2 for the Info tab and Ctrl+3 for the Code tab. Keep in mind that the extension inserts extra tabs after the Interface tab, but before the info and code tabs, so these numbers can change.
A common use would be to select an extra tab on startup and go back to the main interface tab on setup:
extensions [xw]
to startup
xw:create-tab "my-tab"
xw:create-button "setup" [
xw:set-label "Setup"
xw:set-commands "setup"
]
; normally, you'd create a bunch of other widgets...
xw:select-tab 2 ; select "my-tab"
end
to setup
clear-all
; here, you'd initialize your model using values from extra widgets
xw:select-tab 1 ; go back to main interface
end
- xw:set widget-key value
Sets the value of the default property for the widget identified by the string widget-key to value.
The default property can be different (or even undefined) from one widget kind to another, but it is usually the one that you would consider to be the "value" of the widget, i.e. value for a slider, selected-item for a chooser, selected? for a checkbox, etc. Please refer to the widget kinds bundled with the extension to learn about their default properties.
Note that, unlike the xw:set-<property> setter primitives, xw:set does not operate in a widget context (which is why you need to specify a widget-key).
- xw:set-<property> value
Sets the value of <property> for the current widget context.
You will typically use this the command blocks of xw:create-<kind>:
xw:create-tab "black-tab" [
xw:set-title "Black Tab"
xw:set-color black
]
foreach n-values 10 [ ? ] [
xw:create-note (word ?) [
xw:set-text (word ?)
xw:set-y 10 + ? * 35
xw:set-opaque? true
]
]
Or xw:ask:
xw:ask xw:notes [
xw:set-color one-of base-colors - 4
xw:set-font-color xw:color + 6
]
It is an error to use xw:set-<property> in the context of a widget that does not support this particular property. Please refer to [[Kinds]] and [[Properties]] pages to learn all about the properties supported by different widget kinds.
xw:widgets
Similar to xw:<kinds>, but reports a list of all widget keys (i.e., excluding tabs).
Widgets keys are listed in alphabetical order.
- widget-keys xw:with [ reporter ]
Reports the filtered list of widget-keys for which reporter is true when run in the context of each given widget.
Example:
xw:create-tab "t1"
; create 10 sliders:
foreach n-values 10 [ ? ] xw:create-slider
; make 5 of them red:
xw:ask n-of 5 xw:sliders [ xw:set-color red ]
; print the keys of the 5 red sliders:
print xw:sliders xw:with [ xw:color = red ]