Main
Language
Runtime
Tools
FAQs
Changes
Download
Licence
cheesy

Module gui

The gui module supports the creation of simple GUIs and dialog boxes.

To use the gui module, you can either execute a script with idlew.exe (this is the GUI-enabled version of the Idle interpreter) which preloads this module or you can use the console version of the interpreter, idle.exe. In the latter case, module gui has to be loaded explicitly by calling require( ):

require('gui')  -- no harm done if this called from idlew.exe

In both cases, all functions, classes and constants are available under the gui prefix.

Although most of the higher-level functions do not directly use handles and other Windows API paraphernalia, the gui module is a relatively thin wrapper around the Microsoft API, so some knowledge about the way Windows works (or is supposed to work) is probably required: you should have a rough idea what messages, window handles and the like mean.

The gui module supports two different styles of programming: a simple procedural mode where you create the main window and its controls yourself. There is also a slightly more advanced mode where all the GUI elements (buttons, listboxes, edit fields etc) are mapped onto classes (see the Idle standard module Class).

The following control types are currently supported:

The gui module also supports menus and accelerator tables, dragging and dropping of files, popup menus and common dialog boxes to choose fonts and to open or save files and to select folders.

Back to the main Idle Runtime library documentation.

Defaults
top of page

gui.defaults is a table with a few global pre-defined values. They can be changed but doing so after creating and before closing a dialog box may have unpredictable side effects. In other words, change them only when no GUI or dialog box is currently open.

Creating a dialog box
top of page

There are two ways to create a dialog box. The first is a simple procedural interface which in outline looks like this:

require('gui')  -- only required for idle.exe not for idlew.exe
__INCLUDE('guiDefaults.inc')  -- a few useful definitions

local function evHandler(g,id,notf,hwnd)  -- event handler
  if notf<0 then return nil end  -- ignore notification codes < 0
  if id==30000 and notf==gui.BN.CLICKED then gui.MessageBox('Later?')
  elseif id==30001 and notf==gui.BN.CLICKED then gui.destroyGui()
  elseif id==2 then gui.destroyGui()
  else return nil end
  return 0
end

gui.createGui('simplest gui',{eventHandler=evHandler},51,8)
--             class,   caption,     id,   x, y, dx,dy,style
gui.addControl('Button','Do not end',30000,24, 5, 1, 1,GD.PUSHBUTTON)
gui.addControl('Button','End',       30001,24, 5,26, 1,GD.DEFPUSHBUTTON)
gui.displayGui()  -- show it
gui.mainloop()

The event handler deals with significant events while the dialog box and its controls are shown. After creating a dialog box with gui.createGui() and adding controls with calls to gui.addControl() the dialog box is displayed and the main message loop entered. This loop runs until the dialog box is closed, either explicitly by calling gui.destroyGui(), eg after a button is clicked, or implicitly by clicking the close icon in the dialog box titlebar (this latter way of closing a dialog box is handled internally).

The second way to create dialog boxes is via the object-oriented interface. First you define a table structure which contains all required values (size, styles, optional menu and accelerator table, controls etc) like this:

require('gui')
__INCLUDE('guiDefaults.inc')

local testgui={title='testgui',cx=67,cy=80,style=GD.SIZEGUI,
  menu={{name='&File',id=1000,{'file1','file2','file3'}},{name='&Edit',id=2000,{'edit1','edit2','edit3'}},{name='&Help',id=9999}},
  accel={{key='^a',id=9999},{key='!F12',id=1000}},
  controls={
  -- classname, control name,  caption,            width,height,x,   y    window style,          extended window style
    {gui.Static,               title='&Name:',     cx=16,cy=4,  x=1, y=2},
    {gui.Input, name='i_Name', title='Enter Name', cx=44,cy=5,  x=21,y=1, style=GD.INPUT,        xstyle=gui.RESIZE.WIDTH},
    {gui.Static,               title='&Biography:',cx=16,cy=4,  x=1, y=7},
    {gui.Edit,  name='e_Bio',  title='End1',       cx=64,cy=54, x=1, y=13,style=GD.EDIT,         xstyle=_OR(gui.RESIZE.WIDTH,gui.RESIZE.HEIGHT)},
    {gui.Button,name='b_Alive',title='&Alive',     cx=16,cy=5,  x=1, y=69,style=GD.TSTATEBOX,    xstyle=gui.RESIZE.TOP},
    {gui.Button,name='b_Clear',title='&Clear',     cx=16,cy=5,  x=21,y=69,style=GD.PUSHBUTTON,   xstyle=gui.RESIZE.TOP},
    {gui.Button,name='b_End',  title='&End',       cx=16,cy=5,  x=41,y=69,style=GD.DEFPUSHBUTTON,xstyle=gui.RESIZE.TOP}
  }
}

Next the dialog box and all its elements are created and finally the dialog box is displayed and the main loop is called:

-- Create gui window, register menu and accelerator table and create all controls
gui.Gui(testgui)
-- display dialog box
testgui:displayGui()
-- and run main loop
gui.mainloop()

