vedeu 0.4.45 → 0.4.46

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 68ee4c2ed644e698df332ae110ee488fcb38251c
-  data.tar.gz: 5a542609da0c161347ec2cd3de1fada895995aef
+  metadata.gz: ea321b7c3e36486983857a9d6ceeeecb333a17fd
+  data.tar.gz: 5e52ca03e9336ced28a58cc062d680f2dab4b0fc
 SHA512:
-  metadata.gz: 32a29cc71db5d5e1347b6fa9fe5a0d424c4bac02dedf1eb61e325650f386d01dcaee72c4fc890cd6eba16b50f10353ec2cda4a4f75064e156ae61be003217193
-  data.tar.gz: 42a71d09b9aa1dfed20b9b60f1dc92a1967fd134d2b27f3b028d3d59bd6070ec9eb8c5606b924ab4a8c3a26fd43d68c7f74085ef6a584bcf43fbb73b30d9bdfa
+  metadata.gz: f1097844c65d4242aa77ac45844005483b2a9f425a2e0a7469371c89126882a386c8cf708b96c42a8046762366249530aedbb19a7056132c0129f6ef824be583
+  data.tar.gz: 83dc5668eacf4c40b1384345ba34ef0ac2845be750be21d94b7480666239eeda748e619e767139d967e1506ec425f34b8e7a0840d3e52e07b330539a9b5cca05

data/.yardopts

@@ -5,6 +5,7 @@
 docs/api.md
 docs/applications.md
 docs/dsl.md
+docs/events.md
 docs/getting_started.md
 docs/object_graph.md
 docs/views.md

data/Guardfile

@@ -1,6 +1,6 @@
 guard :minitest, all_after_pass: true,
                  focus_on_failed: true,
-                 env: { 'no_simplecov' => true } do
+                 env: { 'NO_SIMPLECOV' => true } do
   watch(%r{^test/(.*)_test\.rb})
   watch(%r{^lib/(.+)\.rb}) { |m| "test/lib/#{m[1]}_test.rb" }
   watch(%r{^test/test_helper\.rb}) { 'test' }

data/docs/dsl.md

@@ -86,7 +86,7 @@ Geometry allows the configuration of the position and size of an interface.
 
 Here is an example of declarations for a `geometry` block:
 
- ```ruby
+```ruby
 interface 'main' do
   geometry do
     height 5 # Sets the height of the view to 5
@@ -104,7 +104,7 @@ available in the terminal will be used. `x` and `y` both default to 0.
 
 You can also make a geometry declaration dependent on another view:
 
- ```ruby
+```ruby
 interface 'other_panel' do
   # other code ...
 end
@@ -140,9 +140,9 @@ You can define keymaps by name which matches a defined interface. When that
 
 ### Menus
 
-
+`@todo` Documentation coming soon!
 
 ### Views
 
-
+@todo Documentation coming soon!
 

data/docs/events/drb.md

@@ -0,0 +1,49 @@
+# @title DRB Events
+
+## DRB Events
+
+### Start DRB Server
+
+    Vedeu.trigger(:_drb_start_)
+
+Use the DRb server to request the client application to start.
+
+
+### Restart DRB Server
+
+    Vedeu.trigger(:_drb_restart_)
+
+Use the DRb server to request the client application to restart.
+
+
+### Stop DRB Server
+
+    Vedeu.trigger(:_drb_stop_)
+
+Use the DRb server to request the client application to stop.
+
+
+### DRB Status
+
+    Vedeu.trigger(:_drb_status_)
+
+Use the DRb server to request the status of the client application.
+
+
+### Store Output of DRB Server
+
+    Vedeu.trigger(:_drb_store_output_, data)
+
+Triggering this event with 'data' will push data into the running application's virtual buffer.
+
+
+### Retrieve Output of DRB Server
+
+    Vedeu.trigger(:_drb_retrieve_output_)
+
+
+### Send Input to DRB Server
+
+    Vedeu.trigger(:_drb_input_, data, type)
+
+Triggering this event will send input to the running application as long as it has the DRb server running.

data/docs/events/main.md

