win32-clipboard 0.4.0

data/CHANGES

@@ -0,0 +1,39 @@
+== 0.4.0 - 24-Feb-2006
+* Removed the C version entirely and replaced it with a pure Ruby version
+  that uses the Win32API package.
+* Added a gemspec.
+* Added a install.rb file.
+
+== 0.3.1 - 2-Feb-2006
+* Unicode fix to handle characters with null bytes.  Thanks go to Brian
+  Marick for the spot.
+
+== 0.3.0 - 26-May-2005
+* Changed the Clipboard.data= method to Clipboard.set_data because it does,
+  in fact, take up to two arguments.  This API change is the main reason for
+  the VERSION bump.
+* Added Clipboard.get_data method as an alias for Clipboard.data.
+* Removed the clipboard.rd file.  The Clipboard.txt file is now rdoc friendly.
+* Now Unicode friendly.
+* Added more tests, including Unicode test.
+* General code cleanup.
+
+== 0.2.1 - 28-Feb-2005
+* Moved the 'examples' directory to the toplevel directory.
+* Renamed the sample script to 'clipboard_test.rb'.
+* Made this document and README rdoc friendly.
+
+== 0.2.0 - 12-Jul-2004
+* Made Clipboard a class instead of a module.
+* Moved the ClipboardError class under the Win32 module.
+* Added the formats() class method.
+* Added the register_format class method.
+* Added the format_available? class method.
+* Added the format_name class method.
+* Replaced all instances (1) of the deprecated STR2CSTR() function with the
+  StringValuePtr() function.  This means that as of version 0.2.0 this package
+  requires Ruby 1.8.0 or later.
+* Moved the sample script to doc/examples.
+
+== 0.1.0 - 19-Nov-2003
+* Initial release

data/MANIFEST

@@ -0,0 +1,11 @@
+MANIFEST
+CHANGES
+README
+
+doc/clipboard.txt
+
+examples/clipboard_test.rb
+
+lib/win32/clipboard.rb
+
+test/tc_clipboard.rb

data/README

@@ -0,0 +1,106 @@
+== Description
+   win32-clipboard - a Ruby package for interacting with the Win32 clipboard.
+
+== Synopsis
+   require "win32/clipboard"
+   include Win32
+    
+   puts "Data on clipboard: " + Clipboard.data
+   puts "Number of available formats: " + Clipboard.num_formats
+    
+   puts "Setting data to 'foobar'"
+   Clipboard.data = "foobar"
+    
+   puts "Clipboard now contains: " + Clipboard.data
+    
+   puts "Clearing clipboard"
+   Clipboard.empty
+        
+== Class Methods
+Clipboard.data(format=nil)
+Clipboard.get_data(format=nil)
+   Returns the data currently in the clipboard.  If 'format' is
+   specified, it will attempt to retrieve the data in that format. The
+   default is Clipboard::TEXT.  See the 'Constants' section for
+   the supported formats.
+    
+   Note that this method does implicit conversions on formats with regards
+   to text data.  See the MSDN documentation for more details.
+    
+Clipboard.set_data(data, format=nil)
+   Sets the clipboard contents to the data that you specify.  You may
+   optionally specify a clipboard format.  The default is Clipboard::TEXT.
+    
+   See the 'Constants' section for a list of the supported formats.
+    
+Clipboard.empty
+   Empty the contents of the clipboard
+    
+Clipboard.format_available?(format_number)
+	Returns true if 'format_number' is currently available on the clipboard,
+	false otherwise.
+	
+Clipboard.format_name(format_number)
+	Returns the corresponding name for the given 'format_number', or nil
+	if it does not exist.
+	
+Clipboard.formats
+	Returns a hash of all the current formats, with the format number as the
+	key and the format name as the value for that key.
+    
+Clipboard.num_formats
+    Returns the number of different data formats currently on the clipboard.
+    
+Clipboard.register_format(format)
+	Registers the given 'format' (a String) as a clipboard format, which
+	can then be used as a valid clipboard format.
+	
+	If a registered format with the specified name already exists, a new
+	format is not registered and the return value identifies the existing
+	format. This enables more than one application to copy and paste data
+	using the same registered clipboard format. Note that the format name
+	comparison is case-insensitive.
+
+	Registered clipboard formats are identified by values in the range 0xC000
+	through 0xFFFF.
+	
+== Error Classes
+ClipboardError
+	Typically only raised if the clipboard fails to open or if you attempt to
+	register an invalid format.
+    
+== Constants
+=== Standard Constants
+VERSION
+   Returns the current version number of this package, as a String.
+    
+=== Clipboard Formats
+Clipboard::OEMTEXT
+   Text format containing characters in the OEM character set. Each line ends
+   with a carriage return/linefeed (CR-LF) combination. A null character
+   signals the end of the data.
+    
+Clipboard::TEXT
+   Text format. Each line ends with a carriage return/linefeed (CR-LF)
+   combination. A null character signals the end of the data. Use this format
+   for ANSI text.
+    
+Clipboard::UNICODETEXT
+   Unicode text format. Each line ends with a carriage return/linefeed
+   (CR-LF) combination. A null character signals the end of the data.  This
+   format is only supported on NT/2000/XP.
+    
+== Future Plans
+   Add more formatting option contants and related methods.
+    
+== License
+   Ruby's
+    
+== Copyright
+   (C) 2003-2006 Daniel J. Berger
+   All Rights Reserved
+    
+== Author
+   Daniel J. Berger
+   djberg96 at gmail dot com
+   imperator/mok on IRC

