IUP Metadata and Code Generators

WIP - Work in Progress

IUP Toolkit is a solid and well-proven portable GUI toolkit that exposes a simple raw C API, so it can be used via FFI.

More information can be found at https://webserver2.tecgraf.puc-rio.br/iup/

This project aims to collect rich metadata information about IUP's elements, enabling code-gen tools to create type-checked bindings for any programing language.

Type-checked

As IUP's API is largely based on key-value string attributes, this metadata can be useful to improve the developer experience through a fully typed and idiomatic API by removing the need for string based actions.

Metadata:

  {
    "ClassName": "dialog",
    "Name": "Dialog",
    "Attributes": [
      {
        "AttributeName": "TITLE",
        "Name": "Title",
        "DataType": "String",
      },
      {
        "AttributeName": "DIALOGFRAME",
        "Name": "DialogFrame",
        "DataType": "Boolean",
      }
    ]
  },
  {
    "ClassName": "button",
    "Name": "Button",
    "Attributes": [
      {
        "AttributeName": "PADDING",
        "Name": "Padding",
        "DataType": "String",
        "DataFormat": "Size",
        "Default": "0x0"
      },
      {
        "AttributeName": "IMAGEPOSITION",
        "Name": "ImagePosition",
        "DataType": "String",
        "DataFormat": "Enum",
        "EnumValues": [
          {
            "Name": "Left",
            "StrValue": "LEFT",
          },
          {
            "Name": "Right",
            "StrValue": "RIGHT",
          },
          {
            "Name": "Bottom",
            "StrValue": "BOTTOM",
          },
          {
            "Name": "Top",
            "StrValue": "TOP",
          }
        ],
        "Default": "LEFT",
      }
    ]
  }

Original IUP API in C:

Ihandle* dlg = IupDialog(NULL);
IupSetAttribute(dlg, "TITLE", "Find");
IupSetAttribute(dlg, "DIALOGFRAME", "Yes");

Ihandle* bt_close = IupButton("Close", NULL);
IupSetCallback(bt_close, "IMAGEPOSITION", "LEFT");
IupSetAttribute(bt_close, "PADDING", "10x2");

Type-checked Zig API generated from metadata:

var dlg = Dialog.init();
dlg.setTitle("Find");
dlg.setDialogFrame(true);

var bt_close = Button.init();
bt_close.setTitle("Close");
bt_close.setImagePosition(.Left);
bt_close.setPadding(10, 2);

Documentation

Additionally, this project also provides documentation snippets extracted directly from the official HTML page, allowing the generated code to use the target programing language documentation conventions and IDE convenience tools.

{
"Documentation": "SIZE (non inheritable): Dialogs size. Additionally the following values can also be defined for width and/or height: \"FULL\": Defines the dialogs width (or height) equal to the screen's width (or height) \"HALF\": Defines the dialogs width (or height) equal to half the screen's width (or height) \"THIRD\": Defines the dialogs width (or height) equal to 1/3 the screen's width (or height) \"QUARTER\": Defines the dialogs width (or height) equal to 1/4 of the screen's width (or height) \"EIGHTH\": Defines the dialogs width (or height) equal to 1/8 of the screen's width (or height)",
"AttributeName": "SIZE",
"Name": "Size",
"DataType": "String",
"DataFormat": "DialogSize",
}

Automatically generated documentation in Zig code:

/// 
/// SIZE (non inheritable): Dialogs size.
/// Additionally the following values can also be defined for width and/or
/// height: "FULL": Defines the dialogs width (or height) equal to the screen's
/// width (or height) "HALF": Defines the dialogs width (or height) equal to
/// half the screen's width (or height) "THIRD": Defines the dialogs width (or
/// height) equal to 1/3 the screen's width (or height) "QUARTER": Defines the
/// dialogs width (or height) equal to 1/4 of the screen's width (or height)
/// "EIGHTH": Defines the dialogs width (or height) equal to 1/8 of the
/// screen's width (or height)
pub fn setSize(self: *Self, width: ?iup.ScreenSize, height: ?iup.ScreenSize) void {
	// ...
}

JSON Metadata

All metadata are available in JSON format and can be consumed by any tool independently of this project.

Download: iup.json

Data types

DataType	Description
Unknown	Not mapped yet
Void	Call-style attribute, with no argument.
String	C-style null terminated string attribute
Boolean	C-style 32bits integer boolean 1 or 0
Int	C-style 32bits signed integer
Float	C-style 32bits signed float
Double	C-style 64bits signed float
RefInt	By ref (address of) a 32bits signed integer
Char	8bits char
Handle	Pointer to a IUP element, See HandleType property if a well-known class, otherwise it can be any IUP element.
VoidPtr	C-style *void pointer
Canvas	Pointer to IUP's Icanvas structure

Formats for string attributes

DataFormat	Description
Binary	This value may be not a string, see DataType for propper binary representation
HandleName	String containing a HandleName
Date	String "TODAY" or a date formated as "yyyy/MM/dd"
Size	String formatted as "widhtxheight", both parts are int and optional.
Margin	String formatted as "horizxvert", both parts are int and required
DialogSize	String formatted as "ScaleWidthxScaleHeight", where ScaleWidth can be "FULL", "HALF", "THIRD", "QUARTER", "EIGHTH" or absolute width integer value and ScaleHeight can be "FULL", "HALF", "THIRD", "QUARTER", "EIGHTH" or absolute height integer value.
Alignment	String formatted as "HAlignment:VAlignment", where HAlignment can be "ALEFT", "ACENTER", "ARIGHT" and VAlignment can be "ATOP", "ACENTER", "ABOTTOM".
LinColPos	String formatted as "lin,col", both parts are int and required
XYPos	String formatted as "x,y", both parts are int and required
Range	String formatted as "begin,end", both parts are int and required
FloatRange	String formatted as "begin,end", both parts are float and required
Rgb	String formated with three or four values "255 255 255" representing the RGB or RGBA components
Rect	String formated with four coordinates "x,y,x + width,y + height", all parts are int and required
Selection	String "NONE", "ALL" or formated as "startlin,startcol:endlin,endcol", all parts are int and required.
MdiActivate	String "NEXT", "PREVIOUS" or a HandleName
Enum	One of defined values in EnumValues.

IUP for Zig

For more information about using IUP on Zig, please visit IUP for Zig repository.

Pending work

• Review DataType and formating for several attributes.
• Metadata for Id and lin,col attributes (list items for example)
• Fix UPPERCASE converter algorithm (for example SCROLLTOPOS is rendered as ScrollTopOs instead of ScrollToPos)
• Add C# Code Generator
• Improve documentation extractor
• Add Linux support for metadata extraction

License

• The IUP Metadata Project is a free and unencumbered software released into the public domain. Plese visit unlicense.org for more details.

• IUP is a Tecgraf/PUC-Rio project licensed under the terms of the MIT license. Please visit https://www.tecgraf.puc-rio.br/iup/ for more details.