Xojo Documentation is useless

I don’t want to describe it so strictly, but I also think that the documentation in its current form is the most confusing documentation that Xojo has offered so far.

I am also very dissatisfied with it. Luckily I’ve been around long enough to be able to help myself otherwise.

6 Likes

I am an experienced dev but new to Xojo. So far I have found the documentation adequate. I would like to see more depth of explanation, for example, from the name I would guess that the Opening event would fire once sometime after the control constructor and presumably when the control is first displayed. But the docs do not really explain to me the order of events in the event model. For example if Opening fires not on first display but is more of an iterated post-constructor initializer, then it has implications for performance in some scenarios and I’d like to keep that in mind. I’ll figure this out by trial and error as I build out my first app.

There doesn’t seem to be a true visual container model, or at least some things I would expect to be a container, are not. For example I am creating tabbed interface and would expect the DesktopTabPanel to be a container for controls on each tab so that I don’t have name collisions to worry about. It is not. Instead, each control is individually associated with a tab by its ordinal index. I take a dim view of this because any code referencing a tab index will break if I later rearrange tabs or add tabs (and I will) and I have to worry about unique-izing (and complicating) control names per tab.

So it would be nice if there is a help topic (that I can find) discussing the overall design philosophy and best practices around issues like this.

Overall though, the documentation is … adequate. I’m generally impressed with the product and while (as is inevitable) some design decisions weren’t taken as I would have, I have found no roadblocks or smoking guns as yet. Some of my remarks above are subject to withdrawal as I figure out where things are in the docs; doubtless I’m missing things.

I agree that the OP is needlessly carping. One always is a bit lost on a new platform. Not sure what they are expecting!

2 Likes

@Bob_Grommes The ContainerControl is your ticket to the container model you are seeking. It can be put in the Window or inside a Tab Panel, Page Panel, Dialog, etc of a Desktop Application so that you don’t have name collisions to worry about.

2 Likes

This, IMO, is a very important point. My large (1000 pages) javascript books have a whole chapter describing the event model (both of them), how events propagate and how to stop them propagating. It would be helpful to have something similar for Xojo.

2 Likes

You should never rely on a specific order between events. It may change, which would break your code.

Each event handler should be self contained.

If you want code to execute in a given order, use timers instead.

Thanks for this – I will check it out :slight_smile:

1 Like

Unique naming of controls by tab, yes, but adding, or changing the order of tabs will not cause an issue. IDE takes care of that kind of thing

-karen

1 Like

Hum, I would say yes and no. For example during the creation of a Window for example, if one tries to manipulate a Control that has not been created yet will yield to problems. Then it’s important to know the order of events when a Window is created. A beginner may gest lost easily with this, but once you have enough knowledge, if you create some code that will run too early, you find out real fast what’s wrong.

Having a tree of the events order is a nice thing. The answers can be all over the documentation, but having it all in a single graphic is worth a thousand words.

Here you can find an example that lists the order of events:

https://www.mbsplugins.de/archive/2021-10-03/The_order_of_events_in_Xojo

Indeed, Opening will happen only after each control Opening event.

So trying to access another control from a control Opening event can be dangerous. However, addressing a window controls from the window Opening control is safe.

My statement stands: each event handler should be self contained. Which means not trying to manipulate other controls.

I am not really interested in making events fire in some order or relying on them firing in some order so much as just understanding how the event model works, and things like whether an event always fires once or not, etc. WRT the Opening event the docs essentially say it fires when the control is opening, which is not really helpful. Also it’s an odd name choice, in other frameworks this kind of thing is typically something like OnOpen – or since one does not conceptually “open” a control it should probably be something more like OnInit depending on what gives the best sense of what fires the event. But that is just whining at this point, it is what it is now so just something similar to what you get when you Google “order of events windows forms” or similar pages for WPF or ASP.NET or whatever.

From what I can tell Opening was an attempt to be polymorphic between App, main window and control events but the semantics don’t hold up. Also it appears to be more a place to put code after the constructor is done but before the control is rendered and the open question for me is whether all controls have this event fired the first time the control is visible to the user or entirely in advance. From what I can gather from old posts, Opening fires first on the App, then on each control in a window, then on the window itself. After that, event order is indeterminate, particularly between platforms.

In my initial app where I have a few tabs each with various controls, if I populate the controls in Opening() then I’m guessing the whole show is held up over needlessly running queries and loading controls on all tabs when all that’s needed is for those things to happen only for the initial tab on startup and then when each tab is selected by the user the first time. So … I probably need to move that to the Pressed() event of the relevant tab.

It’s all good, this is just a matter of orienting to the best way to do things in this particular framework, figuring out exactly what happens when. I expect on my first go-round to have some false starts.

Yes. And I still want to know which events propagate up the hierachy if not handled and which don’t. And how that may be influenced. Essentially as I said upthread.

The previous name of Opening was Open. I don’t know the ins and outs of the reasons behind the renaming, but I was told it was meant to express the fact that the event was happening upon the opening of the control/window. For all intents and purposes, it does the very same thing as onOpen in JavaScript, for instance.

Indeed, Opening means the control has been constructed and is fully accessible.

In terms of a window containing controls, for instance, each control Opening event will fire as it is finished to be constructed. Then when all the controls are finished constructing, the window Opening event will fire.

If you populate existing controls with data in the window Opening event handler, it is safe, because you are sure all controls exist. If, however, you instantiate new controls in Opening, it will take time to have them created and attached to the tab. In general, it is probably best to design the UI in the IDE.

In general, I would recommend not to overintellectualize the design. Just go ahead, design the UI, and attach event handlers. Most of the time, it works as is.

2 Likes

I Agree totally the new documentation is not comprehensive for a normal human, the example of code is insufisant…
I use the old documentation for more understanding

https://docs.xojo.com/index.php/

1 Like

I do that too when I use my m1 MacBook Pro…

I am noticing that editing of the docs is incomplete. For example it looks as if the database object docs were written for SqlLite and then copied to, e.g., PostgreSQLDatabase and then not thoroughly edited for the differences. So in places you have code examples that would work in SqlLite but not in Postgres (Uses ? rather than ?1 for the first argument placeholder, etc). Sometimes the code comments in the sample even mention SqlLite, other times not. After this happens a few times you start to lose confidence that you’re not getting incorrect guidance. As an experienced DB app developer I can spot these things but I pity noobs. Presumably this is being pecked away at but they probably need to hire a tech writer to really go through this stuff and clean it up.

3 Likes

+1 for the tech writer

Thanks for pointing this out. It’s been on our list to correct for some time now. The various specific database class pages are now all updated. If you find anything that appears to be wrong, please file an issue.

This was left over from the old docs. They suffered from the same problem in that all the inherited class members simply pointed back to the parent class: Database which only had examples for SQLite.

1 Like