Window.create

From codeTank

Jump to: navigation, search

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

See Also

Retrieved from "http://codetank.com/wiki/index.php/Window.create"
Personal tools