Difference between revisions of "Zircon"

From RogueBasin
Jump to navigation Jump to search
Line 73: Line 73:
</table>
</table>


    <h1>Zircon - A user-friendly Text GUI &amp; Tile Engine <a
= Zircon - A user-friendly Text GUI &amp; Tile Engine [https://twitter.com/intent/tweet?text=Do%20you%20plan%20to%20make%20a%20roguelike%3F%20Look%20no%20further.%20Zircon%20is%20the%20right%20tool%20for%20the%20job.&url=https://github.com/Hexworks/zircon&hashtags=games,roguelikes [[File:https://img.shields.io/twitter/url/http/shields.io.svg?style=social|Tweet]]] =
            href="https://twitter.com/intent/tweet?text=Do%20you%20plan%20to%20make%20a%20roguelike%3F%20Look%20no%20further.%20Zircon%20is%20the%20right%20tool%20for%20the%20job.&amp;url=https://github.com/Hexworks/zircon&amp;hashtags=games,roguelikes"
            rel="nofollow"><img
            src="https://camo.githubusercontent.com/83d4084f7b71558e33b08844da5c773a8657e271/68747470733a2f2f696d672e736869656c64732e696f2f747769747465722f75726c2f687474702f736869656c64732e696f2e7376673f7374796c653d736f6369616c"
            alt="Tweet"
            data-canonical-src="https://img.shields.io/twitter/url/http/shields.io.svg?style=social"
            style="max-width:100%;"></a></h1>
    <p><a target="_blank" rel="noopener noreferrer"
          href="https://camo.githubusercontent.com/31564d6b382ec94480dfb50fed542c112c86239f/68747470733a2f2f63646e2e646973636f72646170702e636f6d2f6174746163686d656e74732f3230353234353033363038343938353835372f3438313231333030303534303232353535302f66756c6c5f6578616d706c652e676966"><img
            src="https://camo.githubusercontent.com/31564d6b382ec94480dfb50fed542c112c86239f/68747470733a2f2f63646e2e646973636f72646170702e636f6d2f6174746163686d656e74732f3230353234353033363038343938353835372f3438313231333030303534303232353535302f66756c6c5f6578616d706c652e676966"
            data-canonical-src="https://cdn.discordapp.com/attachments/205245036084985857/481213000540225550/full_example.gif"
            style="max-width:100%;"></a></p>
    <p><em>Note that</em> this library was inspired by <a
            href="https://github.com/mabe02/lanterna">Lanterna</a>.
        Check it out if you are looking for a <em>terminal emulator</em> instead.</p>
    <hr>
    <p>Need info? Check the <a href="https://github.com/Hexworks/zircon/wiki">Wiki</a>
        | or <a href="https://github.com/Hexworks/zircon/issues/new">Create an issue</a>
        | Check <a href="https://github.com/Hexworks/zircon/projects/2">our project
            Board</a>
        | <a href="https://discord.gg/hbzytQJ" rel="nofollow">Ask us on Discord</a> |
        Support us on <a href="https://www.patreon.com/hexworks" rel="nofollow">Patreon</a>
    </p>
    <p><a href="https://circleci.com/gh/Hexworks/zircon" rel="nofollow"><img
            src="https://camo.githubusercontent.com/379b1e8a8e5cee1db443e5bb6cc2a25fbc761388/68747470733a2f2f636972636c6563692e636f6d2f67682f486578776f726b732f7a6972636f6e2f747265652f6d61737465722e7376673f7374796c653d736869656c64"
            alt=""
            data-canonical-src="https://circleci.com/gh/Hexworks/zircon/tree/master.svg?style=shield"
            style="max-width:100%;"></a>
        <a href="https://mvnrepository.com/artifact/org.hexworks.zircon/zircon/2017.4.0"
          rel="nofollow"><img
                src="https://camo.githubusercontent.com/3328276fb64554ce9e5f1d6273b4949f5d02b8df/68747470733a2f2f6d6176656e2d6261646765732e6865726f6b756170702e636f6d2f6d6176656e2d63656e7472616c2f6f72672e686578776f726b732e7a6972636f6e2f7a6972636f6e2f62616467652e737667"
                alt=""
                data-canonical-src="https://maven-badges.herokuapp.com/maven-central/org.hexworks.zircon/zircon/badge.svg"
                style="max-width:100%;"></a>
        <a href="https://jitpack.io/#Hexworks/Zircon" rel="nofollow"><img
                src="https://camo.githubusercontent.com/2aa4405cdb116464e70666b89b608ed299110c8e/68747470733a2f2f6a69747061636b2e696f2f762f486578776f726b732f5a6972636f6e2e737667"
                alt="" data-canonical-src="https://jitpack.io/v/Hexworks/Zircon.svg"
                style="max-width:100%;"></a>
        <a href="https://codecov.io/github/Hexworks/zircon?branch=master"
          rel="nofollow"><img
                src="https://camo.githubusercontent.com/e13753971a4b1a27eab4a5ec5cfb8c400aa8c78e/68747470733a2f2f636f6465636f762e696f2f6769746875622f486578776f726b732f7a6972636f6e2f636f7665726167652e7376673f6272616e63683d6d6173746572"
                alt=""
                data-canonical-src="https://codecov.io/github/Hexworks/zircon/coverage.svg?branch=master"
                style="max-width:100%;"></a>
        <a href="https://github.com/Hexworks/zircon/blob/master/LICENSE"><img
                src="https://camo.githubusercontent.com/76f0e887c183ccc31c1cb63c33d2dbf48cb2df51/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d677265656e2e737667"
                alt=""
                data-canonical-src="https://img.shields.io/badge/License-MIT-green.svg"
                style="max-width:100%;"></a>
        <a href="https://github.com/sindresorhus/awesome"><img
                src="https://camo.githubusercontent.com/13c4e50d88df7178ae1882a203ed57b641674f94/68747470733a2f2f63646e2e7261776769742e636f6d2f73696e647265736f726875732f617765736f6d652f643733303566333864323966656437386661383536353265336136336531353464643865383832392f6d656469612f62616467652e737667"
                alt="Awesome"
                data-canonical-src="https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg"
                style="max-width:100%;"></a></p>
    <hr>
    <h2>>Table of Contents</h2>
    <ul>
        <li><a href="https://github.com/Hexworks/zircon#getting-started">Getting Started</a>
            <ul>
                <li><a href="https://github.com/Hexworks/zircon#some-rules-of-thumb">Some
                    rules of thumb</a></li>
                <li><a href="https://github.com/Hexworks/zircon#creating-an-application">Creating
                    an Application</a></li>
                <li><a href="https://github.com/Hexworks/zircon#working-with-screens">Working
                    with Screens</a></li>
                <li><a href="https://github.com/Hexworks/zircon#components">Components</a>
                </li>
                <li><a href="https://github.com/Hexworks/zircon#additional-features">Additional
                    features</a>
                    <ul>
                        <li>
                            <a href="https://github.com/Hexworks/zircon#layering">Layering</a>
                        </li>
                        <li><a href="https://github.com/Hexworks/zircon#input-handling">Input
                            handling</a></li>
                        <li>
                            <a href="https://github.com/Hexworks/zircon#shape-and-box-drawing">Shape
                                and box drawing</a></li>
                        <li><a href="https://github.com/Hexworks/zircon#fonts-and-tilesets">Fonts
                            and tilesets</a></li>
                        <li>
                            <a href="https://github.com/Hexworks/zircon#rexpaint-file-loading">REXPaint
                                file loading</a></li>
                        <li><a href="https://github.com/Hexworks/zircon#color-themes">Color
                            themes</a></li>
                        <li><a href="https://github.com/Hexworks/zircon#animations-beta">Animations
                            (BETA)</a></li>
                        <li><a href="https://github.com/Hexworks/zircon#the-api">The API</a>
                        </li>
                    </ul>
                </li>
            </ul>
        </li>
        <li><a href="https://github.com/Hexworks/zircon#road-map">Road map</a></li>
        <li><a href="https://github.com/Hexworks/zircon#license">License</a></li>
        <li><a href="https://github.com/Hexworks/zircon#credits">Credits</a></li>
    </ul>
    <h2><a id="user-content-getting-started" class="anchor" aria-hidden="true"
          href="#getting-started">
        <svg class="octicon octicon-link" viewBox="0 0 16 16" version="1.1" width="16"
            height="16" aria-hidden="true">
            <path fill-rule="evenodd"
                  d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path>
        </svg>
    </a>Getting Started
    </h2>
    <p>If you want to work with Zircon you can add it to your project as a dependency.</p>
    <p>from Maven:</p>
    <div class="highlight highlight-text-xml"><pre>&lt;<span
            class="pl-ent">dependency</span>&gt;
    &lt;<span class="pl-ent">groupId</span>&gt;com.github.hexworks.zircon&lt;/<span class="pl-ent">groupId</span>&gt;
    &lt;<span class="pl-ent">artifactId</span>&gt;zircon.jvm.swing&lt;/<span class="pl-ent">artifactId</span>&gt;
    &lt;<span class="pl-ent">version</span>&gt;2018.3.27-PREVIEW&lt;/<span class="pl-ent">version</span>&gt;
&lt;/<span class="pl-ent">dependency</span>&gt;</pre>
    </div>
    <p>or you can also use Gradle:</p>
    <div class="highlight highlight-source-groovy">
                                    <pre>compile(<span class="pl-s"><span class="pl-pds">"</span>com.github.hexworks.zircon:zircon.jvm.swing:2018.3.27-PREVIEW<span
                                            class="pl-pds">"</span></span>)</pre>
    </div>
    <p>Note that you need to use <a href="https://jitpack.io/#Hexworks/Zircon"
                                    rel="nofollow">Jitpack</a> for the above dependencies to
        work.</p>
    <p>Want to use a <code>PREVIEW</code>?
        Check <a
                href="https://github.com/Hexworks/zircon/wiki/Release-process-and-versioning-scheme#snapshot-releases">this
            Wiki page</a></p>
    <h3><a id="user-content-some-rules-of-thumb" class="anchor" aria-hidden="true"
          href="#some-rules-of-thumb">
        <svg class="octicon octicon-link" viewBox="0 0 16 16" version="1.1" width="16"
            height="16" aria-hidden="true">
            <path fill-rule="evenodd"
                  d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path>
        </svg>
    </a>Some rules of thumb
    </h3>
    <p>Before we start there are some guidelines which can help you if you are stuck:</p>
    <ul>
        <li>If you want to build something (a <code>TileGraphics</code>, a
            <code>Component</code> or anything which is part of the public API) it is almost
            sure that there is a <code>Builder</code> or a <code>Factory</code> for it. The
            convention is that if you want to create an <code>TileGraphics</code> for
            example,
            then you can use the <code>DrawSurfaces</code> class to do so. (so it is the
            plural form of the thing which you want to build). Your IDE
            will help you with this. These classes reside in the <code>org.hexworks.zircon.api</code>
            package.
        </li>
        <li>If you want to work with external files like tilesets or REXPaint files check
            the same package (<code>org.hexworks.zircon.api</code>), and look for
            classes which end with <code>*Resources</code>. There are a bunch of built-in
            tilesets for example which you can choose from but you can also
            load your own. The rule of thumb is that if you need something external there is
            probably a <code>*Resources</code> class
            for it (like the <a
                    href="https://github.com/Hexworks/zircon/blob/master/zircon.jvm/src/main/kotlin/org/hexworks/zircon/api/CP437TilesetResources.kt">CP437TilesetResources</a>).
        </li>
        <li>You can use <em>anything</em> you can find in the <a
                href="https://github.com/Hexworks/zircon/tree/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api">API</a>
            package, they are part of the public API, and safe to use. The
            <a href="https://github.com/Hexworks/zircon/tree/master/zircon.core/src/main/kotlin/org/hexworks/zircon/internal">internal</a>
            package however is considered private to Zircon so don't depend on anything in
            it.
        </li>
        <li>Some topics are explained in depth on the <a
                href="https://github.com/Hexworks/zircon/wiki">Wiki</a></li>
        <li>If you want to see some example code look <a
                href="https://github.com/Hexworks/zircon/tree/master/zircon.examples/src/main">here</a>.
        </li>
        <li>If all else fails read the javadoc. API classes are well documented.</li>
        <li>If you have any problems which are not answered here feel free to ask us at the
            <a href="https://discord.gg/hbzytQJ" rel="nofollow">Hexworks Discord server</a>.
        </li>
    </ul>
    <h3><a id="user-content-creating-an-application" class="anchor" aria-hidden="true"
          href="#creating-an-application">
        <svg class="octicon octicon-link" viewBox="0 0 16 16" version="1.1" width="16"
            height="16" aria-hidden="true">
            <path fill-rule="evenodd"
                  d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path>
        </svg>
    </a>Creating an Application
    </h3>
    <p>In Zircon almost every object you might want to use has a helper class for building
        it.
        This is the same for <a
                href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/application/Application.kt">Application</a>s
        as well so let's create one using the <a
                href="https://github.com/Hexworks/zircon/blob/master/zircon.jvm.swing/src/main/kotlin/org/hexworks/zircon/api/SwingApplications.kt">SwingApplications</a>
        class:</p>
    <blockquote>
        <p>Note that these examples reside in the
            <code>org.hexworks.zircon.examples.docs</code> package in the <code>zircon.examples</code>
            project,
            you can try them all out.</p>
    </blockquote>
    <div class="highlight highlight-source-java"><pre><span class="pl-k">import</span> <span
            class="pl-smi">org.hexworks.zircon.api.SwingApplications</span>;
<span class="pl-k">import</span> <span class="pl-smi">org.hexworks.zircon.api.application.Application</span>;


<span class="pl-k">public</span> <span class="pl-k">class</span> <span class="pl-en">CreatingAnApplication</span> {
<img src="https://cdn.discordapp.com/attachments/205245036084985857/481213000540225550/full_example.gif" />


    <span class="pl-k">public</span> <span class="pl-k">static</span> <span class="pl-k">void</span> <span
''Note that'' this library was inspired by [https://github.com/mabe02/lanterna Lanterna]. Check it out if you are looking for a ''terminal emulator'' instead.
                class="pl-en">main</span>(<span class="pl-k">String</span>[] <span
                class="pl-v">args</span>) {


        <span class="pl-smi">Application</span> application <span class="pl-k">=</span> <span class="pl-smi">SwingApplications</span><span
 
                class="pl-k">.</span>startApplication();
-----
 
Need info? Check the [https://github.com/Hexworks/zircon/wiki Wiki] | or [https://github.com/Hexworks/zircon/issues/new Create an issue] | Check [https://github.com/Hexworks/zircon/projects/2 our project Board] | [https://discord.gg/hbzytQJ Ask us on Discord] | Support us on [https://www.patreon.com/hexworks Patreon]
 
[https://circleci.com/gh/Hexworks/zircon [[File:https://circleci.com/gh/Hexworks/zircon/tree/master.svg?style=shield]]] [https://mvnrepository.com/artifact/org.hexworks.zircon/zircon/2017.4.0 [[File:https://maven-badges.herokuapp.com/maven-central/org.hexworks.zircon/zircon/badge.svg]]] [https://jitpack.io/#Hexworks/Zircon [[File:https://jitpack.io/v/Hexworks/Zircon.svg]]] [https://codecov.io/github/Hexworks/zircon?branch=master [[File:https://codecov.io/github/Hexworks/zircon/coverage.svg?branch=master]]] [https://github.com/Hexworks/zircon/blob/master/LICENSE [[File:https://img.shields.io/badge/License-MIT-green.svg]]] [https://github.com/sindresorhus/awesome [[File:https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg|Awesome]]]
 
 
-----
 
== Table of Contents ==
 
* [https://github.com/Hexworks/zircon#getting-started Getting Started]
** [https://github.com/Hexworks/zircon#some-rules-of-thumb Some rules of thumb]
** [https://github.com/Hexworks/zircon#creating-an-application Creating an Application]
** [https://github.com/Hexworks/zircon#working-with-screens Working with Screens]
** [https://github.com/Hexworks/zircon#components Components]
** [https://github.com/Hexworks/zircon#additional-features Additional features]
*** [https://github.com/Hexworks/zircon#layering Layering]
*** [https://github.com/Hexworks/zircon#input-handling Input handling]
*** [https://github.com/Hexworks/zircon#shape-and-box-drawing Shape and box drawing]
*** [https://github.com/Hexworks/zircon#fonts-and-tilesets Fonts and tilesets]
*** [https://github.com/Hexworks/zircon#rexpaint-file-loading REXPaint file loading]
*** [https://github.com/Hexworks/zircon#color-themes Color themes]
*** [https://github.com/Hexworks/zircon#animations-beta Animations (BETA)]
*** [https://github.com/Hexworks/zircon#the-api The API]
* [https://github.com/Hexworks/zircon#road-map Road map]
* [https://github.com/Hexworks/zircon#license License]
* [https://github.com/Hexworks/zircon#credits Credits]
 
== Getting Started ==
 
If you want to work with Zircon you can add it to your project as a dependency.
 
from Maven:
 
<source lang="xml"><dependency>
    <groupId>com.github.hexworks.zircon</groupId>
    <artifactId>zircon.jvm.swing</artifactId>
    <version>2018.3.27-PREVIEW</version>
</dependency></source>
or you can also use Gradle:
 
<source lang="groovy">compile("com.github.hexworks.zircon:zircon.jvm.swing:2018.3.27-PREVIEW")</source>
Note that you need to use [https://jitpack.io/#Hexworks/Zircon Jitpack] for the above dependencies to work.
 
Want to use a <code>PREVIEW</code>? Check [https://github.com/Hexworks/zircon/wiki/Release-process-and-versioning-scheme#snapshot-releases this Wiki page]
 
=== Some rules of thumb ===
 
Before we start there are some guidelines which can help you if you are stuck:
 
* If you want to build something (a <code>TileGraphics</code>, a <code>Component</code> or anything which is part of the public API) it is almost sure that there is a <code>Builder</code> or a <code>Factory</code> for it. The convention is that if you want to create an <code>TileGraphics</code> for example, then you can use the <code>DrawSurfaces</code> class to do so. (so it is the plural form of the thing which you want to build). Your IDE will help you with this. These classes reside in the <code>org.hexworks.zircon.api</code> package.
* If you want to work with external files like tilesets or REXPaint files check the same package (<code>org.hexworks.zircon.api</code>), and look for classes which end with <code>*Resources</code>. There are a bunch of built-in tilesets for example which you can choose from but you can also load your own. The rule of thumb is that if you need something external there is probably a <code>*Resources</code> class for it (like the [https://github.com/Hexworks/zircon/blob/master/zircon.jvm/src/main/kotlin/org/hexworks/zircon/api/CP437TilesetResources.kt CP437TilesetResources]).
* You can use ''anything'' you can find in the [https://github.com/Hexworks/zircon/tree/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api API] package, they are part of the public API, and safe to use. The [https://github.com/Hexworks/zircon/tree/master/zircon.core/src/main/kotlin/org/hexworks/zircon/internal internal] package however is considered private to Zircon so don’t depend on anything in it.
* Some topics are explained in depth on the [https://github.com/Hexworks/zircon/wiki Wiki]
* If you want to see some example code look [https://github.com/Hexworks/zircon/tree/master/zircon.examples/src/main here].<br />
 
* If all else fails read the javadoc. API classes are well documented.
* If you have any problems which are not answered here feel free to ask us at the [https://discord.gg/hbzytQJ Hexworks Discord server].
 
=== Creating an Application ===
 
In Zircon almost every object you might want to use has a helper class for building it. This is the same for [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/application/Application.kt Application]s as well so let’s create one using the [https://github.com/Hexworks/zircon/blob/master/zircon.jvm.swing/src/main/kotlin/org/hexworks/zircon/api/SwingApplications.kt SwingApplications] class:
 
<blockquote>Note that these examples reside in the <code>org.hexworks.zircon.examples.docs</code> package in the <code>zircon.examples</code> project, you can try them all out.
</blockquote>
<source lang="java">import org.hexworks.zircon.api.SwingApplications;
import org.hexworks.zircon.api.application.Application;
 
public class CreatingAnApplication {
 
    public static void main(String[] args) {
 
        Application application = SwingApplications.startApplication();
     }
     }
}</pre>
}</source>
    </div>
Running this snippet will result in this screen:
    <p>Running this snippet will result in this screen:</p>
 
    <p><a target="_blank" rel="noopener noreferrer"
[[File:https://cdn.discordapp.com/attachments/363771631727804416/477466202982055939/CreatingAnApplication.png]]
          href="https://camo.githubusercontent.com/843014f75d95fdcbbdc0efa954bfaec73a82e329/68747470733a2f2f63646e2e646973636f72646170702e636f6d2f6174746163686d656e74732f3336333737313633313732373830343431362f3437373436363230323938323035353933392f4372656174696e67416e4170706c69636174696f6e2e706e67"><img
 
            src="https://camo.githubusercontent.com/843014f75d95fdcbbdc0efa954bfaec73a82e329/68747470733a2f2f63646e2e646973636f72646170702e636f6d2f6174746163686d656e74732f3336333737313633313732373830343431362f3437373436363230323938323035353933392f4372656174696e67416e4170706c69636174696f6e2e706e67"
Not very useful, is it? So what happens here? An [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/application/Application.kt Application] is just an object which has a [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/internal/renderer/Renderer.kt Renderer] for rendering [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/data/Tile.kt Tile]s on your screen), and a [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/grid/TileGrid.kt TileGrid], which is the main interface which you will use to interact with Zircon. An [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/application/Application.kt Application] is responsible for ''continuously rendering'' the contents of the grid on the screen. Here we use the ''Swing'' variant, but there are other types in the making (one for LibGDX, and one which works in the browser).
            alt=""
 
            data-canonical-src="https://cdn.discordapp.com/attachments/363771631727804416/477466202982055939/CreatingAnApplication.png"
Since most of the time you don’t care about the [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/application/Application.kt Application] itself, there is a function for creating a [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/grid/TileGrid.kt TileGrid] directly:
            style="max-width:100%;"></a></p>
 
    <p>Not very useful, is it? So what happens here? An <a
<source lang="java">import org.hexworks.zircon.api.SwingApplications;
            href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/application/Application.kt">Application</a>
import org.hexworks.zircon.api.grid.TileGrid;
        is just an object which has a <a
                href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/internal/renderer/Renderer.kt">Renderer</a>
        for rendering <a
                href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/data/Tile.kt">Tile</a>s
        on
        your screen), and a <a
                href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/grid/TileGrid.kt">TileGrid</a>,
        which is the main interface which you will use to interact with Zircon.
        An
        <a href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/application/Application.kt">Application</a>
        is responsible for <em>continuously rendering</em> the contents of the grid on the
        screen. Here we use the <em>Swing</em> variant,
        but there are other types in the making (one for LibGDX, and one which works in the
        browser).</p>
    <p>Since most of the time you don't care about the <a
            href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/application/Application.kt">Application</a>
        itself, there is a function for creating a <a
                href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/grid/TileGrid.kt">TileGrid</a>
        directly:</p>
    <div class="highlight highlight-source-java"><pre><span class="pl-k">import</span> <span
            class="pl-smi">org.hexworks.zircon.api.SwingApplications</span>;
<span class="pl-k">import</span> <span class="pl-smi">org.hexworks.zircon.api.grid.TileGrid</span>;


<span class="pl-k">public</span> <span class="pl-k">class</span> <span class="pl-en">CreatingATileGrid</span> {
public class CreatingATileGrid {


     <span class="pl-k">public</span> <span class="pl-k">static</span> <span class="pl-k">void</span> <span
     public static void main(String[] args) {
                class="pl-en">main</span>(<span class="pl-k">String</span>[] <span
                class="pl-v">args</span>) {


         <span class="pl-smi">TileGrid</span> tileGrid <span class="pl-k">=</span> <span
         TileGrid tileGrid = SwingApplications.startTileGrid();
                class="pl-smi">SwingApplications</span><span class="pl-k">.</span>startTileGrid();
     }
     }
}</pre>
}</source>
    </div>
Now let’s see how we can specify how a [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/grid/TileGrid.kt TileGrid] is created. We’ll use the [https://github.com/Hexworks/zircon/blob/master/zircon.jvm/src/main/kotlin/org/hexworks/zircon/api/AppConfigs.kt AppConfigs] helper for this:
    <p>Now let's see how we can specify how a <a
            href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/grid/TileGrid.kt">TileGrid</a>
        is created. We'll use the <a
                href="https://github.com/Hexworks/zircon/blob/master/zircon.jvm/src/main/kotlin/org/hexworks/zircon/api/AppConfigs.kt">AppConfigs</a>
        helper for this:</p>
    <div class="highlight highlight-source-java"><pre><span class="pl-k">import</span> <span
            class="pl-smi">org.hexworks.zircon.api.AppConfigs</span>;
<span class="pl-k">import</span> <span class="pl-smi">org.hexworks.zircon.api.CP437TilesetResources</span>;
<span class="pl-k">import</span> <span class="pl-smi">org.hexworks.zircon.api.Sizes</span>;
<span class="pl-k">import</span> <span class="pl-smi">org.hexworks.zircon.api.SwingApplications</span>;
<span class="pl-k">import</span> <span class="pl-smi">org.hexworks.zircon.api.grid.TileGrid</span>;


<span class="pl-k">public</span> <span class="pl-k">class</span> <span class="pl-en">CreatingATileGrid</span> {
<source lang="java">import org.hexworks.zircon.api.AppConfigs;
import org.hexworks.zircon.api.CP437TilesetResources;
import org.hexworks.zircon.api.Sizes;
import org.hexworks.zircon.api.SwingApplications;
import org.hexworks.zircon.api.grid.TileGrid;


    <span class="pl-k">public</span> <span class="pl-k">static</span> <span class="pl-k">void</span> <span
public class CreatingATileGrid {
                class="pl-en">main</span>(<span class="pl-k">String</span>[] <span
                class="pl-v">args</span>) {


         <span class="pl-smi">TileGrid</span> tileGrid <span class="pl-k">=</span> <span
    public static void main(String[] args) {
                class="pl-smi">SwingApplications</span><span class="pl-k">.</span>startTileGrid(
 
                 <span class="pl-smi">AppConfigs</span><span class="pl-k">.</span>newConfig()
         TileGrid tileGrid = SwingApplications.startTileGrid(
                         .defaultSize(<span class="pl-smi">Sizes</span><span class="pl-k">.</span>create(<span
                 AppConfigs.newConfig()
                class="pl-c1">10</span>, <span class="pl-c1">10</span>))
                         .defaultSize(Sizes.create(10, 10))
                         .defaultTileset(<span class="pl-smi">CP437TilesetResources</span><span class="pl-k">.</span>rexPaint16x16())
                         .defaultTileset(CP437TilesetResources.rexPaint16x16())
                         .build());
                         .build());
     }
     }
}</pre>
}</source>
    </div>
Adding and formatting [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/data/Tile.kt Tile]s is very simple:
    <p>Adding and formatting <a
 
            href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/data/Tile.kt">Tile</a>s
<source lang="java">import org.hexworks.zircon.api.AppConfigs;
        is very simple:</p>
import org.hexworks.zircon.api.CP437TilesetResources;
    <div class="highlight highlight-source-java"><pre><span class="pl-k">import</span> <span
import org.hexworks.zircon.api.Positions;
            class="pl-smi">org.hexworks.zircon.api.AppConfigs</span>;
import org.hexworks.zircon.api.Sizes;
<span class="pl-k">import</span> <span class="pl-smi">org.hexworks.zircon.api.CP437TilesetResources</span>;
import org.hexworks.zircon.api.SwingApplications;
<span class="pl-k">import</span> <span class="pl-smi">org.hexworks.zircon.api.Positions</span>;
import org.hexworks.zircon.api.Tiles;
<span class="pl-k">import</span> <span class="pl-smi">org.hexworks.zircon.api.Sizes</span>;
import org.hexworks.zircon.api.color.ANSITileColor;
<span class="pl-k">import</span> <span class="pl-smi">org.hexworks.zircon.api.SwingApplications</span>;
import org.hexworks.zircon.api.grid.TileGrid;
<span class="pl-k">import</span> <span class="pl-smi">org.hexworks.zircon.api.Tiles</span>;
<span class="pl-k">import</span> <span class="pl-smi">org.hexworks.zircon.api.color.ANSITileColor</span>;
<span class="pl-k">import</span> <span class="pl-smi">org.hexworks.zircon.api.grid.TileGrid</span>;


<span class="pl-k">public</span> <span class="pl-k">class</span> <span class="pl-en">CreatingATileGrid</span> {
public class CreatingATileGrid {


     <span class="pl-k">public</span> <span class="pl-k">static</span> <span class="pl-k">void</span> <span
     public static void main(String[] args) {
                class="pl-en">main</span>(<span class="pl-k">String</span>[] <span
                class="pl-v">args</span>) {


         <span class="pl-smi">TileGrid</span> tileGrid <span class="pl-k">=</span> <span
         TileGrid tileGrid = SwingApplications.startTileGrid(
                class="pl-smi">SwingApplications</span><span class="pl-k">.</span>startTileGrid(
                 AppConfigs.newConfig()
                 <span class="pl-smi">AppConfigs</span><span class="pl-k">.</span>newConfig()
                         .defaultSize(Sizes.create(10, 10))
                         .defaultSize(<span class="pl-smi">Sizes</span><span class="pl-k">.</span>create(<span
                         .defaultTileset(CP437TilesetResources.rexPaint16x16())
                class="pl-c1">10</span>, <span class="pl-c1">10</span>))
                         .defaultTileset(<span class="pl-smi">CP437TilesetResources</span><span class="pl-k">.</span>rexPaint16x16())
                         .build());
                         .build());


         tileGrid<span class="pl-k">.</span>setTileAt(
         tileGrid.setTileAt(
                 <span class="pl-smi">Positions</span><span class="pl-k">.</span>create(<span
                 Positions.create(2, 3),
                class="pl-c1">2</span>, <span class="pl-c1">3</span>),
                 Tiles.newBuilder()
                 <span class="pl-smi">Tiles</span><span class="pl-k">.</span>newBuilder()
                         .backgroundColor(ANSITileColor.CYAN)
                         .backgroundColor(<span class="pl-smi">ANSITileColor</span><span class="pl-c1"><span
                         .foregroundColor(ANSITileColor.WHITE)
                class="pl-k">.</span>CYAN</span>)
                         .character('x')
                         .foregroundColor(<span class="pl-smi">ANSITileColor</span><span class="pl-c1"><span
                class="pl-k">.</span>WHITE</span>)
                         .character(<span class="pl-s"><span class="pl-pds">'</span>x<span class="pl-pds">'</span></span>)
                         .build());
                         .build());


         tileGrid<span class="pl-k">.</span>setTileAt(
         tileGrid.setTileAt(
                 <span class="pl-smi">Positions</span><span class="pl-k">.</span>create(<span
                 Positions.create(3, 4),
                class="pl-c1">3</span>, <span class="pl-c1">4</span>),
                 Tiles.newBuilder()
                 <span class="pl-smi">Tiles</span><span class="pl-k">.</span>newBuilder()
                         .backgroundColor(ANSITileColor.RED)
                         .backgroundColor(<span class="pl-smi">ANSITileColor</span><span class="pl-c1"><span
                         .foregroundColor(ANSITileColor.GREEN)
                class="pl-k">.</span>RED</span>)
                         .character('y')
                         .foregroundColor(<span class="pl-smi">ANSITileColor</span><span class="pl-c1"><span
                class="pl-k">.</span>GREEN</span>)
                         .character(<span class="pl-s"><span class="pl-pds">'</span>y<span class="pl-pds">'</span></span>)
                         .build());
                         .build());


         tileGrid<span class="pl-k">.</span>setTileAt(
         tileGrid.setTileAt(
                 <span class="pl-smi">Positions</span><span class="pl-k">.</span>create(<span
                 Positions.create(4, 5),
                class="pl-c1">4</span>, <span class="pl-c1">5</span>),
                 Tiles.newBuilder()
                 <span class="pl-smi">Tiles</span><span class="pl-k">.</span>newBuilder()
                         .backgroundColor(ANSITileColor.BLUE)
                         .backgroundColor(<span class="pl-smi">ANSITileColor</span><span class="pl-c1"><span
                         .foregroundColor(ANSITileColor.MAGENTA)
                class="pl-k">.</span>BLUE</span>)
                         .character('z')
                         .foregroundColor(<span class="pl-smi">ANSITileColor</span><span class="pl-c1"><span
                class="pl-k">.</span>MAGENTA</span>)
                         .character(<span class="pl-s"><span class="pl-pds">'</span>z<span class="pl-pds">'</span></span>)
                         .build());
                         .build());
     }
     }
}</pre>
}</source>
    </div>
Running the above code will result in something like this:
    <p>Running the above code will result in something like this:</p>
 
    <p><a target="_blank" rel="noopener noreferrer"
[[File:https://cdn.discordapp.com/attachments/363771631727804416/477469640205926401/CreatingATileGrid.png]]
          href="https://camo.githubusercontent.com/3f4051d1ddff11eab2a984643b1e25690c1ee9fb/68747470733a2f2f63646e2e646973636f72646170702e636f6d2f6174746163686d656e74732f3336333737313633313732373830343431362f3437373436393634303230353932363430312f4372656174696e674154696c65477269642e706e67"><img
 
            src="https://camo.githubusercontent.com/3f4051d1ddff11eab2a984643b1e25690c1ee9fb/68747470733a2f2f63646e2e646973636f72646170702e636f6d2f6174746163686d656e74732f3336333737313633313732373830343431362f3437373436393634303230353932363430312f4372656174696e674154696c65477269642e706e67"
As you can see there is a helper for every class which you might want to use. Here we used <code>Positions.create</code> to create a [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/data/Position.kt Position], <code>Sizes.create</code> for creating [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/data/Size.kt Size]s and the [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/builder/data/TileBuilder.kt TileBuilder] to create tiles.
            alt=""
 
            data-canonical-src="https://cdn.discordapp.com/attachments/363771631727804416/477469640205926401/CreatingATileGrid.png"
A <code>Position</code> denotes a coordinate on a <code>TileGrid</code>, so for example a <code>Position</code> of (<code>3</code>, <code>4</code>) points to the 3rd column and the 4th row (x, y) on the grid.
            style="max-width:100%;"></a></p>
 
    <p>As you can see there is a helper for every class which you might want to use. Here we
Conversely a <code>Size</code> denotes an area with a width and a height. These two classes are used throughout Zircon.
        used <code>Positions.create</code>
        to create a <a
                href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/data/Position.kt">Position</a>,
        <code>Sizes.create</code> for creating <a
                href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/data/Size.kt">Size</a>s
        and the <a
                href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/builder/data/TileBuilder.kt">TileBuilder</a>
        to create tiles.</p>
    <p>A <code>Position</code> denotes a coordinate on a <code>TileGrid</code>, so for
        example a <code>Position</code> of (<code>3</code>, <code>4</code>) points to the
        3rd column
        and the 4th row (x, y) on the grid.</p>
    <p>Conversely a <code>Size</code> denotes an area with a width and a height. These two
        classes are used throughout Zircon.</p>
    <p>A
        <a href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/data/Tile.kt">Tile</a>
        is the most basic graphical unit Zircon supports. In most cases it is a simple
        character with a foreground
        and a background color (like in the example above).</p>
    <p>In addition to colors and characters you can also use <a
            href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/modifier/Modifier.kt">Modifier</a>s
        in your <a
                href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/data/Tile.kt">Tile</a>s.
    </p>
    <blockquote>
        <p>A lot of fancy stuff can be done with <a
                href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/modifier/Modifier.kt">Modifier</a>s,
            like this:</p>
        <p><a target="_blank" rel="noopener noreferrer"
              href="https://camo.githubusercontent.com/adcb972ba57d23f7b92443f4723a61e91b04c6b5/68747470733a2f2f63646e2e646973636f72646170702e636f6d2f6174746163686d656e74732f3336333737313633313732373830343431362f3437373437303638333531333838303537362f6d6f646966696572732e676966"><img
                src="https://camo.githubusercontent.com/adcb972ba57d23f7b92443f4723a61e91b04c6b5/68747470733a2f2f63646e2e646973636f72646170702e636f6d2f6174746163686d656e74732f3336333737313633313732373830343431362f3437373437303638333531333838303537362f6d6f646966696572732e676966"
                alt=""
                data-canonical-src="https://cdn.discordapp.com/attachments/363771631727804416/477470683513880576/modifiers.gif"
                style="max-width:100%;"></a></p>
        <p>If interested check out the code examples <a
                href="https://github.com/Hexworks/zircon/tree/master/zircon.examples/src/main">here</a>.
        </p>
    </blockquote>
    <blockquote>
        <p>Tileset (and by extension resource) handling in Zircon is very simple and if you
            are interested in how to load your
            custom fonts and other resources take a look at the <a
                    href="https://github.com/Hexworks/zircon/wiki/Resource-Handling">Resource
                handling wiki page</a>.</p>
    </blockquote>
    <h3><a id="user-content-working-with-screens" class="anchor" aria-hidden="true"
          href="#working-with-screens">
        <svg class="octicon octicon-link" viewBox="0 0 16 16" version="1.1" width="16"
            height="16" aria-hidden="true">
            <path fill-rule="evenodd"
                  d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path>
        </svg>
    </a>Working with Screens
    </h3>
    <p>
        <a href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/grid/TileGrid.kt">TileGrid</a>s
        alone won't suffice if you want to get any serious work done since they are rather
        rudimentary.</p>
    <p>A
        <a href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/screen/Screen.kt">Screen</a>
        has its own buffer and it can be <code>display</code>ed on
        a
        <a href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/grid/TileGrid.kt">TileGrid</a>
        any time. This means that you can have multiple <a
                href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/screen/Screen.kt">Screen</a>s
        at the same time representing your actual
        game screens. <em>Note that</em> only <em>one</em> <a
                href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/screen/Screen.kt">Screen</a>
        can be displayed at a given moment. <code>display</code>ing one deactivates
        the previous <a
                href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/screen/Screen.kt">Screen</a>.
    </p>
    <p>Let's create a <a
            href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/screen/Screen.kt">Screen</a>
        and fill it up with some stuff:</p>
    <div class="highlight highlight-source-java"><pre><span class="pl-k">import</span> <span
            class="pl-smi">org.hexworks.zircon.api.AppConfigs</span>;
<span class="pl-k">import</span> <span class="pl-smi">org.hexworks.zircon.api.CP437TilesetResources</span>;
<span class="pl-k">import</span> <span class="pl-smi">org.hexworks.zircon.api.ColorThemes</span>;
<span class="pl-k">import</span> <span class="pl-smi">org.hexworks.zircon.api.Positions</span>;
<span class="pl-k">import</span> <span class="pl-smi">org.hexworks.zircon.api.Screens</span>;
<span class="pl-k">import</span> <span class="pl-smi">org.hexworks.zircon.api.Sizes</span>;
<span class="pl-k">import</span> <span class="pl-smi">org.hexworks.zircon.api.SwingApplications</span>;
<span class="pl-k">import</span> <span class="pl-smi">org.hexworks.zircon.api.DrawSurfaces</span>;
<span class="pl-k">import</span> <span class="pl-smi">org.hexworks.zircon.api.Tiles</span>;
<span class="pl-k">import</span> <span class="pl-smi">org.hexworks.zircon.api.component.ColorTheme</span>;
<span class="pl-k">import</span> <span class="pl-smi">org.hexworks.zircon.api.graphics.TileGraphics</span>;
<span class="pl-k">import</span> <span class="pl-smi">org.hexworks.zircon.api.grid.TileGrid</span>;
<span class="pl-k">import</span> <span class="pl-smi">org.hexworks.zircon.api.screen.Screen</span>;


<span class="pl-k">public</span> <span class="pl-k">class</span> <span class="pl-en">CreatingAScreen</span> {
A [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/data/Tile.kt Tile] is the most basic graphical unit Zircon supports. In most cases it is a simple character with a foreground and a background color (like in the example above).


    <span class="pl-k">public</span> <span class="pl-k">static</span> <span class="pl-k">void</span> <span
In addition to colors and characters you can also use [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/modifier/Modifier.kt Modifier]s in your [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/data/Tile.kt Tile]s.
                class="pl-en">main</span>(<span class="pl-k">String</span>[] <span
                class="pl-v">args</span>) {


        <span class="pl-smi">TileGrid</span> tileGrid <span class="pl-k">=</span> <span
<blockquote>A lot of fancy stuff can be done with [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/modifier/Modifier.kt Modifier]s, like this:
                class="pl-smi">SwingApplications</span><span class="pl-k">.</span>startTileGrid(
 
                <span class="pl-smi">AppConfigs</span><span class="pl-k">.</span>newBuilder()
[[File:https://cdn.discordapp.com/attachments/363771631727804416/477470683513880576/modifiers.gif]]
                         .defaultSize(<span class="pl-smi">Sizes</span><span class="pl-k">.</span>create(<span
 
                class="pl-c1">20</span>, <span class="pl-c1">8</span>))
If interested check out the code examples [https://github.com/Hexworks/zircon/tree/master/zircon.examples/src/main here].
                         .defaultTileset(<span class="pl-smi">CP437TilesetResources</span><span class="pl-k">.</span>wanderlust16x16())
</blockquote>
<blockquote>Tileset (and by extension resource) handling in Zircon is very simple and if you are interested in how to load your custom fonts and other resources take a look at the [https://github.com/Hexworks/zircon/wiki/Resource-Handling Resource handling wiki page].
</blockquote>
=== Working with Screens ===
 
[https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/grid/TileGrid.kt TileGrid]s alone won’t suffice if you want to get any serious work done since they are rather rudimentary.
 
A [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/screen/Screen.kt Screen] has its own buffer and it can be <code>display</code>ed on a [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/grid/TileGrid.kt TileGrid] any time. This means that you can have multiple [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/screen/Screen.kt Screen]s at the same time representing your actual game screens. ''Note that'' only ''one'' [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/screen/Screen.kt Screen] can be displayed at a given moment. <code>display</code>ing one deactivates the previous [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/screen/Screen.kt Screen].
 
Let’s create a [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/screen/Screen.kt Screen] and fill it up with some stuff:
 
<source lang="java">import org.hexworks.zircon.api.AppConfigs;
import org.hexworks.zircon.api.CP437TilesetResources;
import org.hexworks.zircon.api.ColorThemes;
import org.hexworks.zircon.api.Positions;
import org.hexworks.zircon.api.Screens;
import org.hexworks.zircon.api.Sizes;
import org.hexworks.zircon.api.SwingApplications;
import org.hexworks.zircon.api.DrawSurfaces;
import org.hexworks.zircon.api.Tiles;
import org.hexworks.zircon.api.component.ColorTheme;
import org.hexworks.zircon.api.graphics.TileGraphics;
import org.hexworks.zircon.api.grid.TileGrid;
import org.hexworks.zircon.api.screen.Screen;
 
public class CreatingAScreen {
 
    public static void main(String[] args) {
 
        TileGrid tileGrid = SwingApplications.startTileGrid(
                AppConfigs.newBuilder()
                         .defaultSize(Sizes.create(20, 8))
                         .defaultTileset(CP437TilesetResources.wanderlust16x16())
                         .build());
                         .build());


         <span class="pl-k">final</span> <span class="pl-smi">Screen</span> screen <span class="pl-k">=</span> <span
         final Screen screen = Screens.createScreenFor(tileGrid);
                class="pl-smi">Screens</span><span class="pl-k">.</span>createScreenFor(tileGrid);


         <span class="pl-k">final</span> <span class="pl-smi">ColorTheme</span> theme <span class="pl-k">=</span> <span
         final ColorTheme theme = ColorThemes.adriftInDreams();
                class="pl-smi">ColorThemes</span><span class="pl-k">.</span>adriftInDreams();


         <span class="pl-k">final</span> <span class="pl-smi">TileGraphics</span> image <span class="pl-k">=</span> <span
         final TileGraphics image = DrawSurfaces.tileGraphicsBuilder()
                class="pl-smi">DrawSurfaces</span><span class="pl-k">.</span>tileGraphicsBuilder()
                 .size(tileGrid.size)
                 .size(tileGrid<span class="pl-k">.</span>size)
                 .build()
                 .build()
                 .fill(<span class="pl-smi">Tiles</span><span class="pl-k">.</span>newBuilder()
                 .fill(Tiles.newBuilder()
                         .foregroundColor(theme<span class="pl-k">.</span>getBrightForegroundColor())
                         .foregroundColor(theme.getBrightForegroundColor())
                         .backgroundColor(theme<span class="pl-k">.</span>getBrightBackgroundColor())
                         .backgroundColor(theme.getBrightBackgroundColor())
                         .character(<span class="pl-s"><span class="pl-pds">'</span>~<span class="pl-pds">'</span></span>)
                         .character('~')
                         .build());
                         .build());


         screen<span class="pl-k">.</span>draw(image, <span class="pl-smi">Positions</span><span class="pl-k">.</span>defaultPosition());
         screen.draw(image, Positions.defaultPosition());


         screen<span class="pl-k">.</span>display();
         screen.display();
     }
     }
}</pre>
}</source>
    </div>
and we’ve got a nice ocean:
    <p>and we've got a nice ocean:</p>
    <p><a target="_blank" rel="noopener noreferrer"
          href="https://camo.githubusercontent.com/0f51884051ef222d272da2899a75ac7a8ec9b6bc/68747470733a2f2f63646e2e646973636f72646170702e636f6d2f6174746163686d656e74732f3336333737313633313732373830343431362f3437373437353638303539343935323232332f4372656174696e674153637265656e2e706e67"><img
            src="https://camo.githubusercontent.com/0f51884051ef222d272da2899a75ac7a8ec9b6bc/68747470733a2f2f63646e2e646973636f72646170702e636f6d2f6174746163686d656e74732f3336333737313633313732373830343431362f3437373437353638303539343935323232332f4372656174696e674153637265656e2e706e67"
            alt=""
            data-canonical-src="https://cdn.discordapp.com/attachments/363771631727804416/477475680594952223/CreatingAScreen.png"
            style="max-width:100%;"></a></p>
    <p>What happens here is that we:</p>
    <ul>
        <li>Create a <a
                href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/screen/Screen.kt">Screen</a>
        </li>
        <li>Fetch a nice <a
                href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/component/ColorTheme.kt">ColorTheme</a>
            which has colors we need
        </li>
        <li>Create a <a
                href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/graphics/TileGraphics.kt">TileGraphics</a>
            with the colors added and fill it with <code>~</code>s
        </li>
        <li>Draw the graphic onto the <a
                href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/screen/Screen.kt">Screen</a>
        </li>
    </ul>
    <p>For more explanation about these jump to the <a
            href="https://github.com/Hexworks/zircon#how-zircon-works">How Zircon works</a>
        section.</p>
    <blockquote>
        <p>You can do so much more with <a
                href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/screen/Screen.kt">Screen</a>s.
            If interested then check out <a
                    href="https://github.com/Hexworks/zircon/wiki/A-primer-on-Screens">A
                primer on Screens</a> on the Wiki!</p>
    </blockquote>
    <h3><a id="user-content-components" class="anchor" aria-hidden="true"
          href="#components">
        <svg class="octicon octicon-link" viewBox="0 0 16 16" version="1.1" width="16"
            height="16" aria-hidden="true">
            <path fill-rule="evenodd"
                  d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path>
        </svg>
    </a>Components
    </h3>
    <p>Zircon supports a bunch of <a
            href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/component/Component.kt">Component</a>s
        out of the box:</p>
    <ul>
        <li><code>Button</code>: A simple clickable component with corresponding event
            listeners
        </li>
        <li><code>CheckBox</code>: Like a BUTTON but with checked / unchecked state</li>
        <li><code>Label</code>: Simple component with text</li>
        <li><code>Header</code>: Like a label but this one has emphasis (useful when using
            <a href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/component/ColorTheme.kt">ColorTheme</a>s)
        </li>
        <li><code>Panel</code>: A <a
                href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/component/Container.kt">Container</a>
            which can hold multiple <a
                    href="https://github.com/Hexworks/zircon/wiki/The-component-system">Components</a>
        </li>
        <li><code>RadioButtonGroup</code> and <code>RadioButton</code>: Like a <code>CheckBox</code>
            but only one can be selected at a time
        </li>
        <li><code>TextBox</code>: Similar to a text area in HTML this <a
                href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/component/Component.kt">Component</a>
            can be written into
        </li>
    </ul>
    <p>These components are rather simple and you can expect them to work in a way you might
        be familiar with:</p>
    <ul>
        <li>You can click on them (press and release are different events)</li>
        <li>You can attach event listeners on them</li>
        <li>Zircon implements focus handling so you can navigate between the components
            using the <code>[Tab]</code> key (forwards) or the <code>[Shift]+[Tab]</code>
            key stroke (backwards).
        </li>
        <li>Components can be hovered and they can change their styling when you do so</li>
    </ul>
    <p>Let's look at an example (notes about how it works are in the comments):</p>
    <div class="highlight highlight-source-java"><pre><span class="pl-k">import</span> <span
            class="pl-smi">org.hexworks.zircon.api.*</span>;
<span class="pl-k">import</span> <span class="pl-smi">org.hexworks.zircon.api.component.Button</span>;
<span class="pl-k">import</span> <span class="pl-smi">org.hexworks.zircon.api.component.CheckBox</span>;
<span class="pl-k">import</span> <span class="pl-smi">org.hexworks.zircon.api.component.Header</span>;
<span class="pl-k">import</span> <span class="pl-smi">org.hexworks.zircon.api.component.Panel</span>;
<span class="pl-k">import</span> <span class="pl-smi">org.hexworks.zircon.api.grid.TileGrid</span>;
<span class="pl-k">import</span> <span class="pl-smi">org.hexworks.zircon.api.screen.Screen</span>;


<span class="pl-k">public</span> <span class="pl-k">class</span> <span class="pl-en">UsingComponents</span> {
[[File:https://cdn.discordapp.com/attachments/363771631727804416/477475680594952223/CreatingAScreen.png]]


    <span class="pl-k">public</span> <span class="pl-k">static</span> <span class="pl-k">void</span> <span
What happens here is that we:
                class="pl-en">main</span>(<span class="pl-k">String</span>[] <span
                class="pl-v">args</span>) {


        <span class="pl-k">final</span> <span class="pl-smi">TileGrid</span> tileGrid <span class="pl-k">=</span> <span
* Create a [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/screen/Screen.kt Screen]
                class="pl-smi">SwingApplications</span><span class="pl-k">.</span>startTileGrid(
* Fetch a nice [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/component/ColorTheme.kt ColorTheme] which has colors we need
                <span class="pl-smi">AppConfigs</span><span class="pl-k">.</span>newConfig()
* Create a [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/graphics/TileGraphics.kt TileGraphics] with the colors added and fill it with <code>~</code>s
                        .defaultSize(<span class="pl-smi">Sizes</span><span class="pl-k">.</span>create(<span
* Draw the graphic onto the [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/screen/Screen.kt Screen]
                class="pl-c1">34</span>, <span class="pl-c1">18</span>))
 
                        .defaultTileset(<span class="pl-smi">CP437TilesetResources</span><span class="pl-k">.</span>wanderlust16x16())
For more explanation about these jump to the [https://github.com/Hexworks/zircon#how-zircon-works How Zircon works] section.
 
<blockquote>You can do so much more with [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/screen/Screen.kt Screen]s. If interested then check out [https://github.com/Hexworks/zircon/wiki/A-primer-on-Screens A primer on Screens] on the Wiki!
</blockquote>
=== Components ===
 
Zircon supports a bunch of [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/component/Component.kt Component]s out of the box:
 
* <code>Button</code>: A simple clickable component with corresponding event listeners
* <code>CheckBox</code>: Like a BUTTON but with checked / unchecked state
* <code>Label</code>: Simple component with text
* <code>Header</code>: Like a label but this one has emphasis (useful when using [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/component/ColorTheme.kt ColorTheme]s)
* <code>Panel</code>: A [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/component/Container.kt Container] which can hold multiple [https://github.com/Hexworks/zircon/wiki/The-component-system Components]
* <code>RadioButtonGroup</code> and <code>RadioButton</code>: Like a <code>CheckBox</code> but only one can be selected at a time
* <code>TextBox</code>: Similar to a text area in HTML this [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/component/Component.kt Component] can be written into
 
These components are rather simple and you can expect them to work in a way you might be familiar with:
 
* You can click on them (press and release are different events)
* You can attach event listeners on them
* Zircon implements focus handling so you can navigate between the components using the <code>[Tab]</code> key (forwards) or the <code>[Shift]+[Tab]</code> key stroke (backwards).
* Components can be hovered and they can change their styling when you do so
 
Let’s look at an example (notes about how it works are in the comments):
 
<source lang="java">import org.hexworks.zircon.api.*;
import org.hexworks.zircon.api.component.Button;
import org.hexworks.zircon.api.component.CheckBox;
import org.hexworks.zircon.api.component.Header;
import org.hexworks.zircon.api.component.Panel;
import org.hexworks.zircon.api.grid.TileGrid;
import org.hexworks.zircon.api.screen.Screen;
 
public class UsingComponents {
 
    public static void main(String[] args) {
 
        final TileGrid tileGrid = SwingApplications.startTileGrid(
                AppConfigs.newConfig()
                        .defaultSize(Sizes.create(34, 18))
                        .defaultTileset(CP437TilesetResources.wanderlust16x16())
                         .build());
                         .build());
         <span class="pl-k">final</span> <span class="pl-smi">Screen</span> screen <span class="pl-k">=</span> <span
         final Screen screen = Screens.createScreenFor(tileGrid);
                class="pl-smi">Screens</span><span class="pl-k">.</span>createScreenFor(tileGrid);


         <span class="pl-smi">Panel</span> panel <span class="pl-k">=</span> <span class="pl-smi">Components</span><span
         Panel panel = Components.panel()
                class="pl-k">.</span>panel()
                 .wrapWithBox() // panels can be wrapped in a box
                 .wrapWithBox() <span class="pl-c"><span class="pl-c">//</span> panels can be wrapped in a box</span>
                 .title("Panel") // if a panel is wrapped in a box a title can be displayed
                 .title(<span class="pl-s"><span class="pl-pds">"</span>Panel<span class="pl-pds">"</span></span>) <span
                 .wrapWithShadow() // shadow can be added
                class="pl-c"><span class="pl-c">//</span> if a panel is wrapped in a box a title can be displayed</span>
                 .size(Sizes.create(32, 16)) // the size must be smaller than the parent's size
                 .wrapWithShadow() <span class="pl-c"><span class="pl-c">//</span> shadow can be added</span>
                 .position(Positions.offset1x1())
                 .size(<span class="pl-smi">Sizes</span><span class="pl-k">.</span>create(<span class="pl-c1">32</span>, <span
                 .build(); // position is always relative to the parent
                class="pl-c1">16</span>)) <span class="pl-c"><span class="pl-c">//</span> the size must be smaller than the parent's size</span>
                 .position(<span class="pl-smi">Positions</span><span class="pl-k">.</span>offset1x1())
                 .build(); <span class="pl-c"><span
                class="pl-c">//</span> position is always relative to the parent</span>


         <span class="pl-k">final</span> <span class="pl-smi">Header</span> header <span class="pl-k">=</span> <span
         final Header header = Components.header()
                class="pl-smi">Components</span><span class="pl-k">.</span>header()
                 // this will be 1x1 left and down from the top left
                 <span class="pl-c"><span class="pl-c">//</span> this will be 1x1 left and down from the top left</span>
                 // corner of the panel
                 <span class="pl-c"><span class="pl-c">//</span> corner of the panel</span>
                 .position(Positions.offset1x1())
                 .position(<span class="pl-smi">Positions</span><span class="pl-k">.</span>offset1x1())
                 .text("Header")
                 .text(<span class="pl-s"><span class="pl-pds">"</span>Header<span class="pl-pds">"</span></span>)
                 .build();
                 .build();


         <span class="pl-k">final</span> <span class="pl-smi">CheckBox</span> checkBox <span class="pl-k">=</span> <span
         final CheckBox checkBox = Components.checkBox()
                class="pl-smi">Components</span><span class="pl-k">.</span>checkBox()
                 .text("Check me!")
                 .text(<span class="pl-s"><span class="pl-pds">"</span>Check me!<span class="pl-pds">"</span></span>)
                 .position(Positions.create(0, 1)
                 .position(<span class="pl-smi">Positions</span><span class="pl-k">.</span>create(<span
                         // the position class has some convenience methods
                class="pl-c1">0</span>, <span class="pl-c1">1</span>)
                         // for you to specify your component's position as
                         <span class="pl-c"><span class="pl-c">//</span> the position class has some convenience methods</span>
                         // relative to another one
                         <span class="pl-c"><span class="pl-c">//</span> for you to specify your component's position as</span>
                         <span class="pl-c"><span class="pl-c">//</span> relative to another one</span>
                         .relativeToBottomOf(header))
                         .relativeToBottomOf(header))
                 .build();
                 .build();


         <span class="pl-k">final</span> <span class="pl-smi">Button</span> left <span class="pl-k">=</span> <span
         final Button left = Components.button()
                class="pl-smi">Components</span><span class="pl-k">.</span>button()
                 .position(Positions.create(0, 1) // this means 1 row below the check box
                 .position(<span class="pl-smi">Positions</span><span class="pl-k">.</span>create(<span
                class="pl-c1">0</span>, <span class="pl-c1">1</span>) <span
                class="pl-c"><span class="pl-c">//</span> this means 1 row below the check box</span>
                         .relativeToBottomOf(checkBox))
                         .relativeToBottomOf(checkBox))
                 .text(<span class="pl-s"><span class="pl-pds">"</span>Left<span class="pl-pds">"</span></span>)
                 .text("Left")
                 .build();
                 .build();


         <span class="pl-k">final</span> <span class="pl-smi">Button</span> right <span class="pl-k">=</span> <span
         final Button right = Components.button()
                class="pl-smi">Components</span><span class="pl-k">.</span>button()
                 .position(Positions.create(1, 0) // 1 column right relative to the left BUTTON
                 .position(<span class="pl-smi">Positions</span><span class="pl-k">.</span>create(<span
                class="pl-c1">1</span>, <span class="pl-c1">0</span>) <span
                class="pl-c"><span class="pl-c">//</span> 1 column right relative to the left BUTTON</span>
                         .relativeToRightOf(left))
                         .relativeToRightOf(left))
                 .text(<span class="pl-s"><span class="pl-pds">"</span>Right<span class="pl-pds">"</span></span>)
                 .text("Right")
                 .build();
                 .build();


         panel<span class="pl-k">.</span>addComponent(header);
         panel.addComponent(header);
         panel<span class="pl-k">.</span>addComponent(checkBox);
         panel.addComponent(checkBox);
         panel<span class="pl-k">.</span>addComponent(left);
         panel.addComponent(left);
         panel<span class="pl-k">.</span>addComponent(right);
         panel.addComponent(right);


         screen<span class="pl-k">.</span>addComponent(panel);
         screen.addComponent(panel);


         <span class="pl-c"><span class="pl-c">//</span> we can apply color themes to a screen</span>
         // we can apply color themes to a screen
         screen<span class="pl-k">.</span>applyColorTheme(<span class="pl-smi">ColorThemes</span><span
         screen.applyColorTheme(ColorThemes.techLight());
                class="pl-k">.</span>techLight());


         <span class="pl-c"><span class="pl-c">//</span> this is how you can define interactions with a component</span>
         // this is how you can define interactions with a component
         left<span class="pl-k">.</span>onMouseReleased((mouseAction <span class="pl-k">-</span><span
         left.onMouseReleased((mouseAction -> {
                class="pl-k">&gt;</span> {
             screen.applyColorTheme(ColorThemes.adriftInDreams());
             screen<span class="pl-k">.</span>applyColorTheme(<span class="pl-smi">ColorThemes</span><span
                class="pl-k">.</span>adriftInDreams());
         }));
         }));


         right<span class="pl-k">.</span>onMouseReleased((mouseAction <span class="pl-k">-</span><span
         right.onMouseReleased((mouseAction -> {
                class="pl-k">&gt;</span> {
             screen.applyColorTheme(ColorThemes.solarizedDarkOrange());
             screen<span class="pl-k">.</span>applyColorTheme(<span class="pl-smi">ColorThemes</span><span
                class="pl-k">.</span>solarizedDarkOrange());
         }));
         }));


         <span class="pl-c"><span
         // in order to see the changes you need to display your screen.
                class="pl-c">//</span> in order to see the changes you need to display your screen.</span>
         screen.display();
         screen<span class="pl-k">.</span>display();
     }
     }
}</pre>
}</source>
    </div>
And the result will look like this:
    <p>And the result will look like this:</p>
 
    <p><a target="_blank" rel="noopener noreferrer"
[[File:https://cdn.discordapp.com/attachments/363771631727804416/363813193488924673/image.png]]
          href="https://camo.githubusercontent.com/7d3ed12516747e659f4cf893cf14221943fa5a65/68747470733a2f2f63646e2e646973636f72646170702e636f6d2f6174746163686d656e74732f3336333737313633313732373830343431362f3336333831333139333438383932343637332f696d6167652e706e67"><img
 
            src="https://camo.githubusercontent.com/7d3ed12516747e659f4cf893cf14221943fa5a65/68747470733a2f2f63646e2e646973636f72646170702e636f6d2f6174746163686d656e74732f3336333737313633313732373830343431362f3336333831333139333438383932343637332f696d6167652e706e67"
You can check out more examples [https://github.com/Hexworks/zircon/tree/master/zircon.examples/src/main here]. Here are some screenshots of them:
            alt=""
 
            data-canonical-src="https://cdn.discordapp.com/attachments/363771631727804416/363813193488924673/image.png"
==== Tileset example: ====
            style="max-width:100%;"></a></p>
 
    <p>You can check out more examples <a
[[File:https://cdn.discordapp.com/attachments/277739394641690625/348400285879894018/image.png]]
            href="https://github.com/Hexworks/zircon/tree/master/zircon.examples/src/main">here</a>.
 
        Here are some
==== Animations: ====
        screenshots of them:</p>
 
    <h4><a id="user-content-tileset-example" class="anchor" aria-hidden="true"
[[File:https://cdn.discordapp.com/attachments/277739394641690625/360086607380086807/GIF.gif]]
          href="#tileset-example">
 
        <svg class="octicon octicon-link" viewBox="0 0 16 16" version="1.1" width="16"
==== Components: ====
            height="16" aria-hidden="true">
 
            <path fill-rule="evenodd"
[[File:https://cdn.discordapp.com/attachments/335444788167966720/361297190863241218/GIF.gif]]
                  d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path>
 
        </svg>
== Additional features ==
    </a>Tileset example:
 
    </h4>
There are a bunch of other things Zircon can do which are not detailed in this README but you can read about them in either the source code or the [https://github.com/Hexworks/zircon/wiki Wiki]:
    <p><a target="_blank" rel="noopener noreferrer"
 
          href="https://camo.githubusercontent.com/4a8a9c0626d3930d74a8b26a7cd7468eba6c60a3/68747470733a2f2f63646e2e646973636f72646170702e636f6d2f6174746163686d656e74732f3237373733393339343634313639303632352f3334383430303238353837393839343031382f696d6167652e706e67"><img
=== Layering ===
            src="https://camo.githubusercontent.com/4a8a9c0626d3930d74a8b26a7cd7468eba6c60a3/68747470733a2f2f63646e2e646973636f72646170702e636f6d2f6174746163686d656e74732f3237373733393339343634313639303632352f3334383430303238353837393839343031382f696d6167652e706e67"
 
            alt=""
Both the [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/grid/TileGrid.kt TileGrid] and the [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/screen/Screen.kt Screen] interfaces implement [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/behavior/Layerable.kt Layerable] which means that you can add [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/graphics/Layer.kt Layer]s on top of them. Every [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/behavior/Layerable.kt Layerable] can have an arbitrary amount of [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/graphics/Layer.kt Layer]s. [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/graphics/Layer.kt Layer]s are like [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/graphics/TileGraphics.kt TileGraphics]s and you can also have transparency in them which can be used to create fancy effects. For more details check the [https://github.com/Hexworks/zircon/blob/master/zircon.jvm/src/main/kotlin/org/hexworks/zircon/api/Layers.kt layers] Wiki page.
            data-canonical-src="https://cdn.discordapp.com/attachments/277739394641690625/348400285879894018/image.png"
 
            style="max-width:100%;"></a></p>
<blockquote>Note that when creating <code>Layer</code>s you can set their <code>offset</code> from the builder but after attaching it to a <code>TileGrid</code> or <code>Screen</code> you can change its position by calling <code>moveTo</code> with a new <code>Position</code>.
    <h4><a id="user-content-animations" class="anchor" aria-hidden="true"
</blockquote>
          href="#animations">
=== Input handling ===
        <svg class="octicon octicon-link" viewBox="0 0 16 16" version="1.1" width="16"
 
            height="16" aria-hidden="true">
Both the [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/grid/TileGrid.kt TileGrid] and the [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/screen/Screen.kt Screen] interfaces implement [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/behavior/InputEmitter.kt InputEmitter] which means that they re-emit all inputs from your users (key strokes and mouse actions) and you can listen on them. There is a [https://github.com/Hexworks/zircon/wiki/Input-handling Wiki page] with more info.
            <path fill-rule="evenodd"
 
                  d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path>
=== Shape and box drawing ===
        </svg>
 
    </a>Animations:
You can draw [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/shape/Shape.kt Shape]s like rectangles and triangles by using one of the [https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/shape/ShapeFactory.kt ShapeFactory] implementations. Check the corresponding [https://github.com/Hexworks/zircon/wiki/Shapes Wiki page] for more info.
    </h4>
 
    <p><a target="_blank" rel="noopener noreferrer"
=== Fonts and tilesets ===
          href="https://camo.githubusercontent.com/170fca3cee81a6a9ebd204ab82c9d602d87ce50f/68747470733a2f2f63646e2e646973636f72646170702e636f6d2f6174746163686d656e74732f3237373733393339343634313639303632352f3336303038363630373338303038363830372f4749462e676966"><img
 
            src="https://camo.githubusercontent.com/170fca3cee81a6a9ebd204ab82c9d602d87ce50f/68747470733a2f2f63646e2e646973636f72646170702e636f6d2f6174746163686d656e74732f3237373733393339343634313639303632352f3336303038363630373338303038363830372f4749462e676966"
Zircon comes with a bunch of built-in tilesets. These come in 2 flavors:
            alt=""
 
            data-canonical-src="https://cdn.discordapp.com/attachments/277739394641690625/360086607380086807/GIF.gif"
* CP437 tilesets ''(More on using them [https://github.com/Hexworks/zircon/wiki/Resource-Handling#cp437-tilesets here])''
            style="max-width:100%;"></a></p>
* and Graphic tilesets ''(Usage info [https://github.com/Hexworks/zircon/wiki/Resource-Handling#graphic-tilesets here])''
    <h4><a id="user-content-components-1" class="anchor" aria-hidden="true"
 
          href="#components-1">
Read more about them in the [https://github.com/Hexworks/zircon/wiki/Resource-Handling resource handling Wiki page] if you want to know more or if you want to use your own tilesets and fonts.
        <svg class="octicon octicon-link" viewBox="0 0 16 16" version="1.1" width="16"
 
            height="16" aria-hidden="true">
Zircon also comes with '''its own tileset format (<code>ztf</code>: Zircon Tileset Format)''' which is '''very easy to use'''. Its usage is detailed [https://github.com/Hexworks/zircon/wiki/Resource-Handling#graphic-tilesets here].
            <path fill-rule="evenodd"
 
                  d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path>
=== REXPaint file loading ===
        </svg>
 
    </a>Components:
REXPaint files (<code>.xp</code>) can be loaded into Zircon <code>Layer</code>s. Read about this feature [https://github.com/Hexworks/zircon/wiki/Resource-Handling#rexpaint-files here].
    </h4>
 
    <p><a target="_blank" rel="noopener noreferrer"
=== Color themes ===
          href="https://camo.githubusercontent.com/f6bc9e80cd8c70d5bda589335a0e5d5dd9cb70c9/68747470733a2f2f63646e2e646973636f72646170702e636f6d2f6174746163686d656e74732f3333353434343738383136373936363732302f3336313239373139303836333234313231382f4749462e676966"><img
 
            src="https://camo.githubusercontent.com/f6bc9e80cd8c70d5bda589335a0e5d5dd9cb70c9/68747470733a2f2f63646e2e646973636f72646170702e636f6d2f6174746163686d656e74732f3333353434343738383136373936363732302f3336313239373139303836333234313231382f4749462e676966"
Zircon comes with a bunch of built-in color themes which you can apply to your components. If interested you can read more about how this works [https://github.com/Hexworks/zircon/wiki/Working-with-ColorThemes here].
            alt=""
 
            data-canonical-src="https://cdn.discordapp.com/attachments/335444788167966720/361297190863241218/GIF.gif"
=== Animations (BETA) ===
            style="max-width:100%;"></a></p>
 
    <h2><a id="user-content-additional-features" class="anchor" aria-hidden="true"
Animations are a beta feature. More info [https://github.com/Hexworks/zircon/wiki/Animation-support here].
          href="#additional-features">
 
        <svg class="octicon octicon-link" viewBox="0 0 16 16" version="1.1" width="16"
=== The API ===
            height="16" aria-hidden="true">
 
            <path fill-rule="evenodd"
If you just want to peruse the Zircon API just navigate [https://github.com/Hexworks/zircon/tree/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api here]. Everything which is intended to be the public API is there.
                  d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path>
 
        </svg>
== Road map ==
    </a>Additional features
 
    </h2>
If you want to see a new feature feel free to [https://github.com/Hexworks/zircon/issues/new create a new Issue] or discuss it with us on [https://discord.gg/hbzytQJ discord]. Here are some features which are either under way or planned:
    <p>There are a bunch of other things Zircon can do which are not detailed in this README
 
        but you can read about them
* libGDX support
        in either the source code or the <a href="https://github.com/Hexworks/zircon/wiki">Wiki</a>:
* Layouts for Components with resizing support
    </p>
* Components for games like MapDisplay
    <h3><a id="user-content-layering" class="anchor" aria-hidden="true" href="#layering">
* Multi-Font support
        <svg class="octicon octicon-link" viewBox="0 0 16 16" version="1.1" width="16"
* Next to <code>ColorTheme</code>s we’ll introduce <code>ComponentTheme</code>s as well (custom look and feel for your components)
            height="16" aria-hidden="true">
 
            <path fill-rule="evenodd"
== License ==
                  d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path>
 
        </svg>
Zircon is made available under the [http://www.opensource.org/licenses/mit-license.php MIT License].
    </a>Layering
 
    </h3>
== Credits ==
    <p>Both the <a
 
            href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/grid/TileGrid.kt">TileGrid</a>
Zircon is created and maintained by Adam Arold, Milan Boleradszki and Gergely Lukacsy
        and the <a
 
                href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/screen/Screen.kt">Screen</a>
''We’re open to suggestions, feel free to message us on [https://discord.gg/hbzytQJ Discord] or open an issue.'' ''Pull requests are also welcome!''
        interfaces implement <a
 
                href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/behavior/Layerable.kt">Layerable</a>
Zircon is powered by:
        which means that you can add <a
                href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/graphics/Layer.kt">Layer</a>s
        on top of
        them. Every <a
                href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/behavior/Layerable.kt">Layerable</a>
        can have an arbitrary amount of <a
                href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/graphics/Layer.kt">Layer</a>s.
        <a href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/graphics/Layer.kt">Layer</a>s
        are like <a
                href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/graphics/TileGraphics.kt">TileGraphics</a>s
        and you can also have
        transparency in them which can be used to create fancy effects.
        For more details check the <a
                href="https://github.com/Hexworks/zircon/wiki/How-Layers-work">layers</a>
        Wiki page.</p>
    <blockquote>
        <p>Note that when creating <code>Layer</code>s you can set their <code>offset</code>
            from the builder but after attaching it to a
            <code>TileGrid</code> or <code>Screen</code> you can change its position by
            calling <code>moveTo</code> with a new <code>Position</code>.</p>
    </blockquote>
    <h3><a id="user-content-input-handling" class="anchor" aria-hidden="true"
          href="#input-handling">
        <svg class="octicon octicon-link" viewBox="0 0 16 16" version="1.1" width="16"
            height="16" aria-hidden="true">
            <path fill-rule="evenodd"
                  d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path>
        </svg>
    </a>Input handling
    </h3>
    <p>Both the <a
            href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/grid/TileGrid.kt">TileGrid</a>
        and the <a
                href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/screen/Screen.kt">Screen</a>
        interfaces implement <a
                href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/behavior/InputEmitter.kt">InputEmitter</a>
        which means that they re-emit all inputs from
        your users (key strokes and mouse actions) and you can listen on them. There is a <a
                href="https://github.com/Hexworks/zircon/wiki/Input-handling">Wiki page</a>
        with more info.</p>
    <h3><a id="user-content-shape-and-box-drawing" class="anchor" aria-hidden="true"
          href="#shape-and-box-drawing">
        <svg class="octicon octicon-link" viewBox="0 0 16 16" version="1.1" width="16"
            height="16" aria-hidden="true">
            <path fill-rule="evenodd"
                  d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path>
        </svg>
    </a>Shape and box drawing
    </h3>
    <p>You can draw <a
            href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/shape/Shape.kt">Shape</a>s
        like rectangles and triangles by using one of the <a
                href="https://github.com/Hexworks/zircon/blob/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api/shape/ShapeFactory.kt">ShapeFactory</a>
        implementations.
        Check the corresponding <a href="https://github.com/Hexworks/zircon/wiki/Shapes">Wiki
            page</a> for more info.</p>
    <h3><a id="user-content-fonts-and-tilesets" class="anchor" aria-hidden="true"
          href="#fonts-and-tilesets">
        <svg class="octicon octicon-link" viewBox="0 0 16 16" version="1.1" width="16"
            height="16" aria-hidden="true">
            <path fill-rule="evenodd"
                  d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path>
        </svg>
    </a>Fonts and tilesets
    </h3>
    <p>Zircon comes with a bunch of built-in tilesets. These come in 2 flavors:</p>
    <ul>
        <li>CP437 tilesets <em>(More on using them <a
                href="https://github.com/Hexworks/zircon/wiki/Resource-Handling#cp437-tilesets">here</a>)</em>
        </li>
        <li>and Graphic tilesets <em>(Usage info <a
                href="https://github.com/Hexworks/zircon/wiki/Resource-Handling#graphic-tilesets">here</a>)</em>
        </li>
    </ul>
    <p>Read more about them in the <a
            href="https://github.com/Hexworks/zircon/wiki/Resource-Handling">resource
        handling Wiki page</a> if you want to know more
        or if you want to use your own tilesets and fonts.</p>
    <p>Zircon also comes with <strong>its own tileset format (<code>ztf</code>: Zircon
        Tileset Format)</strong> which is <strong>very easy to use</strong>.
        Its usage is detailed <a
                href="https://github.com/Hexworks/zircon/wiki/Resource-Handling#graphic-tilesets">here</a>.
    </p>
    <h3><a id="user-content-rexpaint-file-loading" class="anchor" aria-hidden="true"
          href="#rexpaint-file-loading">
        <svg class="octicon octicon-link" viewBox="0 0 16 16" version="1.1" width="16"
            height="16" aria-hidden="true">
            <path fill-rule="evenodd"
                  d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path>
        </svg>
    </a>REXPaint file loading
    </h3>
    <p>REXPaint files (<code>.xp</code>) can be loaded into Zircon <code>Layer</code>s. Read
        about this feature
        <a href="https://github.com/Hexworks/zircon/wiki/Resource-Handling#rexpaint-files">here</a>.
    </p>
    <h3><a id="user-content-color-themes" class="anchor" aria-hidden="true"
          href="#color-themes">
        <svg class="octicon octicon-link" viewBox="0 0 16 16" version="1.1" width="16"
            height="16" aria-hidden="true">
            <path fill-rule="evenodd"
                  d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path>
        </svg>
    </a>Color themes
    </h3>
    <p>Zircon comes with a bunch of built-in color themes which you can apply to your
        components.
        If interested you can read more about how this works <a
                href="https://github.com/Hexworks/zircon/wiki/Working-with-ColorThemes">here</a>.
    </p>
    <h3><a id="user-content-animations-beta" class="anchor" aria-hidden="true"
          href="#animations-beta">
        <svg class="octicon octicon-link" viewBox="0 0 16 16" version="1.1" width="16"
            height="16" aria-hidden="true">
            <path fill-rule="evenodd"
                  d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path>
        </svg>
    </a>Animations (BETA)
    </h3>
    <p>Animations are a beta feature. More info <a
            href="https://github.com/Hexworks/zircon/wiki/Animation-support">here</a>.</p>
    <h3><a id="user-content-the-api" class="anchor" aria-hidden="true" href="#the-api">
        <svg class="octicon octicon-link" viewBox="0 0 16 16" version="1.1" width="16"
            height="16" aria-hidden="true">
            <path fill-rule="evenodd"
                  d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path>
        </svg>
    </a>The API
    </h3>
    <p>If you just want to peruse the Zircon API just navigate <a
            href="https://github.com/Hexworks/zircon/tree/master/zircon.core/src/main/kotlin/org/hexworks/zircon/api">here</a>.
        Everything which is intended to be the public API is there.</p>
    <h2><a id="user-content-road-map" class="anchor" aria-hidden="true" href="#road-map">
        <svg class="octicon octicon-link" viewBox="0 0 16 16" version="1.1" width="16"
            height="16" aria-hidden="true">
            <path fill-rule="evenodd"
                  d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path>
        </svg>
    </a>Road map
    </h2>
    <p>If you want to see a new feature feel free to <a
            href="https://github.com/Hexworks/zircon/issues/new">create a new Issue</a>
        or discuss it with us on <a href="https://discord.gg/hbzytQJ"
                                    rel="nofollow">discord</a>.
        Here are some features which are either under way or planned:</p>
    <ul>
        <li>libGDX support</li>
        <li>Layouts for Components with resizing support</li>
        <li>Components for games like MapDisplay</li>
        <li>Multi-Font support</li>
        <li>Next to <code>ColorTheme</code>s we'll introduce <code>ComponentTheme</code>s as
            well (custom look and feel for your components)
        </li>
    </ul>
    <h2><a id="user-content-license" class="anchor" aria-hidden="true" href="#license">
        <svg class="octicon octicon-link" viewBox="0 0 16 16" version="1.1" width="16"
            height="16" aria-hidden="true">
            <path fill-rule="evenodd"
                  d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path>
        </svg>
    </a>License
    </h2>
    <p>Zircon is made available under the <a
            href="http://www.opensource.org/licenses/mit-license.php" rel="nofollow">MIT
        License</a>.</p>
    <h2><a id="user-content-credits" class="anchor" aria-hidden="true" href="#credits">
        <svg class="octicon octicon-link" viewBox="0 0 16 16" version="1.1" width="16"
            height="16" aria-hidden="true">
            <path fill-rule="evenodd"
                  d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path>
        </svg>
    </a>Credits
    </h2>
    <p>Zircon is created and maintained by Adam Arold, Milan Boleradszki and Gergely
        Lukacsy</p>
    <p><em>We're open to suggestions, feel free to message us on <a
            href="https://discord.gg/hbzytQJ" rel="nofollow">Discord</a> or open an
        issue.</em>
        <em>Pull requests are also welcome!</em></p>
    <p>Zircon is powered by:</p>
    <a href="https://www.jetbrains.com/idea/" rel="nofollow">
        <img src="https://github.com/Hexworks/zircon/raw/master/images/idea_logo.png"
            width="40" height="40" style="max-width:100%;">
    </a>
    <a href="https://kotlinlang.org/" rel="nofollow">
        <img src="https://github.com/Hexworks/zircon/raw/master/images/kotlin_logo.png"
            width="40" height="40" style="max-width:100%;">
    </a>
    <a href="https://www.yourkit.com/java/profiler/" rel="nofollow">
        <img src="https://github.com/Hexworks/zircon/raw/master/images/yklogo.png"
            width="168" height="40" style="max-width:100%;">
    </a>


<a href="https://www.jetbrains.com/idea/"> <img src="https://github.com/Hexworks/zircon/blob/master/images/idea_logo.png" width="40" height="40" /> </a> <a href="https://kotlinlang.org/"> <img src="https://github.com/Hexworks/zircon/blob/master/images/kotlin_logo.png" width="40" height="40" /> </a> <a href="https://www.yourkit.com/java/profiler/"> <img src="https://github.com/Hexworks/zircon/blob/master/images/yklogo.png" width="168" height="40" /> </a>





Revision as of 11:02, 14 October 2018

Zircon
Library project
Developer Adam Arold
Released July 9 2017
Updated Dec 23 2017 (Stable), Mar 22 2018 (Preview)
Status Stable
Licensing MIT License
P. Language Kotlin, Java
Platforms Linux, Mac OS, Windows
Dependencies
Official site of Zircon

Zircon - A user-friendly Text GUI & Tile Engine Tweet

<img src="full_example.gif" />

Note that this library was inspired by Lanterna. Check it out if you are looking for a terminal emulator instead.



Need info? Check the Wiki | or Create an issue | Check our project Board | Ask us on Discord | Support us on Patreon

File:Https://circleci.com/gh/Hexworks/zircon/tree/master.svg?style=shield File:Https://maven-badges.herokuapp.com/maven-central/org.hexworks.zircon/zircon/badge.svg File:Https://jitpack.io/v/Hexworks/Zircon.svg File:Https://codecov.io/github/Hexworks/zircon/coverage.svg?branch=master File:Https://img.shields.io/badge/License-MIT-green.svg Awesome



Table of Contents

Getting Started

If you want to work with Zircon you can add it to your project as a dependency.

from Maven:

<dependency>
    <groupId>com.github.hexworks.zircon</groupId>
    <artifactId>zircon.jvm.swing</artifactId>
    <version>2018.3.27-PREVIEW</version>
</dependency>

or you can also use Gradle:

compile("com.github.hexworks.zircon:zircon.jvm.swing:2018.3.27-PREVIEW")

Note that you need to use Jitpack for the above dependencies to work.

Want to use a PREVIEW? Check this Wiki page

Some rules of thumb

Before we start there are some guidelines which can help you if you are stuck:

  • If you want to build something (a TileGraphics, a Component or anything which is part of the public API) it is almost sure that there is a Builder or a Factory for it. The convention is that if you want to create an TileGraphics for example, then you can use the DrawSurfaces class to do so. (so it is the plural form of the thing which you want to build). Your IDE will help you with this. These classes reside in the org.hexworks.zircon.api package.
  • If you want to work with external files like tilesets or REXPaint files check the same package (org.hexworks.zircon.api), and look for classes which end with *Resources. There are a bunch of built-in tilesets for example which you can choose from but you can also load your own. The rule of thumb is that if you need something external there is probably a *Resources class for it (like the CP437TilesetResources).
  • You can use anything you can find in the API package, they are part of the public API, and safe to use. The internal package however is considered private to Zircon so don’t depend on anything in it.
  • Some topics are explained in depth on the Wiki
  • If you want to see some example code look here.
  • If all else fails read the javadoc. API classes are well documented.
  • If you have any problems which are not answered here feel free to ask us at the Hexworks Discord server.

Creating an Application

In Zircon almost every object you might want to use has a helper class for building it. This is the same for Applications as well so let’s create one using the SwingApplications class:

Note that these examples reside in the org.hexworks.zircon.examples.docs package in the zircon.examples project, you can try them all out.

import org.hexworks.zircon.api.SwingApplications;
import org.hexworks.zircon.api.application.Application;

public class CreatingAnApplication {

    public static void main(String[] args) {

        Application application = SwingApplications.startApplication();
    }
}

Running this snippet will result in this screen:

File:Https://cdn.discordapp.com/attachments/363771631727804416/477466202982055939/CreatingAnApplication.png

Not very useful, is it? So what happens here? An Application is just an object which has a Renderer for rendering Tiles on your screen), and a TileGrid, which is the main interface which you will use to interact with Zircon. An Application is responsible for continuously rendering the contents of the grid on the screen. Here we use the Swing variant, but there are other types in the making (one for LibGDX, and one which works in the browser).

Since most of the time you don’t care about the Application itself, there is a function for creating a TileGrid directly:

import org.hexworks.zircon.api.SwingApplications;
import org.hexworks.zircon.api.grid.TileGrid;

public class CreatingATileGrid {

    public static void main(String[] args) {

        TileGrid tileGrid = SwingApplications.startTileGrid();
    }
}

Now let’s see how we can specify how a TileGrid is created. We’ll use the AppConfigs helper for this:

import org.hexworks.zircon.api.AppConfigs;
import org.hexworks.zircon.api.CP437TilesetResources;
import org.hexworks.zircon.api.Sizes;
import org.hexworks.zircon.api.SwingApplications;
import org.hexworks.zircon.api.grid.TileGrid;

public class CreatingATileGrid {

    public static void main(String[] args) {

        TileGrid tileGrid = SwingApplications.startTileGrid(
                AppConfigs.newConfig()
                        .defaultSize(Sizes.create(10, 10))
                        .defaultTileset(CP437TilesetResources.rexPaint16x16())
                        .build());
    }
}

Adding and formatting Tiles is very simple:

import org.hexworks.zircon.api.AppConfigs;
import org.hexworks.zircon.api.CP437TilesetResources;
import org.hexworks.zircon.api.Positions;
import org.hexworks.zircon.api.Sizes;
import org.hexworks.zircon.api.SwingApplications;
import org.hexworks.zircon.api.Tiles;
import org.hexworks.zircon.api.color.ANSITileColor;
import org.hexworks.zircon.api.grid.TileGrid;

public class CreatingATileGrid {

    public static void main(String[] args) {

        TileGrid tileGrid = SwingApplications.startTileGrid(
                AppConfigs.newConfig()
                        .defaultSize(Sizes.create(10, 10))
                        .defaultTileset(CP437TilesetResources.rexPaint16x16())
                        .build());

        tileGrid.setTileAt(
                Positions.create(2, 3),
                Tiles.newBuilder()
                        .backgroundColor(ANSITileColor.CYAN)
                        .foregroundColor(ANSITileColor.WHITE)
                        .character('x')
                        .build());

        tileGrid.setTileAt(
                Positions.create(3, 4),
                Tiles.newBuilder()
                        .backgroundColor(ANSITileColor.RED)
                        .foregroundColor(ANSITileColor.GREEN)
                        .character('y')
                        .build());

        tileGrid.setTileAt(
                Positions.create(4, 5),
                Tiles.newBuilder()
                        .backgroundColor(ANSITileColor.BLUE)
                        .foregroundColor(ANSITileColor.MAGENTA)
                        .character('z')
                        .build());
    }
}

Running the above code will result in something like this:

File:Https://cdn.discordapp.com/attachments/363771631727804416/477469640205926401/CreatingATileGrid.png

As you can see there is a helper for every class which you might want to use. Here we used Positions.create to create a Position, Sizes.create for creating Sizes and the TileBuilder to create tiles.

A Position denotes a coordinate on a TileGrid, so for example a Position of (3, 4) points to the 3rd column and the 4th row (x, y) on the grid.

Conversely a Size denotes an area with a width and a height. These two classes are used throughout Zircon.

A Tile is the most basic graphical unit Zircon supports. In most cases it is a simple character with a foreground and a background color (like in the example above).

In addition to colors and characters you can also use Modifiers in your Tiles.

A lot of fancy stuff can be done with Modifiers, like this:

File:Https://cdn.discordapp.com/attachments/363771631727804416/477470683513880576/modifiers.gif

If interested check out the code examples here.

Tileset (and by extension resource) handling in Zircon is very simple and if you are interested in how to load your custom fonts and other resources take a look at the Resource handling wiki page.

Working with Screens

TileGrids alone won’t suffice if you want to get any serious work done since they are rather rudimentary.

A Screen has its own buffer and it can be displayed on a TileGrid any time. This means that you can have multiple Screens at the same time representing your actual game screens. Note that only one Screen can be displayed at a given moment. displaying one deactivates the previous Screen.

Let’s create a Screen and fill it up with some stuff:

import org.hexworks.zircon.api.AppConfigs;
import org.hexworks.zircon.api.CP437TilesetResources;
import org.hexworks.zircon.api.ColorThemes;
import org.hexworks.zircon.api.Positions;
import org.hexworks.zircon.api.Screens;
import org.hexworks.zircon.api.Sizes;
import org.hexworks.zircon.api.SwingApplications;
import org.hexworks.zircon.api.DrawSurfaces;
import org.hexworks.zircon.api.Tiles;
import org.hexworks.zircon.api.component.ColorTheme;
import org.hexworks.zircon.api.graphics.TileGraphics;
import org.hexworks.zircon.api.grid.TileGrid;
import org.hexworks.zircon.api.screen.Screen;

public class CreatingAScreen {

    public static void main(String[] args) {

        TileGrid tileGrid = SwingApplications.startTileGrid(
                AppConfigs.newBuilder()
                        .defaultSize(Sizes.create(20, 8))
                        .defaultTileset(CP437TilesetResources.wanderlust16x16())
                        .build());

        final Screen screen = Screens.createScreenFor(tileGrid);

        final ColorTheme theme = ColorThemes.adriftInDreams();

        final TileGraphics image = DrawSurfaces.tileGraphicsBuilder()
                .size(tileGrid.size)
                .build()
                .fill(Tiles.newBuilder()
                        .foregroundColor(theme.getBrightForegroundColor())
                        .backgroundColor(theme.getBrightBackgroundColor())
                        .character('~')
                        .build());

        screen.draw(image, Positions.defaultPosition());

        screen.display();
    }
}

and we’ve got a nice ocean:

File:Https://cdn.discordapp.com/attachments/363771631727804416/477475680594952223/CreatingAScreen.png

What happens here is that we:

For more explanation about these jump to the How Zircon works section.

You can do so much more with Screens. If interested then check out A primer on Screens on the Wiki!

Components

Zircon supports a bunch of Components out of the box:

  • Button: A simple clickable component with corresponding event listeners
  • CheckBox: Like a BUTTON but with checked / unchecked state
  • Label: Simple component with text
  • Header: Like a label but this one has emphasis (useful when using ColorThemes)
  • Panel: A Container which can hold multiple Components
  • RadioButtonGroup and RadioButton: Like a CheckBox but only one can be selected at a time
  • TextBox: Similar to a text area in HTML this Component can be written into

These components are rather simple and you can expect them to work in a way you might be familiar with:

  • You can click on them (press and release are different events)
  • You can attach event listeners on them
  • Zircon implements focus handling so you can navigate between the components using the [Tab] key (forwards) or the [Shift]+[Tab] key stroke (backwards).
  • Components can be hovered and they can change their styling when you do so

Let’s look at an example (notes about how it works are in the comments):

import org.hexworks.zircon.api.*;
import org.hexworks.zircon.api.component.Button;
import org.hexworks.zircon.api.component.CheckBox;
import org.hexworks.zircon.api.component.Header;
import org.hexworks.zircon.api.component.Panel;
import org.hexworks.zircon.api.grid.TileGrid;
import org.hexworks.zircon.api.screen.Screen;

public class UsingComponents {

    public static void main(String[] args) {

        final TileGrid tileGrid = SwingApplications.startTileGrid(
                AppConfigs.newConfig()
                        .defaultSize(Sizes.create(34, 18))
                        .defaultTileset(CP437TilesetResources.wanderlust16x16())
                        .build());
        final Screen screen = Screens.createScreenFor(tileGrid);

        Panel panel = Components.panel()
                .wrapWithBox() // panels can be wrapped in a box
                .title("Panel") // if a panel is wrapped in a box a title can be displayed
                .wrapWithShadow() // shadow can be added
                .size(Sizes.create(32, 16)) // the size must be smaller than the parent's size
                .position(Positions.offset1x1())
                .build(); // position is always relative to the parent

        final Header header = Components.header()
                // this will be 1x1 left and down from the top left
                // corner of the panel
                .position(Positions.offset1x1())
                .text("Header")
                .build();

        final CheckBox checkBox = Components.checkBox()
                .text("Check me!")
                .position(Positions.create(0, 1)
                        // the position class has some convenience methods
                        // for you to specify your component's position as
                        // relative to another one
                        .relativeToBottomOf(header))
                .build();

        final Button left = Components.button()
                .position(Positions.create(0, 1) // this means 1 row below the check box
                        .relativeToBottomOf(checkBox))
                .text("Left")
                .build();

        final Button right = Components.button()
                .position(Positions.create(1, 0) // 1 column right relative to the left BUTTON
                        .relativeToRightOf(left))
                .text("Right")
                .build();

        panel.addComponent(header);
        panel.addComponent(checkBox);
        panel.addComponent(left);
        panel.addComponent(right);

        screen.addComponent(panel);

        // we can apply color themes to a screen
        screen.applyColorTheme(ColorThemes.techLight());

        // this is how you can define interactions with a component
        left.onMouseReleased((mouseAction -> {
            screen.applyColorTheme(ColorThemes.adriftInDreams());
        }));

        right.onMouseReleased((mouseAction -> {
            screen.applyColorTheme(ColorThemes.solarizedDarkOrange());
        }));

        // in order to see the changes you need to display your screen.
        screen.display();
    }
}

And the result will look like this:

File:Https://cdn.discordapp.com/attachments/363771631727804416/363813193488924673/image.png

You can check out more examples here. Here are some screenshots of them:

Tileset example:

File:Https://cdn.discordapp.com/attachments/277739394641690625/348400285879894018/image.png

Animations:

File:Https://cdn.discordapp.com/attachments/277739394641690625/360086607380086807/GIF.gif

Components:

File:Https://cdn.discordapp.com/attachments/335444788167966720/361297190863241218/GIF.gif

Additional features

There are a bunch of other things Zircon can do which are not detailed in this README but you can read about them in either the source code or the Wiki:

Layering

Both the TileGrid and the Screen interfaces implement Layerable which means that you can add Layers on top of them. Every Layerable can have an arbitrary amount of Layers. Layers are like TileGraphicss and you can also have transparency in them which can be used to create fancy effects. For more details check the layers Wiki page.

Note that when creating Layers you can set their offset from the builder but after attaching it to a TileGrid or Screen you can change its position by calling moveTo with a new Position.

Input handling

Both the TileGrid and the Screen interfaces implement InputEmitter which means that they re-emit all inputs from your users (key strokes and mouse actions) and you can listen on them. There is a Wiki page with more info.

Shape and box drawing

You can draw Shapes like rectangles and triangles by using one of the ShapeFactory implementations. Check the corresponding Wiki page for more info.

Fonts and tilesets

Zircon comes with a bunch of built-in tilesets. These come in 2 flavors:

  • CP437 tilesets (More on using them here)
  • and Graphic tilesets (Usage info here)

Read more about them in the resource handling Wiki page if you want to know more or if you want to use your own tilesets and fonts.

Zircon also comes with its own tileset format (ztf: Zircon Tileset Format) which is very easy to use. Its usage is detailed here.

REXPaint file loading

REXPaint files (.xp) can be loaded into Zircon Layers. Read about this feature here.

Color themes

Zircon comes with a bunch of built-in color themes which you can apply to your components. If interested you can read more about how this works here.

Animations (BETA)

Animations are a beta feature. More info here.

The API

If you just want to peruse the Zircon API just navigate here. Everything which is intended to be the public API is there.

Road map

If you want to see a new feature feel free to create a new Issue or discuss it with us on discord. Here are some features which are either under way or planned:

  • libGDX support
  • Layouts for Components with resizing support
  • Components for games like MapDisplay
  • Multi-Font support
  • Next to ColorThemes we’ll introduce ComponentThemes as well (custom look and feel for your components)

License

Zircon is made available under the MIT License.

Credits

Zircon is created and maintained by Adam Arold, Milan Boleradszki and Gergely Lukacsy

We’re open to suggestions, feel free to message us on Discord or open an issue. Pull requests are also welcome!

Zircon is powered by:

<a href="https://www.jetbrains.com/idea/"> <img src="idea_logo.png" width="40" height="40" /> </a> <a href="https://kotlinlang.org/"> <img src="kotlin_logo.png" width="40" height="40" /> </a> <a href="https://www.yourkit.com/java/profiler/"> <img src="yklogo.png" width="168" height="40" /> </a>