Module: Vedeu::API

Included in:
Vedeu, View
Defined in:
lib/vedeu/api/api.rb,
lib/vedeu/api/line.rb,
lib/vedeu/api/stream.rb,
lib/vedeu/api/helpers.rb,
lib/vedeu/api/interface.rb,
lib/vedeu/api/composition.rb

Defined Under Namespace

Modules: Helpers Classes: Composition, Interface, Line, Stream

Instance Method Summary collapse

Instance Method Details

#event(name, opts = {}, &block) ⇒ Hash

Register an event by name with optional delay (throttling) which when triggered will execute the code contained within the passed block.

Examples:

Vedeu.event :my_event do |some, args|
  ... some code here ...

  Vedeu.trigger(:my_other_event)
end

T = Triggered, X = Executed, i = Ignored.

0.0.....0.2.....0.4.....0.6.....0.8.....1.0.....1.2.....1.4.....1.6...
.T...T...T...T...T...T...T...T...T...T...T...T...T...T...T...T...T...T
.X...i...i...i...i...X...i...i...i...i...X...i...i...i...i...i...i...i

Vedeu.event(:my_delayed_event, { delay: 0.5 })
  ... some code here ...
end

T = Triggered, X = Executed, i = Ignored.

0.0.....0.2.....0.4.....0.6.....0.8.....1.0.....1.2.....1.4.....1.6...
.T...T...T...T...T...T...T...T...T...T...T...T...T...T...T...T...T...T
.i...i...i...i...i...i...i...X...i...i...i...i...i...i...X...i...i...i

Vedeu.event(:my_debounced_event, { debounce: 0.7 })
  ... some code here ...
end

Options Hash (opts):

  • :delay (Fixnum|Float) —

    Limits the execution of the triggered event to only execute when first triggered, with subsequent triggering being ignored until the delay has expired.

  • :debounce (Fixnum|Float) —

    Limits the execution of the triggered event to only execute once the debounce has expired. Subsequent triggers before debounce expiry are ignored.



48
49
50
 
# File 'lib/vedeu/api/api.rb', line 48

def event(name, opts = {}, &block)
  Vedeu.events.event(name, opts = {}, &block)
end

#events ⇒ Object

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

Returns [].



226
227
228
229
230
231
232
233
234
235
236
 
# File 'lib/vedeu/api/api.rb', line 226

def events
  @events ||= Vedeu::Events.new do
    event(:_log_)                     { |msg| Vedeu.log(msg)      }
    event(:_exit_)                    { Vedeu.shutdown            }
    event(:_mode_switch_)             { fail ModeSwitch           }
    event(:_clear_)                   { Terminal.clear_screen     }
    event(:_refresh_)                 { Buffers.refresh_all       }
    event(:_resize_, { delay: 0.25 }) { Vedeu.resize              }
    event(:_keypress_)                { |key| Vedeu.keypress(key) }
  end
end

#height ⇒ Fixnum

Find out how many lines the current terminal is able to display.

Examples:

Vedeu.height



72
73
74
 
# File 'lib/vedeu/api/api.rb', line 72

def height
  Terminal.height
end

#interface(name = '', &block) ⇒ TrueClass

Register an interface by name which will display output from a event or command. This provides the means for you to define your application’s views without their content.

Examples:

Vedeu.interface 'my_interface' do
  ...

Vedeu.interface do
  name 'interfaces_must_have_a_name'
  ...



95
96
97
 
# File 'lib/vedeu/api/api.rb', line 95

def interface(name = '', &block)
  API::Interface.define({ name: name }, &block)
end

#keypress(key) ⇒ Object

Handles the keypress in your application. Can also be used to simulate a keypress.

Examples:

TODO



111
112
113
114
115
116
117
 
# File 'lib/vedeu/api/api.rb', line 111

def keypress(key)
  Vedeu.events.trigger(:key, key)
  Vedeu.events.trigger(:_log_, "Key: #{key}") if Configuration.debug?
  Vedeu.events.trigger(:_mode_switch_) if key == :escape
  Vedeu.events.trigger(:_focus_next_)  if key == :tab
  Vedeu.events.trigger(:_focus_prev_)  if key == :shift_tab
end

#log(message) ⇒ TrueClass

Write a message to the Vedeu log file located at ‘$HOME/.vedeu/vedeu.log`

Examples:

Vedeu.log('A useful debugging message: Error!')



129
130
131
 
# File 'lib/vedeu/api/api.rb', line 129

def log(message)
  Vedeu::Log.logger.debug(message) if Configuration.debug?
end

#resize ⇒ Object

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

Returns [].



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

def resize
  trigger(:_clear_)

  trigger(:_refresh_)
end

#shutdown ⇒ Exception

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



248
249
250
251
252
 
# File 'lib/vedeu/api/api.rb', line 248

def shutdown
  trigger(:_cleanup_)

  fail StopIteration
end

#trigger(name, *args) ⇒ Array

Trigger a registered or system event by name with arguments.

Examples:

Vedeu.trigger(:my_event, :oxidize, 'nitrogen')



144
145
146
 
# File 'lib/vedeu/api/api.rb', line 144

def trigger(name, *args)
  Vedeu.events.trigger(name, *args)
end

#unevent(name) ⇒ Hash

Unregister an event by name.



57
58
59
 
# File 'lib/vedeu/api/api.rb', line 57

def unevent(name)
  Vedeu.events.unevent(name)
end

#use(name) ⇒ Vedeu::Interface

Use attributes of another interface whilst defining one. TODO: More help.

Examples:

Vedeu.interface 'main_screen' do
  ... some attributes ...
  width use('my_interface').width
  x     use('my_interface').east(1)
end



162
163
164
 
# File 'lib/vedeu/api/api.rb', line 162

def use(name)
  Vedeu::Interface.new(Vedeu::Buffers.retrieve_attributes(name))
end

#view(name, &block) ⇒ Hash

Define a view (content) for an interface. TODO: More help.

Examples:

view 'my_interface' do
  ... some view attributes ...
end



179
180
181
 
# File 'lib/vedeu/api/api.rb', line 179

def view(name, &block)
  API::Composition.build { view(name, &block) }
end

#views(&block) ⇒ Hash Also known as: composition

Instruct Vedeu to treat contents of block as a single composition.

Examples:

views do
  view 'my_interface' do
    ... some attributes ...
  end
  view 'my_other_interface' do
    ... some other attributes ...
  end
end

composition do
  view 'my_interface' do
    ...
...



206
207
208
209
210
 
# File 'lib/vedeu/api/api.rb', line 206

def views(&block)
  fail InvalidSyntax, '`views` requires a block.' unless block_given?

  API::Composition.build(&block)
end

#width ⇒ Fixnum

Find out how many columns the current terminal is able to display.

Examples:

Vedeu.width



220
221
222
 
# File 'lib/vedeu/api/api.rb', line 220

def width
  Terminal.width
end