vedeu 0.2.1 → 0.2.2

data/lib/vedeu/models/geometry.rb

@@ -3,22 +3,13 @@ module Vedeu
   # Calculates and provides interface geometry determined by both the client's
   # requirements and the terminal's current viewing area.
   #
-  # With terminal geometry, the origin is top-left, y = 1, x = 1.
+  # Geometry for Vedeu, as the same for ANSI terminals, has the origin at
+  # top-left, y = 1, x = 1. The 'y' coordinate is deliberately first.
   #
   # @api private
   class Geometry
 
-    # @return [Hash]
-    attr_reader :attributes
-
-    # @return [Boolean]
-    attr_reader :centred
-
-    # @return [Fixnum]
-    attr_reader :height
-
-    # @return [Fixnum]
-    attr_reader :width
+    attr_reader :attributes, :centred, :height, :width
 
     # Returns a new instance of Geometry.
     #
@@ -110,8 +101,8 @@ module Vedeu
       Esc.set_position(virtual_y[index], left, &block)
     end
 
-    # Returns a fixed or dynamic value depending on whether the interface is
-    # centred or not.
+    # Returns the top coordinate of the interface, a fixed or dynamic value
+    # depending on whether the interface is centred or not.
     #
     # @return [Fixnum]
     def top
@@ -139,8 +130,8 @@ module Vedeu
       top - value
     end
 
-    # Returns a fixed or dynamic value depending on whether the interface is
-    # centred or not.
+    # Returns the left coordinate of the interface, a fixed or dynamic value
+    # depending on whether the interface is centred or not.
     #
     # @return [Fixnum]
     def left
@@ -168,7 +159,8 @@ module Vedeu
       left - value
     end
 
-    # Returns a fixed or dynamic value depending on the value of {#top}.
+    # Returns the bottom coordinate of the interface, a fixed or dynamic value
+    # depending on the value of {#top}.
     #
     # @return [Fixnum]
     def bottom
@@ -190,8 +182,8 @@ module Vedeu
       bottom + value
     end
 
-    # Returns a fixed or dynamic value depending on whether the interface is
-    # centred or not.
+    # Returns the right coordinate of the interface, a fixed or dynamic value
+    # depending on the value of {#left}.
     #
     # @return [Fixnum]
     def right

data/lib/vedeu/models/interface.rb

@@ -3,6 +3,8 @@ module Vedeu
   # An Interface represents a portion of the terminal defined by
   # {Vedeu::Geometry}. It is a container for {Vedeu::Line} and {Vedeu::Stream}
   # objects.
+  #
+  # @api private
   class Interface
 
     include Coercions
@@ -79,17 +81,6 @@ module Vedeu
       @geometry ||= Geometry.new(attributes[:geometry])
     end
 
-    # @return [String]
-    def cursor
-      @cursor ||= if attributes[:cursor] == true
-        Esc.string('show_cursor')
-
-      else
-        Esc.string('hide_cursor')
-
-      end
-    end
-
     private
 
     # The default values for a new instance of Interface.
@@ -104,7 +95,6 @@ module Vedeu
         colour:   {},
         style:    '',
         geometry: {},
-        cursor:   true,
         delay:    0.0,
         parent:   nil,
       }

data/lib/vedeu/models/keymap.rb

@@ -2,6 +2,8 @@ module Vedeu
 
   # A Keymap is the binding of a keypress to one or more interfaces; or globally
   # to perform a client application defined action.
+  #
+  # @api private
   class Keymap
 
     include Common

data/lib/vedeu/models/line.rb

@@ -3,6 +3,8 @@ module Vedeu
   # A Line represents a single row of the terminal. It is a container for
   # {Vedeu::Stream} objects. A line's width is determined by the
   # {Vedeu::Interface} it belongs to.
+  #
+  # @api private
   class Line
 
     include Coercions

data/lib/vedeu/models/stream.rb

@@ -3,6 +3,8 @@ module Vedeu
   # A Stream can represent a character or collection of characters as part of a
   # {Vedeu::Line} which you wish to colour and style independently of the other
   # characters in that line.
+  #
+  # @api private
   class Stream
 
     include Coercions

data/lib/vedeu/models/style.rb

@@ -2,6 +2,8 @@ module Vedeu
 
   # Converts the style value or value collection into a terminal escape
   # sequence. Unrecognised values are discarded- an empty string is returned.
+  #
+  # @api private
   class Style
 
     include Vedeu::Common

data/lib/vedeu/output/clear.rb

@@ -36,7 +36,6 @@ module Vedeu
 
     private
 
-    # @return [Interface]
     attr_reader :interface
 
     # @api private

data/lib/vedeu/output/compositor.rb

@@ -31,7 +31,6 @@ module Vedeu
 
     private
 
-    # @return [String]
     attr_reader :name
 
     # Renders the buffer unless empty, otherwise clears the area which the

data/lib/vedeu/output/refresh.rb

@@ -8,6 +8,9 @@ module Vedeu
     include Vedeu::Common
     extend self
 
+    # System event to refresh all registered interfaces.
+    Vedeu.event(:_refresh_) { Vedeu::Refresh.all }
+
     # Refresh all registered interfaces.
     #
     # @return [Array]

data/lib/vedeu/output/render.rb

@@ -39,13 +39,11 @@ module Vedeu
         out << interface.origin(index)
         out << line.to_s
       end
-      out << interface.cursor
       out.join
     end
 
     private
 
-    # @return [Interface]
     attr_reader :interface
 
     # The client application may have created a line that us too long for the
@@ -58,9 +56,9 @@ module Vedeu
     # @api private
     # @return [Array]
     def processed_lines
-      return [] unless lines.any? { |line| line.streams.any? }
+      return [] unless visible_lines.any? { |line| line.streams.any? }
 
-      lines.map do |line|
+      visible_lines.map do |line|
         if exceeds_width?(line)
           line_length = 0
           new_streams = []
@@ -142,14 +140,22 @@ module Vedeu
       text.chomp.slice(0...value)
     end
 
-    # Provides a collection of lines associated with the interface.
+    # Provides the collection of visible lines associated with the interface.
     # If the option `:top` was set, we will start at that line. Any lines
     # outside of the height will not be rendered.
     #
     # @api private
     # @return [Array]
+    def visible_lines
+      lines[top..height]
+    end
+
+    # Provides the collection of lines associated with the interface.
+    #
+    # @api private
+    # @return [Array]
     def lines
-      interface.lines[top..height]
+      interface.lines
     end
 
     # Provides the currently available height of the interface.

data/lib/vedeu/output/view.rb

@@ -7,6 +7,7 @@ module Vedeu
   #
   # @deprecated May disappear in 0.3.0. Prefer {Vedeu::API#render} instead.
   # @see Vedeu::API#render
+  # @api private
   class View
 
     include Vedeu::API

data/lib/vedeu/repositories/cursors.rb

@@ -0,0 +1,98 @@
+module Vedeu
+
+  # Repository for storing, retrieving and manipulating the cursor position and
+  # visibility for an interface.
+  #
+  # @api private
+  module Cursors
+
+    include Common
+    extend self
+
+    # System events which when called will update the cursor position or
+    # visibility accordingly for the interface in focus.
+    Vedeu.event(:_cursor_up_)      { Cursors.use(:move_up)    }
+    Vedeu.event(:_cursor_right_)   { Cursors.use(:move_right) }
+    Vedeu.event(:_cursor_down_)    { Cursors.use(:move_down)  }
+    Vedeu.event(:_cursor_left_)    { Cursors.use(:move_left)  }
+    Vedeu.event(:_cursor_hide_)    { Cursors.use(:hide)       }
+    Vedeu.event(:_cursor_show_)    { Cursors.use(:show)       }
+    Vedeu.event(:_cursor_refresh_) { Cursors.use(:refresh)    }
+
+    # Adds an interface to the cursors repository.
+    #
+    # @param attributes [Hash]
+    # @return [Hash]
+    def add(attributes)
+      return false unless defined_value?(attributes[:name])
+
+      storage.store(attributes[:name], {
+        name: attributes[:name],
+        x: 1,
+        y: 1,
+        state: :show
+      })
+    end
+
+    # Find the cursor attributes by name.
+    #
+    # @param name [String]
+    # @return [Hash]
+    def find(name)
+      storage.fetch(name) do
+        fail CursorNotFound,
+          "Cursor was not found with this name: #{name.to_s}."
+      end
+    end
+
+    # Returns a boolean indicating whether the named interface is registered.
+    #
+    # @api private
+    # @return [Boolean]
+    def registered?(name)
+      return false if storage.empty?
+
+      storage.keys.include?(name)
+    end
+
+    # Perform an action (moving, showing or hiding) and save the new cursor
+    # state.
+    #
+    # @param action [Symbol] A symbol representing the method name to be called
+    #   on the Cursor instance.
+    # @return [String] The escape sequence sent to the Terminal on completion
+    #   of the action.
+    def use(action)
+      name   = Focus.current
+      cursor = Cursor.new(find(name))
+
+      storage.store(name, cursor.send(action))
+
+      Terminal.output(cursor.to_s)
+    end
+
+    private
+
+    # Access to the storage for this repository.
+    #
+    # @api private
+    # @example
+    #   { 'holmium' => { name: 'holmium', y: 12, x: 6, state: :show } }
+    #
+    # @return [Hash]
+    def storage
+      @_storage ||= in_memory
+    end
+
+    # Returns an empty collection ready for the storing of cursors by name with
+    # current attributes.
+    #
+    # @api private
+    # @return [Hash]
+    def in_memory
+      {}
+    end
+
+  end
+
+end

