[Library] Neutron.ahk - AutoHotkey Web GUIs on Steroids (now for v2!)

Post your working scripts, libraries and tools for AHK v1.1 and older
geek
Posts: 1052
Joined: 02 Oct 2013, 22:13
Location: GeekDude
Contact:

[Library] Neutron.ahk - AutoHotkey Web GUIs on Steroids (now for v2!)

04 Jun 2020, 00:06

Welcome to Neutron

See HERE for AHKv2!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Neutron provides a powerful set of tools for build HTML-based user interfaces with AutoHotkey. It leverages the Trident engine, known for its use in Internet Explorer, because of its deep integration with the Microsoft Windows operating system and its wide availability across systems.

Notable features:
  • Create GUIs with HTML, CSS, JS, and AHK all working together.
  • Make responsive user interfaces that reflow when you resize the window, and scroll when elements go out of view.
  • Full customization of the title bar including fonts and colors.
  • Make better looking interfaces easily with web frameworks like Bootstrap.
  • Compile resources into your script and access them without extracting. Very useful for including images in the script!
Image

Listen and watch about Neutron on YouTube, from the May 2020 webinar recording. This was for a very early version of Neutron but it still contains many of the core concepts.


Getting Started with Neutron

The Neutron library is designed to be minimally invasive, easily included into existing scripts without major modifications. Neutron GUIs are created and managed similarly to native AutoHotkey GUIs.

Code: Select all

; --- Creating a GUI ---
; Traditional syntax:
Gui, name:New,, title
Gui, name:Add, ...
; Neutron syntax:
name := new NeutronWindow("html", "css", "js", "title")
; or
name := new NeutronWindow("<!DOCTYPE html><html>full html document</html>")
; or
name := new NeutronWindow()
name.Load("file.html")

; --- Giving Window Options ---
; Traditional syntax:
Gui, name:+Option +Option
; Neutron syntax:
name.Gui("+Option +Option")

; --- Showing the GUI ---
; Traditional syntax:
Gui, name:Show, w800 h600
; Neutron syntax:
name.Show("w800 h600")

; --- Handling Events ---
; Traditional syntax:
Gui, name:+LabelNamedGui
return
NamedGuiClose:
NamedGuiEscape:
NamedGuiDropFiles:
MsgBox, Events!
return
; Neutron syntax:
name.Gui("+LabelNamedGui")
return
NamedGuiClose:
NamedGuiEscape:
NamedGuiDropFiles:
MsgBox, Events!
return

; --- Hiding the GUI ---
; Traditional syntax:
Gui, name:Hide
; Neutron syntax:
name.Hide()

; --- Destroying the GUI ---
; Traditional syntax:
Gui, name:Destroy
; Neutron syntax:
name.Destroy()
Because all controls are now created through the HTML you provide to Neutron, you're going to need a new way to set up event handlers like the button gLabels you may be familiar with from native GUIs. Neutron provides the HTML/JS with a way to call functions defined in your AutoHotkey source. This is a very convenient method to set up event handlers.

The AHK function will receive any parameters passed by the JavaScript, with an extra "neutron" parameter passed in first that contains the Neutron instance that triggered the event.

Code: Select all

neutron := new NeutronWindow("<button onclick='ahk.Clicked(event)'>Hi</button>")
neutron.Show()
return

Clicked(neutron, event)
{
    MsgBox, % "You clicked: " event.target.innerText
}
Neutron offers a number of shorthands and utility methods to make it easier to interact with the page from AutoHotkey. A non-exhaustive list of these is below:

Code: Select all

neutron := new NeutronWindow("<span>a</span><span>b</span><span>c</span>")

; neutron.doc
; Equivalent to "document" in JS, used to access page contents
MsgBox, % neutron.doc.body.outerHTML

; neutron.wnd
; Equivalent to "window" in JS, used to access JS functions and variables
neutron.wnd.alert("Hi")

; neutron.qs("CSS Selector")
; Equivalent to "document.querySelector" in JS
element := neutron.qs(".main span")

