Custom Property Extension: String Validation

[breadbored]

Feature

We have started using Tiled as our all-in-one map builder for a game in my custom engine. The long-story-short is that we have decided to attach dialog to characters on the map per character occurrence, and need a way to validate the text for the writer.

Proposed Solution

Because this is potentially a niche use-case, I think the broader solution is the ability to add an extension that creates a custom-named string property type, which can be validated by the extension. Even just turning the box outline red and showing some text when invalid is enough for this specific use-case.

Alternatives Considered

I made an external tool that does exactly this basic functionality, but getting the writer to cross-reference an associated dialog ID in Tiled to the tool is proving difficult. If they could find the character on a map and edit a property of a custom type "Dialog" to get immediate feedback, that would make Tiled a perfect solution for our use-case.

Notes

I'd be willing to contribute towards this if I can get some feedback on whether this could be approved, and would be useful to others.

[eishiya]

You can already have Tiled scripts validate custom properties and place Warnings in the warnings panel (via tiled.warn). I think the only functionality that's missing is the ability to focus the property for the user in warn's callback function.

You can, however, spawn a Dialog that duplicates the invalid property and lets the user edit the property in that Dialog, instead of the properties view. You can make the Dialog blocking by using Dialog.exec() instead of Dialog.show().

Since Bjorn is currently working on an overhaul of the properties view, perhaps now would be a good time to add some scripting interactions with it? 👀

The only troublesome part currently is deciding when to validate, as there are currently no signals for custom properties changing. You can have the validator run on/before save, or every N seconds, but that's just not as good or as immediate as responding to changes as they happen.

tl;dr: I don't think there's any need to implement functionality specific to string validation, as that is indeed rather niche, and I don't think embedding custom widgets in the Properties view is necessary for your task. However, the ability to react to custom property changes and focus custom properties via script would be useful generic additions to the scripting API. The signals are covered by #3418.

[bjorn]

I think the only functionality that's missing is the ability to focus the property for the user in warn's callback function.

It would be quite trivial to add a kind of tiled.mapEditor.propertiesView.selectCustomProperty(name) function, if that is desired. The selectCustomPropertyfunction is already there, just not the propertiesView accessor. There is also no way to explicitly set the "current object" from the scripting API yet, though.

I'm a bit surprised I apparently never got around to documenting the Issues view and the ability to raise your own issues from scripted extensions. It's only mentioned in the Tiled 1.3 release notes. :-/

I'd be willing to contribute towards this if I can get some feedback on whether this could be approved, and would be useful to others.

If you need further integration than is currently possible, for example a "scripted validator" on text properties, you're welcome to work on this. I am generally available for any questions, best over Discord since there are also some others that can answer things when I'm not around.

For a scripted validator, my basic idea would be something that wraps QValidator:

tiled.registerStringPropertyValidator("dialog", {
    validate: function(input, pos) {
        return ValidatorState.Acceptable;
    },
});

Open questions:

• In the QValidator API, input and pos are read-write, but I'm unsure if this is useful to expose in the JS API somehow.
• This validator would be set on any string properties called "dialog". It could be some other way of associating the validator with a property is desired.

On the C++ side, I think it would be best to base this on #4045, where the VariantMapProperty::createProperty could create a custom MultilineStringProperty with the validator set on it if applicable. Bonus points for updating this validator when it is registered after property creation, usually when the script engine is reloaded.

Visually, the Invalid state would currently turn the text red, but we can adjust the styling when needed.

[eishiya]

I'm a bit surprised I apparently never got around to documenting the Issues view and the ability to raise your own issues from scripted extensions. It's only mentioned in the Tiled 1.3 release notes. :-/

What do you mean? tiled.error and tiled.warn (not to be confused with tiled.alert) are both in the scripting API docs? That's how I know about them xP They are a bit hidden though. Perhaps I should give it a section in my tip sheet, as it's a hidden gem akin to the tile stamps panel xP

[bjorn]

They are a bit hidden though.

I was referring to the "Issues" view in particular, which isn't mentioned at all in the manual it seems. Some docs for that view, as well as a reference to the related scripting functions, could be helpful.