EgoWiki > Documentation > MakingZippyObjects > ZippyGuiObjects	EgoWiki webs: Main | TWiki | Know | Sandbox
	Documentation . { Changes | Index | Search | Go }

GUI Scripting in Zippy

This document describes the GuiObject class and the Texture function. Currently this functionality is only available via the testgui program. This program runs guitest.lua at the root of the Zippy distribution and enters an event loop until the user presses <Escape>.

Note: The implementation for this interface will be available in releases from 0.0.4 onwards. This implementation is in a very early stage, so you should expect it to change several times before it stabilizes

The GuiObject Class

GUIs may be scripted in Lua by creating a number of objects that handle SDL events from the user and use them to update their own state, the state of the game, and the state of other objects. These objects are all instances of the class GuiObject (or one of its derivatives). See the discussion on ZippyClasses for detailed information about Zippy's class implementation.

GuiObject Methods and Fields

GuiObject()

This is the constructor for GuiObjects. A new GuiObject has no position, is not drawn on the screen, and receives no event notifications.

GuiObject:show()

Calling this method will add the object to the list of active objects and direct the engine to call the draw event handler whenever the screen is refreshed. See ZippyGuiObjects#EventHandlers for details.

GuiObject:hide()

Calling this method removes the object from the list of active objects (preventing it from receiving any event notifications) and prevents its draw handler from being called when the screen is refreshed.

GuiObject:set_position(left, top, right, bottom)

Sets the position of the object so its left edge is left pixels from the left edge of the screen, and likewise for the top, right, and bottom edges of the object. This should be called at least once before the object is drawn for the first time.

GuiObject:focus()

Causes the object to receive all of the keyboard events from the user via the key_event handler (See ZippyGuiObjects#EventHandlers). Only one object may have focus at any given time, so this function will automatically cause the object that is in focus currently to become out of focus.

GuiObject:draw_outline()

Renders the object as a strip of four lines along the four edges of the object. Currently there is no way to specify the line color. This should be called from within the draw handler of the object (see ZippyGuiObjects#EventHandlers).

GuiObject:draw_textured(texture)

If texture is a valid texture created by the Texture() function (see ZippyGuiObjects#GuiTextures), this will render the object as a textured quadrilateral covering the entire area of the object.

GuiObject:draw_text(text)

If text is a string, this function renders the string in the standard Egoboo font within the area of the object, starting from the upper left corner. Newlines are interpreted naturally, and lines that extend past the right-hand boundary of the object will be wrapped. If the text extends below the bottom edge of the object, it will be clipped at that edge. Currently "~" is used to represent a tab, but the standard "\t" will also work, and this feature may change in the near future.

object.listen_to_mouse

This is a boolean field that determines whether the object receives events from the mouse (see below).

Event Handlers

Event handlers are methods of instances of GuiObject that are called when certain events occur. GuiObject defines default handlers for each event, but these handlers take no action whatsoever. The following prototypes should be followed when defining handlers for derived types.

draw(self)

This method should issue commands to draw a visual representation of the object on the screen. It is called for every active object whenver the screen is to be refreshed.

key_event(self, key, direction, mod)

This method is called when self has keyboard focus and key is pressed (direction == "down") or released (direction == "up") with mod. See ZippyKeysyms for information about how to use key and mod to determine which key was pressed, and with which modifiers. This method should return true if the object handles the event (this will usually result in a screen refresh).

mouse_event(self, event, x, y)

This method is called when self.listen_to_mouse is true and some mouse event occurs at location , which is gauranteed to be within the boundaries of self (with one exception, read on). Possible values of event are:

"down": A button was pressed at . "up": A button was released at . "motion": The cursor moved to within the object. "enter": The cursor moved into the object at . "exit": The cursor moved out of the object, and is now at (which is outside of the object).

update(self)

This method is called on every game update (not currently used).

Textures

The following method creates a texture from one or two bitmaps:

Texture(filename, { alpha_filename | color_key })

Returns a texture created from the bitmap stored in filename, which must be a Windows bitmap file. If alpha_filename is provided and is the filename of a grayscale bitmap in Windows bitmap format, the texture created will use that grayscale image as an alpha channel. If color_key is provided instead, it must be a color; the resultant texture will have an alpha of zero wherever that color appears in the source image.

-- ElminI - 07 Jan 2005