sforman
/
Thun
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Thun/docs/VUI-docs/build/html/index.html

242 lines
13 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Welcome to Joy VUI’s documentation! &#8212; Joy VUI 0.1 documentation</title>
<link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/language_data.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Core" href="core.html" />
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="welcome-to-joy-vui-s-documentation">
<h1>Welcome to Joy VUI’s documentation!<a class="headerlink" href="#welcome-to-joy-vui-s-documentation" title="Permalink to this headline"></a></h1>
<p>A simple Graphical User Interface for the Joy programming language,
written using Pygame to bypass X11 et. al., modeled on the Oberon OS, and
intended to be just functional enough to support bootstrapping further Joy
development.</p>
<div class="section" id="screenshot">
<h2>Screenshot<a class="headerlink" href="#screenshot" title="Permalink to this headline"></a></h2>
<img alt="_images/Joy-VUI-screenshot.PNG" src="_images/Joy-VUI-screenshot.PNG" />
</div>
<div class="section" id="quick-start">
<h2>Quick Start<a class="headerlink" href="#quick-start" title="Permalink to this headline"></a></h2>
<p>If you have PyGame and Dulwich installed you should be able to start the
VUI with the following command:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">joy</span><span class="o">.</span><span class="n">vui</span>
</pre></div>
</div>
<p>This will create a <code class="docutils literal notranslate"><span class="pre">~/.thun</span></code> directory in your home dir to store your
data.</p>
</div>
<div class="section" id="how-it-works-now">
<h2>How it works now.<a class="headerlink" href="#how-it-works-now" title="Permalink to this headline"></a></h2>
<p>The VUI is more-or-less a crude text editor along with
a simple Joy runtime (interpreter, stack, and dictionary.) It auto-saves
any named files (in a versioned home directory) and you can write new Joy
primitives in Python and Joy definitions and immediately install and use
them, as well as recording them for reuse (after restarts.)</p>
<p>The only dependencies are Pygame and Dulwich (a Python Git library.)</p>
<p>When the main.py script starts it checks for an environment var “JOY_HOME”
which should point to a directory where you want the system to store the
files (“resources”) it will edit and save, this directory defaults to
<code class="docutils literal notranslate"><span class="pre">~/.thun</span></code>. The first time you run it, it will create some default files
as content. Right click on see_resources to open a viewer with the list
of resources (files), copy a name to the stack and right click on
open_resource_at_good_location to open a viewer on that resource.</p>
<p>Right now the screen size defaults to windowed 1024x768, but if you pass
the <code class="docutils literal notranslate"><span class="pre">-f</span></code> option to the main.py script the UI will take up the full screen
at the highest available resolution. The window is divided into two (or
three in fullscreen) vertical “tracks”, and the number and width of the
tracks are fixed at start up. (Feel free to edit the values in main.py to
play around with different track configurations.) Each track gets divided
horizontally into zero or more “viewers” (like windows in a windowed GUI,
cf. Chapter 4 of “Project Oberon”) for a kind of tiled layout.</p>
<p>Currently, there are only two kinds of (interesting) viewers: TextViewers
and StackViewer. The TextViewers are crude text editors. They provide
just enough functionality to let the user write text and code (Python and
Joy) and execute Joy functions. One important thing they do is
automatically save their content after changes. No more lost work.</p>
<p>The StackViewer is a specialized TextViewer that shows the contents of the
Joy stack one line per stack item. It’s a very handy visual aid to keep
track of what’s going on. There’s also a log.txt file that gets written
to when commands are executed, and so records the log of user actions and
system events. It tends to fill up quickly so there’s a reset_log command
that clears it out.</p>
<p>Viewers have “grow” and “close” in their menu bars. These are buttons.
When you right-click on grow a viewer a copy is created that covers that
viewer’s entire track. If you grow a viewer that already takes up its
whole track then a copy is created that takes up an additional track, up
to the whole screen. Closing a viewer just deletes that viewer, and when
a track has no more viewers, it is deleted and that exposes any previous
tracks and viewers that were hidden.</p>
<p>(Note: if you ever close all the viewers and are sitting at a blank screen
with nowhere to type and execute commands, press the Pause/Break key.
This will open a new “trap” viewer which you can then use to recover.)</p>
<p>Copies of a viewer all share the same model and update their display as it
changes. (If you have two viewers open on the same named resource and edit
one you’ll see the other update as you type.)</p>
</div>
<div class="section" id="ui-guide">
<h2>UI Guide<a class="headerlink" href="#ui-guide" title="Permalink to this headline"></a></h2>
<p>left mouse sets cursor in text, in menu bar resizes viewer interactively
(this is a little buggy in that you can move the mouse quickly and get
outside the menu, leaving the viewer in the “resizing” state. Until I fix
this, the workaround is to just grab the menu bar again and wiggle it a
few pixels and let go. This will reset the machinery.)</p>
<p>Right mouse executes Joy command (functions), and you can drag with the
right button to highlight (well, underline) commands. Words that aren’t
names of Joy commands won’t be underlined. Release the button to execute
the command.</p>
<p>The middle mouse button (usually a wheel these days) scrolls the text but
you can also click and drag any viewer with it to move that viewer to
another track or to a different location in the same track. There’s no
direct visual feedback for this (yet) but that dosen’t seem to impair its
usefulness.</p>
<p>F1, F2 - set selection begin and end markers (crude but usable.)</p>
<p>F3 - copy selected text to the top of the stack.</p>
<p>Shift-F3 - as copy then run “parse” command on the string.</p>
<p>F4 - cut selected text to the top of the stack.</p>
<p>Shift-F4 - as cut then run “pop” (delete selection.)</p>
</div>
<div class="section" id="joy">
<h2>Joy<a class="headerlink" href="#joy" title="Permalink to this headline"></a></h2>
<p>Pretty much all of the rest of the functionality of the system is provided
by executing Joy commands (aka functions, aka “words” in Forth) by right-
clicking on their names in any text.</p>
<p>To get help on a Joy function select the name of the function in a
TextViewer using F1 and F2, then press shift-F3 to parse the selection.
The function (really its Symbol) will appear on the stack in brackets (a
“quoted program” such as “[pop]”.) Then right-click on the word help in
any TextViewer (if it’s not already there, just type it in somewhere.)
This will print the docstring or definition of the word (function) to
stdout. At some point I’ll write a thing to send that to the log.txt file
instead, but for now look for output in the terminal.</p>
</div>
<div class="section" id="modules">
<h2>Modules<a class="headerlink" href="#modules" title="Permalink to this headline"></a></h2>
<img alt="_images/packages_Vui.png" src="_images/packages_Vui.png" />
<div class="toctree-wrapper compound">
<p class="caption"><span class="caption-text">Contents:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="core.html">Core</a></li>
<li class="toctree-l1"><a class="reference internal" href="main.html">Main Module</a></li>
<li class="toctree-l1"><a class="reference internal" href="display.html">Display</a></li>
<li class="toctree-l1"><a class="reference internal" href="viewer.html">Viewer</a></li>
<li class="toctree-l1"><a class="reference internal" href="text_viewer.html">Text Viewer</a></li>
<li class="toctree-l1"><a class="reference internal" href="stack_viewer.html">Stack Viewer</a></li>
<li class="toctree-l1"><a class="reference internal" href="persist_task.html">Persist Task</a></li>
</ul>
</div>
</div>
<div class="section" id="start-up-sequence">
<h2>Start Up Sequence<a class="headerlink" href="#start-up-sequence" title="Permalink to this headline"></a></h2>
<p>PersistTask is the first (non-PyGame-specific) object created.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">screen</span></code>, <code class="docutils literal notranslate"><span class="pre">clock</span></code>, and <code class="docutils literal notranslate"><span class="pre">pt</span></code> are created in <code class="docutils literal notranslate"><span class="pre">init()</span></code> and passed
into <code class="docutils literal notranslate"><span class="pre">main()</span></code>, which calls <code class="docutils literal notranslate"><span class="pre">init_context()</span></code> and then starts
the main loop.</p>
<p>During <code class="docutils literal notranslate"><span class="pre">init_context()</span></code> a few text viewers are opened on files
in the home dir with the help of the <code class="docutils literal notranslate"><span class="pre">pt</span></code>. Then the main loop
is started and the <code class="docutils literal notranslate"><span class="pre">pt</span></code> task is installed and <code class="docutils literal notranslate"><span class="pre">pt</span></code> and <code class="docutils literal notranslate"><span class="pre">world</span></code>
handlers are registered.</p>
</div>
<div class="section" id="indices-and-tables">
<h2>Indices and tables<a class="headerlink" href="#indices-and-tables" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li><a class="reference internal" href="genindex.html"><span class="std std-ref">Index</span></a></li>
<li><a class="reference internal" href="py-modindex.html"><span class="std std-ref">Module Index</span></a></li>
<li><a class="reference internal" href="search.html"><span class="std std-ref">Search Page</span></a></li>
</ul>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="#">Joy VUI</a></h1>
<h3>Navigation</h3>
<p class="caption"><span class="caption-text">Contents:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="core.html">Core</a></li>
<li class="toctree-l1"><a class="reference internal" href="main.html">Main Module</a></li>
<li class="toctree-l1"><a class="reference internal" href="display.html">Display</a></li>
<li class="toctree-l1"><a class="reference internal" href="viewer.html">Viewer</a></li>
<li class="toctree-l1"><a class="reference internal" href="text_viewer.html">Text Viewer</a></li>
<li class="toctree-l1"><a class="reference internal" href="stack_viewer.html">Stack Viewer</a></li>
<li class="toctree-l1"><a class="reference internal" href="persist_task.html">Persist Task</a></li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="#">Documentation overview</a><ul>
<li>Next: <a href="core.html" title="next chapter">Core</a></li>
</ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&copy;2019, Simon Forman.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 1.8.5</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.9</a>
|
<a href="_sources/index.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink