API1 to API2 conversion experience

General
1

As I’ve no development I feel like doing on my app at the minute, I decided it was the time to attempt the conversion. A number of things have cropped up.

Start with two copies of the project. One is for trying things, the other is for applying permanent conversion steps to. I have a number of small windows with only a few controls in each; these converted easily, with no compilation errors, and worked OK when tested. Such steps can then be applied to the clean copy. Having done that, SAVE! This then becomes a new baseline.

Life then gets harder. I had one window with a number of controls; when converted as a whole, some labels lost their alighment (it went back to default), or their text which went back to untitled’. Other items acquired a focus ring they didn’t previously have. All these can be fixed and then a new baseline saved.

Don’t trust Undo: it’s OK to try a conversion, see what problems it gives, perhaps undo the conversion, try converting something else. If that step works OK, apply it to the clean copy. Never Undo a conversion on the clean copy. I must have done this by mistake at some point and ended up with a control set of two radio buttons, which had indices of 6 and 7 rather than 0 and 1. I couldn’t find any way to fix the indices other than by re-creating the control set.

It may be necessary to duplicate some items, having one for API1 and the other for API2, to avoid running into needing cascading changes which run into a brick wall. It may help to convert a small number of individual controls or perhaps just a window itself by editing its super in the inspector. In the latter case you’ll need to reimplement and events which need changing. Open, for example - copy the code in the Open event, add the Opening event to the Window, and paste the code into it. Then delete the Open event handler.

I wanted to convert the main window this way, but had an issue with the Apps main menu bar. I tried converting the menubar but it refuses if there are unconverted windows. And that left it in a state which appeared not to be undo-able.

Remember to compile and run at each stage, and changes that move you forward can then be applied to the clean copy. So far I’m down from over 6000 warnings to around 2600.

5 Likes
2

Thanks Tim, if you can isolate/reproduce any of those, please submit feedback tickets if you have the time.

3 Likes
3

Nothing definite yet, but I had the non (0,1) indices again today and just went into the text file and changed the index values there from (4,5) back to (0,1). Seems to work.

Meanwhile the focus ring re-appeared and some labels reverted to saying Untitled. This latter may be happening at Save time but I can’t say for sure yet.

4

It’s looking like if you convert a window that has a number of items in it, it will look OK after the conversion, but many properties will not then be saved correctly if, as I do, you then save and quit the IDE, and reopen the project.

In one ContainerControl with some rectangles and TextAreas in it, I’ve had the rectangles show up with rounded corners, and the TextAreas with vertical scrollbars when they had none before. When turning off the scrollbar in the IDE, it still shows in the IDE (but no longer in the app).

1 Like
5

What it looks like is happening, is this. I convert a ContainerControl or Window and their contents. I have to fix up a number of property name or method changes, but then, if the change basically works, I save the project and quit the IDE.

Trouble is, at this point, a number of properties such as text alignment, initial text value, corner radius (e.g. for rectangles), border width, vertical scrollbar setting, don’t get saved. Then, when I reopen the project, all these quantities get set to the Desktop defaults for the converted controls. I then fiix them up and that seems to stick.

6

Are you using the convert mechanism or changing each one by hand? Do you get similar results if you simply change the control’s super? Or is there something broken in the convert process?

7

There was such a beast ?

8

Can you make an example? My 4 projects with common code all have so many errors that I couldn’t continue testing. This window makes a nice black-in-black effect which I haven’t seen before:

Screenshot 2021-12-04 at 12.39.26
Screenshot 2021-12-04 at 12.39.262396×1784 311 KB

9

Mostly I’ve been using the convert mechanism. I have a mainwaindow made up of various panes with splitter bars between. You move the splitter bars to change the space allocated to each pane. One large pane is a PagePanel, each panel of which has an instance of a ContainerControl on it. I’m using IMSplitter to provide the splitter bars.

I added code and signatures to IMSplitter so it can handle DesktopControl, DesktopContainer etc as items to resize when the bar is moved (along with existing methods), otheriwse I’d have to migrate everything at once.

The two large ContainerControls I’ve converted so far have followed this pattern:

  1. convert a CC
  2. correct for any methodname/propertyname changes (e.g. invalidate → refresh), also any local vars where I’ve declared them as e.g.: Var myptr as Rectangle
  3. run project, observe it largely looks OK, in particular the CC I’ve just converted
  4. save and quit the IDE
  5. restart tthe IDE, open the project anew.
  6. notice that here is where any of initial text, text alignment, focus ring, vertical scrollbar, border, corner may be wrong in any of the controls within the CC that was converted. Probably for the reason I proposed upthread: they get converted but these properties are somehow not always saved as in step (4) above.

