NkGenie - frame

From Riftui Wiki

Jump to: navigation, search

The frame widget comes in two forms:

Both are created using the nkExtFrame widget type with the comand UI.CreateFrame('nkExtFrame', name, parent, {}). The standard frame widget is an exact duplicate of the standard Rift API frame. The main benefit of using the nkGenie implementation is less lines of code by using the 'update' method.

As soon as you need a bordered frame the widget makes your life as a developper much easier. The only thing you need to provide is the border color parameter. The widget acts on this and will create the advanced bordered version of the widget.

Standard frame

UI.CreateFrame('nkExtFrame', name, parent, { color = { body = '000000' } })

Frame with border

UI.CreateFrame('nkExtFrame', name, parent, { color = { body = '000000', border = 'FFFFFF' } })

Contents

Supported parameters

The following parameters are supported for UI:CreateFrame() and frame:update()

Parameter Description
width The width of the frame
height The height of the frame
anchors The position of the frame. See How to position widgets
callBack An optional function which is executed if the player left clicks on the frame object.

For example: callBack = function() print('hello') end

If you want to prevent 'clickthrough' on a frame you can set an empty function using this parameter: callBack = function() end

color The colors of the frame. See below for more information.
layer The layer of the frame (vs. parent)
strata The stara of the frame
visible The visibility state of the frame (true, false)
template The template to use when building the frame. See Using templates to reduce number of parameters

Supported Methods

getElement(innerFlag)

This method retrieves the underlying Rift UI element. Normally you'd need this method if you want to anchor something to this frame. For a bordered nkGenie frame you can specify if you want to retrieve the border or body frame by supplying the parameter innerFlag. True (or not supplying the parameter) will get the body frame and false will get the border frame. For a non bordered frame the parameter is ignored.

SetEvent(event, function)

You can supply a LeftClick function at creation time using the callBack parameter. However if you want to set any other event (or be consistent when setting events) you can use the SetEvent method. The method takes two parameters: the event to set and the function to execute when event fires. Supported events are:

The parameter function is provided as follows: function () ... end

frame:SetEvent('LeftClick', function() print ('hello') end)

ClearEvent(event)

If you need to delete an event you can do so using this method. You only need to supply the event name to remove. This parameter supports the same values as the first parameter of :SetEvent().

SetMacro (event, macro)

This method allows you to bind a Rift macro to the frame. The method takes two parameters: the event to set and the macro to execute when event fires. Supported events are:

The parameter macro is built like any ingame macro. Use '\n' to specify multi-line macros.

frame:SetMacro('LeftClick', '\s hello\n\s world')

You will have follow the secure frame model of Rift in order to be able to bind a macro to a frame. Please see the API documentation for more information on the secure frame model of Rift.

SetAlpha(value)

The alpha level of the frame can be set by using this method. Of course you can achieve the same using the :update() method, but sometimes the code is easier to read if you use the :SetAlpha() method instead of update() for just changing the alpha level of a frame. In case of a bordered frame this function will change the alpha level of the border frame. Due to the way the Rift API works this will also change the alpha level of the body frame. So if you want to set both individually you'd need to use the update() method.

GetWidth()

If you have set the width of a frame widget at creation time or using the update() method you can access the width of the frame directly using widget.width. This will not work for frame which's width is dynamically done using the two anchors. If you'd need to know the width of these types of frames you'd want to use :GetWidth().

GetHeight()

If you have set the height of a frame widget at creation time or using the update() method you can access the height of the frame directly using widget.height. This will not work for frame which's height is dynamically done using the two anchors. If you'd need to know the height of these types of frames you'd want to use :GetHeight().

Other supported methods

Method Description
ClearAnchors() Clears all anchors of a frame
GetVisible() Retrieve the visibility status of a frame object. Returns true or false
SetVisible(flag) Sets the visibility status of a frame object. Valid parameter values are true and false
SetParent(parent) Changes the parent of a frame object. The parameter parent is the new parent Rift API ui element. Use with care!
SetSecureMode(mode) Sets the secure mode of the frame. Valid parameter values are true and false
SetStrata(strata) Sets the strata of the frame. See the Rift API documentation for valid strata values.
SetLayer(layer) Sets the layer of the frame versus it's parent.
GetAlpha() Gets the alpha level of the frame. In case of a bordered frame this will get the alpha level of the border element.

Frame colorization

The color of a frame is specified through the color parameter. This parameter is provided as a LUA table: color = {}. You have to supply at least the body parameter to specify the main color: color = { body = HEX CODE }. All other parameters are optional. See How to specifiy colors for more information on the format of the color parameter.

The alpha level of the widget is also controlled by the color parameter. In case of a bordered frame you can specify the alpha level of border and inner individually. However as the Rift API does not really support bordered frames you cannot create a frame with invisible inner part. Setting the body alpha level to 0 will simply show the a rectangle colorized with the color of the border.

Parameter Description
body Mandatory main color of the frame. In case of a bordered frame this is the fill color.
border Optional border color. If specified this will instruct nkGenie to create a bordered frame.
alphaborder The alpha level of the border specified as single precision value: from 0.0 to 1.0.
alphabody The alpha level of the body specified as single precision value: from 0.0 to 1.0.
Personal tools
Namespaces
Variants
Actions
Menu
Wiki
Toolbox