ref: 5b7bb5370a455e3a61d16ea71c2fe69cfeb051e3
parent: ec1b85c429d3fb56bb9fe1cd22309b38a6849e2b
author: Tevo <estevan.cps@gmail.com>
date: Sat Jul 3 17:01:53 EDT 2021
Library overview
--- a/libwidget/widget.2.man
+++ b/libwidget/widget.2.man
@@ -159,7 +159,37 @@
M_BUTTON_RELEASED
};
.SH DESCRIPTION
-<we describe libwidget here>
+This library provides a collection of common interactive widgets that are commonly used by graphical applications, such as buttons, and layout facilities to organize such items on the screen. Widgets are defined as a group of coupled structures and functions that draw to a region of the screen and optionally respond to keuboard and mouse events and generates events for the application to handle.
+.PP
+The
+.B Widget
+type defines the shared data and structure between all widgets:
+.B id
+is a unique integer identifying the widget instance during runtime.
+.B kind
+contains a per-widget string used to identify which widget is it a instance of; it is set at creation time and should not be modified, as widgets make use of it for error-checking internaly (applications wishing to do the same may make use of the is* functions, which return 1 or 0 depending on whether the argument is an instance of the named widget or not).
+.B aux
+is a per-instance pointer that applications can use to store data; it is not freed when the widget is destroyed.
+.B bg
+and
+.B fg
+are images used by widgets internally for drawing graphical artifacts. Note that, despite the name, the meaning (and use) of each is widget-dependent.
+.BR redraw ,
+.BR kbdevent ,
+.BR mouseevent
+and
+.B cleanup
+are pointers to functions used to implement widget drawing, keyboard and mouse event handling and freeing, respectively. Applications should not call those directly, but rather use the standalone wrappers
+.BR widgetredraw ,
+.BR kbdevent ,
+.B mouseevent
+and
+.BR freewidget ,
+which may implement sanity-checking and setup code not invoked otherwise. Note that applications should rarely need to directly inform widgets of keyboard/mouse events, as
+.B initwidget
+already takes care of setting up a thread that listens for such events and takes the appropriate actions.
+.PP
+<talk 'bout initwidget(), Widgetctl, etc>
.SH DIAGNOSTICS
These routines call the function pointed to by werror on fatal errors. The function should not return.
.SH BUGS