iup-ffi 0.12.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4da0308e74093ebf8c476f7f3583ff762013eafe1be412894daf037c507829fe
+  data.tar.gz: 1d20c7fb3d37676ce2a375dbb6e7a29582cf97283cd0d31d1338dccc4bafb6ad
+SHA512:
+  metadata.gz: febbb65f5bcdf7897ac7b7e504337ae8188e907b5242f5c8f95f9283318736d703be6806fe5519242e32107a17413c428b9cfa864bb513c41ae5f313d39c4c7e
+  data.tar.gz: cef7c7426dc4af9b20a23e3e27e1f8687264044459c5fd4a73128308a816771856e36c63188c1fcf95549913f22a2987af376e89938f1320c7c8a97ea4238bbd

data/LICENCE.txt

@@ -0,0 +1,21 @@
+The MIT Licence (MIT)
+
+Copyright (c) 2014-26, Peter Lane.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,348 @@
+= ruby-iup-binding
+
+FFI binding for Ruby to the IUP[http://www.tecgraf.puc-rio.br/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.
+
+== Install IUP Libraries
+
+This library currently only works on Linux.
+
+Install the shared libraries from 
+{IUP downloads}[https://www.tecgraf.puc-rio.br/iup/en/download_tips.html] for IUP,
+IM and CD. The shared files must be placed where the system will find them: instead 
+of using the provided installer, I copied the files to /usr/local/lib on Ubuntu.
+
+The required files are:
+
+* libcd.so - from CD files
+* libim.so - from IM files
+
+And, from IUP files:
+
+* libiupcontrols.so  
+* libiup_scintilla.so
+* libiupimglib.so    
+* libiup.so
+* libiupcd.so  
+* libiupim.so  
+
+== 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 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>
+    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[http://www.tecgraf.puc-rio.br/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
+
+
+== 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 http://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: 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
+
+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"
+
+

data/lib/iup-ffi-plain.rb

@@ -0,0 +1,9 @@
+# Provides the direct bindings through FFI to the IUP libraries.
+
+require 'wrapped/constants'
+require 'plain/iuplib'
+require 'plain/iupcdlib'
+require 'plain/iupcontrolslib'
+require 'plain/iupimlib'
+require 'plain/iupimglib'
+require 'plain/scintilla-lib'

data/lib/iup-ffi.rb

@@ -0,0 +1,76 @@
+# Requires files needed for wrapping the plain Iup libraries.
+#
+require 'ffi'
+require 'rbconfig'
+
+require 'iup-ffi-plain'
+
+# helper code
+require 'wrapped/attribute-builders'
+require 'wrapped/attribute-reference'
+require 'wrapped/dynamic-fill-methods'
+require 'wrapped/common-attributes'
+require 'wrapped/image-attributes'
+require 'wrapped/callback-setter'
+require 'wrapped/drag-drop-attributes'
+require 'wrapped/internal-drag-drop-attributes'
+require 'wrapped/scrollbar-attributes'
+
+# the wrapper classes themselves
+# -- core libraries
+require 'wrapped/dialogs'
+
+require 'wrapped/widget'
+require 'wrapped/button'
+require 'wrapped/canvas'
+require 'wrapped/frame'
+require 'wrapped/label'
+require 'wrapped/link'
+require 'wrapped/list'
+require 'wrapped/progressbar'
+require 'wrapped/tabs'
+require 'wrapped/text'
+require 'wrapped/toggle'
+require 'wrapped/tree'
+require 'wrapped/val'
+
+# -- dialogs
+require 'wrapped/colourdialog'
+require 'wrapped/dialog'
+require 'wrapped/filedialog'
+require 'wrapped/fontdialog'
+require 'wrapped/messagedialog'
+require 'wrapped/progressdialog'
+
+# -- resources
+require 'wrapped/image'
+require 'wrapped/menu'
+require 'wrapped/menuitem'
+require 'wrapped/separator'
+require 'wrapped/submenu'
+require 'wrapped/timer'
+
+# -- layout
+require 'wrapped/background-box'
+require 'wrapped/expander'
+require 'wrapped/fill'
+require 'wrapped/gridbox'
+require 'wrapped/hbox'
+require 'wrapped/radio'
+require 'wrapped/scrollbox'
+require 'wrapped/splitbox'
+require 'wrapped/stretchbox'
+require 'wrapped/vbox'
+require 'wrapped/zbox'
+
+# -- extensions
+require 'wrapped/scintilla'
+
+# -- additional controls
+require 'wrapped/colourbar'
+require 'wrapped/dial'
+require 'wrapped/matrix'
+
+# -- global methods
+require 'wrapped/iup-global' 
+

data/lib/plain/iupcdlib.rb

@@ -0,0 +1,107 @@
+# Binding to the CD library
+#
+# TODO: 
+# - images
+# - various get functions
+#
+module CdLib # :nodoc:
+  extend FFI::Library
+
+  case RbConfig::CONFIG['host_os']
+#  when /mswin|mingw/
+#    ffi_lib 'lib/library/iup.dll'
+  when /linux|cygwin/
+    ffi_lib 'libiupcd'
+  else
+    raise Exception, 'iup libraries not found for this platform'
+  end
+
+  attach_function :cdContextIup, [], :pointer
+
+  # -- initialisation
+
+  attach_function :cdCreateCanvas, [:pointer, :pointer], :pointer
+  attach_function :cdKillCanvas, [:pointer], :void
+  attach_function :cdCanvasActivate, [:pointer], :int
+  attach_function :cdCanvasDeactivate, [:pointer], :void
+  attach_function :cdUseContextPlus, [:int], :int
+ # attach_function :cdInitContextPlus, [:void], :void
+  attach_function :cdCanvasGetContext, [:pointer], :pointer
+  attach_function :cdContextCaps, [:pointer], :int
+  attach_function :cdContextType, [:pointer], :int
+  attach_function :cdContextIsPlus, [:pointer], :int
+  attach_function :cdCanvasSimulate, [:pointer, :int], :int
+
+  attach_function :wdCanvasViewport, [:pointer, :int, :int, :int, :int], :void
+  attach_function :wdCanvasWindow, [:pointer, :double, :double, :double, :double], :void
+
+  # -- general attributes
+  attach_function :cdCanvasForeground, [:pointer, :long], :long
+  attach_function :cdCanvasBackground, [:pointer, :long], :long
+  attach_function :cdCanvasWriteMode, [:pointer, :int], :int
+
+  # -- control
+
+  attach_function :cdCanvasClear, [:pointer], :int
+
+  # -- begin/end blocks
+  attach_function :cdCanvasBegin, [:pointer, :int], :void
+  attach_function :cdCanvasVertex, [:pointer, :int, :int], :void
+  attach_function :cdCanvasEnd, [:pointer], :void
+  attach_function :cdCanvasPathSet, [:pointer, :int], :void
+
+  # --- marks
+  attach_function :cdCanvasPixel, [:pointer, :int, :int], :void
+  attach_function :cdCanvasMark, [:pointer, :int, :int], :void
+  attach_function :cdCanvasMarkType, [:pointer, :int], :int
+  attach_function :cdCanvasMarkSize, [:pointer, :int], :int
+
+  # --- lines
+
+  attach_function :cdCanvasLine, [:pointer, :int, :int, :int, :int], :void
+  attach_function :cdCanvasRect, [:pointer, :int, :int, :int, :int], :void
+  attach_function :cdCanvasArc, [:pointer, :int, :int, :int, :int, :double, :double], :void
+  attach_function :cdCanvasLineStyle, [:pointer, :int], :int
+#  attach_function :cdCanvasLineStyleDashes, [:pointer, :pointer, :int], :void # TODO: pointer to int array?
+  attach_function :cdCanvasLineWidth, [:pointer, :int], :int
+  attach_function :cdCanvasLineJoin, [:pointer, :int], :int
+  attach_function :cdCanvasLineCap, [:pointer, :int], :int
+
+  # --- filled areas
+
+  attach_function :cdCanvasBox, [:pointer, :int, :int, :int, :int], :void
+  attach_function :cdCanvasSector, [:pointer, :int, :int, :int, :int, :double, :double], :int
+  attach_function :cdCanvasChord, [:pointer, :int, :int, :int, :int, :double, :double], :int
+  attach_function :cdCanvasBackOpacity, [:pointer, :int], :int
+  attach_function :cdCanvasFillMode, [:pointer, :int], :int
+  attach_function :cdCanvasInteriorStyle, [:pointer, :int], :int
+  attach_function :cdCanvasHatch, [:pointer, :int], :int
+  attach_function :cdCanvasStipple, [:pointer, :int, :int, :string], :void
+
+  # --- text
+
+  attach_function :cdCanvasText, [:pointer, :int, :int, :string], :void
+  attach_function :cdCanvasFont, [:pointer, :string, :int, :int], :void
+  attach_function :cdCanvasNativeFont, [:pointer, :string], :string
+  attach_function :cdCanvasTextAlignment, [:pointer, :int], :int
+  attach_function :cdCanvasTextOrientation, [:pointer, :double], :double
+  # TODO: Get functions
+
+  # --- vector text
+
+  attach_function :cdCanvasVectorText, [:pointer, :int, :int, :string], :void
+  attach_function :cdCanvasVectorTextDirection, [:pointer, :int, :int, :int, :int], :void
+  attach_function :cdCanvasVectorTextSize, [:pointer, :int, :int, :string], :void
+  attach_function :cdCanvasVectorCharSize, [:pointer, :int], :void
+  attach_function :cdCanvasVectorFontSize, [:pointer, :double, :double], :void
+  attach_function :cdCanvasVectorFont, [:pointer, :string], :string
+  # TODO: Get functions
+
+  # --- client images
+
+  # --- server images
+
+  # -- colour functions
+
+  attach_function :cdEncodeColor, [:int, :int, :int], :long
+end

data/lib/plain/iupcontrolslib.rb

@@ -0,0 +1,24 @@
+module ControlsLib # :nodoc:
+  extend FFI::Library
+
+  case RbConfig::CONFIG['host_os']
+    #  when /mswin|mingw/
+    #    ffi_lib 'lib/library/iupcontrols.dll'
+  when /linux|cygwin/
+    ffi_lib 'libiupcontrols'
+  else
+    raise Exception, 'iup libraries not found for this platform'
+  end
+
+  attach_function :IupControlsOpen, [], :int
+
+  # -- additional
+  #  attach_function :IupCells, [], :pointer
+  attach_function :IupColorbar, [], :pointer
+  #  attach_function :IupColorBrowser, [], :pointer
+  attach_function :IupDial, [:string], :pointer
+  attach_function :IupMatrix, [:string], :pointer
+  #  attach_function :IupMatrixList, [], :pointer
+  #  attach_function :IupMatrixEx, [], :pointer
+  #  attach_function :IupWebBrowser, [], :pointer
+end

data/lib/plain/iupimglib.rb

@@ -0,0 +1,14 @@
+module ImgLib # :nodoc:
+  extend FFI::Library
+
+  case RbConfig::CONFIG['host_os']
+  when /mswin|mingw/
+    ffi_lib 'lib/library/iupimglib.lib'
+  when /linux|cygwin/
+    ffi_lib 'libiupimglib'
+  else
+    raise Exception, 'iup libraries not found for this platform'
+  end
+
+  attach_function :IupImageLibOpen, [], :void
+end

data/lib/plain/iupimlib.rb

@@ -0,0 +1,16 @@
+module ImLib # :nodoc:
+  extend FFI::Library
+
+  case RbConfig::CONFIG['host_os']
+#  when /mswin|mingw/
+#    ffi_lib 'lib/library/iup.dll'
+  when /linux|cygwin/
+    ffi_lib 'libiupim'
+  else
+    raise Exception, 'iup libraries not found for this platform'
+  end
+
+  attach_function :IupLoadImage, [:string], :pointer
+  attach_function :IupSaveImage, [:string, :string], :int
+
+end