Class: Vedeu::DSL::Views

Inherits:

Object

• Object
• Vedeu::DSL::Views

Includes:

Vedeu::DSL, Border, Cursors, Elements, Geometry, Use

Defined in:

lib/vedeu/dsl/views.rb

Overview

There are two ways to construct views with Vedeu. You would like to draw the view to the screen immediately (immediate render) or you want to save a view to be drawn when you trigger a refresh event later (deferred view).

Both of these approaches require that you have defined an interface (or ‘visible area’) first. You can find out how to define an interface with Vedeu below or in Interfaces::DSL. The examples in ‘Immediate Render’ and ‘Deferred View’ use these interface definitions: (Note: should you use these examples, ensure your terminal is at least 70 characters in width and 5 lines in height.)

Vedeu.interface :main do
  geometry do
    height 4
    width  50
  end
end

Vedeu.interface :title do
  geometry do
    height 1
    width  50
    x      use('main').left
    y      use('main').north
  end
end

Both of these approaches use a concept of Buffers in Vedeu. There are three buffers for any defined interface. These are imaginatively called: ‘back’, ‘front’ and ‘previous’.

The ‘back’ buffer is the content for an interface which will be shown next time a refresh event is fired globally or for that interface. So, ‘back’ becomes ‘front’.

The ‘front’ buffer is the content for an interface which is currently showing. When a refresh event is fired, again, globally or for that interface specifically, the content of this ‘front’ buffer is first copied to the ‘previous’ buffer, and then the current ‘back’ buffer overwrites this ‘front’ buffer.

The ‘previous’ buffer contains what was shown on the ‘front’ before the current ‘front’.

You can only write to either the ‘front’ (you want the content to be drawn immediately (immediate render)) or the ‘back’ (you would like the content to be drawn on the next refresh (deferred view)).

The basic view DSL methods look like this:

renders/views
  |- view
      |- lines
      |   |- line
      |       |- streams
      |       |   |- stream
      |       |       |- char
      |       |
      |       |- stream
      |           |- char
      |
      |- line
          |- streams
          |   |- stream
          |       |- char
          |
          |- stream
              |- char

renders/views
  |- view
      |- lines/line
          |- streams/stream
              |- char

Instance Attribute Summary

• #client ⇒ Object included from Vedeu::DSL readonly protected

  The object instance where the DSL is being used.

• #model ⇒ void included from Vedeu::DSL readonly protected

  The new model object which the DSL is constructing.

Class Method Summary

• .composition(client, refresh = false, &block) ⇒ Object private

  Creates a new Vedeu::Views::Composition which may contain one or more view Views::View objects.

• .renders(&block) ⇒ Vedeu::Views::Composition (also: render)

• .views(&block) ⇒ Vedeu::Views::Composition

Instance Method Summary

• #absent?(variable) ⇒ Boolean included from Common private

  Returns a boolean indicating whether a variable is nil or empty.

• #attributes ⇒ Hash<Symbol => void> included from Vedeu::DSL private

  Returns the default attributes for the new model.

• #background(value = '') ⇒ String (also: #bg, #bgcolor, #background=, #bg=, #bgcolor=) included from Presentation

  Define the background colour for an interface, line, or a stream.

• #become(klass, attributes) ⇒ Class included from Common private

  Converts one class into another.

• #boolean(value) ⇒ Boolean included from Common private

  Returns a boolean indicating the value was a boolean.

• #boolean?(value) ⇒ Boolean included from Common private

  Returns a boolean indicating whether the value is a Boolean.

• #centre(value = '', opts = {}) ⇒ void (also: #center) included from Elements
• #colour(attrs = {}) ⇒ Vedeu::Colours::Colour (also: #colour=) included from Presentation

  Define either or both foreground and background colours for an interface, line or a stream.

• #colour_attributes ⇒ Hash<Symbol => String> included from Presentation private
• #cursor(value = true) ⇒ Vedeu::Cursors::Cursor included from Cursors

  Set the cursor visibility on an interface.

• #cursor! ⇒ Vedeu::Cursors::Cursor (also: #show_cursor!) included from Cursors

  Set the cursor to visible for the interface or view.

• #escape?(value) ⇒ Boolean included from Common private

  Returns a boolean indicating whether the value is an escape sequence object (e.g. Cells::Escape.).

