dialogbind 0.9.1 → 0.9.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c26d77179c387c148e245aaea10170e798a4b2dfa68e2813d99812b045f8683
-  data.tar.gz: f4a9a8ef1be6f577f335443215fc130b3b5a8424d96da8e685c8baa28abc909b
+  metadata.gz: 381f74289047af6aa93e6a28daeb6a1da99102c39dd098b3d6c384bf94dbc520
+  data.tar.gz: a006ae717ed3253bb8fb623550ef691c1bfb69af5c9c877249a0466e5b816a51
 SHA512:
-  metadata.gz: ccf3e2f001e744556469cbfdf5bb209594ce6239647153b2e2274f74e441c56700e6585aefbcd18cdfd5007602f433b82710b015247fcd7d3b8cd2f1bd8a218d
-  data.tar.gz: bca641aa1a374afd1fc484db342f456cfc215e670373f924b65e37adc784a6e13459f6164c569bfd94b07b5de1e559d3f10bc132e33b173e9384f93a55e08802
+  metadata.gz: '089eacd34517bcead4fc0716cb074849f49219a5f0d475a1a06d1b28eb2f1abbfd42d24a7429c675b7b7be821c083403fab66ca71646f3f3e09067abdbe5301b'
+  data.tar.gz: f30f98c3d6b179526d85aa4d9a30f93c4fc0932c793565b94c9863e174e044a2ffb9ad405ff42a04b0ee517255896095d955e301f59c16c75a2beaf68e4afe75

data/lib/dialogbind.rb

@@ -5,9 +5,12 @@
 # Copyright (C) Tim K 2018-2019 <timprogrammer@rambler.ru>.
 # Licensed under MIT License.
 
+require 'fiddle/import'
+
 $dialogbind_macos_script_cmd = ''
-$dialogbind_version = '0.9.1'
+$dialogbind_version = '0.9.1.1'
 
+# Function used internally in DialogBind to run Zenity from Ruby code. Please do not use this function directly as its API and behaviour might change in any release.
 def zenity(arg)
 	args_total = ''
 	arg.keys.each do |key|
@@ -30,6 +33,26 @@ def zenity(arg)
 	return system('zenity ' + args_total)
 end
 
+# Internal module binding Win32 API MessageBox to Ruby. While it can be used directly, it is not recommended to do so to maintain your app's portability.
+module Win32NativeMessageBox
+	# based on https://gist.github.com/Youka/3ebbdfd03454afa7d0c4
+	extend Fiddle::Importer
+
+	dlload 'user32'
+	typealias 'HANDLE', 'void*'
+	typealias 'HWND', 'HANDLE'
+	typealias 'LPCSTR', 'const char*'
+	typealias 'UINT', 'unsigned int'
+
+	extern 'int MessageBoxA(HWND, LPCSTR, LPCSTR, UINT)'
+end
+
+# Function used internally in DialogBind to run Win32 MessageBoxA from Ruby code. Please do not use this function directly as its API and behaviour might change in any release.
+def win32_msgbox(text, title='DialogBind', buttons=0)
+	return Win32NativeMessageBox::MessageBoxA(nil, text, title, buttons)	
+end
+
+# Function used internally in DialogBind to run XMessage from Ruby code. Please do not use this function directly as its API and behaviour might change in any release.
 def xmessage(arg, buttons={ 'OK' => 0 }, file=false)
 	build_cmd = 'xmessage -center -buttons "'
 	first = true
@@ -49,6 +72,7 @@ def xmessage(arg, buttons={ 'OK' => 0 }, file=false)
 	return system(build_cmd)
 end
 
+# Function used internally in DialogBind to run AppleScript ``display dialog`` from Ruby code. Please do not use this function directly as its API and behaviour might change in any release.
 def macdialog(text, buttons=['OK'], type='dialog', error=false, dryrun=false)
 	text_fixed = text.gsub("!", "").gsub("'", '').gsub('"', '').gsub('$', '')
 	cmd = "osascript -e 'tell app \"System Events\" to display " + type + ' "' + text_fixed + '"'
@@ -68,11 +92,13 @@ def macdialog(text, buttons=['OK'], type='dialog', error=false, dryrun=false)
 	return false
 end
 
-$dialogbind_available_backends = [ 'xmessage', 'zenity', 'macos' ]
+$dialogbind_available_backends = [ 'xmessage', 'zenity', 'macos', 'win32' ]
 $dialogbind_dialog_backend = 'xmessage'
 
 if system('command -v zenity > /dev/null 2>&1') then
 	$dialogbind_dialog_backend = 'zenity'
+elsif ENV.keys.include?('OS') && ENV['OS'] == 'Windows_NT' then
+	$dialogbind_dialog_backend = 'win32'
 elsif `uname`.gsub("\n", "") == 'Darwin' then
 	$dialogbind_dialog_backend = 'macos'
 end
@@ -84,6 +110,11 @@ if $dialogbind_available_backends.include?($dialogbind_dialog_backend) == false
 	raise 'Dialog backend "' + $dialogbind_dialog_backend + '" is not available. Available frontends: ' + $dialogbind_available_backends.join(', ')
 end
 
+# Shows a simple message box (or information message box when using Zenity backend).
+#
+# @param text [String] the text that should be displayed in a message box
+# @param title [String] an optional parameter specifying the title of the message box. Ignored on macOS.
+# @return [Boolean] true on success, false if something went wrong
 def guiputs(text, title='DialogBind')
 	if $dialogbind_dialog_backend == 'xmessage' then
 		return xmessage(text, { 'OK' => 0 })
@@ -91,6 +122,9 @@ def guiputs(text, title='DialogBind')
 		return zenity({ 'info' => nil, 'title' => title, 'text' => text })
 	elsif $dialogbind_dialog_backend == 'macos' then
 		return macdialog(text)