data/lib/vedeu/repositories/events.rb

@@ -69,7 +69,6 @@ module Vedeu
 
     private
 
-    # @return [Hash]
     attr_reader :handlers
 
     # @api private

data/lib/vedeu/repositories/focus.rb

@@ -9,6 +9,24 @@ module Vedeu
 
     extend self
 
+    # System events which when called will change which interface is currently
+    # focussed. When the interface is brought into focus, its cursor position
+    # and visibility is restored.
+    Vedeu.event(:_focus_by_name_) do |name|
+      Vedeu::Focus.by_name(name)
+      Vedeu.trigger(:_cursor_refresh_)
+    end
+
+    Vedeu.event(:_focus_next_) do
+      Vedeu::Focus.next_item
+      Vedeu.trigger(:_cursor_refresh_)
+    end
+
+    Vedeu.event(:_focus_prev_) do
+      Vedeu::Focus.prev_item
+      Vedeu.trigger(:_cursor_refresh_)
+    end
+
     # Add an interface name to the focus list unless it is already registered.
     #
     # @param attributes [String]

data/lib/vedeu/repositories/menus.rb

@@ -30,6 +30,8 @@ module Vedeu
 
       Vedeu.log("Registering menu '#{attributes[:name]}'")
 
+      attributes.merge!({ items: Vedeu::Menu.new(attributes[:items]) })
+
       storage.store(attributes[:name], attributes)
     end
 
@@ -90,11 +92,9 @@ module Vedeu
     # Access a menu by name.
     #
     # @param name [String]
-    # @return [Vedeu::Menu|MenuNotFound]
+    # @return [Vedeu::Menu]
     def use(name)
-      find(name).fetch(:items) do
-        fail MenuNotFound, "This menu '#{name}' has no items."
-      end
+      find(name).fetch(:items)
     end
 
     private

data/lib/vedeu/support/common.rb

@@ -7,9 +7,10 @@ module Vedeu
 
     # Returns a boolean indicating whether a variable has a useful value.
     #
-    # @param variable [String|Symbol|Array] The variable to check.
+    # @param variable [String|Symbol|Array|Fixnum] The variable to check.
     # @return [Boolean]
     def defined_value?(variable)
+      return true if variable.is_a?(Fixnum)
       return true unless variable.nil? || variable.empty?
 
       false

data/lib/vedeu/support/event.rb

@@ -32,17 +32,8 @@ module Vedeu
 
     private
 
-    # @return [Proc]
     attr_reader   :closure
-
-    # @return []
-    attr_accessor :deadline
-
-    # @return []
-    attr_accessor :executed_at
-
-    # @return []
-    attr_accessor :now
+    attr_accessor :deadline, :executed_at, :now
 
     # Execute the code stored in the event closure.
     #

data/lib/vedeu/support/grid.rb

@@ -1,5 +1,5 @@
 # Monkey-patch Ruby's Fixnum to provide a columns method.
-# TODO: Don't monkey-patch because it is naughty.
+# @todo Don't monkey-patch because it is naughty.
 class Fixnum
 
   # Augment Fixnum to calculate column width in a grid-based layout.
@@ -47,7 +47,6 @@ module Vedeu
 
     private
 
-    # @return [Fixnum]
     attr_reader :value
 
     # @api private

data/lib/vedeu/{repositories → support}/keymap_validator.rb

@@ -3,6 +3,7 @@ module Vedeu
   # Validates that a given key is can be used and is not already in-use, either
   # by the same interface, globally or as a system key.
   #
+  # @api private
   class KeymapValidator
 
     include Common
@@ -31,17 +32,17 @@ module Vedeu
     # @see KeymapValidator.check
     def check
       if system_key?(key)
-        [false, "#{fail_message(key)} by the system."]
+        [false, fail_message(key) + ' by the system.']
 
       elsif global_key?(key)
-        [false, "#{fail_message(key)} as a global key."]
+        [false, fail_message(key) + ' as a global key.']
 
       elsif interface_key?(key, interface)
         if defined_value?(interface)
-          [false, "#{fail_message(key)} by this interface."]
+          [false, fail_message(key) + ' by this interface.']
 
         else
-          [false, "#{fail_message(key)} by another interface and therefore " \
+          [false, fail_message(key) + ' by another interface and therefore ' \
                   'cannot be global.']
 
         end