On the scale from useful to useless, I'm not sure where this falls, but we don't know of any good GUI documentation, so: a while back, we went through the gui.lua file in the /system/lib folder and wrote down every single time we could find that a key was written or read from any table by any function. Here's what we got, with the best guesses we could make on what they do.

internal:

• new = method, creates new gui element with no parent
• id = incremental counter uniquely identifying each gui element for debugging
• t0 = time of creation for each element
• sx = draw position, accounting for justify and stuff
• sy = ditto
• clip_to_parent = when clipping drawing to gui element, clips that rectangle to the rectangle of its parent element
• attach = method, creates new gui element attached to this one
• child = table of child elements, can easily be iterated through
• parent = parent element
• head = top of tree of GUI elements
• has_keyboard_focus = method, gives element keyboard focus
• keyboard_focus_el = in head only; points to element with keyboard focus
• set_keyboard_focus = method, can set or remove focus
• has_pointer = true iff pointer points at
• attach_pulldown = method, attaches a special kind of element
• attach_pulldown_item = method, adds items to pulldown
• attach_field = method, attach a text entry field
• attach_scrollbars = method, attach scrollbars (just vertical for now); assumes item to be scrolled is child[1] and scrollbar is child[2]
• attach_button = method, creates and attaches a button
• attach_text_editor = method, attaches a whole-ass text editor; see gui_ed.lua
• detach = method, unhooks element from its parent and returns it
• bring_to_front = method, comment says "bring as far foward as will go before find an element with higher z"
• push_to_back = method, comment says "push as far back as will go before find an element with lower z"
• event = method, sends a message to the element to do ... things. msg.event is a string corresponding to a method; msg.propagate_to_children says if message should propagate to children of messaged element (e.g. with draw and update)
• get_pointer_element = see gui.pointer_element
• get_keyboard_focus_element = see gui.keyboard_focus_el
• el_at_xy = method, looks for what GUI element is at x,y, used to find where ppinter is at
• draw_all = method, draws the whole GUI
• mouse_cursor_gfx = in head only, says if the cursor needs to be replaced (or hidden)
• update_all = method, updates all the updates in the GUI
• pointer_element = element at pointer
• hidden = used by scrollbar autohiding
• last_click_t = time of last click, used for double-click
• last_click_mb = button of last click, ditto (note: two click messages for every double click)

user-set methods (inputs: self, msg):

• update = function run every update to ... update things
• draw = function that draws contents of element on screen
• click = function run when clicked on
• release = function run when mouse released on
• tap = function run when clicked on and click released on
• hover = function run when cursor hovering over (does this work?)
• drag = function run when dragging on element
• doubleclick = function run on doubleclick
• doubletap = function run on doubletap
• mousewheel = action to take when mousewheeling; clobbered by attach_scrollbars
• action = a dropdown thing, function associated with thing
• onclose = a dropdown thing, function to run when closing
• set = a field thing, run on enter

user-set values:

• label = a button thing, is printed on the button and used to determine its size
• x = horiz offset from reference corner (default top left)
• y = vert offset from reference corner
• z = only seems to be used by bring_to_front and push_to_back
• width = current width
• height = current height
• width_rel = if set, fraction of total width to use
• width_add = offset from above fraction
• height_rel = if set, fraction of total height to use
• height_add = offset from above fraction
• justify = string; if "right" or "center" will display at right or center of parent
• vjustify = string; if "bottom" or "center" will display at bottom or center of parent
• cursor = selects which cursor sprite to use?
• stay_open = a dropdown thing
• item_h = a dropdown thing (height of line?)
• divider = a dropdown thing
• str = a field thing, tracks text typed
• autohide = a scrollbar thing, hides scrollbar when contents don't need scrolling
• bar_y = a scrollbar thing, position in the scrolled contents
• bar_h = a scrollbar thing, height of scrollbar in scrollbar
• bgcol = a button thing, contains normal background color in lower byte and on-hover color in upper
• fgcol = a button thing, contains normal foreground color in lower byte and on-hover color in upper

Wow, I didn't know it was so versatile! I'm not 100% sure but I'd guess that clip_to_parent clips the gui element to the parent element, so it won't appear outside of it.

@Soupster: gui.lua does a lot, yeah! I wish I understood it.

And clipping to the parent element would make sense with the name - we just couldn't figure out what it did in code, iwrc. Would probably help if we had any experience doing object-oriented programming...

Ah. On line 497 we get this line: cl,ct,cw,ch,cc = clip(self.sx, self.sy, self.width, self.height, self.clip_to_parent). Take note of the last argument. When it is true, the clipping rectangle is clipped by the previous rectangle, which in this case would be the parent's clipping rectangle. Very clever.

@Soupster: Oh, that's so good! Thanks, updated OP.

Thank you for the great work you've done!

Isn't there a right click user-set method?
Or are we supposed to manage it with mouse() only?

Btw, hover is not working for me

@369369369 If you set up the click method with a second input - so, function [element].click (self, msg) or function [element]:click(msg) - you get a copy of the msg table to read, and that contains the contents of mouse_b from the mouse() function at msg.mb. If the click was generated by the right mouse button, the 2s bit of msg.mb will be on.

Also, I remember we originally had a note about hover in our notes and deleted it - we'll put something back in.

@packbat thanks again!

I just realized I have a mouse() call inside my update function so I could just check if mb==2 but great to know there's a msg input! It will come in handy in the future

@369369369 I think the advantage of using the msg.mb field is that, if someone hacks their gui.lua file to change how it works (e.g. configure to use keyboard input) it'll work correctly with their version. That's the big reason why we want to do our GUI stuff with the library function, so they update automatically.

i've got an update on the hover method. I got it working (kinda)

"Obviously", you shouldn't draw inside there, you should only draw in the draw method.
So I gave my element a col integer value which represents the color I want to change on hover.
Then just changed it in the hover method like this:

hover=function(self) self.col=8 end

It works and the color changes! but I need to understand how to change it back to default once the mouse is not hovering on the element anymore...

@369369369 Set a countdown timer in hover and have update check the value, set the color, and decrement if not zero?

@packbat smart move! Didn't think about using a timer