@DataBase   "Curses.guide"

@REMARK "$VER: Curses.guide 1.5 (09/29/98) by James T. Steichen

@REMARK Written by Jim Steichen, Copyright (c) 1998.

@WIDTH 75
@WORDWRAP

@NODE main  "Curses implementation for AmigaTalk© 1998:"

   The Curses interface for the @{B}AmigaTalk@{UB} system is documented herein
   & is only a subset of the complete Curses package utilized by the
   rest of the world.  Most of the methods are accessed from primitive 124,
   with the exception of the @{B}printAt:@{UB} method, which uses primitive 126.
   
   The following Curses functions are NOT implemented by AmigaTalk, since
   they use variable arguments & it will take someone with more than my
   miniscule knowledge of smalltalk to utilize them.  They can be faked
   by using other parts of the @{B}AmigaTalk@{UB} system & the Curses package, so
   in a sense they are redundant anyway:
@{FG SHINE}   
      int printw(    char *fmt, ... );

      int wprintw(   WINDOW *win, char *fmt, ... );

      int mvprintw(  int line, int col, char *fmt, ... );

      int mvwprintw( WINDOW *win, int line, int col, char *fmt, ... );

      int scanw(     char *fmt, ... );

      int wscanw(    WINDOW *win, char *fmt, ... );

      int mvscanw(   int line, int col, char *fmt, ... );

      int mvwscanw(  WINDOW *win, int line, int col, char *fmt, ... );
@{FG TEXT}

   Methods available for the Curses package are:
   
   @{" Curses Control " LINK CursesControl}
   @{" Text Display   " LINK TextDisplay}
   @{" Text Retrieval " LINK TextRetrieval}
   @{" Text Insertion " LINK TextInsertion}
   @{" Text Removal   " LINK TextRemoval}
   
   @{" Miscellaneous  " LINK MiscFunctions}
@ENDNODE