• #falsy?(value) ⇒ Boolean included from Common private

  Returns a boolean indicating whether the value should be considered false.

• #foreground(value = '') ⇒ Object (also: #fg, #fgcolor, #foreground=, #fg=, #fgcolor=) included from Presentation
• #hash?(value) ⇒ Boolean included from Common private

  Returns a boolean indicating whether the value is a Hash.

• #initialize(model, client = nil) ⇒ void included from Vedeu::DSL

  Returns a new instance of the DSL class including Vedeu::DSL.

• #left(value = '', opts = {}) ⇒ void included from Elements
• #line(value = '', opts = {}, &block) ⇒ void included from Elements

  Specify a single line in a view.

• #line_model? ⇒ Boolean included from Common private

  Returns a boolean indicating the model is a Views::Line.

• #lines(opts = {}, &block) ⇒ void (also: #streams) included from Elements

  Specify multiple lines in a view.

• #method_missing(method, *args, &block) ⇒ void included from Vedeu::DSL private

  Attempts to find the missing method on the client object.

• #name ⇒ NilClass|String|Symbol included from Vedeu::DSL

  Returns the model name if available.

• #no_cursor! ⇒ Vedeu::Cursors::Cursor (also: #hide_cursor!) included from Cursors

  Set the cursor to invisible for the interface or view.

• #numeric?(value) ⇒ Boolean included from Common private

  Returns a boolean indicating whether the value is a Fixnum.

• #present?(variable) ⇒ Boolean included from Common private

  Returns a boolean indicating whether a variable has a useful value.

• #requires_block!(&block) ⇒ NilClass included from Elements private
• #requires_model! ⇒ NilClass included from Elements private
• #right(value = '', opts = {}) ⇒ void included from Elements
• #snake_case(klass) ⇒ String included from Common private

  Converts a class name to a lowercase snake case string.

• #stream(value = '', opts = {}, &block) ⇒ void included from Elements
• #stream_model? ⇒ Boolean included from Common private

  Returns a boolean indicating the model is a Views::Stream.

• #string?(value) ⇒ Boolean included from Common private

  Returns a boolean indicating whether the value is a Fixnum.

• #style(value) ⇒ Vedeu::Presentation::Style (also: #style=, #styles, #styles=) included from Presentation

  Define a style or styles for an interface, line or a stream.

• #text(value = '', opts = {}) ⇒ void included from Elements

  Specify the content for a view.

• #truthy?(value) ⇒ Boolean included from Common private

  Returns a boolean indicating whether the value should be considered true.

• #use(name) ⇒ void included from Use

  Use the attribute of stored model.

• #view_model? ⇒ Boolean included from Common private

  Returns a boolean indicating the model is a Views::View.

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Vedeu::DSL

Instance Attribute Details

#client ⇒ Object (readonly, protected) Originally defined in module Vedeu::DSL

Returns The object instance where the DSL is being used.

Returns:

• (Object) —

  The object instance where the DSL is being used.

#model ⇒ void (readonly, protected) Originally defined in module Vedeu::DSL

This method returns an undefined value.

Returns The new model object which the DSL is constructing.

Class Method Details

.composition(client, refresh = false, &block) ⇒ Object (private)

Creates a new Vedeu::Views::Composition which may contain one or more view Views::View objects.

# @return [Vedeu::Views::Composition]

Parameters:

• client (Object) —

  The client class which called the DSL object.

• refresh (Boolean) (defaults to: false)
• block (Proc) —

  The directives you wish to send to render. Typically includes ‘view` with associated sub-directives.

# File 'lib/vedeu/dsl/views.rb', line 133

def composition(client, refresh = false, &block)
  attrs = { client: client, colour: Vedeu.config.colour }

  Vedeu::Views::Composition.build(attrs, &block).update_buffers(refresh)
end

.renders(&block) ⇒ Vedeu::Views::Composition Also known as: render

Parameters:

• block (Proc) —

  The directives you wish to send to render. Typically includes ‘view` with associated sub-directives.

Returns:

• (Vedeu::Views::Composition)

Raises:

• (Vedeu::Error::RequiresBlock) —

  When the required block was not given.

