Window.create
From codeTank
Contents |
Description
window.create will create a window with the specified parameters. Afterwards, it is expected that you pump the messages to the newly created window using window.pumpmessages.
Arguments
window.create() -- create a default window window.create(config_table) -- most robust method for creating a window (recommended) window.create(title) window.create(title, x, y) window.create(title, x, y, width, height) window.create(title, x, y, width, height, resize)
config_table allows the most flexibility, and is the most verbose, which is why it's the recommended way to create windows. Please see the explanation below for more information on this parameter.
title is what's displayed in the title bar (default "Brain Damage Window"). x and y are the screen coordinates of the upper-left corner of the window. width and height are the pixel dimensions of the client area of the window. resize is a boolean, which determines if the window can be resized or not (default true).
The default values for x, y, width, and height are to use the defaults that Microsoft Windows decides on. If x and y aren't specified, then Microsoft Windows will place the window where it sees fit. If width and height aren't specified, then Microsoft Windows will set the width and height as it sees fit.
Returns
window.create will return the window object on success, or nil on failure, along with a second return value of a string with the error message.
The window object is a table with inherited functions and features from the object table. Most importantly, it inherits the event handling functions that object defines.
If you provide a config_table, then the return value copies this table along with the other settings and functions that are set for windows. If you don't provide a config_table, then a new object is created, and populated with the correct data.
Below is the structure of the returned object. Please note that if you use the default values for x, y, width or height, then Microsoft Windows will calculate the values, and the returned table will contain the results. Note that all measurements are in pixels.
return { everything in object table, -- inherit functions from object table everything in config_table, -- inherit values from config_table -- (possibly overwriting object table stuff) -- below is object data, which might possibly overwrite config_table values -- (except for the data table, which is preserved) hwnd = userdata, -- the actual window title = string, -- the text displayed in the title bar x = integer, -- the x position of the window's left side y = integer, -- the y position of the window's top side width = integer, -- the width of the client area height = integer, -- the height of the client area resize = boolean, -- can the window be resized? totalwidth = integer, -- the width of the entire window totalheight = integer, -- the height of the entire window settimer = function, -- will set a recurring timer invalidate = function, -- will invalidate client area settitle = function, -- will set the window title gettitle = function, -- will get the window title close = function, -- will close the window destroy = function, -- will destroy the window setposition = function, -- will set window's position getposition = function, -- will get the window's position createbutton = function, -- will create a button inside this window createedit = function, -- will create an edit control inside this window createstatic = function, -- will create a static label inside this window children = table, -- will hold children information, if any are created later data = table, -- a spot reserved for user data that will never be touched }
Explanation of Creation Process and config_table
It is recommended that you create your window using the config_table interface. Here is an example window created using that interface:
wnd = window.create{ title = "Hello World", x = 10, y = 10, width = 300, height = 200, resize = false, onclick = function(wnd, mse) alert("You clicked at (" .. mse.x .. ", " .. mse.y .. ")") end, } while window.getcount() > 0 do window.pumpmessages() end
Please notice that window.create is called with braces instead of parentheses, which tells Lua to pass one table to the function, instead of a parameter list.
Using this format, you can see how it cleans up the code, and makes things more obvious from a programming stand point. In the example, you can also see that onclick is defined. Remember that the window object copies the config_table - so the window object will actually have a copy of the onclick function inside of it. When the event is fired, it will find that function in the window object, and fire the event with the mse parameter.
If you use the parameter list instead of config_table, then you cannot add event handlers until after the window has been created. Below is an equivalent script, which is uglier:
wnd = window.create("Hello World", 10, 10, 300, 200, false) wnd.onclick = function(wnd, mse) alert("You clicked at (" .. mse.x .. ", " .. mse.y .. ")") end while window.getcount() > 0 do window.pumpmessages() end
Both of these scripts are legal, and do ALMOST exactly the same thing. There is one important difference though. The onclick event is not set until AFTER the window is created. For a simple program like this, it really doesn't matter. However, for the oncreate event, this is a very important distinction.
You CANNOT capture the oncreate event without using a config_table. This is because the oncreate event is fired when the window is actually being created. If you use the config_table approach, then the oncreate function will be copied over to the window object before the window is created, and will therefore capture the oncreate event. If you try to set the oncreate function after the window is created, then it's too late - you already missed the event.
It's for these reasons I recommend using the config_table when you create windows. It looks nicer, and it has more features available.
Example
r = 0 g = 0 b = 0 math.randomseed() wnd = window.create{ title = "Colors", width = 400, height = 300, oncreate = function(wnd, none) wnd:settimer(1, 1) end, onpaint = function(wnd, pnt) if (math.random(3) == 1) then r = (r + math.random(5)) % 256 elseif (math.random(2) == 1) then g = (g + math.random(5)) % 256 else b = (b + math.random(5)) % 256 end pnt:rectangle(0, 0, wnd.width, wnd.height, false, rgb(r, g, b)) end, ontimer = function(wnd, tmr) wnd:invalidate(false) end, } while window.getcount() > 0 do window.pumpmessages() end
