Class: Tkri::App

Inherits:

Object

• Object
• Tkri::App

Defined in:

lib/tkri.rb

Instance Method Summary

• #_post_process_text(text) ⇒ Object

  Enhance the ri text a bit.

• #execute(command) ⇒ Object

  Execute is the same as invoke_command() except that we don’t provide an event.

• #fetch_ri(topic) ⇒ Object

  Executes the ‘ri’ command and returns its output.

• #go(topic = nil, newtab = false) ⇒ Object

  Navigates to some topic.

• #help_key_bindings ⇒ Object
• #help_known_issues ⇒ Object
• #help_overview ⇒ Object
• #help_rc ⇒ Object
• #help_tips_and_tricks ⇒ Object
• #helpbox(title, text) ⇒ Object
• #initialize ⇒ App constructor

  A new instance of App.

• #interactive_initiate_search(e) ⇒ Object
• #interactive_quit(e) ⇒ Object
• #interactive_search_next(e) ⇒ Object
• #interactive_search_prev(e) ⇒ Object
• #invoke_command(command, event) ⇒ Object

  Invokes an “interactive” command (see Settings::BINDINGS).

• #refresh_tabsbar ⇒ Object
• #run ⇒ Object
• #status=(status) ⇒ Object

  Sets the text to show in the status bar.

Constructor Details

#initialize ⇒ App

Returns a new instance of App.

# File 'lib/tkri.rb', line 806

def initialize
  @root = root = TkRoot.new { title 'Tkri' }
  @search_word = nil
  
  Tkri.the_application = self
  
  Settings.load
 
  menu_spec = [
    [['File', 0],
      ['New tab', proc { execute 'interactive_new_tab' }, 0, 'Ctrl+T' ],
      ['Close tab', proc { execute 'interactive_close_tab' }, 0, 'Ctrl+W' ],
      '---',
      ['Quit', proc { execute 'interactive_quit' }, 0, 'Ctrl+Q' ]],
    [['Search', 0],
      ['Search', proc { execute 'interactive_initiate_search' }, 0, '/'],
      ['Repeat search', proc { execute 'interactive_search_next' }, 0, 'n'],
      ['Repeat backwards', proc { execute 'interactive_search_prev' }, 7, 'N']],
    # The following :menu_name=>'help' has no effect, but it should have...
    # probably a bug in RubyTK.
    [['Help', 0, { :menu_name => 'help' }],
      ['Overview', proc { help_overview }, 0],
      ['Key bindings', proc { help_key_bindings }, 0],
      ['Tips and tricks', proc { help_tips_and_tricks }, 0],
      ['About the $HOME/.tkrirc file', proc { help_rc }, 0],
      ['Known issues', proc { help_known_issues }, 0]],
  ]
  TkMenubar.new(root, menu_spec).pack(:side => 'top', :fill => 'x')

  @tabs = Tabs.new(root, self) {
    pack :side => 'top', :fill => 'both', :expand => true
  }
  @tabsbar = Tabsbar.new(root, @tabs) {
    pack :side => 'top', :fill => 'x', :before => @tabs
  }
  @statusbar = TkLabel.new(root, :anchor => 'w') {
    pack :side => 'bottom', :fill => 'x'
  }

  Tkri::attach_bindings root, 'root'
end

Instance Method Details

#_post_process_text(text) ⇒ Object

Enhance the ri text a bit.

# File 'lib/tkri.rb', line 957

