vedeu 0.4.40 → 0.4.41

data/lib/vedeu/dsl/border.rb

@@ -12,17 +12,20 @@ module Vedeu
     #   # Borders can be defined when defining your interface...
     #   Vedeu.interface 'my_interface' do
     #     border do
-    #       # ...
+    #     # ...
+    #   end
     #
     #   # ...or as part of a view definition...
     #   Vedeu.renders do
     #     view 'border_demo' do
     #       border do
-    #         # ...
+    #       # ...
+    #     end
     #
     #   # ...or standalone; referencing the target interface or view.
     #   Vedeu.border 'some_interface' do
     #     # ...
+    #   end
     #
     # @api public
     class Border
@@ -36,6 +39,7 @@ module Vedeu
       # @example
       #   Vedeu.border 'some_interface' do
       #     # ...
+      #   end
       #
       # @param name [String] The name of the interface or view to which this
       #   border belongs.
@@ -67,6 +71,9 @@ module Vedeu
       #       border do
       #         bottom_left '+'
       #         # ...
+      #       end
+      #     end
+      #   end
       #
       # @param char [String] Character to be used as the bottom left border
       #   character.
@@ -84,6 +91,9 @@ module Vedeu
       #       border do
       #         bottom_right '+'
       #         # ...
+      #       end
+      #     end
+      #   end
       #
       # @param char [String] Character to be used as the bottom right border
       #   character.
@@ -92,6 +102,31 @@ module Vedeu
         model.bottom_right = char
       end
 
+      # Disable this border.
+      #
+      # @return [Boolean]
+      def disable!
+        model.enabled = false
+
+        hide_bottom!
+        hide_left!
+        hide_right!
+        hide_top!
+      end
+
+      # Enable this border.
+      # (Borders are enabled by default if defined for an interface).
+      #
+      # @return [Boolean]
+      def enable!
+        model.enabled = true
+
+        show_bottom!
+        show_left!
+        show_right!
+        show_top!
+      end
+
       # Set the character to be used to draw a horizontal part of the border.
       #
       # @example
@@ -100,6 +135,9 @@ module Vedeu
       #       border do
       #         horizontal '-'
       #         # ...
+      #       end
+      #     end
+      #   end
       #
       # @param char [String] Character to be used as the horizontal border
       #   character.
@@ -119,6 +157,9 @@ module Vedeu
       #         hide_bottom!
       #         # ... or
       #         show_bottom!
+      #       end
+      #     end
+      #   end
       #
       # @param value [Boolean] All values evaluate as true except nil and
       #   false.
@@ -155,6 +196,9 @@ module Vedeu
       #         hide_left!
       #         # ... or
       #         show_left!
+      #       end
+      #     end
+      #   end
       #
       # @param value [Boolean] All values evaluate as true except nil and
       #   false.
@@ -191,6 +235,9 @@ module Vedeu
       #         hide_right!
       #         # ... or
       #         show_right!
+      #       end
+      #     end
+      #   end
       #
       # @param value [Boolean] All values evaluate as true except nil and
       #   false.
@@ -225,6 +272,9 @@ module Vedeu
       #       border do
       #         title 'My Cool Title'
       #         # ...
+      #       end
+      #     end
+      #   end
       #
       #   +- My Cool Title --------------------------------+
       #
@@ -245,6 +295,9 @@ module Vedeu
       #         hide_top!
       #         # ... or
       #         show_top!
+      #       end
+      #     end
+      #   end
       #
       # @param value [Boolean] All values evaluate as true except nil and
       #   false.
@@ -278,6 +331,9 @@ module Vedeu
       #       border do
       #         top_left '+'
       #         # ...
+      #       end
+      #     end
+      #   end
       #
       # @param char [String] Character to be used as the top left border
       #   character.

data/lib/vedeu/dsl/composition.rb

@@ -66,10 +66,11 @@ module Vedeu
       #
       # @example
       #   view 'my_interface' do
-      #     ...
+      #     # ...
+      #   end
       #
       # @raise [InvalidSyntax] The required block was not given.