+	elsif $dialogbind_dialog_backend == 'win32' then
+		win32_msgbox(text, title, 0)
+		return true
 	else
 		puts title + ': ' + text
 		return true
@@ -98,6 +132,11 @@ def guiputs(text, title='DialogBind')
 	return false
 end
 
+# Shows a question message box with "Yes" and "No" buttons.
+#
+# @param text [String] the text that should be displayed in a message box
+# @param title [String] an optional parameter specifying the title of the message box. Ignored on macOS.
+# @return [Boolean] true if the user presses yes, false if the user pressed no
 def guiyesno(text, title='DialogBind')
 	if $dialogbind_dialog_backend == 'xmessage' then
 		return xmessage(text, { 'Yes' => 0, 'No' => 1})
@@ -112,12 +151,20 @@ def guiyesno(text, title='DialogBind')
 		if output.split(':')[1].downcase == 'yes' then
 			return true
 		end
+	elsif $dialogbind_dialog_backend == 'win32' then
+		retv_msgbox = win32_msgbox(text, title, 4)
+		return (retv_msgbox == 6)
 	else
 		raise 'The selected backend does not support question message boxes.'
 	end
 	return false
 end
 
+# Shows an error message box with only single OK button.
+#
+# @param text [String] the text that should be displayed in a message box
+# @param title [String] an optional parameter specifying the title of the message box. Ignored on macOS.
+# @return [Boolean] true on success, false if something went wrong
 def guierror(text, title='DialogBind')
 	if $dialogbind_dialog_backend == 'xmessage' then
 		return xmessage('ERROR. ' + text, { 'OK' => 0 })
@@ -125,12 +172,20 @@ def guierror(text, title='DialogBind')
 		return zenity('error' => nil, 'title' => title, 'text' => text)
 	elsif $dialogbind_dialog_backend == 'macos' then
 		return macdialog(text, [ 'OK' ], 'dialog', true)
+	elsif $dialogbind_dialog_backend == 'win32' then
+		return win32_msgbox('Error. ' + text, title, 0)
 	else
 		raise 'The selected backend does not support question message boxes.'
 	end
 	return false
 end
 
+# Shows either a buttonless message box with the specified text or a progress message box with the specified text. Does not work on Windows.
+# This function is not async, just like all other functions, so you should actually start it in a seperate thread.
+#
+# @param text [String] the text that should be displayed in a message box
+# @param title [String] an optional parameter specifying the title of the message box. Ignored on macOS.
+# @return [Boolean] true on success, false if something went wrong
 def guiprogress(text='Please wait...', title='DialogBind')
 	if $dialogbind_dialog_backend == 'xmessage' then
 		return xmessage(text, { })
@@ -145,6 +200,11 @@ def guiprogress(text='Please wait...', title='DialogBind')
 	return false
 end
 
+# Shows a message box containing the license agreement that is stored in the specified file.
+#
+# @param file [String] the file that contains the licensing terms
+# @param title [String] an optional parameter specifying the title of the message box. Ignored on macOS.
+# @return [Boolean] true if the user accepts the terms of the license agreement or false if not
 def guilicense(file, title='DialogBind')
 	if File.exists?(file) == false then
 		guierror('File "' + file + '" does not exist.', title)
@@ -154,6 +214,13 @@ def guilicense(file, title='DialogBind')
 		return xmessage(file, { 'Accept' => 0, 'Decline' => 1 }, true)
 	elsif $dialogbind_dialog_backend == 'zenity' then
 		return zenity({ 'text-info' => nil, 'title' => title, 'filename' => file, 'checkbox' => 'I have read and accepted the terms of the license agreement.' })
+	elsif $dialogbind_dialog_backend == 'macos' then
+		macdialog('Right now, the license agreement will be shown in TextEdit. Close TextEdit using Command-Q to continue,', ['OK'])
+		system('open -e "' + file.gsub('"', "\\\"") + '"')
+		return guiyesno('Do you accept the terms of the license agreement?', title)
+	elsif $dialogbind_dialog_backend == 'win32' then
+		retv_msgbox = win32_msgbox("Do you accept the terms of the license agreement below?\n\n" + File.read(file), title, 4)
+		return (retv_msgbox == 6)
 	else
 		raise 'The selected backend does not support license message boxes.'
 		return false
@@ -171,6 +238,12 @@ def entry2buttonshash(entries)
 	return hash
 end
 
+# Shows either a message box with buttons matching the items specified in the array ``entries`` or a list message box.
+#
+# @param entries [Array] an array of strings that should be displayed as list in a message box. More than two items are currently not supported.
+# @param text [String] the text that should be displayed in a message box
+# @param title [String] an optional parameter specifying the title of the message box. Ignored on macOS.
+# @return [String] the selected string or nil on cancel
 def guiselect(entries, text='Choose one of the items below:', title='DialogBind')
 	if entries.length > 2 then
 		raise 'More than 2 entries for guiselect are not supported by xmessage.'
@@ -199,6 +272,9 @@ def guiselect(entries, text='Choose one of the items below:', title='DialogBind'
 			return nil
 		end
 		return output.split(':')[1]
+	else
+		raise 'The selected backend does not support license message boxes.'
+		return false
 	end
 	return nil
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dialogbind
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 0.9.1.1
 platform: ruby
 authors:
 - Tim K
@@ -41,5 +41,6 @@ rubygems_version: 3.0.4
 signing_key: 
 specification_version: 4
 summary: DialogBind provides a Ruby API that wraps around Linux and macOS message
-  box-generating tools.
+  box-generating tools. As of version 0.9.2, Windows is also (partially) supported.
+  See https://gitlab.com/timkoi/dialogbind/blob/master/README.md for documentation.
 test_files: []