How to get the properties defined in a Widget Extension

[OpenXTalkPaul]

I mostly built this demo for Tom as he's working on his own custom build of the Property Inspector, but this information could be useful for anyone building IDE tools or may even help with dealing with a Widget where the author didn't include good documentation.

The demo/script is intentionally very basic, it gets the properties defined in a Widget and then gets the properties value and then prints the list to the message box. Select only a single widget.

I didn't look much at the scripts for the existing Property Inspector (I will later) so there may be some better way to get this information. Also my script doesn't check if a value if a property is an array or not, so there may be addition lines of code that need to be added for getting information out of any array properties. And of course a property value may be empty if it has no default value or if it was never assigned any value.

Apparently, from looking at the original Inspector code, Widgets can include their own custom property inspector editors in a sub-folder of the widgets install folder named "editors", which as far as I know is a completely undocumented feature, so that's interesting and could be very useful.

For IDE Extensions Handlers are defined in the Toolset/Libraries directory of the IDE file named: revideextensionlibrary.livecodescript

WidgetProperties.oxtstack

(9.98 KiB) Downloaded 81 times

[OpenXTalkPaul]

Here's an example of how to parse info directly from the Widgets install folder (ie. not using the IDE Extension Library's handlers):
Posted by Mark Weilder (circa 2017):

Re: Getting properties and active handlers of a widget
Post by mwieder » Wed Jun 14, 2017 5:52 pm

Here's how I'm getting the handlers currently:

Code: Select all

/**
* find the extension interfaces folder
*/
private function modulesLocation
   return specialfolderpath("engine") & "/Toolchain/modules/lci/"
end modulesLocation

/**
* given a module name
* return a list of its public handlers
*/
function widgetAvailableHandlersOfModule pModule
   local tFile
   local tContents
   
   put modulesLocation() & "com.livecode." & pModule & ".lci" into tFile
   put url ("file:" & tFile) into tContents
   filter tContents with "*handler*"
   return tContents
end widgetAvailableHandlersOfModule

PowerDebug http://powerdebug.ahsoftware.net
PowerTools http://www.ahsoftware.net/PowerTools/PowerTools.irev
Top
mwieder
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
Posts: 3581
Joined: Mon Jan 22, 2007 1:36 am
Location: Berkeley, CA, US
Contact: Contact mwieder

Post by mwieder » Wed Jun 14, 2017 8:36 pm

because note that revIDEspecialFolderpath("engine") returns nothing on linux.

I wonder does revIDEspecialFolderpath("engine") still return nothing on Linux?

Mark's script makes a lot of assumptions, like that your extension module begins with "com.livecode." which the ones I've added to OXT do not. For OpenXTalk Extension modules I've been using "org.openxtalk." for identifiers, community released widgets may begin with "community.authorsname." as well. So this script would need to be modified for those instances. It also assumes you're only interested in an extension that came included with the IDE, but what about user installed extensions?

Anyway, I don't see much point in rewriting functionality of bits of the IDE's libraries that already exist and have at least to some degree already had kinks worked out, other than perhaps from a curiosity/learning about the IDE's functionality perspective.

I think it would be good to spend some more time instead documenting more of the IDE's libraries functions.
If you're using my builds of the 'Dictionary' then it should include docs for some of the IDE libraries.

[tperry2x]

Thank you Paul (& Mark) - this may be exactly what I was looking for. Bookmarked, for later reference when I'm feeling suitably refreshed.

I wonder does revIDEspecialFolderpath("engine") still return nothing on Linux?

I don't know about the revIDE bit, but specialFolderpath("engine") certainly works. I've used it loads on linux:

eh.png (8.76 KiB) Viewed 1345 times

[OpenXTalkPaul]

So the list of 'public' handlers implemented by an extension is in its 'interface' file.
For and IDE included extension this is at:

Code: Select all

revIDESpecialFolderPath("Toolchain") & "/modules/lci/"& tExtensionKindID &".lci"

Where tExtensionKindID is a variable that contains the extension 'kind' (an rDNS-style identifier) a standard widget property.