@NODE CursesControl "Control of the Curses Package:"             

  @{FG SHINE}
   new @{FG TEXT}

     Initialize the Curses Class.

  @{FG SHINE}
   initialize @{FG TEXT}
 
     Open the Curses screen (equivalent to initscr()).

  @{FG SHINE}
   closeDown @{FG TEXT}
 
     Kill the Curses environment (equivalent to endwin())

  @{FG SHINE}
   initializeWithColors: depth @{FG TEXT}

     Open the Curses screen & use colors (equivalent to: 
     StartColor() [non-standard Curses] followed by initscr()).
     
  @{FG SHINE}
  initWithStdColors @{FG TEXT}

     Open the Curses screen & use colors (equivalent to: 
     start_colors() followed by initscr()).
     
  @{FG SHINE}
  openWindow: xStart yStart: y width: w height: h @{FG TEXT}

     Open a new Curses window (equivalent to newwin()).

  @{FG SHINE}
  openSubWindow: parent xStart: x yStart: y width: w height: h @{FG TEXT}

     Open a Curses sub-window (equivalent to subwin()).

  @{FG SHINE}
  refreshScreen @{FG TEXT}
   
     Refresh the Curses environment (equivalent to refresh()).   

  @{FG SHINE}
  refreshWindow: winNumber @{FG TEXT}

     Refresh a single Curses window (equivalent to wrefresh()).

  @{FG SHINE}
  closeWindow: winNumber @{FG TEXT}

     Close a Curses window (equivalent to delwin(), followed by
     @{B}refreshScreen@{UB}).

  @{FG SHINE}
  moveWindow: winNumber x: x y: y @{FG TEXT}

     Move a Curses window (equivalent to mvwin(), followed by
     @{B}refreshWindow:@{UB}).

  @{FG SHINE}
  cBreak: status @{FG TEXT}

     Either set (status = TRUE: call cbreak()) or reset 
     (status = FALSE: call ncbreak()) the control-break of the 
     Curses system. 

  @{FG SHINE}
  enableClear: winNumber status: status @{FG TEXT}

     Either enable (clearok( status = TRUE )) or disable
     (clearok( status = FALSE )) the clear function for the given
     window.

  @{FG SHINE}
  enableCursor: winNumber status: status @{FG TEXT}

     Either enable (leaveok( status = TRUE )) or disable
     (leaveok( status = FALSE )) the cursor for the given window.

  @{FG SHINE}
  newlineMap: status @{FG TEXT}

     Either enable (nl(), status = TRUE) or disable
     (nonl(), status = FALSE) the mapping of CRLF to CR function for 
     the given window.

  @{FG SHINE}
  echo: status @{FG TEXT}

     Either enable (echo(), status = TRUE) or disable
     (noecho(), status = FALSE) the echo function for the given window.

  @{FG SHINE}
  enableDelay: winNumber status: status   @{FG TEXT}

     Either enable (nodelay( status = FALSE )) or disable
     (nodelay( status = TRUE )) the delay function for the given window.

  @{FG SHINE}
  setColor: number red: r green: g blue: b @{FG TEXT}

     Change the color register @{B}number@{UB} to the new RGB values supplied
     then perform @{B}refreshScreen@{UB}.

  @{FG SHINE}
  setTextPenColor: colornum @{FG TEXT}

     Change the text color rendering pen to register @{B}colornum@{UB}.
     NOTE:  Non-standard Curses.

  @{FG SHINE}
  setBackPenColor: colornum @{FG TEXT}

     Change the background color rendering pen to register @{B}colornum@{UB}.
     NOTE:  Non-standard Curses.

  @{FG SHINE}
  setDrawMode: mode @{FG TEXT}

     Change the drawing mode to @{B}mode@{UB}.  Allowable modes are:
        
       0 = JAM1
       1 = JAM2
       2 = COMPLEMENT
       4 = INVERSEVID
       
     NOTE:  Non-standard Curses.

  @{FG SHINE}
  enableScroll: winNumber status: status @{FG TEXT}

     Either enable (scrollok( status = TRUE )) or disable
     (scrollok( status = FALSE )) the scroll function for the given window.

  @{FG SHINE}
  enableKeyPad: winNumber status: status @{FG TEXT}

     Either enable (keypad( status = TRUE )) or disable
     (keypad( status = FALSE )) the following key values to be sent to
     the given window:

       KEY_BACKSPACE   0010          /* backspace character */
       KEY_DC          0177          /* Delete character    */
       KEY_DOWN        0400          /* The down arrow key  */
       KEY_UP          0401          /* The up arrow key    */
       KEY_LEFT        0402          /* The left arrow key  */
       KEY_RIGHT       0403          /* The right arrow key */
       KEY_HELP        0404          /* Help Key            */
       KEY_F0          0405          /* Function keys       */
       KEY_F(n)        (KEY_F0+(n))

  @{FG SHINE}
  scrollWindow: winNumber @{FG TEXT}

    Scroll the given window (scroll(), followed by @{B}refreshWindow:@{UB}).

  @{FG SHINE}
  setScrollRegion: top Bottom: bott @{FG TEXT}

    Setup the scroll region for the Curses system (equivalent to
    setscrreg(), followed by @{B}refreshScreen@{UB}).

  @{FG SHINE}
  setWindowScrollRegion: winNumber top: top Bottom: bott @{FG TEXT}

    Setup the scroll region for the given window (equivalent to
    wsetscrreg(), followed by @{B}refreshWindow:@{UB}).

  @{FG SHINE}
  windowNeedsRefresh: winNumber @{FG TEXT}

    Tell Curses to add the given window to the refresh list.

  @{FG SHINE}
  setAttributes: attrs @{FG TEXT}

    Setup the Curses system attributes, where @{B}attrs@{UB} is one or more of 
    the following:
       
        NORMAL    = 0
        INVERSE   = 16
        UNDERLINE = 32
        BOLD      = 64    Follow up with a call to @{B}refreshScreen@{UB}.

  @{FG SHINE}
  setWindowAttributes: winNumber attr: attrs @{FG TEXT}

    Setup the given window attributes, where @{B}attrs@{UB} is one or more of 
    the following:
       
        NORMAL    = 0
        INVERSE   = 16
        UNDERLINE = 32
        BOLD      = 64    Follow up with a call to @{B}refreshWindow:@{UB}.

  @{FG SHINE}
  addAttributes: attrs @{FG TEXT}

    Add a Curses system attribute, where @{B}attrs@{UB} is one or more of 
    the following:
       
        NORMAL    = 0
        INVERSE   = 16
        UNDERLINE = 32
        BOLD      = 64    Follow up with a call to @{B}refreshScreen@{UB}.

  @{FG SHINE}
  addWindowAttributes: winNumber attr: attrs @{FG TEXT}

    Add an attribute to the given window, where @{B}attrs@{UB} is one or 
    more of the following:
       
        NORMAL    = 0
        INVERSE   = 16
        UNDERLINE = 32
        BOLD      = 64    Follow up with a call to @{B}refreshWindow:@{UB}.

  @{FG SHINE}
  removeAttributes: attrs @{FG TEXT}

    Remove a Curses system attribute, where @{B}attrs@{UB} is one or more of 
    the following:
       
        NORMAL    = 0
        INVERSE   = 16
        UNDERLINE = 32
        BOLD      = 64    Follow up with a call to @{B}refreshScreen@{UB}.

  @{FG SHINE}
  removeWindowAttributes: winNumber attr: attrs @{FG TEXT}

    Remove an attribute from the given window, where @{B}attrs@{UB} is one or 
    more of the following:
       
        NORMAL    = 0
        INVERSE   = 16
        UNDERLINE = 32
        BOLD      = 64    Follow up with a call to @{B}refreshWindow:@{UB}.

  @{FG SHINE}
  invertColors @{FG TEXT}

    Perform a Curses standout() command, followed by @{B}refreshScreen@{UB}.

  @{FG SHINE}
  invertWindowColors: winNumber @{FG TEXT}

    Perform a Curses wstandout() command, followed by @{B}refreshWindow:@{UB}.

  @{FG SHINE}
  revertColors @{FG TEXT}

    Undo the @{B}invertColors@{UB} (standout()) command by performing a standend()
    Curses command, followed by @{B}refreshScreen@{UB}.

  @{FG SHINE}
  revertWindowColors: winNumber @{FG TEXT}

    Undo the @{B}invertWindowColors@{UB} (wstandout()) command by performing a 
    wstandend() Curses command, followed by @{B}refreshWindow:@{UB}.

  @{FG SHINE}
  moveCursorTo: aPoint @{FG TEXT}

    Move the cursor from the current location to the given point
    (equivalent to move(), followed by @{B}refreshScreen@{UB}).

  @{FG SHINE}
  moveWindowCursor: winNumber to: aPoint @{FG TEXT}

    Move the cursor from the current location in the given window to 
    the given point (equivalent to wmove(), followed by @{B}refreshWindow:@{UB}).

  @{FG SHINE}
  addToRefreshList: winNumber @{FG TEXT}

    Add the given window to the refresh list (equivalent to 
    wnoutrefresh()).

  @{FG SHINE}
  updateWindows @{FG TEXT}

    Update all windows on the refresh list (equivalent to doupdate()).

  @{FG SHINE}
  flushKeys @{FG TEXT}

    Throw away all keystrokes in the system buffer (equivalent to 
    flushinp()).

  @{FG SHINE}
  moveCursorFrom: aPoint to: newPoint  @{FG TEXT}
  
    Move the cursor from the given point to the @{B}newPoint@{UB} (equivalent to
    mvcur(), followed by @{B}refreshScreen@{UB}).
