Winboard Forum

I was thinking of implementing a "Restore Defaults" button in PG. There are some problems
with it which would also apply to all Winboard engines impementing similar functionality.

The problem is that a Restore Defaults button would change the value of the options ***behind
WB's back***. So the options shown in the engine settings dialog would be out of sync with
the true options that apply. I guess one could pop up a dialog box with "Please restart GUI" but
that is lame. Like Windows asking you to reboot after upgrading Notepad.

So wouldn't it be reasonable if there were a command the engine could send to the GUI
telling it that the value of an option has changed? This could even be the same syntax

option name = value

but now going from the engine to the GUI instead of the other way round.

EDIT: There are of course many other uses for such functionality. Like an engine
showing a combo box with a few preset personalities which set the values
of a number of options simultaneously.

As to your latter example: I think it would be a bad idea to have a combo box select such presets, because the combo-box selection would stay up even when the user would then change some of the settings it affected, so that strictly speaking the choice is no longer in force. It would be better if the engine provided a separate button for each preset (e.g. "Preset Aggressive", "Preset Defensive").

That being said, a new option type (-reset ?) could do the job. It would essentially be the inverse of a -save option, which flushes all options from GUI to engine before sending the button press. With -reset the GUI would clear all options from its memory, and then expect the engine to flush the options to the GUI, i.e. give the same response as to a protover command.

Using option features again to relay current option settings might seem needlessly cumbersome, as they do not only relay settings, but also give the option definitions. But if you think about it, it is also more flexible: It could allow the engine to have different sets of options depending on the "preset" you choose. An engine could hide most of its options, only implementing a "More" button of the -reset type next to a few very basic settings such as BookFile. An once a user would press "More" a host of controls would suddenly open up to him. (Of course it would be sympathetic if a "Less" button was amongst them... ) Polyglot could implement a button "Show / Hide Undesirable Options", etc.

For WB this would be easy to implement, as curently the mechanism for reading feature commands is in fact always active, and any option feature, even when received in the middle of a game, would be added to the list in the normal way. So the only thing I would have to add is the -reset type, treat it as a button everywhere except when it is pressed. Then I should set the number of options to zero for that engine before sending the signal, and close the settings dialog after it. (Perhaps automatically re-opening a new one as soon as a feature done=1 is received.) For the engine it should also be easy, as it can simply call the same code as it uses after receiving protover. (Next to implementing changing the option settings you wanted the button to trigger, e.g. restoring defaults.)

I don't want to do this in 4.4.0, though; as far as I am concerned 4.4.0 is already released, and I don't want to add major, bug-prone changes now. The Engine-Settings dialog is announced as an experimental feature, and the original plan was to not include it at all in 4.4.0. It is clear that a lot will have to be improved on it for 4.4.1. (Real spin controls paying attention to the length of option names while formatting, so they will never be cut short; distinguishing -string, -file and -path options; allowing resizing of the dialog window; add tabs or scroll bars; implement -slider controls...) The -reset option type could be added to that list.

Ok that sounds reasonable.

Repeating the reply to the protover command is of course the most trivial to implement.

I guess the engine should probably send a feature first before enabling this functionality? Or is it just part of the feature/option package?
I am a bit worried that older versions of WB which have an engine setting dialog but no reset functionality would get confused by
the -reset button. Or would they just ignore it?

I will try to implement a "Restore Defaults" button.

GUIs that receive an option feature of a type that is not know to them are advised to ignore the option. (I.e. send "reject option" or perhaps send "reject option NAME". I don't think WinBoard 4.4.0 does this yet. I guess the GUI would have to echo the entire option string, because if there is no recognizable type, it cannot know which pat of it is the name. But it seems desirable to have some indication of what is rejected; it would be very awkward if the enine had to count the accepted and reacted option features.)

So if an engine would implement a "Restore Defaults" -reset option, but the GUI would knot support options of type -reset, the button would never appear in the dialog, and people coud not use it. The engine would not really have to know that the option is rejected; it would simply never get the corresponding option command. So I guess there is no need to enable this by an external feature.

It is probably wise to only require resending of all _option_ features, not the regular features. Although WB does not have a problem with receiving any feature command at other times than starting the engine, or even receiving faetures with conflicting settings (the last one would prevail), there is no guarantee other GUIs would behave that way. And no reason to impose it on them.

So I will change the protocol specs we will release with WB 4.4.0 to include the condition that the GUI must be able to receive option features and done=1 features at any time, and just accumulate them. And add the -reset option type to the list of types, with the specs that use of this option should clear the acucmulated list of options.

I put this in the protocol specs (within the descriptions of the various features) now:

WB protocol specs wrote:feature option (string, see text below)
This feature is used by the engine to define an option command to appear in a GUI menu, so that the user can change the corresponding setting of the engine through the GUI interactively. The string describes the option by defining a name, type, current value and (sometimes) the acceptable value range. Unlike other features, option features are accumulated by the GUI, and the GUI must be able to add a new option to the list at any time, even after having received feature done=1. There are ten different options types, each requiring a slighly different syntax of the defining string:
feature option="NAME -button"
feature option="NAME -save"
feature option="NAME -reset"
feature option="NAME -check VALUE"
feature option="NAME -string VALUE"
feature option="NAME -spin VALUE MIN MAX"
feature option="NAME -combo CHOICE1 /// CHOICE2 ..."
feature option="NAME -slider VALUE MIN MAX"
feature option="NAME -file VALUE"
feature option="NAME -path VALUE"
NAME is an arbitrary alphanumeric string which can contain spaces; the other words in capitals would be replaced by the current (default) setting of the option, (a character string for -string options, a decimal number for -spin and -check options, were the latter uses 1=checked, 0=unchecked), the minimum or maximum value of numeric (-spin) options, or arbitrary text labels (for -combo option). In the latter case, the current value will be preceded by an asterisk. The -file and -path options are similar to -string, but can be used to inform the GUI that the text represents a file name or folder name respectively, so the GUI dialog could add the appropriate browse button to the text-edit field. Similarly, a -slider option is like a -spin, but the GUI might make a different graphical representation for it. A -save option is like a -button, and defines an immediate command to be sent by the engine. With -save the GUI will make sure all current option settings are flushed to the engine before it sends this command. A -reset option is like a -button, but use of it purges the list of options before sending the corresponding option command to the engine. This enables the engine to completely redefine its options or their current settings, by sending a new set of option feature commands to the GUI, terminated by feature done=1.

Does that sound OK?

I also added the blue sentence to the description of how to reject options:

In protocol version 2 or later, each feature F that you set generates the response "accepted F" if the feature is implemented, or "rejected F" if it is not. Thus an engine author can request any feature without having to keep track of which protocol version it was introduced in; you need only check whether the feature is accepted or rejected. This mechanism also makes it possible for a user interface author to implement a subset of a protocol version by rejecting some features that are defined in that version; however, you should realize that engine authors are likely to code for xboard and may not be prepared to have a feature that they depend on be rejected. If the GUI rejects an option feature because of the syntax of the value, it should print the value string with the "rejected" command, e.g. "rejected option nonsense" in response to receiving feature option="nonsense".

It seems reasonable.

Some questions:

Is it always necessary to bracket feature option comands with done=0, done=1? It is not said explicitly.

Is it allowed for the engine to send a feature option command with an option which has already been
defined (to change its value), or can this only in reply to pushing a reset button?

Well, I think the way it is formulated above clearly requires the done=1 after resending the features in response to a -reset option command. As for the start-up features, this is not specified, and I think we should leave the original timeout mechanism in force here. It is up to the engine to make sure it can send all its features before WinBoard times out, if necessary by reserving "infinite time" by done=0. Nice engines always send done=1 at the end, to not prolong a pointless wait by WB for more features, but it is not a strict requirement.

There is no timeout after a -reset option. (The timeout was mainly a kludge to still support protocol v1 engines, and by the time a -reset option is being processed it should be clear that we are dealing withc advanced v2...) The reason I want to require done=1 when the engine is done is to provide the GUI with a clear signal that it can reformat the option dialog. If engines would fail to send it, there would be no automatic reformatting of the dialog, it would just be locked until the user closed it, and he could then reopen it to see the new options (received upto that point).

There is no need to send done=0. It is implied. You are not done after receiving a -reset option command until you send done=1. Locking the GUI until you receive the done=1 would be compliant with protocol, but a bit harsh, and not an implementation I would prefer. Is it really not clear that what I don't say should be sent, should really not be sent? (I mean, there are zillions of other things the engine should not send at this point, like resign commands or birthday congratulations, and it is kind of impossible to mention them all... )

The duplication of option features is not allowed in the current implementation, and you are correct that the current formulation is not clear about that. I will certainly have to address that.

I added this sentence at the end of the option feature paragraph:

(The effect of sending an option feature for an option with the same name as was defined before, without first receiving a -reset option command, is undefined.)