vedeu 0.1.19 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f042b9de9119e64b521192d7d59b203d54f7cd0b
-  data.tar.gz: 1e1bd9c449e053e95d163dbfd8833515f21e9f8d
+  metadata.gz: fa08f6802848478327fb38d44b28b19ffbb78d75
+  data.tar.gz: 8e30625c919e7d3c678c7301c707904e5ac70328
 SHA512:
-  metadata.gz: 8b6492e5404edf7622295e205fb8479537671b4dda4d9817a3b9ed2cf0c144b58ab13ec6e7cd786482995f33def8574c2c736ac8fff93a0d4f54cbae10d38083
-  data.tar.gz: 7709bce2742998b9e90c7f8521b4b3d131623ac3b0c35c3b91f98d9cd18f03952e7aba5d54cf2128ed35f1f3319f38adb3607f4511b03508e5d21a28e600bc39
+  metadata.gz: 50aaa91ab6b23ce968ab31fa9100959c8a05f21d9accffd2f3444a53474fa16c6b30527aa4aca79e4ce35fd5dece0799ed101b6e5c9ad171bddc44734ad94bb7
+  data.tar.gz: 7dafc1f4a3f8fa836e05f665ef005c30550632bce5e92eb1ba69abe435e48b159b94268448c7465392816692e625e48f5b129bb573eedc86564eeef64c58af07

data/docs/api.md

@@ -14,7 +14,7 @@ Doing it this way will mean you can use any API method without the `Vedeu.` pref
 ```ruby
 class SomeClassInYourApplication
   include Vedeu
-  
+
   ...
 ```
 
@@ -26,11 +26,11 @@ Doing it this way means you need to use the `Vedeu.` prefix.
 ```ruby
 class OtherClassInYourApplication
   ...
-   
+
   def some_method
-    Vedeu.some_api_method   
+    Vedeu.some_api_method
   end
-   
+
   ...
 ```
 
@@ -46,6 +46,7 @@ height
 interface
 keypress
 log
+menu
 resize
 trigger
 unevent
@@ -69,6 +70,9 @@ width
 height
 centred
 
+items
+name
+
 stream
 text
 foreground
@@ -76,4 +80,4 @@ background
 
 align
 text
-width
+width

data/docs/events.md

@@ -1,7 +1,7 @@
 ## Vedeu Events
 
 Vedeu provides an event mechanism to facilitate the functionality of your
-application. The events are either Vedeu defined, ie. system events or 
+application. The events are either Vedeu defined, ie. system events or
 user defined, ie. user events.
 
 Events described in this document assume that you have included Vedeu in your