data/examples/clipboard_test.rb

@@ -0,0 +1,39 @@
+##########################################################################
+# clipboard_test.rb (win32-clipboard)
+#
+# Generic test script for those without TestUnit installed, or for
+# general futzing.
+##########################################################################
+base = File.basename(Dir.pwd)
+if base == "examples" || base =~ /win32-clipboard/
+	require "ftools"
+	Dir.chdir("..") if base == "examples"
+	Dir.mkdir("win32") unless File.exists?("win32")
+	File.copy("clipboard.so","win32")
+	$LOAD_PATH.unshift Dir.pwd
+	Dir.chdir("examples") if base =~ /win32-clipboard/
+end
+
+require "win32/clipboard"
+require "pp"
+include Win32
+
+puts "VERSION: " + Clipboard::VERSION
+
+pp Clipboard.formats
+pp Clipboard.data(Clipboard::DIB)
+pp Clipboard.format_available?(49161)
+pp Clipboard.format_name(999999999)
+pp Clipboard.format_available?(9999999)
+
+puts "Data was: [" + Clipboard.data + "]"
+
+Clipboard.set_data("foobar")
+
+puts "Data is now: [" + Clipboard.data + "]"
+
+puts "Number of available formats: " + Clipboard.num_formats.to_s
+
+Clipboard.empty
+
+puts "Clipboard emptied"

data/lib/win32/clipboard.rb