See the included example programs for more details.

Functions
top of page

gui.acceptDragFiles(cb,gui)

gui.addAccel(acc,gui)
top of page

gui.addControl(class,title,id,cx,cy,x,y,style,xstyle,gui)

gui.addMenu(menu,gui)
top of page

Menu flags:

gui.browseForFolder(dir,flags,title)
top of page

browseForFolder( ) flags:

browseForFolder( ) standard folder constants:

gui.chooseFont(face,height,flags)
top of page

chooseFont( ) flags:

gui.controlControl(id,what,cx,cy,x,y,gui)
top of page

gui.controlFromHwnd(hwnd,gui)

gui.controlWindow(hwnd,what,cx,cy,x,y)
top of page

gui.createFont(face,height,bold,ital,under)

gui.createGui(title,handlers,cx,cy,x,y,style,xstyle)
top of page

gui.deleteObject(o)

gui.destroyGui(gui)
top of page

gui.displayGui(gui)

gui.getDC(hwnd)
top of page

gui.getDlgCtrlID(hwnd)

gui.getDlgItem(hwnd,id)
top of page

gui.getStockObject(o)

gui.getSystemMetrics(sm)
top of page

System Metrics constants:

gui.getWindowLong(hwnd,off)
top of page

get/setWindowLong( ) flags:

gui.HIBYTE(w)
top of page

gui.HIWORD(l)

gui.LOBYTE(w)
top of page

gui.LOWORD(l)

gui.mainloop()
top of page

gui.MAKELONG(w1,w2)

gui.MAKEWORD(b1,b2)
top of page

gui.MessageBox(msg,title,flags)

Message Box constants:

ID button codes returned by MessageBox( ), also used in default dialog handling:

gui.MessageFmt(t,fmt,...)
top of page

gui.modifyMenu(id,what,gui)

gui.openFilename(dir,filename,flags,title,filters)
top of page

open/saveFilename( ) flags:

gui.peekloop()
top of page

gui.postWindowMessage(hwnd,msg,wp,lp)

gui.print(...)
top of page

gui.printf(fmt,...)

gui.registerHotkey(hk[,cb])
top of page

gui.resizeControls(w,h,gui)?

Control resize flags:

gui.saveFilename(dir,filename,flags,title,filters)
top of page

gui.sendControlMessage(id,msg,wp,lp,gui)

gui.sendWindowMessage(hwnd,msg,wp,lp)
top of page

gui.setGui(gui)

gui.setMinMaxInfo(minX,minY,maxX,maxY,gui)
top of page

gui.setTextColor(hDC,rgb)

gui.setWindowLong(hwnd,off,v)
top of page

gui.showPopupMenu(menu,x,y,id)

gui.steploop()
top of page

Class Gui
top of page

gui.Gui=g.Class:new('Gui')

Gui:setGui()
top of page

Gui:displayGui()

Gui:destroyGui()
top of page

Gui:hide()

Gui:show()
top of page

Gui:setText(s)

Gui:getText()
top of page

Gui:addControl(class,title,id,cx,cy,x,y,style,xstyle)

Gui:addMenu(menu)
top of page

Gui:addAccel(accel)

Gui:modifyMenu(id,what)
top of page

Gui:setMinMaxInfo(minX,minY,maxX,maxY)

Gui:resizeControls(w,h)
top of page

Gui:controlControl(id,what,cx,cy,x,y)

Gui:sendControlMessage(id,msg,wp,lp)
top of page

Gui:controlFromHwnd(hwnd)

Gui:acceptDragFiles(cb)
top of page

Class Control
top of page

gui.Control=g.Class:new('Control')

Control:sendMessage(msg,wp,lp)
top of page

Control:move(cx,cy,x,y)

Control:hide()
top of page

Control:show()

Control:enable()
top of page

Control:disable()

Control:destroy()
top of page

Control:focus()

Control:setText(s)
top of page

Control:getText()

Control:setColor(c)
top of page

Control:update()

Control:setRedraw(f)
top of page

Control:setFont(hf)

Control:clear()
top of page

Control:copy()

Control:cut()
top of page

Control:paste()

Control:undo()
top of page

Class Static
top of page

gui.Static=Control:new('Static')

Class Button
top of page

gui.Button=Control:new('Button')

Button:click()
top of page

Button:getCheck()

Button:isChecked()
top of page

Button:setCheck(chk)

Class Input
top of page

gui.Input=Control:new('Input')

Input:setTextLimit(n)
top of page

Input:isModified()

Input:setModified(m)
top of page

Input:canUndo()

Input:getSel()
top of page

Input:replaceSel(s,undo)

Input:setPasswordChar(ch)
top of page

Input:setReadOnly(ro)

Input:setSel(st,en)
top of page

Class Edit
top of page

gui.Edit=Input:new('Edit')

Edit:getLineCount()
top of page

Edit:getLine(n)

Class Listbox
top of page

gui.Listbox=Control:new('Listbox')

