The Vedeu DSL

Coupled with the API (for interacting with the running client application), the DSL provides the mechanism to configure aspects of your application whilst using Vedeu.

Interfaces

An Interface is a basic element in the GUI. It usually but does not necessarily correspond to a region of the terminal screen (for example, an Interface might not be displayed at certain points in an application life cycle).

Much of the behavior of an Interface comes from child objects that are defined under the Interface. These objects are described in more detail in their respective sections below.

Here is an example of declarations for an interface block:

interface 'main' do
  visible true # whether to show the interface
  focus! # focus this interface
  cursor true # Show the cursor when this section is focused
  colour foreground: '#ffffff', # set interface foreground
         background: '#000033'  # and background colors
  group 'general' # set interface group

  geometry do
    # size and position details
  end
  border do
    # border properties
  end
  keymap do
    # keymap that is in effect when this interface is focused
  end
  views do
    # details about how to render the interface
  end
end

Declaring interface sub-objects

Every object in the DSL besides interface itself is defined for a particular interface. This can either be declared implicitly by defining the object inside an interface block or explicitly, by passing the interface name as a first argument to the declaration.

That is, these are equivalent ways to declare a Geometry for an existing interface

interface 'main' do
  geometry do
    # some geometry
  end

  # some other declarations
end

or you can say

interface 'main' do
  # some other declarations
end

geometry 'main' do
  # some geometry
end

Borders

Provides a mechanism to help configure borders in Vedeu.

Setting a title for the border

If you have you are showing a top border, you could add a title.

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_border identifier id'>border</span> <span class='string val'>'border_demo'</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_title identifier id'>title</span> <span class='string val'>'My Cool Title'</span>
  <span class='comment val'># ... some code</span>
<span class='rubyid_end end kw'>end</span>

produces, depending on other customisations:

<span class='plus op'>+</span><span class='minus op'>-</span> <span class='rubyid_My constant id'>My</span> <span class='rubyid_Cool constant id'>Cool</span> <span class='rubyid_Title constant id'>Title</span> <span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='plus op'>+</span>

Customising the appearance of the border

Set the character to be used to draw the bottom left corner of the border.

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_border identifier id'>border</span> <span class='string val'>'border_demo'</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_bottom_left identifier id'>bottom_left</span> <span class='string val'>'+'</span>
  <span class='comment val'># ... some code</span>
<span class='rubyid_end end kw'>end</span>
Set the character to be used to draw the bottom right corner of the border.

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_border identifier id'>border</span> <span class='string val'>'border_demo'</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_bottom_right identifier id'>bottom_right</span> <span class='string val'>'+'</span>
  <span class='comment val'># ... some code</span>
<span class='rubyid_end end kw'>end</span>
Set the character to be used to draw a horizontal part of the border.

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_border identifier id'>border</span> <span class='string val'>'border_demo'</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_horizontal identifier id'>horizontal</span> <span class='string val'>'-'</span>
  <span class='comment val'># ... some code</span>
<span class='rubyid_end end kw'>end</span>
Set the character to be used to draw the top left corner of the border.

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_border identifier id'>border</span> <span class='string val'>'border_demo'</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_top_left identifier id'>top_left</span> <span class='string val'>'+'</span>
  <span class='comment val'># ... some code</span>
<span class='rubyid_end end kw'>end</span>
Set the character to be used to draw the top right corner of the border.

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_border identifier id'>border</span> <span class='string val'>'border_demo'</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_top_right identifier id'>top_right</span> <span class='string val'>'+'</span>
  <span class='comment val'># ... some code</span>
<span class='rubyid_end end kw'>end</span>
Set the character to be used to draw a vertical part of the border.

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_border identifier id'>border</span> <span class='string val'>'border_demo'</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_vertical identifier id'>vertical</span> <span class='string val'>'|'</span>
  <span class='comment val'># ... some code</span>
<span class='rubyid_end end kw'>end</span>

Enabling/disabling the border

Enable the border: (Borders are enabled by default when defined for an interface).

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_border identifier id'>border</span> <span class='string val'>'border_demo'</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_enable! fid id'>enable!</span>
  <span class='comment val'># ... some code</span>
<span class='rubyid_end end kw'>end</span>
Disable the border:

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_border identifier id'>border</span> <span class='string val'>'border_demo'</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_disable! fid id'>disable!</span>
  <span class='comment val'># ... some other code (will be ignored)</span>
<span class='rubyid_end end kw'>end</span>

Enabling/disabling an aspect of the border

Enable/disable the bottom border.

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_border identifier id'>border</span> <span class='string val'>'border_demo'</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_bottom identifier id'>bottom</span> <span class='rubyid_true true kw'>true</span>  <span class='comment val'># or...</span>
  <span class='rubyid_bottom identifier id'>bottom</span> <span class='rubyid_false false kw'>false</span> <span class='comment val'># or...</span>
  <span class='rubyid_hide_bottom! fid id'>hide_bottom!</span> <span class='comment val'># or...</span>
  <span class='rubyid_show_bottom! fid id'>show_bottom!</span>
  <span class='comment val'># ... some code</span>
<span class='rubyid_end end kw'>end</span>

and false. Enable/disable the left border.

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_border identifier id'>border</span> <span class='string val'>'border_demo'</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_left identifier id'>left</span> <span class='rubyid_true true kw'>true</span>  <span class='comment val'># or...</span>
  <span class='rubyid_left identifier id'>left</span> <span class='rubyid_false false kw'>false</span> <span class='comment val'># or...</span>
  <span class='rubyid_hide_left! fid id'>hide_left!</span> <span class='comment val'># or...</span>
  <span class='rubyid_show_left! fid id'>show_left!</span>
  <span class='comment val'># ... some code</span>
<span class='rubyid_end end kw'>end</span>
Enable/disable the right border.

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_border identifier id'>border</span> <span class='string val'>'border_demo'</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_right identifier id'>right</span> <span class='rubyid_true true kw'>true</span>  <span class='comment val'># or...</span>
  <span class='rubyid_right identifier id'>right</span> <span class='rubyid_false false kw'>false</span> <span class='comment val'># or...</span>
  <span class='rubyid_hide_right! fid id'>hide_right!</span> <span class='comment val'># or...</span>
  <span class='rubyid_show_right! fid id'>show_right!</span>
  <span class='comment val'># ... some code</span>
<span class='rubyid_end end kw'>end</span>
Enable/disable the top border.

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_border identifier id'>border</span> <span class='string val'>'border_demo'</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_top identifier id'>top</span> <span class='rubyid_true true kw'>true</span>  <span class='comment val'># or...</span>
  <span class='rubyid_top identifier id'>top</span> <span class='rubyid_false false kw'>false</span> <span class='comment val'># or...</span>
  <span class='rubyid_hide_top! fid id'>hide_top!</span> <span class='comment val'># or...</span>
  <span class='rubyid_show_top! fid id'>show_top!</span>
  <span class='comment val'># ... some code</span>
<span class='rubyid_end end kw'>end</span>

Geometry

Geometry allows the configuration of the position and size of an interface. Within Vedeu, as the same for ANSI terminals, has the origin at top-left, y = 1, x = 1. The ‘y’ coordinate is deliberately first.

The Geometry DSL can be used within the Interface DSL or standalone. Here are example of declarations for a ‘geometry` block:

A standalone geometry definition:

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_geometry identifier id'>geometry</span> <span class='string val'>'some_interface'</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_height identifier id'>height</span> <span class='integer val'>5</span> <span class='comment val'># Sets the height of the view to 5</span>
  <span class='rubyid_width identifier id'>width</span> <span class='integer val'>20</span> <span class='comment val'># Sets the width of the view to 20</span>
  <span class='rubyid_x identifier id'>x</span> <span class='integer val'>3</span>      <span class='comment val'># Start drawing 3 spaces from left</span>
  <span class='rubyid_y identifier id'>y</span> <span class='integer val'>10</span>     <span class='comment val'># Start drawing 10 spaces from top</span>
  <span class='rubyid_xn identifier id'>xn</span> <span class='integer val'>30</span>    <span class='comment val'># Stop drawing 30 spaces from the left</span>
  <span class='rubyid_yn identifier id'>yn</span> <span class='integer val'>20</span>    <span class='comment val'># Stop drawing 20 spaces from top</span>
<span class='rubyid_end end kw'>end</span>

An interface including a geometry definition:

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_interface identifier id'>interface</span> <span class='string val'>'some_interface'</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_geometry identifier id'>geometry</span> <span class='rubyid_do do kw'>do</span>
    <span class='rubyid_height identifier id'>height</span> <span class='integer val'>5</span>
    <span class='rubyid_width identifier id'>width</span> <span class='integer val'>20</span>
    <span class='rubyid_x identifier id'>x</span> <span class='integer val'>3</span>
    <span class='rubyid_y identifier id'>y</span> <span class='integer val'>10</span>
    <span class='rubyid_xn identifier id'>xn</span> <span class='integer val'>30</span>
    <span class='rubyid_yn identifier id'>yn</span> <span class='integer val'>20</span>
  <span class='rubyid_end end kw'>end</span>
  <span class='comment val'># ... some code here</span>
<span class='rubyid_end end kw'>end</span>

If a declaration is omitted for ‘height` or `width` the full remaining space available in the terminal will be used. `x` and `y` both default to 1.

You can also make a geometry declaration dependent on another view:

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_interface identifier id'>interface</span> <span class='string val'>'other_panel'</span> <span class='rubyid_do do kw'>do</span>
  <span class='comment val'># ... some code here</span>
