Archives/notcurses
2
0
Fork 0
mirror of https://github.com/dankamongmen/notcurses.git synced 2024-11-18 03:25:55 +00:00
Code Issues Packages Projects Releases Wiki Activity

flesh out notcurses_reel.3 #1171

Browse Source
This commit is contained in:
nick black 2020-12-02 20:15:53 -05:00
parent 7b7ed8441d
commit 5b8c71b9b0
No known key found for this signature in database
GPG Key ID: 5F43400C21CBFACC
1 changed files with 49 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

52
doc/man/man3/notcurses_reel.3.md
View File

@ -62,11 +62,11 @@ typedef struct ncreel_options {
# DESCRIPTION
An **ncreel** is a widget for display and manipulation of hierarchal data,
An **ncreel** is a widget for display and manipulation of hierarchical data,
intended to make effective use of the display area while supporting keyboards,
mice, and haptic interfaces. A series of **nctablet**s are ordered on a
virtual cylinder; the tablets can grow and shrink freely, while moving among
the tablets "spins" the cylinder. **ncreel**s support optional borders around
virtual cylinder; the tablets can grow and shrink freely. Moving among the
tablets "spins" the cylinder. **ncreel**s support optional borders around
the reel and/or tablets.
**ncreel_redraw** arranges the tablets, invoking the **tabletcb** defined by
@ -82,8 +82,54 @@ change via **ncreel_next** and **ncreel_prev**. If **ncreel_del** is called on
the focused tablet, and at least one other tablet remains, some tablet receives
the focus.
Calling functions which change the reel, including **ncreel_next**,
**ncreel_prev**, **ncreel_del**, and **ncreel_add**, implicitly calls
**ncreel_redraw**. This behavior **must not be relied upon**, as it is likely
to go away.
## LAYOUT
When the user invokes **ncreel_redraw**, Notcurses can't assume it knows the
size of any tablets--one or more might have changed since the last draw. Only
after a callback does **ncreel_redraw** know how many rows a tablet will
occupy.
A redraw operation starts with the focused tablet. Its callback is invoked with
a plane as large as the reel, i.e. the focused tablet can occupy the entire
reel, to the exclusion of any other tablets. The focused tablet will be kept
where it was, if possible; growth might force it to move. There is now one
tablet locked into place, and zero, one, or two areas of empty space. Tablets
are successively lain out in these spaces until the reel is filled.
In general, if the reel is not full, tablets will be drawn towards the top, but
this ought not be relied on.
## THE TABLET CALLBACK
The tablet callback (of type **tabletcb**) is called with an **ncplane** and a
**bool**. The callback function ought not rely on the absolute position of the
plane, as it might be moved. The **bool** indicates whether the plane ought be
filled in from the bottom, or from the top (this is only meaningful if the
plane is insufficiently large to contain all the tablet's available data). The
callback ought not resize the plane (it will be resized following return). The
callback must return the number of rows used (it is perfectly valid to use zero
rows), or a negative number if there was an error.
Returning more rows than the plane has available is an error.
# RETURN VALUES
**ncreel_focused**, **ncreel_prev**, and **ncreel_next** all return the focused
tablet, unless no tablets exist, in which case they return **NULL**.
**ncreel_add** returns the newly-added **nctablet**.
## BUGS
I can't decide whether to require the user to explicitly call **ncreel_redraw**.
Doing so means changes can be batched up without a redraw, but it also makes
things more complicated for both me and the user.
# SEE ALSO
**notcurses(3)**,