Listbox:reset()
top of page

Listbox:addString(s)

Listbox:deleteString(n)
top of page

Listbox:getText(n)

Listbox:getCount()
top of page

Listbox:getSelCount()

Listbox:getSel()
top of page

Class Combobox
top of page

gui.Combobox=Control:new('Combobox')

Combobox:reset()
top of page

Combobox:addString(s)

Combobox:deleteString(n)
top of page

Combobox:getLBText(n)

Combobox:getCount()
top of page

Combobox:getSel()

Class Richedit
top of page

gui.Richedit=Edit:new('Richedit')

Richedit:getSel()
top of page

Richedit:setSel(s,e)

Richedit:getSelText()
top of page

Class Datepicker
top of page

gui.Datepicker=Control:new('Datepicker')

Datepicker:setText(s,t,u)
top of page

Datepicker:setSystemTime(s,t,u)

Datepicker:getSystemTime()
top of page

Class Listview
top of page

gui.Listview=Control:new('Listview')

Listview:reset()
top of page

Listview:setXstyle(xs)

Listview:deleteItem(n)
top of page

Listview:ensureVisible(n)

Listview:getCount()
top of page

Listview:getSelCount()

Listview:getItem(n,sn)
top of page

Listview:getItemState(n)

Listview:insertColumn(col,len,fmt,n)
top of page

Listview:insertColumns(cols)

Listview:insertItem(it,n)
top of page

Listview:insertItems(its)

Listview:setCount(n)
top of page

Listview:setItem(it,n,sn)

Listview:setItemState(n,sel,chk)
top of page

Class Progressbar
top of page

gui.Progressbar=Control:new('Progressbar')

Progressbar:getPos()
top of page

Progressbar:setPos(n)

Progressbar:getRange()
top of page

Progressbar:setRange(lo,hi)

Progressbar:setStep(n)
top of page

Progressbar:step()

Class Statusbar
top of page

gui.Statusbar=Control:new('Statusbar')

Statusbar:setText(s,n)
top of page

Statusbar:getText(n)

Statusbar:setParts(t)
top of page

Class Trackbar
top of page

gui.Trackbar=Control:new('Trackbar')

Trackbar:getPos()
top of page

Trackbar:setPos(n)

Trackbar:getRange()
top of page

Trackbar:setRange(lo,hi)

Trackbar:setTicFreq(n)
top of page

Class Treeview
top of page

gui.Treeview=Control:new('Treeview')

Treeview:reset()
top of page

Treeview:deleteItem(tr)

Treeview:ensureVisible(tr)
top of page

Treeview:expand(tr,fl)

Treeview:getCount()
top of page

Treeview:getItem(tr)

Treeview:getItemState(tr)
top of page

Treeview:insertItem(tri,par,pos)

Treeview:selectItem(tr)
top of page

Treeview:setIndent(n)

Treeview:setItemState(tr,bold,chk)
top of page

Treeview:sortChildren(tr,fl)

Messages
top of page

The following lists show the currently supported messages, first the generic messages which are valid for all controls, and then the control specific messages. All messages are stored in separate tables inside module gui such that you would use gui.WM.CLOSE if you wanted to refer to the Windows message WM_CLOSE. As long as you use the class-based interface, there almost never a need to resort to these messages.

Window Messages (generic)
top of page

Dialog Messages (for dialog boxes)
top of page

Button Messages
top of page

Combobox Messages
top of page

Datetime Picker Messages
top of page

Edit Messages
top of page

Listbox Messages
top of page

Listview Messages
top of page

Progressbar Messages
top of page

Statusbar Messages
top of page

Trackbar Messages
top of page

Treeview Messages
top of page

Styles
top of page

The following lists show the currently supported window styles, first the generic styles which are valid for all controls, and then the control specific styles. All styles are stored in separate tables inside module gui such that you would use gui.WS.CHILD if you wanted to refer to the style WS_STYLE.

Window Styles (generic)
top of page

Window Styles (extended)
top of page

Dialog Styles
top of page

Button Styles
top of page

Combobox Styles
top of page

Common Control Styles (generic for common controls)
top of page

Datetime Picker Styles
top of page

Edit Styles
top of page

Listbox Styles
top of page

Listview Styles
top of page

Listview Styles (extended)
top of page

Progressbar Styles
top of page

Static Styles
top of page

Trackbar Styles
top of page

Treeview Styles
top of page

Notifications and States
top of page

These are a few predefined tables with control notifications and states. To use a notification like BN_CLICKED you would refer to gui.BN.CLICKED.

Button Notifications and States
top of page

Combobox Notifications
top of page

Edit Notifications
top of page

Listbox Notifications
top of page

Listview Notifications
top of page

Scrollbar Notifications
top of page

Static Notifications
top of page

Treeview Notifications
top of page

Common control notifications (generic for all common controls)
top of page

Common control alignment
top of page

Treeview item position
top of page


$$ built from IdleGui.txt d106963c4f77 Mon Sep 27 13:27:10 2010 +0000 thomasl $$