# File 'lib/vedeu/dsl/views.rb', line 102

def renders(&block)
  fail Vedeu::Error::RequiresBlock unless block_given?

  composition(eval('self', block.binding), true, &block)
end

.views(&block) ⇒ Vedeu::Views::Composition

Parameters:

• block (Proc) —

  The directives you wish to send to render. Typically includes ‘view` with associated sub-directives.

Returns:

• (Vedeu::Views::Composition)

Raises:

• (Vedeu::Error::RequiresBlock) —

  When the required block was not given.

# File 'lib/vedeu/dsl/views.rb', line 115

def views(&block)
  fail Vedeu::Error::RequiresBlock unless block_given?

  composition(eval('self', block.binding), false, &block)
end

Instance Method Details

#absent?(variable) ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating whether a variable is nil or empty.

Parameters:

• variable (String|Symbol|Array|Fixnum) —

  The variable to check.

Returns:

• (Boolean)

#attributes ⇒ Hash<Symbol => void> (private) Originally defined in module Vedeu::DSL

Note:

Specific DSL classes may be overriding this method.

Returns the default attributes for the new model.

Returns:

• (Hash<Symbol => void>)

#background(value = '') ⇒ String Also known as: bg, bgcolor, background=, bg=, bgcolor= Originally defined in module Presentation

Note:

The last defined background colour for a particular interface, line or stream overrides previously defined entries in the same block.

Define the background colour for an interface, line, or a stream. When called with a block, will create a new stream with the background colour specified. When the block terminates, the background will return to that of the parent.

Examples:

interface 'my_interface' do
  background '#0022ff' # /or/ (blue)
  bgcolor    '#22ff00' # /or/ (blue is overridden to green)
  bg         '#ff0022' #      (green is overridden to red)
  # ...

  lines do
    background '#2200ff'
    # ...

    stream do
      background '#22ff00'
      # ...
    end
  end
end

Parameters:

• value (String) (defaults to: '') —

  A HTML/CSS value.

Returns:

• (String)

#become(klass, attributes) ⇒ Class Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Converts one class into another.

Parameters:

• klass (Class) —

  The class to become an instance of.

• attributes (Hash) —

  The attributes of klass.

Returns:

• (Class) —

  Returns a new instance of klass.

#boolean(value) ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating the value was a boolean.

Parameters:

• value (void)

Returns:

• (Boolean)

#boolean?(value) ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating whether the value is a Boolean.

Parameters:

• value (Boolean)

Returns:

• (Boolean)

#centre(value = '', opts = {}) ⇒ void Also known as: center Originally defined in module Elements

This method returns an undefined value.

Parameters:

• value (String|Object) (defaults to: '') —

  A string or object that responds to ‘to_s`.

• opts (Hash<Symbol => void>) (defaults to: {}) —

  Text options.

#colour(attrs = {}) ⇒ Vedeu::Colours::Colour Also known as: colour= Originally defined in module Presentation

Note:

Rejects invalid keys and empty/nil attributes. Also, the last defined colour for a particular interface, line or stream overrides previously defined entries in the same block.

Define either or both foreground and background colours for an interface, line or a stream. At least one attribute is required.

Examples:

interface 'my_interface' do
  colour background: '#ff00ff', foreground: '#ffff00'
  # ...

  lines do
    colour background: '#000000', foreground: '#ffffff'
    # ...

    stream do
      colour background: '#000000', foreground: '#ffffff'
      # ...
    end
  end
end

Parameters:

• attrs (Hash<Symbol => void>) (defaults to: {}) —

  See Colours::Colour

Returns:

• (Vedeu::Colours::Colour)

#colour_attributes ⇒ Hash<Symbol => String> (private) Originally defined in module Presentation

Returns:

• (Hash<Symbol => String>)

#cursor(value = true) ⇒ Vedeu::Cursors::Cursor Originally defined in module Cursors

Set the cursor visibility on an interface.

Parameters:

• value (Boolean) (defaults to: true) —

  Any value other than nil or false will evaluate to true.

Returns:

• (Vedeu::Cursors::Cursor)

#cursor! ⇒ Vedeu::Cursors::Cursor Also known as: show_cursor! Originally defined in module Cursors

Set the cursor to visible for the interface or view.

