NkGenie - Text Field

From Riftui Wiki

Jump to: navigation, search

This widget is used for displaying an editable text field. It enhances the standard Rift API textfield element with a number of additional functionalities:

UI.CreateFrame('nkExtTextfield', name, parent, {})

Contents

Supported parameters

The following parameters are supported for UI:CreateFrame(). Due to the nature of this widget you cannot update it after creation using :update(). Only updating the visibility using the parameter 'visible' is supported by :update().

Parameter Description
width The width of the textfield widget
height The heightof the textfield widget
color The color settings of the textfield widget. See below for more information.
anchors The position of the texture. See How to position widgets
label An optional label to display in front of the textfield
labelwidth The width of the optional label. Only supply this if label is specified.
fontsize The fontsize of the optional label. Only supply this if label is specified.
value The initial value of the textfield. Can be text or numeric. A numeric value is automatically changed to text using tostring()
valuetype The type of value handled by the textfield. Can be set to 'number' to automatically change values to numeric.
func An optional function to call if the user hits ENTER. See below.
visible The visibility state of the text (true, false)

Supported Methods

getElement()

This method retrieves the underlying Rift UI element which in this case is actually the frame around the textfield.

GetLabel()

If you need to get the label (if specified at creation) of the textfield you can do so using this method. It will return the underlying text widget used to build the label.

getValue(getAsTextFlag)

This method retrieves the value of the textfield. Using the parameter you can specifiy if the returned value should be of type number (false) or string (true). If the parameter is not specified the method will return number if the parameter valuetype was set to 'number' at widgte creation time.

local textValue = textfield:getValue(true)

setValue(value)

This method will set the value of the textfield. You can supply a numeric value which will automatically transformed to text using tostring().

textfield:setValue('my value')

leave()

This method 'leave' the field user interface wise. You'd want to use this function if the addon's user interface is closed by the player. The Rift API will not automatically leave fields unless the player hits ESCAPE (or ENTER for nkExtTextfield). So if you do not leave the fields all keyboard entries will still go to the textfield the user was using while closing the addons ui.

textfield:leave()

The widget will automatically restore the original value of the textfield before entering as the user did not hit 'ENTER'.

select()

This method will set the focus to the textfield and select the whole text. This is very usefull if you would like to add some sort of export functionality to your addon. Simply set the value of the textfield and use :select() which will automatically select the content of the textfield. The user would then only need to hit CTRL+C to copy the text to the clipboard.

textfield:setValue('a lot of text')
textfield:select()

Other supported methods

Parameter Description
GetVisible() Returns the visibility of the textfield (true or false)
SetVisible(flag) Sets the visibility status of a textfield object. Valid parameter values are true and false

Call a function on ENTER key

Only if the user hits ENTER the new value of the textfield will be store. If the focus of the textfield is lost before the usre hits ENTER the original value will be restored. This is done to emulate a sort of cancelling function using ESCAPE.

You can tell the widget to execute a specific function if the user hits ENTER. This is done supplying a functoin as parameter func at creation time. For example:

local textfield = UI.CreateFrame('nkExtTextfield', 'myTextfield', UI.Parent, { value = 'myValue', color = { border = 'FFFFFF', body = '000000' }, width = 200, height = 20, func = function (value) print(value) end, 
anchors = {{ from = 'CENTER', object = UI.Parent, to = 'CENTER'}} })

The called function will get the value of the textfield as parameter. In case the parameter valuetype was set to 'number' it will supply the value as numeric value. If the textfield is empty the value 0 will be given as parameter.

Color definition

As the widget automatically creates a bordered frame around the textfield the color parameter is a bit more complicated. You will have to at least supply a value for body and border. For example:

local textfield = UI.CreateFrame('nkExtTextfield', 'myTextfield', UI.Parent, { color = { border = 'FFFFFF', body = '000000' }, width = 200, height = 20, anchors = {{ from = 'CENTER', object = UI.Parent, to = 'CENTER'}} })

If you'd like to highlight the border if the user enters the textfield you can do so by supplying an additiona color parameter 'focus'. The border of the frame will be set to this color if the user enters the field. As soon as the field is left the original border color will be set.

local textfield = UI.CreateFrame('nkExtTextfield', 'myTextfield', UI.Parent, { color = { border = '555555', body = '000000', focus = 'FFFFFF' }, width = 200, height = 20, anchors = {{ from = 'CENTER', object = UI.Parent, to = 'CENTER'}} })

In case you specifiy a label value to put a text label in front of the textfield you have to supply the color parameter 'label' in order to set the label color.

local textfield = UI.CreateFrame('nkExtTextfield', 'myTextfield', UI.Parent, { label = 'my label text', fontsize = 12, labelwidth = 100, color = { label = 'FFFFFF', border = '555555', body = '000000', focus = 'FFFFFF' }, 
width = 200, height = 20, anchors = {{ from = 'CENTER', object = UI.Parent, to = 'CENTER'}} })
Personal tools
Namespaces
Variants
Actions
Menu
Wiki
Toolbox