This has also happened for some but not all separate windows I converted all at once.

10

Which project format do you use? Why do you quit the IDE?

11

Xojo Project. In fact that alllowed me to manually fix up some index values for Control Sets. I quit the IDE to ensure as clean a start as possible when I continue conversion.

12

Conversion of Menu items doesn’t always go to plan. I’ve seen reports of QuitMenuItem converting to a stock DesktopMenuItem. I’ve seen also PrefsMenuItem convert to DesktopMenuItem myself. You have to go and change them to DesktopQuitMenuItem or DesktopPreferencesMenuItem to get them working correctly again.

<https://xojo.com/issue/66763> For the Prefs one.

13

I converted a project and rectangles seem to have been converted to rounded rectangles. Image 1 is a version of the project BEFORE conversion and Image 2 is the look AFTER conversion. (Using Update Controls to API 2.0). I am still picking through the project trying to correct – really replace – all the code that used CellBorderBottomAt etc. for ListBox (now DesktopListBox) and BottomRightCorner etc. for Rectangle (now DesktopRectangle). I have not yet worked out how to do this but I am in the early stages of trying to figure this out. I am sort of surprised that Xojo did not provide example code for how to replace the functionality of things like CellBorderBottomAt when they were deprecated and disappeared in the replacement DesktopListBox/Rectangle classes.

Screen Shot 2021-12-04 at 4.48.50 PM
Screen Shot 2021-12-04 at 4.48.50 PM772×1006 68.1 KB

Screen Shot 2021-12-04 at 4.50.02 PM
Screen Shot 2021-12-04 at 4.50.02 PM758×1018 84.6 KB

As I say, it is early days for my attempts to understand how to bring the API 2 version back to the look of API 1, but be forewarned it is not just a magically perfect conversion when you use Update Controls to API 2.0

I am replying to you just because you mentioned getting rounded rectangles unexpectedly.

14

Xojo 2021 v2.1 in the IDE had in the Library: Rectangle and Rounded Rectangle. The Rounded Rectangle had a Corner Height and Corner Width property that was as a default 16. The Rectangle did not have these properties and the corners were sharp angles

Xojo 2021 v3 in the IDE has in the Library ONLY a Rectangle. It has a single property CornerSize and the default value is 16. So when you create a Rectangle on the window, by default that rectangle is what used to be called a Rounded Rectangle and it looks rounded. You can make the corner size property 0 and then it looks like a simple rectangle with angular corners.

It seems that when you convert a project using Update Controls to API 2.0, all your Rectangles are converted to the new version of the Rectangle and given the default rounded rectangle look because their CornerSize is given the default value of 16.

It seems to me to be a peculiar choice by Xojo to do the conversion and take the old Rectangles and make them visually Rounded Rectangles with the default 16 corner size.

Basically, the old Rectangle is a special case of DesktopRectangle with Corner Size = 0. DesktopRectangle is essentially the old Rounded Rectangle.

15

Converting controls from API 1 to the API 2 Desktop controls can be done all at once using the menu item:

Project > Update Controls to API 2.0

Having done this for a small project, I am surprised by how many fundamental changes occur in controls that will cause:

  1. Errors in code which are flagged. This is because various properties for controls have changed and some are no more. Therefore, any code that refers to these properties is now erroneous.

  2. Controls are somewhat different than their predecessors. This makes whole scale conversion somewhat fraught. I am surprised that there is no documentation (that I can find) listing the differences that one can expect to uncover and providing suggested work arounds.

For ListBoxes the new DesktopListBox eliminates the Properties: CellBorderBottomAt etc. Code that relies on these properties is broken (if you convert to DesktopListBox) because the new version does not have these properties or the equivalent perhaps differently worded. You are on your own, apparently, to deal with this in the PaintCellBackground event. It is said to be easy, but I have not tried to deal with this yet, and I cannot find any examples of how to do this.