User installed extension modules are installed in a similar locations within the users 'My OpenXTalk' folder:
revIDESpecialFolderPath("User Extensions")

The list of properties a widget implements will be in its manifest.xml file, which for an IDE extension is located at revIDESpecialFolderPath("Extensions") & "/"& tExtensionKindID &"/manifest/xml"
or for user installed extensions here:
revIDESpecialFolderPath("User Extensions") & "/"& tExtensionKindID &"/manifest/xml"
The properties listings are parsed already by the IDE when an extension is loaded, you can get the list with:
revIDEExtensionProperties( tExtensionKindID )

put the keys of (revIDEExtensionProperties("com.livecode.widget.treeView"))

revIDEExtensionProperties and some other handlers like it should be documented for IDE and add-on development.
As I've said, I've added some more IDE library handler docs to the dictionary already, but the Extension related ones are all from the library related to Building/compiling and loading Extensions, such as extensionExtractDocs (which was used to extract this libraries own in-line docs) not so much getting info from the loaded or selected extensions like these handlers do.

[tperry2x]

So the list of 'public' handlers implemented by an extension is in its 'interface' file.
For and IDE included extension this is at:

Code: Select all

revIDESpecialFolderPath("Toolchain") & "/modules/lci/"& tExtensionKindID &".lci"

widgetDataTests.png (110.79 KiB) Viewed 1313 times

I'm able to get as far as reading the keys of each widget, and thank you for your instructions.
However, I can't see what values each key can accept. Also, I don't know if any of these keys have things set as default.
Can you modify my attached stack to do that please?

Also, this is just querying the keys of the widget type - but if I had a widget placed on the card (and knew what property to look for based on the above information), how would I set the properies of the widget through script?

For example, in the screenshot above - I've selected the treeview widget.
I can see it has a property called 'foldState' (about half-way down on the field on the right)... but what can I set that to?
And How do I set it?

Thanks for your help Paul. I'm trying to get my head around this, honest.

Also, it's related to the other post here (kind of)

[OpenXTalkPaul]

I'm not sure I understand what is your issue with setting a property via script, because you do it the same way you set any property or custom property on any other control or scriptObject.
Set the foldState of widget "MyWidge" to tProbablyBoolean

Now I will preface this by saying I need to explore this more to figure out how the rev Inspector does this, but...

If you look at the other stack I posted "Ger All Widgets Properties" button calls the IDE handler revIDEWidgets() (which is used by the Tools palette), which returns an array of associative arrays, each installed Widget is a top level element, the keys of each of those are Widget's properties, and each property can be an array (or not) that contains its value and addtional info about the property (or not), such as what editor to use to set that property, or it's visibility in the Inspector. Now this only shows the things that the Widget itself has included metadata for, which in the case of tree view's 'foldState' this only shows 'user_visible = false', so that is a property that is set by some handler in the Widget and NOT meant to be set via script nor visible in the Inspector. A widget can have properties users normally would never see like this one.
I'm sure you could still set the property via script, if you know what type of value it expects to receive, but the Widget author did not design it that to be user-settable.

[tperry2x]

I'm sure you could still set the property via script, if you know what type of value it expects to receive, but the Widget author did not design it that to be user-settable.

It's probably a bad example of a key to pick then, but you get what I mean. You hit the nail on the head:

Set the foldState of widget "MyWidge" to tProbablyBoolean

tProbablyBoolean (it could be a true/false, it could be a 0 or 1, it could be 'folded' / 'unfolded' or 'hinged'... 'unhinged' )
But, it's the not knowing. And how do I know what properties should show up in an inspector, and which ones are reserved and should not be user configurable? That's why I'm finding it a mystery at the moment. I'm sorry if I'm missing something obvious.

[OpenXTalkPaul]

the IDE handler revIDEWidgets() (which is used by the Tools palette), which returns an array of associative arrays, each installed Widget is a top level element, the keys of each of those are Widget's properties,

That' not entirely accurate, some of these second level elements of a widgets element will be 'Widget things' like it's install_path, and Widget metadata such as its icon (a file path to some icon.png) or its svgicon (an SVG path string) if the widget has those included.