; neutron.qsa("CSS Selector")
; Equivalent to "document.querySelectorAll" in JS
elements := neutron.qsa(".main span")

; neutron.Each(collection)
; Allow enumeration of JS arrays / element collections
for index, element in neutron.Each(elements)
    MsgBox, % index ": " element.innerText

; neutron.GetFormData(formElement)
; More easily processing of form data
formData := neutron.GetFormData(formElement)
MsgBox, % formData.fieldName ; Pull a single field
for name, value in formData ; Iterate all fields
    MsgBox, %name%: %value%

; Escape values to place into HTML
; neutron.EscapeHTML("unsafe text")
neutron.qs(".main").innerHTML := "<div>" neutron.EscapeHTML("a<'&>z") "</div>"
; neutron.FormatHTML("format string", "unsafe text 1", "unsafe text 2", ...)
neutron.qs(".main").innerHTML := neutron.FormatHTML("<div>{}</div>", "a<'&>z")
There's plenty more to be learned about Neutron from browsing its source and examples. Neutron's source is commented with great detail, and many methods have full runnable usage examples in the comments alongside them.


Neutron Examples

Neutron comes with a few example scripts to demonstrate how to use the library in a variety of situations. None of them are a one-size-fits-all solution, but they can be a great starting point for building your own Neutron UIs.

Template

Complexity: 1 / 5
This example is designed to show how to use the default Neutron template page. Because it uses the default template, it is also the simplest example to use and tweak as a beginner. It is also designed to show how you would apply your own theming to the template without having to modify it directly, by applying CSS styling to the built-in template title bar elements.
Images

Complexity: 2 / 5
This example demonstrates displaying images through a tabbed multi-page interface. When compiled, this image gallery will stay contained in the exe file without having to extract the image resources to use them on the page.
Simple

Complexity: 2 / 5
This example, while named Simple, is not the most simplistic example. Instead, it is designed to demonstrate all of Neutron's built in behavior as a single custom page. It is meant to be simple by comparison to other examples like the Bootstrap example which demonstrate extending Neutron's functionality with third party web frameworks.
Bootstrap

Complexity: 4 / 5
This example is designed to show how you can use third party frameworks like Bootstrap to build advanced user interfaces, while still keeping all the code local. This script can be compiled and still function fine without the need to extract any files to a temporary directory. As this example is more advanced, it assumes a stronger familiarity with the technology and may gloss over some parts more than other examples. If you're just getting started it may be helpful to work with some of the other example scripts first.

Compiling Neutron Scripts

Some Neutron scripts may require many dependencies, such as HTML, CSS, JS, SVG, and image files. By following a few rules, your Neutron script can be compiled into a portable exe that contains all these dependencies internally, without needing to extract them to a temporary directory for use. Follow these rules to make your script work best when compiled:
  1. Any dependent files must be in the same directory as your AutoHotkey script file.
  2. Reference dependent files by name only, without any path portion.
    • In AHK: neutron.Load("index.html")
    • In HTML: <script src="index.js">, <link href="index.css" rel="stylesheet">, <img src="image.jpg">
  3. Have a FileInstall for each dependent file somewhere in the script. Put this somewhere that it won't be reached, such as just below the return after your auto-execute section.
When you do this, the dependent files will be saved into the EXE's RCDATA resources. Neutron's Load() method will detect when your script is compiled and read the dependencies from there instead of looking for files on the system.


Copyright Disclaimer

The core components of this library have been released under the MIT license, but some examples contain third party code where other or additional license restrictions may apply.

Examples/Bootstrap/bootstrap.min.css

Code: Select all

/*!
 * Bootstrap v4.5.0 (https://getbootstrap.com/)
 * Copyright 2011-2020 The Bootstrap Authors
 * Copyright 2011-2020 Twitter, Inc.
 * Licensed under MIT (https://github.com/twbs/bootstrap/blob/master/LICENSE)
 */
Examples/Bootstrap/bootstrap.min.js