@@ -0,0 +1,182 @@
+require "Win32API"
+
+module Win32
+   class ClipboardError < StandardError; end
+   class Clipboard
+      VERSION = '0.4.0'
+      
+      # Clipboard data types
+      TEXT        = 1
+      OEMTEXT     = 7
+      UNICODETEXT = 13
+   		
+      # Alloc constants
+      GMEM_MOVEABLE = 0x0002
+      GMEM_ZEROINIT = 0x0040
+      GHND          = 0x0042
+ 
+      # Clipboard specific functions
+      @@OpenClipboard    = Win32API.new('user32', 'OpenClipboard', 'L', 'I')
+      @@CloseClipboard   = Win32API.new('user32', 'CloseClipboard', 'V', 'I')
+      @@GetClipboardData = Win32API.new('user32', 'GetClipboardData', 'I', 'P')
+      @@SetClipboardData = Win32API.new('user32', 'SetClipboardData', 'II', 'I')
+      @@EmptyClipboard   = Win32API.new('user32', 'EmptyClipboard', 'V', 'I')
+
+      @@CountClipboardFormats = Win32API.new(
+         'user32', 'CountClipboardFormats', 'V', 'I'
+      )
+      
+      @@IsClipboardFormatAvailable = Win32API.new(
+         'user32', 'IsClipboardFormatAvailable', 'I', 'I'
+      )
+      
+      @@GetClipboardFormatName = Win32API.new(
+         'user32', 'GetClipboardFormatName', 'IPI', 'I'
+      )
+      
+      @@EnumClipboardFormats = Win32API.new(
+         'user32', 'EnumClipboardFormats', 'I', 'I'
+      )
+      
+      @@RegisterClipboardFormat = Win32API.new(
+         'user32', 'RegisterClipboardFormat', 'P', 'I'
+      )
+   		
+      # Generic Win32 functions
+      @@GlobalAlloc  = Win32API.new('kernel32', 'GlobalAlloc', 'II' ,'I')
+      @@GlobalLock   = Win32API.new('kernel32', 'GlobalLock', 'I' ,'I')
+      @@GlobalFree   = Win32API.new('kernel32', 'GlobalFree', 'I' ,'I')
+      @@Memcpy       = Win32API.new('msvcrt',  'memcpy', 'IPI', 'I')
+
+      # Sets the clipboard contents to the data that you specify.  You may
+      # optionally specify a clipboard format.  The default is Clipboard::TEXT.
+      def self.set_data(clip_data, format = TEXT)
+         self.open
+         @@EmptyClipboard.call
+
+         # NULL terminate text
+         case format
+            when TEXT, OEMTEXT, UNICODETEXT				
+               clip_data << "\0"
+         end
+
+         # Global Allocate a movable piece of memory.
+         hmem = @@GlobalAlloc.call(GHND, clip_data.length + 4)
+         mem  = @@GlobalLock.call(hmem)
+         @@Memcpy.call(mem, clip_data, clip_data.length)
+
+         # Set the new data
+         if @@SetClipboardData.call(format, hmem) == 0
+            @@GlobalFree.call(hmem)
+            self.close
+            raise ClipboardError, "SetClipboardData() failed"
+         end
+
+         @@GlobalFree.call(hmem)   
+         self.close
+         self
+      end 		
+
+      # Returns the data currently in the clipboard.  If 'format' is
+      # specified, it will attempt to retrieve the data in that format. The
+      # default is Clipboard::TEXT. 		  		
+      def self.data(format = TEXT)
+         clipdata = ""
+         self.open
+         begin
+            clipdata = @@GetClipboardData.call(format)
+         rescue ArgumentError
+            # Assume failure is caused by no data in clipboard
+         end
+         self.close
+         clipdata
+      end
+
+      # An alias for Clipboard.data.
+      def self.get_data(format = TEXT)
+         self.data(format)
+      end
+
+      # Empties the contents of the clipboard.
+      def self.empty
+         self.open
+         @@EmptyClipboard.call
+         self.close
+         self
+      end
+
+      # Returns the number of different data formats currently on the
+      # clipboard.
+      def self.num_formats
+         count = 0
+         self.open
+         count = @@CountClipboardFormats.call
+         self.close
+         count
+      end
+      
+      # Returns whether or not +format+ (an int) is currently available.
+      def self.format_available?(format)
+         @@IsClipboardFormatAvailable.call(format) == 0 ? false : true
+      end
+      
+      # Returns the corresponding name for the given 'format_number', or nil
+      # if it does not exist.  You cannot specify any of the predefined
+      # clipboard formats (or nil is returned), only registered formats.
+      def self.format_name(format)
+         val = nil
+         buf = 0.chr * 80
+         self.open
+         if @@GetClipboardFormatName.call(format, buf, buf.length) != 0
+            val = buf
+         end
+         self.close
+         val.split(0.chr).first rescue nil
+      end
+      
+      # Returns a hash of all the current formats, with the format number as
+      # the key and the format name as the value for that key.
+      def self.formats
+         formats = {}
+         format = 0
+         
+         self.open
+         while 0 != (format = @@EnumClipboardFormats.call(format))
+            buf = 0.chr * 80
+            @@GetClipboardFormatName.call(format, buf, buf.length)
+            formats[format] = buf.split(0.chr).first
+         end
+         self.close
+         formats
+      end
+      
+      # Registers the given 'format' (a String) as a clipboard format, which
+      # can then be used as a valid clipboard format.
+      #
+      # If a registered format with the specified name already exists, a new
+      # format is not registered and the return value identifies the existing
+      # format. This enables more than one application to copy and paste data
+      # using the same registered clipboard format. Note that the format name
+      # comparison is case-insensitive.
+      #
+      # Registered clipboard formats are identified by values in the range 0xC000
+      # through 0xFFFF.
+      def self.register_format(format)
+         if @@RegisterClipboardFormat.call(format) == 0
+            raise ClipboardError, "RegisterClipboardFormat() call failed"
+         end
+      end
+
+      private
+
+      def self.open
+         if 0 == @@OpenClipboard.call(0)
+            raise ClipboardError, "OpenClipboard() failed"
+         end
+      end
+
+      def self.close
+         @@CloseClipboard.call
+      end
+   end
+end

data/test/tc_clipboard.rb

