Primer: How to load and use Builder extentions

How to USE and/or how to create eXTension Builder Libraries and Custom UI Widgets
Post Reply
User avatar
OpenXTalkPaul
Posts: 2391
Joined: Sat Sep 11, 2021 4:19 pm
Contact:

Primer: How to load and use Builder extentions

Post by OpenXTalkPaul »

So it's occurred to me on several occasions that a lot of the existing user base knows very little about Builder extensions which have been part of the development environment since version 8. I'm not entirely sure why that is. Personally I was 'chomping at the bit' for it to be released after it was crowd-funded in "Infinite LiveCode". I think it's the best thing to happen to xTalk since Frederic Rinaldi (old timers might remember him) or maybe since CompileIt! for HyperCard!

So my hope is that this workshop sub-forum will help people get into at least be able to use Builder extensions, if not also be able to create them!

Here's a quick tutorial on downloading and loaded an existing Builder extension into the IDE.
You can find a few to try out in my Github repos (link in my signature)

I'll use this one as an example, because it's a GUI widget and it should work on any supported platform:
https://github.com/PaulMcClernan/LCB_VirtualDPad

I haven't made an official release package for this repo, but you can still download it and use it.
Download the repo as pictured:
Step1-Download.png
Step1-Download.png (328.76 KiB) Viewed 23435 times
Extract the downloaded zip file somewhere on your computer.
Then open the developement environment and select the Tools menu -> Extention Builder
Step2-Open EXtention Builder.png
Step2-Open EXtention Builder.png (31.93 KiB) Viewed 23434 times
This will open the Extension Builder stack
Click the Folder Icon in the upper right corner to open an existing extension:
Step3-Open lcb file.png
Step3-Open lcb file.png (101.5 KiB) Viewed 23433 times
An open file dialog box will appear. Navigate to where you unzipped the project folder and open the .lcb file in that folder.
IMPORTANT: There can be only one .lcb file per folder, otherwise the compiler gets confused and gives an incorrect error that it can't find any extensions at all!

Now you're ready to load the extension:
Step4-Compile & Load.png
Step4-Compile & Load.png (125.94 KiB) Viewed 23431 times
Extension Builder can either temporarily test compile & load the Builder extension
OR Install the Builder extension into the IDE / Dictionary.
NOTE: You may have to restart the IDE for the new handlers to show up in the dictionary.

When you install an extension into the IDE in this way, it goes into your "My OpenXTalk" folder in your user directory, rather than into the IDE itself. Only the extensions that were included in the release, such as the now extensively used by the IDE "SVG Icon", are in the IDE folder.

If you test load the extension it gets compiled and temporarily loaded into memory. I don't think the entries for any newly available handlers get added to the dictionary if you test load, only if you actually install.

If the extension is a widget it will automatically make a new temporary stack with an instance of the widget placed on it.
Screen Shot 2021-10-21 at 11.07.50 AM.png
Screen Shot 2021-10-21 at 11.07.50 AM.png (49.67 KiB) Viewed 23428 times
That's about all there is to loading a new Builder extension!

You may notice that there are other files in a Builder project folder.
Most of these additional files are going to be ones that are automatically generated from the .lcb file when it gets compiled.

For example, if the .lcb file has documentation integrated in-line with its code, then a api.lcdoc file will be created, which gets used to automatically add the extensions new syntax to the Dictionary, Alternatively, if they choose to, an extension author could manually maintain the api.lcdoc file separately from the .lcb source file.

There may be a code folder with subfolders for different platforms/cpu architectures. If present these would contain any dynamically loaded shared foreign code libraries that the Builder extension may require for its functionality.
It would look something like this:
Screen Shot 2021-10-21 at 11.26.28 AM.png
Screen Shot 2021-10-21 at 11.26.28 AM.png (60.21 KiB) Viewed 23422 times
If there is a samples folder, that would contain any demonstration stacks to show how to use the extensions features.
If there is a support folder that may contain resources such as png icons files or a defaultscript script-only stack that has pre-made scripts for use with the extension. When setup correctly, these pre-made scripts are available for click-adding to a widgets scripts, and appear on the left side of the Script Editor window in the same way that built in controls such as buttons have pre-made handlers for mouesDown, mouseUp, etc.
Screen Shot 2021-10-21 at 11.46.58 AM.png
Screen Shot 2021-10-21 at 11.46.58 AM.png (196.51 KiB) Viewed 23423 times
NOTE: My own Builder repos often contain a LOT of extra files, that aren't needed for using these extension. These projects are all works-in-progress, and so I keep things like graphic design files, or web browser links to related API documentation, in my repos for syncing changes and easy access from whatever computer I'm using while working on them.

