It is worth reading the Tecgraf introductions to Iup, especially in the Guide and Tutorial.

In IUP, widgets are referenced using a handle. Behaviour is modified using attributes and callbacks.

There are two parts to the iup-ffi library:

  • low-level, providing a binding directly to the C API; and

  • high-level, providing a wrapper around the bindings with a better Ruby syntax.

The low-level binding is described below. The rest of the documentation concerns the wrapper, which provides a not-quite-complete binding to IUP.

Some of the missing elements include:

  • anything that has been deprecated. For example, the multiline text widget has been deprecated in favour of using a text widget with its multiline attribute set to "yes".

  • various platform specific functionality.

  • dropfiles

  • GetParam

Some control names have been changed, to be more informative:

  • IUP name → Iup-FFI Ruby name

  • Sbox → StretchBox

  • Split → SplitBox

1. Attributes

Attributes are accessed by name through get and set methods. In this wrapper, instances of Ruby classes represent each widget, container or other IUP object. Each class provides one method per attribute. Attributes come in three forms, and a consistent scheme is used to represent these attributes as Ruby methods.

All attributes must be called with an explicit receiver. This generally only becomes an issue if you subclass an Iup widget, but can also occur in some callbacks. For example:

class TheDialog < Iup::Dialog
  def initialize(title)
    button = Iup::Button.new("Click me") do
      it.action = ->{ Iup.message("Hello", "Thanks for clicking") }
    end
    panel = Iup::VBox.new(button) do
      it.margin = "20x20"
    end
    super panel
    self.title = title # <--------------------
  end
end

Notice that the call to set the title requires an explicit self - otherwise, as usual in Ruby, a new local variable title will be created, and the title will be silently lost.

1.1. Attributes by name

Most attributes are accessed using a simple name. e.g. to define a text widget as a multiline or single line. In C:

  // to get the value of the attribute
  IupGetAttribute(handle, "MULTILINE");
  // to set the value of the attribute
  IupSetAttribute(handle, "MULTILINE", "YES");

In Ruby, these attributes are mapped as parameters:

  # to get the value of the attribute
  text.multiline
  # to set the value of the attribute
  text.multiline = 'YES'

Some parameters are marked read or write only, and only support one of the two accessor methods.

1.2. Attributes with id

Some of the attributes take an id or index. For example, in a list control, items are placed using an index number. The attribute uses the index number within the attribute name. In C:

  // get the first item in a list
  IupGetAttribute(handle, "ITEM1");
  // set the first item in a list
  IupSetAttribute(handle, "ITEM1", "value");

In Ruby, such attributes are represented by a method which takes a parameter for the index:

  # get the first item in a list
  list.item(1)
  # set the first item in a list
  list.item(1, 'value')

1.3. Attributes with properties

A few attributes take a complex value, representing a property-value pair. For example, in Scintilla the attribute markerdefine takes as value a setting, value pair. In C:

  // get markerdefine folder
  IupGetAttribute(handle, "MARKERDEFINE", "FOLDER");
  // set markerdefine folder to plus
  IupSetAttribute(handle, "MARKERDEFINE", "FOLDER=PLUS");

In Ruby, such attributes are represented by a method which takes a parameter for the property:

  # get markerdefine folder
  scintilla.markerdefine('folder')
  # set markerdefine folder to plus
  scintilla.markerdefine('folder', 'plus')

2. References

Some attributes take references to other objects. For example, setting the image to display on a button. In IUP, images (and other widgets) may be given names, called their "handle", which are referred to when attaching the image to a button.

For example, in C (from http://www.tecgraf.puc-rio.br/iup/examples/C/button.c):

  /* Defines released button's image size */
  img_release = IupImage(16, 16, pixmap_release);                 // (1)

  /* Associates img_release with handle "img_release" */
  IupSetHandle( "img_release", img_release );                     // (2)

  /* Creates a button */
  btn_image = IupButton ( "Button with image", "btn_image");      // (3)

  /* Sets released, pressed and inactive button images */
  IupSetAttribute( btn_image, "IMAGE", "img_release" );           // (4)

  1. Create an Image.

  2. Attach the name "img_release" to the image.

  3. Create a Button.

  4. Attach the image named "img_release" to the button.

In Ruby, instances of widgets can be used as arguments directly where appropriate, without naming them:

  img_release = Image.new(16, 16, pixmap_release)     # (1)
  btn_image = Button.new('Button with image') do      # (2)
    it.image = img_release                            # (3)
 end

  1. Create an Image.

  2. Create a Button.

  3. Attach the image referenced in img_release to the button.

3. Resources

3.1. Cursors

Available cursors are shown on the Tecgraf Documentation.

3.2. Fonts

Fonts are described as a triple: "font-name, font-styles font-size". For consistency, restrict use to the following:

Font-name:

  • courier

  • helvetica

  • times

Font-style:

  • bold

  • italic

  • strikeout

  • underline

Font-size is in points (1/72 of an inch), or in pixels (with negative numbers).

Examples:

  • "Times, bold 12"

  • "Courier, bold italic 18"

3.3. Images

Various ways of obtaining, creating and using images are supported by Iup::ImageWidget and its child classes.

The library also includes a number of pre-defined images, which can be used by name wherever an image is expected. For details, and a list of named images, see: http://www.tecgraf.puc-rio.br/iup/en/iupimglib.html

For example, a button with an ActionOk icon:

  Button.new do
    image = 'IUP_ActionOk'
  end

4. Using the FFI directly

To use the C API directly, without the Ruby wrapper:

  require 'iup-ffi-plain'

This provides modules giving direct access to the C API of IUP through FFI. These modules are named NNNNLib, and the bound functions are listed in the API documentation. For example:

  • IupLib the core IUP controls and functions.

  • ImgLib the image library.

  • ScintillaLib the Scintilla widget.

The names used echo those of the C API. For instance, IupSetAttribute is IupLib.IupSetAttribute. The C API is almost completely wrapped, and can be accessed if necessary for anything not covered within "iup-ffi".

In most cases, calls to the C API will need the handle of the widget: this is available for the Ruby classes using the handle attribute.

For example:

  btn = Button.new('text')
  IupLib.IupSetAttribute(btn.handle, 'FONT', 'Times, BOLD 18')

The layout widget Normalizer is only available through the C API. To create a Normalizer with two children, use:

  handle = IupLib.IupNormalizer(child1.handle, :pointer, child2.handle, :pointer, nil)