@@ -0,0 +1,109 @@
+# @title Main Events
+
+## Main Events
+
+### Exiting Vedeu
+
+    `Vedeu.trigger(:_exit_)`
+
+When triggered, Vedeu will trigger a `:cleanup` event which you can define (to save files, etc) and attempt to exit. Also available as: `Vedeu.exit`.
+
+
+### Pressing a key
+
+    `Vedeu.trigger(:_keypress_, key)`
+
+Will cause the triggering of the `:key` event; which you should define to 'do things'. If the `escape` key is pressed, then `key` is triggered with the argument `:escape`, also an internal event `_mode_switch_` is triggered. Vedeu recognises most key presses and some 'extended' keypress (eg. Ctrl+J), a list of
+the supported keypresses can be found here: {Vedeu::Input#specials} and {Vedeu::Input#f_keys}.
+
+
+### Sending a command
+
+    `Vedeu.trigger(:_command_)`
+
+Will cause the triggering of the `:command` event; which you should define to 'do things'.
+
+
+### Logging to the log file
+
+    `Vedeu.trigger(:_log_, message)`
+
+When triggered with a message will cause Vedeu to log the message if logging is enabled in the configuration.
+
+
+### Focussing an interface by name
+
+    `Vedeu.trigger(:_focus_by_name_, name)`
+
+When triggered with an interface name will focus that interface and restore the cursor position and visibility.
+
+
+### Focussing the next visible interface
+
+    `Vedeu.trigger(:_focus_next_)`
+
+When triggered will focus the next interface and restore the cursor position and visibility.
+
+
+### Focussing the previous visible interface
+
+    `Vedeu.trigger(:_focus_prev_)`
+
+When triggered will focus the previous interface and restore the cursor position and visibility.
+
+
+### Clearing the terminal
+
+    `Vedeu.trigger(:_clear_)`
+
+Clears the whole terminal space, or the named interface area to be cleared if given. Also available as: `Vedeu.clear_by_name(name)`.
+
+
+### Refreshing all interfaces
+
+    `Vedeu.trigger(:_refresh_)`
+
+Will cause all interfaces to refresh. Note: Hidden interfaces will be still refreshed in memory but not shown.
+
+
+### Refresing an interface by name
+
+    `Vedeu.trigger(:_refresh_, name)`
+
+Will cause the named interface to refresh. Note: Hidden interfaces will be still refreshed in memory but not shown.
+
+
+### Refreshing the cursor
+
+    `Vedeu.trigger(:_refresh_cursor_, name)`
+
+Will cause the named cursor to refresh, or the cursor of the interface which is currently in focus.
+
+
+### Refreshing a group of interfaces
+
+    `Vedeu.trigger(:_refresh_group_, name)`
+
+Will cause all interfaces in the named group to refresh.
+
+
+### Clearing a group
+
+    `Vedeu.trigger(:_clear_group_, name)`
+
+Clears the spaces occupied by the interfaces belonging to the named group. Also available as: `Vedeu.clear_by_group(name)`
+
+
+### Maximising an interface
+
+    `Vedeu.trigger(:_maximise_, name)`
+
+See also: {Vedeu::Geometry#maximise}
+
+
+### Unmaximising an interface
+
+    `Vedeu.trigger(:_unmaximise_, name)`
+
+See also: {Vedeu::Geometry#unmaximise}
+

data/docs/events/menus.md

@@ -0,0 +1,72 @@
+# @title Menu Events
+
+## Menu Events
+
+### Bottom Item
+
+    Vedeu.trigger(:_menu_bottom_, name)
+
+Makes the last menu item the current menu item.
+
+
+### Current Item
+
+    Vedeu.trigger(:_menu_current_, name)
+
+Returns the current menu item.
+
+
+### Deselect All
+
+    Vedeu.trigger(:_menu_deselect_, name)
+
+Deselects all menu items.
+
+
+### All Items
+
+    Vedeu.trigger(:_menu_items_, name)
+
+Returns all the menu items with respective `current` or `selected` boolean indicators.
+
+
+### Next Item
+
+    Vedeu.trigger(:_menu_next_, name)
+
+Makes the next menu item the current menu item, until it reaches the last item.
+
+
+### Previous Item
+
+    Vedeu.trigger(:_menu_prev_, name)
+
+Makes the previous menu item the current menu item, until it reaches the first item.
+
+
+### Selected Item
+
+    Vedeu.trigger(:_menu_selected_, name)
+
+Returns the selected menu item.
+
+
+### Select Current Item
+
+    Vedeu.trigger(:_menu_select_, name)
+
+Makes the current menu item also the selected menu item.
+
+
+### Top Item
+
+    Vedeu.trigger(:_menu_top_, name)
+
+Makes the first menu item the current menu item.
+
+
+### View from ...
+
+    Vedeu.trigger(:_menu_view_, name)
+
+Returns a subset of the menu items; starting at the current item to the last item.

data/docs/events/movement.md

@@ -0,0 +1,105 @@
+# @title Movement Events
+
+## Movement Events
+
+### Moving the cursor
+
+We can move the cursor by name using the events listed below:
+
+#### Moving the cursor down
+
+    Vedeu.trigger(:_cursor_down_, name)
+
+See also: {Vedeu::Move}
+
+
+#### Moving the cursor left
+
+    Vedeu.trigger(:_cursor_left_, name)
+
+See also: {Vedeu::Move}
+
+
+#### Resetting the position of the cursor
+
+    Vedeu.trigger(:_cursor_origin_, name)
+    Vedeu.trigger(:_cursor_reset_, name)
+
+This event moves the cursor to the interface origin; the top left corner of the named interface. See also: {Vedeu::Move}
+
+
+#### Fetching the position of the cursor
+
+    Vedeu.trigger(:_cursor_position_, name)
+
+When triggered will return the current position of the cursor. See also: {Vedeu::Move}
+
+
+
+#### Moving the cursor to an arbitrary position
+
+    Vedeu.trigger(:_cursor_reposition_, name, y, x)
+
+Moves the cursor to a relative position inside the interface. See also: {Vedeu::Move}
+
+
+#### Moving the cursor right
+
+    Vedeu.trigger(:_cursor_right_, name)
+
+See also: {Vedeu::Move}
+
+
+#### Moving the cursor up
+
+    Vedeu.trigger(:_cursor_up_, name)
+
+See also: {Vedeu::Move}
+
+
+### Moving the interface
+
+We can move an interface by altering its geometry. This is performed using the events listed below:
+
+### Moving the interface down
+
+    Vedeu.trigger(:_geometry_down_, name)
+
+See also: {Vedeu::Move}
+
+
+### Moving the interface left
+
+    Vedeu.trigger(:_geometry_left_, name)
+
+See also: {Vedeu::Move}
+
+
+### Moving the interface right
+
+    Vedeu.trigger(:_geometry_right_, name)
+
+See also: {Vedeu::Move}
+
+
+### Moving the interface up
+
+    Vedeu.trigger(:_geometry_up_, name)
+
+See also: {Vedeu::Move}
+
+
+
+
+### Showing an interface
+
+    Vedeu.trigger(:_show_interface_, name)
+
+See: {Vedeu::Buffer#show}
+
+
+### Toggling an interface
+
+    Vedeu.trigger(:_toggle_interface_, name)
+
+See: {Vedeu::Buffer#toggle}

data/docs/events/visibility.md

@@ -0,0 +1,61 @@
+# @title Visibility Events
+
+## Visibility Events
+
+### Hiding the cursor
+
+    Vedeu.trigger(:_hide_cursor_, name)
+    Vedeu.trigger(:_cursor_hide_, name)
+
+Hide the cursor of the named interface or if a name is not given, the interface currently in focus. Also available as:
+
+    Vedeu.hide_cursor(name)
+
+
+### Showing the cursor
+
+    Vedeu.trigger(:_show_cursor_, name)
+    Vedeu.trigger(:_cursor_show_, name)
+
+Show the cursor of the named interface or if a name is not given, the interface currently in focus. Also available as:
+
+    Vedeu.show_cursor(name)
+
+
+### Hiding a group
+
+    Vedeu.trigger(:_hide_group_, group_name)
+
+Will hide all of the interfaces belonging to the named group. Useful for
+hiding part of that which is currently displaying in the terminal.
+
+This may be rarely used, since the action of showing a group
+will effectively clear the terminal and show the new group.
+
+
+### Showing a group
+
+    Vedeu.trigger(:_show_group_, group_name)
+
+Will clear the terminal and then show all of the interfaces belonging to the named group.
+
+
+### Hiding an interface
+
+    Vedeu.trigger(:_hide_interface_, name)
+
+See: {Vedeu::Buffer#hide}
+
+
+### Showing an interface
+
+    Vedeu.trigger(:_show_interface_, name)
+
+See: {Vedeu::Buffer#show}
+
+
+### Toggling an interface
+
+    Vedeu.trigger(:_toggle_interface_, name)
+
+See: {Vedeu::Buffer#toggle}

data/docs/events.md

@@ -0,0 +1,13 @@
+# @title Vedeu Events
+
+# Vedeu Events
+
+{include:file:docs/events/main.md}
+
+{include:file:docs/events/drb.md}
+
+{include:file:docs/events/menus.md}
+
+{include:file:docs/events/movement.md}
+
+{include:file:docs/events/visibility.md}

data/lib/vedeu/api.rb

@@ -1,11 +1,14 @@
 require 'vedeu/support/common'
 require 'vedeu/support/terminal'
 require 'vedeu/support/timer'
+require 'vedeu/support/visibility'
 require 'vedeu/output/renderers/all'
 require 'vedeu/events/all'
 require 'vedeu/models/all'
 require 'vedeu/input/all'
 require 'vedeu/dsl/all'
+require 'vedeu/application'
+require 'vedeu/output/clear'
 
 module Vedeu
 
@@ -230,6 +233,26 @@ module Vedeu
     #   @see Vedeu::Trigger.trigger
     def_delegators Vedeu::Trigger, :trigger
 
+    # @!method exit
+    #   @see Vedeu::Application.stop
+    def_delegators Vedeu::Application, :exit
+
+    # @!method clear_by_name
+    #   @see Vedeu::Clear.by_name
+    def_delegators Vedeu::Clear, :clear_by_name
+
+    # @!method clear_by_group
+    #   @see Vedeu::Clear.by_group
+    def_delegators Vedeu::Clear, :clear_by_group
+
+    # @!method hide_cursor
+    #   @see Vedeu::Visibility.hide_cursor
+    def_delegators Vedeu::Visibility, :hide_cursor
+
+    # @!method show_cursor
+    #   @see Vedeu::Visibility.show_cursor
+    def_delegators Vedeu::Visibility, :show_cursor
+
   end # API
 
   extend API

data/lib/vedeu/application/controller.rb

@@ -22,6 +22,7 @@ module Vedeu
       #
       # @param name [Symbol] The name of the controller.
       # @return [void]
+      # @todo This event binding should be: `Vedeu.bind(:show_view, name)`.
       def controller_name(name)
         Vedeu.bind("show_#{name}".to_sym) { new }
       end

data/lib/vedeu/application.rb

@@ -5,29 +5,34 @@ module Vedeu
   # @api private
   class Application
 
-    # @param (see #initialize)
-    def self.start(configuration)
-      new(configuration).start
-    end
+    class << self
 
-    # @param (see #initialize)
-    def self.restart(configuration)
-      new(configuration).start
-    end
+      # @param (see #initialize)
+      def start(configuration)
+        new(configuration).start
+      end
 
-    # Stops the application!
-    # - The `:_cleanup_` event is triggered, which in turn triggers the client
-    #   event `:cleanup`; the client application may treat this event as Vedeu
-    #   signalling that it is about to terminate. Client applications are
-    #   encouraged to use this event to close any open buffers, save files,
-    #   empty trash, etc.
-    #
-    # @return [void]
-    def self.stop
-      Vedeu.trigger(:_cleanup_)
+      # @param (see #initialize)
+      def restart(configuration)
+        new(configuration).start
+      end
 
-      Vedeu::MainLoop.stop!
-    end
+      # Stops the application!
+      # - The `:_cleanup_` event is triggered, which in turn triggers the client
+      #   event `:cleanup`; the client application may treat this event as Vedeu
+      #   signalling that it is about to terminate. Client applications are
+      #   encouraged to use this event to close any open buffers, save files,
+      #   empty trash, etc.
+      #
+      # @return [void]
+      def stop
+        Vedeu.trigger(:_cleanup_)
+
+        Vedeu::MainLoop.stop!
+      end
+      alias_method :exit, :stop
+
+    end # Eigenclass
 
     # :nocov:
     # Returns a new instance of Vedeu::Application.

data/lib/vedeu/bindings/bindings.rb

@@ -14,6 +14,7 @@ module Vedeu
   #   underscore, it's probably used by Vedeu internally.
   #
   # @api public
+  # {include:file:docs/events/main.md}
   module Bindings
 
     include Vedeu::Bindings::DRB
@@ -29,8 +30,7 @@ module Vedeu
       Vedeu.trigger(:cleanup)
     end
 
-    # When triggered, Vedeu will trigger a `:cleanup` event which you can define
-    # (to save files, etc) and attempt to exit.
+
     Vedeu.bind(:_exit_) { Vedeu::Application.stop }
 
     # Vedeu triggers this event when it is ready to enter the main loop. Client
@@ -39,18 +39,8 @@ module Vedeu
     # this event, the :_refresh_ event is also triggered automatically.
     Vedeu.bind(:_initialize_) { Vedeu.trigger(:_refresh_) }
 
-    # Will cause the triggering of the `:key` event; which
-    # you should define to 'do things'. If the `escape` key is pressed, then
-    # `key` is triggered with the argument `:escape`, also an internal event
-    # `_mode_switch_` is triggered.
     Vedeu.bind(:_keypress_) { |key| Vedeu.keypress(key) }
-
-    # Will cause the triggering of the `:command` event; which you should define
-    # to 'do things'.
     Vedeu.bind(:_command_) { |command| Vedeu.trigger(:command, command) }
-
-    # When triggered with a message will cause Vedeu to log the message if
-    # logging is enabled in the configuration.
     Vedeu.bind(:_log_) { |msg| Vedeu.log(type: :debug, message: msg) }
 
     # When triggered (after the user presses `escape`), Vedeu switches from a
@@ -63,49 +53,20 @@ module Vedeu
     # events. Please see those events for their behaviour.
     Vedeu.bind(:_resize_, delay: 0.15) { Vedeu.resize }
 
-    # When triggered will return the current position of the cursor.
-    Vedeu.bind(:_cursor_position_) do |name|
-      Vedeu.cursors.by_name(name).position
-    end
-
-    # When triggered with an interface name will focus that interface and
-    # restore the cursor position and visibility.
     Vedeu.bind(:_focus_by_name_) { |name| Vedeu.focus_by_name(name) }
-
-    # When triggered will focus the next interface and restore the cursor
-    # position and visibility.
     Vedeu.bind(:_focus_next_) { Vedeu.focus_next }
-
-    # When triggered will focus the previous interface and restore the cursor
-    # position and visibility.
     Vedeu.bind(:_focus_prev_) { Vedeu.focus_previous }
-
-    # Clears the whole terminal space, or the named interface area to be cleared
-    # if given.
     Vedeu.bind(:_clear_) { |name| Vedeu::Clear.by_name(name) }
 
-    # Will cause all interfaces to refresh, or the named interface if given.
-    #
-    # @note
-    #   Hidden interfaces will be still refreshed in memory but not shown.
     Vedeu.bind(:_refresh_) do |name|
       name ? Vedeu::Refresh.by_name(name) : Vedeu::Refresh.all
     end
 
-    # Will cause the named cursor to refresh, or the cursor of the interface
-    # which is currently in focus.
     Vedeu.bind(:_refresh_cursor_) { |name| Vedeu::RefreshCursor.render(name) }
-
-    # Will cause all interfaces in the named group to refresh.
     Vedeu.bind(:_refresh_group_) { |name| Vedeu::Refresh.by_group(name) }
-
-    # Clears the spaces occupied by the interfaces belonging to the named group.
     Vedeu.bind(:_clear_group_) { |name| Vedeu::Clear.by_group(name) }
-
-    # @see Vedeu::Geometry#maximise
     Vedeu.bind(:_maximise_) { |name| Vedeu.geometries.by_name(name).maximise }
 
-    # @see Vedeu::Geometry#unmaximise
     Vedeu.bind(:_unmaximise_) do |name|
       Vedeu.geometries.by_name(name).unmaximise
     end