Code: Select all

/*!
  * Bootstrap v4.3.1 (https://getbootstrap.com/)
  * Copyright 2011-2019 The Bootstrap Authors (https://github.com/twbs/bootstrap/graphs/contributors)
  * Licensed under MIT (https://github.com/twbs/bootstrap/blob/master/LICENSE)
  */
Examples/Bootstrap/jquery.min.js

Code: Select all

/*! jQuery v3.5.1 | (c) JS Foundation and other contributors | jquery.org/license */


Download Neutron
geek
Posts: 1052
Joined: 02 Oct 2013, 22:13
Location: GeekDude
Contact:

Re: [Library] Neutron.ahk - AutoHotkey Web GUIs on Steroids

04 Jun 2020, 00:21

A preview at what the examples look like when run:



See also, the CloudAHK Blocks editor (built with Neutron)

https://www.autohotkey.com/boards/viewtopic.php?p=335149#p335149

Image
r2997790
Posts: 71
Joined: 02 Feb 2017, 02:46

Re: [Library] Neutron.ahk - AutoHotkey Web GUIs on Steroids

04 Jun 2020, 00:53

Deeply impressive work, as ever GeekDude. Thank you for your contribution to helping make AHK evergreen and more awesome!
Helgef
Posts: 4709
Joined: 17 Jul 2016, 01:02
Contact:

Re: [Library] Neutron.ahk - AutoHotkey Web GUIs on Steroids

04 Jun 2020, 01:46

Looks really great, thanks for sharing.

Cheers :beer: .
BoBo
Posts: 6564
Joined: 13 May 2014, 17:15

Re: [Library] Neutron.ahk - AutoHotkey Web GUIs on Steroids

04 Jun 2020, 04:11

+1 :thumbup:


...
Tre4shunter
Posts: 139
Joined: 26 Jan 2016, 16:05

Re: [Library] Neutron.ahk - AutoHotkey Web GUIs on Steroids

04 Jun 2020, 07:33

Simply amazing stuff - thanks again G33kdude for all your work!
geek
Posts: 1052
Joined: 02 Oct 2013, 22:13
Location: GeekDude
Contact:

Re: [Library] Neutron.ahk - AutoHotkey Web GUIs on Steroids

04 Jun 2020, 07:49

BoBo wrote:
04 Jun 2020, 04:11
Will there be an option to use the full-blown JS 'wording'/terms ('querySelectorAll' vs 'qsa') instead of an 'every developers wet dream - spare as much chars as possible'-attempt? Like we all know from command line tools /c vs /close, /k vs /kiosk, /s vs /superduperlongparamname ... ?!!

I found myself in a situation (creating 'lean'-named functions) where I had to realize that several abbreviations would end up in duplicates and bc that won't work out, to end up with too many exceptions from the rule (no idea if that'll be the case with JS, just thinking about it). And I guess it would be a huge benefit (and attraction) for those who know JS from scratch - that they wouldn't have to re-learn an additional terminology if using Neutron. JM2€C

Thx for listening + and sharing that tool! :)
The full syntax would be neutron.wb.document.querySelector and neutron.wb.document.querySelectorAll. The middle-length syntax would be neutron.doc.querySelector and neutron.doc.querySelctorAll. I would recommend that if you do not want to use the shorthand function to use the middle-length syntax as it will continue to work in future versions, and can also be used to access other DOM methods like getElementBy*() and addEventListener().

:dance:
burque505
Posts: 1731
Joined: 22 Jan 2017, 19:37

Re: [Library] Neutron.ahk - AutoHotkey Web GUIs on Steroids

04 Jun 2020, 08:18

:bravo: Just ran all the examples, awesome indeed. Thank you!
Regards, burque505
Tre4shunter
Posts: 139
Joined: 26 Jan 2016, 16:05

Re: [Library] Neutron.ahk - AutoHotkey Web GUIs on Steroids

04 Jun 2020, 08:39

