tkar 0.63

data/.gitignore

@@ -0,0 +1,5 @@
+*.bck
+pkg
+doc
+tmp
+misc

data/FAQ.rdoc

@@ -0,0 +1,39 @@
+= Design Decisions
+
+== what is tkar trying to be?
+
+The gnuplot of animation -- a quick and dirty way to get data (stream or file) into a window to see what is happening.
+
+== why Tk?
+
+Tcl/Tk is widely available, and the Ruby/Tk interface is a standard part of ruby.
+
+== why TkCanvas?
+
+TkCanvas has easy access to relatively high-level 2D vector graphics constructs, such as groups, layers, splines, fonts, icons, zoom, and scroll. Plus, it supports mouse/keyboard operations, dialogs, and so on.
+
+== why not just write code in Ruby/Tk instead of stream to tkar?
+
+1. Because you may not want to write your code in the Tk framework. Maybe you're using a different gui, or not a gui at all.
+
+2. Tkar handles a lot of window / process complications such as drag-and-drop and following (see canvas.rb and window.rb for details).
+
+3. You can write upstream code in any language, or even just cat from a file.
+
+4. You can distribute processing: take advantage of 2 cpus, or even 2 hosts across a network.
+
+== why not HTML 5 canvas, other gui canvas, or Processing?
+
+Those are heavyweight and add more dependencies (browser, java), and in some cases still lack some of the features of TkCanvas. Tkar is light enough that you can run several instances at once even on resource limited machines.
+
+== why not opengl?
+
+It would be more work to get the diagram and user interaction stuff. Anyway, it's overkill.
+
+== why a special protocol, rather than ruby/tk method calls serialized as text?
+
+The protocol is not a programming language: there are no variables, functions, loops, etc. There are only macros. It is very simple, which makes it much easier to emit from other languages than ruby, and less prone to programming errors.
+
+== why is the protocol so ugly?
+
+It's not meant to be written by hand. You wouldn't write http headers by hand, would you?

data/History.txt

@@ -0,0 +1,175 @@
+tkar 0.63
+
+- Use bones and git.
+
+tkar 0.62
+
+- Added window_xy command.
+
+tkar 0.61
+
+- Permit CR chars after line continuation backslash.
+
+tkar 0.60
+
+- Fixed bug in simulink block: turn off verbose if stderr can't go to
+  either console or file, otherwise rubyw dies without exception.
+
+- Fixed bug in tkar/window.rb: sometimes drag_start is nil during draw_proc.
+
+- Performance improvement to simulink block: only wait for update response
+  if simulation is more than one step ahead of animation.
+
+- Added --version, lib/version.rb, and rake targets for maintaining this file.
+
+tkar 0.59
+
+- Minor doc updates for the simulink block.
+
+tkar 0.58
+
+- In --persist case, always update canvas on input EOF.
+
+tkar 0.57
+
+- Added mkgrid.rb.
+
+tkar 0.56
+
+- Updated protocol.txt.
+
+tkar 0.55
+
+- Added echo command.
+
+tkar 0.54
+
+- Added sample/dial.rb.
+
+- Option shortcuts: "fill" == "fc", and so on.
+
+tkar 0.53
+
+- Fixed problem in scale command.
+
+- Minor cleanup.
+
+tkar 0.52
+
+- Added delete_all and scale commands.
+
+tkar 0.51
+
+- Added tkar_period parameter to simulink block and tkar.c.
+
+- Refectored all state in tkar.c into TkarState struct.
+
+tkar 0.50
+
+- No more static data in tkar.c.
+
+tkar 0.49
+
+- Added more messages in verbose case.
+
+tkar 0.48
+
+- Added the "disable" parameter to tkar block.
+
+tkar 0.47
+
+- Fixed a dragging bug (clicking and dragging quickly allowed the mouse to
+  move outside the object).
+
+tkar 0.46
+
+- simulink/tkar.c now waits for "update"
+
+- consolidated docs
+
+tkar 0.45
+
+- Merged readme files into tkar.txt
+
+- Added protocol.txt.
+
+- Fixed bug in hovering over non-filled shape.
+
+- Fixed bug in layering code.
+
+tkar 0.44
+
+- Added tkarlib.mdl and slblocks.m to simulink/.
+
+- Added verbose param to tkar block
+
+tkar 0.43
+
+- Migrated to argos for argv option parsing.
+
+tkar 0.42
+
+- Preprocess floats "1234.00" --> "1234" so floats can be used for colors.
+
+- Accept backslash for line continuation.
+
+- Load command tries relative path after trying absolute.
+
+tkar 0.41
+
+- Added the simulink dir to project.
+
+tkar 0.40
+
+- Added the --persist, --radians, and --flip options.
+
+- Internally, angles are now stored in radians.
+
+- Added "load" and "exit" commands.
+
+tkar 0.39
+
+- Added --stderr option.
+
+- Impoved docs.
+
+tkar 0.38
+
+- Added help button.
+
+- Improved help window text.
+
+- Support for MouseWheel on MSWindows.
+
+tkar 0.37
+
+- Added help window.
+
+tkar 0.36
+
+- Support for TkcImages.
+
+tkar 0.35
+
+- improved dragging and scrolling
+
+tkar 0.34
+
+- added "bounds" command
+
+tkar 0.33
+
+- improvements to drag and drop
+
+tkar 0.32
+
+- added movie creation
+
+tkar 0.31
+
+- added -c flag
+
+tkar 0.30
+
+- First general release.
+

