imitator_x 0.0.1

data/README.rdoc

@@ -0,0 +1,70 @@
+=Imitator for X
+The Imitator for X library brings input automation to Linux by a C extension written for Ruby. 
+You can fake keyboard and mouse input, just as if an user sits in front of a computer and presses and 
+releases keys or moves the mouse. Additionally, you get control of the CD/DVD devices and the windows displayed 
+on the screen, properly wrapped as Ruby objects. As an useful extra, clipboard access is provided. 
+==Installation
+Just as always. 
+  # gem install imitator_x
+You need to have the X11 libraries (should be available on every system using X11) and the development 
+headers of the XTEST extension or compiling will fail. On Ubuntu, you do a 
+  sudo apt-get install libxtst-dev
+or use +aptitude+ or Synaptic or whatever package manager you like. It shouldn't be hard to obtain the package for other systems. 
+==Usage
+  require "imitator/x"
+  
+  #Move the mouse somewhere
+  Imitator::X::Mouse.move(100, 100)
+  #Send some keystrokes
+  Imitator::X::Keyboard.simulate("This is testtext!")
+  #Or kill an opened window
+  xwin = Imitator::X::XWindow.from_title(/gedit/)
+  xwin.kill
+==Note for non-gem use and debugging
+If you don't want to use Imitator for X as a gem, for example for debugging purposes, you will have to set the 
+gobal variable $imitator_x_charfile_path to the path of your "imitator_x_special_chars.yml" 
+file (which contains the key combinations for creating characters like @)  _before_ you require "imitator/x", 
+because otherwise Imitator for X isn't able to find that file (or if you have a non-gem version *and* 
+the gem installed you'll get the gem's file). 
+==Author
+  Marvin G�lker
+  You can contact me at sutniuq<>gmx<>net. 
+  
+  Initia in potestate nostra sunt, de eventu fortuna iudicat. 
+==License & Copyright
+Copyright � 2010 Marvin G�lker
+
+Imitator for X is free software: you can redistribute it and/or modify
+it under the terms of the GNU Lesser General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+Imitator for X is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public License
+along with Imitator for X.  If not, see <http://www.gnu.org/licenses/>.
+
+==Disclaimer of Warranty
+THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+==Limitation of Liability
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+

data/Rakefile.rb

