dialog-fu 0.2 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 546f459f27e812bb284a2afeda60a26995655286
-  data.tar.gz: b7398666b2b26e12512143fec0afe4c5ae1526b1
+  metadata.gz: 8f4a4746fb273f26058ff24e4ea211b81e4483e4
+  data.tar.gz: db6d274a13467edfdfbf5c692a56db19411a1bd6
 SHA512:
-  metadata.gz: 98327730998009bf20e0302ed6dccba9c7ae3849f64e234fab4024dcd88ea878c8f51fd4cadaf4c6781a17540bddb81b0c6458c93ab9c2bb926cebd650204f62
-  data.tar.gz: c94b88165cef7049f2a5d1bc618271b4cb83f5d0a05391db06d4738ff9ffa1b4f6a3d74629af8faff6fb57acb6261ce852c81f1e6407e688595e5c182572d5c7
+  metadata.gz: a7fd7dd5fd3017d89b9665b480f1f04500190af2653599b58bb818f4cdb60bf1d4e9c16fbae281cc967593646a3709b2e6cdbfcb2fca926c2b5392b2bd2c4258
+  data.tar.gz: cbcd2863b35591459157e7f18b7ee77a88cc81ea05ced036a04126c44791d7597c2b443809a1d17fad718632c20124636c6b3a923ebc8a69463170cf80bd6ed1

data/README.adoc

@@ -2,7 +2,7 @@
 Chris Riddoch <riddochc@gmail.com>
 :language: ruby
 
-Version 0.2, 2014-06-27
+Version 0.2.1, 2014-07-07
 
 == Description
 

data/lib/dialog.rb

@@ -1,5 +1,5 @@
 module Dialog
-  VERSION='0.2'
+  VERSION='0.2.1'
 end
 
 require_relative "dialog/dialog"

data/lib/dialog/kdialog.rb

@@ -1,5 +1,6 @@
 require 'open3'
 require 'tempfile'
+require 'dbus'
 
 module Dialog::KDialog
 
@@ -192,6 +193,8 @@ module Dialog::KDialog
     selection(choices, label: label, type: :radio, default: default)
   end
 
+  # Implementation of radiobuttons and checkboxes; user selections.
+  #
   # @macro choiceparam
   # @macro labelparam
   # @macro defaultparam
@@ -199,7 +202,6 @@ module Dialog::KDialog
   #   radio buttons, only one selection)
   # @raise UnknownSelectionType If type is something other than :check or :radio
   # @macro runreturn
-  #
   # @note If +type+ is +:radio+, it's the caller's responsibility to either specify a default,
   #   or make sure only one of the 'choices' attributes is true in the +choices+ parameter.
   def selection(choices, label: "", type: :check, default: nil)
@@ -290,37 +292,138 @@ module Dialog::KDialog
     end
   end
 
-  # @todo Implement
-  # Known groups for iconloader (on my system, anyway):
+  # Icon Picker
+  #
+  # Allows the user to choose an icon among those available to KDE.
   #
-  # * Desktop, Toolbar, MainToolbar, Small, Panel, Dialog, User, Action, Application, Device, FileSystem, MimeType, Animation, Category, Emblem, Emote, International, Place, StatusIcon
-  # * From KDE3: Devices, MimeTypes, Applications, Actions
+  # @macro runreturn
   def icon()