-      # @return [Vedeu::Interfaces<Vedeu::Interface>]
+      # @return [Vedeu::InterfaceCollection<Vedeu::Interface>]
       def view(name = '', &block)
         fail InvalidSyntax, 'block not given' unless block_given?
 
@@ -85,6 +86,7 @@ module Vedeu
       #     template_for('my_interface',
       #                  '/path/to/template.erb',
       #                  @some_object, options)
+      #   end
       #
       # @todo More documentation required.
       #
@@ -96,7 +98,7 @@ module Vedeu
       # @param object [Object] The object for which the values of template's
       #   variables can be obtained.
       # @param options [Hash] See {Vedeu::Wordwrap}
-      # @return [Vedeu::Interfaces<Vedeu::Interface>]
+      # @return [Vedeu::InterfaceCollection<Vedeu::Interface>]
       def template_for(name, filename, object = nil, options = {})
         fail MissingRequired, 'Cannot render template without the name of ' \
                               'the view.' unless name

data/lib/vedeu/dsl/geometry.rb

@@ -11,7 +11,7 @@ module Vedeu
     #
     #   Vedeu.geometry 'some_interface' do
     #     # ...
-    #
+    #   end
     #
     #   This crude ASCII diagram represents a Geometry within Vedeu, each of the
     #   labels is a value you can access or define.
@@ -37,6 +37,7 @@ module Vedeu
       # @example
       #   Vedeu.geometry 'some_interface' do
       #     # ...
+      #   end
       #
       # @param name [String] The name of the interface or view to which this
       #   geometry belongs.
@@ -69,10 +70,12 @@ module Vedeu
       #   geometry 'some_interface' do
       #     centred!
       #     # ...
+      #   end
       #
       #   geometry 'some_interface' do
       #     centred false
       #     # ...
+      #   end
       #
       # @return [Boolean]
       def centred(value = true)
@@ -93,6 +96,7 @@ module Vedeu
       #   geometry 'some_interface' do
       #     height 8
       #     # ...
+      #   end
       #
       # @note
       #   This value will be ignored if by `y` and `yn` are set.
@@ -116,6 +120,7 @@ module Vedeu
       #   geometry 'some_interface' do
       #     width 25
       #     # ...
+      #   end
       #
       # @note
       #   This value will be ignored if by `x` and `xn` are set.
@@ -131,11 +136,12 @@ module Vedeu
       #   geometry 'some_interface' do
       #     x 7 # start on column 7.
       #     # ...
+      #   end
       #
       #   geometry 'some_interface' do
       #     x { use('other_interface').east } # start on column 8, if
       #     # ...                             # `other_interface` changes
-      #                                       # position, `some_interface` will
+      #   end                                 # position, `some_interface` will
       #                                       # too.
       #
       # @param value [Fixnum]
@@ -153,11 +159,12 @@ module Vedeu
       #   geometry 'some_interface' do
       #     xn 37 # end at column 37.
       #     # ...
+      #   end
       #
       #   geometry 'some_interface' do
       #     xn  { use('other_interface').right } # if `other_interface` changes
       #     # ...                                # position, `some_interface`
-      #                                          # will too.
+      #   end                                    # will too.
       #
       # @note
       #   This value will override `width`.
@@ -177,11 +184,12 @@ module Vedeu
       #   geometry 'some_interface' do
       #     y  4
       #     # ...
+      #   end
       #
       #   geometry 'some_interface' do
       #     y  { use('other_interface').north } # start on row/line 3, if
       #     # ...                               # `other_interface` changes
-      #                                         # position, `some_interface`
+      #   end                                   # position, `some_interface`
       #                                         # will too.
       #
       # @param value [Fixnum]
@@ -199,11 +207,12 @@ module Vedeu
       #   geometry 'some_interface' do
       #     yn 24 # end at row 24.
       #     # ...
+      #   end
       #
       #   geometry 'some_interface' do
       #     yn { use('other_interface').bottom } # if `other_interface` changes
       #     # ...                                # position, `some_interface`
-      #                                          # will too.
+      #   end                                    # will too.
       #
       # @note
       #   This value will override `height`.

