vedeu 0.2.3 → 0.2.4

data/lib/vedeu/models/cursor.rb

@@ -8,19 +8,28 @@ module Vedeu
 
     extend Forwardable
 
-    def_delegators :geometry, :top, :right, :bottom, :left
+    def_delegators :interface, :top, :right, :bottom, :left
+
+    attr_reader :name, :state
 
     # Provides a new instance of Cursor.
     #
     # @param attributes [Hash] The stored attributes for a cursor.
+    # @option attributes :name [String] The name of the interface this cursor
+    #   belongs to.
+    # @option attributes :state [Symbol] The visibility of the cursor, either
+    #   +:hide+ or +:show+.
+    # @option attributes :x [Fixnum]
+    # @option attributes :y [Fixnum]
+    #
     # @return [Cursor]
     def initialize(attributes = {})
       @attributes = defaults.merge!(attributes)
 
-      @name  = @attributes[:name]
-      @state = @attributes[:state]
-      @x     = @attributes[:x]
-      @y     = @attributes[:y]
+      @name       = @attributes[:name]
+      @state      = @attributes[:state]
+      @x          = @attributes[:x]
+      @y          = @attributes[:y]
     end
 
     # Returns an attribute hash for the current position and visibility of the
@@ -29,89 +38,64 @@ module Vedeu
     # @return [Hash]
     def attributes
       {
-        name:  name,
-        state: state,
-        x:     x,
-        y:     y,
+        name:     name,
+        state:    state,
+        x:        x,
+        y:        y,
       }
     end
     alias_method :refresh, :attributes
 
-    # Move the cursor up one row.
+    # Returns the x coordinate (column/character) of the cursor. Attempts to
+    # sensibly reposition the cursor if it is currently outside the interface.
     #
-    # @return [Cursor]
-    def move_up
-      unless y == top || y - 1 < top
-        @y -= 1
-      end
+    # @return [Fixnum]
+    def x
+      if @x <= left
+        @x = left
 
-      attributes
-    end
+      elsif @x >= right
+        @x = right - 1
 
-    # Move the cursor down one row.
-    #
-    # @return [Cursor]
-    def move_down
-      unless y == bottom || y + 1 >= bottom
-        @y += 1
-      end
+      else
+        @x
 
-      attributes
+      end
     end
 
-    # Move the cursor left one column.
+    # Returns the y coordinate (row/line) of the cursor. Attempts to sensibly
+    # reposition the cursor if it is currently outside the interface.
     #
-    # @return [Cursor]
-    def move_left
-      unless x == left || x - 1 < left
-        @x -= 1
-      end
+    # @return [Fixnum]
+    def y
+      if @y <= top
+        @y = top
 
-      attributes
-    end
+      elsif @y >= bottom
+        @y = bottom - 1
 
-    # Move the cursor right one column.
-    #
-    # @return [Cursor]
-    def move_right
-      unless x == right || x + 1 >= right
-        @x += 1
-      end
+      else
+        @y
 
-      attributes
+      end
     end
 
-    # Make the cursor visible if it is not already.
+    # Make the cursor visible.
     #
-    # @return [Symbol]
+    # @return [Hash]
     def show
       @state = :show
 
-      attributes
+      Cursors.update(attributes)
     end
 
-    # Make the cursor invisible if it is not already.
+    # Make the cursor invisible.
     #
-    # @return [Symbol]
+    # @return [Hash]
     def hide
       @state = :hide
 
-      attributes
-    end
-
-    # Toggle the visibility of the cursor.
-    #
-    # @return [Symbol]
-    def toggle
-      if visible?
-        @state = :hide
-
-      else
-        @state = :show
-
-      end
-
-      attributes
+      Cursors.update(attributes)
     end
 
     # Returns an escape sequence to position the cursor and set its visibility.
@@ -130,29 +114,35 @@ module Vedeu
       end
     end
 
-    private
+    # Return a boolean indicating the visibility of the cursor, invisible if
+    # the state is not defined.
+    #
+    # @return [Boolean]
+    def visible?
+      return false unless states.include?(state)
+      return false if state == :hide
 
-    attr_reader :name, :state
+      true
+    end
+
+    private
 
     # Returns the escape sequence to position the cursor and set its visibility.
     #
-    # @api private
     # @return [String]
     def sequence
       [ position, visibility ].join
     end
 
-    # Returns the escape sequence to position the cursor.
+    # Returns the escape sequence for setting the position of the cursor.
     #
-    # @api private
     # @return [String]
     def position
-      ["\e[", y, ';', x, 'H'].join
+      @_position ||= Position.new(y, x).to_s
     end
 
     # Returns the escape sequence for setting the visibility of the cursor.
     #
-    # @api private
     # @return [String]
     def visibility
       return Esc.string('show_cursor') if visible?
@@ -160,85 +150,20 @@ module Vedeu
       Esc.string('hide_cursor')
     end
 
-    # Return a boolean indicating the visibility of the cursor, invisible if
-    # the state is not defined.
-    #
-    # @api private
-    # @return [Boolean]
-    def visible?
-      return false unless states.include?(state)
-      return false if state == :hide
-
-      true
-    end
-
-    # Returns the y coordinate of the cursor, unless out of range, in which case
-    # sets y to the first row (top) of the interface.
+    # Returns an instance of the associated interface for this cursor, used to
+    # ensure that {x} and {y} are still 'inside' the interface. A cursor could
+    # be 'outside' the interface if the terminal has resized, causing the
+    # geometry of an interface to change and therefore invalidating the cursor's
+    # position.
     #
     # @api private
-    # @return [Fixnum]
-    def y
-      if y_out_of_range?
-        @y = top
-
-      else
-        @y
-
-      end
-    end
-
-    # Returns the x coordinate of the cursor, unless out of range, in which case
-    # sets x to the first column (left) of the interface.
-    #
-    # @api private
-    # @return [Fixnum]
-    def x
-      if x_out_of_range?
-        @x = left
-
-      else
-        @x
-
-      end
-    end
-
-    # Returns a boolean indicating whether the previous y coordinate is still
-    # inside the interface or terminal.
-    #
-    # @api private
-    # @return [Boolean]
-    def y_out_of_range?
-      @y < top || @y > bottom
-    end
-
-    # Returns a boolean indicating whether the previous x coordinate is still
-    # inside the interface or terminal.
-    #
-    # @api private
-    # @return [Boolean]
-    def x_out_of_range?
-      @x < left || @x > right
-    end
-
-    # Returns the position and size of the interface.
-    #
-    # @api private
-    # @return [Geometry]
-    def geometry
-      @geometry ||= Vedeu::Geometry.new(interface[:geometry])
-    end
-
-    # Returns the attributes of a named interface.
-    #
-    # @api private
-    # @return [Hash]
+    # @return [Interface]
     def interface
-      Vedeu::Interfaces.find(name)
+      @interface ||= Interfaces.build(name)
     end
 
     # The valid visibility states for the cursor.
     #
-    # @api private
     # @return [Array]
     def states
       [:show, :hide]
@@ -246,14 +171,13 @@ module Vedeu
 
     # The default values for a new instance of Cursor.
     #
-    # @api private
     # @return [Hash]
     def defaults
       {
-        name:  '',
-        x:     1,
-        y:     1,
-        state: :hide,
+        name:     '',
+        state:    :show,
+        x:        1,
+        y:        1,
       }
     end
 

data/lib/vedeu/models/{attributes/foreground.rb → foreground.rb}

@@ -8,19 +8,16 @@ module Vedeu
 
     private
 
-    # @api private
     # @return [String]
     def named
       ["\e[", foreground_codes[colour], 'm'].join
     end
 
-    # @api private
     # @return [String]
     def numbered
       ["\e[38;5;", css_to_numbered, 'm'].join
     end
 
-    # @api private
     # @return [String]
     def rgb
       if Configuration.colour_mode == 16777216
@@ -35,7 +32,6 @@ module Vedeu
     # Produces the foreground named colour escape sequence hash from
     # {Vedeu::ColourTranslator#codes}
     #
-    # @api private
     # @return [Hash]
     def foreground_codes
       codes

data/lib/vedeu/models/geometry.rb

@@ -9,7 +9,7 @@ module Vedeu
   # @api private
   class Geometry
 
-    attr_reader :attributes, :centred, :height, :width
+    attr_reader :attributes, :centred
 
     # Returns a new instance of Geometry.
     #
@@ -60,13 +60,13 @@ module Vedeu
     # is not off-screen.
     #
     # @return [Fixnum]
