home *** CD-ROM | disk | FTP | other *** search
/ Fish 'n' More 2 / fishmore-publicdomainlibraryvol.ii1991xetec.iso / fish / libraries / curses_391 / curses.doc < prev    next >
Text File  |  1990-10-27  |  12KB  |  428 lines
  1.             AMIGA CURSES PACKAGE
  2.             ====================
  3.  
  4. Author : Simon John Raybould    (sie@fulcrum.bt.co.uk)
  5. Date   : 21st April 1990
  6.  
  7.  
  8.     This is a brief description of the curses functions provided by this
  9. package. I have not gone into great detail as I assume the users of this to
  10. already have a knowledge of UN*X curses, more than likely porting UN*X screen
  11. based applications to the Amiga. There is plenty of curses documentation
  12. about so I will only outline each of the functions provided.
  13.  
  14.     Cheers
  15.  
  16.         Sie
  17.  
  18.  
  19.  
  20.  
  21. Below is a list of the supported functions and there operation.
  22. ===============================================================
  23.  
  24.  
  25. initscr()
  26.  
  27.     This is usually the first function called by a program. It creates
  28.     stdscr and must be called before any of the other functions will work.
  29.  
  30.  
  31. endwin()
  32.  
  33.     This should be called before exiting a curses program.
  34.     It frees all memory used and dismantles all structures.
  35.     It closes the custom screen and window used.
  36.  
  37.  
  38. beep()
  39.  
  40.     Produces an audible beep from the speaker. This beep is similar in pitch
  41.     and duration to the beep from a terminal when a BEL (^G) character is
  42.     recieved.
  43.  
  44.  
  45. flash()
  46.  
  47.     Flashes the display by complementing the background colour. With the
  48.     default black background, this will flash the screen yellow.
  49.  
  50.  
  51. box(window, vertical, horizontal)
  52.  
  53.     Draws a box around the edge of the window.
  54.     window     - pointer returned from newwin or subwin, or stdscr even.
  55.     vertical   - character to use for the verticals.
  56.     horizontal - character to use for the horizontals.
  57.  
  58.     Either of the characters may be zero. In this case, the defaults of
  59.     '|' and '-' will be used for vertical and horizontal respectivly.
  60.  
  61.     NOTE
  62.     ----
  63.     The box drawn is INSIDE the window. Therefore any of the clear routines
  64.     will effect the box if carried out on its window.
  65.  
  66.  
  67. cbreak()
  68. nocbreak()
  69.  
  70.     cbreak() puts the terminal into CBREAK mode, making characters typed
  71.     available immediately.
  72.  
  73.     nocbreak() sets NOCBREAK mode and characters are not available until
  74.     a newline is typed.
  75.  
  76.     The default is NOCBREAK mode, so most programs call cbreak() before
  77.     doing any reads on the keyboard.
  78.  
  79.  
  80. crmode()
  81. nocrmode()
  82.  
  83.     As cbreak() and nocbreak() as shown above.
  84.  
  85.  
  86. clearok(WinPtr, flag)
  87.  
  88.     If flag is TRUE then this function will make every refresh clear the
  89.     display before updating it. If the flag is FALSE then the screen will
  90.     not be cleared on each refresh. The DEFAULT is FALSE.
  91.  
  92.  
  93. leavok(window, flag)
  94.  
  95.     If flag is TRUE then the cursor will not be displayed.
  96.     The default is FALSE and the cursor is displayed.
  97.  
  98.  
  99. subwin(orig, lines, cols, beg_line, beg_col)
  100.  
  101.     Creates a new window within another window. The original window has
  102.     its pointer passed as 'orig'.
  103.     The new window will be at line 'beg_line' and column 'beg_col' of the
  104.     window pointed to by 'orig'. It will be of size 'lines' lines of 'cols'
  105.     columns.
  106.  
  107.     A sub-window is part of its surrounding window. When the surrounding
  108.     window is refreshed, the sub-window is refreshed as well.
  109.  
  110.  
  111. newwin(lines, cols, beg_line, beg_col)
  112.  
  113.     Creates a new window at line 'beg_line' and column 'beg_col'.
  114.     The size of this window is 'lines' lines of 'cols' columns.
  115.  
  116.     The new window has its own data structures and does not affect any
  117.     data in other windows.
  118.  
  119.  
  120. delwin(window)
  121.  
  122.     Deletes a window and frees the associated memory. This should be done if
  123.     the window is no longer used.
  124.  
  125.     It is not necessary to free all windows, endwin() will free all windows
  126.     still allocated before returning.
  127.  
  128.  
  129. mvwin(window, new_line, new_col)
  130.  
  131.     Moves a window to a new position on the screen. This position is relative
  132.     to the top left of the screen and NOT to the start of any surrounding
  133.     window in the case of sub-windows.
  134.  
  135.  
  136. nl()
  137. nonl()
  138.  
  139.     nl() - Causes newline to newline/carriage return mapping on output and
  140.     return to newline mapping on input.
  141.  
  142.     nonl() - disables this.
  143.     The DEFAULT is that mapping is done.
  144.  
  145.  
  146. echo()
  147. noecho()
  148.  
  149.     echo() causes every character read to be echoed back to the display.
  150.     noecho() prevents the echo, this is useful when reading movement keys,
  151.     you don't want them echoed to the screen.
  152.     The DEFAULT is that echoing is performed.
  153.  
  154.  
  155. nodelay(window, flag)
  156.  
  157.     nodelay is enabled by a call : nodelay(stdscr, TRUE);
  158.     When in nodelay mode, getch will return -1 if there is no input pending.
  159.     The DEFAULT is nodelay FALSE and getch will wait for at least one char
  160.     in CBREAK mode or a newline otherwise.
  161.  
  162.  
  163. has_colors()
  164. start_color()
  165. init_color(n, r, g, b) 
  166.  
  167.     has_colors() is to check if colours are available on this terminal.
  168.     On the Amiga, it will simply return TRUE.
  169.  
  170.     start_colour() is to tell the terminal that you wish to use colour.
  171.  
  172.     init_color() will alter the Red, Green and Blue content of colour n.
  173.     r, g and b are in the range 1 to 1000. The colour number 'n' is in the
  174.     range 0 to 15 and it should be noted that colour 0 is the background
  175.     colour. Initially the foreground is set to colour 1 but can be changed
  176.     with the attron() or attrset() function to any of the colours 1 to 15,
  177.     0 is not allowed as this is the background. If 0 is selected, the
  178.     foreground colour will be set to 1.
  179.  
  180.  
  181. keypad(window, flag)
  182.  
  183.     If flag is TRUE then the ANSI sequences for the function keys and the
  184.     cursor keys will be converted to the tokens KEY_UP, KEY_HELP, e.t.c.
  185.     The DEFAULT is that the ANSI sequences will returned.
  186.     So to cause special keys to be returned as tokens in the standard screen,
  187.     add the following line:
  188.  
  189.         keypad(stdscr, TRUE);
  190.  
  191.  
  192. printw(fmt, args)
  193. wprintw(window, fmt, args)
  194. mvprintw(line, col, fmt, args)
  195. mvwprintw(window, line, col, fmt, args)
  196.  
  197.     Offer formatted output similar to printf(3).
  198.     printw() - prints at the current position in stdscr.
  199.     wprintw() - prints at the current position in window.
  200.     mvprintw() - prints at line 'line' column 'col' in stdscr.
  201.     mvwprintw() - prints at line 'line' column 'col' in 'window'.
  202.  
  203.  
  204. scanw(fmt, args)
  205. wscanw(window, fmt, args)
  206. mvscanw(line, col, fmt, args)
  207. mvwscanw(window, line, col, fmt, args)
  208.  
  209.     Offer formatted input similar to scanf(3).
  210.     scanw() - scans at the current position in stdscr.
  211.     wscanw() - scans at the current position in window.
  212.     mvscanw() - scans at line 'line' column 'col' in stdscr.
  213.     mvwscanw() - scans at line 'line' column 'col' in 'window'.
  214.  
  215.  
  216. scrollok(window, flag)
  217.  
  218.     When flag is true, curses will automatically scroll the window up one
  219.     line when output goes off the bottom.
  220.     E.g.
  221.             scrollok(stdscr, TRUE);
  222.     
  223.     stdscr will then be automatically scrolled up one line when output goes
  224.     off bottom of stdscr.
  225.     The DEFAULT is that the window will NOT be scrolled, the bottom line
  226.     will be used over and over again without scrolling.
  227.  
  228.  
  229. scroll(window)
  230.  
  231.     The window is scrolled up one line.
  232.  
  233.  
  234. setscrreg(top, bottom)
  235. wsetscrreg(window, top, bottom)
  236.  
  237.     Sets the region from line 'top' to line 'bottom' inclusive.
  238.     When output moves below line 'bottom', the region is scrolled up one line
  239.     ( if scrollok() has been called ).
  240.  
  241.  
  242. touchwin(window)
  243.  
  244.     Will force the window to be completely refreshed on the next call to
  245.     refresh by dumping all optimisation information. This can be useful if
  246.     the state of the screen is unknown or if a window was obscured by
  247.     another window which was not a subwindow of the one it covered. Then
  248.     you may need to touchwin() the window that was covered and refresh it.
  249.     
  250.  
  251. addch(c)
  252. waddch(window, c)
  253. mvaddch(line, col, c)
  254. mvwaddch(window, line, col, c)
  255.  
  256.     addch(c) - Prints character c at current screen position in stdscr.
  257.     addch(window, c) - Prints character c at current screen position in
  258.             window.
  259.     mvaddch(line, col, c) - Prints character c at line 'line' column 'col' in
  260.             stdscr.
  261.     mvwaddch(window, line, col, c) - Prints character c at line 'line' column
  262.             'col' in window.
  263.  
  264.  
  265. addstr(str)
  266. waddstr(window, str)
  267. mvaddstr(line, col, str)
  268. mvwaddstr(window, line, col, str)
  269.  
  270.     addstr(str) - Prints string str at current screen position in stdscr.
  271.     waddstr(window, str) - Prints string str at current screen position in
  272.             window.
  273.     mvaddstr(line, col, str) - Prints string str at line 'line' column 'col'
  274.             in stdscr.
  275.     mvwaddstr(window, line, col, str) - Prints string str at line 'line'
  276.             column 'col' in window.
  277.     
  278.  
  279. attrset(attrs)
  280. wattrset(window, attrs)
  281.  
  282.     These routines set the attributes for stdscr or the specified window in
  283.     the case of wattset() to the value passed in attrs. This is usually used
  284.     to get the attributes to a known state before using attron() and
  285.     attroff() to add and remove extra attributes respectively.
  286.  
  287.  
  288. attron(attrs)
  289. wattron(window, attrs)
  290.  
  291.     These routines add the attributes specified in attrs to those already set
  292.     for stdscr or the window specified in the case of wattron(). Any previous
  293.     attributes that are not directly affected by the changes will be left as
  294.     they were.
  295.  
  296.  
  297. attroff(attrs)
  298. wattroff(window, attrs)
  299.  
  300.     These routines remove the attributes specified in attrs from those set
  301.     for stdscr or the window specified in the case of wattroff().
  302.     Any previous attributes that are not directly affected by the changes
  303.     will be left as they were.
  304.  
  305.         e.g.
  306.                 attron(A_REVERSE)
  307.                 addstr("This is in inverse");
  308.                 attroff(A_REVERSE);
  309.                 refresh();
  310.  
  311.  
  312. standout()
  313. wstandout(window)
  314.  
  315.     These routines make the following text appear in inverse video.
  316.  
  317.  
  318. standend()
  319. wstandend(window)
  320.  
  321.     These routines will return the text type to normal video.
  322.  
  323.  
  324. clear()
  325. wclear(window)
  326.  
  327.     These routines will empty the screen buffer and will cause the screen
  328.     to be cleared on the next call to refresh().
  329.  
  330.  
  331. erase()
  332. werase(window)
  333.  
  334.     These routines will empty the screen buffer and will cause the screen
  335.     to be cleared on the next call to refresh(). Similar to erase() except
  336.     that these will call clearok() as well.
  337.  
  338.  
  339. clrtobot()
  340. wclrtobot(window)
  341.  
  342.     On the next refresh(), the window will be blanked from the current
  343.     position to bottom righthand corner.
  344.  
  345.  
  346. clrtoeol()
  347. wclrtoeol(window)
  348.  
  349.     On the next refresh(), the window will be blanked from the current
  350.     position to the end of the line.
  351.  
  352.  
  353. delch()
  354. wdelch(window)
  355. mvdelch(line, col)
  356. mvwdelch(window, line, col)
  357.  
  358.     These routines delete the character at the current position, the rest of
  359.     the line to the right of this character is slid along to the left to
  360.     fill the gap. This can be very useful in editors and the like.
  361.  
  362.  
  363. getch()
  364. wgetch(window)
  365. mvgetch(line, col)
  366. mvwgetch(window, line, col)
  367.  
  368.     These routines return the next character from the keyboard. If cbreak()
  369.     has been called then they return as soon as there is a character to read
  370.     else they wait for a <CR> before returning. If nodelay() has been called
  371.     then they will return a character if there is one or -1 if not.
  372.  
  373.  
  374. getstr()
  375. wgetstr(window)
  376. mvgetstr(line, col)
  377. mvwgetstr(window, line, col)
  378.  
  379.     These routines should be used to read a string in from the keyboard.
  380.     Delete is processed for you.
  381.  
  382.  
  383. inch()
  384. winch(window)
  385. mvinch(line, col)
  386. mvwinch(window, line, col)
  387.  
  388.     These routines return the character at the current position in the
  389.     window or at the specified position in the 'mv' cases.
  390.  
  391.  
  392. insch()
  393. winsch(window)
  394. mvinsch(line, col)
  395. mvwinsch(window, line, col)
  396.  
  397.     These routines insert a character at the current window position, or at
  398.     the specified position in the 'mv' cases. The remainder of the line is
  399.     shifted along to the right to make room. The character at the far right
  400.     is lost.
  401.  
  402.  
  403. insertln()
  404. winsterln(window)
  405.  
  406.     These routines insert a line at the current window position.
  407.     All of the lines below are shifted down and the bottom line is lost.
  408.  
  409.  
  410. deleteln()
  411. wdeleteln(window)
  412.  
  413.     These routines delete a line at the current window position.
  414.     All of the lines below are shifted up into the space and the bottom line
  415.     is left blank.
  416.  
  417.  
  418. move(line, col)
  419. wmove(window, line, col)
  420.  
  421.     These routines set the current position to line 'line' and column 'col'.
  422.  
  423. refresh()
  424. wrefresh(window)
  425.  
  426.     These routines cause all outstanding changes to 'stdscr' or the specified
  427.     window 'wrefresh' to be sent to the screen.
  428.