+    run(["--geticon", "--help"])
+  end
+
+  # Color Picker
+  #
+  # @return [Array<Integer> nil] An array of [red, green, blue] 8-bit color components, or nil if 'cancel' pressed.
+  def color()
+    c = nil
+    run(["--getcolor"]) {|out|
+      c = [out[1,2].to_i(16),
+       out[3,2].to_i(16),
+       out[5,2].to_i(16)]
+    }
+    c
+  end
+
+  # Wraps the ruby-dbus interface to connect to and control a KDE ProgressDialog object.
+  # An instance of this object is easily created by the {Dialog::KDialog#progressbar} method, don't try to create it yourself.
+  class ProgressBar
+    # @param servicename [String] The dbus service to connect to, provided by kdialog's output
+    # @param path [String] The path to the progress bar, provided by kdialog's output
+    # @!macro [new] pgargs
+    #   @param show_cancel [Boolean] If true, display a cancel button for the user to request early stop of work
+    #   @param label [String] Text to display above the progress bar, typically providing information about current activity
+    #   @param autoclose [Boolean] If true, the window will close when the progress is set to the highest value
+    #   @yieldparam bar [ProgressBar] An object for manipulating state of the progress bar, ensures proper closing at block exit
+    def initialize(servicename, path, show_cancel: false, label: "Working...", autoclose: true)
+      bus = DBus::SessionBus.instance
+      service = bus.service(servicename)
+      dbusobj =  service.object(path)
+      dbusobj.introspect
+      @progress = dbusobj["org.kde.kdialog.ProgressDialog"]
+      #@progress["maximum"] = max
+      @progress["autoClose"] = autoclose
+      @progress.setLabelText(label)
+      if block_given?
+        begin
+          yield(self)
+        ensure
+          self.close()
+        end
+      end
+      self
+    end
+
+    # If the option to show a cancel button is available, has it been pressed?
+    # @return [Boolean]
+    def canceled?
+      @progress.wasCancelled.first
+    end
+    alias cancelled? canceled?
+
+    # Get the current value of the progress bar
+    # @return [Integer]
+    def value()
+      @progress["value"].to_i
+    end
+
+    # Set the current value of the progress bar. The percentage shown is (n / max)
+    # Values outside the range of 0..max will be ignored.
+    #
+    # @param n [Integer] Number to set it to
+    # @return [ProgressBar] self, for method chaining
+    def value=(n)
+      @progress["value"] = n
+      self
+    end
+
+    # Increments the progress bar by one step
+    # @return [ProgressBar] self, for method chaining
+    def succ
+      begin
+        @progress["value"] += 1
+      rescue DBus::Error
+        # This could happen...
+      end
+      self
+    end
+
+    # @return [Integer] The maximum value the progress bar go up to.
+    def max()
+      @progress["maximum"]
+    end
+
+    # Sets the maximum value the progress bar can go up to
+    # 
+    # @param n [Integer] Number to set it to
+    # @return [ProgressBar] self, for method chaining
+    def max=(n)
+      @progress["maximum"] = n
+      self
+    end
+
+    # Change the text of the label above the progress bar
+    # @param text [String] New text for label
+    # @return [ProgressBar] self, for method chaining
+    def label(text)
+      @progress.setLabelText(text)
+      self
+    end
+
+    # Close the progress bar
+    # @return [Boolean] true
+    def close()
+      begin
+        @progress.close
+      rescue DBus::Error
+        # Already closed, no worries.
+      end
+      true
+    end
   end
 
-  # @todo Design and implement API for using progressbar
-  def progressbar()
-    require 'dbus' unless DBus
-    steps = 10
-    out, status = Open3.capture2("kdialog", "--progressbar", "Titlebar Text", steps.to_s)
+  # Present a progress bar to the user; returns an object to control its desplay
+  #
+  # @param steps [Integer] Number of increments in the progress bar.
+  # @param title [String] Text to display in the titlebar of the window
+  # @macro pbargs
+  # @return [ProgressBar] An object for manipulating state of the progress bar 
+  def progressbar(steps: 100, title: "Progress Bar", show_cancel: false, label: "Working...", autoclose: true, &blk)
+    out, status = Open3.capture2("kdialog", "--progressbar", title, steps.to_s)
     if status != 0
       raise "kdialog exited unexpectedly"
     end
     servicename, path = *out.split(/\s+/)
-
-    bus = DBus::SessionBus.instance
-    dialogservice = bus.service(servicename)
-    dialogobj =  dialogservice.object(path)
-    d = dialogobj["org.kde.kdialog.ProgressDialog"]
-
-    d.showCancelButton(true) # or false...
-    r = d.wasCancelled
-    r.first # the boolean.  Why it's in an array? Dunno.
-    d["maximum"] # => 10
-    d["autoClose"] # => false, by default
-    d.setLabelText("Test")
-    d["value"] # Can be assigned! Yay!  Ignored if out of range.
-    d.close # When done!
+    ProgressBar.new(servicename, path, label: label, autoclose: autoclose, &blk)
   end
 
   # @api private

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dialog-fu
 version: !ruby/object:Gem::Version
-  version: '0.2'
+  version: 0.2.1
 platform: ruby
 authors:
 - Chris Riddoch
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-06 00:00:00.000000000 Z
+date: 2014-07-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake