win32-shortcut 0.2.0

data/CHANGES

@@ -0,0 +1,44 @@
+== 0.2.0 - 30-Oct-2006
+* Replaced the C extension code with a pure Ruby version that uses win32ole
+  and Wscript.Shell behind the scenes.
+* The Shortcut#icon_number method was dropped since that property isn't
+  supported by Wscript.Shell.  It was a useless method anyway.
+* The Shortcut#relative_path method was dropped since that property isn't
+  actually supported by a Wsh.Shortcut object, contrary to what the MSDN
+  documentation says.
+* The Shortcut.new method now takes a block, yields self, and automatically
+  ensures that Shortcut#save is called at the end of the block.
+* The Shortcut#hotkey method now takes a human readable string instead of a
+  hex value.
+* The Shortcut#show_cmd method was renamed Shortcut#window_style (though
+  there's an alias for backwards compatability.
+* The Shortcut#window_style accessor now accepts/emits human readable
+  strings as well as constants.
+* Removed the 'doc' directory.  The documentation is now inlined as rdoc
+  and/or in the README file.
+
+== 0.1.4 - 17-Jul-2005
+* Fixed a bug in the Shortcut.open method.  Thanks go to an anonymous user
+  for the spot.
+* Added a test for the Shortcut.open method.
+* Added a Shortcut.open example in the test script.
+* Modified the extconf.rb script to set _WIN32_WINNT macro as needed.
+
+== 0.1.3 - 9-Jun-2005
+* Removed shortcut.rd file.
+* The shortcut.txt file is now rdoc friendly.
+* Now Unicode friendly.
+* Minor test suite tweaks and additions.
+* Minor changes to the example program.
+* Code cleanup.
+
+== 0.1.2 - 1-Mar-2005
+* Moved the 'examples' directory to the toplevel directory.
+* Renamed the sample script to 'shortcut_test.rb'.
+
+== 0.1.1 - 12-Feb-2005
+* Modified the extconf.rb file to be more cygwin/mingw friendly.
+* Modified some documentation to be more rdoc friendly.
+
+== 0.1.0 - 28-Sep-2004
+* Initial release

data/MANIFEST

@@ -0,0 +1,11 @@
+CHANGES
+MANIFEST
+README
+install.rb
+win32-shortcut.gemspec
+
+examples/example_shortcut.rb
+
+lib/win32/shortcut.rb
+
+test/tc_shortcut.rb

data/README

@@ -0,0 +1,61 @@
+== Description
+   This is an interface for creating and/or modifying Windows shortcuts.
+
+== Requirements
+   Ruby 1.8.2 or later.
+   The win32ole package (part of the stdlib).
+
+== Installation
+=== Gem Installation
+   * ruby win32-shortcut.gemspec
+   * gem install win32-shortcut-x.y.z.gem
+=== Standard Installation
+   * ruby install.rb
+   
+== Synopsis
+	require 'win32/shortcut'
+   include Win32
+	
+   Shortcut.new('c:\test.lnk') do |s|
+      s.description = "test link"
+      s.path = "c:\\winnt\\notepad.exe"
+      s.show_cmd = Shortcut::SHOWNORMAL
+      s.working_directory = "C:\\"
+   end
+   
+== Notes
+   This code uses win32ole + wscript behind the scenes.  The original C code
+   is not distributed as part of the release, but is still retained in the
+   CVS repository under the 'ext' directory should anyone ever need it.
+
+== Known Bugs
+   None known.
+	
+   Please report any bugs on the project page at
+   http://rubyforge.org/projects/win32utils.
+	
+== Future Plans
+   Ideas welcome.  Please submit them on the project page as a
+   "Feature Request".
+	
+== Copyright
+   (C) 2003-2006, Daniel J. Berger, All Rights Reserved
+    
+== License
+   Ruby's
+    
+== Warranty
+   This package is provided "as is" and without any express or
+   implied warranties, including, without limitation, the implied
+   warranties of merchantability and fitness for a particular purpose.
+	
+== Acknowledgements
+   The original win32-shortcut package was largely based on Aldo Calpini's
+   Win32::Shortcut Perl module, and I copied some of the documentation as
+   well.
+   
+   The current version is based on a patch by Jano Svitok.
+	
+== Author(s)
+   Daniel J. Berger   
+   Park Heesob

