win32-clipboard 0.4.4 → 0.5.0

data/CHANGES

@@ -1,3 +1,14 @@
+== 0.5.0 - 24-Apr-2009
+* Added the Clipboard.notify_change method, which notifies you if any changes
+  have been made to the clipboard.
+* Added support for copying file lists, bitmaps and Windows metafiles.
+* Added the Clipboard.clear alias for Clipboard.empty
+* The previous documentation for the Clipboard.format_available? method was
+  misleading. It has been corrected.
+* Added rdoc for modules, classes and constants, and added some inline
+  code examples for some methods.
+* Gemspec update for handling a deprecated method.
+
 == 0.4.4 - 26-Aug-2008
 * Some internal refactoring to ensure that the clipboard is closed on failure
   in a more robust fashion.

data/Rakefile

@@ -1,20 +1,24 @@
 require 'rake'
 require 'rake/testtask'
 
-desc "Install the win32-clipboard package (non-gem)"
+desc "Install the win32-clipboard library (non-gem)"
 task :install do
    dest = File.join(Config::CONFIG['sitelibdir'], 'win32')
    Dir.mkdir(dest) unless File.exists? dest
    cp 'lib/win32/clipboard.rb', dest, :verbose => true
 end
 
-desc "Install the win32-clipboard package as a gem"
+desc "Install the win32-clipboard library as a gem"
 task :install_gem do
    ruby 'win32-clipboard.gemspec'
    file = Dir["*.gem"].first
    sh "gem install #{file}"
 end
 
+desc "Run the example program"
+task :example do
+   sh "ruby -Ilib examples/clipboard_test.rb"
+
 Rake::TestTask.new do |t|
    t.warning = true
    t.verbose = true

data/examples/clipboard_test.rb

@@ -1,13 +1,9 @@
 ##########################################################################
 # clipboard_test.rb (win32-clipboard)
 #
-# Generic test script for those without TestUnit installed, or for
-# general futzing.
+# Generic test script for those without Test::Unit installed, or for
+# general futzing. You can run this example via the 'rake example' task.
 ##########################################################################
-Dir.chdir('..') if File.basename(Dir.pwd) == 'examples'
-$LOAD_PATH.unshift(Dir.pwd)
-$LOAD_PATH.unshift(Dir.pwd + '/lib')
-
 require "win32/clipboard"
 require "pp"
 include Win32

data/lib/win32/clipboard.rb

@@ -1,31 +1,72 @@
 require 'windows/clipboard'
 require 'windows/memory'
 require 'windows/error'
+require 'windows/shell'
+require 'windows/library'
+require 'windows/window'
 require 'windows/msvcrt/buffer'
+require 'windows/gdi/metafile'
+require 'windows/window/message'
+require 'windows/window/classes'
 
+# The Win32 module serves as a namespace only.
 module Win32
+   # The Clipboard class encapsulates functions that relate to the MS Windows
+   # clipboard.
    class Clipboard
+      # The Clipboard::Error class is raised if any of the Win32::Clipboard
+      # methods should fail.
       class Error < StandardError; end
       
       include Windows::Clipboard
       include Windows::Memory
       include Windows::Error
+      include Windows::Shell
+      include Windows::Library
+      include Windows::Window
       include Windows::MSVCRT::Buffer
+      include Windows::GDI::MetaFile
+      include Windows::Window::Message
+      include Windows::Window::Classes
 
       extend Windows::Clipboard
       extend Windows::Memory
       extend Windows::Error
+      extend Windows::Shell
+      extend Windows::Library
+      extend Windows::Window
       extend Windows::MSVCRT::Buffer
+      extend Windows::GDI::MetaFile
+      extend Windows::Window::Message
+      extend Windows::Window::Classes
       
-      VERSION = '0.4.4'
+      # The version of this library
+      VERSION = '0.5.0'
       
-      # Clipboard data types
-      TEXT        = CF_TEXT
-      OEMTEXT     = CF_OEMTEXT
+      # Clipboard formats
+      
+      # Text
+      TEXT = CF_TEXT
+      OEMTEXT = CF_OEMTEXT
       UNICODETEXT = CF_UNICODETEXT
 
