Primer: How to load and use Builder extentions
Posted: Thu Oct 21, 2021 2:41 pm
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:
Extract the downloaded zip file somewhere on your computer.
Then open the developement environment and select the Tools menu -> Extention Builder
This will open the Extension Builder stack
Click the Folder Icon in the upper right corner to open an existing extension:
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:
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.
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:
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.
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.
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 (328.76 KiB) Viewed 49977 times
Then open the developement environment and select the Tools menu -> Extention Builder
- Step2-Open EXtention Builder.png (31.93 KiB) Viewed 49976 times
Click the Folder Icon in the upper right corner to open an existing extension:
- Step3-Open lcb file.png (101.5 KiB) Viewed 49975 times
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 (125.94 KiB) Viewed 49973 times
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 (49.67 KiB) Viewed 49970 times
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 (60.21 KiB) Viewed 49964 times
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 (196.51 KiB) Viewed 49965 times
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.
