NkGenie - grid

From Riftui Wiki

Jump to: navigation, search

The nkExtGrid widget is a rather complex widget. It's purpose is to display structured data in a tabled form. It's basically like a small spreadsheet. If you know the JavaScript dojo you'll find that the datagrid widget is quite similar to this one. Well that's where the idea for this widget comes from in the end.

Overall this widget's implementation is the same as all other nkGenie widgets. There are however some notable differences which are explained in the following documentation.

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

Contents

Supported parameters

The creation process of the widget is nothing more than creating an empty shell to be filled with life afterwards. You'll need to supply quite a number of parameters though.

Parameter Description
headerHeight This is an optional parameter defining the height of the grid header
fontsize The fontsize used to display the header labels
color Defines the colorization of the grid widget. See below.
wheelFunc Optional, a function which is called if the user uses the mouse wheel while positioned above the grid widget. The function will get the index of the top element being displayed as parameter.
mouseOverFunc Optional, a function which is called if the user moves the mouse over a grid row
mouseOutFunc Optional, a function which is called if the user moves the mouses out of a grid row
anchors The position of the grid widget. See How to position widgets
layer The layer of the grid widget versus parent

Supported Methods

getElement()

This method retrieves the underlying Rift UI element.

layout(cols, rows, settings)

This method is very important as it defines the actual layout of the widget. You need to provide three different parameters. If one of the three parameters is omitted the function will not execute!

cols

The first parameter defines the columns of the grid. You can either define standard text cols or texture cols. The parameter itself is expected to be a LUA table of the following format:

cols = {{ align = 'center', header = 'my column header text',  texture = true, type = 'Rift', path = 'resources/icondummy.png', width = 30, textureWidth = 17, textureHeight = 17}, 
	{ align = 'left', header = 'my column header text', width = 218, sortable = false }, ...
}

As you can see there are two completely different possible entries. The first in the above example defines a column which will display textures, the second is the standard definition of a column handling text values.

Standard column definition

Parameter Description
align Optoinal, the alignment of the cells content ('left' or or 'right'). If not supplied the cell contents will be centered.
header Optional, the text to display in the header cell
width The width of the column in pixel
sortable Optional, can be used to disable the column sorting. Default is true if not specified

Texture column definition

Parameter Description
align The alignment of the cells content ('left', 'center' or 'right')
header Optional, the text to display in the header cell
texture Set this to 'true' if you'd like to display textures in this column
type Either 'Rift' or the name of your addon depending on whether you'll want to display custom textures or in-game textures.
path You can set this actually to whatever you want. Simply supply it as an element.
width The width of the column in pixel
textureWidth The width of the textures going to be displayed in the column cells
textureHeight The height of the textures going to be displayed in the column cells
sortable Optional, can be used to disable the column sorting. Default is true if not specified

The second parameter is the number of rows to be displayed. The widget will automatically size the grid based on the initial settings (at creation) plus the col definition and number of rows.

You can use the third parameter to change any of the initial parameters at creation time similar to how :update() works for the other widgets. It is recommended to supply 'headerHeight' as element of the third parameter.

cols = {{ align = 'center', header = 'my column header text',  texture = true, type = 'Rift', path = 'resources/icondummy.png', width = 30, textureWidth = 17, textureHeight = 17}, 
	{ align = 'left', header = 'my column header text', width = 218 }, ...
}
 
myGrid:layout (cols, 10, {headerHeight = 25})

fill (values)

This method actually fills in the values in the grid. You have to supply a Lua table with all the values you want to display. The number of values can of course be greater than the number of rows. The grid will automatically display a scrollbox if the number of values is greater than the number of rows specified through :layout(). You will have to make sure though, that the number of values per row are the same as defined by the cols argument to :layout().

There are two ways to provide the values of the grid. The value of a cell can be provided in form of number or string. In case of number the widget will automatically perform a tostring() on the value. For cols which are supposed to display a texture you'll simply have to provide the path to the texture as value of the cell.

The easy way

The easiest way is to use a simply Lua table of the following format:

myGridValues = {{ value1, value2, value3, value4, ...},
                { value1, value2, value3, value4, ...},
                ...
               }

This will work perfectly for most uses of the grid widget.

The advanced way

The advanced table setup allows you to specify a custom color for each cell value using the property color. This can be defined on a 'per cell' base.

In addition your provide a key for a value row which makes it much easier to identify the data being displayed in a row. The key is supposed to be set in the first column value.

myGridValues = {{ { key = 'key1', value = value1, color = 'hex code'}, { value = value2, color = 'hex code'}, ...},
                { { key = 'key2', value = value1, color = 'hex code'}, { value = value2, color = 'hex code'}, ...},
                ...
               }

search(searchValue, col)

This method searches for a specific value within the grid's values and positions the grid to the first found entry. The search method only searches in specific column which has to be defined as second parameter.

The searching is done using string.find(). This means that partial strings work. In addition the compare is done case insensitive.

setClickEvent (clickCallBack, rightClick)

If you want to execute a function if the user clicks on a grid row you can do so using this method. You'll simply have to provide the function and declare whether the function is to be bound to the left or right click of the mouse.

The method will initiate the event and pass the clicked row as parameter to the function. Using the nkExtGrid.counter property you can then easily calculate the index of the displayed values entry. Then again you can access that table using nkExtGrid.values.

local myClickFunc = function (index)
   print ('value of first cell of clicked row: ' .. myGrid.values[myGrid.counter + index - 1])
end
 
myGrid:setClickEvent (myClickFunc, false)

Other supported methods

Parameter Description
getCounter() returns the index of the top element being out of the value list
getKey(index) returns the key value of a value list entry. The parameter index defines for which entry the key is supposed to be retrieved.
getHeight() returns the height of the grid widget.
reSort(column, ascending) This method sorts and re-displays the grid contents. Using the two parameters you can specify which column to use for the sorting and if the sorting is to be ascending (true) or descending (false).
setPos(pos) Positions the grid contents to a specific value entry. This function does not check if the position is valid, so handle with care!

Setting the color of the grid

The color property is supplied in form of a Lua table using the following format:

color = { body = 'hex code', border = 'hex code', label = 'hex code', headerBody= 'hex code', headerLabel = 'hex code', bodyhighlight = 'hex code', labelhighlight = 'hex code' }
Parameter Description
body The color used for the body of the grid cells.
border The color used for the borders of the grid cells.
label The standard color used for the cell contents.
headerBody Optional, set this if you want the header cell to use a different body color. Set to if you don't want colored header cells (for example if you use a background texture)
headerLabel Optional, set this if you want the header cell to use a different label color.
bodyhighlight This is used as body color if the user mouses over a row to highlight it.
labelhighlight This is used as label color if the user mouses over a row to highlight it. If a custom color is used for the cell entry this property will not have any effect.
Personal tools
Namespaces
Variants
Actions
Menu
Wiki
Toolbox