porting from pGUI
xpGUI is the Phix Cross Platform Graphical User Interface, a planned replacement for pGUI.
Unlike pGUI, xpGUI will only contain js-compatible things, and perhaps some incompatible bits I actually need,
such as loading an image from disk so I can generate the equivalent (source code of a) constant that is js-compatible.
Likewise there is a general avoidance of any Windows-only or GTK-only appearance or functionality.
On Windows, uses the native windows API but can be made to use GTK, for testing purposes only (see gUseGTK).
On Linux, uses GTK and assumes that is already installed, and besides IUP does/did the same anyway.
In a web browser, uses pwa/xpGUI.js which is a laboriously and lovingly hand-crafted drop-in replacement.
The Windows part is based on Arwen (tougher than expected), pGUI.js only needs superficial mods, GTK began easy and got messy.
With a bit of luck, OpenGL/WebGL should only require the lightest of tweaks to make it [x]pGUI-agnostic, or an easy fork.
To minimise confusion, none/few of the Windows API, Arwen, GTK, or IUP-style globals/names are exposed or (re-)used, one
notable exception being VK_F1 (etc) of arwen (as per the aside here).
Implemented in demo\xpGUI\xpGUI.e for desktop/Phix and pwa\xpGUI.js for use under pwa/p2js.
and there is no longer either a global or per-dialog "PARENTDIALOG".
Some not insignificant refactoring may be required to ensure dialogs are created in the right order.
Many things have been simplified, unified and consolidated, for instance "just" gSetAttribute(), several attributes have been renamed and several controls have been dropped, and the use of normal first class routines as handlers instead of callbacks, all of which makes it a touch impractial to summarise everything properly on a/this single page. Should the old pGUI docs tag pwa/p2js as not supported, then like as not it probably won’t have made it into xpGUI.
The following mini-helper is intended to alleviate most of the tedious editing needed:
include builtins\xpGUI_from_pGUI.e
string res = xpGUI_from_pGUI(string src)
Should you copy some source code into the clipboard, run demo\xpGUI\gButton.exw, and click on the "port from pGUI" button, which should be disabled if the clipboard does not contain "include pGUI.e", and as next will be disabled as soon as you click it, then it updates the clipboard contents modified roughly as follows:
"include pGUI.e" is replaced with "requires(\"1.0.4\")\n" & "include xpGUI.e"
`IupOpen()` and `IupClose()` are simply deleted [xpGUI.e has a private and auto-invoked when actually needed xpg_Init() instead]
`IHandl(e|n)[s]` are replaced with `gdx` [note there is now only one gdx type, not four.]
`IupDialog` is replaced with `gDialog` (must manually specify any parent, when needed, after the child)
`"PARENTDIALOG"` is replaced with ?PARENTDIALOG? (as prior, needs further editing)
Likewise "MAP_CB" and "UNMAP_CB", since you can probably just delete those
`Iup(Set[Str]|Store)Attribute` are all replaced with `gSetAttribute`
`Icallback("xxx")` is replaced with `xxx` (quotes removed)
`IupSetCallback[s](` is replaced with `gSetHandler[s](?` (you’ll need to fixup quotes, remove call_back(), etc.)
`IupXxxx` is replaced with `gXxxx` (a dirty great big long list, probably forever incomplete)
[maybe] `cdXxxx` is replaced with `gXxxx` (ditto [we really really can’t just "cd"->"g", obvs.])
`"XXX_CB"` is replaced with `"XXX"` (ditto, plus `"K_ANY"` -> `"KEY"`)
`IUP_` is replaced with `XPG_` (blanket, unverified)
`K_` is replaced with `VK_` (only if prev char is non-alphanumeric, verified)
More tweaks may/will be added as necessary. (it’ll probably never be totally finished/perfected)
I also plan to incorporate similar into the new demo\Edita\xpEditer.exw if that ever gets going properly, and/or Edita/Edix if not.
(Mind you, should xpEditer.exw somehow fail to become a reality, by 2024|5, then I’ll consider xpGUI an abject failure...)
Note that the gRadio() of xpGUI is quite different to the IupRadio() of pGUI, and that will need to be manually changed. Typically you should get/expect an error that gRadio() is not a function, since it isn’t. See demo\xpGUI\gRadio.exw for an example. Ditto IupNormalizer/gNormalise.
Attribute inheritance has been replaced with recursive application in a few places, but largely dropped and in any case would require a manual attribute-specific reimplementation in xpGUI, so don’t be too surprised if/when that needs a few tweaks.
Obviously there is no guarantee or even likelihood of the result running without any further changes, in fact at least a dozen things deliberately trigger compilation errors that need to be manually fixed up (List/DropDown/Menu amongst the most likely), and no apologies whatsoever should you clobber the only working version you have without making an adequate backup first.
crash(`setHandler(Canvas,"ACTION",rtn) should be changed to "REDRAW"`)
(obviously I’ll give it my best shot, but no doubt some will be missed and some will just be too tricky)
and you should take appropriate care to ensure any required associated updates are also made, as follows:
Unlike pGUI, xpGUI will only contain js-compatible things, and perhaps some incompatible bits I actually need,
such as loading an image from disk so I can generate the equivalent (source code of a) constant that is js-compatible.
Likewise there is a general avoidance of any Windows-only or GTK-only appearance or functionality.
On Windows, uses the native windows API but can be made to use GTK, for testing purposes only (see gUseGTK).
On Linux, uses GTK and assumes that is already installed, and besides IUP does/did the same anyway.
In a web browser, uses pwa/xpGUI.js which is a laboriously and lovingly hand-crafted drop-in replacement.
The Windows part is based on Arwen (tougher than expected), pGUI.js only needs superficial mods, GTK began easy and got messy.
With a bit of luck, OpenGL/WebGL should only require the lightest of tweaks to make it [x]pGUI-agnostic, or an easy fork.
To minimise confusion, none/few of the Windows API, Arwen, GTK, or IUP-style globals/names are exposed or (re-)used, one
notable exception being VK_F1 (etc) of arwen (as per the aside here).
Implemented in demo\xpGUI\xpGUI.e for desktop/Phix and pwa\xpGUI.js for use under pwa/p2js.
porting from pGUI to xpGUI
The single biggest change is that any parent must be specified up-front on gDialog() (nee IupDialog()),and there is no longer either a global or per-dialog "PARENTDIALOG".
Some not insignificant refactoring may be required to ensure dialogs are created in the right order.
Many things have been simplified, unified and consolidated, for instance "just" gSetAttribute(), several attributes have been renamed and several controls have been dropped, and the use of normal first class routines as handlers instead of callbacks, all of which makes it a touch impractial to summarise everything properly on a/this single page. Should the old pGUI docs tag pwa/p2js as not supported, then like as not it probably won’t have made it into xpGUI.
The following mini-helper is intended to alleviate most of the tedious editing needed:
include builtins\xpGUI_from_pGUI.e
string res = xpGUI_from_pGUI(string src)
Should you copy some source code into the clipboard, run demo\xpGUI\gButton.exw, and click on the "port from pGUI" button, which should be disabled if the clipboard does not contain "include pGUI.e", and as next will be disabled as soon as you click it, then it updates the clipboard contents modified roughly as follows:
"include pGUI.e" is replaced with "requires(\"1.0.4\")\n" & "include xpGUI.e"
`IupOpen()` and `IupClose()` are simply deleted [xpGUI.e has a private and auto-invoked when actually needed xpg_Init() instead]
`IHandl(e|n)[s]` are replaced with `gdx` [note there is now only one gdx type, not four.]
`IupDialog` is replaced with `gDialog` (must manually specify any parent, when needed, after the child)
`"PARENTDIALOG"` is replaced with ?PARENTDIALOG? (as prior, needs further editing)
Likewise "MAP_CB" and "UNMAP_CB", since you can probably just delete those
`Iup(Set[Str]|Store)Attribute` are all replaced with `gSetAttribute`
`Icallback("xxx")` is replaced with `xxx` (quotes removed)
`IupSetCallback[s](` is replaced with `gSetHandler[s](?` (you’ll need to fixup quotes, remove call_back(), etc.)
`IupXxxx` is replaced with `gXxxx` (a dirty great big long list, probably forever incomplete)
[maybe] `cdXxxx` is replaced with `gXxxx` (ditto [we really really can’t just "cd"->"g", obvs.])
`"XXX_CB"` is replaced with `"XXX"` (ditto, plus `"K_ANY"` -> `"KEY"`)
`IUP_` is replaced with `XPG_` (blanket, unverified)
`K_` is replaced with `VK_` (only if prev char is non-alphanumeric, verified)
More tweaks may/will be added as necessary. (it’ll probably never be totally finished/perfected)
I also plan to incorporate similar into the new demo\Edita\xpEditer.exw if that ever gets going properly, and/or Edita/Edix if not.
(Mind you, should xpEditer.exw somehow fail to become a reality, by 2024|5, then I’ll consider xpGUI an abject failure...)
Note that the gRadio() of xpGUI is quite different to the IupRadio() of pGUI, and that will need to be manually changed. Typically you should get/expect an error that gRadio() is not a function, since it isn’t. See demo\xpGUI\gRadio.exw for an example. Ditto IupNormalizer/gNormalise.
Attribute inheritance has been replaced with recursive application in a few places, but largely dropped and in any case would require a manual attribute-specific reimplementation in xpGUI, so don’t be too surprised if/when that needs a few tweaks.
Obviously there is no guarantee or even likelihood of the result running without any further changes, in fact at least a dozen things deliberately trigger compilation errors that need to be manually fixed up (List/DropDown/Menu amongst the most likely), and no apologies whatsoever should you clobber the only working version you have without making an adequate backup first.
Handler changes
Several run-time errors, specifically designed to assist in the porting process, can also occur in xpGUI.e such ascrash(`setHandler(Canvas,"ACTION",rtn) should be changed to "REDRAW"`)
(obviously I’ll give it my best shot, but no doubt some will be missed and some will just be too tricky)
and you should take appropriate care to ensure any required associated updates are also made, as follows:
| Affects | pGUI name | xpGUI name | Notes |
|---|---|---|---|
| gCanvas | "ACTION" | "REDRAW" | The callback function has now become a procedure instead |
| gCheckbox | "ACTION" | "VALUE_CHANGED" | Just a more intuitive name, and the callback has also become a procedure. |
| gText | "ACTION" | "VALUE_CHANGED" | Again a more intuitive name, but this one is still a function. |