Ruminations on API 2.0

I took some time this week to really work with API 2.0.  I took a generic ActiveRecord project and converted it to the new API.  It wasn’t long before I found a showstopper bug with DateTime and Introspection (it has since been fixed in a beta).  There were only a thousand or so “Deprecations with Replacement” message so that was just a few hours of work.  Many were duplicates of the same bug (since I use a lot of arrays in ActiveRecord the Append method needs to change to AddRow).  Fairly easy to change if not repetitious.  No big deal, right?

Shorts, our reporting tool, has thousands of immediate ‘deprecations with replacements’ warnings.  And then I got into things like Recordset turning into RowSets and string functions changing.  After 5 hours of working on it I’m still at over 3,000 deprecation warnings.  At this point I just don’t see the point of trying to convert Shorts.  Obviously at some point I will have to but there is no immediate need to do so.

And that’s the problem with flagging all the old API warnings as Deprecations.  It’s kind of silly because there is no immediate need to do so.  It’s just an item marked as deprecated but will be around forever.  So I think it’s silly to call them deprecated in the first place.

Another issue I have with the list is that it’s not grouped in any functional way.  They appear in the list as they’re found by the compiler.  In my ideal world I’d like to work with all the Dates I’m converting to DateTime all at the same time.  Same with RecordSets to RowSets and so on.  The Check Project just doesn’t help when it has thousands and thousands of warnings in random order.

Some changes you can use global search and replace.  The caveat being that if you’ve added a similar method to your class you might kill your project accidentally (i.e. see Shorts above).  The other thing that really makes life hard is string manipulation.  In the old framework strings were 1-based.  In API 2.0 they are 0-based so if you were using String.Inst and checking for zero you now are using String.IndexOf and checking negative one.  There is simply no way you can do a global search and replace for that.  The other one that’s been biting me is the use of Recordset.IDXField that was 1-based.  The replacement is RowSet.ColumnAt is 0-based so that’s another thing you can’t just use global search and replace.

The 2019 R2 IDE added the ability to quickly create a #if block to separate pre-2019 R2 code with new API 2.0 code.  That works well but for large projects that might be a lot of work.  Too much work on any project of any reasonable size.  

In API 2.0 there are a lot of replacement properties and methods.  For the most part these are not a big deal.  However they don’t always make sense.  For example, the TextField and TextArea Text property have been changed to Value.  How does that make using TextFields and TextAreas any ‘easier’ to understand?  TextField1.Text = SomeVariable is perfectly understandable whereas TextField1.Value = SomeVariable is less understandable because now I need to know that I’m talking about a TextField or that SomeVariable is a string.  If you are enforcing your control naming conventions and variable naming conventions it’s not so bad, but still this seems like an unnecessary change.  It makes reading code LESS clear in my opinion.

Since the value type didn’t change (string in this case), I don’t see why this change happened.  I guess one could argue that it makes it more consistent with things like CheckBox.Value but I’d argue that CheckBox.State is the better ‘value’ property since a Checkbox can have three states.  Inconsistencies like that make API 2.0 harder to use in my opinion.

The new Event names in API 2.0 is a big deal.  Nearly every control event has new event names.  But then some like MouseMove, MouseDown, MouseUp didn’t change.  Seriously, if you are going to change the event names for practically everything why not go all out and change everything?  Which begs the question why were some changed and not others?  I digress.

Some changes like Button.Action changing to Button.Pressed actually make some sense.  There was actually confusion from new users on what event to implement.  I can’t tell you how many times I saw a new Xojo user implement the MouseDown event because it looked more promising than Action.

But some new event names are just stupid.  Timer.Action event is replaced with Timer.Run.  WTF was this for?  The Timer has one event and I could argue that “Run” is not an accurate description of what that event means.  The timer isn’t ‘running’, it’s finished running.  Maybe a more appropriate event name would have been “DoYourOneJobNow”.  This begs the question I’ve been saying for years that why do I have to implement the timer event at all?  Rarely have I ever used with without the event.

And sharing code between versions of Xojo is totally borked.  Say, I have a class written with API 1.0 and I implement the Open event and then give it to you.  You’re in 2019 R2, create a subclass of my control, and implement the Opening event (because that’s what you want to use because you don’t want those silly deprecation warnings).  However, when you do this you’ve now kept my Open event from being called.  Thus whatever I had in the Open event is no longer run.  To me this is the most egregious bit about API 2.0.  Me, as a 3rd party Xojo developer can’t control what you’ve implemented.

There are several solutions (probably more) to the events issue.  First, the compiler, in 2019 R2 and above must produce an error if both the old and new events are implemented.  It would require a compiler engineer to move up the chain and see if both old and new events are implemented in the object and then spit out a compiler error that is understandable.  Who on staff could do this?