Also NOTE: I'm currently renaming & changing the identifiers of my Builder extensions to org.oxt.paulmcclernan.extention_name_here because I was thinking we might be including some of these, pre-installed into the IDE for a release of OXT.
User avatar
richmond62
Posts: 4239
Joined: Sun Sep 12, 2021 11:03 am
Location: Bulgaria
Contact:

Re: Primer: How to load and use Builder extentions

Post by richmond62 »

So: I followed all those instructions and could subsequently NOT locate
any folder on my computer called "My OpenXTalk" nor any sign of the
extension showing up in the IDE in any way whatsoever.

MacOS 12.0.1
https://richmondmathewson.owlstown.net/
User avatar
OpenXTalkPaul
Posts: 2391
Joined: Sat Sep 11, 2021 4:19 pm
Contact:

Re: Primer: How to load and use Builder extentions

Post by OpenXTalkPaul »

richmond62 wrote: Thu Oct 21, 2021 5:12 pm So: I followed all those instructions and could subsequently NOT locate
any folder on my computer called "My OpenXTalk"
Ah...well that's probably because you're not using my OpenXTalk modified bits of the IDE, one of those mods creates the "My OpenXtalk" (instead of creating a "My LiveCode") folder, which on macOS would be in /Users/YourUserName/Documents/

NOTE: If you ARE using my modded IDE scripts from the IDE repo, then you may have to reset your preferences in the OXT IDE, I had to do that several times while working on modding them.

Alternatively, you could use LC Community, in which case the new extensions would be installed to the "My LiveCode" folder. But like I said in the instructions, you don't need to install it to try out a Builder extension, you can temporarily test load/unload from the Extension Builder stack without actually installing the extension. While developing these extensions I've spent a lot of the time doing just that (load/test/unload/fix mistakes/repeat/).
richmond62 wrote: Thu Oct 21, 2021 5:12 pm nor any sign of the
extension showing up in the IDE in any way whatsoever.
A Widget should show up right away in an automatically created test stack, but a Builder Library isn't going to show up because it doesn't (usually) have any GUI to show.

They should show in the list view of either Widget or Library tab of the Extension Manager stack (right above the Extension Builder in the Tools Menu)
Screen Shot 2021-10-22 at 6.05.02 PM.png
Screen Shot 2021-10-22 at 6.05.02 PM.png (1.28 MiB) Viewed 23380 times
Another way to check that an extension is actually loaded into memory is to

Code: Select all

put the loadedExtensions
, which returns a line delimited list of the Builder extensions that are loaded.

There's actually a bunch of handlers for dealing with Builder Extensions but they aren't included in the Dictionary of LCC.
They ARE included the OTX Dictionary though ;)
Screen Shot 2021-10-22 at 5.57.06 PM.png
Screen Shot 2021-10-22 at 5.57.06 PM.png (1.99 MiB) Viewed 23383 times
User avatar
overclockedmind
Posts: 362
Joined: Sat Apr 30, 2022 9:05 pm
Location: Midwest US
Contact:

Re: Primer: How to load and use Builder extentions

Post by overclockedmind »

OpenXTalkPaul wrote: Fri Oct 22, 2021 8:32 pm
richmond62 wrote: Thu Oct 21, 2021 5:12 pm So: I followed all those instructions and could subsequently NOT locate
any folder on my computer called "My OpenXTalk"
Ah...well that's probably because you're not using my OpenXTalk modified bits of the IDE, one of those mods creates the "My OpenXtalk" (instead of creating a "My LiveCode") folder, which on macOS would be in /Users/YourUserName/Documents/

NOTE: If you ARE using my modded IDE scripts from the IDE repo, then you may have to reset your preferences in the OXT IDE, I had to do that several times while working on modding them.