-      # Sets the clipboard contents to the data that you specify.  You may
-      # optionally specify a clipboard format.  The default is Clipboard::TEXT.
+      # Images
+      DIB = CF_DIB
+      BITMAP = CF_BITMAP
+      
+      # Metafiles
+      ENHMETAFILE = CF_ENHMETAFILE
+      
+      # Files
+      HDROP = CF_HDROP
+
+      # Sets the clipboard contents to the data that you specify. You may
+      # optionally specify a clipboard format. The default is Clipboard::TEXT.
+      #
+      # Example:
+      #
+      #    # Put the string 'hello' on the clipboard
+      #    Win32::Clipboard.set_data('hello')
       # 
       def self.set_data(clip_data, format = TEXT)
          self.open
@@ -59,25 +100,51 @@ module Win32
       # specified, it will attempt to retrieve the data in that format. The
       # default is Clipboard::TEXT.
       #
-      # If there is no data in the clipboard then an empty string is returned.
+      # If there is no data in the clipboard, or data is available but the
+      # format doesn't match the data, then an empty string is returned.
+      #
+      # Examples:
+      #
+      #    # Get some plain text
+      #    Win32::Clipboard.data # => e.g. 'hello'
+      #
+      #    # Get a list of files copied from the Windows Explorer window
+      #    Win32::Clipboard.data(Clipboard::HDROP) # => ['foo.rb', 'bar.rb']
+      #
+      #    # Get a bitmap and write it to another file
+      #    File.open('bitmap_copy', 'wb'){ |fh|
+      #       fh.write Win32::Clipboard.data(Clipboard::DIB)
+      #    }
       # 
       def self.data(format = TEXT)
          begin
             self.open
-            clipdata = GetClipboardData(format) || ""
+            if IsClipboardFormatAvailable(format)
+               handle = GetClipboardData(format)
+               case format
+                  when TEXT, OEMTEXT, UNICODETEXT
+                     clip_data = 0.chr * GlobalSize(handle)
+                     memcpy(clip_data, handle, clip_data.size)
+                     clip_data.strip!
+                  when HDROP
+                     clip_data = get_file_list(handle)
+                  when ENHMETAFILE
+                     clip_data = get_metafile_data(handle)
+                  when DIB, BITMAP
+                     clip_data = get_image_data(handle)
+                  else
+                     raise Error, 'format not supported'
+               end
+            else
+               clip_data = ''
+            end
          ensure
             self.close
          end
 
-         clipdata
+         clip_data
       end
       
-      # Singleton aliases
-      # 
-      class << self
-         alias :get_data :data
-      end
-
       # Empties the contents of the clipboard.
       # 
       def self.empty
@@ -91,6 +158,13 @@ module Win32
          self
       end
 
+      # Singleton aliases
+      # 
+      class << self
+         alias :get_data :data
+         alias :clear :empty
+      end
+
       # Returns the number of different data formats currently on the
       # clipboard.
       # 
@@ -135,6 +209,10 @@ module Win32
       
       # 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.
+      #
+      # Example:
+      #
+      #    Win32::Clipboard.formats # => {1 => nil, 49335 => "HTML Format"}
       # 
       def self.formats
          formats = {}
@@ -167,22 +245,168 @@ module Win32
       # through 0xFFFF.
       # 
       def self.register_format(format)
+         raise TypeError unless format.is_a?(String)
+         
          if RegisterClipboardFormat(format) == 0
             error = "RegisterClipboardFormat() call failed: " + get_last_error
