bundle specification of open/save arg UI

[pett]

Our current scheme of registering keywords needs to be expanded somewhat to allow fuller descriptions of the keywords to be registered — for use in graphical interfaces such as the Save dialog. I’m thinking the Save line in setup.py would still allow the keyword:arg-type syntax, in which case the description would default to be the same as the keyword, but also allow keyword:description:arg-type. Other registration interfaces would be similarly expanded, perhaps by allowing (keyword,desciption) wherever it currents allows just keyword. Obviously, the API for retrieving keywords for a format would also need to be enhanced somehow.

[Conrad Huang]

The current core.commands.cli.Annotation class supports two attributes:

name: 'article name, *e.g.*, "an integer"'
url: 'URL for help information'

So the StringArg Annotation subclass has "name" set to "a text string" and no URL.

Is the suggestion that we

(a) support overriding the "name" attribute, or
(b) add a new attribute "description" to the Annotation base class

from the setup.py classifiers?

If (a), there is already a mechanism for supporting Annotation subclasses defined in the bundle module. If XYZArg(Annotation) class is defined in the bundle, it can be used as a keyword argument type "XYZ" in the classifier list in setup.py. Obviously, XYZArg can override "name" and/or "url".

If (b), what is the difference between "name" and "description". And what is the plan for basic types like StringArg?

[pett]

The plan is (b). "Name" is used by "usage" to describe what type of value should be provided for that argument. Seems like "type_description" would be more accurate. "Description" would not be used by commands at all -- as mentioned above, it would be used by GUIs to provide more information about the argument than just the name of the argument. So for instance, mol2 saving adds a 'skip_atoms' arg to the save command, which would be quite cryptic if that's all you got in a GUI. A fuller description could be "Atoms that should be omitted when writing the Mol2 file".

[Greg Couch]

If you want a better error message, you use a custom argument 
annotation.  Annotations come in two flavors, classes and instances.  
For example, if an annotation is an instance, e.g., TupleOf, then it 
should have a "name" keyword argument to override the default value.  
Many other annotations, like StringArg, are classes, and you would have 
to subclass it to change the "name" that is used to describe it.  It 
would be simple to add, for example, a NamedStringArg class whose 
instances would change the name of a StringArg.

[Conrad Huang]

Summary: Eric is saying he wants to (b) add another attribute instead of overriding "name", whereas Greg's response is essentially (a) override "name".

"long_description" below refers to the name of the new proposed attribute that is used only by the GUI. I'm not enamored with the name. Just need something as a placeholder.

Adding a "long_description" attribute is pretty easy. The question is now "how?" The existing mechanism can be used to supply a custom annotation type in the bundle that has the "long_description" attribute. Alternatively, we can make the classifier code smarter to allow for long descriptions in keyword argument data, and create new annotations with "long_description" attributes. The latter is probably easier for the novice developer since the latter only requires extending the open/save classifiers, rather than having to create a subclass in the bundle and change the open/save classifiers to refer to the new class.

An orthogonal question is whether we add "long_description" to all existing annotations, or require GUI code to handle the possibility that the attribute is missing.

Comments?

[pett]

I'm pretty sure replacing 'name' is not correct. As I understand it, 'name' is a description of the legal values of an argument, such a "true or false" for a BoolArg. I am looking for a more user-friendly description of the semantics of an argument, i.e. a better replacement for keyword, not for name. I mean, if you replace name, then the usage command becomes almost unintelligible.

BTW, as per the original description in the ticket, 'description' (why "long_description"?) defaults to the keyword text (with underscores replaced by spaces I would suggest).

The main need for this is for interfaces that are automatically created, such as options added to the open/save commands and then displayed in generic open/save dialogs, which is why I suggested the extension to the syntax of setup.py in the original ticket description. Support in other contexts is far less important, since custom-created interfaces will simply have the information provided by the interface designer.

--Eric

[Tom Goddard]

Ticket retargeted after milestone closed

[pett]

Upon further reflection, automatic generation of an open/save option UI based off the keyword names and types is pretty much intractable even if fuller descriptions are available, because you also need to know the proper initial default values -- which may vary by session state.

Tom G. is working on enhancing the current dialog to at least handle a few more options (like what model to save!), which involves participating bundles to use custom initialization to register information with the main save dialog.

Tentatively, an alternative is to have a BundleAPI method that the dialog could query which would return a Qt widget for the option interface. The widget would also have a 'arg_string' method to get the corresponding argument string based on the current option interface settings.

The whole ball of wax probably merits discussion.

[Conrad Huang]

Per 2019-06-06 Chimera meeting, the plan is to use the manager-provider mechanism to:

• Add save/open-options manager to ui
• Add providers that return functions to build/parse UI elements
• Move image/session saving UI from core to ui
  • I believe we decided against this after finding that core can be a provider source
• Need to make core a possible provider source (Conrad will check first)
  • This was confirmed. You have to edit setup.py.in to add in the providers as classifiers, but it works.

And Eric "volunteered".

[pett]

Now a duplicate of #2079