vedeu 0.6.8 → 0.6.9

data/docs/events/movement.md

@@ -0,0 +1,57 @@
+# @title Vedeu Movement Events
+
+## Movement Events
+
+### :_cursor_origin_
+This event moves the cursor to the interface origin; the top left
+corner of the named interface.
+
+    Vedeu.trigger(:_cursor_origin_, name)
+    Vedeu.trigger(:_cursor_reset_, name)
+
+### :_cursor_position_
+When triggered will return the current position of the cursor.
+
+    Vedeu.trigger(:_cursor_position_, name)
+
+### :_cursor_reposition_
+Moves the cursor to a relative position inside the interface.
+
+    Vedeu.trigger(:_cursor_reposition_, name, y, x)
+
+### :_cursor_(up, down, left, right)_
+Adjusts the position of the cursor or view.
+
+When a name is not given, the cursor in the interface which is
+currently in focus should move in the direction specified.
+
+    Vedeu.trigger(:_cursor_left_, 'my_interface')
+    Vedeu.trigger(:_cursor_left_)
+    Vedeu.trigger(:_cursor_right_)
+    Vedeu.trigger(:_cursor_up_)
+    Vedeu.trigger(:_cursor_down_)
+
+- The cursor or view may not be visible, but it will still move if
+  requested.
+- The cursor will not exceed the border or boundary of the interface,
+  or boundary of the visible terminal.
+- The cursor will move freely within the bounds of the interface,
+  irrespective of content.
+- The view will not exceed the boundary of the visible terminal,
+  though its offset may (this means content will appear to have
+  scrolled).
+- The view will move freely within the bounds of the interface,
+  irrespective of content.
+
+### :_view_(up, down, left, right)_
+
+See {file:docs/events.md#\_cursor__up_down_left_right_}
+
+Please note that the name of the view is required for these events.
+
+    Vedeu.trigger(:_view_down_,  'my_interface')
+    Vedeu.trigger(:_view_left_,  'my_interface')
+    Vedeu.trigger(:_view_right_, 'my_interface')
+    Vedeu.trigger(:_view_up_,    'my_interface')
+
+Each of the :_view_* events has an alias, :_geometry_* if you prefer.

data/docs/events/refresh.md

@@ -0,0 +1,25 @@
+# @title Vedeu Refresh Events
+
+## Refresh Events
+
+### :_refresh_
+Refreshes all registered interfaces or the named interface.
+
+The interfaces will be refreshed in z-index order, meaning that
+interfaces with a lower z-index will be drawn first. This means
+overlapping interfaces will be drawn as specified. Hidden interfaces
+will be still refreshed in memory but not shown.
+
+    Vedeu.trigger(:_refresh_)
+    Vedeu.trigger(:_refresh_, name)
+
+### :_refresh_cursor_
+Will cause the named cursor to refresh, or the cursor of the interface
+which is currently in focus.
+
+    Vedeu.trigger(:_refresh_cursor_, name)
+
+### :_refresh_group_
+Will cause all interfaces in the named group to refresh.
+
+    Vedeu.trigger(:_refresh_group_, name)

data/docs/events/system.md

@@ -0,0 +1,90 @@
+# @title Vedeu System Events
+
+## System Events
+
+### :_cleanup_
+Vedeu triggers this event when `:_exit_` is triggered. You can hook
+into this to perform a special action before the application
+terminates. Saving the user's work, session or preferences might be
+popular here.
+
+    Vedeu.trigger(:_exit_)
+
+### :_clear_
+Clears the whole terminal space, or when a name is given, the named
+interface area will be cleared.
+
+    Vedeu.trigger(:_clear_)
+    Vedeu.clear_by_name(name)
+
+### :_command_
+Will cause the triggering of the `:command` event; which you should
+define to 'do things'.
+
+    Vedeu.trigger(:_command_, command)
+
+### :_editor_
+This event is called by {Vedeu::Input::Input#capture}. When
+invoked, the key will be passed to the editor for currently
+focussed view.
+
+    Vedeu.trigger(:_editor_, key)
+
+### :_exit_
+When triggered, Vedeu will trigger a `:cleanup` event which you can
+define (to save files, etc) and attempt to exit.
+
+    Vedeu.trigger(:_exit_)
+    Vedeu.exit
+
+### :_initialize_
+Vedeu triggers this event when it is ready to enter the main loop.
+Client applications can listen for this event and perform some
+action(s), like render the first screen, interface or make a sound.
+
+    Vedeu.trigger(:_initialize_)
+
+### :_keypress_
+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 supported keypresses can be found here:
+{Vedeu::Input::Input#specials} and {Vedeu::Input::Input#f_keys}.
+
+    Vedeu.trigger(:_keypress_, key)
+
+### :_log_
+When triggered with a message will cause Vedeu to log the message if
+logging is enabled in the configuration.
+
+    Vedeu.trigger(:_log_, message)
+
+### :_maximise_
+Maximising an interface.
+
+    Vedeu.trigger(:_maximise_, name)
+
+See {Vedeu::Geometry::Geometry#maximise}
+
+### :_mode_switch_
+When triggered (by default, after the user presses `escape`), Vedeu
+switches between modes of the terminal. The idea here being
+that the raw mode is for single keypress actions, whilst fake and cooked
+modes allow the user to enter more elaborate commands- such as commands
+with arguments.
+
+    Vedeu.trigger(:_mode_switch_)
+
+### :_resize_
+When triggered will cause Vedeu to trigger the `:_clear_` and
+`:_refresh_` events. Please see those events for their behaviour.
+
+    Vedeu.trigger(:_resize_)
+
+### :_unmaximise_
+Unmaximising an interface.
+
+    Vedeu.trigger(:_unmaximise_, name)
+
+See {Vedeu::Geometry::Geometry#unmaximise}

data/docs/events/visibility.md

@@ -0,0 +1,68 @@
+# @title Vedeu Visibility Events
+
+## Visibility Events
+
+### :_clear_group_
+Clears the spaces occupied by the interfaces belonging to the named
+group.
+
+    Vedeu.trigger(:_clear_group_, name)
+    Vedeu.clear_by_group(name)
+
+### :_hide_cursor_
+Hide the cursor of the named interface or when a name is not given,
+the interface currently in focus.
+
+    Vedeu.trigger(:_hide_cursor_, name)
+    Vedeu.trigger(:_cursor_hide_, name)
+    Vedeu.hide_cursor(name)
+
+### :_hide_group_
+Hiding a group of interfaces.
+
+    Vedeu.trigger(:_hide_group_, name)
+    Vedeu.hide_group(name)
+
+### :_hide_interface_
+Hiding an interface.
+
+    Vedeu.trigger(:_hide_interface_, name)
+    Vedeu.hide_interface(name)
+
+### :_show_cursor_
+Show the cursor of the named interface or when a name is not given,
+the interface currently in focus.
+
+    Vedeu.trigger(:_show_cursor_, name)
+    Vedeu.trigger(:_cursor_show_, name)
+    Vedeu.show_cursor(name)
+
+### :_show_group_
+Showing a group of interfaces.
+
+    Vedeu.trigger(:_show_group_, name)
+    Vedeu.show_group(name)
+
+### :_show_interface_
+Showing an interface.
+
+    Vedeu.trigger(:_show_interface_, name)
+    Vedeu.show_interface(name)
+
+### :_toggle_cursor_
+Toggling a cursor.
+
+    Vedeu.trigger(:_toggle_cursor_, name)
+    Vedeu.toggle_cursor(name)
+
+### :_toggle_group_
+Toggling a group of interfaces.
+
+    Vedeu.trigger(:_toggle_group_, name)
+    Vedeu.toggle_group(name)
+
+### :_toggle_interface_
+Toggling an interface.
+
+    Vedeu.trigger(:_toggle_interface_, name)
+    Vedeu.toggle_interface(name)

data/lib/vedeu.rb

@@ -34,9 +34,9 @@ module Vedeu
 
   # Return the name of currently focussed interface.
   #
-  # @return [Vedeu::Focus]
+  # @return [Vedeu::Models::Focus]
   def self.focusable
-    @focusable ||= Vedeu::Focus
+    @focusable ||= Vedeu::Models::Focus
   end
 
   # :nocov:

data/lib/vedeu/all.rb

@@ -100,12 +100,13 @@ require 'vedeu/geometry/all'
 require 'vedeu/input/all'
 require 'vedeu/menus/all'
 
+require 'vedeu/output/presentation/presentation'
+
 require 'vedeu/output/direct'
 require 'vedeu/output/clear/named_group'
 require 'vedeu/output/clear/named_interface'
-require 'vedeu/output/presentation'
+
 require 'vedeu/output/compressor'
-require 'vedeu/output/style'
 require 'vedeu/output/text'
 require 'vedeu/output/output'
 require 'vedeu/output/viewport'

data/lib/vedeu/api.rb

@@ -87,16 +87,16 @@ module Vedeu
     def_delegators Vedeu::Events::Aliases, :bind_alias, :unbind_alias
 
     # @!method focus
-    #   @see Vedeu::Focus#focus
+    #   @see Vedeu::Models::Focus#focus
     # @!method focus_by_name
-    #   @see Vedeu::Focus#focus_by_name
+    #   @see Vedeu::Models::Focus#focus_by_name
     # @!method focussed?
-    #   @see Vedeu::Focus#focussed?
+    #   @see Vedeu::Models::Focus#focussed?
     # @!method focus_next
-    #   @see Vedeu::Focus#focus_next
+    #   @see Vedeu::Models::Focus#focus_next
     # @!method focus_previous
-    #   @see Vedeu::Focus#focus_previous
-    def_delegators Vedeu::Focus, :focus, :focus_by_name, :focussed?,
+    #   @see Vedeu::Models::Focus#focus_previous
+    def_delegators Vedeu::Models::Focus, :focus, :focus_by_name, :focussed?,
                    :focus_next, :focus_previous
 
     # @!method log
@@ -160,28 +160,28 @@ module Vedeu
     def_delegators Vedeu::Cursors::Cursor, :toggle_cursor
 
     # @!method hide_group
-    #   @see Vedeu::Group#hide
-    def_delegators Vedeu::Group, :hide_group
+    #   @see Vedeu::Models::Group#hide
+    def_delegators Vedeu::Models::Group, :hide_group
 
     # @!method show_group
-    #   @see Vedeu::Group#show
-    def_delegators Vedeu::Group, :show_group
+    #   @see Vedeu::Models::Group#show
+    def_delegators Vedeu::Models::Group, :show_group
 
     # @!method toggle_group
-    #   @see Vedeu::Group#toggle
-    def_delegators Vedeu::Group, :toggle_group
+    #   @see Vedeu::Models::Group#toggle
+    def_delegators Vedeu::Models::Group, :toggle_group
 
     # @!method hide_interface
-    #   @see Vedeu::Interface#hide
-    def_delegators Vedeu::Interface, :hide_interface
+    #   @see Vedeu::Models::Interface#hide
+    def_delegators Vedeu::Models::Interface, :hide_interface
 
     # @!method show_interface
-    #   @see Vedeu::Interface#show
-    def_delegators Vedeu::Interface, :show_interface
+    #   @see Vedeu::Models::Interface#show
+    def_delegators Vedeu::Models::Interface, :show_interface
 
     # @!method toggle_interface
-    #   @see Vedeu::Interface#toggle
-    def_delegators Vedeu::Interface, :toggle_interface
+    #   @see Vedeu::Models::Interface#toggle
+    def_delegators Vedeu::Models::Interface, :toggle_interface
 
   end # API
 

data/lib/vedeu/application/controller.rb

@@ -1,6 +1,6 @@
 module Vedeu
 
-  # Provides methods to be used by Vedeu::ApplicationController.
+  # Provides methods to be used by {Vedeu::ApplicationController}.
   #
   module Controller
 

data/lib/vedeu/application/helper.rb

@@ -1,6 +1,6 @@
 module Vedeu
 
-  # Provides methods to be used by Vedeu::ApplicationHelper.
+  # Provides methods to be used by {Vedeu::ApplicationHelper}.
   #
   module Helper
 

data/lib/vedeu/application/view.rb

@@ -1,6 +1,6 @@
 module Vedeu
 
-  # Provides methods to be used by Vedeu::ApplicationView.
+  # Provides methods to be used by {Vedeu::ApplicationView}.
   #
   module View
 

data/lib/vedeu/bindings/application.rb

@@ -4,7 +4,6 @@ module Vedeu
 
     # System events relating to movement of cursors or interfaces.
     #
-    # :nocov:
     module Application
 
       extend self
@@ -19,16 +18,7 @@ module Vedeu
 
       private
 
-      # Call a client application controller's action with parameters.
-      #
-      # @example
-      #   Vedeu.trigger(:_goto_,
-      #                 :your_controller,
-      #                 :some_action,
-      #                 { id: 7 })
-      #   Vedeu.goto(:your_controller, :some_action, { id: 7 })
-      #
-      # @return [TrueClass]
+      # See {file:docs/events/application.md#\_goto_}
       def goto!
         Vedeu.bind(:_goto_) do |controller, action, **args|
           Vedeu::Router.goto(controller, action, **args)
@@ -38,7 +28,6 @@ module Vedeu
       end
 
     end # Application
-    # :nocov:
 
   end # Bindings
 

data/lib/vedeu/bindings/bindings.rb

@@ -1,6 +1,8 @@
 module Vedeu
 
-  # Binds various events for running and manipulating Vedeu.
+  # Binds various events for running and manipulating Vedeu. When
+  # called provide a variety of core functions and behaviours.
+  # They are soft-namespaced using underscores.
   #
   # @note
   #   The methods these modules use are private, and should not be

data/lib/vedeu/bindings/document.rb

@@ -5,7 +5,6 @@ module Vedeu
     # System events relating to the document/editor/fake terminal
     # implementation.
     #
-    # :nocov:
     module Document
 
       extend self
@@ -28,118 +27,66 @@ module Vedeu
 
       private
 
-      # @example
-      #   Vedeu.trigger(:_editor_execute_, name)
-      #
-      # @return [TrueClass]
+      # See {file:docs/events/document.md#\_editor_execute_}
       def editor_execute!
         Vedeu.bind(:_editor_execute_) do |name|
           Vedeu.documents.by_name(name).execute
         end
       end
 
-      # This event attempts to delete the character in the named
-      # document at the current virtual cursor position.
-      #
-      # @example
-      #   Vedeu.trigger(:_editor_delete_character_, name)
-      #
-      # @return [TrueClass]
+      # See {file:docs/events/document.md#\_editor_delete_character_}
       def editor_delete_character!
         Vedeu.bind(:_editor_delete_character_) do |name|
           Vedeu.documents.by_name(name).delete_character
         end
       end
 
-      # This event attempts to delete the line in the named document
-      # at the current virtual cursor position.
-      #
-      # @example
-      #   Vedeu.trigger(:_editor_delete_line_, name)
-      #
-      # @return [TrueClass]
+      # See {file:docs/events/document.md#\_editor_delete_line_}
       def editor_delete_line!
         Vedeu.bind(:_editor_delete_line_) do |name|
           Vedeu.documents.by_name(name).delete_line
         end
       end
 
-      # This event attempts to move the virtual cursor down by one
-      # line in the named document.
-      #
-      # @example
-      #   Vedeu.trigger(:_editor_down_, name)
-      #
-      # @return [TrueClass]
+      # See {file:docs/events/document.md#\_editor_down_}
       def editor_down!
         Vedeu.bind(:_editor_down_) do |name|
           Vedeu.documents.by_name(name).down
         end
       end
 
-      # This event attempts to insert the given character in the named
-      # document at the current virtual cursor position.
-      #
-      # @example
-      #   Vedeu.trigger(:_editor_insert_character_, name, character)
-      #
-      # @return [TrueClass]
+      # See {file:docs/events/document.md#\_editor_insert_character_}
       def editor_insert_character!
         Vedeu.bind(:_editor_insert_character_) do |name, character|
           Vedeu.documents.by_name(name).insert_character(character)
         end
       end
 
-      # This event attempts to insert a new line in the named document
-      # at the current virtual cursor position.
-      #
-      # @example
-      #   Vedeu.trigger(:_editor_insert_line_, name)
-      #
-      # @return [TrueClass]
+      # See {file:docs/events/document.md#\_editor_insert_line_}
       def editor_insert_line!
         Vedeu.bind(:_editor_insert_line_) do |name|
           Vedeu.documents.by_name(name).insert_line
         end
       end
 
-      # This event attempts to move the virtual cursor left by one
-      # character in the named document.
-      #
-      # @example
-      #   Vedeu.trigger(:_editor_left_, name)
-      #
-      # @return [TrueClass]
+      # See {file:docs/events/document.md#\_editor_left_}
       def editor_left!
         Vedeu.bind(:_editor_left_) { |name| Vedeu.documents.by_name(name).left }
       end
 
-      # This event attempts to move the virtual cursor right by one
-      # character in the named document.
-      #
-      # @example
-      #   Vedeu.trigger(:_editor_right_, name)
-      #
-      # @return [TrueClass]
+      # See {file:docs/events/document.md#\_editor_right_}
       def editor_right!
         Vedeu.bind(:_editor_right_) do |name|
           Vedeu.documents.by_name(name).right
         end
       end
 
-      # This event attempts to move the virtual cursor up by one line
-      # in the named document.
-      #
-      # @example
-      #   Vedeu.trigger(:_editor_up_, name)
-      #
-      # @return [TrueClass]
+      # See {file:docs/events/document.md#\_editor_up_}
       def editor_up!
         Vedeu.bind(:_editor_up_) { |name| Vedeu.documents.by_name(name).up }
       end
 
     end # Document
-    # :nocov:
 
   end # Bindings