-            raise Error,  error
+            raise Error, error
+         end
+      end
+
+      # Sets up a notification loop that will call the provided block whenever
+      # there's a change to the clipboard.
+      #
+      # Example:
+      #
+      #    Win32::Clipboard.notify_change{
+      #       puts "There's been a change in the clipboard contents!"
+      #    }
+      #--
+      # We skip the first notification because the very act of attaching the
+      # new window causes it to trigger once.
+      #
+      def self.notify_change(&block)
+         name   = 'ruby-clipboard-' + Time.now.to_s
+         handle = CreateWindow('static', name, 0, 0, 0, 0, 0, 0, 0, 0, 0)
+         
+         @first_notify = true
+
+         wnd_proc = Win32::API::Callback.new('LLLL', 'L') do |hwnd, umsg, wparam, lparam|
+            case umsg
+               when WM_DRAWCLIPBOARD
+                  yield unless @first_notify
+                  next_viewer = GetWindowLongPtr(hwnd, GWL_USERDATA)
+                  if next_viewer != 0
+                     PostMessage(next_viewer, umsg, wparam, lparam)
+                  end
+                  rv = 0
+               when WM_CHANGECBCHAIN
+                  yield unless @first_notify
+                  next_viewer = lparam if next_viewer == wparam
+                  if next_viewer != 0
+                     PostMessage(next_viewer, umsg, wparam, lparam)
+                  end
+                  rv = 0
+               else
+                  rv = DefWindowProc(hwnd, umsg, wparam, lparam)
+            end
+            
+            @first_notify = false
+         
+            rv
+         end
+
+         old_wnd_proc = SetWindowLongPtr(handle, GWL_WNDPROC, wnd_proc.address)
+         next_viewer  = SetClipboardViewer(handle)
+
+         SetWindowLongPtr(handle, GWL_USERDATA, next_viewer)
+
+         msg = 0.chr * 100
+
+         while true
+            while PeekMessage(msg, handle, 0, 0, 1)
+               TranslateMessage(msg)
+               DispatchMessage(msg)
+            end
+            sleep 0.1
          end
       end
 
       private
 
+      # Opens the clipboard and prevents other applications from modifying
+      # the clipboard content until it is closed.
+      #
       def self.open
-         if 0 == OpenClipboard(0)
+         if 0 == OpenClipboard(nil)
             raise Error, "OpenClipboard() failed: " + get_last_error
          end
       end
 
+      # Close the clipboard
+      #
       def self.close
          CloseClipboard()
       end
+      
+      # Get data for enhanced metadata files
+      #
+      def self.get_metafile_data(handle)
+         buf_size = GetEnhMetaFileBits(handle, 0, nil)
+         buf = 0.chr * buf_size
+         GetEnhMetaFileBits(handle, buf_size, buf)
+         buf
+      end
+      
+      # Get data for bitmap files
+      #
+      def self.get_image_data(handle)       
+         buf = nil
+         bmi = 0.chr * 44 # BITMAPINFO
+
+         begin
+            address  = GlobalLock(handle)
+            buf_size = GlobalSize(handle)
+
+            memcpy(bmi, address, bmi.length)
+
+            size        = bmi[0,4].unpack('L').first  # biSize
+            bit_count   = bmi[14,2].unpack('S').first # biBitCount
+            compression = bmi[16,4].unpack('L').first # biCompression
+            size_image  = bmi[20,4].unpack('L').first # biSizeImage
+            clr_used    = bmi[32,4].unpack('L').first # biClrUsed
+
+            size_image = buf_size + 16 if size_image == 0
+
+            # Calculate the header size
+            case bit_count
+               when 1
+                  table_size = 2
+               when 4
+                  table_size = 16
+               when 8
+                  table_size = 256
+               when 16, 32
+                  if compression == 0
+                     table_size = clr_used
+                  elsif compression == 3
+                     table_size = 3
+                  else
+                     raise Error, "invalid bit/compression combination"
+                  end
+               when 24
+                  table_size = clr_used
+               else
+                  raise Error, "invalid bit count"
+            end # case
+
+            offset = 0x36 + (table_size * 4)
+            buf = 0.chr * buf_size
+
+            memcpy(buf, address, buf.size)
+
+            buf = "\x42\x4D" + [size_image].pack('L') + 0.chr * 4 + [offset].pack('L') + buf
+         ensure
+            GlobalUnlock(handle)
+         end
+
+         buf
+      end
+
+      # Get and return an array of file names that have been copied.
+      #
+      def self.get_file_list(handle)
+         array = []
+         count = DragQueryFile(handle, 0xFFFFFFFF, nil, 0)
+
+         0.upto(count - 1){ |i|
+            length = DragQueryFile(handle, i, nil, 0) + 1
+            buf = 0.chr * length
+            DragQueryFile(handle, i, buf, buf.length)
+            array << buf.strip
+         }
+
+         array
+      end
    end