So - printing the document(html page) using neutron. Is this something that is possible, or maybe through a third party library like print.js? the only issue i see with print.js is that it cant be done without user interation i.e the print dialog will always appear. Do you know of any way to get around this?

i know the webbrowser control has a print() function available, but not sure how i would implement it using Neutron.
User avatar
Delta Pythagorean
Posts: 627
Joined: 13 Feb 2017, 13:44
Location: Somewhere in the US
Contact:

Re: [Library] Neutron.ahk - AutoHotkey Web GUIs on Steroids

05 Jun 2020, 16:03

Saw this on GitHub a few days before this thread was made, and I'm very interested in this.
I wonder if someday I could make it possible to create a sub-par version of the Discord desktop version or maybe a YouTube application.

[AHK]......: v2.0.12 | 64-bit
[OS].......: Windows 11 | 23H2 (OS Build: 22621.3296)
[GITHUB]...: github.com/DelPyth
[PAYPAL]...: paypal.me/DelPyth
[DISCORD]..: tophatcat

imustbeamoron
Posts: 44
Joined: 18 Aug 2016, 22:56

Re: [Library] Neutron.ahk - AutoHotkey Web GUIs on Steroids

05 Jun 2020, 20:48

Looks great GeekDude. thanks for sharing. Looking fwd to trying this out.
User avatar
moefr01
Posts: 115
Joined: 25 Nov 2015, 09:01
Location: Germany

Re: [Library] Neutron.ahk - AutoHotkey Web GUIs on Steroids

06 Jun 2020, 07:06

:bravo: Absolutely A W E S O M E . thx a lot GeekDude
I've tried your excellent examples and found out that the checkbox and radio-control didn't scale properly (very small) on a 4k-monitor with 200% desktop-scaling. +/-DPIScale couldn't fix that issue ...
Is there a possibility to get that fixed maybe within the css or html file ?
:wave: moefr01

==============================================================
fixed it ;)

simple.html > just added the following html-code to deal with the size of checkbox and radio-control at 200%-screen:

Code: Select all

/*** Generic Form Styling ***/
...
    input[type=checkbox],
    input[type=radio],
    setsize {
      width: 0.75em; 
      height: 0.75em;
    }
Attachments
after.PNG
after.PNG (36.5 KiB) Viewed 20465 times
before.PNG
before.PNG (35.05 KiB) Viewed 20465 times
Last edited by moefr01 on 20 Jun 2020, 10:24, edited 1 time in total.
ozzii
Posts: 481
Joined: 30 Oct 2013, 06:04

Re: [Library] Neutron.ahk - AutoHotkey Web GUIs on Steroids

07 Jun 2020, 05:36

R E A L L Y I M P R E S S I V E GeekDude.
Thanks
User avatar
joedf
Posts: 8940
Joined: 29 Sep 2013, 17:08
Location: Canada
Contact:

Re: [Library] Neutron.ahk - AutoHotkey Web GUIs on Steroids

21 Jun 2020, 12:39

Super neat work as always, geekdude! :bravo:

I've put a mention here, in the Web GUI tutorial:
https://www.autohotkey.com/boards/viewtopic.php?f=74&t=4588

I believe it is much cleaner and more powerful then WebApp.ahk
Image Image Image Image Image
Windows 10 x64 Professional, Intel i5-8500, NVIDIA GTX 1060 6GB, 2x16GB Kingston FURY Beast - DDR4 3200 MHz | [About Me] | [About the AHK Foundation] | [Courses on AutoHotkey]
[ASPDM - StdLib Distribution] | [Qonsole - Quake-like console emulator] | [LibCon - Autohotkey Console Library]
geek
Posts: 1052
Joined: 02 Oct 2013, 22:13
Location: GeekDude
Contact:

Re: [Library] Neutron.ahk - AutoHotkey Web GUIs on Steroids

21 Jun 2020, 18:35

Thanks for the shout out joedf!

Return to “Scripts and Functions (v1)”

Who is online

Users browsing this forum: Google [Bot] and 130 guests