<span class='rubyid_end end kw'>end</span>

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_interface identifier id'>interface</span> <span class='string val'>'main'</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_geometry identifier id'>geometry</span> <span class='rubyid_do do kw'>do</span>
    <span class='rubyid_height identifier id'>height</span> <span class='integer val'>10</span>
    <span class='rubyid_y identifier id'>y</span> <span class='lbrace token'>{</span> <span class='rubyid_use identifier id'>use</span><span class='lparen token'>(</span><span class='string val'>'other_panel'</span><span class='rparen token'>)</span><span class='dot token'>.</span><span class='rubyid_south identifier id'>south</span> <span class='rbrace token'>}</span>
  <span class='rubyid_end end kw'>end</span>
  <span class='comment val'># ... some code here</span>
<span class='rubyid_end end kw'>end</span>

This view will begin just below “other_panel”.

This crude ASCII diagram represents a Geometry within Vedeu, each of the labels is a value you can access or define.

     <span class='rubyid_x identifier id'>x</span>    <span class='rubyid_north identifier id'>north</span>    <span class='rubyid_xn identifier id'>xn</span>           <span class='comment val'># north:  y - 1</span>
   <span class='rubyid_y identifier id'>y</span> <span class='plus op'>+</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='plus op'>+</span>           <span class='comment val'># top:    y</span>
     <span class='bitor op'>|</span>     <span class='rubyid_top identifier id'>top</span>      <span class='bitor op'>|</span>           <span class='comment val'># west:   x - 1</span>
     <span class='bitor op'>|</span>              <span class='bitor op'>|</span>           <span class='comment val'># left:   x</span>
<span class='rubyid_west identifier id'>west</span> <span class='bitor op'>|</span> <span class='rubyid_left identifier id'>left</span>   <span class='rubyid_right identifier id'>right</span> <span class='bitor op'>|</span> <span class='rubyid_east identifier id'>east</span>      <span class='comment val'># right:  xn</span>
     <span class='bitor op'>|</span>              <span class='bitor op'>|</span>           <span class='comment val'># east:   xn + 1</span>
     <span class='bitor op'>|</span>    <span class='rubyid_bottom identifier id'>bottom</span>    <span class='bitor op'>|</span>           <span class='comment val'># bottom: yn</span>
  <span class='rubyid_yn identifier id'>yn</span> <span class='plus op'>+</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='plus op'>+</span>           <span class='comment val'># south:  yn + 1</span>
          <span class='rubyid_south identifier id'>south</span>

Setting the interface dimensions

Instructs Vedeu to calculate x and y geometry automatically based on the centre character of the terminal, the width and the height.

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_geometry identifier id'>geometry</span> <span class='string val'>'some_interface'</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_centred identifier id'>centred</span> <span class='rubyid_false false kw'>false</span> <span class='comment val'># or...</span>

  <span class='rubyid_centred identifier id'>centred</span> <span class='rubyid_true true kw'>true</span>  <span class='comment val'># or...</span>
  <span class='rubyid_centred! fid id'>centred!</span>      <span class='comment val'># or...</span>
  <span class='comment val'># ... some code</span>
<span class='rubyid_end end kw'>end</span>
Specify the number of characters/rows/lines tall the interface will be. This value will be ignored when ‘y` and `yn` are set.

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_geometry identifier id'>geometry</span> <span class='string val'>'some_interface'</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_height identifier id'>height</span> <span class='integer val'>8</span>
  <span class='comment val'># ... some code</span>
<span class='rubyid_end end kw'>end</span>
Specify the number of characters/columns wide the interface will be. This value will be ignored when ‘x` and `xn` are set.

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_geometry identifier id'>geometry</span> <span class='string val'>'some_interface'</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_width identifier id'>width</span> <span class='integer val'>25</span>
  <span class='comment val'># ... some code</span>
<span class='rubyid_end end kw'>end</span>
Returns the width in characters for the number of columns specified.

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_geometry identifier id'>geometry</span> <span class='string val'>'main_interface'</span> <span class='rubyid_do do kw'>do</span>
  <span class='comment val'># ... some code</span>
  <span class='rubyid_width identifier id'>width</span> <span class='rubyid_columns identifier id'>columns</span><span class='lparen token'>(</span><span class='integer val'>9</span><span class='rparen token'>)</span> <span class='comment val'># Vedeu.width # => 92 (for example)</span>
                   <span class='comment val'># 92 / 12 = 7</span>
                   <span class='comment val'># 7 * 9 = 63</span>
                   <span class='comment val'># Therefore, width is 63 characters.</span>
