1# Direct mode
2
3Direct mode allows you to use Notcurses together with standard I/O. While
4the cursor can still be moved arbitrarily, direct mode is intended to be used
5with newline-delimited, scrolling output. Direct mode has no concept of frame
6rendering; output is intended to appear immediately (subject to buffering). It
7is still necessary to have a valid `TERM` environment variable identifying a
8valid terminfo database entry for the running terminal.
9
10The authoritative reference for direct mode is the `notcurses_direct(3)`
11man page.
12
13Enter direct mode with a call to `ncdirect_init()`. It takes three arguments:
14
15`struct ncdirect* ncdirect_init(const char* termtype, FILE* fp, uint64_t flags);`
16
17You can usually simply pass `NULL`, `NULL`, and 0. This will use the terminal
18entry specified by the `TERM` environment variable, and write to `stdout`. If
19the terminfo entry cannot be loaded, `ncdirect_init()` will fail. Otherwise,
20the active style (italics, reverse video, etc.) will be reset to the default,
21and all `ncdirect` functions are available to use. When done with the context,
22call `ncdirect_stop()` to release its resources, and restore the terminal's
23preserved status.
24
25The cursor is not moved by initialization. If your program was invoked as
26`ncdirect-demo` from an interactive shell, the cursor is most likely to be
27on the first column of the line following your command prompt, exactly where
28a program like `ls` would start its output.
29
30```c
31{{#include directmode-helloworld.c}}
32```
33![](directmode-helloworld.png)
34
35The terminal will scroll on output just like it normally does, and if you have
36a scrollback buffer, any output you generate will be present there. Remember:
37direct mode simply *styles* standard output. With that said, the cursor can be
38freely controlled in direct mode, and moved arbitrarily within the viewing
39region. Dimensions of the terminal can be acquired with `ncdirect_dim_y()` and
40`ncdirect_dim_x()` (if you initialized direct mode with a file not attached to
41a terminal, Notcurses will simulate a 80x24 canvas). The cursor's location is
42found with `ncdirect_cursor_yx()` (this function fails if run on a
43non-terminal, or if the terminal does not support this capability).
44
45**ncdirect_ cursor functions**
46
47The cursor can be moved relative to its current location, or absolutely within
48the terminal's boundaries. The location can also be pushed and popped (''FIXME''
49why don't we synthesize this in the absence of `sc/rc`? why is this exposed at
50all? do some terminals support `sc` but not cursor location discovery?).
51
52The cursor can be hidden and made visible once more with `ncdirect_cursor_disable()`
53and `ncdirect_cursor_enable()`. Unlike rendered mode, the cursor is not hidden
54by default at initialization.
55
56**example scrolling a screen's worth of text**
57**picture before and after run**
58