ref: 488cbb480ec16eb03431f7b491275229b368c307
parent: 3afb1d0db57feeada8fb704a45c2b6cd55219f2f
author: kvik <kvik@a-b.xyz>
date: Thu Oct 29 13:16:58 EDT 2020
programming-gui: add article from old wiki (thanks Amavect)
--- /dev/null
+++ b/programming-gui.md
@@ -1,0 +1,341 @@
+# Writing Interactive Graphical Programs
+
+This tutorial will explain how to write an interactive graphical
+program for 9front using libdraw and libthread, written especially for
+beginning programmers.
+
+Some alternative, contributed, graphical libraries not covered here:
+
+* [microui](https://github.com/ftrvxmtrx/microui)
+* [libnuklear](https://github.com/Plan9-Archive/libnuklear)
+* [nuklear-demo](https://github.com/Plan9-Archive/nuklear-demo)
+
+## The man Pages
+
+The important man pages are as follows. Please read up before
+continuing, even if you don't fully understand what they mean.
+
+* _graphics(2)_
+* _draw(2)_
+* _allocimage(2)_
+* _addpt(2)_
+* _thread(2)_
+* _mouse(2)_
+* _keyboard(2)_
+
+Other useful man pages are listed in the See Also section of _graphics(2)_.
+
+## Draw Something Simple
+
+Before we can draw, we need to set up all of the boilerplate. The man
+pages of 9front list the header files that we need include in order to
+use the library. (cursor.h isn't actually necessary, unless you plan
+on changing the cursor image.)
+
+ #include <u.h>
+ #include <libc.h>
+ #include <draw.h>
+ #include <cursor.h>
+
+If the program takes in arguments, we will need to use _arg(2)_. The
+macros function like a switch statement. If an invalid argument is
+passed, it will go to default, where we will print to stderr and exit.
+`argv0` is a special variable set by _ARGBEGIN_ that is the program's
+name. If you're not using _arg(2)_, it is in `argv[0]`.
+
+ void
+ main(int argc, char *argv[])
+ {+ ulong co; /* a color */
+ Image *im1, *im2, *bg; /* pointers to images we will draw, named "image1", "image2" and "background" */
+
+ co = 0xFF0000FF; /* fully red, no green, no blue, fully opaque (alpha). Ever heard of RGBA? */
+
+ ARGBEGIN{+ case 'b':
+ co = DBlue; /* using an enum definition from allocimage(2) */
+ default:
+ fprint(2, "usage: %s [-b]\n", argv0); /* file descriptor 2 is stderr */
+ exits("usage"); /* return with an exit string, because the program didn't successfully end */+ }ARGEND;
+
+A common pattern in C is to provide initialization routines for
+libraries that handle a lot of state. These libraries will set
+_errstr(2)_ and return -1 if they fail, so we need to catch and abort
+if it happens. _Initdraw_ connects us to the display and initializes
+the global `display` variable. We use the default error function by
+passing nil, another nil pointer to use the default font, and the name
+of the program as the label.
+
+ if(initdraw(nil, nil, argv0) < 0)
+ sysfatal("%s: %r", argv0);+
+We now need to connect to the window by using _getwindow_.
+This needs to be done every time the window is resized, but we will
+handle that case when we get to mouse control. As it turns out,
+_initdraw_ already calls _getwindow_ for us! No need to call it yet.
+
+Let's draw!
+
+First, we will need to allocate an image by using _allocimage_.
+Images are allocated on the drawing device, _display_. If you are
+connected to a cpu server, the drawing device is still local to your
+machine. We will take advantage of this fact to make sure drawing
+happens as fast as possible.
+
+We shall allocate a 10x10 size image on the display. The image
+supports red, green, blue, for a total of 24 bits. The `repl` flag is
+cleared, so this image will not tile and only draw once. The image
+fill is set to yellow (an enum in _allocimage(2)_).
+
+ im1 = allocimage(display, Rect(0,0,100,100), RGB24, 0, DYellow);
+
+We do a similar thing, but with a different color that is fully green
+but half transparent (this is called premultiplied alpha). Colors are
+defined in _color(2)_ and _color(6)_.
+
+ im2 = allocimage(display, Rect(0,0,100,100), RGBA32, 0, 0x007F007F);
+
+We shall also allocate a 1x1 size image on the display. The image is
+opaque, only supporting red, green, and blue, 8 bits per channel. The
+`repl` flag is set! Drawing this image will repeat itself over and
+over again to fill up the whole window. We use the color that we
+defined earlier as the default image fill.
+
+ bg = allocimage(display, Rect(0,0,1,1), RGB24, 1, co);
+
+Because allocating can fail, we must check if the returned images are nil.
+
+ if(im1 == nil || im2 == nil || bg == nil)
+ sysfatal("get more memory, bub");+
+Now we need to composite the image using the _draw_ function. We will
+first draw `bg`, then `im1`, and lastly `im2`.
+
+We first pass a pointer of the destination image, the global `screen`
+variable. Then, we pass in the area that our source image is allowed
+to draw into, which will be the destination's size. Then, the source
+image pointer is given. A mask image could be given, but we pass a
+nil pointer for it instead. ZP is the zero point, {0,0}. See+_draw(2)_ for a description of how _draw_ handles the point argument.
+
+ draw(screen, screen->r, bg, nil, ZP);
+
+We then composite the next images on top, im1 below im2. We use the
+src image rectangle for this, but then we need to add the dst minimum
+point, and an offset.
+
+ draw(screen, rectaddpt(im1->r, addpt(screen->r.min, Pt(40,40))), im1, nil, ZP);
+ draw(screen, rectaddpt(im2->r, addpt(screen->r.min, Pt(20,20))), im2, nil, ZP);
+
+This can also be written as follows. The reason for the negated
+offset and what the `p` argument does is for sprites. This is
+explained further in AdvancedLibdrawTips.
+
+ draw(screen, screen->r, im1, nil, Pt(-40,-40));
+ draw(screen, screen->r, im2, nil, Pt(-20,-20));
+
+These draw commands are not immediately written to the screen. We
+need to push these Remote Procedure Calls (RPCs) to the draw device
+using _flushimage_ (see _draw(2)_). We then call sleep so the image
+stays for a while, and then exit.
+
+ flushimage(display, Refnone);
+ sleep(10000);
+ exits(nil);
+ }
+
+Compile the program using 6c, link with 6l, and run it. You should
+see a red screen, a yellow square, and a transparent green square on
+top.
+
+## About Libthread
+
+Libthread is the library that provides easy concurrency and parallel
+program execution. These threads are scheduled cooperatively; when
+one thread is blocked, it gives up execution, and a different thread
+is run. Note that this is not parallelism, as these threads are
+within the same proc (process). Procs are preemptively scheduled by
+the kernel, which may interrupt execution at any time (a great source
+of both bugs and learning!). Libthread also supports creating
+parallel procs with shared memory, though this tutorial will not
+explore that. Procs contain the promise of faster speeds on manycore
+architectures, but the difficulty of managing them isn't always worth
+the effort. Threads simply allow coroutines, which are suitable for
+organizing certain problems.
+
+Threads and procs can control shared memory using locked variables or
+channels. Know when to use either: channels are used for 2-way
+communication between threads and procs, locks are generally used for
+multi-proc global variables where parallel execution can mess up
+memory access.
+
+## Mouse and Keyboard Input ##
+
+_mouse(2)_ and _keyboard(2)_ both use threads to execute, and
+communicate with channels. Both open files in /dev, read it into
+convenient C data structures, and send the data through channels.
+
+Let's get started with including the header files. Our program will
+start similarly as before, through with some extra declarations.
+Check the man pages for what the `Mousectl` and `Keyboardctl` structs
+are. _main_ is changed to threadmain, as libthread defines its own
+_main_ function and then calls _threadmain_.
+
+ #include <u.h>
+ #include <libc.h>
+ #include <draw.h>
+ #include <cursor.h>
+ #include <thread.h>
+ #include <mouse.h>
+ #include <keyboard.h>
+
+ void
+ threadmain(int argc, char *argv[])
+ {+ ulong co;
+ Image *im1, *im2, *bg;
+ Mousectl *mctl;
+ Keyboardctl *kctl;
+ Mouse mouse;
+ int resize[2];
+ Rune kbd;
+ uchar magenta[3] = {0xFF, 0x00, 0xFF};+ uchar cyan[3] = {0xFF, 0xFF, 0x00};+ uchar purple[3] = {0xFF, 0x00, 0xA0};+ uchar orange[3] = {0x00, 0x7F, 0xFF};+
+ co = 0xFF0000FF;
+
+ ARGBEGIN{+ case 'b':
+ co = DBlue;
+ default:
+ fprint(2, "usage: %s [-b]\n", argv0);
+ exits("usage");+ }ARGEND;
+
+ if(initdraw(nil, nil, argv0) < 0)
+ sysfatal("%s: %r", argv0);+ im1 = allocimage(display, Rect(0,0,100,100), RGB24, 0, DYellow);
+ im2 = allocimage(display, Rect(0,0,100,100), RGBA32, 0, 0x007F007F);
+ bg = allocimage(display, Rect(0,0,1,1), RGB24, 1, co);
+ if(im1 == nil || im2 == nil || bg == nil)
+ sysfatal("get more memory, bub");+ draw(screen, screen->r, bg, nil, ZP);
+ draw(screen, screen->r, im1, nil, Pt(-40,-40));
+ draw(screen, screen->r, im2, nil, Pt(-20,-20));
+ flushimage(display, Refnone);
+
+But now we need to initialize the mouse and keyboard, similarly to
+_initdraw_. Using very compact C notation, a function, assignment,
+comparison, and branch are all performed within the same line. See
+the associated man pages for what each argument means.
+
+ if((mctl = initmouse(nil, screen)) == nil)
+ sysfatal("%s: %r", argv0);+ if((kctl = initkeyboard(nil)) == nil)
+ sysfatal("%s: %r", argv0);+
+It's entirely possible to use _nbrecv_ (no-block receive) to check all
+of the channels before determining what to do with any received data.
+The `Alt` struct and function is a convenience to do all of this. The
+function will read each Alt structure in an array, put the read data
+into the pointer, and return with the index of that Alt struct in the
+array. We will define our Alt array at declaration, for convenience.
+Note the convention of channels ending with a 'c'.
+
+ enum{MOUSE, RESIZE, KEYBD, NONE};+ Alt alts[4] = {+ {mctl->c, &mouse, CHANRCV},+ {mctl->resizec, &resize, CHANRCV},+ {kctl->c, &kbd, CHANRCV},+ {nil, nil, CHANEND},+ };
+
+We then use the _alt_ function to read through every Alt and return
+one of the indices. This is used in a switch statement to decide what
+to do next. This is all done inside of a forever loop to create an
+event loop.
+
+ for(;;){+ switch(alt(alts)){+
+Our first case is `MOUSE`. Let's change the bg color to magenta or
+cyan depending on the mouse click and redraw. Note that loadimage
+loads in little endian byte order (blue first).
+
+ case MOUSE:
+ if(mouse.buttons == 1)
+ loadimage(bg, bg->r, magenta, sizeof(magenta));
+ else if(mouse.buttons == 4)
+ loadimage(bg, bg->r, cyan, sizeof(cyan));
+ draw(screen, screen->r, bg, nil, ZP);
+ draw(screen, screen->r, im1, nil, Pt(-40,-40));
+ draw(screen, screen->r, im2, nil, Pt(-20,-20));
+ flushimage(display, Refnone);
+ break;
+
+If the window gets resized, we lose window control, have to call
+_getwindow_, and redraw.
+
+ case RESIZE:
+ if(getwindow(display, Refnone) < 0)
+ sysfatal("%s: %r", argv0);+ draw(screen, screen->r, bg, nil, ZP);
+ draw(screen, screen->r, im1, nil, Pt(-40,-40));
+ draw(screen, screen->r, im2, nil, Pt(-20,-20));
+ flushimage(display, Refnone);
+ break;
+
+Next, let's handle a keyboard input. If the character is the delete
+key, we will exit the program (as is the 9front convention), however
+using _threadexitsall_ instead of _exits_. Note that if the program
+is capturing keyboard input and the delete key case is not handled,
+there will be no way to exit the program (besides deleting the
+window).
+
+ case KEYBD:
+ if(kbd == 'a')
+ loadimage(bg, bg->r, purple, sizeof(purple));
+ else if(kbd == 'b')
+ loadimage(bg, bg->r, orange, sizeof(orange));
+ else if(kbd == '')
+ threadexitsall(nil);
+ draw(screen, screen->r, bg, nil, ZP);
+ draw(screen, screen->r, im1, nil, Pt(-40,-40));
+ draw(screen, screen->r, im2, nil, Pt(-20,-20));
+ flushimage(display, Refnone);
+ break;
+
+In case there's any errors in the alt, do nothing.
+
+ case NONE:
+ break;
+ }
+ }
+ }
+
+And that's it!
+
+If you've noticed, a lot of the redrawing can be factored out into a
+separate function, following the rule of Don't Repeat Yourself. If
+there's some things I had glossed over (like channels), be sure to
+read the man pages. Happy hacking!
+
+### Other Options
+
+An alternative to using libdraw is to use
+[libnuklear](https://github.com/vurtun/nuklear). Find it in
+[ports](https://code.9front.org/hg/ports) under /draw-libs/libnuklear.
+
+Other Plan 9 libraries include _event(2)_ and _control(2)_. Libevent
+is a very old input library, and while it is still capable, libthread
+has largely superseded it. Libcontrol tries to provide a complete
+toolkit for creating GUIs. However, the Plan 9 team left it
+unfinished. Personally, I (Amavect) have tried using it, but I didn't
+find it particularly easy to create my own control elements.
+
+### See Also
+
+[libdraw-tips](libdraw-tips.html)