@@ -0,0 +1,94 @@
+###########################################################################
+# tc_clipboard.rb
+#
+# Test suite for the win32-clipboard package.  This will copy and remove
+# data from your clipboard.  If your current clipboard data is crucial to
+# you, please save it first.
+###########################################################################
+base = File.basename(Dir.pwd)
+if base == 'test' || base =~ /win32-clipboard/
+   Dir.chdir('..') if base == 'test'
+   $LOAD_PATH.unshift(Dir.pwd + '/lib')
+   Dir.chdir('test') if base =~ /win32-clipboard/
+end
+
+require "win32/clipboard"
+require "test/unit"
+include Win32
+
+class TC_Win32ClipBoard < Test::Unit::TestCase  
+   def test_version
+      assert_equal('0.4.0', Clipboard::VERSION)
+   end
+     
+   def test_data
+      assert_respond_to(Clipboard, :data)
+      assert_nothing_raised{ Clipboard.data }     
+      assert_kind_of(String, Clipboard.data, 'bad data type')
+      assert_raises(NameError){ Clipboard.data(CF_FOO) }
+   end
+   
+   def test_set_data
+      assert_respond_to(Clipboard, :set_data)
+      assert_nothing_raised{ Clipboard.set_data("foo") }
+      assert_nothing_raised{
+         Clipboard.set_data('Ηελλας', Clipboard::UNICODETEXT)
+      }
+      assert_raises(NameError){ Clipboard.set_data('foo', CF_FOO) }
+   end
+   
+   def test_set_and_get_ascii
+      assert_nothing_raised{ Clipboard.set_data('foobar') }
+      assert_equal('foobar', Clipboard.data)
+   end
+   
+   def test_set_and_get_unicode
+      assert_nothing_raised{
+         Clipboard.set_data('Ηελλας', Clipboard::UNICODETEXT)
+      }
+      assert_equal('Ηελλας', Clipboard.data(Clipboard::UNICODETEXT))
+   end
+   
+   def test_empty
+      assert_respond_to(Clipboard, :empty)
+      assert_nothing_raised{ Clipboard.empty }
+   end
+   
+   def test_num_formats
+      assert_respond_to(Clipboard, :num_formats)
+      assert_nothing_raised{ Clipboard.num_formats }
+      assert_kind_of(Fixnum, Clipboard.num_formats)
+   end
+   
+   # This TypeError check causes a segfault when using Win32API in 1.8.4 or
+   # earlier.
+   def test_register_format
+      assert_respond_to(Clipboard,:register_format)
+      assert_nothing_raised{ Clipboard.register_format('foo') }
+      #assert_raises(TypeError){ Clipboard.register_format(1) }
+   end
+   
+   def test_formats
+      assert_respond_to(Clipboard, :formats)
+      assert_nothing_raised{ Clipboard.formats }
+      assert_kind_of(Hash, Clipboard.formats)
+   end
+   
+   def test_format_available
+      assert_respond_to(Clipboard, :format_available?)
+      assert_nothing_raised{ Clipboard.format_available?(1) }
+   end
+   
+   def test_format_name
+      assert_respond_to(Clipboard, :format_name)
+      assert_nothing_raised{ Clipboard.format_name(1) }
+      assert_nil(Clipboard.format_name(9999999))
+      assert_raises(TypeError){ Clipboard.format_name('foo') }
+   end
+   
+   def test_constants
+      assert_not_nil(Clipboard::TEXT)
+      assert_not_nil(Clipboard::OEMTEXT)
+      assert_not_nil(Clipboard::UNICODETEXT)
+   end 
+end

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.11
+specification_version: 1
+name: win32-clipboard
+version: !ruby/object:Gem::Version 
+  version: 0.4.0
+date: 2006-02-24 00:00:00 -07:00
+summary: A package for interacting with the Windows clipboard
+require_paths: 
+- lib
+email: djberg96@gmail.com
+homepage: http://www.rubyforge.org/projects/win32utils
+rubyforge_project: win32utils
+description: A package for interacting with the Windows clipboard
+autorequire: 
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+authors: 
+- Daniel J. Berger
+files: 
+- examples/clipboard_test.rb
+- lib/win32/clipboard.rb
+- test/tc_clipboard.rb
+- CHANGES
+- MANIFEST
+- README
+test_files: 
+- test/tc_clipboard.rb
+rdoc_options: []
+
+extra_rdoc_files: 
+- CHANGES
+- README
+executables: []
+
+extensions: []
+
+requirements: []
+
+dependencies: []
+