Opasarkisto: Ncurses: Osa 1 - Perusteet

Ncurses on API (Application Programming Interface) tekstigraafisten ohjelmien luomiseen. Ncurses sisältää työkalut ikkunoiden luomiseen, syötteen tulostamiseen, kursorin hallintaan, jne. Kyseinen kirjasto on vapaa (free software) klooni SVr4 cursesista. Ncursesin avulla pystyt helposti luomaan oman tekstigraafisen koodieditorin tai vaikka pelin. Käyttötarkoitukset venyvät hyötyohjelmista viihteeseen. Esimerkiksi kuuluisa roguelike Nethack käyttää Ncursesia (vaihtoehtoisesti). Muita esimerkkejä voisivat olla kommenteissa esille tulleet editorit vim ja nano.

Tässä oppaassa ei käsitellä Ncursesin lisännäisten eikä monien ikkunoiden käyttöä (Huomaa, ettei se ole sama asia kuin monta erillistä terminaalia/konsolia). Sisältö on hyvin paljolti perusteita. Ncurses on kuitenkin loppujen lopuksi helppo käyttää.

NCursesin asentaminen

Järjestelmästäsi riippuen käytä järjestelmäsi käyttämää paketinhallintaa. Ncurses on vain UNIX-tyylisille järjestelmille. Windowsille on olemassa PDCurses, joka on Curses-klooni. Tämä opas pätee myös jotakuinkin PDCursesin kohdalla. Lähdekoodipaketin mukana tulee hyvin kattava ohjeistus asennuksesta, joten en puutu asiaan sen enempää.

Ikkunan alustaminen

// Esittely:
WINDOW* initscr(void);
int endwin(void);

Curses-tilaan päästäksesi sinun täytyy kutsua alustusfunktiota:

initscr();

Tämän jälkeen ikkuna on curses-tilassa. initscr() 'päättelee' terminaalin ja tekee tarvittavat muistinvaraukset. Onnistuessaan initscr() palauttaa osoitteen stdscr:ään (standard screen). Jos initscr() kohtaa virheen, se kirjoittaa virheen stderr:ään ja lopettaa ohjelman suorituksen. Stdscr:n on se ikkuna, johon esim. printw() oletuksena tulostaa tekstiä.

Curses-tilan lopettaminen onnistuu funktiolla:

endwin();

Edellä mainittu funktio siis vain lopettaa curses-tilan. Jos tätä funktiota ei kutsuta, ja ohjelmasta poistutaan, voi terminaali, jossa curses-ohjelma pyöri, käyttäytyä hyvin oudosti.

Muita curses-tilan muokkaamiseen tarkoitettuja (tärkeitä ja vaihtoehtoisia) funktoita ovat:

int raw(void);

raw() kutsutaan esimerkiksi heti ohjelman (initscr():n jälkeen) alussa. Pakollista se ei ole. Raw yksinkertaisesti sanottuna muuttaa tapaa, jolla ohjelma lukee syötettä näppäimistöltä. Kun ohjelma on kutsunut Rawia, näppäimistöltä saatu syöte on heti käytettävissä. Uutta riviä (new line) tai carriage returnia ei enää tarvita, jotta syöte olisi ohjelman käsiteltävissä. Tämä mahdollistaa interaktiivisen ympäristön helpon luomisen, esimerkiksi pelejä silmällä pitäen.

int noecho(void);

noecho() poistaa "echon" (kaiun), joka tapahtuu, kun käyttäjä antaa syötteen getch():n (tai jonkin muun input-funktion) pyytämänä. Normaalisti käyttäjän antaessa syötteen tämä syöte myös tulostuisi ikkunaan, mutta noecho() poistaa tämän ominaisuuden. Ominaisuuden saa takaisin päälle echo()-kutsulla.

int curs_set(int visibility);

curs_set() funktion avulla saadaan kursori pois näkyvistä (anna funktiolle parametri 0), normaalisti näkyvä (1) ja vielä voimakkaammin esille tuova (2).

