iup-ffi

FFI binding for Ruby to Tecgraf’s IUP portable user interface toolkit; IUP is a multi-platform toolkit for building graphical user interfaces. The library provides both a low-level binding to the C library calls, and a high-level wrapping of most widgets to give a more natural Ruby syntax.

This library is available as a rubygem or in source format.

Tecgraf’s IUP documentation (Version 3.32) should be read along with the API documentation for iup-ffi. A number of examples can be found in the source, or downloaded with the latest tagged version.

Description

The module Iup provides a Ruby-flavoured syntax for creating a GUI, wrapping each IUP component in a Ruby class with suitable mutators/accessors for the attributes and associated methods. For example:

require "iup-ffi"

Iup.mainloop do
  btn = Iup::Button.new("click me", ->{ puts "clicked" }) do |b|
    b.font = "Times, Bold 18"
  end
  puts "Button font is: ", btn.font

  Iup::Dialog.new(btn) do |d|
    d.title = "Example program"
  end.show
end

For direct access to the shared libraries, the bound functions for IUP, CD and IM are available in separate modules (names ending in “Lib”). These low-level functions provide a direct mapping to the C API of IUP. This can be useful when converting code from other sources or when something is missing from the wrapper. For example, the C program (www.tecgraf.puc-rio.br/iup/examples/C/message.c):

/* IupMessage Example */

#include <stdlib.h>
#include <stdio.h>

/* IUP libraries include */
#include <iup.h>

/* Main program */
int main(int argc, char **argv)
{
  /* Initializes IUP */
  IupOpen(&argc, &argv);
  
  /* Executes IupMessage */
  IupMessage("IupMessage Example", "Press the button");

  /* Finishes IUP */
  IupClose ();

  /* Program finished successfully */
  return EXIT_SUCCESS;

}

is translated into Ruby as:

require "iup-ffi" # or "iup-ffi-plain" for just the low-level bindings

IupLib.IupOpen(0, nil)
IupLib.IupMessage("IupMessage Example", "Press the button")
IupLib.IupClose

Supported Widgets

(As IUP is a large library and continues to be expanded, the list of supported widgets and their properties is at best partial.)

Top-level containers:

• Iup::ColorDialog, Iup::Dialog, Iup::FileDialog, Iup::FontDialog, Iup::MessageDialog, Iup::ProgressDialog

Layout containers to arrange child widgets:

• Iup::Fill, Iup::GridBox, Iup::HBox, Iup::VBox, Iup::ZBox, Iup::ScrollBox, Iup::SplitBox, Iup::StretchBox,

Grouping containers to organise related controls:

• Iup::BackgroundBox, Iup::Expander, Iup::Frame, Iup::Radio, Iup::Tabs

Information controls to display data:

• Iup::Image, Iup::ImageRGB, Iup::ImageRGBA, Iup::Label, Iup::Link, Iup::ProgressBar

Interactive controls:

• Iup::Button, Iup::ColorBar, Iup::Dial, Iup::List, Iup::Text, Iup::Toggle, Iup::Tree, Iup::Val

Specialised/complex widgets:

• Iup::Canvas, Iup::Matrix, Iup::Scintilla

Non-visual controls and menus:

• Iup::Menu, Iup::MenuItem, Iup::Separator, Iup::SubMenu, Iup::Timer

Installation

Pre-built binaries are supported on Linux and Windows (x64) platforms:

$ gem install iup-ffi

• Windows gem does not include Iup::Scintilla.

From source, download the CD, IM and IUP shared libraries from www.tecgraf.puc-rio.br/iup/en/download_tips.html into the appropriate “lib/library” folder: Linux68_64 and Win64_dllw6 are used in the pre-built binaries.

Support

File bugs at the codeberg issues page, or send an email to peterlane@gmx.com.

Copyright/Licence

iup-ffi is copyright © 2014-26 Peter Lane, and released under the MIT Licence. Tecgraf IUP products are also released under the MIT licence: www.tecgraf.puc-rio.br/iup/en/copyright.html