xdo 0.0.4

data/DEPRECATE.rdoc

@@ -0,0 +1,11 @@
+=Deprecations
+The following method uses are _deprecated_ and will be removed in the next minor version bump. They show a warning if you use them unless otherwise stated. 
+
+* XWindow.desktop_name= is obsolete now and has noo effect anymore. 
+* XWindow.desktop_name is obsolete now. It always returns "x-nautilus-desktop". 
+* XWindow.focus_desktop has been deprecated. Use XWindow.unfocus instead. 
+* All Clipboard module methods take a hash in order to specify which clipboards to interact with now take the symbols directly via a rest argument. 
+* All Mouse module methods that took constant values now accept symbols. The old behaviour is deprecated now. 
+* All XWindow class methods that take a hash in order to specify which windows to search now take the symbols directly via a rest argument. 
+* All XWindow class methods that take a string as the window to search for are now accepting Regular Expressions. That means, in later version you have to pass in a regexp if you don't want to look for an entire title at once, i.e. <tt>"edit"</tt> won't find a "gedit" window, but <tt>/edit/</tt> will. <b>This doesn't show a warning. </b>
+* XWindow.from_name has been deprecated. The old functionality (i.e. the ability to specify all search parameters) is now provided by the XWindow.from_search method. XWindow.from_name will be used as an alias for XWindow.from_title in the next version. 

data/HISTORY.rdoc

