Module: XDo::Clipboard

Defined in:
lib/xdo/clipboard.rb

Overview

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]+ 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…

Class Method Summary collapse

Class Method Details

.append(text, *to) ⇒ Object

Appends text to a X clipboard.

Parameters

text

The text to append.

*to

(:clipboard) 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).



152
153
154
155
156
157
158
159
160
161
162
 
# File 'lib/xdo/clipboard.rb', line 152

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

.clear(*clips) ⇒ Object

Clears the specified clipboards.

Parameters

*clips

(:primary, :clipboard, :secondary) 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



177
178
179
180
181
182
183
184
185
186
187
188
 
# File 'lib/xdo/clipboard.rb', line 177

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

.read(*from) ⇒ Object

Reads text from a X clipboard.

Parameters

*from

(:clipboard, :primary, :secondary) Specifies from which clipboards you want to read (in 70% of all cases you want to read from :clipboard).

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 :clipboard, :primary and :secondary. 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.



97
98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/xdo/clipboard.rb', line 97

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

.write(text, *to) ⇒ Object

Writes text to a X clipboard.

Parameters

*to

(:clipboard) 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.



123
124
125
126
127
128
129
130
131
132
133
134
 
# File 'lib/xdo/clipboard.rb', line 123

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