data/install.rb

@@ -0,0 +1,11 @@
+# For those who don't like gems...
+require 'rbconfig'
+require 'ftools'
+include Config
+
+sitelibdir = CONFIG['sitelibdir']
+installdir = sitelibdir + '/win32'
+file = 'lib\win32\shortcut.rb'
+
+Dir.mkdir(installdir) unless File.exists?(installdir)
+File.copy(file, installdir, true)

data/lib/win32/shortcut.rb

@@ -0,0 +1,206 @@
+require 'win32ole'
+
+module Win32
+   class Shortcut      
+      VERSION = '0.2.0'
+            
+      # Activates and displays a window. If the window is minimized or maximized,
+      # the system restores it to its original size and position. An application
+      # should specify this flag when displaying the window for the first time.
+      # 
+      SHOWNORMAL = 1
+
+      # Activates the window and displays it as a maximized window.
+      # 
+      SHOWMAXIMIZED = 3
+
+      # Displays the window in its minimized state, leaving the currently active
+      # window as active.
+      # 
+      SHOWMINNOACTIVE = 7
+      
+      # Creates and returns a Shortcut object.  In block form it yields +self+
+      # and automatically ensures that Shortcut#save is called at the end of
+      # the block.  In non-block form it does not actually create the shortcut
+      # until the Shorcut#save method is called.
+      # 
+      def initialize(file)
+         @file  = file
+         @shell = WIN32OLE.new('WScript.Shell')
+         @link  = @shell.CreateShortcut(file)
+         
+         if block_given?
+            begin
+               yield self
+            ensure
+               save
+            end
+         end
+      end
+      
+      # Identical to Shortcut#new except that it will raise an ArgumentError
+      # unless the +file+ already exists.
+      # 
+      def self.open(file)
+         raise ArgumentError, 'shortcut not found' unless File.exists?(file)
+         self.new(file)
+      end
+      
+      # Returns any arguments (i.e. command line options) for the shortcut.
+      # 
+      def arguments
+         @link.Arguments
+      end
+      
+      # Sets the arguments (i.e. command line options) for the shortcut.
+      # 
+      def arguments=(args)
+         @link.Arguments = args
+      end
+      
+      # Returns the description (i.e. comment) for the shortcut.
+      # 
+      def description
+         @link.Description
+      end
+      
+      # Sets the description for the shortcut.
+      # 
+      def description=(desc)
+         @link.Description = desc
+      end
+      
+      # Returns the file name of the shortcut.
+      # 
+      def file
+         @file
+      end
+      
+      # Returns the hotkey (i.e. shortcut key) associated to the shortcut, in
+      # the form of a 2-byte number of which the first byte identifies the
+      # modifiers (Ctrl, Alt, Shift) and the second is the ASCII code of
+      # the character key.
+      # 
+      def hotkey
+         @link.HotKey
+      end
+      
+      # Sets the hotkey for the shortcut.
+      # 
+      def hotkey=(key)
+         @link.HotKey = key
+      end
+      
+      # Returns the name of the file that contain the icon for the shortcut.
+      # In practice this is almost always blank.  YMMV.
+      # 
+      def icon_location
+         @link.IconLocation
+      end
+      
+      # Sets the name of the icon file to be used for the shortcut.
+      # 
+      def icon_location=(location)
+         @link.IconLocation = location
+      end
+      
+      # Returns the target of the shortcut. This is, joined with arguments, the
+      # content of the "Target" field in a Shortcut Properties Dialog Box. The
+      # target name is returned in 8.3 format.
+      # 
+      def path
+         @link.TargetPath
+      end
+      
+      alias target_path path
+      
+      # Sets the target of the shortcut.
+      # 
+      def path=(link_path)
+         @link.TargetPath = link_path
+      end
+      
+      alias target_path= path=
+      
+      # Attempts to automatically resolve a shortcut and returns the resolved path,
+      # or raises an error.  In case no resolution was made, the path is returned
+      # unchanged.
+      # 
+      # Note that the path is automatically updated in the path attribute of the
+      # Shortcut object.
+      # 
+      def resolve
+         @link.FullName
+      end
+      
+      # Returns the type of window style used by a shortcut.  The possible
+      # return values are 'normal', 'maximized', or 'minimized'.
+      #
+      def window_style
+         case @link.WindowStyle
+            when SHOWNORMAL
+               'normal'
+            when SHOWMAXIMIZED
+               'maximized'
+            when SHOWMINNOACTIVE
+               'minimized'
+            else
+               'unknown' # Should never reach here
+         end
+      end
+      
+      # Deprecated.
+      alias show_cmd window_style
+      
+      # Sets the window style to a shortcut.  The +style+ can be one of the
+      # following three constants or equivalent string values:
+      # 
+      # * SHOWNORMAL      or 'normal'
+      # * SHOWMAXIMIZED   or 'maximized'
+      # * SHOWMINNOACTIVE or 'minimized'
+      # 
+      # Please see the documentation for those constants for further details.
+      # 
+      def window_style=(style)
+         valid = [SHOWNORMAL, SHOWMAXIMIZED, SHOWMINNOACTIVE]
+         valid.concat(['normal', 'maximized', 'minimized'])
+         
+         unless valid.include?(style)
+            raise ArgumentError, 'invalid style'
+         end
+         
+         if style.is_a?(String)
+            case style.downcase
+               when 'normal'
+                  style = SHOWNORMAL
+               when 'maximized'
+                  style = SHOWMAXIMIZED
+               when 'minimized'
+                  style = SHOWMINNOACTIVE
+            end
+         end
+   
+         @link.WindowStyle = style
+      end
+      
+      # Deprecated.
+      alias show_cmd= window_style=
+      
+      # Returns directory in which the targeted program will be executed.
+      # Correspond to the "Start in" field of a Shortcut Properties Dialog Box.
+      # 
+      def working_directory
+         @link.WorkingDirectory
+      end
+      
+      # Sets the directory in which the targeted program will be executed.
+      #
+      def working_directory=(directory)
+         @link.WorkingDirectory = directory
+      end
+      
+      def save
+         @link.Save
+      end
+   end
+end

