SDK API changes

[mandrav]

OK, so I was thinking of what are the major changes that need to be done before RC3 (which will bring a complete feature-freeze until 1.0 is out).
I 'm talking about major changes regarding the SDK. Specifically, the managers and plugins interfaces.
Not much I could think of. Actually, none.

So I started thinking of what will follow after 1.0 is out. And I discovered quite a few major changes that will have to be done then.
For example, I evaluated wxIFM.
wxIFM is a docking library which is sooo much better than wxDockit (the one we 're using now), except it doesn't handle toolbars (at least not yet).
Evaluating wxIFM made me change some things and found out that it was actually better this way.

One thing was the MessageManager. Currently it is a wxNotebook managing its pages. With wxIFM, each page is a different window managed by wxIFM. So, no more wxNotebook for MessageManager. That's a goot thing actually. We could change this now.

Another thing was the toolbars. As said above, wxIFM doesn't handle toolbars yet. So we would either have to use one big toolbar (like in earlier versions) or make our custom toolbars using wxPanels etc. Anyway this will be left for when that time comes. It's in the application, not in the SDK, so it can change any time. *But* what will need to change is the cbPlugin::BuildToolbar(). Instead of manipulating a wxToolbar directly, it could return an array of a special struct describing each tool to be added.
Then, it makes sense to change cbPlugin::BuildMenu() to work in a similar way...

About the cbPlugin::BuildToolbar() and cbPlugin::BuildMenu() changes, they will have to be performed anyway when we implement the ActionManager we 've been discussing of adding.

So, we have two options:

• Leave the SDK as it is now and change it when needed, after 1.0 is out.

This will of course completely break the SDK but will allow us to reach RC3 soon.

• Make these important changes in the SDK now.

This will allow the SDK to remain consistent before and after 1.0 is out. Of course it will change but changes will be minor and easy to update plugins. If the changes are major (like in option 1) then plugin-devs would have to maintain two versions of their plugins (one for 1.0 and one for post-1.0 releases).
But this option will set us back a while...
[/list]

Which option do you think is better?

[Michael]

So, we have two options:

• Leave the SDK as it is now and change it when needed, after 1.0 is out.

This will of course completely break the SDK but will allow us to reach RC3 soon.

• Make these important changes in the SDK now.

This will allow the SDK to remain consistent before and after 1.0 is out. Of course it will change but changes will be minor and easy to update plugins. If the changes are major (like in option 1) then plugin-devs would have to maintain two versions of their plugins (one for 1.0 and one for post-1.0 releases).
But this option will set us back a while...
[/list]

Which option do you think is better?

IMHO, I think that the second option would be better. Another advantage I see, is that it would be easier for new developers (e.g., of plugins) to get in touch with C::B. If not they would have to learn how plugins are deveoloped now and how they will be later (with the new changes). It is better to keep consistency.

Moreover, I can wait a bit for RC3 . In case of need, I can just compile a SVN version or use an already-compiled-Therion-version.

Best wishes,
Michael

[tiwag]

i think it is better to make these changes now because not soo much plugins are existing by 3rd parties till now.

[Urxae]

IMHO, I think that the second option would be better. Another advantage I see, is that it would be easier for new developers (e.g., of plugins) to get in touch with C::B. If not they would have to learn how plugins are deveoloped now and how they will be later (with the new changes). It is better to keep consistency.

Moreover, I can wait a bit for RC3 . In case of need, I can just compile a SVN version or use an already-compiled-Therion-version.

Took the words right out of my mouth keyboard .

Make the changes now, so any new plugins made to work with version 1.0 won't need a lot of changes to work with post-1.0 builds. I'm likely to keep using the SVN version, so if any interesting new plugins pop up I'd like them to be compatible with that .

[mandrav]

I 'm glad you all think option 2 is better. I think so too, I just didn't state it because I didn't want to bias the discussion.
Btw, if you haven't seen the wxIFM demo, do so. It's amazing

[Michael]

Btw, if you haven't seen the wxIFM demo, do so. It's amazing

Thanks for the wxIFM demo link. Yes, it is really amazing .

Michael

[killerbot]

I also prefer the second option. We are the early adaptors, for us it's no problem. We are svn users ;-)
It was the same with firefox, suddenly all plug-ins break, and the authors have orphaned their plug-ins. This gives a bad user experience. Better to break now, and have everthing nicely up and running at version 1.0, and preferably not break afterwards.

By the way, RC3, I am at RC1508 

And now when can still add some features, yipeeeeee.

Lieven

[killerbot]

wxIFM : yes yes yes !!!!

Haha, M$ DevStud 2005 also has these kind of functionalities, but now CB will have it to.

I need a special smiley/emoticon here (I think in old icq it would say : killerbot is jumping anxiously up and down )

[mandrav]

Regarding wxIFM, here's part of the mail I sent to its author. This contains the showstoppers for us now.

1) Add child as a tab of a specific window.
When adding a child, I can specify if it will be created as a tab (data.m_tabify=true). But can I specify which child this tab will be created in? According to wxIFM's docs, it is created as a tab of the last added child. This is not good at all. As you may know, C::B is quite a dynamic environment using plugins. So the order in which windows are created is not predetermined. For example, a plugin might add a message log panel at any time. But I 'd like it to be added as a tab of the "messages" group of tabs, initially. I don't see how this is possible...