The previous Rectangle and RoundedRectangle controls have effectively been combined into one: DesktopRectangle. Basically, DesktopRectangle is like RoundRectangle. What used to be just Rectangle is the special case of RoundRectangle with the CornerSize Property equal to zero. The old RoundRectangle actually had two properties CornerHeight and CornerWidth in place of the new single property CornerSize. I had never used different values for CornerHeight and CornerWidth so this change does not affect me much. It is more just like a name change. However, the default value of the CornerSize for a DesktopRectangle is 16 so I have found all my plain rectangles in my project converted to have rounded corners. The solution is just to find all these controls and change their Corner Size to 0 so they will appear as the sharp cornered rectangles that you originally specified.

The old Rectangle had two properties: BottomRightColor and TopLeftColor which allowed you to specify different colors for the border of the rectangle. The old RoundRectangle just had a single property BorderColor. The new DesktopRectangle follows the pattern of the old RoundRectangle: you can only specify a single color. When you use Project > Update Controls to API 2.0 you end up with just the default Black as the color of any Rectangles that you might have had. In my own project, this affected many of my controls because I had taken advantage, for aesthetic reasons, of the ability to specify different colors for the top left and bottom right borders of the Rectangle control.

The take-away for me is that I would be very cautious about using the Project > Update Controls to API 2.0. Particularly in a moderate to large-sized project this could cause you to need to update many lines of code and deal with changes in the appearance of many controls. The above is hardly a complete review of changes that you might expect to encounter. These are just the things I happened to encounter in a small project. It is why I wish we had been proved with a document that provided a complete description of the things we are likely to encounter when doing a wholesale conversion.

The code problems are at least obvious in the sense that the code will not run until they are dealt with. The aesthetic changes might not be noticed until some later time and require a little more caution if they are important. You can on a case by case basis revert controls back to their pre-Desktop deprecated classes so you might not find it to be a big deal. But you have to go back and figure out what were the old property values if it happens that those properties were dropped (BottomRightColor for example). In my experience I just saw that things looked “strange” in the new Desktop Controls version and then I had to just try and figure out why.

1 Like
16

OK - I’m essentially finished. From over 6000 warnings I’m down to 60, which are all in IMSplitter, as I expected would be the case. I left menubars and converting the app itself to last. By the time of converting the last few items I was fairly confident that the process would converge and indeed, the last few were relatively trouble-free.

Having two screens attached to this Mini I kept 2021r2.1 up on one screen with the app version up to 2021r2.1 open. That was handy for comparing the converted control with how it was supposed to be configured, and for copy/pasting chunks of text which didn’t get saved under r3. This happened every time I converted anything.

I strongly recommend following the steps I outlined upthread. Be systematic and don’t change too many things at once. Think out the dependencies and if you have a base class or CC, consider duplicating it and convert the duplicate, then use that in converted items as required until everything that uses that class or CC has been done. Then tidy up by removing the unconverted class/CC and renaming.

1 Like
17

Well, all my TextAreas have a black background after conversion:

<https://xojo.com/issue/66895>: 66895 - All TextAreas have black background after converting to Desktop API 2. Example project is private.

While making an example for the above bug I made the conversion crash:

<https://xojo.com/issue/66894>: 66894 - Unhandled NilObjectException in DesktopConversions.ConvertControlsHelper%A1o%A1oo

The conversion still seems very unfinished.

1 Like
18

DesktopCanvas may loose transparency on picture instances drawn on it. Not sure what causes this yet. Just a note you should really make sure it’s stable for your use.

19

OK, someone help me out here. I’ve been carefully following all the talk here on the forum about API1 to API2 conversion. Here’s my situation:

  1. Using API1 and have developed a number of very successful customer applications (some quite complex) that are currently in use and have put the bread on my table for some years now.

  2. I’ve NEVER had an occasion where I needed something that was not available because of using API1. Either the native Xojo code or MBS and Einhugur have provided every coding solution I’ve ever needed. Neither functionality or performance is an issue in any way.

  3. There’s a half dozen projects now on my active development list that will probably take me the better part of the next 8 - 12 months to complete. Every one of them is VERY similar in nature and needed functionality and appearance to the ones I’ve already done. There is NOTHING new in the customer needs of these programs.

  4. I turned 70 in July and will probably only be keeping my company alive for another few years at most.

So, my question is … Am I missing something? … Why would I want to switch to API2???

Thanks in advance for your thoughts.
… Don

20

I can’t do my coding without autocomplete. My brain retains only one set of instructions. Whatever Add was before, I don’t remember. The docs are bad for API 1 because everything is hidden.

1 Like