data/test/tc_shortcut.rb

@@ -0,0 +1,109 @@
+##############################################################################
+# tc_shortcut.rb
+#
+# Test suite for the win32-shortcut package.  This will temporarily create
+# a link to Notepad on C:\, which should be automatically deleted.
+##############################################################################
+Dir.chdir('..') if File.basename(Dir.pwd) == 'test'
+$LOAD_PATH.unshift(Dir.pwd + '/lib')
+
+require 'win32/shortcut'
+require 'test/unit'
+include Win32
+
+class TC_Shortcut < Test::Unit::TestCase
+   def setup
+      @link = Dir.pwd + '/test.lnk'
+      @s = Shortcut.new(@link)
+   end
+   
+   def test_version
+      assert_equal('0.2.0', Shortcut::VERSION)
+   end
+  
+   def test_arguments
+      assert_respond_to(@s, :arguments)
+      assert_respond_to(@s, :arguments=)
+      assert_nothing_raised{ @s.arguments }
+      assert_nothing_raised{ @s.arguments = '-v' }
+   end
+    
+   def test_description
+      assert_respond_to(@s, :description)
+      assert_respond_to(@s, :description=)
+      assert_nothing_raised{ @s.description }
+      assert_nothing_raised{ @s.description = "test link" }
+   end
+  
+   def test_file
+      assert_respond_to(@s, :file)
+      assert_nothing_raised{ @s.file }
+   end
+   
+   # TODO: Figure out why hotkey assignment fails here.  It works fine inthe
+   # example program.
+   #  
+   def test_hotkey
+      assert_respond_to(@s, :hotkey)
+      assert_respond_to(@s, :hotkey=)
+      assert_nothing_raised{ @s.hotkey }
+      #assert_nothing_raised{ @s.hotkey = "CTRL-SHIFT-F" }
+   end
+   
+   def test_icon_location
+      assert_respond_to(@s, :icon_location)
+      assert_respond_to(@s, :icon_location=)
+      assert_nothing_raised{ @s.icon_location }
+      assert_nothing_raised{ @s.icon_location = "notepad.exe"}
+   end
+ 
+   def test_path
+      assert_respond_to(@s, :path)
+      assert_respond_to(@s, :path=)
+      assert_nothing_raised{ @s.path }
+      assert_nothing_raised{ @s.path = 'c:\winnt\notepad.exe' }
+   end
+   
+   def test_open
+      shortcut = Shortcut.new(@link)
+      shortcut.save
+      
+      assert_respond_to(Shortcut, :open)
+      assert_nothing_raised{ Shortcut.open(@link) }
+   end   
+
+   def test_resolve
+      assert_respond_to(@s, :resolve)
+   end
+   
+   def test_save
+      assert_respond_to(@s, :save)
+      assert_nothing_raised{ @s.save }
+      assert_equal(true, File.exists?(@link))
+   end
+   
+   def test_window_style
+      assert_respond_to(@s, :window_style)
+      assert_respond_to(@s, :window_style=)
+      assert_nothing_raised{ @s.window_style }
+      assert_nothing_raised{ @s.window_style = Shortcut::SHOWNORMAL }
+   end
+   
+   def test_working_directory
+      assert_respond_to(@s, :working_directory)
+      assert_respond_to(@s, :working_directory=)
+      assert_nothing_raised{ @s.working_directory }
+      assert_nothing_raised{ @s.working_directory = "c:\\" }
+   end
+   
+   def test_constants
+      assert_not_nil(Shortcut::SHOWNORMAL)
+      assert_not_nil(Shortcut::SHOWMINNOACTIVE)
+      assert_not_nil(Shortcut::SHOWMAXIMIZED)
+   end
+   
+   def teardown
+      @s = nil
+      File.delete(@link) if File.exists?(@link)
+   end
+end