def _post_process_text(text)

  # Make the "Multiple choices" output easier to read.
  if text.match /Multiple choices/
    text.gsub! /,\s+/, "\n"
    text.gsub! /^ */,  ""
    text.gsub! /\n/,   "\n     "
  end

  # Highlight the names of included modules.
  bold_on  = "\x1b[1m"
  bold_off = "\x1b[0m"
  parts = text.split /([\r\n]\S*Includes:.*?[\r\n][\r\n])/m
  parts.map! { |s|
    if s =~ /[\r\n]\S*Includes:/
      # Modules have parentheses following them.
      s.gsub! /(\S+)\(/, bold_on + '\1' + bold_off + '('
    else
      s
    end
  }
  text = parts.join

  return text
end

#execute(command) ⇒ Object

Execute is the same as invoke_command() except that we don’t provide an event. It’s existence is for aesthetics’ sake only. It is used in menus.

# File 'lib/tkri.rb', line 863

def execute(command)
  invoke_command(command, nil)
end

#fetch_ri(topic) ⇒ Object

Executes the ‘ri’ command and returns its output.

# File 'lib/tkri.rb', line 927

def fetch_ri topic
  if !@ri_cache
    @ri_cache = {}
    @cached_topics = []
  end

  return @ri_cache[topic] if @ri_cache[topic]

  command = Settings::COMMAND.select { |k,v| RUBY_PLATFORM.index(k) }.first.to_a[1] || Settings::COMMAND['__default__']
  text = Kernel.`(command % topic)  # `
  if $? != 0
    text += "\n" + "ERROR: Failed to run the command '%s' (exit code: %d). Please make sure you have this command in your PATH.\n\nYou may wish to modify this program's source (%s) to update the command to something that works on your system." % [command % topic, $?, $0]
  else
    if text == "nil\n"
      text = 'Topic "%s" not found.' % topic
    end
    text = _post_process_text(text)
    @ri_cache[topic] = text
    @cached_topics << topic
  end

  # Remove the oldest topic from the cache
  if @cached_topics.length > 20
    @ri_cache.delete @cached_topics.shift
  end

  return text
end

#go(topic = nil, newtab = false) ⇒ Object

Navigates to some topic. This method simply delegates to the current tab.

# File 'lib/tkri.rb', line 876

def go(topic=nil, newtab=false)
  @tabs.new_tab if newtab and not @tabs.current_tab.new?
  @tabs.current_tab.go topic
end

#help_key_bindings ⇒ Object

# File 'lib/tkri.rb', line 1010

def help_key_bindings
  helpbox('Help: Key bindings', <<EOS)
These are the *default* bindings. They are configurable via the 'rc' file.

Left mouse button
  Navigate to the topic under the cursor.
Ctrl + Left mouse button
  Navigate to the topic selected (marked) with the mouse.
Middle mouse button
  Navigate to the topic under the cursor. Opens in a new tab.
Right mouse button, Backspace, Alt+Left
  Move back in the history.
Alt+Right
  Move foreward in the history.
Ctrl+W. Or middle mouse button, on a tab button
  Close the tab (unless this is the only tab).
Ctrl+L
  Move the keyboard focus to the "address" box, where you can type a topic.
Ctrl+T
  New tab.
Alt+1 .. Alt+9, Ctrl+PgUp, Ctrl+PgDn
  Swith to a certain tab, or to the next/previous one.
u
  Goes "up" one level. That is, if you're browsing Module::Class#method,
  you'll be directed to Module::Class. Press 'u' again for Module.
Enter
  Go to the topic under the caret, or, if some text is selected, to the
  topic selected.
/
  Find string in page. 
n, N
  Jump to next/previous finds.
EOS
end

#help_known_issues ⇒ Object

# File 'lib/tkri.rb', line 1099

def help_known_issues
  helpbox('Help: Known issues', <<EOS)
Here's a list of known issues / bugs:

ON THE WINDOWS PLATFORM:

* The mouse wheel works only if the keyboard focus is in the
textarea. That's unfortunate. It's a Tk issue, not Tkri's.

* If your $HOME variable contains non-ASCII charcaters, Tkri
seems not to be able to deal with the 'rc' file. It's a Ruby
issue(?).

ALL PLATFORMS:

* No known issues.
EOS
end

#help_overview ⇒ Object

# File 'lib/tkri.rb', line 990

def help_overview
  helpbox('Help: Overview', <<EOS)
ABOUT

Tkri (pronounce TIK-ri) is a GUI front-end to the 'ri', or
'qri', executables. By default it uses 'qri', which is part
of the Fast-RI package.

Tkri displays the output of that program in a window where
each work is "hyperlinked".

USAGE

Launch tkri by typing 'tkri' at the operating system prompt. You
can provide a starting topic as an argument on the command line.
Inside the application, type the topic you wish to go to at the
address bar, or click on a word in the main text.
EOS
end

#help_rc ⇒ Object

# File 'lib/tkri.rb', line 1074

def help_rc
  helpbox('Help: RC', <<EOS)
Tkri has some settings. E.g., the colors and fonts it uses.

These settings are hard-coded in the source code. But you can
override them by having an 'rc' file in your home folder. On
your system this file is here:

  #{Tkri.get_rc_file_path}

(If it's at a weird place, set your $HOME environment variable.)

Of course, you're a busy person and don't have time to write
this file from scratch. So you're going to tell Tkri to write
this file for you; When you type:

  tkri --dump-rc

you're telling Tkri to dump all its default settings into that
file. Then edit this file to your liking using your text editor.
Finally, run tkri; it will automatically merge the settings from
this file onto the hard-coded ones.
EOS
end

#help_tips_and_tricks ⇒ Object

# File 'lib/tkri.rb', line 1045

def help_tips_and_tricks
  helpbox('Help: Tips and tricks', <<EOS)
Some random tips:

Type '/' to quickly highlight a string in the page. (If the
string happens to be off-screen, hit ENTER to jump to it.)

Ctrl+L is probably the fastest way to move the keyboard
focus to the "address box".

The references for "Hash", "Array" and "String" are the most
sought-after, so instead of typing their full name in the address
box you can just type the letters h, a or s, respectively.

You can type the topic(s) directly on the command line;
e.g., "tkri Array.flatten sort_by"

Left-clicking on a word doesn't yet send you to a new page. It's
*releasing* the button that sends you there. This makes it possible to
select pieces of code: left-click, then drag, then release; since some
text is now selected, Tkri figures out that's all you wanted.

When using Enter to go to a selected (marked) topic, note that it's easier
to hit the Enter of the keypad, with your thumb, because it's near the
mouse (provided you're right-handed). As a bonus, you can navigate with one
hand only.
EOS
end

#helpbox(title, text) ⇒ Object

# File 'lib/tkri.rb', line 983

def helpbox(title, text)
  w = TkToplevel.new(:title => title)
  t = TkText.new(w, :height => text.count("\n"), :width => 80).pack.insert('1.0', text)
  t.configure Settings::get_configuration('__base__')
  TkButton.new(w, :text => 'Close', :command => proc { w.destroy }).pack
end

#interactive_initiate_search(e) ⇒ Object

# File 'lib/tkri.rb', line 904

def interactive_initiate_search e
  self.status = 'Type the string to search'
  entry = TkEntry.new(@root).pack(:fill => 'x').focus
  ['Key-Return', 'Key-KP_Enter'].each do |event|
    entry.bind(event) {
      self.status = ''
      @search_word = entry.get
      @tabs.current_tab.search_next_word entry.get
      entry.destroy
    }
  end
  ['Key-Escape', 'FocusOut'].each do |event|
    entry.bind(event) {
      self.status = ''
      entry.destroy
    }
  end
  entry.bind('KeyRelease') {
    @tabs.current_tab.highlight_word entry.get
  }
end

#interactive_quit(e) ⇒ Object

# File 'lib/tkri.rb', line 867

def interactive_quit e
  exit
end

#interactive_search_next(e) ⇒ Object

# File 'lib/tkri.rb', line 896

def interactive_search_next e
  if @search_word
    @tabs.current_tab.search_next_word @search_word
  else
    interactive_initiate_search nil
  end
end

#interactive_search_prev(e) ⇒ Object

# File 'lib/tkri.rb', line 890

def interactive_search_prev e
  if @search_word
    @tabs.current_tab.search_prev_word @search_word
  end
end

#invoke_command(command, event) ⇒ Object

Invokes an “interactive” command (see Settings::BINDINGS). The command is searched in App, Tabs, Tabsbar, Tab, in this order.

# File 'lib/tkri.rb', line 850

def invoke_command(command, event)
  possible_targets = [self, @tabs, @tabsbar, @tabs.current_tab]
  possible_targets.each { |target|
    if target.respond_to?(command, true)
      target.send(command, event)
      break
    end
  }
end

#refresh_tabsbar ⇒ Object

# File 'lib/tkri.rb', line 886

def refresh_tabsbar
  @tabsbar.build_buttons if @tabsbar
end

#run ⇒ Object

# File 'lib/tkri.rb', line 871

def run
  Tk.mainloop
end

#status=(status) ⇒ Object

Sets the text to show in the status bar.

# File 'lib/tkri.rb', line 882

def status=(status)
  @statusbar.configure(:text => status)
end