FileDialog documentation needs clarification and maybe working examples

[Alice-Cheshire]

FileDialog documentation needs clarification and maybe working examples

[texus]

I'll have a look at what my current documentation says and write a proper response to this later, as right now I don't have enough time, but you may want to already check out https://tgui.eu/tutorials/latest-stable/signals/#lambda-captures section to get a better understanding of the lambda capture and the reason behind the access violation.

[Alice-Cheshire]

I'll have a look at what my current documentation says and write a proper response to this later, as right now I don't have enough time, but you may want to already check out https://tgui.eu/tutorials/latest-stable/signals/#lambda-captures section to get a better understanding of the lambda capture and the reason behind the access violation.

I've read that page but rereading it now, I think I misread some of it, though if I'm reading it correctly now, I'm not sure why the code I quoted above would work now:

In a more advanced situation you can combine capture by value and capture by reference by specifying the individual variables (with or without an ampersand in front of the name to choose by reference vs. by value). All three functions below are identical.

If I'm understanding this correctly, then I can just do [&variable/class] to access a specific thing, such as Reader or loadFolderDialog. The part I'm not sure I understand is why I need to pass the FileDialog pointer as an input when I already have the [&] or else I get a crash. Is this because I'm dynamically creating the FileDialog in the onClick event for a button? If so, why? Since the FileDialog still exists when I click the open button in it, and the close event fires after that point, should loadFolderDialog not still be in scope and thus not need me to pass a reference to it?

Also, adding a bit that mentions the potential issues that the signals pages goes over but in a context more relevant to this specific widget, with some short examples, and a link to that section of the signals page would definitely help make things a lot clearer.

[texus]

I wrote the "Lambda captures" section in the Signals tutorial because I knew that many people might not be familiar enough with lambdas. I'm open to suggestions on how to improve the information on that page.

One issue with writing better examples is that [&] vs [=] only matters in complex cases. Simple examples can't demonstrate "correct" behavior because they aren't complex enough, and also because the correct option depends on what you want to do in the lambda (which I can't predict). What I can do to improve the situation though is to make sure all examples use [=] unless otherwise required. That way copying the example code can't lead to crashes and only to cases where variables outside the lambda aren't being altered (where it is easier to explain that a reference is needed).

I don't think I can add explanations to every single place where lambdas are used. The main reason I use lambdas in examples is to keep them short, so when just demonstrating what parameters a callback can have there shouldn't be a lot of code.

Something as detailed as Mozilla's MDN should not be expected. Writing good documentation takes a lot of time, so it's unlikely that there will be detailed guides on how to use TGUI. If there are specific parts in the documentation that can use some more clarification then I'm however willing to take suggestions or you can even send pull requests for them.

Since the FileDialog still exists when I click the open button in it

The capture [&] is equivalent to writing [&Reader,&loadFolderDialog] while [&,loadFolderDialog] is equivalent to [&Reader,loadFolderDialog]. The difference between the two is whether you take a reference to loadFolderDialog or whether the object is copied.

When taking a reference, what isn't important is whether the file dialog itself still exists, but whether the loadFolderDialog variable itself still exists. If you are creating the file dialog in a onClick event then I'm assuming your loadFolderDialog is a variable that is local to that onClick callback. As soon as the variable goes out of scope, the reference to it becomes invalid and attempting to use it will result in a crash, even if the file dialog still exists in the gui.

This is why you need to copy the loadFolderDialog object in the lambda, so that it continues to exist even after loadFolderDialog went out of scope. Because loadFolderDialog is a pointer, you are only copying a pointer and thus the object in the lambda is still the same file dialog.

[Alice-Cheshire]

I wrote the "Lambda captures" section in the Signals tutorial because I knew that many people might not be familiar enough with lambdas. I'm open to suggestions on how to improve the information on that page.

One issue with writing better examples is that [&] vs [=] only matters in complex cases. Simple examples can't demonstrate "correct" behavior because they aren't complex enough, and also because the correct option depends on what you want to do in the lambda (which I can't predict). What I can do to improve the situation though is to make sure all examples use [=] unless otherwise required. That way copying the example code can't lead to crashes and only to cases where variables outside the lambda aren't being altered (where it is easier to explain that a reference is needed).

I don't think I can add explanations to every single place where lambdas are used. The main reason I use lambdas in examples is to keep them short, so when just demonstrating what parameters a callback can have there shouldn't be a lot of code.

That might be a good compromise. Though I do think it might be a good idea to add a section about potential pitfalls to the lambas section of the signals page. I can't speak for everyone but even though I managed to get my code working, it wasn't immediately obvious why the change I'd made worked so I'd imagine I'm not the only one to have run into an issue like this.

Something as detailed as Mozilla's MDN should not be expected. Writing good documentation takes a lot of time, so it's unlikely that there will be detailed guides on how to use TGUI. If there are specific parts in the documentation that can use some more clarification then I'm however willing to take suggestions or you can even send pull requests for them.

Yeah, I can understand that. I meant MDN as more being the ideal than what someone should realistically shoot for though anyways, especially for a small project like this that seems to have only one dev.

Since the FileDialog still exists when I click the open button in it

The capture [&] is equivalent to writing [&Reader,&loadFolderDialog] while [&,loadFolderDialog] is equivalent to [&Reader,loadFolderDialog]. The difference between the two is whether you take a reference to loadFolderDialog or whether the object is copied.

When taking a reference, what isn't important is whether the file dialog itself still exists, but whether the loadFolderDialog variable itself still exists. If you are creating the file dialog in a onClick event then I'm assuming your loadFolderDialog is a variable that is local to that onClick callback. As soon as the variable goes out of scope, the reference to it becomes invalid and attempting to use it will result in a crash, even if the file dialog still exists in the gui.

This is why you need to copy the loadFolderDialog object in the lambda, so that it continues to exist even after loadFolderDialog went out of scope. Because loadFolderDialog is a pointer, you are only copying a pointer and thus the object in the lambda is still the same file dialog.

This helped clarify things a lot, thanks. Judging by this, I should probably change it from [&, loadFolderDialog] to [&Reader, loadFolderDialog] then since those are the only two things I actually need any access to there. No need to be overly general and risk accidentally accessing something from the outside scope that I didn't actually want to access.