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>
-
Create an
Image
. -
Attach the name “img_release” to the image.
-
Create a
Button
. -
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
-
Create an
Image
. -
Create a
Button
. -
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:
-
anything that has been deprecated. For example, the
multiline
text widget has been deprecated in favour of using atext
widget with itsmultiline
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
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:
-
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 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):
-
“NONE” or “NULL”
-
“ARROW”
-
“BUSY”
-
“CROSS”
-
“HAND”
-
“HELP”
-
“MOVE”
-
“PEN”
-
“RESIZE_N”
-
“RESIZE_S”
-
“RESIZE_NS”
-
“RESIZE_W”
-
“RESIZE_E”
-
“RESIZE_WE”
-
“RESIZE_NE
-
“RESIZE_SW”
-
“RESIZE_NW
-
“RESIZE_SE”
-
“TEXT”
-
“UPARROW”
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”
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:
-
“IUP_ActionCancel”
-
“IUP_ActionOk”
-
“IUP_ArrowDown”
-
“IUP_ArrowLeft”
-
“IUP_ArrowRight”
-
“IUP_ArrowUp”
-
“IUP_EditCopy”
-
“IUP_EditCut”
-
“IUP_EditErase”
-
“IUP_EditFind”
-
“IUP_EditPaste”
-
“IUP_EditRedo”
-
“IUP_EditUndo”
-
“IUP_FileClose”
-
“IUP_FileCloseAll”
-
“IUP_FileNew”
-
“IUP_FileOpen”
-
“IUP_FileProperties”
-
“IUP_FileSave”
-
“IUP_FileSaveAll”
-
“IUP_FileText”
-
“IUP_FontBold”
-
“IUP_FontDialog”
-
“IUP_FontItalic”
-
“IUP_MediaForward”
-
“IUP_MediaGotoBegin”
-
“IUP_MediaGoToEnd”
-
“IUP_MediaPause”
-
“IUP_MediaPlay”
-
“IUP_MediaRecord”
-
“IUP_MediaReverse”
-
“IUP_MediaRewind”
-
“IUP_MediaStop”
-
“IUP_MessageError”
-
“IUP_MessageHelp”
-
“IUP_MessageInfo”
-
“IUP_NavigateHome”
-
“IUP_NavigateRefresh”
-
“IUP_Print”
-
“IUP_PrintPreview”
-
“IUP_ToolsColor”
-
“IUP_ToolsSettings”
-
“IUP_ToolsSortAscend”
-
“IUP_ToolsSortDescend”
-
“IUP_ViewFullScreen”
-
“IUP_Webcam”
-
“IUP_WindowsCascade”
-
“IUP_WindowsTile”
-
“IUP_Zoom”
-
“IUP_ZoomActualSize”
-
“IUP_ZoomIn”
-
“IUP_ZoomOut”
-
“IUP_ZoomSelection”
-
“IUP_Tecgraf”
-
“IUP_PUC-Rio”
-
“IUP_BR”
-
“IUP_Lua”
-
“IUP_TecgrafPUC-Rio”
-
“IUP_Petrobras”