-    def viewport_width
-      if (x + width) > Terminal.width
-        new_width = width - ((x + width) - Terminal.width)
+    def width
+      if (x + @width) > Terminal.width
+        new_width = @width - ((x + @width) - Terminal.width)
         return new_width < 1 ? 1 : new_width
 
       else
-        width
+        @width
 
       end
     end
@@ -81,18 +81,21 @@ module Vedeu
     # Vedeu render the view to ensure the content is not off-screen.
     #
     # @return [Fixnum]
-    def viewport_height
-      if (y + height) > Terminal.height
-        new_height = height - ((y + height) - Terminal.height)
+    def height
+      if (y + @height) > Terminal.height
+        new_height = @height - ((y + @height) - Terminal.height)
         return new_height < 1 ? 1 : new_height
 
       else
-        height
+        @height
 
       end
     end
 
-    # Returns the top-left coordinate, relative to the interface's position.
+    # Returns an escape sequence to position the cursor at the top-left
+    # coordinate, relative to the interface's position.
+    #
+    # @todo I think this method belongs with Area.
     #
     # @param index [Fixnum]
     # @param block [Proc]
@@ -107,7 +110,7 @@ module Vedeu
     # @return [Fixnum]
     def top
       if centred
-        Terminal.centre_y - (viewport_height / 2)
+        Terminal.centre_y - (height / 2)
 
       else
         y
@@ -136,7 +139,7 @@ module Vedeu
     # @return [Fixnum]
     def left
       if centred
-        Terminal.centre_x - (viewport_width / 2)
+        Terminal.centre_x - (width / 2)
 
       else
         x
@@ -162,9 +165,6 @@ module Vedeu
     # Returns the bottom coordinate of the interface, a fixed or dynamic value
     # depending on the value of {#top}.
     #
-    # @todo I think `height` should be `viewport_height` because the terminal
-    #   may have resized, and viewport_height will properly handle this.
-    #
     # @return [Fixnum]
     def bottom
       top + height
@@ -188,9 +188,6 @@ module Vedeu
     # Returns the right coordinate of the interface, a fixed or dynamic value
     # depending on the value of {#left}.
     #
-    # @todo I think `width` should be `viewport_width` because the terminal may
-    #   have resized, and viewport_width will properly handle this.
-    #
     # @return [Fixnum]
     def right
       left + width
@@ -213,6 +210,8 @@ module Vedeu
 
     # Provides a virtual y position within the interface's dimensions.
     #
+    # @todo I think this method belongs with Area.
+    #
     # @example
     #   # top = 3
     #   # bottom = 6
@@ -225,6 +224,8 @@ module Vedeu
 
     # Provides a virtual x position within the interface's dimensions.
     #
+    # @todo I think this method belongs with Area.
+    #
     # @example
     #   # left = 9
     #   # right = 13
@@ -245,8 +246,6 @@ module Vedeu
         width:           width,
         x:               x,
         y:               y,
-        viewport_height: viewport_height,
-        viewport_width:  viewport_width,
         top:             top,
         right:           right,
         bottom:          bottom,

data/lib/vedeu/models/interface.rb

@@ -14,8 +14,7 @@ module Vedeu
     extend Forwardable
 
     def_delegators :geometry, :north, :east, :south, :west, :top, :right,
-                              :bottom, :left, :width, :height, :origin,
-                              :viewport_width, :viewport_height
+                              :bottom, :left, :width, :height, :origin
 
     attr_reader :attributes, :delay, :group, :name, :parent
 
@@ -67,6 +66,17 @@ module Vedeu
       self
     end
 
+    # Returns an instance of Cursor.
+    #
+    # @return [Cursor]
+    def cursor
+      @_cursor ||= Cursor.new({
+        name: name,
+        x:    area.x_position(offset.x),
+        y:    area.y_position(offset.y),
+      })
+    end
+
     # Returns a boolean indicating whether this interface is currently in focus.
     #
     # @return [Boolean]
@@ -80,6 +90,7 @@ module Vedeu
     def lines
       @lines ||= Line.coercer(attributes[:lines])
     end
+    alias_method :content, :lines
 
     # Returns the position and size of the interface.
     #
@@ -88,11 +99,29 @@ module Vedeu
       @geometry ||= Geometry.new(attributes[:geometry])
     end
 