Returns:

• (Vedeu::Cursors::Cursor)

#escape?(value) ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating whether the value is an escape sequence object (e.g. Vedeu::Cells::Escape.)

Returns:

• (Boolean)

#falsy?(value) ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating whether the value should be considered false.

Parameters:

• value (void)

Returns:

• (Boolean)

#foreground(value = '') ⇒ Object Also known as: fg, fgcolor, foreground=, fg=, fgcolor= Originally defined in module Presentation

See Also:

• #background

#hash?(value) ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating whether the value is a Hash.

Parameters:

• value (Hash|void)

Returns:

• (Boolean)

#initialize(model, client = nil) ⇒ void Originally defined in module Vedeu::DSL

Returns a new instance of the DSL class including Vedeu::DSL.

Parameters:

• model (void) —

  The model class which the DSL class is wrapping.

• client (void) (defaults to: nil) —

  The class where the DSL methods are being used.

#left(value = '', opts = {}) ⇒ void Originally defined in module Elements

This method returns an undefined value.

Parameters:

• value (String|Object) (defaults to: '') —

  A string or object that responds to ‘to_s`.

• opts (Hash<Symbol => void>) (defaults to: {}) —

  Text options.

#line(value = '', opts = {}, &block) ⇒ void Originally defined in module Elements

TODO:

This documentation needs editing. (GL: 2015-12-17)

This method returns an undefined value.

Specify a single line in a view.

Vedeu.renders do
  view :my_interface do
    lines do
      line 'some text...'
      # ... some code

      line 'some more text...'
      # ... some code
    end
  end
end

Parameters:

• value (String) (defaults to: '') —

  The value for the line. Ignored when a block is given.

• opts (Hash) (defaults to: {})
• block (Proc)

Options Hash (opts):

• ... (void)

Raises:

• (Vedeu::Error::Fatal)

#line_model? ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating the model is a Views::Line.

Returns:

• (Boolean)

#lines(opts = {}, &block) ⇒ void Also known as: streams Originally defined in module Elements

TODO:

This documentation needs editing. (GL: 2015-12-17)

This method returns an undefined value.

Specify multiple lines in a view.

Examples:

Vedeu.view :my_interface do
  lines do
    # ... see {Vedeu::DSL::Line} and {Vedeu::DSL::Stream}
  end
end

Vedeu.view :my_interface do
  line do
    # ... see {Vedeu::DSL::Line} and {Vedeu::DSL::Stream}
  end
end

Parameters:

• block (Proc)

Raises:

• (Vedeu::Error::RequiresBlock) —

  When the required block was not given.

• (Vedeu::Error::Fatal)

#name ⇒ NilClass|String|Symbol Originally defined in module Vedeu::DSL

Returns the model name if available.

Returns:

• (NilClass|String|Symbol)

#no_cursor! ⇒ Vedeu::Cursors::Cursor Also known as: hide_cursor! Originally defined in module Cursors

Set the cursor to invisible for the interface or view.

Returns:

• (Vedeu::Cursors::Cursor)

#numeric?(value) ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating whether the value is a Fixnum.

Parameters:

• value (Fixnum|void)

Returns:

• (Boolean)

#present?(variable) ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating whether a variable has a useful value.

Parameters:

• variable (String|Symbol|Array|Fixnum) —

  The variable to check.

Returns:

• (Boolean)

#requires_block!(&block) ⇒ NilClass (private) Originally defined in module Elements

Parameters:

• block (Proc)

Returns:

• (NilClass)

Raises:

• (Vedeu::Error::RequiresBlock) —

  When the required block was not given.

#requires_model! ⇒ NilClass (private) Originally defined in module Elements

Returns:

• (NilClass)

Raises:

• (Vedeu::Error::Fatal) —

  When the model cannot be determined.

#right(value = '', opts = {}) ⇒ void Originally defined in module Elements

This method returns an undefined value.

Parameters:

• value (String|Object) (defaults to: '') —

  A string or object that responds to ‘to_s`.

• opts (Hash<Symbol => void>) (defaults to: {}) —

  Text options.

#snake_case(klass) ⇒ String Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Converts a class name to a lowercase snake case string.

Examples:

snake_case(MyClassName) # => "my_class_name"
snake_case(NameSpaced::ClassName)
# => "name_spaced/class_name"

snake_case('MyClassName') # => "my_class_name"
snake_case(NameSpaced::ClassName)
# => "name_spaced/class_name"

Parameters:

• klass (Module|Class|String)

Returns:

• (String)

#stream(value = '', opts = {}, &block) ⇒ void Originally defined in module Elements

This method returns an undefined value.

Parameters:

• value (String) (defaults to: '') —

  The value for the stream. Ignored when a block is given.

• opts (Hash) (defaults to: {})
• block (Proc)

Options Hash (opts):

• ... (void)

Raises:

• (Vedeu::Error::Fatal)

#stream_model? ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating the model is a Views::Stream.

Returns:

• (Boolean)

#string?(value) ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating whether the value is a Fixnum.

Parameters:

• value (String|void)

Returns:

• (Boolean)

#style(value) ⇒ Vedeu::Presentation::Style Also known as: style=, styles, styles= Originally defined in module Presentation

Define a style or styles for an interface, line or a stream.

Examples:

interface 'my_interface' do
  style 'normal'
  # ...
end

lines do
  style ['bold', 'underline']
  # ...
end

stream do
  style 'blink'
  # ...
end

Parameters:

• value (Array<Symbol>|Array<String>|Symbol|String)

Returns:

• (Vedeu::Presentation::Style)

#text(value = '', opts = {}) ⇒ void Originally defined in module Elements

TODO:

This documentation needs editing. (GL: 2015-12-17)

Note:

If using the convenience methods; left, centre, center or right, then a specified align option will be ignored.

This method returns an undefined value.

Specify the content for a view. Provides the means to align a string (or object responding to ‘to_s`), and add it as a Line or to the Stream.

Examples:

lines do
  centre '...'
end

line do
  right '...'
end

line do
  stream do
    text '...'
  end
end

left 'This will be left aligned.', width: 35
# => 'This will be left aligned.         '

centre 'This will be aligned centrally.', width: 35
# => '  This will be aligned centrally.  '
# centre is also aliased to center

right 'This will be right aligned.', width: 35
# => '        This will be right aligned.'

right 'This will be right aligned.', width: 35,
  align: centre

text 'This will be truncated here. More text here.',
  width: 28 # => 'This will be truncated here.'

text 'Padded with hyphens.', width: 25, pad: '-',
  align: :right # => '-----Padded with hyphens.'

Parameters:

• value (String|Object) (defaults to: '') —

  A string or object that responds to ‘to_s`.

• opts (Hash<Symbol => void>) (defaults to: {}) —

  Text options.

Options Hash (opts):

• :align (Symbol) —

  One of ‘:left`, `:centre`/`:center`, or `:right`.

• :width (Integer|NilClass) —

  The width of the text stream to add. If the ‘string` provided is longer than this value, the string will be truncated. If no width is provided in the context of ’lines’, then the interface width is used. If no width is provided in the context of a ‘stream’, then no alignment will occur.

• :pad (String) —

  The character to use to pad the width, by default uses an empty space (0x20). Only when the string is shorter than the specified width.

Raises:

• (Vedeu::Error::Fatal)

#truthy?(value) ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating whether the value should be considered true.

Parameters:

• value (void)

Returns:

• (Boolean)

#use(name) ⇒ void Originally defined in module Use

Note:

• Only models of the same repository can be used in this way.

• If the stored model cannot be found, a ModelNotFound exception may be raised, or the request for an attribute may raise a NoMethodError exception.

This method returns an undefined value.

Use the attribute of stored model.

This DSL method provides access to a stored model by name. You can then request an attribute of that model for use within the current model. The models which current support this are Border, Geometry and Interface.

Examples:

# Here the character used for :my_border is used in
# :my_other_border.
Vedeu.border :my_other_border do
  top_right use(:my_border).top_right
end

Parameters:

• name (String|Symbol) —

  The name of the model with the value you wish to use.

Raises:

• Vedeu::Error::ModelNotFound|Vedeu::Error::NoMethodError

  The model or attribute cannot be found.

#view_model? ⇒ Boolean Originally defined in module Common

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating the model is a Views::View.

Returns:

• (Boolean)