@ENDNODE

@NODE TextDisplay "Displaying of Text for the Curses Package:"             

   For primitive 126, defined within the @{B}String@{UB} Class, @{B}printAt:@{UB} 
   is:
@{FG SHINE}   
   printAt:  The argument must be a @{B}Point@{UB} which describes a location on
             the @{I}Curses@{UI} screen.  The string is printed at the specified
             location.
@{FG TEXT}
  @{FG SHINE}
  printChar: c @{FG TEXT}

    Print a character @{B}c@{UB} at the current cursor location (equivalent to
    addch(), followed by @{B}refreshScreen@{UB}).    

  @{FG SHINE}
  printWindowChar: winNumber char: c  @{FG TEXT}

    Print a character @{B}c@{UB} at the current cursor location in the
    given window (equivalent to waddch(), followed by @{B}refreshWindow:@{UB}).

  @{FG SHINE}
  printChar: c at: thePoint @{FG TEXT}

    Print a character @{B}c@{UB} at the given location (equivalent to
    mvaddch(), followed by @{B}refreshScreen@{UB}).    

  @{FG SHINE}
  printWindowChar: winNumber char: c at: thePoint @{FG TEXT}

    Print a character @{B}c@{UB} at the given location in the
    given window (equivalent to mvwaddch(), followed by @{B}refreshWindow:@{UB}).

  @{FG SHINE}
  printString: string @{FG TEXT}

    Print @{B}string@{UB} at the current cursor location (equivalent to
    addstr(), followed by @{B}refreshScreen@{UB}).    

  @{FG SHINE}
  printWindowString: winNumber string: string @{FG TEXT}

    Print a @{B}string@{UB} at the current cursor location in the
    given window (equivalent to waddstr(), followed by @{B}refreshWindow:@{UB}).

  @{FG SHINE}
  printString: string at: thePoint @{FG TEXT}

    Print a @{B}string@{UB} at the given location (equivalent to
    mvaddstr(), followed by @{B}refreshScreen@{UB}).    

  @{FG SHINE}
  printWindowString: winNumber string: string at: thePoint @{FG TEXT}

    Print a @{B}string@{UB} at the given location in the
    given window (equivalent to mvwaddstr(), followed by @{B}refreshWindow:@{UB}).

