[chimerax-users] bundle_info.xml API changes

[Eric Pettersen]

As of tomorrow’s daily build, the new way for developers to hook into the open/save commands will be deployed.  What this means...

For Users

There will be “open2” and “save2” commands that use the new mechanism.  The ‘open’ and ’save’ commands will continue to exist and work in the same way they always have, so there is not much reason to try the ‘2’ versions out unless you want to.  The syntax for the ‘2’ versions is identical to the original commands.  One very slight advantage to the ‘2’ versions is that since optional keywords are specific to the file format being opened, in some cases you can type less.  For instance, for the keywords ’structureModel’ (MD coordinates) and ’structureFactors’ (PDB/mmCIF), using ‘open’ you have to type “structure” + a letter, whereas using ‘open2' you can just type “str”.

One thing to note is that the dialogs in the File menu issue the new commands, so if you run into some kind of problem there that seems related to the change, you may have to go to the command line and type the equivalent open/save command.

When we go to ChimeraX 1.0 beta (in approximately 1 month) the old ‘open’ and ’save’ commands will be given the heave-ho and open2/save2 will become open/save.

For Developers

The “For Users” section above has relevant info, so don’t just skip it. :-). As mentioned in previous messages in this thread, the new scheme uses the Manager/Provider bundle_info.xml tags for the bundle to provide the information that the open and save commands need.  The Programmer’s Documentation still refers to the old method in most places and will be revised in the next week or two, but this page:

	http://www.cgl.ucsf.edu/chimerax/docs/devel/tutorials/bundle_info.html <http://www.cgl.ucsf.edu/chimerax/docs/devel/tutorials/bundle_info.html>

goes over the new scheme in detail (use the Table of Contents on the left side to get to the relevant sections).  That page actually won’t have updated information until the builds are made tonight, so any complaints will have to wait until tomorrow. :-). Once it’s available, let me know if anything is unclear.

--Eric

	Eric Pettersen
	UCSF Computer Graphics Lab

> On Feb 6, 2020, at 3:18 PM, Eric Pettersen <pett at cgl.ucsf.edu> wrote:
> 
> Again for the 1 or 2 developers that care…
> 
> Upon actually embarking upon the implementation of these features it became obvious that for practical purposes it would be impossible to offer an overlap period where both schemes would work.  So, instead, at some point these API changes will be deployed into a daily build, and a few days beforehand I will send out a notification here of when exactly when that will happen so you can update your code synchronously if desired.  Still probably a month or two off.
> 
> —Eric
> 
>> On Jan 31, 2020, at 2:48 PM, Eric Pettersen <pett at cgl.ucsf.edu <mailto:pett at cgl.ucsf.edu>> wrote:
>> 
>> Any non-developers feel free to skip this message.  Even for developers, unless you are writing a toolshed bundle that uses the DataFormat, Open, Save, and/or Fetch tags in the bundle’s bundle_info.xml file, you could skip this message.
>> 
>> For the two of you that are left, in anticipation of the the ChimeraX 1.0 release sometime this year we are changing some APIs we are unhappy with.  Namely, the tags in the in bundle_info.xml that I mentioned in the previous paragraph.  As they stand, they are not easily extensible and it is not obvious without looking at the documentation what the various fields do.  On top of that, it is difficult to take the information in those tags and present interfaces for options in ChimeraX’s Open/Save file dialogs.  Also, there is nothing preventing keywords added to the open command by one bundle from conflicting with keywords added by another bundle.
>> 
>> We will be migrating those tags to use bundle_info’s Manager/Provider architecture (described here <https://www.cgl.ucsf.edu/chimerax/docs/devel/tutorials/bundle_info.html>).  Instead of fixed fields, you have keyword/value pairs, which is slightly more self-documenting.  Also, a manager can ask a provider for various things, so in one case the manager can provide a partially processed “open” command along with the “rest of line” for the provider to handle its options, if any, and actually open the file, whereas in another the manager can ask for a widget containing options to show in an open or save dialog.  In brief, the change allows us to solve some issues that looked pretty intractable with the old scheme.
>> 
>> The exact details of the managers and providers supporting these functions are not detailed in that link (just the generic mechanism), but details will be added as implementations are completed.
>> 
>> For convenience, there will some period of time when both the old scheme and new scheme will both work, but we anticipate dropping the old scheme before the 1.0 release.
>> 
>> —Eric
>> 
>> 	Eric Pettersen
>> 	UCSF Computer Graphics Lab
>> 
>> 
>> 
>> _______________________________________________
>> ChimeraX-users mailing list
>> ChimeraX-users at cgl.ucsf.edu <mailto:ChimeraX-users at cgl.ucsf.edu>
>> Manage subscription:
>> http://www.rbvi.ucsf.edu/mailman/listinfo/chimerax-users
> 
> _______________________________________________
> ChimeraX-users mailing list
> ChimeraX-users at cgl.ucsf.edu
> Manage subscription:
> http://www.rbvi.ucsf.edu/mailman/listinfo/chimerax-users

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://plato.cgl.ucsf.edu/pipermail/chimerax-users/attachments/20200331/3d1a532f/attachment.html>