ruby-iup-binding

home

peterlane.netlify.app/ruby-iup/

source

notabug.org/peterlane/ruby-iup-binding

Description

FFI binding for Ruby to the IUP portable user interface toolkit. 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.

Simple Example

With 'iup-ffi'

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

require 'iup-ffi'
include Iup

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

  Dialog.new btn do
    title 'Example program'
  end.show
end

With 'iup-ffi-plain'

A direct mapping to the C API of IUP is available by requiring 'iup-ffi-plain'. This can be useful when converting code from other sources, or to access options not available in Iup. For example:

require 'iup-ffi-plain'

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

Behind the Scenes

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

Attributes are accessed by name through get and set methods. 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.

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, a method is provided with the same name as the attribute.

Use the method with no values to retrieve the attribute's current value; pass an argument to set the attribute's value.

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

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'

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'

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 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>
   image img_release                                 # <3>
end
  1. Create an Image.

  2. Create a Button.

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

Differences to IUP

The Ruby library provides a not-quite-complete binding to IUP.

Some of the missing elements include:

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

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:

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 widgets Normalizer and Zbox are only available through the C API. To create a Zbox with two children, use:

handle = IupLib.IupZbox child1.handle, :pointer, child2.handle, :pointer, nil

Resources

Cursors

Available cursors (see list and image at www.tecgraf.puc-rio.br/iup/en/attrib/iup_cursor.html):

Fonts

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

Font-name:

Font-style:

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

Examples:

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 see: www.tecgraf.puc-rio.br/iup/en/iupimglib.html

For example, a button with an ActionOk icon:

Button.new do 
  image 'IUP_ActionOk'
end

The list of available images is: