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. You can think of it as a container for a portion of the terminal screen. Interfaces can be set to be show or hidden, and combined into groups to form the different 'screens' of your application.

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
end

The content for an interface is handled by a 'view'. More details on these can be found here: Views

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.

Creating a new named border

Setting a title for the border

Customising the appearance of the border

Enabling/disabling the border

Enabling/disabling an aspect of the border

and false.

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='symbol 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='symbol 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='symbol 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='symbol 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='symbol 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>

Creating a new named geometry

Setting the interface dimensions

Align the interface/view horizontally or vertically within the terminal.

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.

Creating a new named group

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='symbol val'>:title_screen</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_add identifier id'>add</span> <span class='symbol 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='symbol val'>:main_screen</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_add identifier id'>add</span> <span class='symbol val'>:editor_interface</span>
  <span class='rubyid_add identifier id'>add</span> <span class='symbol val'>:status_interface</span>
  <span class='rubyid_add identifier id'>add</span> <span class='symbol 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='symbol val'>:main_screen</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_members identifier id'>members</span> <span class='symbol val'>:editor_interface</span><span class='comma token'>,</span>
          <span class='symbol val'>:status_interface</span><span class='comma token'>,</span>
          <span class='symbol 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='symbol val'>:some_interface</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_group identifier id'>group</span> <span class='symbol val'>:some_group</span>
  <span class='comment val'># ... some code</span>
<span class='rubyid_end end kw'>end</span>

Add interfaces to groups

Add the named interface to this group.

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_group identifier id'>group</span> <span class='symbol val'>:main_screen</span> <span class='rubyid_do do kw'>do</span>
  <span class='rubyid_add identifier id'>add</span> <span class='symbol val'>:editor_interface</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.

Creating a new named group

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='symbol val'>:my_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='symbol 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='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='symbol val'>:my_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>

Menus

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='symbol 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='symbol 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>

Register a menu by name which will display a collection of items for your users to select; and provide interactivity within your application.

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::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.)

<span class='rubyid_Vedeu constant id'>Vedeu</span><span class='dot token'>.</span><span class='rubyid_interface identifier id'>interface</span> <span class='symbol 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'>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='symbol 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 an event or a 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='symbol 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

Deferred rendering

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.

The Vedeu DSL

Interfaces

Declaring interface sub-objects

Borders

Creating a new named border

Setting a title for the border

Customising the appearance of the border

Enabling/disabling the border

Enabling/disabling an aspect of the border

Geometry

Creating a new named geometry

Setting the interface dimensions

Groups

Creating a new named group

Add interfaces to groups

Keymaps

Creating a new named group

Menus

Creating a new named menu

Views

Immediate rendering

Deferred rendering

Authors Notes