# xpGUI

xpGUI is the Phix Cross Platform Graphical User Interface.

- Easy to learn and use - the API was inspired by that of IUP but is even simpler.
  At the time of writing xpGUI (but not including OpenGL) has just 88 entry points and 148 global constants,
  plus to be fair (but still not including OpenGL) at least 27 named handlers and 114 named attributes, a
  combined total of just 377, which must make it one of the smallest and easiest ever. In comparison:
  pGUI (which it is intended to replace) has ~450 entry points, 490 global constants, over 70 named handlers
  and well over 500 named attributes, which makes it about 1,510 in all (w/o OpenGL).
  The GTK3 dlls contain (I can back this up) at least 21,774 public entry points - and that’s not including any
  of an equally frankly frightening number of constants, structures, and callbacks (or OpenGL).
  The mini.chm I built ages ago from MSDN has 22,451 pages and indexes 12,135 things from WinAPI, no
  OpenGL, and not all of which is going to be GUI related, though fwiw my gut instincts say maybe around ⅔ is.
  The JavaScript DOM might actually boil down to something more reasonable, all I can say is that my time in
  the browser development tools is generally utterly dominated by paging through seemingly endless
  screenfuls of functions and attributes and nested prototypes on each and every element node.
  Of course (other search engines/sites exist) googling things and searching StackOverflow is pretty easy, but
  generally speaking for the most part only after you already know the names of things to look for.
  The whole point of xpGUI is not so much to be complete, but instead easy to fix and extend. It may not have all
  the bells and whistles, however I reject the premise that a "proper" API must be tortuously complicated and
  difficult and confusing to make it flexible and powerful.
- Minimal dependencies - requires a working GTK install on Linux, or just a Windows OS, or just a working browser.
  I should probably admit that all development and testing has occurred on a Windows 10 box (plus VirtualBox).
  Oh, you do actually need some kind of computing device, and it currently has to have an x86/64 chip inside,
  though one of the main motivations for starting it was making ARM a worthwhile target for Phix version 2.
- Zero build overhead - no additional compiler/toolchain needed, just edit & go.
  Of course some bugs may be difficult to find/remedy, but if you can edit the xpGUI source code, you’re done,
  unless you need the same fix in both xpGUI.e and xpGUI.js, which is (hopefully) also a pretty trivial step.

### Example

    include xpGUI.e
    gdx lbl = gLabel(`This is a label`),
        box = gHbox({lbl},`MARGIN=13x13`),
        dlg = gDialog(box,`gLabel`,`SIZE=240x60`)
    gShow(dlg)
    gMainLoop()

For the whirlwind aerial tour, visit Elements and click on each of the 21 images to see the code that made it.
You should also be able to run Phix\pdemo.exw (currently still pGUI), filter on xpGUI.e, and run each of the examples that shows.
You may also want to run demo\Edita\xpEditer.exw to see where that’s at.

### Roadmap / todo

The all-important layout manager has finally gurgled into life, but probably still needs quite a bit of finessing, esp margins, gaps, etc.
All element sizes must be known/stored pixel-perfect, even/esp when they differ between the different backends (bugs can be hard to spot).
Last few elements: gImage variants, gDatePick under GTK (needs layout manager first)...
All attributes with a ? next to them still need actually implementing or at least thorough testing.
Anything with ?? next to it means "" and/or that documentation entry may yet need completely rewriting.
I still regularly break things, but at least that is significantly improving my delta debugging skills.
demo\xpGUI\scroller.exw uses 100% fake scrollbars, similar may be needed elsewhere to overcome (eg) GTK obstinacy.
Add SCROLLSIZE and VIEWPORT handling to gList and gTable (fully automatic), and possibly gGraph (when explicitly set).
Work on integrating with OpenGL not started at all, but hopefully that should prove reasonably superficial.
Speaking of integrating, pdemo should probably also allow open in p2js, or via that in browser (as well as desktop/Phix).
xpGUI.js is always likely to lag behind xpGUI.e: in my experience desktop->browser is far easier than browser-first.
Ultimately, this paves the way for Phix on ARM, since with no viable GUI that would be pretty pointless.

### Immediate plans

1. gDatePick: write a (simple) hll version for GTK, initially in demo\xpGUI\gDatePick.exw.
2. gList: selected line with background colour, then mouse/keyboard handling (first steps)
3. gTable: "", and probably needs to be made more like the gList API
4. gTabs: insert/delete/swap tabs (probably a complete rewrite/redesign)
5. gTreeview: allow "no icons", and/or app-provided ones
6. xpEditer: needs above gList/gTabs fixing, along with some further fixes to the layout manager
7. log api calls/unit testing - g_proc/g_func?
8. rewriting gCanvasArc() with similar innards to gCanvasPolygon() for WinAPI is a tedious but necessary chore.

### Licence

As stated in the introduction. You may freely use xpGUI in an otherwise closed source commercial proprietary application, but any modifications, bugfixes, and enhancements to xpGUI itself must be made public - besides you probably would not want to have to manually re-apply any such changes to every new release.