mrdialog 1.0.5 → 1.0.7

data/docs/README.md

@@ -0,0 +1,294 @@
+## Introduction
+
+`mrdialog` is a pure
+[ruby](https://www.ruby-lang.org/) library for the ncurses
+[dialog](http://invisible-island.net/dialog/dialog.html) program.
+[dialog](http://invisible-island.net/dialog/dialog.html) is
+a command line tool that can present questions, messages, forms using
+dialog boxes from a shell script on terminal. If you compiled linux kernel and typed 
+`make menuconfig`, configured Linux from command line with various 
+configuration managers, you have used 'dialog' like programs. Please
+have a lookt at the [screenshots](screenshots/) on the dialogs look 
+like.
+
+However, it is painful to program dialog from shell scripts due to lack of
+data structure. You constantly have to watch if the correct number of
+items are specified, if the arguments are in correct order for example. It is
+a lot of fun to program dialog from an object oriented scripting language like
+[ruby](https://www.ruby-lang.org/). Compare the sample shell scripts of dialog program with
+the sample ruby scripts of mrdialog in the [samples](samples/) directory, I think you will agree. Look at [samples/extra_button/](samples/extra_button/) directory for samples on using an extra button on various input dialogs.
+
+MRDialog is based on the rdialog ruby gem http://rdialog.rubyforge.org/ by
+Aleks Clark (Does not seem to exist anymore).
+
+I did the following:
+
+- Added features and support for all of the missing widgets.
+- Fixed the bugs I found.
+- Implemented the examples for all the widgets.
+
+If you have bug reports, questions, requests or suggestions, please enter it in the [Issues](https://github.com/muquit/mrdialog/issues) with an appropriate label.
+
+## Latest Version (1.0.7 - Oct-19-2025)
+
+The latest version is 1.0.7
+
+**Important fix in 1.0.7**: Fixed a parsing bug where dialog commands 
+would fail if any text contained apostrophes (single quotes). All special 
+characters in user input are now properly handled.
+
+Please look at the [ChangeLog.md](ChangeLog.md) file for details. Please look at the [screenshots](screenshots/) to see how the widgets look like.
+
+## To install
+
+```bash
+gem install mrdialog
+or
+sudo gem install mrdialog
+```
+
+## To uninstall
+
+```bash
+gem uninstall mrdialog
+or
+sudo gem uninstall mrdialog
+```
+
+
+## Screenshots
+
+Please look at the [screenshots](screenshots/) directory. There are individual screenshots for each of the widgets. Also the animated GIF file [all.gif](screenshots/all.gif) contains screenshot of all the widgets.
+
+## Requirements
+
+The [dialog](http://invisible-island.net/dialog/dialog.html) program must be installed. Note: the dialog program that is available in ubuntu is little old. Check the dialog version by typing `dialog --version`
+
+I tested with `Version: 1.3-20250116`
+
+dialog HOME: http://invisible-island.net/dialog/dialog.html.
+
+
+## Run the sample apps
+
+Find out where the mrdialog gem is installed. Example:
+```bash
+gem which mrdialog
+/Users/muquit/.rvm/gems/ruby-3.2.2/gems/mrdialog-1.0.7/lib/mrdialog.rb
+```
+
+
+`cd` to the `samples` directory and run the apps.
+Example:
+```bash
+cd /Users/muquit/.rvm/gems/ruby-3.2.2/gems/mrdialog-1.0.7/samples
+./msgbox.rb
+```
+
+Look at samples/extra_button/ on how to use an extra button on various input
+dialogs.
+
+## How to use the API
+
+For now, please look at the apps in [samples](samples/) directory to see how the API works.
+
+    require 'mrdialog'
+    dialog = MRDialog.new
+
+## Properties
+
+The various properties of the dialog (shadow, title etc.) can be set by calling the appropriate setters. The supported properties are shown below:
+
+| Property       | Example                                                                                                  | Description                                                                                                                                                            | Default           |
+| -------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
+| shadow         | `dialog.shadow = false`                                                                                  | Draw a shadow to the right and bottom of each dialog box.                                                                                                              | true              |
+| title          | `dialog.title = 'foo'`                                                                                   | Specifies a title string to be displayed at the top of the dialog box                                                                                                  | N/A               |
+| logger         | `dialog.logger = Logger.new("dialog.log")`                                                               | Debug messages will be logged to the specified ruby Logger                                                                                                             | N/A               |
+| clear          | `dialog.clear = true`                                                                                    | Clears the widget screen, keeping only the screen_color background.                                                                                                    | false             |
+| insecure       | `dialog.insecure = true`                                                                                 | Makes the password widget friendlier but less secure, by echoing asterisks for each character.                                                                         | false             |
+| ascii_lines    | `dialog.ascii_lines = true`                                                                              | Rather than draw graphics lines around boxes, draw ASCII "+" and "-" in the same place. See also "--no-lines".                                                         | false             |
+| rc_file        | `dialog.rc_file = "/path/to/rc/file"`                                                                    | Use the specified rc file.                                                                                                                                             | "$HOME/.dialogrc" |
+| yes_label      | `dialog.yes_label = "Sure"`                                                                              | Use the specified label on the "Yes" button.                                                                                                                           | "Yes"             |
+| no_label       | `dialog.no_label = "Nope"`                                                                               | Use the specified label on the "No" button.                                                                                                                            | "No"              |
+| cancel_label   | `dialog.cancel_label = "Forget"`                                                                         | Use the specified label on the "Cancel" button.                                                                                                                        | "Cancel"          |
+| help_button    | `dialog.help_button = true`                                                                              | Include a "Help" button on the dialog.                                                                                                                                 | false             |
+| help_label     | `dialog.help_label = "What?"`                                                                            | Use the specified label on the "Help" button.                                                                                                                          | "Help"            |
+| extra_button   | `dialog.extra_button = true`                                                                             | Include an "Extra" button on the dialog.                                                                                                                               | false             |
+| extra_label    | `dialog.extra_label = "More"`                                                                            | Use the specified label on the "Extra" button.                                                                                                                         | "Extra"           |
+| dialog_options | `dialog.dialog_options="any valid dialog option"` e.g. `dialog.dialog_options="--no-tags"` for checklist | Pass any valid dialog option. `man dialog` and look at the **OPTIONS** section. It is the caller's responsibility to specify correct options, no validation will be done | N/A               |
+
+## Widgets
+
+The following dialog widgets are supported:
+
+- buildlist
+- calendar
+- checklist
+- editbox
+- form
+- fselect
+- gauge
+- infobox
+- textbox
+- inputbox
+- menu
+- msgbox
+- passwordbox
+- passwordform
+- pause
+- prgbox
+- progressbox
+- programbox
+- radiolist
+- timebox
+- treeview
+- yesno
+
+### buildlist
+
+A buildlist dialog displays two lists, side-by-side. The list on the left shows unselected items. The list on the right shows selected items. As items are selected or unselected, they move between the lists. The SPACE bar is used to
+select or unselect an item.
+
+Use a carriage return or the "OK" button to accept the current value in the selected-window and exit. The results are written using the order displayed in the selected-window. The caller is responsible to create the items properly.
+
+returns an array of selected tags
+```bash
+result_array = dialog.buildlist(text="Text Goes Here", items, height=0, width=0, listheight=0)
+```
+- Please look at [buildlist.rb](samples/buildlist.rb) for an example.
+
+### calendar
+
+- Please look at [calendar.rb](samples/calendar.rb) for an example.
+
+### checklist
+
+- Please look at [checklist.rb](samples/checklist.rb) for an example.
+
+### editbox
+
+- Please look at [editbox.rb](samples/editbox.rb) for an example.
+
+### form
+
+- Please look at
+[form1.rb](samples/form1.rb), [form2.rb](samples/form2.rb), [form3.rb](samples/form3.rb)
+for examples.
+
+### fselect
+
+- Please look at [fselect.rb](samples/fselect.rb) for an example.
+
+### gauge
+
+- Please look at [gauge.rb](samples/gauge.rb) for an example.
+
+### infobox
+
+- Please look at [infobox.rb](samples/infobox.rb) for an example.
+
+### textbox
+- Please look at [textbox.rb](samples/textbox.rb) for an example.
+
+### inputbox
+
+- Please look at [inputbox.rb](samples/inputbox.rb) for an example.
+
+### menu
+
+- Please look at [menubox.rb](samples/menubox.rb) for an example.
+
+### msgbox
+
+- Please look at [msgbox.rb](samples/msgbox.rb) for an example.
+
+### passwordbox
+
+- Please look at [password.rb](samples/password.rb), [password2.rb](samples/password2.rb)
+for examples.
+
+### passwordform
+
+- Please look at [passwordform.rb](samples/passwordform.rb) for an example.
+
+### pause
+
+- Please look at [pause.rb](samples/pause.rb) for an example.
+
+### prgbox
+
+- Please look at [prgbox.rb](samples/prgbox.rb) for an example.
+
+### progressbox
+
+- Please look at [progressbox.rb](samples/progressbox.rb) for an example.
+
+### programbox
+
+- Please look at [programbox.rb](samples/programbox.rb) for an example.
+
+### radiolist
+
+- Please look at [radiolist.rb](samples/radiolist.rb) for an example.
+
+### timebox
+
+- Please look at [timebox.rb](samples/timebox.rb) for an example.
+
+### treeview
+
+- Please look at [treeview.rb](samples/treeview.rb) for an example.
+
+### yesno
+
+- Please look at [yesno.rb](samples/yesno.rb) for an example.
+
+## Dependencies
+
+Mrdialog does not have dependencies on any other gems. The gems in Gemfile are
+for development for building the gem.
+
+
+## For Developers
+
+Note: Pre-built `mrdialog-1.0.7.gem` is in the pkg directory
+
+If you need to build the gem yourself:
+
+Install bundler first:
+```bash
+gem install bundler
+bundle install
+```
+
+- To build: 
+```bash
+  rake clean
+  rake gemspec
+  rake build
+```
+
+Will create the gem inside the pkg directory
+
+- To install the built gem: 
+```bash
+sudo gem install --local pkg/mrdialog-1.0.7.gem
+```
+
+- To install using rake: 
+```bash
+sudo rake install
+```
+
+- To install the gem to a specific directory: 
+```bash
+    GEM_HOME=/tmp gem install --local pkg/mrdialog-1.0.7.gem`
+```
+
+The gem will be installed in `/tmp/gems` directory
+
+Please see the [Makefile](Makefile) for build and release commands
+
+## License
+
+License is MIT. Please look at the [LICENSE.txt](LICENSE.txt) file for details.