Another solution is to alias the events so that if someone implements the Opening event it automatically calls the Open event.  One question that’s not answered yet is:  Do we know if API 2.0 events fire in a different order than the old API 1.0 events?

Another solution that I’m pretty sure Xojo will not do is revert the events back to pre-API 2.0 status.  This solves all of the backwards compatibility issues that the Xojo 3rd party developers have with API 2.0.  We can deal with new methods using the #if XojoVersion technique but I don’t see how anything else is going to work and keep everyone happy.  The new API 2.0 properties in pre R2 projects could be hard to deal with so I’m not sure the best way of dealing with those since any flags put in for R2 won’t work in pre-R2.

In general, I think API 2.0 is a hot mess.  You don’t HAVE to upgrade your project to API 2.0 and I highly recommend that you do NOT for the foreseeable future.  I have not migrated any existing clients to R2 and have told clients that do their own development to not upgrade as well.  The API 2.0 saga is not finished by a long shot and it will take a while resolve itself (hopefully).

10 thoughts on “Ruminations on API 2.0

  1. While i don’t see the issue with Timer.Action, maybe ExecuteAction would have been clearer. As you point out run is ambiguous.

    And yes Value everywhere is not very helpful/descriptive.

    I wish they had put more thought upfront into API 2… They needed to do a lot more work up front before starting to code it… a deeper more detailed roadmap than just a short document of high level principles…

    And that document should have been reviewed and feedback gotten from a select group of users… and maybe gone though a few revisions based on teh feedback before any code was written.

    The product is too big and complex IMO for the approach taken to yield optimal results. I just hope this mess will not do too much damage to to the product’s future.

    • Having documentation for the proposed changes was a must. Not doing that violates everything I’ve ever learned as an electrical engineer, software developer, and robotics coach.

      As an engineer I spent a full year creating the user manual for a control system (fueling system for a new airport in Asia) and had to get client approval *before* doing any coding. The beautiful thing was that the coding was easy because I had the ‘manual’ in front of me. Were there changes? Of course, but I knew exactly what 95% of the code was going to be before I started.

      I wish Xojo had used that level of forethought, planning, and review (and community review) before they started coding.

      • IF Xojo were a work for hire I would absolutely expect it.
        Unfortunately its not

        Still some involvement by the community would have been welcome before all this got really rolling.
        But thats never been Xojo’s style to consult with its users beforehand regardless of the shit storms this brings nearly every time there are major changes.

        • The thing is between the the Xojo IDE/navigator, Xojo.framework, API 2 and the lack of significant advancement that improves productivity in many areas of the product for so long, i think many are more fed up than I can remember in the last 18 years.

          • I was an early alpha tester of the Xojo IDE with Navigator. I wrote pages of notes on the specific things I disliked about Xojo. My comments were ignored because I’m not a normal user. Funny, but those were the same things echoed by many people in the community.

            There’s been plenty of comments about iOS over the past couple of years by people actually using it for real projects. Funny, somehow those users are not the target audience.

            Fast forward to today and comments the beta testers put forward about API 2.0 were ignored too. Funny how the beta testers aren’t part of the target audience for Xojo.

            Starting to think it’s not worth my time to report anything since I’m not a valued customer with valid insights.

          • I think outside of how long I have been using the product, I am pretty much a normal user…

            No IT training, never held a job where coding was in the job description etc…

            And I pretty much have always felt the same issues that you have (outside anything to to with source control)… Maybe if one is beta tester they think they are not normal? 😉

            Actually I don’t think usage/profession is what determines it…

            By the company priorities I think new users who are inexperienced in coding altogether, who have not yet bumped into the product limitations, must be what they consider “normal” … Once they have used the product for a few years they become ‘abnormal’! 😉

            – Karen

    • Quite honestly I wondered why you’d been so quiet. The most recent betas would have made you quite apoplectic just like they have for the rest of us now pondering their future use of Xojo.

    • Similarly, I have rewritten code in C++ or C#, and have had increased stability, more functionality with graphics options, less cost, and greater performance.

      I wrote examples in Java and it isn’t an option as it suffers from the same issues with cross-compatibility limited-functionality as other x-platform languages.

  2. I see Geoff Perlman last year at the MBS Conferences in Munich and it was impressive how he on the one hand didn’t let anything show on the very hard criticism at the Developer Panel and on the other hand how he stuck to his point of view. He certainly runs the company, but please don’t let this jewel end in a fatal accident. Please wake up dear Xojo team. Focus on your core competencies, Write once, Compile everywhere, add new controls (Listbox, Datefield) and please take care of the Reporteditor. Often you can’t say more about it than in the last weeks.

    It’s a shame that Thomas Trmpelmann seems to turn his back on Xojo now. He often enough offered to take care of multicore threading.

Comments are closed.