module Dialog::KDialog
Public Instance Methods
Present a set of checkboxes to the user
Using this method may be easier than using selection
, as you don’t need to indicate you want checkboxes.
@macro choiceparam @macro labelparam @!macro [new] defaultparam
@param default [Array<String> String] The name of the attribute to be pre-selected for the user, or a list of such names, in the case of checkboxes. If not provided, the attribute's value is tested, and if true, is selected.
@example Using a Struct for checkboxes
Foodselection = Struct.new(:salad, :soup, :sandwich, :cookie, :drink) choices = Foodselection.new(false, false, true, false, true) # sandwich and drink preselected checkboxes(choices, label: "What would you like for lunch?")
@macro runreturn
# File lib/dialog/kdialog.rb, line 178 def checkboxes(choices, label: "", default: nil) selection(choices, label: label, type: :check, default: default) end
Color Picker
@return [Array<Integer> nil] An array of [red, green, blue] 8-bit color components, or nil if ‘cancel’ pressed.
# File lib/dialog/kdialog.rb, line 307 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
A dropdown box
This is similar to a radio button selection; only one selection can be made.
@macro choiceparam @macro labelparam
# File lib/dialog/kdialog.rb, line 153 def combobox(choices, label: "") cmd = ["--combobox", label] + choices.members.map {|k| k.to_s} run(cmd) {|sel| selected = (sel + '=').to_sym (choices.members - [selected]).each {|c| choices.send((c.to_s + '=').to_sym, false)} choices.send(selected, true) } end
Standard dialog boxes
The valid combinations of boolean parameters specifying the type of buttons available are as follows:
- cols=“4”
-
|=== |YesNo |Cancel |Warning |Continue
| true | true | true | false
| true | true | false | false
| true | false | false | false
| true | false | true | false
| false | true | true | true |===
@param text [String] The text presented to the user above buttons. @param yesno [Boolean] If true, show “Yes” and “No” buttons. @param cancel [Boolean] If true, show a “Cancel” button. @param continue_btn [Boolean] If true, show a “Continue” button. @param warning [Boolean] If true, the icon shown is a warning icon, not a standard question icon @yield [] If the user makes a positive selection (yes or continue), the given
block is called. If not, the block is ignored.
# File lib/dialog/kdialog.rb, line 51 def dialogbox(text, yesno: true, cancel: false, continue_btn: false, warning: false) valid_dialogs = {"warningyesnocancel" => true, "yesnocancel" => true, "yesno" => true, "warningyesno" => true, "warningcontinuecancel" => true} cmd = "" cmd += "warning" if warning == true cmd += "yesno" if yesno == true cmd += "continue" if continue_btn == true cmd += "cancel" if cancel == true unless valid_dialogs.has_key?(cmd) raise "Can't make that kind of dialog box" end cmd = "--#{cmd}" out, status = *run([cmd, text]) if block_given? and status == true yield() end end
Present a file-picker box, for getting filenames or URLs from the user, for saving or opening.
@param action [Symbol] One of :save or :open @param type [Symbol] One of :url, :file, or :directory, indicating what kind of input is expected from the user @param dir [String] Directory to start the UI in, defaults to ENV @param multiple [Boolean] If true, allow the user to select multiple files. Only works when action is :open. @param filter [String] A description of what types of files should be displayed in directory listings @yieldparam path [Array<String> String] The path (or paths) selected by the user @return [Array<String> String] The path (or paths) selected by the user @todo Figure out what kinds of strings are expected of the filter parameter, write code to validate
# File lib/dialog/kdialog.rb, line 257 def filepicker(action: :save, type: :file, dir: ENV['HOME'], multiple: false, filter: nil, &blk) cmd = ["--separate-output"] cmd << "--multiple" if (multiple and action == :open) cmd << case [action, type] when [:save, :file] "--getsavefilename" when [:save, :url] "--getsaveurl" when [:open, :file] "--getopenfilename" when [:open, :url] "--getopenurl" else if type == :directory "--getexistingdirectory" end end cmd << dir cmd << filter unless (type == :directory or filter.nil?) if block_given? run(cmd) do |input| if multiple param = input.split(/\n/) else param = input end yield(param) end else input, status = run(cmd) if multiple input.split(/\n/) else input end end end
Icon Picker
Allows the user to choose an icon among those available to KDE.
@macro runreturn
# File lib/dialog/kdialog.rb, line 300 def icon() run(["--geticon", "--help"]) end
Present an input box. It may be a one-line field, a password field, or a larger text-entry area potentially with scrollbars.
@param prompt [String] The text to prompt the user, above the input fields @param content [String] The initial value in the input box @param height [Integer] The height of the input field. If 1, presents a single-line input field.
If larger, presents a text box that can potentially scroll vertically and horizontally. Defaults to 1
@param width [Integer] The width of the input field. Note that this does not limit the amount of text
the user may return, only how much can be seen on the screen at once.
@param password [Boolean] When true, use a ‘key’ icon and only show dots in place of input characters.
When this is true, the height parameter is required to be 1, otherwise this option has no effect.
@yieldparam input [String] the text provided by the user @macro runreturn
# File lib/dialog/kdialog.rb, line 118 def inputbox(prompt: "Input some text", content: nil, height: 1, width: 40, password: false, &blk) if height == 1 if password == true cmd = ["--password"] else cmd = ["--inputbox"] end elsif height > 1 cmd = ["--textinputbox"] end cmd << prompt if password == false cmd << content if content if height > 1 cmd += ["--height", height] end cmd += ["--width", 40] end run(cmd, &blk) end
A message box, for displaying a little text to the user.
For longer, multi-line text, you may prefer to use textbox
. Contrasting with the standard dialog boxes, the button presented to the user
only has the effect of closing the box.
@param type [:msgbox :sorry :error] The type of message box, affects the choice of icon shown in the box @!macro [new] runreturn
@return [Array<(String, Boolean)>] the textual output of running kdialog, and whether it exited successfully
# File lib/dialog/kdialog.rb, line 78 def messagebox(text, type: :msgbox) unless {:msgbox => 1, :sorry => 1, :error => 1}.has_key?(type) raise "Can't make that kind of message box" end cmdtype = "--#{type}" run([cmdtype, text]) end
Raise a notification for the user. This doesn’t bring up a window that takes focus, just a little box (usually above the taskbar) in the notification area that goes away by itself.
@param text [String] The text to show in the notification @param timeout [Integer] The number of seconds to show the notification for
# File lib/dialog/kdialog.rb, line 243 def notification(text, timeout: 3) run(["--passivepopup", text, timeout.to_s]) end
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
# File lib/dialog/kdialog.rb, line 420 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+/) ProgressBar.new(servicename, path, label: label, autoclose: autoclose, &blk) end
@api private @param arglist [Array<String>] List of command-line arguments for kdialog @raise [StandardError] Any exception raised by Open3#capture2 @yieldparam output [String] The output of running kdialog @macro runreturn
# File lib/dialog/kdialog.rb, line 434 def run(arglist, &blk) cmd = ["kdialog"] + arglist output, code = Open3.capture2(*cmd) status = case code.exitstatus when 0 then true when 1 then false else false end if block_given? and status == true yield(output.chomp) end return output.chomp, status end
Implementation of radiobuttons and checkboxes; user selections.
@macro choiceparam @macro labelparam @macro defaultparam @param type [Symbol] Either :check (for checkboxes, multiple selections allowed) or :radio, (for
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.
# File lib/dialog/kdialog.rb, line 207 def selection(choices, label: "", type: :check, default: nil) cmd = ["--separate-output"] cmd << case type when :check "--checklist" when :radio "--radiolist" else raise UnknownSelectionType, "Unknown selection type", caller end cmd << label choices.members.each_with_index {|c, i| if ((default.nil? and choices.send(c)) or (default == c) or (default.include?(c))) cmd += [i.to_s, c.to_s, 'on'] else cmd += [i.to_s, c.to_s, 'off'] end } run(cmd) do |sel| selected = sel.each_line.map{|l| l.chomp.to_i} choices.members.each.with_index do |box, i| method = (box.to_s + '=').to_sym if selected.include?(i) choices.send(method, true) else choices.send(method, false) end end end end
A window for showing the user a large amount of text, potentially using horizontal and vertical scrollbars. For small amounts of text, use messagebox
@param text [String IO] The text to send to the user, or a readable IO object. @param height [Integer] The height of the textbox area, defaults to 10 @param width [Integer] The width of the textbox area, defaults to 40 @macro runreturn
# File lib/dialog/kdialog.rb, line 93 def textbox(text, height: 10, width: 40) Tempfile.open('dialogfu') do |tf| if text.respond_to?(:read) tf.print(text.read) else tf.print(text) end tf.close run(["--textbox", path, "--height", height, "--width", width]) tf.unlink end end