Page 1 of 2

CustomControls - Style Guide ?

Posted: Thu Aug 15, 2024 10:18 am
by Skids
I believe that CustomControls are a useful addition to OpenXtalk and having written a couple I propose that some form os Style Guide is created. At present this will take the form of this thread so please do not post questions here about actual Custom Controls unless illustration a point.

Here are some initial thoughts:

1) Where possible a CustomControl should encapsulate all of its code. The exception to this is if it uses a behavior button when it is acceptable to store the behavior button elsewhere.

(My Custom Controls Palette adds a substack to your project for behavior buttons when you drag a CustomControl into your own project. Of course this can be changed but it seemed a good idea when I created the palette during Covid lockdown).

2) Like LC widgets ideally Custom Controls need to be stored in an easy to use location. At the moment I believe the options are either on a custom palette stack or as individual plugins accessed via the plugins menu. There may be better ideas.

3) Some account of Dark Mode needs to be included. (I have no idea what though!)

4) The CustomControl's API needs to be explained and documented.

5) Some form of error handling should be included within the code of a CustomControl.

Over to you.

best wishes
Simon

Re: CustomControls - Style Guide ?

Posted: Thu Aug 15, 2024 10:53 am
by richmond62
Am I to understand that a 'Custom Control' might be another name for a LiveCode widget (as opposed to an LCB widget), or a fancy group of other controls with an over-arching group script?

Re: CustomControls - Style Guide ?

Posted: Thu Aug 15, 2024 1:48 pm
by Skids
Am I to understand that a 'Custom Control' might be another name for a LiveCode widget (as opposed to an LCB widget), or a fancy group of other controls with an over-arching group script?
Hmmmm, I think of a CustomControl as a group with script that performs a specific role. I was unaware that there were two types of widgets. I think that widgets are the things introduced in Edinburgh in 2016 written in LCB with a graphical element. I'm still looking for the 1000 that were going to be created by Christmas. I'm not sure what a Livecode Widget is - sorry.

S

Re: CustomControls - Style Guide ?

Posted: Thu Aug 15, 2024 2:26 pm
by richmond62
LiveCode made a thing a short while ago about an upcoming thing to make widgets in LC without LCB.

Re: CustomControls - Style Guide ?

Posted: Thu Aug 15, 2024 3:38 pm
by Skids
LiveCode made a thing a short while ago about an upcoming thing to make widgets in LC without LCB.
I'll have a search for it. Thanks

Re: CustomControls - Style Guide ?

Posted: Thu Aug 15, 2024 3:53 pm
by Skids
https://livecode.com/oxy_testimonial/bu ... ilder-lcb/

Its a blank page so I guess they changed their minds.

Re: CustomControls - Style Guide ?

Posted: Thu Aug 15, 2024 4:20 pm
by richmond62
They have a tendency to 'talk things up' and make sweeping promises, of which some, at least, are 'quietly forgotten' (c.f. Kickstarter goals).

That does not mean that OXT cannot profit from keeping some of LC's broken promises for them. :lol:

Re: CustomControls - Style Guide ?

Posted: Fri Aug 16, 2024 2:10 am
by OpenXTalkPaul
Skids wrote: Thu Aug 15, 2024 3:53 pm https://livecode.com/oxy_testimonial/bu ... ilder-lcb/

Its a blank page so I guess they changed their minds.
Hmm, yeah too much work for little benefit to their business maybe, and there's a good chance no one will adopt that system either, like the way hardly anyone in the community took up making LCB Widgets.
But I did look at some sampling of the idea that was shared by a user, and it was interesting (script only file though, so just like LCB Widgets they were still creating its UI objects on-demand.
I prefer keeping CustomControls in my Object Library (which I've made a few minor improvements on over LC version). I looked at the pre-Widgets DropTools community-made system too, which was like a 'CustomControl' palette and specifications for a standard.
What I want is a UI mark-up text, or a text-only-UI-stack format to compliment the script-only text format, but for UI controls. I've been leaning towards something XML based for that, something akin to Qt's QML.

Re: CustomControls - Style Guide ?

Posted: Fri Aug 16, 2024 2:59 am
by OpenXTalkPaul
Here's a Lesson LC put out on "Script-Widgets", it appears they are indeed either UI built on the fly or just groups of controls that are treated slightly differently by theirIDE. It treats the grouped controls as if there a single object (that might be in a IDE script library that's doing that special treatment, or maybe they added support to the Engine, can't be sure but a script library could do this too I'm sure).

These script-widgets use special initializer/uninitializer handlers similar to how Script-Extension Libraries have, and use setProp/getProp handlers for the widget's properties, it allows uses of same metadata tags and inline documentation as Extension Builder packages do, use widget reverse-DNS-style identifiers to give your Widget 'class' object a unique ID.

https://lessons.livecode.com/m/98525/l/ ... ipt-widget

Here's a user's shared script-widget you can look at too:
https://github.com/stam66/tristate

Re: CustomControls - Style Guide ?

Posted: Fri Aug 16, 2024 5:30 am
by Skids
It treats the grouped controls as if there a single object (that might be in a IDE script library that's doing that special treatment, or maybe they added support to the Engine, can't be sure but a script library could do this too I'm sure).
I can't help thinking why didn't they make more of a fuss over adding this feature and also why did they add it? Back in 2016 they were hoping that thousands of widgets / extensions would be created by users in a few months using the new Builder and Extensions manager. Now they have added the ability to write widgets using script which is great but apart from one lesson there does not seem to be any other documentation.

I searched the otherforum and found a thread where Stam was reporting issues with his tristate widget and what was interesting was that he was getting replies from the LC team. Mind you they did not solve the problem which was solved by Bernd (no surprise there!).

Getting back to Xtalk I don't understand enough of what happens behind the curtain such as how script libraries interact with the Engine. For example I have always assumed that new versions of the IDE have always meant that the Engine had been updated but now I'm wondering if many of the point updates have just involved changes to these script libraries as I imagine re-building the Engine is a complex task requiring a lot of regression testing.

Drifting back towards the subject of this thread and having recently edited a CustomControl (CC) I am changing my mind on the use of external behavior scripts i.e. those saved outside the group. My reason for using a behavior was to keep the handlers that enable the CC to work as hidden from the end user as possible. The ability to declare handlers as private to the group would be useful but I don't think this is possible so other methods will have to be employed to obscure the internal workings.

best wishes

Simon

Re: CustomControls - Style Guide ?

Posted: Fri Aug 16, 2024 5:46 am
by Skids
I have just looked at HH's circular slider control and confirmed that one technique for hiding code is to place the group control's group inside another group. This outer group is what the end user sees and only handlers that are meant to be exposed to the end user can go in this group. Neat, why didn't I think of that?

S

Re: CustomControls - Style Guide ?

Posted: Fri Aug 16, 2024 8:39 am
by tperry2x
Have a look here:
https://github.com/trevordevore/livecode-extensions
This repository contains widgets that I have made available to the community.
Trevor Devore
Image

In fact, might be an idea to grab all these "Community Widgets" while they are still there.

If it does "disappear", you can also try here.

Re: CustomControls - Style Guide ?

Posted: Fri Aug 16, 2024 9:48 pm
by OpenXTalkPaul
tperry2x wrote: Fri Aug 16, 2024 8:39 am Have a look here:
https://github.com/trevordevore/livecode-extensions
This repository contains widgets that I have made available to the community.
Trevor Devore
In fact, might be an idea to grab all these "Community Widgets" while they are still there.

If it does "disappear", you can also try here.
Trevor's examples Widget set are very good to start from.
He also has his own Widget building tutorials on his website:
https://www.bluemangolearning.com/livec ... er-widget/
https://www.bluemangolearning.com/livec ... e-widgets/
https://www.bluemangolearning.com/livec ... e-builder/
These were all from back when there was promises of '1000 Widgets by Christmas", sigh.

I think I might take a crack at writing my own xB Widget tutorial. I've since learned some things that were not covered, or at least not covered in detail back when.

Just for clarity, Trevor's widgets at that URL are all built in Extension Builder language, not LC's new-fangled 'Script-Widgets".

I'm 100% for keeping Extension Builder, but I'm not at all against having our own system of CustomControl Script/Grouped Classic Controls based Widget system too. Like I said, I use the "Object Libraries" stack for that sort of thing, but that stack is very basic, and would be so much more useful as a palette IMO.

Re: CustomControls - Style Guide ?

Posted: Fri Aug 16, 2024 11:35 pm
by OpenXTalkPaul
This is from 'libscript' (part of the engine source code)
https://github.com/livecode/livecode/bl ... ript.h#L61

The comments has info that shows the package format used as .LCE package format
////////////////////////////////////////////////////////////////////////////////

// Packages are a collection of modules which share a common set of foreign
// code and resources.
//
// When a package is loaded into memory, all its modules are loaded also making
// them available in the module namespace and accessible through the module
// functions.
//
// A package loaded from a particular file, or with a particular name can only
// be loaded once - if an attempt is made to load a package from a file and that
// package has the same name as a loaded package it is an error. If an attempt
// is made to load a package by name and such a package is already loaded it just
// returns that package.
//
// Ensuring modules are usable is done lazily - either by an attempt to create
// a module instance, or by explicitly ensuring via the appropriate API.
//
// Packages can be unloaded from memory, however they are not completely removed
// until it is possible to do so - i.e. until there are no instances of any module
// within the package in use.

Code: Select all

////////////////////////////////////////////////////////////////////////////////
// Packages are a zip archive with the following structure:
//   <root>/
//     manifest.xml
//     module.lcm
//     support/
//       <files for the IDE / store etc.>
//     modules/
//       <compiled submodule files>
//     symbols/
//       <compiled module debug info>
//     resources/
//       <shared resources>
//     code/
//       <compiled foriegn code>
//     source/
//       <original source code>
//     docs/
//       <docs tree>
EDIT: OT but... I was looking through that source directory in the folder above that one in the repo, which is the source code for extension builder ( xB language modules that make up the Extension Builder language itself), and I came across encode/decode syntax which I never noticed before, I don't think I've ever even seen it be used in any xB source, I probably would have used it if I had (although it looks like that particular windows text encodings is not wrapped).
https://github.com/livecode/livecode/bl ... coding.lcb

So in xB you can do
decode tMyData as using utf16 into tMyDoublByteText
or
encode tMyData using base64 into tMyBase64EncData
Cool!

I just checked, that syntax is not even in the LCB section of LC Dictionary, like the one they have available online currently!

Re: CustomControls - Style Guide ?

Posted: Sat Aug 17, 2024 6:50 am
by Skids
I know I should go and look but what can be in a module ?

Re: CustomControls - Style Guide ?

Posted: Sat Aug 17, 2024 7:39 am
by Skids
Trevor's examples Widget set are very good to start from.
He also has his own Widget building tutorials on his website:
Thanks for the links. Trevor helped me out with my Calendar Reader extension with issues with callbacks that I was (and is) having when trying to get the user to grant permission to access the EkEventStore. I say "is" because it no longer works in the LC IDE when running under Sonoma as Apple have depreciated some commands and require new lines in two of the plist file in the IDE. These are simple to edit but then MacOS reports that the IDE is broken because of the changes made (SIP strikes!!!). Full details and examples plus an ugly solution are all detailed here https://quality.livecode.com/show_bug.cgi?id=24054

The issues I have with LiveCodeBuilder Widgets are that when compared to a Custom Control Groups, widgets are complex to build and require that a new programming language be learnt. Yes its like script but it is different and as has been written many times the documentation is sparse. However they do provide a method of extending LC/Xtalk and apparently offer some technical advantages.

The real problems for me start when I use a commercial widget in a stack and then I want some help. In my example I used a date picker which was part of the summer bundle from Run Rev in a test stack written to debug my EkEventKit extension. The only indication that the widget was not free to use when I started getting reports that my test stack was not working as expected. I realise that the community has paid for locked library stacks for years but somehow it seems simpler to fall into the trap with a widget that appears in the tools palette.

Yesterday I downloaded a number of Community Widgets and along the way read some posts by HH in 2020 detailing why he was ceasing to produce widgets : I paraphrase but he felt his suggestions about LCB were being ignored and his bug reports left unresolved.

I also found a thread where LC and Python user Stam details the issues he ran into trying to build a new script widget. Simply it caused a slow down which attracted the attention of LC. However they were beaten to the solution by Bernd. See https://forums.livecode.com/viewtopic.p ... te#p225331 and an earlier post : https://forums.livecode.com/viewtopic.p ... te#p224936

Mind you I've yet to try and build a widget - perhaps I will love the process.....?

Re: CustomControls - Style Guide ?

Posted: Wed Aug 21, 2024 1:06 am
by OpenXTalkPaul
Skids wrote: Sat Aug 17, 2024 7:39 am
Trevor's examples Widget set are very good to start from.
He also has his own Widget building tutorials on his website:
Thanks for the links. Trevor helped me out with my Calendar Reader extension with issues with callbacks that I was (and is) having when trying to get the user to grant permission to access the EkEventStore. I say "is" because it no longer works in the LC IDE when running under Sonoma as Apple have depreciated some commands and require new lines in two of the plist file in the IDE. These are simple to edit but then MacOS reports that the IDE is broken because of the changes made (SIP strikes!!!).
I've managed to have callbacks working with some Objective C stuff, but it is a bit tricky. If Apple deprecated / removed something your code relied on there's nothing to do about it but rewrite to support Apple's latest and (allegedly) greatest APIs. I have a 'macToast' popup notification command in my macOS Tools library that no longer functions on macOS 11+ because Apple switched up the API, so I know exactly what you mean. It's a pain but what can yo do?
Full details and examples plus an ugly solution are all detailed here https://quality.livecode.com/show_bug.cgi?id=24054
I'd prefer it if you not use links to bugzilla, pasting quotes here is fine, report bugs here like in tPerry's bugs list thread, , just don't want that particular external sources of info linked to here.

The issues I have with LiveCodeBuilder Widgets are that when compared to a Custom Control Groups, widgets are complex to build and require that a new programming language be learnt. Yes it's like script but it is different and as has been. However they do provide a method of extending LC/Xtalk and apparently offer some technical advantages.
Yes this is all true. There's a learning curve, it's like a half-step into C++ way of writing code. Much of the documentation is poorly written or non-existent but that can be worked on. For me the benefits of Foreign Function interface is what drew me into leaning xBuilder, I didn't write any LCB or widgets until the FFI was added. Things that are worth doing can be difficult to learn to do. I wanted to be able to send MIDI data generated from script and it enabled me to do that (after a month or so of racking my brain over Apple's CoreMIDI docs which was far worse than Extension Builder's docs.). I learned to appreciate Widgets later.
The real problems for me start when I use a commercial widget in a stack and then I want some help. In my example I used a date picker which was part of the summer bundle from Run Rev in a test stack written to debug my EkEventKit extension. The only indication that the widget was not free to use when I started getting reports that my test stack was not working as expected. I realise that the community has paid for locked library stacks for years but somehow it seems simpler to fall into the trap with a widget that appears in the tools palette.
This does't apply here. We are not LiveCode Ltd. We have no commercial version or locked commercial widgets, we can't even if we wanted to. There is some LC Module that was about checking if an Extension is commercial encrypted or not, but I removed it. You cannot used any locked stacks or locked commercial extensions with OXT, and you most likely never will be able to. All Extensions and Stacks here are Open Source, in accordance to the GPLv3 license inherited from the LC Community project.
Yesterday I downloaded a number of Community Widgets and along the way read some posts by HH in 2020 detailing why he was ceasing to produce widgets : I paraphrase but he felt his suggestions about LCB were being ignored and his bug reports left unresolved.
Yes I remember HH was getting a bit cranky about it towards the end there on the forum and in some of his bug reports too, then he stopped, then unfortunately he died a short while later. But he left some amazing work to the community, liberally MIT licensed.
I also found a thread where LC and Python user Stam details the issues he ran into trying to build a new script widget. Simply it caused a slow down which attracted the attention of LC. However they were beaten to the solution by Bernd. See https://forums.livecode.com/viewtopic.p ... te#p225331 and an earlier post : https://forums.livecode.com/viewtopic.p ... te#p224936

"Script-Widgets" don't really apply here either, at least not unless we come up with our own system for doing that. Although I have been curious about how that might be implemented, I have a pretty good idea of how it could be. We can already created Script-Extension-Libraries.

I'm working on an xBuilder Editor that shows potential for taking out a bunch of the tedious bits of writing Widgets.

I might be able to help you with your Apple EventKit wrapper, if you share it here, explain the problem with it, like what got deprecated by Apple that broke it.
https://developer.apple.com/documentation/eventkit

Re: CustomControls - Style Guide ?

Posted: Fri Aug 23, 2024 4:26 pm
by Skids
I might be able to help you with your Apple EventKit wrapper, if you share it here, explain the problem with it, like what got deprecated by Apple that broke it.
Wildo once I return from holiday sometime next week. From memory when running on Sonoma the SIP calls require that the IDE contain a new line in the two plist files. While simple to add (its just a text file) editing the plist file then brakes the SIP of the IDE meaning it will not run: a this application is broken alert gets posted. The work around seems to be to create a new signature file (not sure if thats the correct term) and all is well.

Re: CustomControls - Style Guide ?

Posted: Fri Aug 23, 2024 9:34 pm
by OpenXTalkPaul
Skids wrote: Fri Aug 23, 2024 4:26 pm
I might be able to help you with your Apple EventKit wrapper, if you share it here, explain the problem with it, like what got deprecated by Apple that broke it.
Wildo once I return from holiday sometime next week. From memory when running on Sonoma the SIP calls require that the IDE contain a new line in the two plist files. While simple to add (its just a text file) editing the plist file then brakes the SIP of the IDE meaning it will not run: a this application is broken alert gets posted. The work around seems to be to create a new signature file (not sure if thats the correct term) and all is well.
AH, did you try the opposite? Stripping all code signing from the binaries of the app? There is still ability to run unsigned apps, and it should request the permission when EK API is called.
Also the EK API may have it's own way to request the needed permission on-the-fly. For using microphone / AVAudioRecording I had to use something similar. To do it the official-like way you probably need to codesign your app with a provisioning file that has the missing keys.

Re: CustomControls - Style Guide ?

Posted: Sun Aug 25, 2024 9:33 am
by Skids
Here is my latest version of my EkEventKit reader library extension along with a test stack that, if all is well, lists all the events in the user's calendar. As I wrote above Apple have just depreciated how permission to access the calendar data is obtained and this causes issues when running on OS Sonoma.

The library and test stack work fine when run in OXT DPE on OS Big Sur. I believe that when run under Sonoma any standalones will run but running within the IDE does not work unless some hoops are jumped through. These "hoops" are described in the dictionary entry about the calendar library (Follow these instructions at entirely your own risk!). The instructions call for an additional line to be added to two plist files within the IDE which is simple. Next the IDE needs resigning which is a little more of an issue.

Of course it is possible that it is not an issue at all from OXT.

best wishes

Simon
ReadCalendarEvents.lcb.zip
Reads Calendar Events
(10.04 KiB) Downloaded 74 times
Test_Dual_Access_to_Eventkit.oxtstack
Test stack that uses the ReadCalendarEvents Library
(54.36 KiB) Downloaded 73 times