Alternatively, you could use LC Community, in which case the new extensions would be installed to the "My LiveCode" folder. But like I said in the instructions, you don't need to install it to try out a Builder extension, you can temporarily test load/unload from the Extension Builder stack without actually installing the extension. While developing these extensions I've spent a lot of the time doing just that (load/test/unload/fix mistakes/repeat/).
richmond62 wrote: Thu Oct 21, 2021 5:12 pm nor any sign of the
extension showing up in the IDE in any way whatsoever.
A Widget should show up right away in an automatically created test stack, but a Builder Library isn't going to show up because it doesn't (usually) have any GUI to show.

They should show in the list view of either Widget or Library tab of the Extension Manager stack (right above the Extension Builder in the Tools Menu)

Screen Shot 2021-10-22 at 6.05.02 PM.png

Another way to check that an extension is actually loaded into memory is to

Code: Select all

put the loadedExtensions
, which returns a line delimited list of the Builder extensions that are loaded.

There's actually a bunch of handlers for dealing with Builder Extensions but they aren't included in the Dictionary of LCC.
They ARE included the OTX Dictionary though ;)

Screen Shot 2021-10-22 at 5.57.06 PM.png
Bonkers... it's like the XCMDs had children all over every available OS :)
System76 serv12 (64GB RAM, 2TB SSD, 2TB HD, Win10 Pro, Current)
MBA (Early 2015, 8GB/512G SSD, Monterey 12.7.2 and Linux Mint)
User avatar
OpenXTalkPaul
Posts: 2391
Joined: Sat Sep 11, 2021 4:19 pm
Contact:

Re: Primer: How to load and use Builder extentions

Post by OpenXTalkPaul »

overclockedmind wrote: Sat May 28, 2022 5:29 am
OpenXTalkPaul wrote: Fri Oct 22, 2021 8:32 pm Another way to check that an extension is actually loaded into memory is to

Code: Select all

put the loadedExtensions
, which returns a line delimited list of the Builder extensions that are loaded.

There's actually a bunch of handlers for dealing with Builder Extensions but they aren't included in the Dictionary of LCC.
They ARE included the OTX Dictionary though ;)

Screen Shot 2021-10-22 at 5.57.06 PM.png
Bonkers... it's like the XCMDs had children all over every available OS :)
Right!
I think it might be more accurate to say that Heizer's Compile-It!, XFNCs/XCMDs, xTalk and Pascal (Extension Builder Language variant has statically typed variables and such) produced grandchildren.
Plus there's also included useful pre-wrapped lib, (most of) the Skia canvas drawing library (also used in some web browsers), that's mostly been used for rendering custom controls (widgets) such as my Piano Widget, which I'm including with OpenXTalk Don't Panic Edition along with a FluidSynth wrapper and "General Music" script library in order to reinstate HyperCard-style ABC musical notation with sampled sound playback into the xTalk sphere.
User avatar
overclockedmind
Posts: 362
Joined: Sat Apr 30, 2022 9:05 pm
Location: Midwest US
Contact:

Re: Primer: How to load and use Builder extentions

Post by overclockedmind »

OpenXTalkPaul wrote: Mon May 30, 2022 4:25 pm
overclockedmind wrote: Sat May 28, 2022 5:29 am
OpenXTalkPaul wrote: Fri Oct 22, 2021 8:32 pm Another way to check that an extension is actually loaded into memory is to

Code: Select all

put the loadedExtensions
, which returns a line delimited list of the Builder extensions that are loaded.

There's actually a bunch of handlers for dealing with Builder Extensions but they aren't included in the Dictionary of LCC.
They ARE included the OTX Dictionary though ;)

Screen Shot 2021-10-22 at 5.57.06 PM.png
Bonkers... it's like the XCMDs had children all over every available OS :)
Right!
I think it might be more accurate to say that Heizer's Compile-It!, XFNCs/XCMDs, xTalk and Pascal (Extension Builder Language variant has statically typed variables and such) produced grandchildren.
Plus there's also included useful pre-wrapped lib, (most of) the Skia canvas drawing library (also used in some web browsers), that's mostly been used for rendering custom controls (widgets) such as my Piano Widget, which I'm including with OpenXTalk Don't Panic Edition along with a FluidSynth wrapper and "General Music" script library in order to reinstate HyperCard-style ABC musical notation with sampled sound playback into the xTalk sphere.
That's what I used to create my alarm clock. (HyperCard's sample playback,) hooked to the speakers of my TV; I had the frequency cranked so high it sounded like a fire alarm, until I added the bit to make the notes meander up or down just a bit.) Sorry everyone else in the house, Dad has to work today...