@ENDNODE

@NODE TextRetrieval "Retrieving of Text for the Curses Package:"

  @{FG SHINE}
  getChar @{FG TEXT}

    Return the character at the current cursor location (equivalent to
    getch()).

  @{FG SHINE}
  getWindowChar: winNumber @{FG TEXT}

    Return the character at the current cursor location in the given
    window (equivalent to wgetch()).

  @{FG SHINE}
  getCharAt: aPoint @{FG TEXT}

    Return the character at the given location (equivalent to mvgetch()).

  @{FG SHINE}
  getWindowChar: winNumber at: aPoint @{FG TEXT}

    Return the character at the given location in the given window
    (equivalent to mvwgetch()).

  @{FG SHINE}
  getString: buffer @{FG TEXT}

    Return a string at the current cursor location (equivalent to getstr()).

  @{FG SHINE}
  getWindowString: winNumber buffer: string @{FG TEXT}

    Return a string at the current cursor location for the given window
    (equivalent to wgetstr()).

  @{FG SHINE}
  getStringAt: aPoint buffer: string @{FG TEXT}

    Return a string at the given location (equivalent to mvgetstr()).

  @{FG SHINE}
  getWindowString: winNumber at: aPoint buffer: string    @{FG TEXT}

    Return a string at the given location for the given window
    (equivalent to mvwgetstr()).

  @{FG SHINE}
  readChar @{FG TEXT}

    Wait for the user to type in a character (equivalent to inch()).

  @{FG SHINE}
  readWindowChar: winNumber @{FG TEXT}

    Wait for the user to type in a character in the given window 
    (equivalent to winch()).

  @{FG SHINE}
  readCharAt: aPoint @{FG TEXT}

    Wait for the user to type in a character at the given location
    (equivalent to mvinch()).

  @{FG SHINE}
  readWindowChar: winNumber at: aPoint @{FG TEXT}

    Wait for the user to type in a character at the given location in 
    the given window (equivalent to mvwinch()).

@ENDNODE

@NODE TextInsertion "Insertion of Text for the Curses Package:"

  @{FG SHINE}
  insertChar @{FG TEXT}

    Insert a character at the current cursor location (equivalent to
    insch(), followed by @{B}refreshScreen@{UB}).

  @{FG SHINE}
  insertWindowChar: winNumber @{FG TEXT}

    Insert a character at the current cursor location in the given 
    window (equivalent to winsch(), followed by @{B}refreshWindow:@{UB}).

  @{FG SHINE}
  insertCharAt: aPoint @{FG TEXT}

    Insert a character at the given location (equivalent to
    mvinsch(), followed by @{B}refreshScreen@{UB}).

  @{FG SHINE}
  insertWindowChar: winNumber at: aPoint @{FG TEXT}

    Insert a character at the given location in the given 
    window (equivalent to mvwinsch(), followed by @{B}refreshWindow:@{UB}).

  @{FG SHINE}
  insertLine @{FG TEXT}

    Insert a line at the current cursor location (equivalent to
    insertln(), followed by @{B}refreshScreen@{UB}).

  @{FG SHINE}
  insertWindowLine: winNumber @{FG TEXT}

    Insert a line at the current cursor location in the given 
    window (equivalent to winsertln(), followed by @{B}refreshWindow:@{UB}).

