class Flammarion::Engraving

The engraving class represents a window. It contains everything you need to display on the screen and interacts with a user. An {Engraving} contains one or more panes, which are containers for writeable areas. Most of the power of the panes comes from the {Writeable} module, which is also included in {Engraving} (operating on the default pane) for convenience. @see Writeable @note Right now, there is no persistence of Engravings. Once it is closed,

everything is erased, and you'll need to set it up all over again.

@note If you try to display something to a closed window, it will open a new

blank window, and then display that thing.

Attributes

actions[RW]
callbacks[RW]
on_callback_exception[RW]
on_connect[RW]
on_disconnect[RW]
sockets[RW]

Public Class Methods

new(options = {}) click to toggle source

Creates a new Engraving (i.e., a new display window) @option options [Proc] :on_connect Called when the display window is

connected (i.e., displayed)

@option options [Proc] :on_disconnect Called when the display windows is

disconnected (i.e., closed)

@option options [Proc] :on_callback_exception Called when there is an

exception executing a provided callback. (e.g., so you can log it)
If no handler is provided, Flammarion will attempt to pass the exception
back to the original calling thread.

@option options [Boolean] :exit_on_disconnect (false) Will call exit

when the widow is closed if this option is true.

@option options [Boolean] :close_on_exit (false) Will close the window

when the process exits if this is true. Otherwise, it will just stay
around, but not actually be interactive.

@option options [String] :title The initial title of the engraving. If

empty, a random title will be generated.

@raise {SetupError} if neither chrome nor electron is set up correctly and

and Flammarion is unable to display the engraving.
# File lib/flammarion/engraving.rb, line 37
def initialize(options = {})
  options = {:title => options} if options.is_a?(String)
  @chrome = OpenStruct.new
  @sockets = []
  @actions = {}
  @engraving = self
  @pane_name = "default"
  @on_connect = options[:on_connect]
  @on_disconnect = options[:on_disconnect]
  @on_callback_exception = options[:on_callback_exception]
  @exit_on_disconnect = options.fetch(:exit_on_disconnect, false)

  start_server
  @window_id = @@server.register_window(self)
  open_a_window(options) unless options[:no_window]
  @callbacks = {}
  wait_for_a_connection unless options[:no_wait]

  at_exit {close if window_open?} if options.fetch(:close_on_exit, true)

  title options[:title] if options[:title]
end

Public Instance Methods

alert(text) click to toggle source

Pops up an alert message containing text.

# File lib/flammarion/engraving.rb, line 72
def alert(text)
  send_json(action:'alert', text:text)
end
close() click to toggle source

Attempts to close the window.

# File lib/flammarion/engraving.rb, line 90
def close
  send_json({action:'close'})
end
disconnect(ws) click to toggle source

@api private

# File lib/flammarion/engraving.rb, line 128
def disconnect(ws)
  @sockets.delete ws
  exit 0 if @exit_on_disconnect
  @on_disconnect.call if @on_disconnect
end
get_save_path() click to toggle source

Opens a native “Save File” Dialog box, prompting the user for a file.

# File lib/flammarion/engraving.rb, line 95
def get_save_path
  if Gem.win_platform?
    `powershell "Add-Type -AssemblyName System.windows.forms|Out-Null;$f=New-Object System.Windows.Forms.SaveFileDialog;$f.InitialDirectory='%cd%';$f.Filter='All Files (*.*)|*.*';$f.showHelp=$true;$f.ShowDialog()|Out-Null;$f.FileName"`.strip
  else
    `zenity --file-selection --save --confirm-overwrite`.strip
  end
end
layout(file) click to toggle source

Allows you to load a custom layout file. This replaces all html in the window with a custom slim layout. You probably don’t want this unless your writing a very complex application.

# File lib/flammarion/engraving.rb, line 122
def layout(file)
  data = Slim::Template.new(file).render
  send_json({action:'layout', data:data})
end
make_id() click to toggle source

@api private

# File lib/flammarion/engraving.rb, line 166
def make_id
  @id ||= 0
  @id += 1
  "i#{@id}"
end
orientation=(orientation) click to toggle source

Changes the orientation of the panes in this engraving. Options are

  • :horizontal

  • :vertical

# File lib/flammarion/engraving.rb, line 79
def orientation=(orientation)
  raise ArgumentError.new("Orientation must be :horizontal or :vertical") unless [:horizontal, :vertical].include?(orientation)
  send_json({action:'reorient', orientation:orientation})
end
process_message(msg) click to toggle source

@api private

# File lib/flammarion/engraving.rb, line 135
def process_message(msg)
  @last_msg = msg
  m = {}
  begin
    m = JSON.parse(msg)
  rescue JSON::ParserError
    log "Invalid JSON String"
    return
  end

  case m["action"]
  when 'callback'
    callback = @callbacks[m['id']]
    unless callback.nil?
      if callback.arity == 1
        callback.call(m)
      else
        callback.call
      end
    end
  end
  @actions[m["action"]].call(m) if @actions.include?(m["action"])
rescue Exception
  if @on_callback_exception then
    @on_callback_exception.call($!)
  else
    raise
  end
end
send_json(val) click to toggle source

@api private

# File lib/flammarion/engraving.rb, line 181
def send_json(val)
  if @sockets.empty? then
    open_a_window
    wait_for_a_connection
  end
  @sockets.each{|ws| ws.send val.to_json}
  nil
end
server() click to toggle source

@api private

# File lib/flammarion/engraving.rb, line 178
def server; @@server; end
snapshot(&block) click to toggle source

Currently only works with Electron. Returns a PNG image of the Engraving

# File lib/flammarion/engraving.rb, line 104
def snapshot(&block)
  if block_given?
    id = make_id
    callbacks[id] = Proc.new {|d| block.call(d.fetch('data', {}).fetch('data', []).pack('c*')) }
    send_json(action:'snapshot', id: id)
  else
    return_value = nil
    snapshot {|d| return_value = d}
    Timeout.timeout(10) do
      sleep(0.01) until return_value
    end
    return return_value
  end
end
start_server() click to toggle source

@api private

# File lib/flammarion/engraving.rb, line 173
def start_server
  @@server ||= Server.new
end
title(str) click to toggle source

Sets the title of the window

# File lib/flammarion/engraving.rb, line 85
def title(str)
  send_json({action:'title', title:str})
end
wait_until_closed() click to toggle source

Blocks the current thread until the window has been closed. All user interactions and callbacks will continue in other threads.

# File lib/flammarion/engraving.rb, line 62
def wait_until_closed
  sleep 1 until @sockets.empty?
end
window_open?() click to toggle source

Is this Engraving displayed on the screen.

# File lib/flammarion/engraving.rb, line 67
def window_open?
  not @sockets.empty?
end