-end
+end

data/test/test_clipboard.rb

@@ -7,34 +7,48 @@
 #
 # You should run this test case via the 'rake test' task.
 ###########################################################################
+require 'rubygems'
+gem 'test-unit'
+
 require 'win32/clipboard'
 require 'test/unit'
 include Win32
 
 class TC_Win32_ClipBoard < Test::Unit::TestCase  
    def test_version
-      assert_equal('0.4.4', Clipboard::VERSION)
+      assert_equal('0.5.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) }
+      assert_kind_of(String, Clipboard.data)
+   end
+   
+   def test_data_expected_errors
+      assert_raise(TypeError){ Clipboard.data('test') }
+      assert_raise(NameError){ Clipboard.data(CF_FOO) }
    end
    
    def test_get_data_alias
       assert_respond_to(Clipboard, :get_data)
-      assert_equal(true, Clipboard.method(:data) == Clipboard.method(:get_data))
+      assert_true(Clipboard.method(:data) == Clipboard.method(:get_data))
    end
    
    def test_set_data
       assert_respond_to(Clipboard, :set_data)
       assert_nothing_raised{ Clipboard.set_data("foo") }
+   end
+   
+   def test_set_data_unicode
       assert_nothing_raised{
          Clipboard.set_data('Ηελλας', Clipboard::UNICODETEXT)
       }
-      assert_raises(NameError){ Clipboard.set_data('foo', CF_FOO) }
+   end
+   
+   def test_set_data_expected_errors
+      assert_raise(ArgumentError){ Clipboard.set_data }
+      assert_raise(NameError){ Clipboard.set_data('foo', CF_FOO) }
    end
    
    def test_set_and_get_ascii
@@ -54,18 +68,28 @@ class TC_Win32_ClipBoard < Test::Unit::TestCase
       assert_nothing_raised{ Clipboard.empty }
    end
    
+   def test_clear_alias
+      assert_respond_to(Clipboard, :clear)
+      assert_true(Clipboard.method(:clear) == Clipboard.method(: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_num_formats_expected_errors
+      assert_raise(ArgumentError){ Clipboard.num_formats(true) }
+   end
+
    def test_register_format
-      assert_respond_to(Clipboard,: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_register_format_expected_errors
+      assert_raises(TypeError){ Clipboard.register_format(1) }
    end
    
    def test_formats
@@ -74,21 +98,37 @@ class TC_Win32_ClipBoard < Test::Unit::TestCase
       assert_kind_of(Hash, Clipboard.formats)
    end
    
+   def test_formats_expected_errors
+      assert_raise(ArgumentError){ Clipboard.formats(true) }      
+   end
+   
    def test_format_available
       assert_respond_to(Clipboard, :format_available?)
       assert_nothing_raised{ Clipboard.format_available?(1) }
+      assert_boolean(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_format_name_expected_errors
+      assert_raise(TypeError){ Clipboard.format_name('foo') }
+   end
+   
+   def test_notify_change
+      assert_respond_to(Clipboard, :notify_change)
    end
    
    def test_constants
       assert_not_nil(Clipboard::TEXT)
       assert_not_nil(Clipboard::OEMTEXT)
       assert_not_nil(Clipboard::UNICODETEXT)
+      assert_not_nil(Clipboard::BITMAP)
+      assert_not_nil(Clipboard::DIB)
+      assert_not_nil(Clipboard::HDROP)
+      assert_not_nil(Clipboard::ENHMETAFILE)
    end 
 end

data/win32-clipboard.gemspec

@@ -1,27 +1,32 @@
 require "rubygems"
 
 spec = Gem::Specification.new do |gem|
-	gem.name         = "win32-clipboard"
-	gem.version      = "0.4.4"
-	gem.authors      = ["Daniel J. Berger", "Park Heesob"]
-	gem.email        = "djberg96@gmail.com"
-	gem.homepage     = "http://www.rubyforge.org/projects/win32utils"
-	gem.platform     = Gem::Platform::RUBY
-	gem.summary      = "A library for interacting with the Windows clipboard"
-	gem.description  = "A library for interacting with the Windows clipboard"
-	gem.test_file    = "test/test_clipboard.rb"
-	gem.has_rdoc     = true
-	gem.extra_rdoc_files  = ['CHANGES', 'README', 'MANIFEST']
-	gem.rubyforge_project = "win32utils"
-	gem.add_dependency("windows-pr", ">= 0.8.1")
-	
-	files = Dir["doc/*"] + Dir["examples/*"] + Dir["lib/win32/*"]
-	files += Dir["test/*"] + Dir["[A-Z]*"]
-	files.delete_if{ |item| item.include?("CVS") }
-	gem.files = files
+   gem.name              = 'win32-clipboard'
+   gem.version           = '0.5.0'
+   gem.authors           = ['Daniel J. Berger', 'Park Heesob']
+   gem.email             = 'djberg96@gmail.com'
+   gem.homepage          = 'http://www.rubyforge.org/projects/win32utils'
+   gem.platform          = Gem::Platform::RUBY
+   gem.summary           = 'A library for interacting with the Windows clipboard'
+   gem.test_file         = 'test/test_clipboard.rb'
+   gem.has_rdoc          = true
+   gem.extra_rdoc_files  = ['CHANGES', 'README', 'MANIFEST']
+   gem.rubyforge_project = 'win32utils'
+
+   gem.add_dependency('windows-pr', '>= 1.0.3')
+
+   gem.description = "The win32-clipboard library provides an interface for
+      interacting with the Windows clipboard. It supports the ability to read
+      and write text, images, files, and Windows metafiles.".gsub(/\s+/, ' ')
+   
+   files = Dir['doc/*'] + Dir['examples/*'] + Dir['lib/win32/*']
+   files += Dir['test/*'] + Dir['[A-Z]*']
+   files.delete_if{ |item| item.include?('CVS') }
+
+   gem.files = files
 end
 
 if $0 == __FILE__
-   Gem.manage_gems
+   Gem.manage_gems if Gem::RubyGemsVersion.to_f < 1.0
    Gem::Builder.new(spec).build
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: win32-clipboard
 version: !ruby/object:Gem::Version 
-  version: 0.4.4
+  version: 0.5.0
 platform: ruby
 authors: 
 - Daniel J. Berger
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-08-26 00:00:00 -06:00
+date: 2009-04-24 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -21,9 +21,9 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 0.8.1
+        version: 1.0.3
     version: 
-description: A library for interacting with the Windows clipboard
+description: The win32-clipboard library provides an interface for interacting with the Windows clipboard. It supports the ability to read and write text, images, files, and Windows metafiles.
 email: djberg96@gmail.com
 executables: []
 
@@ -38,15 +38,14 @@ files:
 - lib/win32/clipboard.rb
 - test/test_clipboard.rb
 - CHANGES
-- examples
-- lib
 - MANIFEST
 - Rakefile
 - README
-- test
 - win32-clipboard.gemspec
 has_rdoc: true
 homepage: http://www.rubyforge.org/projects/win32utils
+licenses: []
+
 post_install_message: 
 rdoc_options: []
 
@@ -67,9 +66,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: win32utils
-rubygems_version: 1.2.0
+rubygems_version: 1.3.2
 signing_key: 
-specification_version: 2
+specification_version: 3
 summary: A library for interacting with the Windows clipboard
 test_files: 
 - test/test_clipboard.rb