gh-152263: Add curses soft-label-key functions

[serhiy-storchaka]

Wrap the X/Open Curses soft-label-key functions in the curses module. Soft labels are a row of labels along the bottom line of the screen, conventionally labelling a row of function keys, managed and refreshed independently of the standard window.

Added module-level functions:

• slk_init(fmt=0) — reserve a screen line for the labels and choose their layout. Must be called before initscr() or newterm().
• slk_set(labnum, label, justify) / slk_label(labnum) — set and query a label's text.
• slk_refresh(), slk_noutrefresh(), slk_clear(), slk_restore(), slk_touch().
• slk_attron(attr), slk_attroff(attr), slk_attrset(attr), slk_attr() — the chtype attribute functions.
• slk_attr_on(attr), slk_attr_off(attr), slk_attr_set(attr, pair=0), slk_color(pair) — the attr_t/color-pair attribute functions.

slk_set uses slk_wset for wide-character labels when built against ncursesw. Tests drive their own pseudo-terminals (soft labels must be initialised before newterm()), and pass under UTF-8, Latin-1 and C locales.

• Issue: Add curses soft-label-key (slk_*) functions #152263

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #33359890 | 📁 Comparing 2facde8 against main (8eb6fb0)

  🔍 Preview build  

27 files changed · ± 26 modified · - 1 deleted

± Modified

• c-api/type.html
• deprecations/index.html
• deprecations/pending-removal-in-3.16.html
• deprecations/soft-deprecations.html
• howto/curses.html
• howto/mro.html
• library/asyncio-eventloop.html
• library/asyncio-llapi-index.html
• library/asyncio-runner.html
• library/asyncio.html
• and 16 more...

- Deleted

• library/asyncio-policy.html

[vstinner]

I didn't know soft-label-key functions. Is it commonly used? I'm not sure that it's worth it to expose these functions.

Soft labels are a row of labels displayed along the bottom line of the screen, conventionally used to label a row of function keys

Would you be able to write a short demo so I can see how it does look like?

(I don't understand well the purpose of these functions.)

[serhiy-storchaka]

No, they are not often used. But they are the part of the Posix standard. Demo:

import curses

LABELS = ["Help", "Save", "Open", "Find", "Run", "Stop", "Setup", "Quit"]
def main(stdscr):
    for i, text in enumerate(LABELS):
        curses.slk_set(i + 1, text, 1) # 1 - center
    curses.slk_refresh()
    stdscr.addstr(0, 0, "Soft labels are on the bottom line. Press any key.")
    stdscr.getkey()
curses.slk_init(0) # 3-2-3 layout
curses.wrapper(main)

[vstinner]

On Fedora 44, the example looks like:

[vstinner]

3 is only supported on ncurses? If yes, can we reject 3 if the Python _curses module is not linked to ncurses?

[serhiy-storchaka]

I will test how out-of-range values are handled. Most likely you will get a curses.error.

Other implementations can also support them.

[vstinner]

Would it be possible to move these functions in a new "Soft-label keys" section?

[serhiy-storchaka]

Yes. I just reorganized the docs (#152584), these functions will be in a separate section.

[vstinner]

LGTM.

For slk_init(), I'm fine with not rejecting fmt=3 but just pass the value to curses.

For the doc, I didn't see the reorganized doc. Nice.

[vstinner]

Ah, and good luck to solve the merge conflicts :-)

[serhiy-storchaka]

Thank you. This was peanuts in comparison with five PRs fighting for the same place in What's New, with flaky CI tests.