+    # Returns the current offset for the content within the interface.
+    #
+    # @return [Offset]
+    def offset
+      @offset ||= Offsets.find_or_create(name)
+    end
+
+    # Returns the currently visible area of the interface.
+    #
+    # @return [Viewport]
+    def viewport
+      @_viewport ||= Viewport.show(self)
+    end
+
     private
 
+    # @return [Area]
+    def area
+      @_area ||= Area.from_interface(self)
+    end
+
     # The default values for a new instance of Interface.
     #
-    # @api private
     # @return [Hash]
     def defaults
       {
@@ -107,12 +136,14 @@ module Vedeu
       }
     end
 
-    # @api private
+    # @param method [Symbol] The name of the method sought.
+    # @param args [Array] The arguments which the method was to be invoked with.
+    # @param block [Proc] The optional block provided to the method.
     # @return []
     def method_missing(method, *args, &block)
       Vedeu.log("Interface#method_missing '#{method.to_s}' (args: #{args.inspect})")
 
-      @self_before_instance_eval.send(method, *args, &block)
+      @self_before_instance_eval.send(method, *args, &block) if @self_before_instance_eval
     end
 
   end # Interface

data/lib/vedeu/models/keymap.rb

@@ -13,7 +13,9 @@ module Vedeu
     # Define a keymap for an interface or interfaces to perform an action when
     # a key is pressed whilst an aforementioned interface is in focus.
     #
-    # @param attributes [Hash]
+    # @param attributes [Hash] The attributes to register the keymap with.
+    # @option attributes :interfaces []
+    # @option attributes :keys []
     # @param block [Proc]
     # @return [Keymap]
     def self.define(attributes = {}, &block)
@@ -48,7 +50,6 @@ module Vedeu
 
     # The default attributes of the Keymap model.
     #
-    # @api private
     # @return [Hash]
     def defaults
       {
@@ -57,12 +58,14 @@ module Vedeu
       }
     end
 
-    # @api private
+    # @param method [Symbol] The name of the method sought.
+    # @param args [Array] The arguments which the method was to be invoked with.
+    # @param block [Proc] The optional block provided to the method.
     # @return []
     def method_missing(method, *args, &block)
       Vedeu.log("Keymap#method_missing '#{method.to_s}' (args: #{args.inspect})")
 
-      @self_before_instance_eval.send(method, *args, &block)
+      @self_before_instance_eval.send(method, *args, &block) if @self_before_instance_eval
     end
 
   end # Keymap

data/lib/vedeu/models/line.rb

@@ -37,26 +37,44 @@ module Vedeu
       end
     end
 
-    # Returns a collection of streams associated with this line.
+    # Returns an array of all the characters with formatting for this line.
     #
     # @return [Array]
-    def streams
-      @streams ||= Stream.coercer(attributes[:streams])
+    # @see Vedeu::Stream
+    def chars
+      return [] if empty?
+
+      @_chars ||= streams.map(&:chars).flatten
     end
 
-    private
+    # Returns a boolean indicating whether the line has content.
+    #
+    # @return [Boolean]
+    def empty?
+      size == 0
+    end
 
-    # Convenience method to provide Presentation with a consistent interface.
+    # Returns the size of the content in characters without formatting.
+    #
+    # @return [Fixnum]
+    def size
+      streams.map(&:size).inject(0, :+) { |sum, x| sum += x }
+    end
+
+    # Returns a collection of streams associated with this line. This method
+    # also has the alias_method :data, a convenience method to provide
+    # Presentation with a consistent interface.
     #
-    # @api private
     # @return [Array]
-    def data
-      streams
+    def streams
+      @streams ||= Stream.coercer(attributes[:streams])
     end
+    alias_method :data, :streams
+
+    private
 
     # The default values for a new instance of Line.
     #
-    # @api private
     # @return [Hash]
     def defaults
       {
@@ -67,12 +85,14 @@ module Vedeu
       }
     end
 
-    # @api private
+    # @param method [Symbol] The name of the method sought.
+    # @param args [Array] The arguments which the method was to be invoked with.
+    # @param block [Proc] The optional block provided to the method.
     # @return []
     def method_missing(method, *args, &block)
       Vedeu.log("Line#method_missing '#{method.to_s}' (args: #{args.inspect})")
 
-      @self_before_instance_eval.send(method, *args, &block)
+      @self_before_instance_eval.send(method, *args, &block) if @self_before_instance_eval
     end
 
   end # Line