ix: Function parameters

I left off after describing how to send indicator bar setup information from the main Conky (conky_main) function to a separate function called indicator_bar which takes the information sent to it and draws a bar indicator based on those settings.

We did this in conky_main, putting all our settings right into the function call:

indicator_bar (100, 100, 30, 100, tonumber (conky_parse ("${cpu}")),100,
	0.5, 0.5, 0.5, 1, 1, 0, 1, 1, 1, 10, 50, 0, 1, 0, 1, 1, 1, 0, 1, 80,
	1, 0, 0, 1) 

While this way works just fine there are some drawbacks to doing it this way.

First of all, its just hard to keep track of what each number means and second its easy to miss something out (or miss out a comma which are necessary to separate values) -- as I described earlier a missed entry (or comma) when sending information this way will lead to your script giving an error.

I prefer to define my strings, and then duplicate each string name in the function call for example using the multiply function it would look like this:

number = 16
result = multiply (number)

Now we dont have to touch our function call change the number we are sending to the function; we only need change the value we are assigning to the string called "number".

So, for our indicator bar setup we would just take the settings lines we already have, and add the call at the end.

-- SETTINGS FOR INDICATOR BAR
bar_bottom_left_x = 100
bar_bottom_left_y = 100
bar_width = 30
bar_height = 100
bar_value = tonumber (conky_parse ("${cpu}"))
bar_max_value = 100

-- Set bar background colors, 0.5, 0.5, 0.5, 1 = fully opaque grey.
bar_bg_red = 0.5
bar_bg_green = 0.5
bar_bg_blue = 0.5
bar_bg_alpha = 1

-- Bar border settings.
bar_border = 1 -- Set 1 for border or 0 for no border.

-- Set border color rgba.
border_red = 0
border_green = 1
border_blue = 1
border_alpha = 1

-- Set border thickness.
border_width = 10

-- Color change.
-- Set value for first color change, low cpu usage to mid cpu usage.
mid_value = 50

-- Set "low" cpu usage color and alpha, ie bar color below 50% - 0, 1, 0, 1 =
-- 		fully opaque green.
lr, lg, lb, la = 0, 1, 0, 1

-- Set "mid" cpu usage color, between 50 and 79 - 1, 1, 0, 1 = fully opaque.
-- 		Yellow.
mr, mg, mb, ma = 1, 1, 0, 1

-- Set alarm value. This is the value at which bar color will change.
alarm_value = 80

-- Set alarm bar color, 1, 0, 0, 1 = red fully opaque.
ar, ag, ab, aa = 1, 0, 0, 1

-- End of settings, call drawing function.
[b]indicator_bar (bar_bottom_left_x, bar_bottom_left_y, bar_width,
		bar_height, bar_value, bar_max_value, bar_bg_red, bar_bg_green,
		bar_bg_blue, bar_bg_alpha, bar_border, border_red, border_green,
		border_blue, border_alpha, border_width, mid_value, lr, lg, lb,
		la, mr, mg, mb, ma, alarm_value, ar, ag, ab, aa)[/b]

You set values to all your strings and each string matches each entry in the function call list so that the values are transfered directly between the two.

Writing your code this spells out everything nice and simply, which allows easy entry of settings.

You don't have to remember what numbers mean what, you don't have to worry about commas and you are less likely to miss out a value (you would have to delete a whole setting line to do that).

The downside to this is that it takes a lot more lines of code this way.

ANOTHER WAY. You can do something halfway between these two methods mentioned so far which takes advantage of the fact that Lua doesn't mind having its code split onto multiple lines AS LONG AS the information is bounded either by curved brackets () (when sending info to functions) or curly brackets {} (when defining a table).

Take the rectangle drawing command (cairo_rectangle (cr, 50, 50, 50,-100)).

This is just like the function we made, except you don't see the rectangle drawing code anywhere in the script (it's a built-in function).

We call the function cairo_rectangle and send it the information it needs inside curved brackets ().

BUT once the curved brackets are opened (the opening bracket has to be on the same line as the function call), we can then split up our entries on to separate lines.

cairo_rectangle (cr,
	50,
	50,
	50,
	-100)