2) Loading/saving the layout.
Equally important for obvious reasons and I 'm really surprised you haven't already implemented it. I mean it's nice to give the end-users the kind of freedom they get using wxIFM in customizing their environment, but it's not worth a cent if next time they launch the app they 're back at square zero
I could start writing such a serialization mechanism, but I 'd like a few pointers on where to start. I see I can get the visibility state for each managed window (btw, it 'd be nice if I could access that list of windows) but I don't see how I could get to the child size, orientation, etc.
Any pointers on that?

[thomas]

Massive changes are best done early. The earlier, the less dependencies that break.

[Urxae]

By the way, is there any particular reason Mandrav and Thomas have such confusingly similar (but not, as I just now noticed, identical) avatars all of a sudden? :shock:
It's a lot easier to follow a conversation when people have unique avatars, and "slightly different" doesn't really count .

[MortenMacFly]

I 'm glad you all think option 2 is better. I think so too, [...]

Allthough I'm not a C::B core dev I would vote the same according to experiences.

Btw, if you haven't seen the wxIFM demo, do so. It's amazing

This is awsome and already looks like C::B somehow... "Build, "Console", "File", "Classes"... :lol:. I personally like to overlay of the docking option a lot. That really looks professional and is very helpful. Never-ever docking to somewhere you didn't want to dock. Cool!

Morten.

[mandrav]

By the way, is there any particular reason Mandrav and Thomas have such confusingly similar (but not, as I just now noticed, identical) avatars all of a sudden? :shock:

They 're from the same artist  :lol:

It's a lot easier to follow a conversation when people have unique avatars, and "slightly different" doesn't really count .

I see your point, actually I got confused now

[tiwag]

.. actually I got confused now

looks a lot better again when not so jumbled  :lol:

[Urxae]

By the way, is there any particular reason Mandrav and Thomas have such confusingly similar (but not, as I just now noticed, identical) avatars all of a sudden? :shock:

They 're from the same artist  :lol:

Yes, that was rather obvious .

It's a lot easier to follow a conversation when people have unique avatars, and "slightly different" doesn't really count .

I see your point, actually I got confused now

Ah, I see you changed yours back. Much better .

[280Z28]

Major versions (the first number in the version) are allowed to change the API from previous major versions. Minor versions are only allowed to make minor changes to the API that should be relatively easy for plugin developers to update their plugins for.

