IUP Metadata and Code Generators

June 22, 2021 ยท View on GitHub

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

DataTypeDescription
UnknownNot mapped yet
VoidCall-style attribute, with no argument.
StringC-style null terminated string attribute
BooleanC-style 32bits integer boolean 1 or 0
IntC-style 32bits signed integer
FloatC-style 32bits signed float
DoubleC-style 64bits signed float
RefIntBy ref (address of) a 32bits signed integer
Char8bits char
HandlePointer to a IUP element, See HandleType property if a well-known class, otherwise it can be any IUP element.
VoidPtrC-style *void pointer
CanvasPointer to IUP's Icanvas structure

Formats for string attributes

DataFormatDescription
BinaryThis value may be not a string, see DataType for propper binary representation
HandleNameString containing a HandleName
DateString "TODAY" or a date formated as "yyyy/MM/dd"
SizeString formatted as "widhtxheight", both parts are int and optional.
MarginString formatted as "horizxvert", both parts are int and required
DialogSizeString 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.
AlignmentString formatted as "HAlignment:VAlignment", where HAlignment can be "ALEFT", "ACENTER", "ARIGHT" and VAlignment can be "ATOP", "ACENTER", "ABOTTOM".
LinColPosString formatted as "lin,col", both parts are int and required
XYPosString formatted as "x,y", both parts are int and required
RangeString formatted as "begin,end", both parts are int and required
FloatRangeString formatted as "begin,end", both parts are float and required
RgbString formated with three or four values "255 255 255" representing the RGB or RGBA components
RectString formated with four coordinates "x,y,x + width,y + height", all parts are int and required
SelectionString "NONE", "ALL" or formated as "startlin,startcol:endlin,endcol", all parts are int and required.
MdiActivateString "NEXT", "PREVIOUS" or a HandleName
EnumOne 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