data/win32-shortcut.gemspec

@@ -0,0 +1,23 @@
+require "rubygems"
+
+spec = Gem::Specification.new do |gem|
+   gem.name        = "win32-shortcut"
+   gem.version     = "0.2.0"
+   gem.author      = "Daniel J. Berger"
+   gem.email       = "djberg96@gmail.com"
+   gem.homepage    = "http://www.rubyforge.org/projects/win32utils"
+   gem.platform    = Gem::Platform::RUBY
+   gem.summary     = "An interface for creating or modifying Windows shortcuts."
+   gem.description = "An interface for creating or modifying Windows shortcuts."
+   gem.test_file   = "test/tc_shortcut.rb"
+   gem.has_rdoc    = true
+   gem.files       = Dir["lib/win32/*.rb"] + Dir["test/*"] + Dir["[A-Z]*"]
+   gem.files.reject! { |fn| fn.include? "CVS" }
+   gem.require_path = "lib"
+   gem.extra_rdoc_files = ["README", "CHANGES"]
+end
+
+if $0 == __FILE__
+   Gem.manage_gems
+   Gem::Builder.new(spec).build
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.9.0
+specification_version: 1
+name: win32-shortcut
+version: !ruby/object:Gem::Version 
+  version: 0.2.0
+date: 2006-10-30 00:00:00 -07:00
+summary: An interface for creating or modifying Windows shortcuts.
+require_paths: 
+- lib
+email: djberg96@gmail.com
+homepage: http://www.rubyforge.org/projects/win32utils
+rubyforge_project: 
+description: An interface for creating or modifying Windows shortcuts.
+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: 
+post_install_message: 
+authors: 
+- Daniel J. Berger
+files: 
+- lib/win32/shortcut.rb
+- test/tc_shortcut.rb
+- CHANGES
+- examples
+- install.rb
+- lib
+- MANIFEST
+- README
+- test
+- win32-shortcut.gemspec
+test_files: 
+- test/tc_shortcut.rb
+rdoc_options: []
+
+extra_rdoc_files: 
+- README
+- CHANGES
+executables: []
+
+extensions: []
+
+requirements: []
+
+dependencies: []
+