int start_color(void);
bool has_colors(void);

start_color() funktion avulla saadaan värit käyttöön. Tämä tehdään yleensä initscr()-kutsun jälkeen. Funktio ei palauta mitään arvoa, joka kertoisi, pystyykö käytössä oleva konsoli väreihin curses-tilassa. Tätä varten on funktio has_colors(), joka palauttaa TRUEn, jos konsoli pystyy väreihin, ja FALSEn jos ei.

int keypad(WINDOW *win, bool bf);

Keypad() ottaa parametriksi ikkunan, jossa halutaan tämä "keypad" ominaisuus päälle. Se on joko päällä (TRUE) tai ei päällä (FALSE). Tämän käyttäminen mahdollistaa nuolinäppäinten ja F1, F2, jne. näppäinten käytön.

// Esimerkkiohjelma:

// Sisällytetään ncurses projektiin.
#include <ncurses.h>

int main(int argc, char** argv) {
  // Siirrytään curses-tilaan. Emme testaa vielä,
  // onnistuimmeko siirtymään ko. tilaan.
  initscr();

  // Nuolinäppäimet yms. käytettäviksi
  keypad(stdscr, TRUE);

  // Näppäinpainallusten puskurointi pois
  raw();

  // "Kaikuminen" pois.
  noecho();

  // Kursori pois näkyvistä.
  curs_set(0);

  // Värit päälle. Emme testaa vielä, pystyykö konsoli väreihin.
  start_color();

  // Odotellaan, että käyttäjä painaa jotain.
  getch();

  // Poistutaan curses-tilasta ja lopetetaan ohjelman suoritus.
  endwin();
  return 0;
}

Nyt esitellyt alustusfunktiot eivät toki ole ainoita, vaan niitä on useita muitakin. En kuitenkaan niitä tässä nyt mainitse.

NCurses-ohjelman kääntäminen

Käytämme kääntäjänä GNU GCC:tä, ja sen kohtalaisen tuoretta versiota (3.3.*-3.4.*) Itse ohjelman kääntäminen onnistuu konsolissa näin:

g++ source.cpp -o binaryname -lncurses

Käytä gcc:tä g++:n sijaan, jos teet C-ohjelmaa.

Ikkunaan tulostaminen

Alustuksien jälkeen on mahdollista tulostaa jotain ruudulle. NCurses tietenkin tarjoaa omat työkalunsa tähän. Printw()-funktio toimii ulkoisesti jotakuinkin niin kuin C-kielessä oleva printf()-funktio.

int printw(const char *fmt, ...);

Funktiolla printw():llä kuitenkin onnistuu "vain" tekstin tulostaminen samaan tyyliin kuin C-kielen printf:llä, joten mielekiintomme siirtyy seuraavaksi funktioon nimeltä mvprintw().

int mvprintw(int y, int x, const char *fmt, ...);

Funktio mvprintw() toimii muutoin samalla tapaa kuin printw(), paitsi että pystyt päättämään, mihin merkkijonon alku sijoitetaan. On siis esimerkiksi mahdollista tulostaa jokin merkkijono keskelle ruutua.

//Esimerkki:

// Sijoittaa merkkijonon "Hei, maailma!" kohtaan y = 5, x = 8.
// Yksi askel "koordinaatistossa" vastaa tietenkin yhtä kirjainta.
mvprintw(5,8,"Hei, maailma!");

Huomattavasti nopeampi tapa tulostaa yksittäisiä merkkejä on addch() ja/tai mvaddch().

int addch(const chtype ch);
int mvaddch(int y, int x, const chtype ch);

Esimerkki:
// Sijoittaa merkin @ kohtaan y = 10, x = 6.
mvaddch(10,6,'@');

Kyseiset funktio siis tulostavat merkin ruudulle. Mvaddchin tapauksessa pystyt ohjaamaan tätä paikkaa mvprintw:n tavoin.

