Users will familiar with the module preference panel. It is used to set generic Vassal preferences affecting module behaviour for that user. For example, whether or not the user’s view will centre on another player’s moves.
A module can also define custom preferences - special Global Properties, local to the user, that the module will interpret in a module-specific way.
For example, in the Commands & Colors: Medieval module (v1.7) we find this tab on the Preferences window:
The five settings have been added to the Global Options component. Here is what this looks like in the module editor:
These are all Checkbox preferences - a boolean setting (i.e. true or false). Various other data types are available. A default value can be specified for each type (Caution: Prior to Vassal V3.6, Checkbox preferences are not initialised correctly, until the user specifically inputs a value.)
Here is one of the Checkbox preferences defined in the example module:
Here is an example of where the Checkbox is used in the module; if the user has checked the Show block icons option, a (variable) layer is displayed. If not, no image layer is displayed. Note: This is local to the user; what other users see depends on their own setting of the same checkbox.
This method is appropriate for setting features in the module that are local to the user. If some shared component is affected by a user preference setting, then all users will be affected! This might be appropriate but the module designer will need to structure how the preference affects the module.
Advanced Uses: Setting a preference from within a module
This technique is useful when you wish for users to be able to change their preference settings by a hotkey or button. The changes will take effect for the current module session (i.e. across game open/closes but resetting to the Preferences setting when the module is closed).
To do this, define a Global Key Command that actions a piece to set the user preference. Use the trait “Set Global Property” to set the value for the user preference Global property.
In the above example, the Global Property’s name would be showblocksicon; you might define a button or hotkey to toggle this value. For example, this set global property configuration will toggle the setting:
Extra option: If the user preference is internal to a module, you can exclude it from the user’s view in Preferences by leaving the Preference tab name blank when you define it.
Bear in mind that if your local user preference needs to have a particular value at the start of a game, then you will need to engineer this using a Startup GKC.