And to this day, I still think that way. Why go download something when I can break out something of my own?
System76 serv12 (64GB RAM, 2TB SSD, 2TB HD, Win10 Pro, Current)
MBA (Early 2015, 8GB/512G SSD, Monterey 12.7.2 and Linux Mint)
User avatar
OpenXTalkPaul
Posts: 2391
Joined: Sat Sep 11, 2021 4:19 pm
Contact:

Re: Primer: How to load and use Builder extentions

Post by OpenXTalkPaul »

overclockedmind wrote: Tue May 31, 2022 4:16 am
OpenXTalkPaul wrote: Mon May 30, 2022 4:25 pm Right!
I think it might be more accurate to say that Heizer's Compile-It!, XFNCs/XCMDs, xTalk and Pascal (Extension Builder Language variant has statically typed variables and such) produced grandchildren.
Plus there's also included useful pre-wrapped lib, (most of) the Skia canvas drawing library (also used in some web browsers), that's mostly been used for rendering custom controls (widgets) such as my Piano Widget, which I'm including with OpenXTalk Don't Panic Edition along with a FluidSynth wrapper and "General Music" script library in order to reinstate HyperCard-style ABC musical notation with sampled sound playback into the xTalk sphere.
That's what I used to create my alarm clock. (HyperCard's sample playback,) hooked to the speakers of my TV; I had the frequency cranked so high it sounded like a fire alarm, until I added the bit to make the notes meander up or down just a bit.) Sorry everyone else in the house, Dad has to work today...

And to this day, I still think that way. Why go download something when I can break out something of my own?
When I found out about LiveCode (some time around 2013-14) the first thing I did was put a Play "Piano" [PlaySentence] into the message box and was instantly disappointed when no sound came out of the speakers! It's been a goal for me to enable that ever since (and I'm just about there). It's an instant-gratification feature, and as you pointed out can have practical uses, such as a musical alarm clock, ear training for musicians, someone was telling me they were interested in FluidSynth (which can 'bend' sample pitches into very high and low frequencies) to use in testing speakers. I've used it (and my other MIDI related extensions) both as a realtime musical instrument, and for experimenting with algorithmic composition.
User avatar
overclockedmind
Posts: 362
Joined: Sat Apr 30, 2022 9:05 pm
Location: Midwest US
Contact:

Re: Primer: How to load and use Builder extentions

Post by overclockedmind »

Absolutely hilarious, and why I added the bit of code for a note to occasionally be slightly off-tune. I'm a musician as well, and my tuning ear would go completely bonkers on sour notes, even if they were that high of a pitch! :lol:

I'm sure I will enjoy what you're working on, I have a keyboard with MIDI I've been dying to connect to a computer for *some* reason! (I'm not a piano player though, primarily bass guitar.)
Regards,
Joshua
System76 serv12 (64GB RAM, 2TB SSD, 2TB HD, Win10 Pro, Current)
MBA (Early 2015, 8GB/512G SSD, Monterey 12.7.2 and Linux Mint)
User avatar
richmond62
Posts: 4239
Joined: Sun Sep 12, 2021 11:03 am
Location: Bulgaria
Contact:

Re: Primer: How to load and use Builder extentions

Post by richmond62 »

Every now and then I turn on my BBC Model B:
-
BBCDE1.jpeg
BBCDE1.jpeg (40.69 KiB) Viewed 22766 times
-
and get it to play some music.

BBC BASIC has 4 sound channels.

That's not mine: mine is jacked into a very cheap flat-screen telly with a coaxial cable.
-
Now, as my BBC computer sports 32 KB RAM (saves to a cassette tape), and it has BBC BASIC on a chip, I really wonder
why 'Kev' and the boy scouts couldn't have managed the music-thing that was 'there' in HyperCard.
https://richmondmathewson.owlstown.net/
User avatar
OpenXTalkPaul
Posts: 2391
Joined: Sat Sep 11, 2021 4:19 pm
Contact:

Re: Primer: How to load and use Builder extentions

Post by OpenXTalkPaul »

Damn it!