// Esimerkkiohjelma:

#include <ncurses.h>

int main(int argc, char** argv) {
  initscr();
  raw();
  noecho();
  curs_set(0);
  start_color();

  // Luetaan näppäinpainallukset tähän apumuuttujaan.
  char ch = 0;

  // Tehdään silmukkaa niin kauan, kunnes pelaaja painaa q-kirjainta:
  do {
    // Luetaan näppäimistöltä.
    ch = getch();

    // Tulostetaan ruutua kohtaan Y = 0 (rivi numero 1), X = 5 (rivi numero 6).
    mvprintw(0,5,"Painoit juuri näppäintä %c. Sen ASCII-arvo on %d.",ch,(int)ch);
  }while(ch != 'q');

  endwin();
  return 0;
}

Ncurses sisältää monia muitakin tulostusfunktioita. Toinen hyödyllinen pari on addstr() ja mvaddstr(). Näitä funktioita voidaan käyttää pelkkien merkkijonojen tulostamiseen. Merkkijonon muotoilu täytyy siis olla jo valmiiksi tehty.

int addstr(const char *str);
int mvaddstr(int y, int x, const char *str);

// Esimerkki:
const char* name = "Harald Harvahammas";

// Tulostaa merkkijonon Harald Harvahammas
// kohtaan Y=10, X=0.
mvaddstr(10,0,name);

Jos ei välttämättä halua käyttää erikseen näitä mvaddstr- tai mvprintw-funktioita, on mahdollista siirtää pelkästään itse kursoria. Tämä onnistuu funktiolla move().

int move(int y, int x)

// Liikutetaan kursori kohtaan Y=9,X=1
move(9,1);
// Tulostetaan kohtaan Y=9,X=1 merkkijono
printw("Hei, maailma!");

Syötteen lukeminen

Syötteen lukeminen on Ncursesin avulla helppoa. Aikaisemmin käytimme jo getchiä. Tämä funktio siis jää odottamaan käyttäjältä yhtä syötettä, ja jos raw() (tai cbreak) on päällä, (jompaa funktioita olisi siis kutsuttu), riittäisi mikä tahansa napin painallus.

int getch(void);

Funktio getch() siis palauttaa painamasi näppäimen ASCII-arvon. Kuten paluuarvosta näetkin, kannattaa se tallettaa int-tyyppiseen muuttujaan käsittelyä varten.

getch() on kätevä esim. valikkoja ja niissä liikkumista silmällä pitäen. Joskus kuitenkin tulee eteen tilanne, jolloin halutaan lukea käyttäjältä kokonainen merkkijono.

int getstr(char* str);

Funktiolle tulee siis antaa parametrina se merkkijono, johon haluat tallentaa pelaajan syötteen. Syötteen lukeminen lopetetaan, kun funktio kohtaa uuden rivin, carriage returnin tai EOF-merkin.

//Esimerkkiohjelma:

#include <ncurses.h>
#include <string>

using namespace std;

int main(int argc, char** argv) {
  initscr();
  raw();
  keypad(stdscr, TRUE);
  curs_set(0);
  noecho();
  start_color();

  int maxX, maxY;
  const int minWindowSizeX = 60;
  const int minWindowSizeY = 20;
  int maxNameSize = 20;

  // Hakee stdscr:n Y:n ja X:n suurimman koon.
  // Eli sen, miten iso ikkuna tällä hetkellä on.
  getmaxyx(stdscr,maxY,maxX);

  // Jos konsoli tai ikkuna oli liian pieni,
  // pyydetään käyttäjää suurentamaan sitä.
  if(maxX < minWindowSizeX || maxY < minWindowSizeY) {
    printw("Ikkunasi on liian pieni ohjelmalle. Suurenna ikkuna kokoon %d x %d, jotta se toimisi oikein.", minWindowSizeX, minWindowSizeY);
    getch();
    endwin();
    return 0;
  }

  char playerName[maxNameSize];

  // Echo päälle, jotta pelaaja näkee,
  // mitä on kirjoittamassa.
  echo();
  // Luetaan merkkijono playerNameen.
  getstr(playerName);
  // Echo pois.
  noecho();

  mvprintw(0, 0, "Your name is: %s", playerName);

  mvprintw(maxY/2,maxX/3,"NCurses program");

  // Odotetaan, että pelaaja painaa jotain.
  getch();

  endwin();
  return 0;
}