data/lib/vedeu/dsl/group.rb

@@ -18,12 +18,14 @@ module Vedeu
       #   Vedeu.group 'title_screen' do
       #     add 'welcome_interface'
       #     # ...
+      #   end
       #
       #   Vedeu.group 'main_screen' do
       #     add 'editor_interface'
       #     add 'status_interface'
       #     add 'command_interface'
       #     # ...
+      #   end
       #
       # @note
       #   Creating a group with the same name as an existing group overwrites

data/lib/vedeu/dsl/interface.rb

@@ -70,14 +70,18 @@ module Vedeu
       #     cursor  :show # => both of these are equivalent to line above
       #     cursor!       #
       #     # ...
+      #   end
       #
+      #   interface 'my_interface' do
       #     cursor false # => hide the cursor for this interface
       #     cursor nil   # => as above
       #     # ...
+      #   end
       #
       #   view 'my_interface' do
-      #     cursor true
-      #     # ...
+      #     cursor true # => Specify the visibility of the cursor when the view
+      #     # ...       #    is rendered.
+      #   end
       #
       # @return [Cursor]
       def cursor(value = true)
@@ -103,6 +107,7 @@ module Vedeu
       #   interface 'my_interface' do
       #     delay 0.5 # interface will not update more often than every 500ms.
       #     # ...
+      #   end
       #
       # @return [Fixnum|Float]
       def delay(value)
@@ -112,7 +117,15 @@ module Vedeu
       # Specify this interface as being in focus when the application starts.
       #
       # @note If multiple interfaces are defined, and this is included in each,
-      #   then the last defined will be the interface in focus.
+      #   then the last defined will be the interface in focus. However, this
+      #   behaviour can be overridden:
+      #
+      #   ```ruby
+      #   Vedeu.focus_by_name 'some_interface'
+      #   ```
+      #
+      #   When the above is specified (outside of a `Vedeu.interface`
+      #   declaration), the named interface will be focussed instead.
       #
       # @return [String] The name of the interface in focus.
       def focus!
@@ -151,6 +164,7 @@ module Vedeu
       #   interface 'my_interface' do
       #     group 'main_screen'
       #     # ...
+      #   end
       #
       # @param name [String] The name of the group to which this interface
       #   should belong.
@@ -204,6 +218,7 @@ module Vedeu
       #   interface do
       #     name 'my_interface'
       #     # ...
+      #   end
       #
       # @return [String]
       def name(value)
@@ -250,14 +265,18 @@ module Vedeu
       #     visible true  # => show the interface
       #     show!         # => as above
       #     # ...
+      #   end
       #
+      #   interface 'my_interface' do
       #     visible false # => hide the interface
       #     hide!         # => as above
       #     # ...
+      #   end
       #
       #   view 'my_interface' do
       #     visible false
       #     # ...
+      #   end
       #
       # @return [void]
       def visible(value = true)
@@ -279,6 +298,7 @@ module Vedeu
       #   interface 'my_interface' do
       #     zindex 3
       #     # ...
+      #   end
       #
       # @param value [Fixnum]
       # @return [void]

data/lib/vedeu/dsl/keymap.rb

@@ -21,6 +21,8 @@ module Vedeu
       #   Vedeu.interface 'my_interface' do
       #     keymap do
       #       # ...
+      #     end
+      #   end
       #
       # @param name [String] The name of the interface which this keymap relates
       #   to.
@@ -29,17 +31,23 @@ module Vedeu
       # @example
       #   Vedeu.keymap 'my_interface' do
       #     # ...
+      #   end
       #
       #   Vedeu.keys 'my_interface' do
       #     # ...
+      #   end
       #
       #   Vedeu.interface 'my_interface' do
       #     keymap do
       #       # ...
+      #     end
+      #   end
       #
       #   Vedeu.interface 'my_interface' do
       #     keys do
       #       # ...
+      #     end
+      #   end
       #
       # @raise [InvalidSyntax] The required block was not given.
       # @return [Keymap]