I just accidentally deleted a really long post, listing a lot of details about General Music lib, libFluidSynth, and CoreMIDI libraries. I was accidentally (admin) editing Joshuas's post instead of quoting it, then messed up trying to correct my mistake. Bottom line is it's fairly extensive, cross platform support, simple to use, should require no setup at all on the IDE user's part. Recording MIDI-in is still a bit sketchy though (will probably have to implement sequencer object features).

I'm too tired and aching (COVID) to retype that all out right now, probably better to put that info into a demo stack anyway.
User avatar
OpenXTalkPaul
Posts: 2391
Joined: Sat Sep 11, 2021 4:19 pm
Contact:

Re: Primer: How to load and use Builder extentions

Post by OpenXTalkPaul »

richmond62 wrote: Fri Jun 03, 2022 6:50 am Every now and then I turn on my BBC Model B:
-
BBCDE1.jpeg
-
and get it to play some music.

BBC BASIC has 4 sound channels.

That's not mine: mine is jacked into a very cheap flat-screen telly with a coaxial cable.
-
Now, as my BBC computer sports 32 KB RAM (saves to a cassette tape), and it has BBC BASIC on a chip, I really wonder
why 'Kev' and the boy scouts couldn't have managed the music-thing that was 'there' in HyperCard.
To be fair, it was missing in MetaCard too, omitted long before RunRev/LC people got involved.

OpenXION has it, it uses whatever sound synth that Oracle supplies in their JVM.

SuperCard has it too.

Someone did create a (Mac only / commercial license only) MIDI external (not an extension) for RunRev/LC called sunnYmidi about 10 years ago. I've only seen video / screens of it, so I can't really offer a review.

UDI's makeSMF library (Public Domain and I've incorporated it into "General Music" lib ) should work under most xTalk engines. It was created in the late 1990s, before RunRev. That does the HC-ABC-style notation to MIDI data conversion, then you pass that data to a playback engine (could be QuickTime, an external CLI app, MS MCI command, etc.). It works practically in realtime, even on my old, old Android phone (Android 2.x - 4.x) where you can play the MIDI using 'play videoClip' through Android's default (Yamaha I think) soundbank.
User avatar
overclockedmind
Posts: 362
Joined: Sat Apr 30, 2022 9:05 pm
Location: Midwest US
Contact:

Re: Primer: How to load and use Builder extentions

Post by overclockedmind »

https://www.musicainformatica.org/resou ... estosa.php

I used to use this program, before I had a MIDI controller or a MIDI-compatible device... via the "piano scroll" view, putting in a note at a time. I must have had a lot of free time :lol:
System76 serv12 (64GB RAM, 2TB SSD, 2TB HD, Win10 Pro, Current)
MBA (Early 2015, 8GB/512G SSD, Monterey 12.7.2 and Linux Mint)
User avatar
OpenXTalkPaul
Posts: 2391
Joined: Sat Sep 11, 2021 4:19 pm
Contact:

Re: Primer: How to load and use Builder extentions

Post by OpenXTalkPaul »

overclockedmind wrote: Sun Jun 05, 2022 5:37 am https://www.musicainformatica.org/resou ... estosa.php

I used to use this program, before I had a MIDI controller or a MIDI-compatible device... via the "piano scroll" view, putting in a note at a time. I must have had a lot of free time :lol:
Cool, I've tried that one and a lot of others. MuseScore is pretty good (and free) too...

I created a widget grid framework, which one of the intended use-cases is as a Piano-Roll style grid (I've already used that way). For traditional graphical music notation symbols, I intend to add and SVG icon set, already have some basic vector art (Notes/Rests symbols). My Piano Widget can be used to animate playback. 'Step-writing' facilities, but I'm also very interested in the realtime aspects. I worked on several other extensions (Apple only), CoreMIDI and ones that can load AudioUnit plug-ins (like Mac version of VSTs). The goal being to allow access some higher-end software synths and fx from your scripts and communicating with DAWs / external things. There's video demos of some of the music stuff, which I made like a year or more ago, on my YouTube channels.

Lots more work to do in those, but for now I'm just trying to get the HC-ABC notation as a base-line feature on all the platforms and get the whole 'OXT' IDE out to people for testing.
Post Reply

Who is online

Users browsing this forum: No registered users and 1 guest