Integrating Properties

In Lesson 3 we defined the rotation property of the widget.

• Properties are shown in the Basic pane of the Property Inspector.
• The name of the property is shown as the label in the Property Inspector.
• A standard editor is shown for the property.

property "rotation" get mRotation set setRotation

You can more fully define widget properties in the LCB source file using metadata. Any property metadata is optional. Property metadata definitions have the format:

metadata <property name>.<metadata name> is <value>

You can define:

• Property label
• Editor type
• Editor specific metadata
• Default value
• Property Inspector Section
• Property group
• User visible
• Read only

For more on property metadata see Property Definitions Read Me.

Property metadata

Add the metadata for the rotation property to the widget source file.

• label: the label to be shown in the Property Inspector
• editor: the type of editor to be used in the Property Inspector
• default: the default value of the property

Editor specific metadata:

• step: the step value for number properties
• min: the minimum value for a number property
• max: the maximum value for a number property

We want this property to appear in the Basic section so do not specify a section.

widget community.livecode.elanorb.rotatedtext

… widget inclusions and metatdata

property "rotation" get mRotation set setRotation
metadata rotation.label is "Rotation"
metadata rotation.editor is "com.livecode.pi.number"
metadata rotation.default is "0"
metadata rotation.step is "1"
metadata rotation.min is "0"
metadata rotation.max is "359"

… widget handlers
end widget

The Content Property

We will add a second property, content, which allows the user to change the text displayed in the widget.

• Define a variable to store the property value.
• Define the property, getter and setter.
• Add metadata for the property.
  • editor
  • default
  • label

widget community.livecode.elanorb.rotatedtext
… widget inclusions and metatdata
… rotation property definition

private variable mContent as String
property "content" get mContent set setContent
metadata content.editor is "com.livecode.pi.string"
metadata content.default is "Default text"
metadata content.label is "Content"

… widget handlers

end widget

The setContent Handler

Add the content property setter handler.

• Takes a string parameter
• Has no return value
• Update the mContent variable with the paramater value.
• Redraw the widget with the new text.

public handler setContent(in pText as String) returns nothing
 put pText into mContent
 redraw all
end handler

Update OnPaint

The OnPaint handler needs updated to use the value of the content property.

• Delete the declaration for the tText variable
• Update the “fill text” line to use the mContent variable

public handler OnPaint()
   variable tText as String
   variable tHeight as Real
   variable tWidth as Real
 
   put my width into tWidth
   put my height into tHeight
   put "LiveCode" into tText

   rotate this canvas by mRotation

   variable tRectangle as Rectangle
   variable tPath as Path
   put rectangle path of rectangle [0,0,tWidth,tHeight] into tPath
   rotate tPath by (mRotation * -1)
   put the bounding box of tPath into tRectangle
   fill text tText at center of tRectangle on this canvas
   fill text mContent at center of tRectangle on this canvas
end handler

The OnCreate Handler

When a widget is created the default values for its properties should be used.

The OnCreate handler is called when the widget is first created.

To ensure the values of the rotation and content properties are set we add the OnCreate handler which will call the property setters with the default values.

• Set the default value of the content  property to “Default text”
• Set the default value of the rotation property to 0

widget community.livecode.elanorb.rotatedtext

… widget inclusions and metadata
… property definitions
… OnPaint handler

public handler OnCreate()
   setContent("Default text")
   setRotation(0)
end handler

… Property setters

end widget

Testing the Widget

Now build and test your widget using the Extension Builder.

You should see the Content property in the Property Inspector and be able to change the text displayed in the widget.