IUP Intro

IUP (homepage) is the graphics library exposed to Lua.

The game uses a modifed version of IUP 2.4. The documentation for this release can be downloaded here.

Overview

The basic building blocks elements (like buttons, dropdown boxes etc.) and containers (hbox and vbox). Elements are put into containers which then decide how to display the elements.

For a list of avaialable functions, see the List of IUP functions

hbox and vbox

These are the basic containers. Elements put into an hbox ("horizontal box") will be stacked horizontally, while a vbox ("vertical box") will arrange them vertically. Containers can be added as elements into other containers, i.e. they can be nested.

The following, for example, would produce a box with two vertically arranged labels as elements (i.e. they wouldd appear on top of each other). <source lang="lua"> iup.vbox {

   iup.label{ title = "[Label 1]" },
   iup.label{ title = "[Label 2]" },

} </source>

A simple example of nesting: <source lang="lua"> iup.hbox {

   iup.vbox {
       iup.label{ title = "[Label 1]" },
       iup.label{ title = "[Label 2]" },
   },
   iup.vbox {
       iup.label { title = "[Label 3]" },
       iup.label { title = "[Label 4]" },
   }

} </source>

When stuck into a window, the result would look something like this:

   +-----------------x+
   +------------------+
   |[Label 1][Label 3]|
   |[Label 2][Label 4]|
   +------------------+

Windows

The boxes need to be put into a window to actually be displayed. This is done by using an IUP dialog and a "pdarootframe". Using the example above ("iuppy" can obviously be replaced with anything): <source lang="lua"> iuppy.main = iup.dialog {

   iup.pdarootframe {
       iup.hbox {
           iup.vbox {
               iup.label{ title = "[Label 1]" },
               iup.label{ title = "[Label 2]" }
           },
           iup.vbox {
               iup.label { title = "[Label 3]" },
               iup.label { title = "[Label 4]" }
           }
       }
   };
   TOPMOST = "yes"

} </source>

Show and Hide

You can control when to show and when not to show the created window using the "show" and "hide" functions; they do the obvious thing: <source lang="lua"> iuppy.main:show() -- Displays the window iuppy.main:hide() -- Hides the window </source> Calling show when the window is already showing or calling hide when it's already hidden does nothing.

Images

Images are are commonly displayed using labels, although other widgets can have one or more assigned to them too. To display an image with a label leave the "title" attribute blank and point the "image" attribute to the image file. The "bgcolor" attribute affects how the image is rendered.

<source lang="lua"> iup.label{title="", image="bla.png"} </source>

To work everywhere image dimensions should be powers of two. Supported formats are PNG, TGA and JPEG.

The UV attribute can be used to display a part of an image. The Attribute string has the format "topx topy bottomx bottomy". Each parameter is a float, between 0 and 1, originating in the top left corner of the source image.

this displays the top left quarter of the image: <source lang="lua"> iup.label{title="", image="bla.png", UV="0 0 0.5 0.5"} </source>