@@ -14,64 +14,111 @@ class:
     ...
 ```
 
-### System Events
+## System Events
 
 System events generally control the internal state of Vedeu with respects to
 your application. They are soft-namespaced using underscores.
 
-#### `:_cleanup_`
+### `:_cleanup_`
 
 This event is fired by Vedeu 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.
 
-#### `:_clear_`
+### `:_clear_`
 
 Clears the whole terminal space.
 
-#### `:_exit_` 
+### `:_exit_`
 
 When triggered, Vedeu will trigger a `:_cleanup_` event which you can define (to save files, etc) and attempt to exit.
 
-#### `:_focus_by_name_` 
+### `:_focus_by_name_`
 
 When triggered with an interface name will focus that interface.
 
-#### `:_focus_next_`
+### `:_focus_next_`
 
-When triggered will focus the next interface. 
+When triggered will focus the next interface.
 
-#### `:_focus_prev_`
+### `:_focus_prev_`
 
 When triggered will focus the previous interface.
 
-#### `:_initialize_`
+### `:_initialize_`
 
 Special event which Vedeu triggers 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.
 
-#### `:_keypress_`
+### `:_keypress_`
 
 Triggering this event 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.
 
-#### `:_log_` 
+### `:_log_`
 
 When triggered with a message will cause Vedeu to log the message if logging is enabled in the configuration.
 
-#### `:_mode_switch_`
+### `:_menu_current_`
+
+Requires target menu name as argument. Returns the current menu item.
+
+### `:_menu_selected_`
+
+Requires target menu name as argument. Returns the selected menu item.
+
+### `:_menu_next_`
+
+Requires target menu name as argument. Makes the next menu item the current menu
+item, until it reaches the last item.
+
+### `:_menu_prev_`
+
+Requires target menu name as argument. Makes the previous menu item the current
+menu item, until it reaches the first item.
+
+### `:_menu_top_`
+
+Requires target menu name as argument. Makes the first menu item the current
+menu item.
+
+### `:_menu_bottom_`
+
+Requires target menu name as argument. Makes the last menu item the current menu
+item.
+
+### `:_menu_select_`
+
+Requires target menu name as argument. Makes the current menu item also the
+selected menu item.
+
+### `:_menu_deselect_`
+
+Requires target menu name as argument. Deselects all menu items.
+
+### `:_menu_items_`
+
+Requires target menu name as argument. Returns all the menu items with
+respective `current` or `selected` boolean indicators.
+
+### `:_menu_view_`
+
+Requires target menu name as argument. Returns a subset of the menu items;
+starting at the current item to the last item.
+
+### `:_mode_switch_`
 
 When triggered (after the user presses `escape`), Vedeu switches from a "raw mode" terminal to a "cooked mode" terminal. The idea here being that the raw mode is for single keypress actions, whilst cooked mode allows the user to enter more elaborate commands- such as commands with arguments.
 
-#### `:_refresh_`
+### `:_refresh_`
 
 Triggering this event will cause all interfaces to refresh.
 
-#### `:_refresh_group_(group_name)_`
+### `:_refresh_group_(group_name)_`
 
 Will refresh all interfaces belonging to this group. E.g. `_refresh_group_home_` will refresh all interfaces with the group of `home`.
 
-#### `:_refresh_(interface_name)_`
+### `:_refresh_(interface_name)_`
 
 Will refresh the interface with this name. E.g. `_refresh_widget_` will refresh the interface `widget`.
 
-#### `:_resize_`
+### `:_resize_`
 
 When triggered will cause Vedeu to trigger the `:_clear_` and `:_refresh_`
 events. Please see those events for their behaviour.

data/lib/vedeu.rb

@@ -19,6 +19,9 @@ module Vedeu
   # encounters a problem.
   InvalidSyntax = Class.new(StandardError)
 
+  # Raised when a menu cannot be found by name.
+  MenuNotFound = Class.new(StandardError)
+
   # Raised intentionally when the client application wishes to switch between
   # cooked and raw (or vice versa) terminal modes. Vedeu is hard-wired to use
   # the `Escape` key to trigger this change for the time being.
@@ -90,8 +93,10 @@ require 'vedeu/api/composition'
 require 'vedeu/api/helpers'
 require 'vedeu/api/interface'
 require 'vedeu/api/line'
+require 'vedeu/api/menu'
 require 'vedeu/api/stream'
 
+require 'vedeu/repositories/menus'
 require 'vedeu/repositories/interfaces'
 require 'vedeu/repositories/groups'
 require 'vedeu/repositories/focus'

data/lib/vedeu/api/api.rb

@@ -158,6 +158,29 @@ module Vedeu
       Vedeu::Log.logger.debug(message) if Configuration.debug? || force
     end
 
+    # Register a menu by name which will display output from a event or
+    # command. This provides the means for you to define your application's
+    # views without their content.
+    #
+    # @api public
+    # @param name  [String] The name of the menu. Used to reference the
+    #   menu throughout your application's execution lifetime.
+    # @param block [Proc] A set of attributes which define the features of the
+    #   menu. TODO: More help.
+    #
+    # @example
+    #   Vedeu.menu 'my_interface' do
+    #     ...
+    #
+    #   Vedeu.menu do
+    #     name 'menus_must_have_a_name'
+    #     ...
+    #
+    # @return [API::Menu]
+    def menu(name = '', &block)
+      API::Menu.define({ name: name }, &block)
+    end
+
     # When the terminal emit the 'SIGWINCH' signal, Vedeu can intercept this
     # and attempt to redraw the current interface with varying degrees of
     # success. Can also be used to simulate a terminal resize.
@@ -172,7 +195,8 @@ module Vedeu
     end
     # :nocov:
 
-    # Trigger a registered or system event by name with arguments.
+    # Trigger a registered or system event by name with arguments. If the
+    # event stored returns a value, that is returned.
     #
     # @api public
     # @param name [Symbol] The name of the event you wish to trigger.
@@ -182,11 +206,21 @@ module Vedeu
     # @example
     #   Vedeu.trigger(:my_event, :oxidize, 'nitrogen')
     #
-    # @return [Array]
+    # @return [Array|undefined]
     def trigger(name, *args)
       Vedeu.events.trigger(name, *args)
     end
 
+    # Unregisters the event by name, effectively deleting the associated events
+    # bound with it also.
+    #
+    # @api public
+    # @param name [Symbol]
+    # @return [Hash]
+    def unevent(name)
+      Vedeu.events.unevent(name)
+    end
+
     # Use attributes of another interface whilst defining one. TODO: More help.
     #
     # @api public
@@ -261,16 +295,6 @@ module Vedeu
       Terminal.width
     end
 
-    # Unregisters the event by name, effectively deleting the associated events
-    # bound with it also.
-    #
-    # @api public
-    # @param name [Symbol]
-    # @return [Hash]
-    def unevent(name)
-      Vedeu.events.unevent(name)
-    end
-
   end
 
   extend API

data/lib/vedeu/api/menu.rb

@@ -0,0 +1,111 @@
+module Vedeu
+  module API
+
+    # Provides the mechanism to create menus within client applications and use
+    # events to drive them.
+    class Menu
+
+      include Common
+
+      attr_reader :attributes
+
+      # @param attributes [Hash]
+      # @param block [Proc]
+      # @return [API::Menu]
+      def self.define(attributes = {}, &block)
+        new(attributes).define(&block)
+      end
+
+      # Return a new instance of Menu.
+      #
+      # @param  attributes [Hash]
+      # @return [API::Menu]
+      def initialize(attributes = {})
+        @attributes = defaults.merge!(attributes)
+      end
+
+      # @param block [Proc]
+      # @return [API::Menu]
+      def define(&block)
+        fail InvalidSyntax, '`menu` requires a block.' unless block_given?
+
+        @self_before_instance_eval = eval('self', block.binding)
+
+        instance_eval(&block)
+
+        validate_attributes!
+
+        Vedeu::Menus.add(attributes)
+
+        self
+      end
+
+      # Define the items for the menu. Most powerful when used with one of your
+      # model classes.
+      #
+      # In the 'my_playlist' example below, your `Track` model may return a
+      # collection of tracks to populate the menu.
+      #
+      # @api public
+      # @param collection [Array]
+      #
+      # @example
+      #   menu 'my_menu' do
+      #     items [:item_1, :item_2, :item_3]
+      #   end
+      #
+      #   menu 'my_playlist' do
+      #     items Track.all_my_favourites
+      #   end
+      #
+      # @return [Vedeu::Menu]
+      def items(collection = [])
+        attributes[:items] = Vedeu::Menu.new(collection)
+      end
+
+      # The name of the menu. Used to reference the menu throughout your
+      # application's execution lifetime.
+      #
+      # @api public
+      # @param value [String]
+      #
+      # @example
+      #   menu do
+      #     name 'my_menu'
+      #     ...
+      #
+      # @return [String]
+      def name(value)
+        attributes[:name] = value
+      end
+
+      private
+
+      # The default values for a new instance of Menu.
+      #
+      # @api private
+      # @return [Hash]
+      def defaults
+        {
+          name:  '',
+          items: []
+        }
+      end
+
+      # @api private
+      # @return [TrueClass|FalseClass]
+      def validate_attributes!
+        unless defined_value?(attributes[:name])
+          fail InvalidSyntax, 'Menus must have a `name`.'
+        end
+      end
+
+      # @api private
+      # @return []
+      def method_missing(method, *args, &block)
+        @self_before_instance_eval.send(method, *args, &block)
+      end
+
+    end
+  end
+end

data/lib/vedeu/launcher.rb

@@ -48,6 +48,7 @@ module Vedeu
 
     private
 
+    # @return [Array]
     attr_reader :argv
 
   end

data/lib/vedeu/models/attributes/colour_translator.rb

@@ -60,6 +60,7 @@ module Vedeu
 
     private
 
+    # @return [Fixnum|NilClass|Symbol|String]
     attr_reader :colour
 
     # @api private

data/lib/vedeu/models/colour.rb

@@ -7,6 +7,7 @@ module Vedeu
   # @api private
   class Colour
 
+    # @return [Hash]
     attr_reader :attributes
 
     # Returns a new instance of Colour.

data/lib/vedeu/models/composition.rb

@@ -65,6 +65,7 @@ module Vedeu
     end
 
     # @api private
+    # @return []
     def method_missing(method, *args, &block)
       @self_before_instance_eval.send(method, *args, &block)
     end

data/lib/vedeu/models/geometry.rb

@@ -6,7 +6,17 @@ module Vedeu
   # @api private
   class Geometry
 
-    attr_reader :attributes, :centred, :height, :width
+    # @return [Hash]
+    attr_reader :attributes
+
+    # @return [TrueClass|FalseClass]
+    attr_reader :centred
+
+    # @return [Fixnum]
+    attr_reader :height
+
+    # @return [Fixnum]
+    attr_reader :width
 
     # Returns a new instance of Geometry.
     #