data/README.rdoc

@@ -0,0 +1,153 @@
+= <b>tkar</b> -- Tk-based animation process and protocol
+
+The Tkar animator aims to do one thing well: listen to an incoming stream of data and animate it in a 2D canvas. User interaction is streamed back out.
+
+To skip to the protocol documentation: {protocol}[link:files/protocol_rdoc.html].
+
+Also of interest:
+{FAQ}[link:files/FAQ_rdoc.html].
+
+== Overview
+
+Tkar is a Tk/ruby-based animation program using TkCanvas. It accepts command input from stdin or a socket. Commands may define parametrized shapes, place them on the canvas, move and rotate them, change parameters, etc. User interaction events (click, drag, etc) are sent back on the socket or stdout. The canvas can be resized, scrolled, zoomed, and tracked to an object.
+
+=== Graphical constructs
+
+* Shapes include: arc, oval, polygon, line, curve, text, bitmap. 
+
+* Parameters include color/pattern of border/area, arrowheads, splines, line dot/dash/width, text font, etc.
+
+* Can group, layer, rotate, move, and scale objects
+
+=== Tkar command summary
+
+_shape_:: define shape in terms of primitives (Tk Canvas objects). Shape may expose any Tk parameters (e.g, colors, lengths of poly sides)
+
+_add_:: add object to canvas with specified shape, layer, position, rotation, params
+
+_move_, _rotate_, _scale_, _delete_:: operate on existing object
+
+_param_:: change param value of an object (e.g. change color or geometry over time; change arrow shape because endpoint moves)
+
+utilities:: _wait_ (playback with specified frame rate), _update_ (end of time step), set window _params_ (color, size, zoom), _follow_ a specified object, _load_ file (like #include)
+
+=== User interaction
+
+* Use keys and mouse to zoom, pan/scroll, select, double-click, drag, drop, etc.
+
+* User commands are sent back over stream to controlling process
+e.g. "drag 2 140.0 259.0" and "drop 2 7" ("2" and "7" are object ids)
+
+
+== Installation
+
+=== Prerequisites
+
+==== Tcl/Tk
+
+For windows: http://www.activestate.com/Products/ActiveTcl/
+
+For linux, just use your distribution's package tool to install tcl. However, you may need to make sure that ruby and linux both use (or do not use) the pthread library.
+
+==== Ruby
+
+For windows: http://rubyforge.org/projects/rubyinstaller/
+
+For other platforms: http://www.ruby-lang.org
+
+=== Gem installation
+
+  gem install tkar
+
+=== Tarball installation
+
+Alternately, you can download and unpack the source code tar ball from rubyforge:
+
+  wget ...
+  tar xzvf ...
+  cd ...
+
+You can then either install it as follows:
+
+  ruby install.rb config
+  ruby install.rb setup
+  ruby install.rb install
+
+or you can run it in place using the <tt>--local-lib</tt> command line option
+
+  bin/tkar --local-lib
+
+
+== Usage
+
+=== Command line
+
+See the -h command line option for details on running tkar.
+
+Examples are available with the source code--read the comments to see how to run.
+
+=== Tkar window
+
+Press the "h" key for on-line help using the tkar window.
+
+=== Protocol
+
+See {protocol}[link:files/protocol_rdoc.html] for details on the protocol and writing shape files.
+
+=== Integrating tkar with other applications
+
+There are three transport options:
+
+1. Over pipe
+
+    cat data | tkar
+
+   or
+
+    program | tkar
+
+   - unidirectional (no mouseclick feedback to program)
+   
+   - output messages simply go to stdout
+   
+   - easy to write filters this way
+
+   <tt></tt>
+
+2. Over TCP socket
+
+    tkar [<ipaddr>] <port>
+
+   - bidirectional; client can block waiting for update to finish
+   
+   - remote host possible, using ipaddr=="localhost"
+   
+   - if port is 0, lets OS choose port and prints it to stderr
+   
+   - can still write filters by using netcat
+   
+   <tt></tt>
+
+3. Over unix domain socket
+
+    tkar /path/to/socket
+
+   - bidirectional; client can block waiting for update to finish
+   
+   - faster than TCP (but unix/linux only)
+
+Note that tkar has a -c option which tells it to be the socket client rather than the server. This is useful when your main program needs to choose the port, for example.
+
+== Tkar and Simulink
+
+Tkar can be interfaced with Simulink. Tkar appears in a simulink model as a block to which can be wired to any number of data sources that drive objects in the animation. You can have several tkar blocks. Think of tkar as the animation version of the built-in plotting block. (Simulink's built-in animation capabilities are bad.)
+
+An additional set of C files need to be compiled as a Simulink extension. Contact author for details.
+
+== Author
+
+Copyright 2006-2009, Joel VanderWerf, mailto:vjoel@users.sourceforge.org
+
+== License
+
+Ruby license, see http://www.ruby-lang.org.

data/TODO

@@ -0,0 +1,67 @@
+switch for protocol N, if protocol changes
+
+make most add arguments optional
+
+height/width broken after user resizes
+
+set select/hover colors
+
+set radian/degrees, flip y
+
+examples for web site
+  screen shots
+
+new options:
+
+  --flip-shape --radian-shape
+  
+  --flip-gobal --radian-global [ replaces --flip and --radians ]
+
+  --flip --radians [ implies both of above, resp. ]
+  
+  OR: do these as commands rather than options !!!
+
+new kind of object: connector
+
+  connects and moves with n normal objects
+
+  defined in terms of a shape which has 3*n params: x,y,r of each part
+  
+    also xdelta and ydelta, in each part's local coord sys?
+  
+  instantiated by passing ids of n objects, plus any add'l params
+  
+  when objects move, connector's params are changed accordingly, reshaping it
+  
+  (even when objects dragged in gui)
+  
+  when connector is dragged, objects are dragged with it (?)
+  
+  a connector with n==1 is a useful special case (control point, port, etc.)
+  
+
+
+constrained drag motion, drop targets (per individual object)
+
+  constrain by ID(s) of object(s) that drag must stay within
+
+object flags
+
+  draggable, hoverable, etc
+
+import shapes from .svg, so you can draw them in Dia, etc.
+
+documentation
+
+  shape vs global coords
+  
+  how to write line labels in simulink
+  
+  tutorial
+  
+    - simplest possible animation
+    
+    - more complex shapes
+    
+    - more complex motion
+    

data/bin/tkar

@@ -0,0 +1,104 @@
+#!/usr/bin/env ruby
+
+local_lib_dir = File.join(File.dirname(File.dirname(__FILE__)), "lib")
+
+if ARGV.delete("--local-lib")
+  $LOAD_PATH.unshift local_lib_dir
+end
+
+require 'tkar/argos'
+
+optdef = {
+  "b"         => true,
+  "c"         => true,
+  "h"         => true,
+  "help"      => true,
+  "v"         => true,
+  "persist"   => true,
+  "radians"   => true,
+  "flip"      => true,
+  "stderr"    => proc {|arg| arg},
+  "version"   => true
+}
+
+opts = Argos.parse_options(ARGV, optdef)
+
+stderr_file = opts["stderr"]
+if stderr_file
+  begin
+    $stderr = File.open(stderr_file, "w")
+  rescue
+    $stderr.puts "Warning: could not open #{stderr_file} for writing."
+  end
+end
+
+$0 = "tkar"
+
+if opts["h"] or opts["help"]
+  puts <<-END
+  
+  #{$0} [options] [addr] [port]
+    
+    Start a tkar animation process. Its inputs and outputs are one of:
+    
+      stdin/stdout: this is the default
+      
+      TCP socket:   if port is given (addr default is 127.0.0.1)
+      
+      UNIX socket:  if addr only is given
+    
+    Options:
+    
+      -b            turns on binary protocol mode, otherwise uses ascii
+      
+      -c            act as client instead of server [socket cases only];
+                    attempts to connect to specified address
+    
+      -h            this help
+      --help
+      
+      -v            be verbose
+      
+      --version     print version information and exit
+      
+      --local-lib   look for tkar lib files at path relative to this
+                    program (currently, #{local_lib_dir})
+      
+      --persist     keep window open after finishing (even in
+                    case of errors)
+      
+      --radians     accept rotation input in radians instead of degrees;
+                    doesn't affect coords inside shapes
+      
+      --flip        flips the global y axis, affecting both input
+                    and output; doesn't affect coords inside shapes
+
+  END
+  exit
+end
+
+if opts["version"]
+  require 'tkar/version'
+  puts Tkar::Version
+  exit
+end
+
+require 'tkar'
+
+# so io errors kill the whole process instead of just one thread.
+Thread.abort_on_exception = true
+
+if defined?(REQUIRE2LIB) # for rubyscript2exe
+  require 'tk/root'
+  require 'tk/frame'
+  require 'tk/bindtag'
+  require 'tk/pack'
+  require 'tk/grid'
+  require 'tk/scrollbar'
+  require 'tk/virtevent'
+  require 'tk/timer'
+  require 'tk/variable'
+  exit
+end
+
+Tkar.run(ARGV, opts)