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