{"id":10707,"date":"2020-07-07T13:45:25","date_gmt":"2020-07-07T13:45:25","guid":{"rendered":"https:\/\/fhug.org.uk\/kb\/?post_type=kb_article&p=10707"},"modified":"2020-12-11T14:08:37","modified_gmt":"2020-12-11T14:08:37","slug":"iup-gui-builder-hints-and-tips","status":"publish","type":"kb_article","link":"https:\/\/www.fhug.org.uk\/kb\/kb-article\/iup-gui-builder-hints-and-tips\/","title":{"rendered":"IUP GUI Builder Hints and Tips"},"content":{"rendered":"

Introduction<\/h2>\n

IUP is a very powerful tool for building graphical user interfaces (GUI), but it’s fairly unforgiving and the IUP Documentation<\/a> is a little sparse especially when used with Lua. This page contains handy tips for the various options of dialogue building.<\/p>\n

When you are working on developing dialogues, always save before running, as if you get it wrong the dialogue will not appear and you will need to kill \u0192h<\/span><\/span>, using task manager to reset it.<\/p>\n

Dialogues are built using a fairly simple nested table containing the controls. A control can be any of a selection of items, including labels, input boxes, buttons and many others.<\/p>\n

Import Family Historian 7 note<\/h2>\n

For Plugins that use Lua to work correctly, you must include the following in your code before any IUP functionality is called:<\/p>\n

require(\"iuplua\");\r\niup.SetGlobal(\"CUSTOMQUITMESSAGE\",\"YES\");<\/pre>\n
Building Blocks<\/h2>\n
When building a dialogue, it’s best to sketch what you want on a sheet of paper, or a wireframe tool like\u00a0framebox.org<\/a>\u00a0or\u00a0balsamiq.com<\/a>, that way you can see the components you need to add.<\/p>\n
Here is an example dialogue, that was drawn in framebox:<\/p>\n
\"\"<\/p>\n
There are 9 visual controls on the dialogue, consisting of three labels, two single line text boxes, a multiline text box and three buttons.<\/p>\n
For each control you need to get information from, or interact with, you need to give them a name, but for other items you simply need to use the constructor.<\/p>\n
In your plugin you need to define the inner most items first; a bit like building a set of Russian dolls, you need to put the smallest ones together first.<\/p>\n
Creating Components Part 1<\/h2>\n
So lets define the 3 buttons:<\/p>\n
local btn_ok = iup.button{name=\"ok\", title=\"OK\",\r\n    action = function(self)\r\n        res=self.name\r\n        return iup.CLOSE\r\n    end}\r\nlocal btn_cancel = iup.button{name=\"cancel\", title=\"Cancel\",\r\n    action = function(self) res=self.name return iup.CLOSE\r\n    end}\r\nlocal btn_help = iup.button {name=\"help\", title=\"Help\",\r\n    action = function (self) iup.Message('Help','Help Goes Here')\r\n    end}<\/pre>\n
For each button we have defined the text for the button and the action to take when the button is pressed. Note that both the OK and Cancel button return\u00a0iup.CLOSE<\/code>\u00a0which will cause the dialog to close when the button is pressed, where as the Help button simply shows a message.<\/p>\n
If you prefer the actions for buttons can be defined separately using the following syntax:<\/p>\n
function btn_ok:action()\r\n\u00a0 \u00a0 res=self.name\r\n\u00a0 \u00a0 return iup.CLOSE\r\nend<\/pre>\n
Note the : in the function name, this means the first parameter for the function is the button itself and it can be accessed using\u00a0self<\/code>.<\/p>\n
When using the iup.dialog<\/code> to build a dialog you will need to use the\u00a0iup.vbox<\/code>\u00a0and\u00a0iup.hbox<\/code>\u00a0to arrange the controls on the dialog. In our example, we need to add a\u00a0vbox\u00a0<\/code>and three\u00a0hbox\u00a0<\/code>controls to control the layout, as shown below:<\/p>\n
\"\"<\/p>\n
Now we have 3 buttons we can add a little more code so we can display the dialog:<\/p>\n
local res\r\nlocal btn_ok = iup.button{name=\"ok\", title=\"OK\"}\r\n \r\nfunction btn_ok:action()\r\n    res=self.name\r\n    return iup.CLOSE\r\nend\r\nlocal btn_cancel = iup.button{name=\"cancel\", title=\"Cancel\", action = function (self) res=self.name return iup.CLOSE end}\r\nlocal btn_help = iup.button {name=\"help\", title=\"Help\", action = function (self) iup.Message('Help','Help Goes Here') end}\r\ndlg = iup.dialog{iup.hbox{btn_ok,btn_cancel,btn_help};\r\n                          title=\"Sample\",size=\"320x240\",padding='10px',gap='5px', \r\n                          close_cb=function() res='closed' return iup.CLOSE end}\r\ndlg:show()      -- Show the dialog\r\niup.MainLoop()  -- Process the dialog\r\nprint(res)      -- Print the pressed button<\/pre>\n
In the code above the\u00a0iup.dialog<\/code>\u00a0takes a table of tables and values which control the layout. The three buttons we created earlier are wrapped in\u00a0iup.hbox<\/code>\u00a0which means that they will be shown horizontally across the layout. If you were to simply include the three buttons without the\u00a0hbox\u00a0<\/code>they would all appear vertically one above the another.<\/p>\n
Note the semi-colon between the fields for the dialog and the values. This is common practice to show where the controls end and the values start, but could equally be a comma. Another readability trick is the use of\u00a0{}<\/code>\u00a0on their own to pass a table to a function\u00a0iup.button{}<\/code>\u00a0is the same as\u00a0iup.button({})<\/code><\/p>\n
The\u00a0close_cb<\/code>\u00a0function is called when the window close button is pressed. It’s good practice to use the return\u00a0iup.CLOSE<\/code>\u00a0when this is pressed and set some sort of return code, especially when more than one dialog is in use as not doing so can have unexpected results.<\/p>\n
If you run the code above in the editor, the dialog will display and you can press any of the buttons to see the results.<\/p>\n
Adding the Text Boxes<\/h2>\n
-------------------------------------------------------- Define Text Fields\r\nlocal inp_title = iup.text{name='title',expand='HORIZONTAL' }\r\nlocal inp_tags  = iup.text{name='tags',  expand='HORIZONTAL' }\r\nlocal inp_memo  = iup.text{name='memo',  expand='HORIZONTAL', multiline = 'YES',visiblelines = 10}<\/pre>\n
This code defines three input boxes, to keep it simple the expand option is used to tell the boxes to fill any available width on the dialog.<\/p>\n
The memo field has its\u00a0multiline\u00a0<\/code>option set to\u00a0YES\u00a0<\/code>and the number of lines set to\u00a010<\/code>.<\/p>\n
The\u00a0IUP\u00a0documentation always uses capital letters for attribute keywords e.g\u00a0MULTILINE<\/code> and their values e.g.\u00a0YES<\/code>, but in Lua you may use lowercase e.g.\u00a0multiline<\/code> and\u00a0yes<\/code> or mixed case e.g.\u00a0Multiline<\/code>\u00a0and\u00a0Yes<\/code>. But when these values are interrogated they will always be returned in UPPERCASE.<\/p>\n
Call back functions such as\u00a0action<\/code>\u00a0and\u00a0close_cb<\/code>\u00a0must always be in lowercase.<\/p>\n
The names following\u00a0iup<\/code>.\u00a0must use the correct letter case:<\/p>\n