Unfortunately I don't know the SDK that well. One suggestion I have is making the first call to a plugin a request for the SDK version number that was used to program the plugin. Like was the case with the update from Firefox 1.0 to 1.5, plugin developers will have to update what this function returns from release to release, but that is not hard. Most Firefox 1.0 plugins worked in 1.5 by exactly this type of change. Minor versions are also allowed to add new features to the SDK that do not interfere with the already existing SDK. Not interfering is the key to the idea that plugins will probably work after a minor version update, with little to no changes before the code works.

There was the suggestion to move to an entirely new concept for events and event bindings for 2.0. That alone would require all plugins be updated for 2.0. The fulll major version release cycle (dev, beta, RC, final) is designed to work around such requirements and give plenty of time to allow updating to use the new SDK changes.

All that said, the only changes you need to make before RC3 are:
* if you plan to release a minor version between 1.0 and 2.0 (such as 1.1 or 1.5) you will need to make changes now with the understanding that only very small SDK changes (excluding additions) are allowed between minor versions.
* you need a way to verify the SDK version that a plugin is designed to work with so you don't have C::B 2.0 trying to load a 1.0 plugin that clearly won't work. You can implement this with either:
- a function that returns single number (string) of the form "1.0" or "major.minor" that a plugin is designed to work with.
- a function that returns a range of the form "1.0-1.5" that a plugin is designed to work with.
- two functions, one that returns the minimum and one that returns the maximum.

Keep in mind that these functions should never change. A call by any future C::B version to this function will quickly let C::B know whether or not it should try to load the plugin.

There is no obligation to make changes to the SDK that you know will not appear until the 2.0 development cycle. Since we technically are already in RC stage, I suggest holding off on making any such changes now that are not trivial.

If we come out of 1.0 ready to add/change a bunch of things, there is nothing stopping us from starting development on 2.0 immediately, so we won't be hindered by obligations to not change the SDK. Make 2.0 development a branch in the repository so 1.x development can continue with bug fix patches in the trunk, and merge the branch with the trunk when we are ready for 2.0 Beta 1. Before that merge, branch the final trunk version of the 1.x code so any future major bugfixes that it needs can still be made, but for the most part we'll be able to "abandon" it at that point.

[280Z28]

Massive changes are best done early. The earlier, the less dependencies that break.

Massive changes are best done early. Early before the release candidate stage though. Good practice tells that the final release should be identical to the final release candidate. This means we feel that the release candidate is bug-free enough to consider it ready for everyone. Only minor changes should be made before RC3 so it isn't too hard to say "yes, we have checked RC3 for bugs and feel that it is ready to be called 1.0". If we find showstopper bugs, we have to go to RC4 at that point, test them, and then call RC4 final. Andd so on...

[280Z28]

Oh, you should also add a way to let a user know that a new version is available, with the option to notify on all (beta, RC, and final) new releases, or just for new final releases.

You don't need it able to automatically download and install the update, just let them know.

[Michael]

Oh, you should also add a way to let a user know that a new version is available

AFAIK, when a new version is available, it is displayed in the C::B website and a new message is posted in the forum. What would be interesting would be to add a "check updates" option in Settings or Help menu of C::B.

Michael

[thomas]

Ah, I see you changed yours back. Much better .

Bah...

[thomas]

Well, hope nobody complains about the modified version then...

[rickg22]

I vote for making the changes now. *JUST* make a tag before it's actually done, or we could be in big trouble! (read-as: I can't compile CVS with RC2! :lol: )

And yes, If we're gonna make changes to the SDK, better be *before* version 1.0 is released officially. That'll save us from a lot of headaches later.

[tiwag]

Well, hope nobody complains about the modified version then...

just updated ! works fine !!! thanks

[thomas]

Well, hope nobody complains about the modified version then...

just updated ! works fine !!! thanks

Ah, I did not mean that at all   I meant the modified version of Yiannis' avatar which I made. :lol:
But yes, the projects have been updated too

[tiwag]

...Ah, I did not mean that at all   I meant the modified version of Yiannis' avatar which I made. :lol:
But yes, the projects have been updated too

oops  :shock:
thread switching took place only in my mind