Class: Win32::Shortcut

Inherits:
Object
  • Object
show all
Defined in:
lib/win32/shortcut.rb

Overview

The Shortcut class encapsulates an MS Windows shortcut.

Constant Summary collapse

VERSION =

The version of this library

'0.2.2'
SHOWNORMAL =

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.

1
SHOWMAXIMIZED =

Activates the window and displays it as a maximized window.

3
SHOWMINNOACTIVE =

Displays the window in its minimized state, leaving the currently active window as active.

7

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(file) ⇒ Shortcut

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.

Examples:

# Create a shortcut called 'test' to a file in non-block form.
s = Shortcut.new('test.lnk')
s.target_path = 'C:/Documents and Settings/john/some_file.txt'
s.save

# Create a shortcut called 'test2' to a folder in block form.
Shortcut.new('test2.lnk') do |sc|
   sc.target_path = 'C:/Documents and Settings/john/some_dir'
end



42
43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/win32/shortcut.rb', line 42

def initialize(file)
   @file  = file.tr('/', "\\")
   @shell = WIN32OLE.new('WScript.Shell')
   @link  = @shell.CreateShortcut(@file)
   
   if block_given?
      begin
         yield self
      ensure
         save
      end
   end
end

Class Method Details

.open(file) ⇒ Object

Identical to Shortcut#new except that it will raise an ArgumentError unless the file already exists.

Raises:

  • (ArgumentError) 


59
60
61
62
 
# File 'lib/win32/shortcut.rb', line 59

def self.open(file)
   raise ArgumentError, 'shortcut not found' unless File.exists?(file)
   self.new(file)
end

Instance Method Details

#arguments ⇒ Object

Returns any arguments (i.e. command line options) for the shortcut.



66
67
68
 
# File 'lib/win32/shortcut.rb', line 66

def arguments
   @link.Arguments
end

#arguments=(args) ⇒ Object

Sets the arguments (i.e. command line options) for the shortcut.



72
73
74
 
# File 'lib/win32/shortcut.rb', line 72

def arguments=(args)
   @link.Arguments = args
end

#description ⇒ Object

Returns the description (i.e. comment) for the shortcut.



78
79
80
 
# File 'lib/win32/shortcut.rb', line 78

def description
   @link.Description
end

#description=(desc) ⇒ Object

Sets the description for the shortcut.



84
85
86
 
# File 'lib/win32/shortcut.rb', line 84

def description=(desc)
   @link.Description = desc
end

#file ⇒ Object

Returns the file name of the shortcut.



90
91
92
 
# File 'lib/win32/shortcut.rb', line 90

def file
   @file
end

#hotkey ⇒ Object

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.



99
100
101
 
# File 'lib/win32/shortcut.rb', line 99

def hotkey
   @link.HotKey
end

#hotkey=(key) ⇒ Object

Sets the hotkey for the shortcut.



105
106
107
 
# File 'lib/win32/shortcut.rb', line 105

def hotkey=(key)
   @link.HotKey = key
end

#icon_location ⇒ Object

Returns the name of the file that contain the icon for the shortcut. In practice this is almost always blank. YMMV.



112
113
114
 
# File 'lib/win32/shortcut.rb', line 112

def icon_location
   @link.IconLocation
end

#icon_location=(location) ⇒ Object

Sets the name of the icon file to be used for the shortcut.



118
119
120
 
# File 'lib/win32/shortcut.rb', line 118

def icon_location=(location)
   @link.IconLocation = location.tr('/', "\\")
end

#path ⇒ Object Also known as: target_path

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.



126
127
128
 
# File 'lib/win32/shortcut.rb', line 126

def path
   @link.TargetPath
end

#path=(link_path) ⇒ Object Also known as: target_path=

Sets the target of the shortcut. – Forward slashes are converted to backslashes to ensure folder shortcuts work properly.



137
138
139
 
# File 'lib/win32/shortcut.rb', line 137

def path=(link_path)
   @link.TargetPath = link_path.tr('/', "\\")
end

#resolve ⇒ Object

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.



150
151
152
 
# File 'lib/win32/shortcut.rb', line 150

def resolve
   @link.FullName
end

#save ⇒ Object

Saves (creates) the link object in the current directory.



222
223
224
 
# File 'lib/win32/shortcut.rb', line 222

def save
   @link.Save
end

#window_style ⇒ Object Also known as: show_cmd

Returns the type of window style used by a shortcut. The possible return values are ‘normal’, ‘maximized’, or ‘minimized’.



157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/win32/shortcut.rb', line 157

def window_style
   case @link.WindowStyle
      when SHOWNORMAL
         'normal'
      when SHOWMAXIMIZED
         'maximized'
      when SHOWMINNOACTIVE
         'minimized'
      else
         'unknown' # Should never reach here
   end
end

#window_style=(style) ⇒ Object Also known as: show_cmd=

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.



182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
 
# File 'lib/win32/shortcut.rb', line 182

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

#working_directory ⇒ Object

Returns directory in which the targeted program will be executed. Correspond to the “Start in” field of a Shortcut Properties Dialog Box.



210
211
212
 
# File 'lib/win32/shortcut.rb', line 210

def working_directory
   @link.WorkingDirectory
end

#working_directory=(directory) ⇒ Object

Sets the directory in which the targeted program will be executed.



216
217
218
 
# File 'lib/win32/shortcut.rb', line 216

def working_directory=(directory)
   @link.WorkingDirectory = directory.tr('/', "\\")
end