@@ -0,0 +1,99 @@
+#!/usr/bin/env ruby
+#Encoding: UTF-8
+=begin
+--
+Imitator for X is a library allowing you to fake input to systems using X11. 
+Copyright © 2010 Marvin Gülker
+
+This file is part of Imitator for X.
+
+Imitator for X is free software: you can redistribute it and/or modify
+it under the terms of the GNU Lesser General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+Imitator for X is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public License
+along with Imitator for X.  If not, see <http://www.gnu.org/licenses/>.
+++
+=end
+
+require "rake/gempackagetask"
+require "rake/clean"
+require "rake/testtask"
+begin
+  require "hanna/rdoctask"
+rescue LoadError
+  require "rake/rdoctask"
+end
+
+$stdout.sync = true
+
+CLEAN.include("ext/*.o")
+CLEAN.include("ext/Makefile")
+CLEAN.include("ext/mkmf.log")
+CLOBBER.include("ext/*.so")
+
+Rake::RDocTask.new do |rt|
+  rt.options = ["--charset=ISO-8859-1"] #Needed for correct displaying of chars like ä. 
+  rt.rdoc_files.include("README.rdoc", "TODO.rdoc", "COPYING.rdoc", "COPYING.LESSER.rdoc")
+  rt.rdoc_files.include("ext/x.c")
+  rt.rdoc_files.include("ext/xwindow.c")
+  rt.rdoc_files.include("ext/mouse.c")
+  rt.rdoc_files.include("ext/clipboard.c")
+  rt.rdoc_files.include("ext/keyboard.c")
+  rt.rdoc_files.include("lib/imitator/x.rb")
+  rt.rdoc_files.include("lib/imitator/x/drive.rb")
+  rt.title = "Imitator for X: RDocs"
+  rt.main = "README.rdoc"
+  rt.rdoc_dir = "doc"
+end
+
+spec = Gem::Specification.new do |s|
+  s.name = "imitator_x"
+  s.summary = "Simulate keyboard and mouse input directly via Ruby to a Linux X server system"
+  s.description =<<DESC
+The Imitator for X library allows you to simulate key and 
+mouse input to any Linux system that uses the X server version 11. 
+Features also include CD/DVD drive control and direct interaction 
+with Windows, wrapped as Rubyish objects. 
+It's a Ruby 1.9-only library. Please also note that this is 
+a C extension that will be compiled during installing. 
+DESC
+  s.add_development_dependency("test-unit", ">= 2.0")
+  s.requirements = ["Linux with X11", "eject command (usually installed)"]
+  s.version = "0.0.1"
+  s.author = "Marvin Gülker"
+  s.email = "sutniuq<>gmx<>net"
+  s.platform = Gem::Platform::RUBY #BUT it's Linux-only
+  s.required_ruby_version = ">=1.9"
+  s.files = [Dir["lib/**/*.rb"], Dir["ext/**/**.c"], Dir["ext/**/*.h"], Dir["test/*.rb"], "ext/extconf.rb", "lib/imitator_x_special_chars.yml", "Rakefile.rb", "README.rdoc", "TODO.rdoc", "COPYING.rdoc", "COPYING.LESSER.rdoc"].flatten
+  s.extensions << "ext/extconf.rb"
+  s.has_rdoc = true
+  s.extra_rdoc_files = %w[README.rdoc TODO.rdoc COPYING.rdoc COPYING.LESSER.rdoc ext/x.c ext/xwindow.c ext/mouse.c ext/clipboard.c ext/keyboard.c] #Why doesn't RDoc document the C files automatically?
+  s.rdoc_options << "-t" << "Imitator for X: RDocs" << "-m" << "README.rdoc" << "-c" << "ISO-8859-1"
+  s.test_files = Dir["test/test_*.rb"]
+  #s.rubyforge_project = 
+  s.homepage = "http://github.com/Quintus/imitator"
+end
+Rake::GemPackageTask.new(spec).define
+
+Rake::TestTask.new("test") do |t|
+  t.pattern = "test/test_*.rb"
+  t.warning = true
+end
+
+desc "Compile Imitator for X"
+task :compile do 
+  Dir.chdir("ext") do
+    ruby "extconf.rb"
+    sh "make"
+  end
+end
+
+desc "Compiles, tests and then creates the gem file."
+task :default => [:clobber, :compile, :test, :gem]

data/TODO.rdoc

@@ -0,0 +1,8 @@
+=TODO list
+This is the list of things planned but not done yet. 
+
+* Make XWindow#children return XWindow objects [Segfault problems]
+* Make XWindow.search searching recursive all children layers
+* Make Mouse.wheel accept the same parameters as Mouse.move
+* Implement for Clipboard.write the TIMESTAMP request
+* Take care of swapped mouse buttons for left-handed people

data/ext/clipboard.c

@@ -0,0 +1,429 @@
+/*********************************************************************************
+Imitator for X is a library allowing you to fake input to systems using X11. 
+Copyright � 2010 Marvin G�lker
+
+This file is part of Imitator for X.
+
+Imitator for X is free software: you can redistribute it and/or modify
+it under the terms of the GNU Lesser General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+Imitator for X is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public License
+along with Imitator for X.  If not, see <http://www.gnu.org/licenses/>.
+*********************************************************************************/
+#include "x.h"
+#include "clipboard.h"
+
+/*
+*It was an awful lot of work to get into the X clipboard stuff. 
+*I don't think I'll ever forget this, but just in case, here are the 
+*important things: 
+** What the X standard calls a "selection" is a clipboard. 
+** An atom is for X what a symbol is for Ruby. Just an internal storage thing convertable to strings. 
+** X maintains 3 clipboards: 
+***PRIMARY (Atom: XA_PRIMARY): The middle-mouse-button-clipboard. Mildly deprecated. 
+***SECONDARY (Atom: XA_SECONDARY): This clipboard isn't used by anyone. It's just there and stands around. 
+*** CLIPBOARD (Atom: XInternAtom(p_display, "CLIPBOARD", True): The main clipboard. It acts as the Mac or Windows clipboard via [CTRL]+[C] and the like. 
+**XConvertSelection() is sparely described in the X standard. For whatever reason, after 10 times reading it's documentation I 
+*  did not understand what's actually _converted_ here. After I looked into xsel's and xclip's sources many times I finally got it: 
+*  this damned function converts the clipboard data from X's internal storage to the specified encoding. The word "encoding" wasn't ever 
+*  mentioned in the function's description, just "target atom". Why? It's a riddle, solve it if you like...
+** XA_STRING is the atom for the ISO-8859-1 encoding. 
+*  The atom for UTF-8 is: XInternAtom(p_display, "UTF8_STRING", True). 
+*  The atom for binary and ASCII stuff is XA_TEXT. 
+**XConvertSelection() fails for the CLIPBOARD selection if None is specified as the "property" parameter; just another thing not documented. 
+*  It's absolutly... We Germans say "wurschtegal", I don't know how to translate this - it's unimportant in any way - what you pass in. Just use an atom you like, as e.g. XInternAtom(p_display, "DAMNED_FUNCTION", False). 
+** If a X function wants a delay, you shouldn't pass in 0 if you want to make it executed immediately. Pass in CurrentTime instead. 
+**Since X doesn't maintain a central clipboard application (but thank God, approaches are made for a shared library in order to simplify the interaction with the selections!) you must 
+*  create a requestor window whose "xselection" property will get set. That works even if the window isn't mapped. 
+** Data in the PRIMARY clipboard is set in that very moment you select text. You don't have to press any button or click any menu - it's just made. If you deselect the text, 
+*  the PRIMARY clipboard's content goes away. 
+** The requestor window will get a SelectionNotify event after a call to XConvertSelection(), regardless of that function's success. If XConvertSelection() failed, the SelectionNotify's 
+*  "property" member will be None. 
+*/
+
+/*Document-module: Imitator::X::Clipboard
+*Yeah, finally, this is the Clipboard module. During development I thought more than once I should stop 
+*this, because to deal with X's selection functions is awkward. And still, the Clipboard.write method doesn't work 
+*well, so don't rely on it (although Clipboard.read should do a good job). 
+*Also, the methods defined here can't be used to set or access non-textual data. 
+*
+*So, here's what you need to know about X and the clipboard: 
+*
+** <b>X doesn't have clipboards. </b>
+*  Yes, that's true! X does not use the term "clipboard", they're always called "selections". 
+*
+** <b>X has 3 selections. </b>
+*  Every X server maintains three selections: The PRIMARY, the SECONDARY and the CLIPBOARD selection. 
+*
+** The <b>PRIMARY</b> selection is set when you select some text - really, you don't need anything else. Just 
+*  open a terminal window, select some text and then press the middle mouse button (or your mouse wheel) 
+*  and the selected text gets pasted. Of course this data can't survive the application that sets it. 
+*
+** The <b>SECONDARY</b> selection... well, it's used by nobody. Just ignore it. 
+*
+** The <b>CLIPBOARD</b> selection is to an extend of ~95% the one you're looking for. When you press [CTRL]+[C] 
+*  or select text and then choose "copy" from a pull-down menu, your data is stored here. Depending on your 
+*  system, the data stored here remains accessible even after the application that set it terminated. To achieve this, 
+*  a program called a "clipboard manager" that is running in the background silently copies data applications store 
+*  in the CLIPBOARD selection into it's own buffer and then acquires ownership of CLIPBOARD. 
+*
+*In conclusion, just remember that you should probably try the PRIMARY selection if CLIPBOARD doesn't contain your data. 
+*
+*This module operates on UTF-8-encoded strings; that means, you should pass UTF-8-encoded strings to Clipboard.write and 
+*you get back UTF-8-encoded strings from Clipboard.read. 
+*/
+
+/*
+*call-seq: 
+*  Clipboard.read(selection = :clipboard) ==> aString
+*
+*Reads the value of the specified +clipboard+. 
+*===Parameters
+*[+selection+] The selection to read from. One of <tt>:clipboard</tt>, <tt>:primary</tt> and <tt>:secondary</tt>. 
+*===Return value
+*A string containing the selection's content or an empty string if there is no data in the selection. 
+*===Raises
+*[ArgumentError] Incorrect +selection+ argument given. 
+*[XError] Could not retrieve the selection data for some reason. It's likely that there's data in the selection, but it isn't textual data; such as an image, for example. 
+*===Example
+*  puts Imitator::X::Clipboard.read(:clipboard) #=> I love Ruby!
+*/
+static VALUE m_read(int argc, VALUE argv[], VALUE self)
+{
+  Display * p_display;
+  Atom clipboard, actual_type;
+  Window win;
+  XEvent xevt;
+  int actual_format;
+  unsigned long nitems, bytes_after_return;
+  unsigned char * property;
+  char * cp;
+  VALUE rclipboard, result;
+  
+  rb_scan_args(argc, argv, "01", &rclipboard);
+  
+  if (NIL_P(rclipboard))
+    rclipboard = ID2SYM(rb_intern("clipboard"));
+  
+  p_display = XOpenDisplay(NULL);
+  XSetErrorHandler(handle_x_errors);
+  
+  rclipboard = rb_funcall(rclipboard, rb_intern("to_s"), 0); /*Symbol -> String*/
+  rclipboard = rb_funcall(rclipboard, rb_intern("upcase"), 0); /*String -> STRING*/
+  clipboard = XInternAtom(p_display, StringValuePtr(rclipboard), True); /*STRING -> Atom(STRING)*/
+  if (clipboard == None)
+    rb_raise(rb_eArgError, "Invalid clipboard specified!");
+  
+  /*Check wheather there is a clipboard owner, and if not, just return an empty string. */
+  if (XGetSelectionOwner(p_display, clipboard) == None)
+    return rb_str_new2("");
+  
+  /*Create a window for selection interaction*/
+  win = CREATE_REQUESTOR_WIN;
+  
+  /*Order the selection content from the current selection owner*/
+  XConvertSelection(p_display, clipboard, UTF8_ATOM, IMITATOR_X_CLIP_ATOM, win, CurrentTime);
+  /*Wait until our requestor window gets the message that it has received the selection content*/
+  for (;;)
+  {
+    XNextEvent(p_display, &xevt);
+    if (xevt.type == SelectionNotify)
+      break;
+  }
+  if (xevt.xselection.property == None)
+      rb_raise(XError, "Could not retrieve selection (XConvertSelection() failed)! Is there non-text data in the clipboard?");
+  
+  /*Read the selection property of our requestor window, just in order to get the selection content's size. We don't read the actual data here. */
+  XGetWindowProperty(xevt.xselection.display, xevt.xselection.requestor, xevt.xselection.property, 0, 0, False, AnyPropertyType, &actual_type, &actual_format, &nitems, &bytes_after_return, &property);
+  cp = (char *) malloc(bytes_after_return); /*Nice - we already get the number of bytes to allocate from X*/
+  /*This is the exciting moment. Reads the data from our requestor window. */
+  XGetWindowProperty(xevt.xselection.display, xevt.xselection.requestor, xevt.xselection.property, 0, bytes_after_return, False, AnyPropertyType, &actual_type, &actual_format, &nitems, &bytes_after_return, &property);
+  /*Now copy it away from X, since X wants to XFree() it's data*/
+  strcpy(cp, (char *) property);
+  /*Convert it to a Ruby UTF-8 string*/
+  result = rb_enc_str_new(cp, strlen(cp), rb_utf8_encoding());
+  
+  /*Clean-up actions*/
+  XFree(property);
+  free(cp);
+  XDestroyWindow(p_display, win); /*We don't need the window anymore, a new request will create a new window*/
+  XSetErrorHandler(NULL);
+  XCloseDisplay(p_display);
+  
+  return result;
+}
+
+/*
+*call-seq: 
+*  Clipboard.write( text ) ==> text
+*
+*Writes +text+ to the CLIPBOARD selection. 
+*===Parameters
+*[+text+] The text to store. 
+*===Return value
+*The +text+ argument. 
+*===Raises
+*[XError] No clipboard manager available, or it doesn't signal it's existance via CLIPBOARD_MANAGER. Also indicates failure in acquiring ownership of the CLIPBOARD selection or failure in setting the clipboard manager as it's owner. 
+*===Example
+*  Imitator::X::Clipboard.write("I love Ruby")
+*  puts Imitator::X::Clipboard.read #=> I love Ruby
+*===Remarks
+*This method doesn't work well in all cases. It works on my Ubuntu Karmic machine, but didn't work 
+*with Xubuntu and openSUSE when I tested it in VirtualBox. Therefore, don't rely on this method. 
+*/
+static VALUE m_write(VALUE self, VALUE rtext)
+{
+  Display * p_display;
+  Window win, clipboard_owner;
+  XEvent xevt, xevt2;
+  Atom targets[6], target_sizes[12], save_targets[2];
+  VALUE rtext_utf8, rtext_iso_latin1;
+  int utf8_len, iso_latin1_len;
+  
+  /*Get neccessary information*/
+  rtext_utf8 = rb_str_export_to_enc(rtext, rb_utf8_encoding());
+  rtext_iso_latin1 = rb_str_export_to_enc(rtext, rb_enc_find("ISO-8859-1"));
+  /*rtext_utf8.bytes.to_a.length - otherwise we lose data due to multibyte characters*/
+  utf8_len = NUM2INT(rb_funcall(rb_funcall(rb_funcall(rtext_utf8, rb_intern("bytes"), 0), rb_intern("to_a"), 0), rb_intern("length"), 0));
+  iso_latin1_len = NUM2INT(rb_funcall(rtext_iso_latin1, rb_intern("length"), 0));
+  
+  /*Open default display*/
+  p_display = XOpenDisplay(NULL);
+  /*Let Ruby handle protocol errors*/
+  XSetErrorHandler(handle_x_errors);
+  /*This are the TARGETS we support*/
+  targets[0] = TARGETS_ATOM;
+  targets[1] = UTF8_ATOM;
+  targets[2] = XA_STRING;
+  targets[3] = XInternAtom(p_display, "TIMESTAMP", True); /*TODO: Implement this request*/
+  targets[4] = SAVE_TARGETS_ATOM;
+  targets[5] = TARGET_SIZES_ATOM;
+  /*These are the target's sizes*/
+  target_sizes[0] = TARGETS_ATOM;
+  target_sizes[1] = 6 * sizeof(Atom);
+  
+  target_sizes[2] = UTF8_ATOM;
+  target_sizes[3] = utf8_len;
+  
+  target_sizes[4] = XA_STRING;
+  target_sizes[5] = iso_latin1_len;
+  
+  target_sizes[6] = XInternAtom(p_display, "TIMESTAMP", True);
+  target_sizes[7] = -1;
+  
+  target_sizes[8] = SAVE_TARGETS_ATOM;
+  target_sizes[9] = -1;
+  
+  target_sizes[10] = TARGET_SIZES_ATOM;
+  target_sizes[11] = 12 * sizeof(Atom);
+  /*We want our data have stored as UTF-8*/
+  save_targets[0] = UTF8_ATOM;
+  save_targets[1] = XA_STRING;
+  if (CLIPBOARD_MANAGER_ATOM == None)
+  {
+    XSetErrorHandler(NULL);
+    XCloseDisplay(p_display);
+    rb_raise(XError, "No clipboard manager available!");
+  }
+  
+  /*Create a window for copying into CLIPBOARD*/
+  win = CREATE_REQUESTOR_WIN;
+  
+  /*Make sure that there's a clipboard manager which can process our request*/
+  if ( (clipboard_owner = XGetSelectionOwner(p_display, CLIPBOARD_MANAGER_ATOM)) == None)
+  {
+    XDestroyWindow(p_display, win);
+    XSetErrorHandler(NULL);
+    XCloseDisplay(p_display);
+    rb_raise(XError, "No owner for the CLIPBOARD_MANAGER selection!");
+  }
+  
+  /*Get control of the CLIPBOARD*/
+  XSetSelectionOwner(p_display, CLIPBOARD_ATOM, win, CurrentTime);
+  if (XGetSelectionOwner(p_display, CLIPBOARD_ATOM) != win)
+  {
+    XDestroyWindow(p_display, win);
+    XSetErrorHandler(NULL);
+    XCloseDisplay(p_display);
+    rb_raise(XError, "Could not acquire ownership of the CLIPBOARD selection!");
+  }
+  
+  /*Our application "needs to exit"*/
+  XChangeProperty(p_display, win, IMITATOR_X_CLIP_ATOM, XA_ATOM, 32, PropModeReplace, (unsigned char *) save_targets, 1);
+  XConvertSelection(p_display, CLIPBOARD_MANAGER_ATOM, SAVE_TARGETS_ATOM, IMITATOR_X_CLIP_ATOM, win, CurrentTime);
+  for (;;)
+  {
+    XNextEvent(p_display, &xevt);
+    if (xevt.type == SelectionRequest) /*selection-related event*/
+    {
+      /*This is for all anserwing events the same (except "not supported")*/
+      xevt2.xselection.type = SelectionNotify;
+      xevt2.xselection.display = xevt.xselectionrequest.display;
+      xevt2.xselection.requestor = xevt.xselectionrequest.requestor;
+      xevt2.xselection.selection = xevt.xselectionrequest.selection;
+      xevt2.xselection.target = xevt.xselectionrequest.target;
+      xevt2.xselection.time = xevt.xselectionrequest.time;
+      xevt2.xselection.property = xevt.xselectionrequest.property;
+      
+      /*Handle individual selection requests*/
+      if (xevt.xselectionrequest.target == XInternAtom(p_display, "TARGETS", True)) /*TARGETS information requested*/
+      {
+        /*Write supported TARGETS into the requestor*/
+        XChangeProperty(p_display, xevt.xselectionrequest.requestor, xevt.xselectionrequest.property, XA_ATOM, 32, PropModeReplace, (unsigned char *) targets, 6);
+        /*Notify the requestor we have set its requested property*/
+        XSendEvent(p_display, xevt.xselectionrequest.requestor, False, NoEventMask, &xevt2);
+      }
+      else if (xevt.xselectionrequest.target == TARGET_SIZES_ATOM)
+      {
+        /*Answer how much data we want to store*/
+        XChangeProperty(p_display, xevt.xselectionrequest.requestor, xevt.xselectionrequest.property, ATOM_PAIR_ATOM, 32, PropModeReplace, (unsigned char *) target_sizes, 6);
+        /*Notify the requestor we have set its requested property*/
+        XSendEvent(p_display, xevt.xselectionrequest.requestor, False, NoEventMask, &xevt2);
+      }
+      else if (xevt.xselectionrequest.target == MULTIPLE_ATOM) /*Makes multiple requests at once*/
+      { /*I know, allocating variables in inner blocks is bad style, but I didn't want to 
+        *declare this amount of variables at the function's top, beacuse that would decrease readability*/
+        Atom actual_type, requested = None;
+        int actual_format, i;
+        unsigned long nitems, bytes;
+        unsigned char * prop;
+        Atom * wanted_atoms;
+        /*See how much data is there and allocate this amount*/
+        XGetWindowProperty(p_display, xevt.xselectionrequest.requestor, xevt.xselectionrequest.property, 0, 0, False, AnyPropertyType, &actual_type, &actual_format, &nitems, &bytes, &prop);
+        wanted_atoms = (Atom *) malloc(sizeof(Atom) * nitems);
+        /*Now get the data and copy it to our variable*/
+        XGetWindowProperty(p_display, xevt.xselectionrequest.requestor, xevt.xselectionrequest.property, 0, 1000000, False, AnyPropertyType, &actual_type, &actual_format, &nitems, &bytes, &prop);
+        memcpy(wanted_atoms, prop, sizeof(Atom) * nitems);
+        /*Now handle each single request by it's own*/
+        for(i = 0;i < nitems; i++)
+        {
+          if (requested == None) /*This means we'll get a target atom*/
+            requested = wanted_atoms[i];
+          else /*This means we'll get a property atom*/
+          {
+            /*OK, I see. I could have made the event handling a separate function and then call it recursively here, 
+            *but since I only support two targets that's unneccessary I think*/
+            if (requested == UTF8_ATOM)
+              XChangeProperty(p_display, xevt.xselectionrequest.requestor, wanted_atoms[i], requested, 8, PropModeReplace, (unsigned char *) StringValuePtr(rtext_utf8), utf8_len);
+            else if (requested == XA_STRING)
+              XChangeProperty(p_display, xevt.xselectionrequest.requestor, wanted_atoms[i], requested, 8, PropModeReplace, (unsigned char *) StringValuePtr(rtext_iso_latin1), iso_latin1_len);
+            else /*Not supported request*/
+              XChangeProperty(p_display, xevt.xselectionrequest.requestor, wanted_atoms[i], requested, 32, PropModeReplace, (unsigned char *) None, 1);
+            requested = None; /*The next iteration will be a target atom again*/
+          }
+        }
+        /*Notify the requestor we have finished*/
+        XSendEvent(p_display, xevt.xselectionrequest.requestor, False, NoEventMask, &xevt2);
+        /*Free the allocated memory*/
+        free(wanted_atoms);
+        XFree(prop);
+      }
+      //~ else if (xevt.xselectionrequest.target == UTF8_ATOM || xevt.xselectionrequest.target == XA_STRING) /*UTF-8 or ASCII requested*/
+      else if (xevt.xselectionrequest.target == UTF8_ATOM)
+      {
+        /*Write the string into the requestor*/
+        XChangeProperty(p_display, xevt.xselectionrequest.requestor, xevt.xselectionrequest.property, xevt.xselectionrequest.target, 8, PropModeReplace, (unsigned char *) StringValuePtr(rtext_utf8), utf8_len);
+        /*Notify the requestor we've finished*/
+        XSendEvent(p_display, xevt.xselectionrequest.requestor, False, NoEventMask, &xevt2);
+      }
+      else if (xevt.xselectionrequest.target == XA_STRING)
+      {
+        XChangeProperty(p_display, xevt.xselectionrequest.requestor, xevt.xselectionrequest.property, xevt.xselectionrequest.target, 8, PropModeReplace, (unsigned char *) StringValuePtr(rtext_iso_latin1), iso_latin1_len);
+        XSendEvent(p_display, xevt.xselectionrequest.requestor, False, NoEventMask, &xevt2);
+      }
+      else /*No supported request. SAVE_TARGETS is included here, since it's only a marker*/
+      {
+        /*Notify the requestor we don't support what it wants*/
+        xevt2.xselection.target = None; /*This indicates we don't support what it wants*/
+        XSendEvent(p_display, xevt.xselectionrequest.requestor, False, NoEventMask, &xevt2);
+      }
+    }
+    else if (xevt.type == SelectionNotify) /*OK, our request to the clipboard manager has completed*/
+    {
+      if (xevt.xselection.property == None) /*Ooops - conversion failed, we're still the owner of CLIPBOARD*/
+      {
+        XDestroyWindow(p_display, win);
+        XSetErrorHandler(NULL);
+        XCloseDisplay(p_display);
+        rb_raise(XError, "Unable to request the clipboard manager to acquire the CLIPBOARD selection!");
+      }
+      else if (xevt.xselection.property == IMITATOR_X_CLIP_ATOM) /*Success - we're out of responsibility now and can safely exit*/
+        break;
+    }
+  }
+  
+  /*Cleanup actions*/
+  XDestroyWindow(p_display, win);
+  XSetErrorHandler(NULL);
+  XCloseDisplay(p_display);
+  
+  return rtext;
+}
+
+/*
+*call-seq: 
+*  Clipboard.clear( *selections = :clipboard ) ==> nil
+*
+*Clears the specified selection(s). 
+*===Parameters
+*[<tt>*selections</tt>] (<tt>:clipboard</tt>) Specifies one or more of <tt>:primary</tt>, <tt>:secondary</tt> and/or <tt>:clipboard</tt>. 
+*===Return value
+*nil. 
+*===Raises
+*[XError] Invalid selection specified. 
+*===Example
+*  #Clear the CLIPBOARD's contents
+*  Imitator::X::Clipboard.clear
+*  #Clear PRIMARY
+*  Imitator::X::Clipboard.clear(:primary)
+*  #Clear PRIMARY and CLIPBOARD
+*  Imitator::X::Clipboard.clear(:primary, :clipboard)
+*/
+VALUE m_clear(VALUE self, VALUE args)
+{
+  VALUE rtemp;
+  Display * p_display;
+  int length, i;
+  Atom selection;
+  
+  if (RTEST(rb_funcall(args, rb_intern("empty?"), 0)))
+    rb_ary_push(args, ID2SYM(rb_intern("clipboard")));
+  
+  p_display = XOpenDisplay(NULL);
+  XSetErrorHandler(handle_x_errors);
+  
+  length = NUM2INT(rb_funcall(args, rb_intern("length"), 0));
+  for(i = 0; i < length; i++)
+  {
+    rtemp = rb_funcall(rb_ary_entry(args, i), rb_intern("upcase"), 0);
+    selection = XInternAtom(p_display, StringValuePtr(rtemp), True);
+    if (selection == None)
+    {
+      XSetErrorHandler(NULL);
+      XCloseDisplay(p_display);
+      rb_raise(XError, "Invalid selection specified!");
+    }
+    XSetSelectionOwner(p_display, selection, None, CurrentTime);
+  }
+  
+  XSetErrorHandler(NULL);
+  XCloseDisplay(p_display);
+  return Qnil;
+}
+
+/********************Init function**********************/
+
+void Init_clipboard(void)
+{
+  Clipboard = rb_define_module_under(X, "Clipboard");
+  rb_define_module_function(Clipboard, "read", m_read, -1);
+  rb_define_module_function(Clipboard, "write", m_write, 1);
+  rb_define_module_function(Clipboard, "clear", m_clear, -2);
+}

data/ext/clipboard.h

@@ -0,0 +1,61 @@
+/*********************************************************************************
+Imitator for X is a library allowing you to fake input to systems using X11. 
+Copyright � 2010 Marvin G�lker
+
+This file is part of Imitator for X.
+
+Imitator for X is free software: you can redistribute it and/or modify
+it under the terms of the GNU Lesser General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+Imitator for X is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public License
+along with Imitator for X.  If not, see <http://www.gnu.org/licenses/>.
+*********************************************************************************/
+#ifndef IMITATOR_CLIPBOARD_HEADER
+#define IMITATOR_CLIPBOARD_HEADER
+
+/*All the macros defined here assume that you have an open X server connection stored 
+*in a variable p_display. */
+
+/*UTF-8 X-Encoding atom*/
+#define UTF8_ATOM XInternAtom(p_display, "UTF8_STRING", True)
+
+/*Atom for the CLIPBOARD selection*/
+#define CLIPBOARD_ATOM XInternAtom(p_display, "CLIPBOARD", True)
+
+/*CLIPBOARD_MANAGER atom*/
+#define CLIPBOARD_MANAGER_ATOM XInternAtom(p_display, "CLIPBOARD_MANAGER", True)
+
+/*ATOM_PAIR atom*/
+#define ATOM_PAIR_ATOM XInternAtom(p_display, "ATOM_PAIR", True)
+
+/*SAVE_TARGETS atom*/
+#define SAVE_TARGETS_ATOM XInternAtom(p_display, "SAVE_TARGETS", True)
+
+/*TARGET_SIZES atom*/
+#define TARGET_SIZES_ATOM XInternAtom(p_display, "TARGET_SIZES", True)
+
+/*TARGETS atom*/
+#define TARGETS_ATOM XInternAtom(p_display, "TARGETS", True)
+
+/*MULTIPLE request atom*/
+#define MULTIPLE_ATOM XInternAtom(p_display, "MULTIPLE", True)
+
+/*Atom for storing properties used by this library*/
+#define IMITATOR_X_CLIP_ATOM XInternAtom(p_display, "IMITATOR_X_CLIP", False)
+
+/*In order to work with the X selections, we need a window. 
+*This macro just creates a simple, unmapped window that is used for 
+*the X selection interaction*/
+#define CREATE_REQUESTOR_WIN XCreateSimpleWindow(p_display, XDefaultRootWindow(p_display), 0, 0, 1, 1, 0, 0, 0)
+
+VALUE Clipboard;
+void Init_clipboard(void);
+
+#endif