[tperry2x]

... some of these second level elements of a widgets element will be 'Widget things' like it's install_path, and Widget metadata such as its icon (a file path to some icon.png) or its svgicon (an SVG path string) if the widget has those included.

....right.... so, that's the question. How do we drill down into just getting a list of the properties that should be set, and then finding out what variables / inputs they expect to receive?

This is why I'm rapidly going off the idea of supporting widgets in their current form. I do want to try and support them if I can, but I can count the number of times I ever added one of them to a stack on one hand.

[OpenXTalkPaul]

how do I know what properties should show up in an inspector, and which ones are reserved and should not be user configurable?

Right, I thought I answered this, The properties 'user_visible' metadata, if that element is present and set to 'false' then it should not be visible in the Inspector.

If a property has meta data element that says to use com.livecode.pi.boolean then the property can be nonexistent/empty, the string "true" or string "false", no quotes needed when setting the property as far as OUR xTalk interpreter is concerned because true/false are constants variables that contain string literals (emphasis 'OUR'' because I believe LC has changed their xTalk recently to have more C++ -like booleans).

We should have a list of all possible metadata like
metadata user_visible = ["true,"false"], a boolean indicating if the property should be visible in the property inspector.
...and also a list of all of the Prop Inspector editors and what values the generate.
For example:
com.livecode.pi.colorwithalpha editor sets a string that is 4 comma separated number "0,0,0,127" (RGB+Alpha = 50% transparent black).

A big problem is that not all of these properties have an 'editor' metadata element set. So I'm not sure how one knows the expected values for those. I do know that the Extension Builder can infer what editor to use from the property variables builder-language data type, so if its XB type is 'as boolean' then it will assume that it should use the boolean editor (which is simply a checkbox control). So I'll have to investigate that further.
Standard properties like 'label' are going to use the same editor as the 'classic controls' properties, so 'label' is a string text prop editor, likewise we know that the standard property "disabled' property is a boolean.

Another thing to complicate this is that Widget properties can have a metadata element that indicate which tab of the property inspector a property's editor should be displayed in. I suppose this could be ignored if you wanted to do away with tabbed interface in PI, most widgets I've seen don't even use this property metadata tag.

Also note that user_visible COULD be true, but the property might have metadata that says it's a 'read_only' property (which means it's not backed by an XB handler that allows it to be 'set' but you can still 'get' the property value. If this is the case the value should be displayed in the property inspector but not with an editor. For example this way you could show the percentage an image was scaled up/down, without allowing the image to be rescaled from that property (I can't think of a better example of the top of my head).

[tperry2x]

...not all of these properties have an 'editor' metadata element set. So I'm not sure how one knows the expected values for those.

Exactly.

Also note that user_visible COULD be true, but the property might have metadata that says it's a 'read_only' property (which means it's not backed by an XB handler that allows it to be 'set' but you can still 'get' the property value. If this is the case the value should be displayed in the property inspector but not with an editor.

Nice and straightforward then!

[OpenXTalkPaul]

This is why I'm rapidly going off the idea of supporting widgets in their current form. I do want to try and support them if I can, but I can count the number of times I ever added one of them to a stack on one hand.

OK, but then you guys talk about a system where users can make stack-script-behavior based 'widgets', which I think is a fine idea to support, but such as system that makes script-widgets that can be edited with a Property Inspector is likely going to wind up being as complicated as this Extension Builder Widgets system (the current implementation actually makes a lot of sense to me, needs better docs though), and those stack-script-based 'widgets' are limited by the capabilities of groups of 'classic controls'. Why not use the system that's already in place, possibly tweak it as needed to allow it to use stacks as widgets.
In fact I've been thinking the Extension packaging format could also be used to deliver 'example stacks' without any extension in the package. Those .lce files are really just zipped-up folders.

[tperry2x]

OK, but then you guys talk about a system where users can make script-behavior based 'widgets', which I think is a fine idea to support, but such as system that makes script-widgets that can be edited with a Property Inspector, is likely going to be as complicated as this Extension Builder Widgets system...

I think it could be simplified massively. (understatement of the year)

...(the current implementation makes a lot of sense to me), and those stack-script-based 'widgets' are limited by the capabilities of groups of 'classic controls'...

Yes, I suppose so - but then what can't be done with groups of classic controls that you can specifically do with Widgets instead?
If it makes a lot of sense to you, that's great - but (at the risk of annoying you, which is not my intention), It's still a mystery to me. You can't say for sure how to know what value any given key of that widget array it's looking for, so I would say 'makes sense' is a bit inaccurate.

Why not use the system that's already in place, possibly tweak it as needed to allow it to use stacks as widgets.

I would love to, if only we had an example stack that I can place any widget on, and can reliably know what to set the various properties as. At the moment, seems like I'd have to loop through all the properties, reading each one, comparing if it should be editable, (should it not actually be user-editable even if it seems like it should?), then who-knows what it's expecting the properties of each element to be - so at best any inspector is just an array key reader, without knowing what to write back - otherwise it'll just create bucket-loads of errors.

In fact I've been thinking the Extension packaging format could also be used to deliver 'example stacks' without any extension in the package. Those .lce files are really just zipped-up folders.

Yes, I found that out purely by mistake by unzipping one of those. I don't think that was documented anywhere either.

[OpenXTalkPaul]

Nice and straightforward then!

More options for how the Widget's authors want their widget to display/edit is good thing.
Most of the time it would be some sort of string, even numeric values, possibly an array
You can find out with script, if <myProp> is an array then ... or .. if <myProp> is an integer then ...

is a[n] {array | boolean | color | date | integer | number | point | rect | ASCII string }

[tperry2x]

Most of the time it would be some sort of string...

Most of the time... and what about when it's not a string?
It seems like this stuff is getting further and further away from the "programming for the rest of us". I'd defer to your knowledge on xTalk, however (don't get big headed ) but even you aren't 100% sure how this all works, so what chance do us mere mortals (or anyone else for that matter) have?

Example:

clock.png (31.11 KiB) Viewed 1247 times

Here's a clock widget dragged in from the tools palette. What does "timezone" do? nothing... or is that broken?
What about if I want it to display an hour in advance, or 10 minutes in advance? Where are the settings for it? Yes, I can change colours but I can't do much else.

Yet, I could absolutely do all that with a group of classic controls and have pre-populated scripts when they were dragged off the tools palette to allow full user control. None of that would be a mystery. All someone has to do to 'get at' the code is edit the group.

Essentially I see widgets a bit like the problem of the engine. It's all wrapped up in it's own obfusicated way. Talking about externalising things, we would be better off having widgets made up of classic controls in my opinion - thereby externalising the widgets.

[richmond62]

this stuff is getting further and further away from the "programming for the rest of us".

I am not surprised in the slightest: I have a feeling that the "programming for the rest of us" concept was chucked out just about the same time as it became obvious that the Open Source version was not going to be the fantastic cash-cow that various people seemed somehow to think it would be.

The upcoming 'fading into the background' of the Stacks & Cards metaphor is also part of the same trend.

The idea that people nowadays will not know what a Rolodex thing is, and that will somehow stop them being able to understand the Stacks & Cards metaphor is a load of Hoo-Hah (I hade never seen a Rolodex thing, and only actually found out what they were when I saw one in a film made in the 1980s quite recently).

Only people who were brought up in families adhering to totalitarian cults do not know what a deck of playing cards is . . . I had an aunt who got all hot and bothered by playing cards and the evils she imagined were attached to their use: so when she came to stay we had to play 'Happy Families'.
-

HappyFamiliesbox_2_540x.jpg (69.52 KiB) Viewed 1229 times

[OpenXTalkPaul]

You aren't annoying me, no worries, its good thing for me to have explain / defend my position on this and discussing the IDE is why we're here.

Yes, I suppose so - but then what can't be done with groups of classic controls that you can specifically do with Widgets instead?

LOTS of things...
First...
I mean the DataGrid is basically a stack/script based widget, but I wouldn't called that less complicated.
On the other hand, I have some nice stack/script based 'widgets' that are useful right now in my revOXTObjects library, such as HH's graphic object based rotary control, that is fairly simple, with one or two custom properties. I similarly made my 'piano widget' as graphics objects originally.
But even the base default 'classic controls' are created based on data in files in the IDE, that's how I was able to add 'Filled Button" style (originally I called it a 'macOS style' button) as a NEW 'classic control'.

On the Widget side...
Everything in a widget is externalized, no need for the user to edit anything, just set the use_visible properties, unless they want to and then they can edit the widget at its source (since we're all FOSS here). There's never a missing button icon image due to conflicting image IDs.
The 'regular' Widgets render visually identical on all platforms (as long as the widget doesn't specify to use a font that isn't loaded)
Unless they're 'native layer' widgets, like "Mac Native Button", "Android Native Field", etc.), which they can be.
They run in the UI thread, separate from the script execution thread.
They're pre-compiled byte code (potentially faster execution)
They render faster for the most part (that could depend on how its coded)
They render 'sub-pixel' accuracy on HiDPI screens (like Retina displays, 2K,4K+).
They can use, or be driven by, System APIs via the Foreign Function Interface, like in the Browser Widget or in my Apple PDFKit Widget.
Theoretically a widget could display either 'native' layer, system provided UI Widget OR a custom drawn control (and someday I'll test this Idea).
They can be loaded and unloaded from memory (including dictionary entrees) in a modular, isolated way. They sort of run in their own little sandbox.

You can't say for sure how to know what value any given key of that widget array it's looking for, so I would say 'makes sense' is a bit inaccurate.

They make sense in the same way that the classic controls make sense to me now... their properties, default values, PI editors, etc. are defined by a set of data (tabbed-text data lists), the data just cannot be stored in the same way for Widgets due to their modular nature.

How do you know what a 'classic control' property expects for a value? Take for a 'standard' property for example "traversOn", Is that a boolean string (yes), or numeric? Could it be enumerated as "on, off"? You know because you looked it up in the dictionary, right? But its values / range is actually set from that tabbed data .tsv file.

I'm 100% sure there are methods to get the expected value type and allowed range for every property of every widget (that's not user_visible = false), because the rev prop Inspector does this already (of course there might be some spaghetti wiring to untangle there), but I do have to look into it more thoroughly to see how they did it.

Admittedly it probably makes sense to me in part because I've made and looked at the source for a bunches of widgets, and I'm familiar with the way properties are defined in them. But I'm pretty sure I could write a handler that parses the data directly from the extensions install_folder from it's xml or even directly from the .lcb file, but I'm sure it would be easier to use whatver method rev Prop Inspector is using already uses.

I would love to, if only we had an example stack that I can place any widget on, and can reliably know what to set the various properties as. At the moment, seems like I'd have to loop through all the properties, reading each one, comparing if it should be editable, (should it not actually be user-editable even if it seems like it should?), then who-knows what it's expecting the properties of each element to be - so at best any inspector is just an array key reader, without knowing what to write back - otherwise it'll just create bucket-loads of errors.

Yes, I'm sure the current rev PI does exactly that (iterates through a list of properties stored in arrays) for all controls, including widget controls).
How are you doing it now for classic controls? Are you using idePropertyNames( pObjType ) or are you making assumptions about what properties get which editor based on pre-exising knowledge of each of the 'classic controls'? If so that might be OK, maybe even a few milliseconds faster, so long as those controls are never changed which could then break your Inspector.

In fact I've been thinking the Extension packaging format could also be used to deliver 'example stacks' without any extension in the package. Those .lce files are really just zipped-up folders.

Yes, I found that out purely by mistake by unzipping one of those. I don't think that was documented anywhere either.

Agreed, the docs need work.

[OpenXTalkPaul]

I spent some time yesterday with that old 'DropTools' stack/script based 'widget' system, which I think I played with on the v6 engine a long time ago, but it's totally broken in the 9.x IDE.

[OpenXTalkPaul]

this stuff is getting further and further away from the "programming for the rest of us".

WE aren't doing 'programming for the rest of us' here, we're doing programming for end users to do programming for the rest of us, so that the xTalk script author end-user doesn't have to create their own 'Piano' widget ( my favorite example), before they can make their program when they really just want to make a thing that teaches musical notation symbols or something like that.

[tperry2x]

You aren't annoying me, no worries, its good thing for me to have explain / defend my position on this and discussing the IDE is why we're here.

Good, that's a relief. I didn't want this to come across sounding like an argument as it's not supposed to.

How do you know what a 'classic control' property expects for a value? Take for a 'standard' property for example "traversOn", Is that a boolean string (yes), or numeric? Could it be enumerated as "on, off"? You know because you looked it up in the dictionary, right?

No, I didn't look it up in the dictionary, I mean I could have done - but I did already know about that.
Thing is, I could have used:

traversal.png (3.46 KiB) Viewed 1209 times

I can just run that in the messageBox to get (and set) the current value. How did I know that "traversalON" actually means "Focus with Keyboard"? Because on the inspector I can hover over it and the tooltip gives the name of the property. (As does my replacement property inspector). Without that, I would likely have been stuck.

I'm 100% sure there are methods to get the expected value type and allowed range for every property of every widget (that's not user_visible = false), because the rev prop Inspector does this already (of course there might be some spaghetti wiring to untangle there), but I do have to look into it more thoroughly to see how they did it.

Well, I'll carry on with my Property inspector, because the widget info will probably load in it's own dynamic tab. The rest will be static properties (more on this further down as I see you mention it).

How are you doing it now for classic controls? Are you using idePropertyNames( pObjType ) or are you making assumptions about what properties get which editor based on pre-exising knowledge of each of the 'classic controls'? If so that might be OK, maybe even a few milliseconds faster, so long as those controls are never changed which could then break your Inspector.

Making assumptions (well, not assumptions - I mean, the properties are all there and as plain as day to see, so it's not an assumption as such. Factual assessment is probably a better description They don't change).
As I mentioned before, changing any aspect about the classic controls will mean they break in the Standalone (runtimes) without the runtimes being recompiled to match. So, no - I don't expect them to change. Plus, changing them will also break backwards compatibility with previous stacks.

Thing is, I can currently do the same for the existing widgets, with the old property inspector. So as you say, this must be being read and pulled in somehow.

switch.png (15.52 KiB) Viewed 1205 times

For example, this switch widget. If I want to change the theme, under the appearance popup menu (on the old inspector), the options are: Native, iOS, Android.
Now, nowhere I can find is that documented.

So, I can inspect it and piece together what other values I can set (because they show as options). I don't need to look in a dictionary, because the options it supports are right there.

changed-by-messagebox.png (7.65 KiB) Viewed 1205 times

So knowing that, I can go change them in script (as will be required of course, somewhere along the line).
But up until just 10 minutes ago, I didn't know I could do that. (I've genuinely never used a mobile-style 'switch widget' in a stack). Without having the old property inspector read these array keys and the corresponding values, I would have had no idea how to script or control it.
That's what I'm going on about. It's not a fundamental objection to widgets, but imagine you didn't have an inspector to list these properties. How would you know this widget only responds to "Native, iOS, Android" when setting or getting the 'theme' property of it? You wouldn't. Not unless your inspector (or documentation) could tell you so.

But again, the inspector must be getting these from somewhere. That's the method I want to track down, because it knows not only the keys in the widget array, but it also knows what each of the keys can be when it is filling out the old inspector.

Agreed, the docs need work [regarding lce files]

By all means, we could have our own widget package (oxtwa) "OXT Widget Archive" perhaps. But, what I'm on about is why can't we make it simpler? With each one, include a usage stack which shows as a practical example how you get / set properties for each key the widget supports and what data it's expecting. Just like sons of thunder did - they detailed what properties their widget supported and what inputs it expects. Simply because it takes the head scratching and frustration (and guess work) out of the equation. Yes, we are creating software (recreating?) for people who will be the intended audience for "programming for the rest of us", but why are we making maintaining it hard for ourselves? There's no reason to do that.