Creating the LiveCode Builder file

As with the Hello World Library and Rotated Text Widget we will start a new LiveCode Builder source file.

• Create a new directory.
• Create a new plain text file in the directory and save it to disk with the extension “lcb”.

I am naming my file “pieChart.lcb” but you can name your file anything suitable.

Note: The extension builder currently relies on there being only one .lcb file in a given directory, this is why we create a separate folder for each new extension.

Widget definition

Begin by defining the pie chart widget in the LCB file.

Remember

• The widget declaration is followed by an identifier.
• An extension identifier should be in the form

community.livecode.<user name>.<widget name>

For more on module naming see the Naming section of the LiveCode Builder Style Guide, accessible from the Dictionary stack or the Additional Resources section of the course.

widget community.livecode.elanorb.piechart

end widget

Including modules

Include the recommended modules and libraries in the LCB file.

• com.livecode.canvas
• com.livecode.widget
• com.livecode.engine
• Com.livecode.library.widgetutils

For a full list of modules see the Importing Libraries section of the Extending LiveCode Guide and the API entries for the individual modules.

widget community.livecode.elanorb.piechart

use com.livecode.canvas
use com.livecode.widget
use com.livecode.engine
use com.livecode.library.widgetutils

end widget

Widget metadata

Add the required widget metadata to the definition.

• title
• author
• version

You can also include an optional metadata. We want to ensure the Pie Chart widget is created at a reasonable size so add

• Preferred size

widget community.livecode.elanorb.piechart

use com.livecode.canvas
use com.livecode.widget
use com.livecode.engine
use com.livecode.library.widgetutils

metadata title is "Pie Chart"
metadata author is "Elanor Buchanan"
metadata version is "1.0.0"
metadata preferredSize is "200,150"

end widget

Variable declarations

In Step 1 we identified 3 properties of the Pie Chart widget: values, labels and whether labels should be shown.

In addition we want an a list variable to store the list of colors that will be used for the sectors.

As before we will use module level variables to store the values of these properties.

Declare the 4 variables and their types.

Also add a constant kPadding which will be used to layout the elements of the widget.

Note: See Lesson 3 – Step 3: Module level variables if you need a refresher.

widget community.livecode.elanorb.piechart

… module imports
… metadata

private variable mValues as List
private variable mLabels as List
private variable mColors as List
private variable mShowLabels as Boolean

constant kPadding is 10

end widget

The values property

The values property will have both a getter and a setter handler.

Add the definition for the property, including:

• Property name
• Getter handler name
• Setter handler name
• Default value
• Property label

widget community.livecode.elanorb.piechart

… module imports
… metadata
… instance variable declarations

property "sectorValues" get getValues set setValues
metadata sectorValues.default is "1,2,3,5,8,13"
metadata sectorValues.label is "Values"

end widget

The segmentValues property has both a getter and a setter property.

The Property Inspector allows the user to set the segmentValues to a comma separated list of values.

The setValues handler converts the comma separated string to a LCB list.

The getValues handler converts the LCB list to a string, allowing it to be displayed in  the Property Inspector.

Add the handlers to the source code.

widget community.livecode.elanorb.piechart

...previous code

public handler setValues(in pValues as String) returns nothing
   split pValues by "," into mValues
   redraw all
end handler

private handler getValues() returns String
   variable tValues
   combine mValues with "," into tValues
   return tValues
end handler

end widget

The labels property

The labels property will also have both a getter and a setter handler.

Add the definition for the property, including:

• Property name
• Getter handler name
• Setter handler name
• Default value
• Property label

widget community.livecode.elanorb.piechart

… module imports
… metadata
… instance variable declarations
… previous property definitions

property "sectorLabels" get getLabels set setLabels
metadata sectorLabels.default is "Jan,Feb,Mar,Apr,May,Jun"
metadata sectorLabels.label is "Labels"

… code continues

end widget

Like the segmentValues property the segmentLabels property has both a getter and a setter property.

The Property Inspector allows the user to set the segmentLabels to a comma separated list of values.

The setLabels handler converts the comma separated string to a LCB list.

The getLabels handler converts the LCB list to a string, allowing it to be displayed in  the Property Inspector.

Add the handlers to the source code.

widget community.livecode.elanorb.piechart

… previous code

public handler setLabels(in pLabels as String) returns nothing
   split pLabels by "," into mLabels
   redraw all
end handler

private handler getLabels() returns String
   variable tLabels
   combine mLabels with "," into tLabels
   return tLabels
end handler

end widget

The showLabels property

The Show labels property is a boolean value so only has a setter handler.

The value of the mShowLabels variable is returned when the property value is requested.

Add the definition for the property, including:

• Property name
• Variable name for the get method
• Setter handler name
• Default value
• Property label

widget community.livecode.elanorb.piechart

… module imports
… metadata
… instance variable declarations
… previous property definitions

property "showLabels" get mShowLabels set setShowLabels

metadata showLabels.default is "true"
metadata showLabels.label is "Show labels"

… code continues

end widget

The setShowLabels handler sets the value of the mShowLabels variable to the value passed in.

Add the handler to the source code.

widget community.livecode.elanorb.piechart

… previous code

public handler setShowLabels(in pShow as Boolean) returns nothing
   put pShow into mShowLabels
   redraw all
end handler

end widget