STRESZCZENIE
#include <curses.h>OPIS
Uwaga! To tłumaczenie może być nieaktualne!Funkcje biblioteki curses dają użytkownikowi niezależne od terminala metody obsługiwania ekranów znakowych z sensowną optymalizacją. Ta implementacja to ,,nowe curses'' (ncurses). Jest ona zatwierdzonym zamiennikiem dla klasycznych curses z 4.4BSD, których rozwoju zaprzestano.
Funkcje ncurses emulują bibliotekę curses(3X) Systemu Vr4, a także standard XPG4 (XSI curses), lecz biblioteka ncurses jest wolnodostępna w postaci źródłowej. Różnice między curses z SVr4 podsumowano w sekcjach ROZSZERZENIA i BŁĘDY, występujących poniżej, a opisano szczegółowo w takich samych sekcjach stron podręcznika systemowego poświęconych poszczególnym funkcjom.
Program, który korzysta z tych funkcji, musi być skonsolidowany z opcją -lncurses (lub jeśli został wygenerowany) z biblioteką debuggową -lncurses_g. Biblioteka ncurses_g generuje logi śledzenia (plik o nazwie 'trace', w bieżącym katalogu), które opisują akcje curses.
Pakiet ncurses obsługuje: działanie na ekranie, oknach i padach; wyjście do okien i padów; odczytywanie wejścia z terminala; sterowanie terminalem oraz opcje wejścia/wyjścia curses; funkcje zapytań środowiskowych; działanie na kolorach; używanie klawiszy o miękkich etykietach; właściwości terminfo; i dostęp do niskopoziomowych funkcji obsługi terminala.
Aby zainicjalizować pakiet, należy na samym początku wywołać funkcję initscr, lub newterm. Przed wyjściem należy wywołać funkcję endwin. Aby uzyskać wejście znakowe znak-po-znaku bez echa (większość interaktywnie zorientowanych programów tego chce), powinno się użyć następującej sekwencji:
initscr(); cbreak(); noecho();
Większość programów chętnie wykorzystuje też sekwencje:
nonl();
intrflush(stdscr, FALSE);
keypad(stdscr, TRUE);
Przed uruchomieniem programu curses, należy ustawić <tab stops> (pozycje tabulacji) terminala, oraz wysłać doń łańcuchy inicjujące. Można tego dokonać, wywołując polecenie tput init po uprzednim wyeksportowaniu zmiennej środowiskowej TERM. Odpowiedzialny za to jest tset(1). [Szczegóły - zobacz terminfo(5).]
Biblioteka curses zezwala na działanie na strukturach danych, nazywanych oknami, o których można myśleć jak o dwuwymiarowych tablicach znaków, reprezentujących część lub całość ekranu CRT. Dostarczane jest domyślne okno, o nazwie stdscr, którego wymiary odpowiadają ekranowi terminala. Inne okna można utworzyć przy użyciu funkcji newwin.
Zauważ, że curses nie obsługuje zachodzących okien - jest to robione przez bibliotekę panels(3x). Znaczy to, że możesz albo używać stdscr, albo podzielić ekran na okna i nie używać stdscr w ogóle. Łączenie tych dwóch spowoduje niepraktyczne i niepożądane efekty.
Do okien można odnosić się poprzez zmienne zadeklarowane jako WINDOW *. Działań na tych strukturach dokonuje się funkcjami opisanymi na tej stronie oraz w innych miejscach stron podręcznika ncurses. Najbardziej podstawowymi funkcjami są move i addch. Ogólniejsze wersje tych funkcji figurują pod nazwami zaczynającymi się od w i umożliwiają podanie okna. Funkcje nie zaczynające się od w działają na stdscr.
Po użyciu funkcji działania na oknie, wywoływany jest refresh, nakazujący curses, by ekran CRT zaczął wyglądać tak jak stdscr. Znaki okna są właściwie typu chtype (znak i dane atrybutu), więc dane o znaku można przechowywać w nim samym.
Można też operować szczególnymi oknami, padami. Okna te nie są ograniczone rozmiarami ekranu, a ich zawartość nie musi być w całości wyświetlana. Więcej szczegółów znajdziesz w curs_pad(3X).
Oprócz rysowania na ekranie znaków, mogą być obsługiwane atrybuty i kolory, a więc znaki mogą pokazywać się w trybach takich jak podkreślenie, inwersja, lub w kolorze, o ile terminal na to pozwala. Można wyświetlać znaki składające się na linie. Na wejściu, ncurses potrafi tłumaczyć klawisze strzałek i funkcyjne, które przekazują sekwencje eskejpowe, na zwykłe wartości. Atrybuty wideo, znaki rysowania linii i nazwy wartości wejściowych są zdefiniowane w <curses.h> i mają nazwy typu A_REVERSE, ACS_HLINE, czy KEY_LEFT.
Jeśli ustawiono zmienne środowiskowe LINES i COLUMNS, lub jeśli program jest uruchomiony w środowisku okienkowym, to informacje o rozmiarze ekranu przesłonią dane odczytywane z terminfo.
Jeśli zdefiniowana jest zmienna środowiskowa TERMINFO, to każdy program używający curses będzie szukał najpierw lokalnej definicji terminala, a dopiero potem zajrzy do standardowego miejsca. Np. Jeśli TERM jest ustawione na att4424, to wkompilowana definicja terminala jest znajdywana w
/usr/lib/terminfo/a/att4424.
(a jest kopiowane z pierwszej litery att4424, aby zapobiec tworzeniu wielkich katalogów.) Jednak jeśli ustawiono TERMINFO, np. na wartość $HOME/myterms, to curses zajrzy wpierw do
$HOME/myterms/a/att4424,
a jeśli to zawiedzie, do
/usr/lib/terminfo/a/att4424.
Jest to przydatne dla rozwijania eksperymentalnych definicji, lub gdy nie ma praw zapisu do /usr/lib/terminfo.
Zmienne całkowite LINES i COLS są zdefiniowane w <curses.h> i są wypełniane przez initscr wartościami, odpowiadającymi rozmiarowi ekranu. Stałe TRUE i FALSE mają odpowiednio wartości 1 i 0.
Zmienne curses definiują również zmienną WINDOW *curscr, która jest używana do pewnych niskopoziomowych operacji, jak np. oczyszczanie i odświeżanie ekranu, zawierającego śmieci. curscr może być użyte tylko w niektórych funkcjach.
Nazwy funkcji i argumentów
Wiele funkcji curses ma dwie lub więcej wersji. Zmienne, poprzedzone w, wymagają argumentu okna. Zmienne poprzedzone p wymagają argumentu padu. Funkcje bez przedrostka odnoszą się w ogólności do stdscr.Zmienne z przedrostkiem mv wymagają współrzędnych y i x, wskazujących miejsce ekranu, do którego należy się przenieść przed dokonaniem akcji. Funkcje te wymuszają wywołanie move przed wywołaniem innej funkcji. Współrzędna y zawsze odnosi się do wiersza (okna), a x do kolumny. Górny lewy narożnik ma współrzędne (0,0), nie (1,1).
Funkcje z przedrostkiem mvw pobierają zarówno argument okna, jak i parametry współrzędnych. Argument okna jest zawsze podawany przed współrzędnymi.
W każdym wypadku, win jest oknem, a pad padem, na które wpływa funkcja. win i pad są zawsze wskaźnikami do typu WINDOW.
Funkcje ustawiające opcje wymagają flagi logicznej bf, której wartość wynosi albo TRUE, albo FALSE; bf jest zawsze typu bool. Zmienne ch i attrs niżej, są zawsze typu chtype. Typy WINDOW, SCREEN, bool, i chtype są zdefiniowane w <curses.h>. Typ TERMINAL jest zdefiniowany w <term.h>. Wszystkie pozostałe argumenty są typu integer.
Indeks nazw funkcji
W poniższej tablicy podano każdą z funkcji curses, wskazując przy okazji odpowiadającą jej stronę podręcznika man. Funkcje oznaczone `*', są specyficzne dla ncurses, nieopisane przez XPG4 i SVr4.
Nazwa funkcji Nazwa strony podręcznika ___________________________________________ addch curs_addch(3X) addchnstr curs_addchstr(3X) addchstr curs_addchstr(3X) addnstr curs_addstr(3X) addstr curs_addstr(3X) attroff curs_attr(3X) attron curs_attr(3X) attrset curs_attr(3X) baudrate curs_termattrs(3X) beep curs_beep(3X) bkgd curs_bkgd(3X) bkgdset curs_bkgd(3X) border curs_border(3X) box curs_border(3X) can_change_color curs_color(3X) cbreak curs_inopts(3X) clear curs_clear(3X) clearok curs_outopts(3X) clrtobot curs_clear(3X) clrtoeol curs_clear(3X) color_content curs_color(3X) copywin curs_overlay(3X) curs_set curs_kernel(3X) def_prog_mode curs_kernel(3X) def_shell_mode curs_kernel(3X) del_curterm curs_terminfo(3X) delay_output curs_util(3X) delch curs_delch(3X) deleteln curs_deleteln(3X) delscreen curs_initscr(3X) delwin curs_window(3X) derwin curs_window(3X) doupdate curs_refresh(3X) dupwin curs_window(3X) echo curs_inopts(3X) echochar curs_addch(3X) endwin curs_initscr(3X) erase curs_clear(3X) erasechar curs_termattrs(3X) filter curs_util(3X) flash curs_beep(3X) flushinp curs_util(3X) getbegyx curs_getyx(3X) getch curs_getch(3X) getmaxyx curs_getyx(3X) getmouse curs_mouse(3X)* getparyx curs_getyx(3X) getstr curs_getstr(3X) getsyx curs_kernel(3X) getwin curs_util(3X) getyx curs_getyx(3X) halfdelay curs_inopts(3X) has_colors curs_color(3X) has_ic curs_termattrs(3X) has_il curs_termattrs(3X) hline curs_border(3X) idcok curs_outopts(3X) idlok curs_outopts(3X) immedok curs_outopts(3X) inch curs_inch(3X) inchnstr curs_inchstr(3X) inchstr curs_inchstr(3X) init_color curs_color(3X) init_pair curs_color(3X) initscr curs_initscr(3X) innstr curs_instr(3X) insch curs_insch(3X) insdelln curs_deleteln(3X) insertln curs_deleteln(3X) insnstr curs_insstr(3X) insstr curs_insstr(3X) instr curs_instr(3X) intrflush curs_inopts(3X) is_linetouched curs_touch(3X) is_wintouched curs_touch(3X) isendwin curs_initscr(3X) keyname curs_util(3X) keypad curs_inopts(3X) killchar curs_termattrs(3X) leaveok curs_outopts(3X) longname curs_termattrs(3X) meta curs_inopts(3X) mouseinterval curs_mouse(3X)* mousemask curs_mouse(3X)* move curs_move(3X) mvaddch curs_addch(3X) mvaddchnstr curs_addchstr(3X) mvaddchstr curs_addchstr(3X) mvaddnstr curs_addstr(3X) mvaddstr curs_addstr(3X) mvcur curs_terminfo(3X) mvdelch curs_delch(3X) mvderwin curs_window(3X) mvgetch curs_getch(3X) mvgetstr curs_getstr(3X) mvinch curs_inch(3X) mvinchnstr curs_inchstr(3X) mvinchstr curs_inchstr(3X) mvinnstr curs_instr(3X) mvinsch curs_insch(3X) mvinsnstr curs_insstr(3X) mvinsstr curs_insstr(3X) mvinstr curs_instr(3X) mvprintw curs_printw(3X) mvscanw curs_scanw(3X) mvwaddch curs_addch(3X) mvwaddchnstr curs_addchstr(3X) mvwaddchstr curs_addchstr(3X) mvwaddnstr curs_addstr(3X) mvwaddstr curs_addstr(3X) mvwdelch curs_delch(3X) mvwgetch curs_getch(3X) mvwgetstr curs_getstr(3X) mvwin curs_window(3X) mvwinch curs_inch(3X) mvwinchnstr curs_inchstr(3X) mvwinchstr curs_inchstr(3X) mvwinnstr curs_instr(3X) mvwinsch curs_insch(3X) mvwinsnstr curs_insstr(3X) mvwinsstr curs_insstr(3X) mvwinstr curs_instr(3X) mvwprintw curs_printw(3X) mvwscanw curs_scanw(3X) napms curs_kernel(3X) newpad curs_pad(3X) newterm curs_initscr(3X) newwin curs_window(3X) nl curs_outopts(3X) nocbreak curs_inopts(3X) nodelay curs_inopts(3X) noecho curs_inopts(3X) nonl curs_outopts(3X) noqiflush curs_inopts(3X) noraw curs_inopts(3X) notimeout curs_inopts(3X) overlay curs_overlay(3X) overwrite curs_overlay(3X) pair_content curs_color(3X) pechochar curs_pad(3X) pnoutrefresh curs_pad(3X) prefresh curs_pad(3X) printw curs_printw(3X) putp curs_terminfo(3X) putwin curs_util(3X) qiflush curs_inopts(3X) raw curs_inopts(3X) redrawwin curs_refresh(3X) refresh curs_refresh(3X) reset_prog_mode curs_kernel(3X) reset_shell_mode curs_kernel(3X) resetty curs_kernel(3X) restartterm curs_terminfo(3X) ripoffline curs_kernel(3X) savetty curs_kernel(3X) scanw curs_scanw(3X) scr_dump curs_scr_dump(3X) scr_init curs_scr_dump(3X) scr_restore curs_scr_dump(3X) scr_set curs_scr_dump(3X) scrl curs_scroll(3X) scroll curs_scroll(3X) scrollok curs_outopts(3X) set_curterm curs_terminfo(3X) set_term curs_initscr(3X) setscrreg curs_outopts(3X) setsyx curs_kernel(3X) setterm curs_terminfo(3X) setupterm curs_terminfo(3X) slk_attroff curs_slk(3X) slk_attron curs_slk(3X) slk_attrset curs_slk(3X) slk_clear curs_slk(3X) slk_init curs_slk(3X) slk_label curs_slk(3X) slk_noutrefresh curs_slk(3X) slk_refresh curs_slk(3X) slk_restore curs_slk(3X) slk_set curs_slk(3X) slk_touch curs_slk(3X) standend curs_attr(3X) standout curs_attr(3X) start_color curs_color(3X) subpad curs_pad(3X) subwin curs_window(3X) syncok curs_window(3X) termattrs curs_termattrs(3X) termname curs_termattrs(3X) tgetent curs_termcap(3X) tgetflag curs_termcap(3X) tgetnum curs_termcap(3X) tgetstr curs_termcap(3X) tgoto curs_termcap(3X) tigetflag curs_terminfo(3X) tigetnum curs_terminfo(3X) tigetstr curs_terminfo(3X) timeout curs_inopts(3X) touchline curs_touch(3X) touchwin curs_touch(3X) tparm curs_terminfo(3X) tputs curs_termcap(3X) tputs curs_terminfo(3X) typeahead curs_inopts(3X) unctrl curs_util(3X) ungetch curs_getch(3X) ungetmouse curs_mouse(3X)* untouchwin curs_touch(3X) use_env curs_util(3X) vidattr curs_terminfo(3X) vidputs curs_terminfo(3X) vline curs_border(3X) vwprintw curs_printw(3X) vwscanw curs_scanw(3X) waddch curs_addch(3X) waddchnstr curs_addchstr(3X) waddchstr curs_addchstr(3X) waddnstr curs_addstr(3X) waddstr curs_addstr(3X) wattroff curs_attr(3X) wattron curs_attr(3X) wattrset curs_attr(3X) wbkgd curs_bkgd(3X) wbkgdset curs_bkgd(3X) wborder curs_border(3X) wclear curs_clear(3X) wclrtobot curs_clear(3X) wclrtoeol curs_clear(3X) wcursyncup curs_window(3X) wdelch curs_delch(3X) wdeleteln curs_deleteln(3X) wechochar curs_addch(3X) wenclose curs_mouse(3X)* werase curs_clear(3X) wgetch curs_getch(3X) wgetnstr curs_getstr(3X) wgetstr curs_getstr(3X) whline curs_border(3X) winch curs_inch(3X) winchnstr curs_inchstr(3X) winchstr curs_inchstr(3X) winnstr curs_instr(3X) winsch curs_insch(3X) winsdelln curs_deleteln(3X) winsertln curs_deleteln(3X) winsnstr curs_insstr(3X) winsstr curs_insstr(3X) winstr curs_instr(3X) wmove curs_move(3X) wnoutrefresh curs_refresh(3X) wprintw curs_printw(3X) wredrawln curs_refresh(3X) wrefresh curs_refresh(3X) wresize curs_resize(3x)* wscanw curs_scanw(3X) wscrl curs_scroll(3X) wsetscrreg curs_outopts(3X) wstandend curs_attr(3X) wstandout curs_attr(3X) wsyncdown curs_window(3X) wsyncup curs_window(3X) wtimeout curs_inopts(3X) wtouchln curs_touch(3X) wvline curs_border(3X)
WARTOŚĆ ZWRACANA
Funkcje, które zwracają integer, zwracają ERR w wypadku błędu, a po sukcesie dowolny inny integer. (chyba że zaznaczono inaczej w opisie funkcji).Wszystkie makra zwracają wartość wersji w, poza setscrreg, wsetscrreg, getyx, getbegyx, getmaxyx. Wartości zwracane setscrreg, wsetscrreg, getyx, getbegyx, i getmaxyx są niezdefiniowane (np. nie powinny być używane jako instrukcje prawej strony przypisań).
Funkcje, które zwracają wskaźniki, po błędzie zwracają NULL.
ROZSZERZENIA
Biblioteka curses może być skompilowana z opcją (-DTERMCAP_FILE), która powoduje skok wstecz, do starodawnego pliku /etc/termcap, jeśli nie ma odpowiedniego wpisu w terminfo. Użycie tej właściwości nie jest zalecane, gdyż w zasadzie włącza ona do kodu startowego curses cały kompilator termcapa.Kompilowanie z -DTERMCAP_FILE zmienia sekwencję inicjalizacji biblioteki, na sposób podobny do 4.4BSD curses. Jeśli nie ma żadnego terminfo, opowiadającego TERM, to biblioteka zaczyna szukać wpisów termcap. Robi to w następujących miejscach: (1) jeśli TERMINFO nie jest zdefiniowane, w pliku o nazwie TERMCAP_FILE; (2) jeśli zdefiniowano TERMINFO, i nazwa zaczyna się od ukośnika, to jest interpretowane jako nazwa pliku termcap, w którym należy szukać TERM; (3) gdy TERMINFO ma napis prowadzący, który wygląda jak lista wpisów nazw terminala i odpowiada TERM, to zawartość TERMINFO jest interpretowana jako termcap; (4) jeśli terminfo wygląda jak termcap, lecz nie zawiera TERM, plik termcap jest przeszukiwany wśród oddzielonych dwukropkami ścieżek TERMPATHS, o ile jest ono zdefiniowane i w ~/.termcap i ostatecznie w wartości plikowej TERMCAP_FILE.
Wersje curses, skompilowane na PC, wspierają znaki PC ROM (zawierające znaki 0-31, których curses z SVr4 nie potrafi wyświetlić). Zobacz sekcje ROZSZERZENIA w curs_addch(3x) i curs_attr(3x).
PRZENOŚNOŚĆ
Bibliotekę curses zaprojektowano jako zgodną ze standardem XSI Curses na poziomie podstawowym. Obsługiwane są pewne partie rozszerzonych XSI Curses (łącznie z obsługą koloru). Nie zaimplementowano jeszcze następujących wywołań rozszerzonego XSI Curses, związanych z obsługą szerokich (wielobajtowych) znaków: addnwstr, addwstr, mvaddnwstr, mvwaddnwstr, mvaddwstr, waddnwstr, waddwstr, add_wch, wadd_wch, mvadd_wch, mvwadd_wch, add_wchnstr, add_wchstr, wadd_wchnstr, wadd_wchstr, mvadd_wchnstr, mvadd_wchstr, mvwadd_wchnstr, mvwadd_wchstr, bkgrndset, bkgrnd, getbkgrnd, wbkgrnd, wbkgrndset, wgetbkgrnd, border_set, wborder_set, box_set, hline_set, mvhline_set, mvvline_set, mvwhline_set, mvwvline_set, whline_set, vhline_set, wvline_set, echo_wchar, wecho_wchar, erasewchar, killwchar, get_wch, mvget_wch, mvwget_ch, wget_wch, getwchtype, get_wstr, getn_wstr, wget_wstr, wgetn_wstr, mvget_wstr, mvgetn_wstr, mvwget_wstr, mvwgetn_wstr, innwstr, inwstr, winnwstr, winwstr, mvinnwstr, mvinwstr, mvwinnwstr, mvwinwstr, ins_nwstr, ins_wstr, mvins_nwstr, mvins_wstr, mvwins_nwstr, mvwins_wstr, wins_nwstr, wins_wstr, ins_wch, wins_wch, mvins_wch, mvwins_wch, in_wch, win_wch, mvin_wch, mvwin_wch, inwchstr, inwchnstr, winwchstr, winwchnstr, mvinwchstr, mvinwchnstr, mvinwchstr, mvwinwchnstr.Niewielka ilość różnic (to jest poszczególnych różnic między XSI Curses, a wywołaniami curses) jest opisywana w sekcjach PRZENOŚNOŚĆ konkretnych stron podręcznika man.
Format terminfo, obsługiwany przez curses jest binarnie zgodny z SVr$, lecz nie jest zgodny z XSI curses. Jest tak, ponieważ ludzie od XSI Curses, w przypływie uszkodzenia mózgu, zmienili nieudokumentowaną właściwość SVr4 getm z napisu na wartość logiczną, zmieniając przez to offsety binarne wszystkich pozostałych właściwości.
Funkcje getmouse, mousemask, ungetmouse, mouseinterval i wenclose, związane z myszą, nie są częścią XPG4 ani SVr$. Zobacz dla dalszych szczegółów curs_mouse(3X).
Funkcja wresize nie jest częścią XPG4, i nie jest obecna w SVr4. Więcej szczegółów znajdziesz w curs_resize(3X).
W historycznych wersjach curses, opóźnienia zawarte we właściwościach cr, ind, cub1, ff i tab uaktywniały odpowiadające im bity opóźnień w UNIX-owym sterowniku tty. W tej implementacji wypełnianie jest dokonywane wysłaniami znaków NUL. Metoda ta jest trochę bardziej kosztowna, lecz znacząco zawęża interfejs z jądrem UNIX-a i odpowiednio do tego polepsza przenośność pakietu.
W standardzie XSI i w stronach podręcznika SVr4, wiele wpisów ma argumenty prototypopwe char *const (lub cchar_t *const, lub wchar_t *const, lub void *const). Zależnie od interpretacji standardu ANSI C (zobacz sekcję 3.5.4.1), deklaracje te są (a) bez znaczenia, lub (b) bez znaczenia i niedozwolone. Deklaracja const char *x to modyfikowalny wskaźnik do modyfikowalnych danych, lecz char *const x to niemodyfikowalny wskaźnik do modyfikowalnych danych. Ponieważ C przekazuje argumenty przez wartość, <typ> *const jako typ formalny jest co najmniej wątpliwy. Ta więc w tej implementacji zamieniono je globalnie na const <type> *.
UWAGI
Plik nagłówkowy <curses.h> automatycznie włącza pliki <stdio.h> i <unctrl.h>.Jesli standardowe wyjście, programu curses jest przekierowywane do czegoś, co nie jest tty, odświeżenia ekranu będą kierowane na standardowe wyjście błędu. Jest to nieudokumentowana właściwość curses z AT&T SVr3.
AUTORZY
Zeyd M. Ben-Halim, Eric S. Raymond. Zejście z oryginalnych pcurses zrobił Pavel Curtis.INFORMACJE O TŁUMACZENIU
Powyższe tłumaczenie pochodzi z nieistniejącego już Projektu Tłumaczenia Manuali i może nie być aktualne. W razie zauważenia różnic między powyższym opisem a rzeczywistym zachowaniem opisywanego programu lub funkcji, prosimy o zapoznanie się z oryginalną (angielską) wersją strony podręcznika za pomocą polecenia:- man --locale=C 3ncurses ncurses
Prosimy o pomoc w aktualizacji stron man - więcej informacji można znaleźć pod adresem http://sourceforge.net/projects/manpages-pl/.