We have to make sure that we have still have commas separating the entries but entering data this way has the advantage that we can write comments on each line and everything still works.

cairo_rectangle (cr,
	50, -- Rectangle x position.
	50, -- Rectangle y position.
	50, -- Rectangle width.
	-100 -- Rectangle height.
)

We could do this just the same with out indicator bar function you can see below I have split some entries onto separate lines but kept others together on the same line where it makes sense.

indicator_bar (
	750, 400, 				-- Position x, y.
	30, 					-- Bar width.
	100, 					-- Bar height.
	tonumber (conky_parse ("${cpu}")), 	-- Value to send bar.
	100, 					-- Max value.
	0.5, 0.5, 0.5, 1, 			-- Bar background color rgba - grey.
	1, 					-- Want border, 1 = yes, 0 = no.
	0, 1, 1, 1, 				-- Border color rgba - light blue.
	10, 					-- Border width.
	50, 					-- Mid value, point of first color.
						--	    change.
	0, 1, 0, 1, 				-- Low cpu% color rgba - green.
	1, 1, 0, 1, 				-- Mid cpu% color rgba - yellow.
	80, 					-- Alarm value, point of second color.
						--  	change.
	1, 0, 0, 1 				-- Alarm color rgba - red.
)

A MORE COMPLEX USE OF FUNCTIONS

The functions I have given as examples are pretty straightforward -- set up the function, call it and give it the info it needs and the function outputs something, for example a number or some graphics.

But the use of functions can be more complex.

Here is an example. We are going to have our main Conky function, and two additional functions: one for drawing arcs and the second to convert degrees into radians and adjust for the cairo_arc quirk so that 0 degrees is the top of the circle.

Our angle conversion function might look like this:

function arad (degrees)

	-- Compensate for cairo_arc quirk.
	degrees = degrees - 90

	-- Convert degrees to radians.
	radians = degrees * (math.pi / 180)

	-- Return angle.
	return radians
end

NOTE: this line -- degrees = degrees - 90 -- I write it quite often, as others do in their scripts.

I'm taking the value of the string "degrees" as it was set inside (), subtracting 90 from it and putting the result of that operation into a string -- also called "degrees".

As mentioned earlier, strings of the same name overwrite each other, so the second instance of a string called "degrees" will indeed overwrite the first instance. However, this will not happen until the original "degrees" string is used in the calculation.

As long as you know that you will no longer need the value held in the first "degrees" string after using it in, for example, a calculation, then reusing the string name just makes it so that you don't have to keep thinking up new string names!

The arc drawing function might look like this. I'll use nice short string names here :).

mx will be for middle x position. my will be for middle y position. rad for radius. sa for start angle. ea for end angle.

(I will be giving angles in degrees when I call the function).

I want all my circles to be white with a line thickness of 1, so I'm going to set color, alpha and line_width in the function itself.

function circle (mx, my, rad, sa, ea)
	cairo_set_source_rgba (cr, 1, 1, 1, 1)
	cairo_set_line_width (cr, 1)
	cairo_arc (cr, mx, my, rad, arad (sa), arad (ea))
	cairo_stroke (cr)
end

The important line to note is this one cairo_arc (cr, mx, my, rad, arad (sa),arad (ea))

I can use the arad function inside the cairo_arc command to convert the degree values we send "circle" into adjusted radian values to use with cairo_arc.

Then, last of all, we have our conky_main function.

function conky_main ()
	-- Conky function setup lines
	circle (100, 100, 50, 90, 270)
	-- Conky function close out lines.
end

If we think about the flow of information, we send "circle" the information in the function call inside conky_main.

Circle receives the list of values and sets its list of strings to those values in order.

It uses the strings my, mx and rad directly but it ships out sa and ea to arad.

arad receives the value of sa, puts that value into a string called degrees and converts the value to adjusted radians and sends this new value back to "circle" where is is used as the start value directly in the cairo_arc command.

Then arad receives the value of ea and returns the result directly into cairo_arc.

The chain of functions using functions could keep going for as many functions as you could write and you can of course use as many functions within any other function as you want.

Next part will introduce tables.