@@ -76,9 +84,10 @@ module Vedeu
       #     key('h', :left) { Vedeu.trigger(:left) }
       #     key('j', :down) { Vedeu.trigger(:down) }
       #     key('p') do
-      #       ...
+      #       # ...
       #     end
-      #     ...
+      #     # ...
+      #   end
       #
       # @raise [InvalidSyntax] When the required block is not given, the
       #   value_or_values parameter is undefined, or when processing the
@@ -109,10 +118,6 @@ module Vedeu
       # available to all interfaces. Once a key has been defined in the
       # '_global_' keymap, it cannot be used for a specific interface.
       #
-      # @note Using the name of a keymap that already exists will overwrite that
-      #   keymap. Do not use the name '_system_' as unexpected behaviour may
-      #   occur.
-      #
       # @param value [String]
       # @return [String]
       def name(value)

data/lib/vedeu/dsl/line.rb

@@ -58,6 +58,9 @@ module Vedeu
       #
       #       line do
       #         # ...
+      #       end
+      #     end
+      #   end
       #
       # @raise [InvalidSyntax] When no block or value is provided.
       # @return [Vedeu::Lines]
@@ -90,9 +93,14 @@ module Vedeu
       #       line do
       #         streams do
       #           # ...
+      #         end
       #
       #         stream do
       #           # ...
+      #         end
+      #       end
+      #     end
+      #   end
       #
       # @raise [InvalidSyntax] The required block was not given.
       # @return [Vedeu::Streams<Vedeu::Stream>]

data/lib/vedeu/dsl/menu.rb

@@ -28,6 +28,7 @@ module Vedeu
       #   menu 'my_menu' do
       #     item SomeClass.new
       #     item SomeClass.new
+      #   end
       #
       # @return [Array]
       def item(element)
@@ -65,7 +66,8 @@ module Vedeu
       # @example
       #   menu do
       #     name 'my_menu'
-      #     ...
+      #     # ...
+      #   end
       #
       # @return [String]
       def name(value)

data/lib/vedeu/dsl/presentation.rb

@@ -32,6 +32,9 @@ module Vedeu
       #       stream do
       #         background '#22ff00'
       #         # ...
+      #       end
+      #     end
+      #   end
       #
       # @return [String]
       def background(value = '')
@@ -68,6 +71,9 @@ module Vedeu
       #       stream do
       #         colour background: '#000000', foreground: '#ffffff'
       #         # ...
+      #       end
+      #     end
+      #   end
       #
       # @return [Vedeu::Colour]
       def colour(attributes = {})
@@ -81,15 +87,18 @@ module Vedeu
       # @example
       #   interface 'my_interface' do
       #     style 'normal'
-      #     ...
+      #     # ...
+      #   end
       #
       #   lines do
       #     style ['bold', 'underline']
-      #     ...
+      #     # ...
+      #   end
       #
       #   stream do
       #     style 'blink'
-      #     ...
+      #     # ...
+      #   end
       #
       # @return [Vedeu::Style]
       def style(value)

data/lib/vedeu/dsl/text.rb

@@ -16,9 +16,11 @@ module Vedeu
       # @example
       #   lines do
       #     centre '...'
+      #   end
       #
       #   line do
       #     right '...'
+      #   end
       #
       #   left 'This will be left aligned.', width: 35
       #   # => 'This will be left aligned.         '

data/lib/vedeu/dsl/view.rb

@@ -23,10 +23,12 @@ module Vedeu
         # @example
         #   Vedeu.interface 'my_interface' do
         #     # ...
+        #   end
         #
         #   Vedeu.interface do
         #     name 'interfaces_must_have_a_name'
         #     # ...
+        #   end
         #
         # @raise [InvalidSyntax] The required block was not given.
         # @return [Interface]
@@ -51,6 +53,8 @@ module Vedeu
         #   Vedeu.renders do
         #     view 'my_interface' do
         #       # ...
+        #     end
+        #   end
         #
         # @raise [InvalidSyntax] The required block was not given.
         # @return [Array<Interface>]
@@ -81,7 +85,8 @@ module Vedeu
         #     view 'my_other_interface' do
         #       # ... some other attributes ...
         #     end
