Tip: Using Global Option User Preferences

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.

{!showblocksicon} (! is a binary negation in Java) is simpler than {showblocksicon ? false : true}.

Yes, this is the neat way and normally I would have put it in the example.

In this particular case, due to the user preference bug mentioned, users who have not ever set or cleared the checkbox will experience boolean evaluation error, hence I treated the property as potentially non-boolean in the GP expression.

This reminds me that I need to test the fix which was released in v3.6.

1 Like

That’s fixed already in one of the 3.6.0 betas.

1 Like