@ENDNODE

@NODE TextRemoval "Removal of Text for the Curses Package:"             

  @{FG SHINE}
  emptyScreen @{FG TEXT}

    Erase the Curses system display (equivalent to erase(), followed by
    @{B}refreshScreen@{UB}).

  @{FG SHINE}
  emptyWindow: winNumber @{FG TEXT}

    Erase the given window display (equivalent to werase(), followed by
    @{B}refreshWindow:@{UB}).

  @{FG SHINE}
  clearScreen @{FG TEXT}

    Clear the Curses system display (equivalent to clear(), followed by
    @{B}refreshScreen@{UB}).

  @{FG SHINE}
  clearWindow: winNumber @{FG TEXT}

    Clear the given window display (equivalent to wclear(), followed by
    @{B}refreshWindow:@{UB}).

  @{FG SHINE}
  clearScreenToBottom @{FG TEXT}

    Clear the Curses system display from the current location to the 
    bottom (equivalent to clrtobot(), followed by @{B}refreshScreen@{UB}).

  @{FG SHINE}
  clearWindowToBottom: winNumber @{FG TEXT}

    Clear the given window display from the current location to the 
    bottom (equivalent to wclrtobot(), followed by @{B}refreshWindow:@{UB}).

  @{FG SHINE}
  clearScreenToEOL @{FG TEXT}

    Clear the Curses system display from the current location to the 
    end of the current line (equivalent to clrtoeol(), followed by
    @{B}refreshScreen@{UB}).

  @{FG SHINE}
  clearWindowToEOL: winNumber @{FG TEXT}

    Clear the given window display from the current location to the 
    end of the current line (equivalent to wclrtoeol(), followed by
    @{B}refreshWindow:@{UB}).

  @{FG SHINE}
  deleteChar @{FG TEXT}

    Remove a character at the current cursor location from the Curses
    system display (equivalent to delch(), followed by @{B}refreshScreen@{UB}).

  @{FG SHINE}
  deleteWindowChar: winNumber @{FG TEXT}

    Remove a character at the current cursor location from the given
    window display (equivalent to wdelch(), followed by @{B}refreshWindow:@{UB}).

  @{FG SHINE}
  deleteCharAt: aPoint @{FG TEXT}

    Remove a character at the given cursor location from the Curses
    system display (equivalent to mvdelch(), followed by @{B}refreshScreen@{UB}).

  @{FG SHINE}
  deleteWindowChar: winNumber at: aPoint @{FG TEXT}

    Remove a character at the given cursor location from the given
    window display (equivalent to mvwdelch(), followed by @{B}refreshWindow:@{UB}).

  @{FG SHINE}
  deleteLine @{FG TEXT}

    Delete the current line the cursor is on (equivalent to deleteln(),
    followed by @{B}refreshScreen@{UB}).

  @{FG SHINE}
  deleteWindowLine: winNumber @{FG TEXT}

    Delete the current line the cursor is on in the given window 
    (equivalent to wdeleteln(), followed by @{B}refreshWindow:@{UB}).

@ENDNODE

@NODE MiscFunctions "Miscellaneous Curses methods:"             

  @{FG SHINE}
  drawBorder: winNumber hChar: hc vChar: vc @{FG TEXT}

     Draw a box around the given window (equivalent to box(), followed
     by @{B}refreshWindow:@{UB}). 

  @{FG SHINE}
  beep @{FG TEXT}

     Send a Ctrl-G (ASCII Bel) to the system.

  @{FG SHINE}
  flash @{FG TEXT}

     Flash the Curses screen.

  @{FG SHINE}
  hasColors @{FG TEXT}

     Return the status of the Curses screen color usage.

@ENDNODE