@@ -0,0 +1,33 @@
+=History of the xdo gem
+This file shows the history of the xdo gem 
+from it's very beginning. Important changes in the 
+API are marked <b>bold</b>. Bugfixes are <i>italic</i>. 
+
+==0.0.4
+* <b>Several methods now accept a +sync+ parameter wrapping +xdotool+'s <tt>--sync</tt> option. </b>
+* <b>Added XWindow.unfocus</b>
+* <b>Added XWindow.root_id</b>
+* <b>Added XWindow.from_root</b>
+* <b>Added XWindow.from_null</b>
+* Removed the internal SmallScanner class. We're now using StringScanner directly. 
+* All methods in the Mouse module now accept symbols for the +button+ parameter. 
+* <i>XWindow#exists? aways returned false. This has been fixed.</i>
+* <i>XWindow#visible? always returned false. This has been fixed.</i>
+* <b>Added XWindow#to_i and XWindow#to_s.</b>
+* <b>Added XWindow#zero? and XWindow#nonzero?.</b>
+* All methods in the Keyboard module that accept a +w_id+ parameter now can take XWindow objects. 
+* Removed Keyboard.sequence_escape. 
+* Several deprecations. See DEPRECATE.rdoc. 
+* <b>Added XWindow.from_title.</b>
+
+==0.0.3
+* <i>Some XWindow instance methods (like #close!) showed wrong error messages due to the redundance of Kernel#raise with XWindow#raise. This has been fixed. </i>
+* If run alone, the "test_xwindow.rb" test file failed with obscure errors. Fixed. 
+
+==0.0.2
+* Replaced fork{system("gedit")} in full_demo.rb with spawn("gedit")
+* Removed "require 'pp'" from keyboard.rb
+* <b>Added the Simulatable mixin</b>
+* <b>Corrected window id usage for the XDo::Keyboard module</b>
+* Added a test for the window id usage
+* Made the test-unit gem a development dependency

data/README.rdoc

@@ -0,0 +1,53 @@
+--
+This file is part of Xdo. 
+Copyright © 2009, 2010 Marvin Gülker
+  Initia in potestate nostra sunt, de eventu fortuna iudicat. 
+++
+=XDo
+XDo is a library to simulate keyboard and mouse input and manipulating windows on the X server. 
+It's wrapped around the command-line tools xdotool[http://www.semicomplete.com/projects/xdotool/], 
+xsel[http://linux.die.net/man/1/xsel], xwininfo[http://linux.die.net/man/1/xwininfo], eject[http://linux.die.net/man/1/eject] and xkill[http://linux.die.net/man/1/xkill], 
+so you will need to have them installed if you want to use Xdo (even if xwininfo, eject and xkill are usually already installed). 
+If not, try to install them via your favourite packaging manager. 
+After they're installed, install XDo via RubyGems: 
+  sudo gem install xdo
+==Usage
+  #Require some of XDo's files
+  require "xdo/keyboard"
+  require "xdo/mouse"
+  require "xdo/xwindow"
+  #Move the cursor
+  XDo::Mouse.move(100, 100)
+  #Simulate text (with special escape sequences!)
+  XDo::Keyboard.simulate("This is{TAB}text.")
+  #Some sequences can be shortened: 
+  XDo::Keyboard.simulate("This ist\ttext.")
+  #And this will move a window containing the string "gedit", 
+  #unless it's maximized. 
+  win = XDo::XWindow.from_title(/gedit/)
+  win.move(200, 200)
+==Files
+You can require the following files in your projects: 
+* xdo/clipboard: Clipboard access
+* xdo/drive: Get control of CD/DVD devices
+* xdo/keyboard: Pretty self-explaining
+* xdo/mouse: Automate the mouse
+* xdo/xwindow: Manipulate windows in various ways
+As an helpful extra, I created an executable ruby file "xinfo.rb". Thanks to RubyGems, 
+you can start this GUI tool right from the command line by typing: 
+  xinfo.rb
+It's by far not perfect, maybe not even good, but I think it can be useful sometimes 
+(you will need to have wxRuby installed, try <tt>sudo gem install wxruby-ruby19</tt>). 
+If you're looking for a more professional program, try the "X window information" tool. 
+==Notes
+* If your +xdotool+ seems to reject the --window option, you are not using the current version. Try building the newest one from the source. 
+* I recommand the "X window information" tool to get infos about your windows if you aren't satisfied by the xinfo.rb shipped with this package. 
+==Fairly incomplete
+* I'm sure there are several things I didn't notice that can be automated somehow. If you know about, email me! Please add a description of the possibilities and a sample script. 
+* Another interesting thing are the samples. There are many Linux distrubitions out there, and even many of them rely on X. I cannot test with another than a recent Ubuntu machine, but if you want to contribute and send samples for another OS, I want to encourage you to - I surely won't reject your work. :-)
+==License/Copyright
+  Copyright © 2009, 2010 Marvin Gülker
+  This library is free software; you may redistribute it and/or modify it 
+  under the terms of Ruby's license (see http://www.ruby-lang.org/en/LICENSE.txt). 
+  You can contact me at sutniuq ät gmx Dot net. 
+  Initia in potestate nostra sunt, de eventu fortuna iudicat. 

data/VERSION

@@ -0,0 +1 @@
+0.0.4

data/bin/xinfo.rb

@@ -0,0 +1,155 @@
+#!/usr/bin/env ruby
+#Encoding: UTF-8
+#This file is part of Xdo. 
+#Copyright © 2009, 2010 Marvin Gülker
+#  Initia in potestate nostra sunt, de eventu fortuna iudicat. 
+#
+#This program displays information about the currently selected window 
+#and the mouse. The displayed infos are updated every 1/2 second, 
+#but set XInfo::UPDATE_TIME to another value if you'd like to change that. 
+
+require "logger"
+require "wx"
+
+require_relative("../lib/xdo/xwindow")
+require_relative("../lib/xdo/mouse")
+
+#Class that retrieves the information of windows. 
+class InfoGetter
+  
+  attr_reader :act_win
+  attr_reader :cursorpos
+  
+  def initialize
+    @act_win = XDo::XWindow.from_active
+    @cursorpos = XDo::Mouse.position
+  end
+  
+  def update
+    @act_win = XDo::XWindow.from_active
+    @cursorpos = XDo::Mouse.position
+  end
+  
+end
+
+class XInfoFrame < Wx::Frame
+  include Wx
+  
+  #Time intervall of updating the infos, in milliseconds. 
+  #Default is 500, which is 1/2 second. 
+  UPDATE_TIME = 500
+  
+  def initialize(parent = nil)
+    super(parent, title: "XInfo", size: Size.new(300, 400), style: DEFAULT_FRAME_STYLE | STAY_ON_TOP)
+    self.background_colour = NULL_COLOUR
+    THE_APP.log.debug("Creating controls")
+    create_controls
+    THE_APP.log.debug("Setting up timer")
+    create_updater
+  end
+  
+  private
+  
+  def create_controls
+    StaticText.new(self, -1, "Title of active window: ", Point.new(20, 20))
+    @title = TextCtrl.new(self, pos: Point.new(20, 50), size: Size.new(260, 24), style: TE_READONLY)
+    StaticText.new(self, -1, "ID of active window: ", Point.new(20, 80))
+    @id = TextCtrl.new(self, -1, "", Point.new(20, 110), Size.new(260, 24), TE_READONLY)
+    StaticText.new(self, -1, "Absoloute and relative upper-left coords: ", Point.new(20,140))
+    StaticText.new(self, -1, "Abs: ", Point.new(20, 173))
+    @abs_xy = TextCtrl.new(self, -1, "", Point.new(60, 170), Size.new(70, 24), TE_READONLY)
+    StaticText.new(self, -1, "Rel: ", Point.new(150, 173))
+    @rel_xy = TextCtrl.new(self, -1, "", Point.new(190, 170), Size.new(70, 24), TE_READONLY)
+    StaticText.new(self, -1, "Size: ", Point.new(20, 200))
+    StaticText.new(self, -1, "Width: ", Point.new(20, 233))
+    @width = TextCtrl.new(self, -1, "", Point.new(65, 230), Size.new(70, 24), TE_READONLY)
+    StaticText.new(self, -1, "Height: ", Point.new(150, 233))
+    @height = TextCtrl.new(self, -1, "", Point.new(200, 230), Size.new(70, 24), TE_READONLY)
+    
+    StaticText.new(self, -1, "Mouse position: ", Point.new(20, 300))
+    StaticText.new(self, -1, "X: ", Point.new(20, 333))
+    @x = TextCtrl.new(self, -1, "", Point.new(60, 330), Size.new(70, 24), TE_READONLY)
+    StaticText.new(self, -1, "Y: ", Point.new(150, 333))
+    @y = TextCtrl.new(self, -1, "", Point.new(190, 330), Size.new(70, 24), TE_READONLY)
+  end
+  
+  def create_updater
+    @updater = InfoGetter.new
+    Timer.every(UPDATE_TIME) do
+      begin
+        @updater.update
+        @title.value = @updater.act_win.title
+        @id.value = @updater.act_win.id.inspect
+        @abs_xy.value = @updater.act_win.abs_position.join(", ")
+        @rel_xy.value = @updater.act_win.rel_position.join(", ")
+        ary = @updater.act_win.size
+        @width.value = ary[0].inspect
+        @height.value = ary[1].inspect        
+      end
+      
+      curpos = @updater.cursorpos
+      @x.value = curpos[0].inspect
+      @y.value = curpos[1].inspect
+    end
+  end
+  
+end
+
+#Main App object of this program. 
+class XInfo < Wx::App
+  include Wx
+  
+  #Logger. 
+  attr_reader :log  
+  
+  def on_init
+    @log = Logger.new($stdout)
+    @log.level = Logger::INFO unless $VERBOSE || $DEBUG
+    @log.info("Started")
+    @log.debug "Creating main window"
+    @mainwindow = XInfoFrame.new    
+    @mainwindow.show
+  end
+  
+  def on_run
+    super
+  rescue => e
+    @log.fatal(e.class.name)
+    @log.fatal(e.message)
+    e.backtrace.each{|trace| @log.fatal(trace)}
+    message = "A #{e.class} occured: #{e.message} \n\nBacktrace: \n\n#{e.backtrace.join("\n")}"    
+    message << "\n\nIf you want to contact me about the error, send an email to sutniuq ät gmx Dot net."    
+    msgbox = MessageDialog.new(@mainwindow, message, $!.class.name, OK | ICON_ERROR)
+    msgbox.show_modal
+    raise
+  end
+  
+  def on_exit
+    super
+    @log.info("Finished.")
+  end
+  
+end
+
+if ARGV.include?("-h") or ARGV.include?("--help")
+  puts "This is xinfo.rb, from xdo #{XDo::VERSION}."
+  puts "xinfo.rb is a tool for inspecting GUI windows on X."
+  puts
+  puts "Copyright © 2010 Marvin Gülker"
+  puts "Licensed under the same terms as Ruby."
+  puts "You can find Ruby's license at http://www.ruby-lang.org/en/LICENSE.txt."
+  puts
+  puts "xinfo.rb doesn't understand many command-line options."
+  puts "There's -h for this message, -V for verbose output"
+  puts "and -d for debugging. -v shows XDo's version."
+  exit
+elsif ARGV.include?("-v") or ARGV.include?("--version")
+  puts "This is xinfo.rb, from xdo #{XDo::VERSION}."
+  exit
+end
+
+$VERBOSE = true if ARGV.include?("-V")
+$DEBUG = true if ARGV.include?("-d")
+
+x = XInfo.new  
+x.main_loop

data/lib/xdo.rb

@@ -0,0 +1,37 @@
+#Encoding: UTF-8
+#This file is part of Xdo. 
+#Copyright © 2009 Marvin Gülker
+#  Initia in potestate nostra sunt, de eventu fortuna iudicat. 
+
+require "open3"
+require "strscan"
+
+#The namespace of this library. 
+module XDo
+  
+  #The command to start xdotool. 
+  XDOTOOL = "xdotool"
+  
+  #The command to start xsel. 
+  XSEL = "xsel"
+  
+  #The command to start xwininfo. 
+  XWININFO = "xwininfo"
+  
+  #The command to start xkill. 
+  XKILL = "xkill"
+  
+  #The command to start eject. 
+  EJECT = "eject"
+  
+  #The version of this library. 
+  VERSION = File.read(File.join(File.expand_path(File.dirname(__FILE__)), "..", "VERSION")).freeze
+  
+  #Class for errors in this library. 
+  class XError < StandardError
+  end
+  
+  class ParseError < StandardError
+  end
+  
+end #module XDo

data/lib/xdo/clipboard.rb

@@ -0,0 +1,208 @@
+#Encoding: UTF-8
+#This file is part of Xdo. 
+#Copyright © 2009, 2010 Marvin Gülker
+#  Initia in potestate nostra sunt, de eventu fortuna iudicat. 
+
+require_relative("../xdo")
+
+module XDo
+  
+  #A module for interaction with the X clipboard. Please note, that the X clipboard 
+  #consists of three parts: The PRIMARY clipboard, the CLIPBOARD clipboard, and 
+  #the SECONDARY clipboard. The clipboard you access normally via [CTRL]+[C] 
+  #or by right-clicking and selecting "copy", is usually the CLIPBOARD clipboard (but that 
+  #depends on the application you use). The three main methods of this module (#read, #write 
+  #and #clear) take a list symbols of the clipboards to interact with. If you don't want to 
+  #pass in the symbols, use the predefined read_xy, write_xy and clear_xy methods. They cannot 
+  #access more than one clipboard at a time. 
+  #The symbols for the clipboards are: 
+  #[PRIMARY] :primary
+  #[SECONDARY] :secondary
+  #[CLIPBOARD] :clipboard
+  #You cannot store complex objects like images via this interface, only strings. However, 
+  #you could translate an image into a string (packed pixels maybe?) and put that on the 
+  #clipboard -- for your own application this may be fine, but it won't magically allow 
+  #a user to paste that image into a graphics program. 
+  #
+  #The +xsel+ program used by this module is quite outdated. As far as I can see, it's 
+  #last update happened in 2002 and since I do not believe that software exists that 
+  #won't break over a period of 8 years without a single modification while updating systems I'm about to 
+  #switch to a newer one. +xclip+ is likely, but that one got it's last update in early 
+  #2009... 
+  module Clipboard
+    
+    class << self
+      
+      ##
+      # :singleton-method: read_primary
+      #Returns the contents of the PRIMARY clipboard. 
+      #See #read for an explanation. 
+      
+      ##
+      # :singleton-method: read_clipboard
+      #Returns the contents of the CLIPBOARD clipboard. 
+      #See #read for an explanation. 
+      
+      ##
+      # :singleton-method: read_secondary
+      #Returns the contents of the SECONDARY clipboard. 
+      #See #read for an explanation. 
+      
+      ##
+      # :singleton-method: write_primary
+      #Writes to the PRIMARY clipboard. 
+      #See #write for an explanation. 
+      
+      ##
+      # :singleton-method: write_clipboard
+      #Writes to the CLIPBOARD clipboard. 
+      #See #write for an explanation. 
+      
+      ##
+      # :singleton-method: write_secondary
+      #Writes to the SECONDARY clipboard. 
+      #See #write for an explanation. 
+      
+      ##
+      # :singleton-method: clear_primary
+      #Clears the PRIMARY clipboard. 
+      #See #clear for an explanation. 
+      
+      ##
+      # :singleton-method: clear_clipboard
+      #Clears the CLIPBOARD clipboard. 
+      #See #clear for an explanation. 
+      
+      ##
+      # :singleton-method: clear_secondary     
+      #Clears the SECONDARY clipboard. 
+      #See #clear for an explanation. 
+      
+      #Reads text from a X clipboard. 
+      #===Parameters
+      #[<tt>*from</tt>] (<tt>:clipboard</tt>, <tt>:primary</tt>, <tt>:secondary</tt>) Specifies from which clipboards you want to read (in 70% of all cases you want to read from <tt>:clipboard</tt>). 
+      #===Return value
+      #A hash of form
+      #  {:clip_sym => "clipboard_content"}
+      #If you didn't pass any arguments to #read, the hash will contain keys for 
+      #all clipboard, i.e. for <tt>:clipboard</tt>, <tt>:primary</tt> and <tt>:secondary</tt>. 
+      #If you did, only those symbols will be included you passed. See 
+      #the _Example_ section for an example of this. 
+      #===Example
+      #  XDo::Clipboard.read #| {:clipboard => "...", :primary => "...", :secondary => "..."}
+      #  XDo::Clipboard.read(:primary) #| {:primary => "..."}
+      #  XDo::Clipboard.read(:clipboard, :secondary) #| {clipboard => "...", :secondary => "..."}
+      #===Remarks
+      #You could also use one of the read_* methods for convenience.       
+      def read(*from)
+        if from.first.kind_of? Hash
+          warn("#{caller.first}: Deprecation warning: Use symbols as a rest argument now!")
+          from = from.first.keys
+        end
+        from.concat([:clipboard, :primary, :secondary]) if from.empty?
+        
+        hsh = {}
+        hsh[:primary] = `#{XSEL}` if from.include? :primary
+        hsh[:clipboard] = `#{XSEL} -b` if from.include? :clipboard
+        hsh[:secondary] = `#{XSEL} -s` if from.include? :secondary
+        hsh
+      end
+        
+      
+      #Writes text to a X clipboard. 
+      #===Parameters
+      #[<tt>*to</tt>] (<tt>:clipboard</tt>) Specifies to what clipboards you want to wrote to. 
+      #===Return value
+      #The text written. 
+      #===Example
+      #  XDo::Clipboard.write("I love Ruby") #You can now paste this via [CTRL] + [V]
+      #  XDo::Clipboard.write("I love Ruby", :primary) #You can now paste this via a middle-mouse-button click
+      #  XDo::Clipboard.write("I love Ruby", :clipboard, :primary) #Both of the above
+      #===Remarks
+      #You could also use one of the write_* methods for convenience. 
+      def write(text, *to)
+        if to.first.kind_of? Hash
+          warn("#{caller.first}: Deprecation warning: Use symbols as a rest argument now!")
+          to = to.first.keys
+        end
+        to << :clipboard if to.empty?
+        
+        IO.popen("xsel -i", "w"){|io| io.write(text)} if to.include? :primary
+        IO.popen("xsel -b -i", "w"){|io| io.write(text)} if to.include? :clipboard
+        IO.popen("xsel -s -i", "w"){|io| io.write(text)} if to.include? :secondary
+        text
+      end
+      
+      #Appends text to a X clipboard. 
+      #===Parameters
+      #[+text+] The text to append. 
+      #[<tt>*to</tt>] (<tt>:clipboard</tt>) The clipboards to which you want to append. 
+      #===Return value
+      #Undefined. 
+      #===Example
+      #  XDo::Clipboard.write("I love ")
+      #  XDo::Clipboard.append("Ruby")
+      #  puts XDo::Clipboard.read(:clipboard)[:clipboard] #=> I love Ruby
+      #  
+      #  XDo::Clipboard.write("I love", :primary)
+      #  XDo::Clipboard.append("Ruby", :primary, :clipboard)
+      #  #If you now paste via [CTRL] + [V], you'll get 'Ruby'. If you 
+      #  #paste via the middle mouse button, you'll get 'I love Ruby' 
+      #  #(Assuming you didn't execute the first block of code, of course). 
+      def append(text, *to)
+        if to.first.kind_of? Hash
+          warn("#{caller.first}: Deprecation warning: Use symbols as a rest argument now!")
+          to = to.first.keys
+        end
+        to << :clipboard if to.empty?
+        
+        IO.popen("xsel -a -i", "w"){|io| io.write(text)} if to.include? :primary
+        IO.popen("xsel -b -a -i", "w"){|io| io.write(text)} if to.include? :clipboard
+        IO.popen("xsel -s -a -i", "w"){|io| io.write(text)} if to.include? :secondary
+      end
+      
+      #Clears the specified clipboards. 
+      #===Parameters
+      #[<tt>*clips</tt>] (<tt>:primary</tt>, <tt>:clipboard</tt>, <tt>:secondary</tt>) The clipboards you want to clear. 
+      #===Return value
+      #nil. 
+      #===Example
+      #  XDo::Clipboard.write("I love Ruby")
+      #  XDo::Clipboard.clear
+      #  #Nothing can be pasted anymore
+      #  
+      #  XDo::Clipboard.write("I love Ruby", :clipboard, :primary)
+      #  XDo::Clipboard.clear(:primary)
+      #  #You can still paste via [CTRL] + [V], but not with the middle mouse button
+      def clear(*clips)
+        if clips.first.kind_of? Hash
+          warn("#{caller.first}: Deprecation warning: Use symbols as a rest argument now!")
+          clips = clips.first.keys
+        end
+        clips.concat([:primary, :clipboard, :secondary]) if clips.empty?
+        
+        `#{XSEL} -c` if clips.include? :primary
+        `#{XSEL} -b -c` if clips.include? :clipboard
+        `#{XSEL} -s -c` if clips.include? :secondary
+        nil
+      end
+      
+      [:primary, :clipboard, :secondary].each do |sym|
+        
+        define_method(:"read_#{sym}") do
+          read(sym)[sym]
+        end
+        
+        define_method(:"write_#{sym}") do |text|
+          write(text, sym)
+        end
+        
+        define_method(:"clear_#{sym}") do
+          clear(sym)
+        end
+        
+      end
+      
+    end
+  end
+end