Class: Vedeu::DSL::View

Inherits:
Object
  • Object
show all
Extended by:
Common
Includes:
Common, Vedeu::DSL, Presentation, Shared, Text, Use
Defined in:
lib/vedeu/dsl/view.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
    centred!
    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 collapse

Class Method Summary collapse

Instance Method Summary collapse

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

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

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

Parameters:

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

    The variable to check.

Returns:

  • (Boolean)

.composition(client, &block) ⇒ Vedeu::Views::Composition (private)

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

Parameters:

  • client (Object)
  • block (Proc)

Returns:



199
200
201
 
# File 'lib/vedeu/dsl/view.rb', line 199

def composition(client, &block)
  Vedeu::Views::Composition.build(client: client, &block)
end

.demodulize(klass) ⇒ String Originally defined in module Common

Removes the module part from the expression in the string.

Examples:

demodulize('Vedeu::SomeModule::SomeClass') # => "SomeClass"

Parameters:

  • klass (Class|String)

Returns:

  • (String)

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

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

Parameters:

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

    The variable to check.

Returns:

  • (Boolean)

.renders(&block) ⇒ Array<View> Also known as: render

Directly write a view buffer to the terminal. Using this method means that the refresh event does not need to be triggered after creating the views, though can be later triggered when needed.

Vedeu.renders do
  view :some_interface do
    line do
      stream do
        left 'Title goes here', width: 35
      end
      stream do
        right Time.now.strftime('%H:%m'), width: 7
      end
    end
  end
  view :other_interface do
    lines do
      line 'This is content for the main interface.'
      line ''
      line 'Pretty easy eh?'
    end
  end
  # ... some code
end

# or...

Vedeu.render do
  view :my_interface do
    # ... some code
  end
end

Parameters:

  • block (Proc) —

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

Returns:

Raises:



136
137
138
139
140
141
142
 
# File 'lib/vedeu/dsl/view.rb', line 136

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

  client = eval('self', block.binding)

  store(:store_immediate, client, &block)
end

.snake_case(name) ⇒ String Originally defined in module Common

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"

Parameters:

  • name (String)

Returns:

  • (String)

.store(method, client, &block) ⇒ Array (private)

Stores each of the views defined in their respective buffers ready to be rendered on next refresh.

Parameters:

  • method (Symbol) —

    An instruction; ‘:store_immediate` or `:store_deferred` which determines whether the view will be shown immediately or later respectively.

  • client (Object) —

    The client class which called the DSL object.

  • block (Proc)

Returns:

  • (Array) 


213
214
215
216
217
 
# File 'lib/vedeu/dsl/view.rb', line 213

def store(method, client, &block)
  composition(client, &block).views.map do |view|
    view.public_send(method)
  end
end

.views(&block) ⇒ Array<View>

Define a view (content) for an interface.

As you can see by comparing the examples above to these below, the immediate render simply wraps what is already here in the deferred view.

The views declared within this block are stored in their respective interface back buffers until a refresh event occurs. When the refresh event is triggered, the back buffers are swapped into the front buffers and the content here will be rendered to Terminal#output.

Vedeu.views do
  view :some_interface do
    line do
      stream do
        left 'Title goes here', width: 35
      end
      stream do
        right Time.now.strftime('%H:%m'), width: 7
      end
    end
  end
  view :other_interface do
    lines do
      line 'This is content for the main interface.'
      line ''
      line 'Pretty easy eh?'
    end
  end
  # ... some code
end

Parameters:

  • block (Proc) —

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

Returns:

Raises:



183
184
185
186
187
188
189
 
# File 'lib/vedeu/dsl/view.rb', line 183

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

  client = eval('self', block.binding)

  store(:store_deferred, client, &block)
end

Instance Method Details

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

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)

#border(name = nil, &block) ⇒ Vedeu::Borders::Border Originally defined in module Shared

Allows the setting of a border for the interface.

Examples:

Vedeu.interface :my_interface do
  border do
    # ... see Vedeu::Borders::DSL for DSL methods for
    #     borders.
  end
end

Parameters:

  • name (String|Symbol) (defaults to: nil) —

    The name of the interface; this is already provided when we define the interface or view, setting it here is just mirroring functionality of Borders::DSL.border.

  • block (Proc)

Returns:

Raises:

See Also:

#border! ⇒ Vedeu::Borders::Border Originally defined in module Shared

Applies the default border to the interface.

Examples:

Vedeu.interface :my_interface do
  border!

  # ... some code
end

Returns:

#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:

Returns:

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

Returns:

  • (Hash<Symbol => String>)

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

Removes the module part from the expression in the string.

Examples:

demodulize('Vedeu::SomeModule::SomeClass') # => "SomeClass"

Parameters:

  • klass (Class|String)

Returns:

  • (String)

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

See Also:

#geometry(name = nil, &block) ⇒ Vedeu::Geometry::Geometry Originally defined in module Shared

Define the geometry for an interface.

Examples:

Vedeu.interface :my_interface do
  geometry do
    # ... see Vedeu::Geometry::DSL for DSL methods for
    #     geometries.
  end
end

Parameters:

  • name (String|Symbol) (defaults to: nil) —

    The name of the interface; this is already provided when we define the interface or view, setting it here is just mirroring functionality of Geometry::DSL.geometry.

  • block (Proc)

Returns:

Raises:

See Also:

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

Returns an 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.

#lines(&block) ⇒ Vedeu::Views::Line Also known as: line

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)

Returns:

Raises:



240
241
242
243
244
 
# File 'lib/vedeu/dsl/view.rb', line 240

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

  model.add(model.member.build(attributes, &block))
end

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

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

Parameters:

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

    The variable to check.

Returns:

  • (Boolean)

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

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"

Parameters:

  • name (String)

Returns:

  • (String)

#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:

#text(value = '', options = {}) ⇒ String Also known as: text=, align, center, centre, left, right, align=, center=, centre=, left=, right= Originally defined in module Text

Note:

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

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,
  anchor: centre

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

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

Parameters:

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

    A string or object that responds to ‘to_s`.

  • options (Hash) (defaults to: {}) —

    Text options.

Options Hash (options):

  • :anchor (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.

Returns:

  • (String)

#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.