<span class='rubyid_end end kw'>end</span>
Returns the height in characters for the number of rows specified.

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_geometry identifier id'>geometry</span> <span class='string val'>'main_interface'</span> <span class='rubyid_do do kw'>do</span>
  <span class='comment val'># ... some code</span>
  <span class='rubyid_height identifier id'>height</span> <span class='rubyid_rows identifier id'>rows</span><span class='lparen token'>(</span><span class='integer val'>3</span><span class='rparen token'>)</span>  <span class='comment val'># Vedeu.height # => 38 (for example)</span>
                  <span class='comment val'># 38 / 12 = 3</span>
                  <span class='comment val'># 3 * 3 = 9</span>
                  <span class='comment val'># Therefore, height is 9 characters.</span>
<span class='rubyid_end end kw'>end</span>
Specify the starting x position (column) of the interface.

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_geometry identifier id'>geometry</span> <span class='string val'>'some_interface'</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_x identifier id'>x</span> <span class='integer val'>7</span> <span class='comment val'># start on column 7.</span>

  <span class='rubyid_x identifier id'>x</span> <span class='lbrace token'>{</span> <span class='rubyid_use identifier id'>use</span><span class='lparen token'>(</span><span class='string val'>'other_interface'</span><span class='rparen token'>)</span><span class='dot token'>.</span><span class='rubyid_east identifier id'>east</span> <span class='rbrace token'>}</span> <span class='comment val'># start on column 8, if</span>
  <span class='comment val'># ... some code                   # `other_interface` changes</span>
<span class='rubyid_end end kw'>end</span>                                 <span class='comment val'># position, `some_interface` will</span>
                                    <span class='comment val'># too.</span>
Specify the ending x position (column) of the interface. This value will override ‘width`.

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_geometry identifier id'>geometry</span> <span class='string val'>'some_interface'</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_xn identifier id'>xn</span> <span class='integer val'>37</span> <span class='comment val'># end at column 37.</span>

  <span class='rubyid_xn identifier id'>xn</span>  <span class='lbrace token'>{</span> <span class='rubyid_use identifier id'>use</span><span class='lparen token'>(</span><span class='string val'>'other_interface'</span><span class='rparen token'>)</span><span class='dot token'>.</span><span class='rubyid_right identifier id'>right</span> <span class='rbrace token'>}</span> <span class='comment val'># when `other_interface`</span>
                                       <span class='comment val'># changes position,</span>
  <span class='comment val'># ... some code                      # `some_interface` will too.</span>
<span class='rubyid_end end kw'>end</span>
Specify the starting y position (row/line) of the interface.

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_geometry identifier id'>geometry</span> <span class='string val'>'some_interface'</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_y identifier id'>y</span>  <span class='integer val'>4</span> <span class='comment val'># start at row 4</span>

  <span class='rubyid_y identifier id'>y</span>  <span class='lbrace token'>{</span> <span class='rubyid_use identifier id'>use</span><span class='lparen token'>(</span><span class='string val'>'other_interface'</span><span class='rparen token'>)</span><span class='dot token'>.</span><span class='rubyid_north identifier id'>north</span> <span class='rbrace token'>}</span> <span class='comment val'># start on row/line 3, when</span>
  <span class='comment val'># ... some code                     # `other_interface` changes</span>
<span class='rubyid_end end kw'>end</span>                                   <span class='comment val'># position, `some_interface`</span>
                                      <span class='comment val'># will too.</span>
Specify the ending y position (row/line) of the interface. This value will override ‘height`.

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_geometry identifier id'>geometry</span> <span class='string val'>'some_interface'</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_yn identifier id'>yn</span> <span class='integer val'>24</span> <span class='comment val'># end at row 24.</span>

  <span class='rubyid_yn identifier id'>yn</span> <span class='lbrace token'>{</span> <span class='rubyid_use identifier id'>use</span><span class='lparen token'>(</span><span class='string val'>'other_interface'</span><span class='rparen token'>)</span><span class='dot token'>.</span><span class='rubyid_bottom identifier id'>bottom</span> <span class='rbrace token'>}</span> <span class='comment val'># if `other_interface` changes</span>
  <span class='comment val'># ... some code                      # position, `some_interface`</span>
<span class='rubyid_end end kw'>end</span>                                    <span class='comment val'># will too.</span>

Groups

Interfaces can be configured to be part of a named group. Once an interface is a member of group, the group can be affected by other controls. For example, assuming the client application is a simple Git client, it may have a group called ‘commit’. The ‘commit’ group will contain the interfaces ‘diff’ (to show the changes), ‘staged’ (to show which files are staged) and ‘unstaged’. A refresh of the ‘commit’ group would cause all interfaces belonging to the group to refresh. Similarly, showing or hiding the group would of course, show or hide the interfaces of that group.

Add interfaces to groups

Specify a new group of interfaces with a simple DSL. Creating a group with the same name as an existing group overwrites the existing group.

The example below resembles ‘vim’ (the popular terminal-based text editor):

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_group identifier id'>group</span> <span class='string val'>'title_screen'</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_add identifier id'>add</span> <span class='string val'>'welcome_interface'</span>
  <span class='comment val'># ... some code</span>
<span class='rubyid_end end kw'>end</span>

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_group identifier id'>group</span> <span class='string val'>'main_screen'</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_add identifier id'>add</span> <span class='string val'>'editor_interface'</span>
  <span class='rubyid_add identifier id'>add</span> <span class='string val'>'status_interface'</span>
  <span class='rubyid_add identifier id'>add</span> <span class='string val'>'command_interface'</span>
  <span class='comment val'># ... some code</span>
<span class='rubyid_end end kw'>end</span>

or more succinctly:

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_group identifier id'>group</span> <span class='string val'>'main_screen'</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_members identifier id'>members</span> <span class='string val'>'editor_interface'</span><span class='comma token'>,</span> <span class='string val'>'status_interface'</span><span class='comma token'>,</span> <span class='string val'>'command_interface'</span>
  <span class='comment val'># ... some code</span>
<span class='rubyid_end end kw'>end</span>

or when defining an interface:

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_interface identifier id'>interface</span> <span class='string val'>'some_interface'</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_group identifier id'>group</span> <span class='string val'>'some_group'</span>
  <span class='comment val'># ... some code</span>
<span class='rubyid_end end kw'>end</span>

Keymaps

You can define keymaps by name which matches a defined interface. When that interface is in focus, keys pressed as part of this definition will affect that interface. This allows you to form context driven behaviour for your application. Define actions for keypresses for when specific interfaces are in focus. Unless an interface is specified, the key will be assumed to be global, meaning its action will happen regardless of the interface in focus.

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_keymap identifier id'>keymap</span> <span class='string val'>'some_interface'</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_key identifier id'>key</span><span class='lparen token'>(</span><span class='string val'>'s'</span><span class='rparen token'>)</span>        <span class='lbrace token'>{</span> <span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_trigger identifier id'>trigger</span><span class='lparen token'>(</span><span class='symbol val'>:save</span><span class='rparen token'>)</span> <span class='rbrace token'>}</span>
  <span class='rubyid_key identifier id'>key</span><span class='lparen token'>(</span><span class='string val'>'h'</span><span class='comma token'>,</span> <span class='symbol val'>:left</span><span class='rparen token'>)</span> <span class='lbrace token'>{</span> <span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_trigger identifier id'>trigger</span><span class='lparen token'>(</span><span class='symbol val'>:left</span><span class='rparen token'>)</span> <span class='rbrace token'>}</span>
  <span class='rubyid_key identifier id'>key</span><span class='lparen token'>(</span><span class='string val'>'j'</span><span class='comma token'>,</span> <span class='symbol val'>:down</span><span class='rparen token'>)</span> <span class='lbrace token'>{</span> <span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_trigger identifier id'>trigger</span><span class='lparen token'>(</span><span class='symbol val'>:down</span><span class='rparen token'>)</span> <span class='rbrace token'>}</span>
  <span class='rubyid_key identifier id'>key</span><span class='lparen token'>(</span><span class='string val'>'p'</span><span class='rparen token'>)</span> <span class='rubyid_do do kw'>do</span>
    <span class='comment val'># ... some code</span>
  <span class='rubyid_end end kw'>end</span>
  <span class='comment val'># ... some code</span>
<span class='rubyid_end end kw'>end</span>

<span class='comment val'># or...</span>

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_keys identifier id'>keys</span> <span class='string val'>'some_interface'</span> <span class='rubyid_do do kw'>do</span>
  <span class='comment val'># ... some code</span>
<span class='rubyid_end end kw'>end</span>

<span class='comment val'># or...</span>

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_interface identifier id'>interface</span> <span class='string val'>'some_interface'</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_keymap identifier id'>keymap</span> <span class='rubyid_do do kw'>do</span>
    <span class='comment val'># ... some code</span>
  <span class='rubyid_end end kw'>end</span> <span class='comment val'># or...</span>

  <span class='rubyid_keys identifier id'>keys</span> <span class='rubyid_do do kw'>do</span>
    <span class='comment val'># ... some code</span>
  <span class='rubyid_end end kw'>end</span>
<span class='rubyid_end end kw'>end</span>
Define the name of the keymap.

To only allow certain keys to work with specific interfaces, use the same name as the interface.

When the name ‘global’ is used, all keys in the keymap block will be available to all interfaces. Once a key has been defined in the ‘global’ keymap, it cannot be used for a specific interface.

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_keymap identifier id'>keymap</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_name identifier id'>name</span> <span class='string val'>'some_interface'</span>
<span class='rubyid_end end kw'>end</span>

Provides the mechanism to create menus within client applications and use events to drive them. Add an individual item to the menu. 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.

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_menu identifier id'>menu</span> <span class='string val'>'my_menu'</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_items identifier id'>items</span> <span class='lbrack token'>[</span><span class='symbol val'>:item_1</span><span class='comma token'>,</span> <span class='symbol val'>:item_2</span><span class='comma token'>,</span> <span class='symbol val'>:item_3</span><span class='rbrack token'>]</span>
<span class='rubyid_end end kw'>end</span>

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_menu identifier id'>menu</span> <span class='string val'>'my_playlist'</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_items identifier id'>items</span> <span class='rubyid_Track constant id'>Track</span><span class='dot token'>.</span><span class='rubyid_all_my_favourites identifier id'>all_my_favourites</span>
<span class='rubyid_end end kw'>end</span>
The name of the menu. Used to reference the menu throughout your application’s execution lifetime.

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_menu identifier id'>menu</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_name identifier id'>name</span> <span class='string val'>'my_menu'</span>
  <span class='comment val'># ...</span>
<span class='rubyid_end end kw'>end</span>

Views

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 Vedeu::DSL::Interface. 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.)

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_interface identifier id'>interface</span> <span class='string val'>'main'</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_geometry identifier id'>geometry</span> <span class='rubyid_do do kw'>do</span>
    <span class='rubyid_centred! fid id'>centred!</span>
    <span class='rubyid_height identifier id'>height</span> <span class='integer val'>4</span>
    <span class='rubyid_width identifier id'>width</span>  <span class='integer val'>50</span>
  <span class='rubyid_end end kw'>end</span>
<span class='rubyid_end end kw'>end</span>

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_interface identifier id'>interface</span> <span class='string val'>'title'</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_geometry identifier id'>geometry</span> <span class='rubyid_do do kw'>do</span>
    <span class='rubyid_height identifier id'>height</span> <span class='integer val'>1</span>
    <span class='rubyid_width identifier id'>width</span>  <span class='integer val'>50</span>
    <span class='rubyid_x identifier id'>x</span>      <span class='rubyid_use identifier id'>use</span><span class='lparen token'>(</span><span class='string val'>'main'</span><span class='rparen token'>)</span><span class='dot token'>.</span><span class='rubyid_left identifier id'>left</span>
    <span class='rubyid_y identifier id'>y</span>      <span class='rubyid_use identifier id'>use</span><span class='lparen token'>(</span><span class='string val'>'main'</span><span class='rparen token'>)</span><span class='dot token'>.</span><span class='rubyid_north identifier id'>north</span>
  <span class='rubyid_end end kw'>end</span>
<span class='rubyid_end end kw'>end</span>

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:

<span class='rubyid_renders identifier id'>renders</span><span class='div op'>/</span><span class='rubyid_views identifier id'>views</span>
  <span class='bitor op'>|</span><span class='minus op'>-</span> <span class='rubyid_view identifier id'>view</span>
      <span class='bitor op'>|</span><span class='minus op'>-</span> <span class='rubyid_lines identifier id'>lines</span>
      <span class='bitor op'>|</span>   <span class='bitor op'>|</span><span class='minus op'>-</span> <span class='rubyid_line identifier id'>line</span>
      <span class='bitor op'>|</span>       <span class='bitor op'>|</span><span class='minus op'>-</span> <span class='rubyid_streams identifier id'>streams</span>
      <span class='bitor op'>|</span>       <span class='bitor op'>|</span>   <span class='bitor op'>|</span><span class='minus op'>-</span> <span class='rubyid_stream identifier id'>stream</span>
      <span class='bitor op'>|</span>       <span class='bitor op'>|</span>       <span class='bitor op'>|</span><span class='minus op'>-</span> <span class='rubyid_char identifier id'>char</span>
      <span class='bitor op'>|</span>       <span class='bitor op'>|</span>
      <span class='bitor op'>|</span>       <span class='bitor op'>|</span><span class='minus op'>-</span> <span class='rubyid_stream identifier id'>stream</span>
      <span class='bitor op'>|</span>           <span class='bitor op'>|</span><span class='minus op'>-</span> <span class='rubyid_char identifier id'>char</span>
      <span class='bitor op'>|</span>
      <span class='bitor op'>|</span><span class='minus op'>-</span> <span class='rubyid_line identifier id'>line</span>
          <span class='bitor op'>|</span><span class='minus op'>-</span> <span class='rubyid_streams identifier id'>streams</span>
          <span class='bitor op'>|</span>   <span class='bitor op'>|</span><span class='minus op'>-</span> <span class='rubyid_stream identifier id'>stream</span>
          <span class='bitor op'>|</span>       <span class='bitor op'>|</span><span class='minus op'>-</span> <span class='rubyid_char identifier id'>char</span>
          <span class='bitor op'>|</span>
          <span class='bitor op'>|</span><span class='minus op'>-</span> <span class='rubyid_stream identifier id'>stream</span>
              <span class='bitor op'>|</span><span class='minus op'>-</span> <span class='rubyid_char identifier id'>char</span>

<span class='rubyid_renders identifier id'>renders</span><span class='div op'>/</span><span class='rubyid_views identifier id'>views</span>
  <span class='bitor op'>|</span><span class='minus op'>-</span> <span class='rubyid_view identifier id'>view</span>
      <span class='bitor op'>|</span><span class='minus op'>-</span> <span class='rubyid_lines identifier id'>lines</span><span class='div op'>/</span><span class='rubyid_line identifier id'>line</span>
          <span class='bitor op'>|</span><span class='minus op'>-</span> <span class='rubyid_streams identifier id'>streams</span><span class='div op'>/</span><span class='rubyid_stream identifier id'>stream</span>
              <span class='bitor op'>|</span><span class='minus op'>-</span> <span class='rubyid_char identifier id'>char</span>
Register an interface by name which will display output from a event or command. This provides the means for you to define your the views of your application without their content.

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_interface identifier id'>interface</span> <span class='string val'>'my_interface'</span> <span class='rubyid_do do kw'>do</span>
  <span class='comment val'># ... some code</span>
<span class='rubyid_end end kw'>end</span>

Immediate rendering

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.

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_renders identifier id'>renders</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_view identifier id'>view</span> <span class='string val'>'some_interface'</span> <span class='rubyid_do do kw'>do</span>
    <span class='rubyid_line identifier id'>line</span> <span class='rubyid_do do kw'>do</span>
      <span class='rubyid_stream identifier id'>stream</span> <span class='rubyid_do do kw'>do</span>
        <span class='rubyid_left identifier id'>left</span> <span class='string val'>'Title goes here'</span><span class='comma token'>,</span> <span class='label val'>width:</span> <span class='integer val'>35</span>
      <span class='rubyid_end end kw'>end</span>
      <span class='rubyid_stream identifier id'>stream</span> <span class='rubyid_do do kw'>do</span>
        <span class='rubyid_right identifier id'>right</span> <span class='rubyid_Time constant id'>Time</span><span class='dot token'>.</span><span class='rubyid_now identifier id'>now</span><span class='dot token'>.</span><span class='rubyid_strftime identifier id'>strftime</span><span class='lparen token'>(</span><span class='string val'>'%H:%m'</span><span class='rparen token'>)</span><span class='comma token'>,</span> <span class='label val'>width:</span> <span class='integer val'>7</span>
      <span class='rubyid_end end kw'>end</span>
    <span class='rubyid_end end kw'>end</span>
  <span class='rubyid_end end kw'>end</span>
  <span class='rubyid_view identifier id'>view</span> <span class='string val'>'other_interface'</span> <span class='rubyid_do do kw'>do</span>
    <span class='rubyid_lines identifier id'>lines</span> <span class='rubyid_do do kw'>do</span>
      <span class='rubyid_line identifier id'>line</span> <span class='string val'>'This is content for the main interface.'</span>
      <span class='rubyid_line identifier id'>line</span> <span class='string val'>''</span>
      <span class='rubyid_line identifier id'>line</span> <span class='string val'>'Pretty easy eh?'</span>
    <span class='rubyid_end end kw'>end</span>
  <span class='rubyid_end end kw'>end</span>
  <span class='comment val'># ... some code</span>
<span class='rubyid_end end kw'>end</span>

<span class='comment val'># or...</span>

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_render identifier id'>render</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_view identifier id'>view</span> <span class='string val'>'my_interface'</span> <span class='rubyid_do do kw'>do</span>
    <span class='comment val'># ... some code</span>
  <span class='rubyid_end end kw'>end</span>
<span class='rubyid_end end kw'>end</span>

Deferred rendering

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 Vedeu::Terminal#output.

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_views identifier id'>views</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_view identifier id'>view</span> <span class='string val'>'some_interface'</span> <span class='rubyid_do do kw'>do</span>
    <span class='rubyid_line identifier id'>line</span> <span class='rubyid_do do kw'>do</span>
      <span class='rubyid_stream identifier id'>stream</span> <span class='rubyid_do do kw'>do</span>
        <span class='rubyid_left identifier id'>left</span> <span class='string val'>'Title goes here'</span><span class='comma token'>,</span> <span class='label val'>width:</span> <span class='integer val'>35</span>
      <span class='rubyid_end end kw'>end</span>
      <span class='rubyid_stream identifier id'>stream</span> <span class='rubyid_do do kw'>do</span>
        <span class='rubyid_right identifier id'>right</span> <span class='rubyid_Time constant id'>Time</span><span class='dot token'>.</span><span class='rubyid_now identifier id'>now</span><span class='dot token'>.</span><span class='rubyid_strftime identifier id'>strftime</span><span class='lparen token'>(</span><span class='string val'>'%H:%m'</span><span class='rparen token'>)</span><span class='comma token'>,</span> <span class='label val'>width:</span> <span class='integer val'>7</span>
      <span class='rubyid_end end kw'>end</span>
    <span class='rubyid_end end kw'>end</span>
  <span class='rubyid_end end kw'>end</span>
  <span class='rubyid_view identifier id'>view</span> <span class='string val'>'other_interface'</span> <span class='rubyid_do do kw'>do</span>
    <span class='rubyid_lines identifier id'>lines</span> <span class='rubyid_do do kw'>do</span>
      <span class='rubyid_line identifier id'>line</span> <span class='string val'>'This is content for the main interface.'</span>
      <span class='rubyid_line identifier id'>line</span> <span class='string val'>''</span>
      <span class='rubyid_line identifier id'>line</span> <span class='string val'>'Pretty easy eh?'</span>
    <span class='rubyid_end end kw'>end</span>
  <span class='rubyid_end end kw'>end</span>
  <span class='comment val'># ... some code</span>
<span class='rubyid_end end kw'>end</span>

Specifying view content

Provides methods to be used to define views.

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_renders identifier id'>renders</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_view identifier id'>view</span> <span class='string val'>'my_interface'</span> <span class='rubyid_do do kw'>do</span>
    <span class='rubyid_lines identifier id'>lines</span> <span class='rubyid_do do kw'>do</span>
      <span class='rubyid_background identifier id'>background</span> <span class='string val'>'#000000'</span>
      <span class='rubyid_foreground identifier id'>foreground</span> <span class='string val'>'#ffffff'</span>
      <span class='rubyid_line identifier id'>line</span> <span class='string val'>'This is white text on a black background.'</span>
      <span class='rubyid_line identifier id'>line</span> <span class='string val'>'Next is a blank line:'</span>
      <span class='rubyid_line identifier id'>line</span> <span class='string val'>''</span>

      <span class='rubyid_streams identifier id'>streams</span> <span class='lbrace token'>{</span> <span class='rubyid_stream identifier id'>stream</span> <span class='string val'>'We can define '</span> <span class='rbrace token'>}</span>

      <span class='rubyid_streams identifier id'>streams</span> <span class='rubyid_do do kw'>do</span>
        <span class='rubyid_foreground identifier id'>foreground</span> <span class='string val'>'#ff0000'</span>
        <span class='rubyid_stream identifier id'>stream</span> <span class='string val'>'parts of a line '</span>
      <span class='rubyid_end end kw'>end</span>

      <span class='rubyid_streams identifier id'>streams</span> <span class='lbrace token'>{</span> <span class='rubyid_stream identifier id'>stream</span> <span class='string val'>'independently using '</span> <span class='rbrace token'>}</span>

      <span class='rubyid_streams identifier id'>streams</span> <span class='rubyid_do do kw'>do</span>
        <span class='rubyid_foreground identifier id'>foreground</span> <span class='string val'>'#00ff00'</span>
        <span class='rubyid_stream identifier id'>stream</span> <span class='string val'>'streams.'</span>
      <span class='rubyid_end end kw'>end</span>
    <span class='rubyid_end end kw'>end</span>
  <span class='rubyid_end end kw'>end</span>
<span class='rubyid_end end kw'>end</span>
Specify a single line in a view.

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_renders identifier id'>renders</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_view identifier id'>view</span> <span class='string val'>'my_interface'</span> <span class='rubyid_do do kw'>do</span>
    <span class='rubyid_line identifier id'>line</span> <span class='string val'>'some text...'</span>
    <span class='comment val'># ... some code</span>

    <span class='rubyid_line identifier id'>line</span> <span class='rubyid_do do kw'>do</span>
      <span class='comment val'># ... some code</span>
    <span class='rubyid_end end kw'>end</span>
  <span class='rubyid_end end kw'>end</span>
<span class='rubyid_end end kw'>end</span>
Define multiple streams (a stream is a subset of a line). Uses Vedeu::DSL::Stream for all directives within the required block.

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_renders identifier id'>renders</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_view identifier id'>view</span> <span class='string val'>'my_interface'</span> <span class='rubyid_do do kw'>do</span>
    <span class='rubyid_line identifier id'>line</span> <span class='rubyid_do do kw'>do</span>
      <span class='rubyid_streams identifier id'>streams</span> <span class='rubyid_do do kw'>do</span>
        <span class='comment val'># ... some code</span>
      <span class='rubyid_end end kw'>end</span>

      <span class='rubyid_stream identifier id'>stream</span> <span class='rubyid_do do kw'>do</span>
        <span class='comment val'># ... some code</span>
      <span class='rubyid_end end kw'>end</span>
    <span class='rubyid_end end kw'>end</span>
  <span class='rubyid_end end kw'>end</span>
<span class='rubyid_end end kw'>end</span>

@todo More documentation coming soon.

Authors Notes

The Rubydoc documentation has more specific information about the DSL methods demonstrated above: RubyDoc.

I've tried to write the DSL in a way which makes it read nice; believing that this will make it easier to use. I hope this is the case for you.