Yllä olevassa esimerkissä on kuitenkin olemassa ylivuodon vaara. Tämä johtuu siitä, että getstr(char *str) lukee merkkejä niin paljon kuin käyttäjä haluaa syöttää. On siis varsin helppoa mennä yli sallitun määrän. Tällaisia tilanteita varten on olemassa getnstr(char *str, int n).

getnstr(char *str, int n);

Kuten arvata saattaa, getnstr lukee merkkejä n suuruisen kokonaisluvun verran.

Attribuutit tulostuksen yhteydessä

Attribuuttien avulla on mahdollista muotoilla ja kustomoida tulostetta. Esimerkiksi lihavoitu teksti ja värit ovat attribuuttien avulla mahdollisia. Ncursesin tarjoamat attribuutit ovat nämä:

Listattujen asioiden lisäksi ovat attribuutit A_PROTECT ja A_CHARTEXT. En käsittele niitä tässä.

Miten näitä muita sitten käytetään? Jos haluat laittaa pidemmäksi aikaa jonkin attribuutin päälle, käytä attron()- ja attroff()-funktioita.

int attron(int attrs);
int attroff(int attrs);

Attribuutteja voi kerralla kytkeä monta päälle. Tämä onnistuu bittioperaattori tailla ( | ).

//Esimerkki:

// Lihavointi ja alleviivaus päälle.
attron(A_BOLD|A_UNDERLINE);
// Tulostetaan lihavoitua ja alleviivattua tekstiä.
printw("Hei, maailma!");
// Otetaan lihavointi pois päältä.
// Huomaa, että alleviivaus jää päälle!
attroff(A_BOLD);

Yksittäistä merkkiä lisättäessä voi mieleesi tulla, miksi aina tehdä erikseen attron() ja attroff()-härdelli? Tähän löytyy nopeampi tapa, joka kuitenkin toimii vain addch() ja muilla vastaavilla yhden merkin tulostavilla funktioilla.

// Esimerkki:
// Tulostetaan lihavoitu ja alleviivattu A-kirjain.
addch('A'|A_BOLD|A_UNDERLINE);

Värit tuovat visuaalista ilmettä ohjelmaasi. Ncursesiin on valmiiksi määritelty makroina 8 perusväriä. Omia värejä pystyy toki luomaan. Ensiksi tulee kuitenkin testata, pystyykö terminaali vaihtamaan värejä:

int init_pair(short pair, short f, short b);
int init_color(short color, short r, short g, short b);
bool can_change_color();

//Esimerkki:

// Otetaan arvo talteen, joka kertoo, pystyykö
// terminaali vaihtamaan väriasetuksia.
bool allowColorChange = can_change_color();

// Jos pystyy, vaihdetaan värin nro 1. määritystä.
if(allowColorChange == true) {
  // Tämän jälkeen väriä nro. 1 voidaan muuttaa näin:
  init_color(1, 66, 22, 33);

  // Valkoista tekstiä yllä määritellyllä taustavärillä.
  init_pair(6,COLOR_WHITE,1);
} else {
  // Valkoista mustalla taustalla, väripari nro. 6.
  init_pair(6,COLOR_WHITE,COLOR_BLACK);
}

// Väripari otetaan näin käyttöön:
attron(COLOR_PAIR(6));

// Ja pois päältä:
attroff(COLOR_PAIR(6));

Yllä olevassa esimerkissä init_color() muuttaa väriä numero 1. R-,G-,B-arvot täytyvät olla väliltä 0-1000.

