lib/TinyCon/README

   1 TinyCon - A tiny console library, written for C++
   2 --------------------------------------------------------------------------------
   3 License:  BSD
   4 Author:   Unix-Ninja | chris (at) unix-ninja (dot) com
   5 Version:  0.6
   6 Released: March 20, 2013
   7 --------------------------------------------------------------------------------
   8
   9 Perhaps you are writing an application that requires user input to a console on
  10 the commandline. There is the readline library from GNU, but it's license may
  11 be a bit restrictive for your type of application. Instead, TinyCon is meant to
  12 be a fairly light-weight and cross-platform input console library written in
  13 C++, that is released under a less restrictive license. It is available for
  14 Windows, OS X, and Linux. To use this library, simply include the tinycon.cpp
  15 source file into your project. Then you can create an instance of the
  16 "tinyConsole" class:
  17
  18   tinyConsole tc;
  19
  20 Optionally, you can also specify a custom command prompt when you delcare your
  21 instance:
  22
  23   tinyConsole tc("prompt> ");
  24
  25 To run tinycon, just use the run() method.
  26
  27   tc.run();
  28
  29 Tinycon will then sit and collect input from the user until the class registers
  30 a quit state, (by default this occurs when the user types "exit");
  31
  32 To compile the demo with GCC, you can run the following:
  33 $  g++ -o demo demo.cpp tinycon.cpp
  34
  35
  36 MAKING IT USEFUL
  37 -----------------
  38
  39 Tinycon becomes most useful when inheriting it in a custom class. Here, you have
  40 the option to over-ride the trigger() and hotkeys() methods. By doing so, you
  41 can define your own custom behaviour to how tinycon handles user input.
  42
  43
  44 REFERENCE
  45 ----------
  46
  47 getLine([int mode] [, string mask])
  48     This method will collect user input until the return key is pressed. Once
  49     collected, it will return the input as a string.
  50     Optionally, you can specify the mode of operation as either M_LINE (default)
  51     or M_PASSWORD. Setting this to M_PASSWORD will supress echoing of the input
  52     characters as they are typed.
  53     A mask can also be supplied when using M_PASSWORD mode. If given, the mask
  54     will be echoed to the screen instead of the characters being typed.
  55
  56 hotkeys(char c)
  57     This method will trigger each time a key is pressed. You can override this
  58     method in an inherited class, and use it to evaluate the value of "c" in
  59     order to perform some action that matches your criteria.
  60     (Please note, the enter key does NOT trigger the hotkeys method).
  61
  62 run()
  63     This method starts collecting input from the user in an infinite loop. It
  64     will terminate when a "quit" state is registered.
  65
  66 setBuffer(string s)
  67     This method will copy the contents of the current line buffer with the
  68     contents of the given string "s".
  69
  70 setMaxHistory(int size)
  71     This method setst the size of the history buffer. You can use this to
  72     control the total number of commands that tinycon can remember. A user can
  73     use the up and down arrow keys to scroll through history on the commandline.
  74
  75 trigger(string input)
  76     When a user presses the enter key, their input is passed as a string to this
  77     method. You can override this method in an inherited class to process a
  78     user's input.
  79
  80 quit(boolean state)
  81     This method registered the quit state of the console. It can be set to true
  82     or false;
  83
  84