PDCursesMod Documentation

The curses library provides a procedural interface for screen-handling and updating via 'windows'. A window is a two-dimensional array of characters representing part or all of a terminal screen.

Core Workflow:

1. Manipulation: Use routines like move() and addch() to manipulate the default window, stdscr (which represents the whole screen).
2. Buffering: Applications add data to the window in any order. The curses package maintains an internal record of what characters are on the screen.
3. Refreshing: Call the refresh() routine. The library calculates the minimal set of operations required to update the physical terminal to match the window's contents, optimizing for the specific terminal type.

Window Types:

• Standard Windows: Created via newwin(). For every routine that manipulates stdscr (e.g., move()), there is a corresponding routine prefixed with w to manipulate a specific window (e.g., wmove()).
• Pads: Large windows that are bigger than the actual screen size.
• Partial Windows: Windows that may only be partially visible on the screen.

Soft Label Keys (SLK) are a separate window area used for labels. Clicking an SLK returns a function key press (e.g., clicking the leftmost SLK returns KEY_F(1)).

Initialization

slk_init(int fmt) must be called before initscr() or newterm(). This call removes 1 or 2 lines from the usable screen to accommodate the SLK window.

Formats

• 0: 3-2-3 format
• 1: 4-4 format
• 2: 4-4-4 format
• 3: 4-4-4 format with index line
• 55: 5-5 format (PDCurses specific)
• Hexadecimal Format (PDCursesMod extension): You can pass a hex value to slk_init() to specify custom widths. For example, 0x414 results in a 4-1-4 format. Negating the fmt value adds an index line.

Re-initialization

In PDCursesMod, you can call slk_init() after initscr() to reset the label format. If you do this, you must reset the label text and call slk_refresh(). Note that you cannot toggle the index line or turn SLK on/off after initscr() has been called.

int slk_init(int fmt);
int slk_set(int labnum, const char *label, int justify);
int slk_refresh(void);
int slk_noutrefresh(void);
char *slk_label(int labnum);
int slk_clear(void);
int slk_restore(void);
int slk_touch(void);
int slk_attron(const chtype attrs);
int slk_attr_set(const attr_t attrs, short color_pair, void *opts);
int slk_attroff(const chtype attrs);
int slk_attr_off(const attr_t attrs, void *opts);
int slk_color(short color_pair);
int slk_wset(int labnum, const wchar_t *label, int justify);
wchar_t *slk_wlabel(int labnum);

The VT platform uses a mix of xterm, VT-100, VT-200, and ANSI escape sequences. Users should be aware of the following limitations:

• Windows 10/11: Use of the VT platform is strongly discouraged on Windows. While partially supported, you are limited to 16 colors (no RGB), mouse support is unreliable, and the console size cannot be determined or set. Use WinGUI or WinCon instead.
• Key Support: Arrow keys and some function keys are recognized. However, Shift, Ctrl, and Alt modifiers (including arrows) are mostly not correctly identified. Extended keyboard keys (e.g., Browser Back/Forward, Search, Refresh) are not detected.
• Mouse: Some mouse input is recognized, but it is not guaranteed across all terminals.
• Clipboard: Clipboard functions are currently completely absent on this platform.
• Color: Assumes 256 colors are available (16 in NANSI mode), but can use full RGB if the terminal supports it and PDC_VT=RGB is configured.

The panel API allows you to manage depth relationships between windows. Instead of windows simply overwriting each other, panels can be stacked in a 'deck'. The initial stdscr window sits at the very bottom, beneath all panels.

Core Workflow:

1. Create a panel associated with a window using new_panel(WINDOW *win).
2. Manipulate the deck order using top_panel(), bottom_panel(), panel_above(), or panel_below().
3. Hide or show panels using hide_panel() and show_panel().
4. Crucial Step: After manipulating panels, you must call update_panels() to refresh the virtual screen to reflect the new depth relationships, and then call doupdate() to refresh the physical screen.

Note: Use move_panel() to move a panel; do not use mvwin() on the underlying window, as this can break the panel logic.

PANEL *new_panel(WINDOW *win);
void update_panels(void);
// After update_panels, call doupdate() to see changes