Lisähuomautus (lisätty 27.8.2008):

lainaus:

NCurses, joka on käännetty vakioasetuksilla, ei tue enempää kuin kuuttatoista väriä. Tuki 256:lle värille löytyy, mutta se täytyy itse aktivoida kääntämällä ncurses --enable-ext-colors lippu päällä. Tällä taas on vaikutusta kirjastojen binääri-yhteensopivuuteen, koska tämä muuttaa cchar_t:n kokoa. Tällä taas on sitten muita implikaatioita, joista en ole aivan selvillä.

Yllä olevan lisäksi terminaalin tulee myös tukea 256 väriä, sekä sitä, että paletin muuttaminen on sallittua.

Makroina löytyvät värit ovat seuraavat:

Muita Ncurses-funktioita

// Esittelyt:

int erase(void);
int clear(void);
int refresh(void);
int getmaxyx(WINDOW* screen, int y, int x);
int clrtoeol(void);

Funktiot erase() ja clear() tyhjentävät ruudun (näissä kahdessa funktiossa on kuitenkin eroavaisuutensa), refresh() taas näyttää stdscr:n sisällön. Funktio getmaxyx() asettaa kahteen annettuun muuttujaan (y ja x) parametrina annetun ikkunan maksimikoon. Ja viimeisenä clrtoeol() (Clear to end of line) tyhjentää kursorin oikealta puolelta kaiken.

Esimerkkiohjelma

/* Ohjelma tulostaa konsoliin satunnaisiin kohtiin satunnaisia merkkejä satunnaisilla väreillä. */

#include <ncurses.h>
#include <ctime>
#include <cstdlib>

int main(int argc, char** argv) {
  // Alustetaan satunnaislukugeneraattori.
  srand((unsigned int)time((time_t *)NULL));

  initscr();
  noecho();
  raw();
  curs_set(0);
  start_color();

  int ch = 0;

  // Looppikerrat
  const int loopKerrat = 10000;

  // Arpomista varten
  int valittuVari = 0;
  char valittuMerkki = 0;
  int valittuPaikkaX = 0, valittuPaikkaY = 0;

  // Ovatko värit käytettävissä?
  bool varitKaytossa = has_colors();

  // Konsolin tämän hetkinen koko.
  int ikkunaKokoX = 0, ikkunaKokoY = 0;
  getmaxyx(stdscr,ikkunaKokoY,ikkunaKokoX);

  // Tehdään niin kauan, kunnes kierroksia tulee loopKerrat verran täyteen.
  int count = 0;
  while(count < loopKerrat) {

    // Valitaan XY sijainti
    valittuPaikkaX = rand()%ikkunaKokoX;
    valittuPaikkaY = rand()%ikkunaKokoY;
    // Valitaan tulostettava merkki
    // väliltä 32-127 ASCII-taulukosta.
    valittuMerkki = rand()%95+32;

    // Jos värit ovat käytettävissämme,
    // Laitamme ohjelmaan väriä!
    if(varitKaytossa == true) {
      // Mustaa ei oteta mukaan (väri nro. 0)
      valittuVari = rand()%7+1;

      // Teemme uuden väriparin.
      // Parin numero on sama kuin kirjaimen värin numero, jottei tulisi sekaannusta.
      init_pair(valittuVari,valittuVari,COLOR_BLACK);
    }
    // Tulostetaan kirjain värin kanssa.
    mvaddch(valittuPaikkaY,valittuPaikkaX,valittuMerkki|COLOR_PAIR(valittuVari));
    count += 1;

    // Näytetään stdscr:n sisältö joka kierroksen jälkeen.
    refresh();
  }
  endwin();
  return 0;
}

Lisätietoa

Tämän oppaan kirjoittamisessa on käytetty sivua http://en.tldp.org/HOWTO/NCURSES-Programming-HOWTO/ ja Unixin man-sivuja.