-        #     ...
+        #     # ...
+        #   end
         #
         # @raise [InvalidSyntax] The required block was not given.
         # @return [Array<Interface>]

data/lib/vedeu/events/event.rb

@@ -90,6 +90,8 @@ module Vedeu
 
       # Unbind events from a named handler.
       #
+      # Removes all events associated with the given name.
+      #
       # @example
       #   Vedeu.unbind('some_event')
       #
@@ -131,7 +133,7 @@ module Vedeu
         new_collection = repository.find(name).add(self)
 
       else
-        new_collection = Vedeu::Events.new([self], nil, name)
+        new_collection = Vedeu::EventCollection.new([self], nil, name)
 
       end
 

data/lib/vedeu/generator/application.rb

@@ -20,6 +20,8 @@ module Vedeu
         new(name).generate
       end
 
+      # Returns a new instance of Vedeu::Generator::Application.
+      #
       # @param name [String] The name of the application.
       # @return [Vedeu::Generator::Application]
       def initialize(name)
@@ -35,7 +37,6 @@ module Vedeu
         copy_application_controller
         copy_application_helper
         copy_global_keymap
-        copy_system_keymap
         copy_application_executable
         make_application_executable
         copy_configuration
@@ -99,12 +100,6 @@ module Vedeu
                   "#{name}/app/models/keymaps/_global_.rb")
       end
 
-      # @return [void]
-      def copy_system_keymap
-        copy_file(source + '/app/models/keymaps/_system_.rb',
-                  "#{name}/app/models/keymaps/_system_.rb")
-      end
-
       # @return [Array<String>]
       def directories
         [

data/lib/vedeu/generator/templates/application/app/models/keymaps/_global_.rb

@@ -1,3 +1,8 @@
 Vedeu.keymap('_global_') do
   # see http://www.rubydoc.info/gems/vedeu/Vedeu/DSL/Keymap
+
+  key('q')        { Vedeu.trigger(:_exit_) }
+  key(:esc)       { Vedeu.trigger(:_mode_switch_) }
+  key(:shift_tab) { Vedeu.trigger(:_focus_previous_) }
+  key(:tab)       { Vedeu.trigger(:_focus_next_) }
 end

data/lib/vedeu/generator/templates/application/app/views/interfaces/name.erb

@@ -5,6 +5,12 @@ Vedeu.interface '<%= object.name %>' do
     # style  'normal'
 
     # Define visibility of border
+    #
+    # Uncomment one of these:
+    # enable!
+    # disable!
+    #
+    # Individually control each border:
     # show_bottom!
     # show_left!
     # show_right!
@@ -24,8 +30,12 @@ Vedeu.interface '<%= object.name %>' do
 
   # background
 
+  # colour
+
   # cursor!
 
+  # focus!
+
   # foreground
 
   # geometry do

data/lib/vedeu/generator/view.rb

@@ -22,6 +22,8 @@ module Vedeu
         new(name).generate
       end
 
+      # Returns a new instance of Vedeu::Generator::View.
+      #
       # @param name [String] The name of the view.
       # @return [Vedeu::Generator::View]
       def initialize(name)

data/lib/vedeu/geometry/geometry.rb

@@ -103,6 +103,12 @@ module Vedeu
       "maximise:#{maximised}>"
     end
 
+    # Will maximise the named interface geometry. This means it will occupy all
+    # of the available space on the terminal window.
+    #
+    # @example
+    #   Vedeu.trigger(:_maximise_, name)
+    #
     # @return [Vedeu::Geometry|NilClass]
     def maximise
       return self if maximised?
@@ -116,6 +122,14 @@ module Vedeu
       work
     end
 
+    # Will unmaximise the named interface geometry. Previously, if a geometry
+    # was maximised, then triggering the unmaximise event will return it to its
+    # usual defined size (terminal size permitting: if the terminal has been
+    # resized, then the new geometry size should adapt).
+    #
+    # @example
+    #   Vedeu.trigger(:_unmaximise_, name)
+    #
     # @return [Vedeu::Geometry|NilClass]
     def unmaximise
       return self unless maximised?