Skip to content

Property Editors

Jump to bottom
codeCatLady edited this page Sep 22, 2022 · 36 revisions

Contents

Built-In Property Editors

Name Description Additional Parameters Default Appearance Optional Appearance
com.livecode.pi.action
com.livecode.pi.align
com.livecode.pi.aligncenter
com.livecode.pi.array
com.livecode.pi.boolean
com.livecode.pi.color
com.livecode.pi.colorwithalpha
com.livecode.pi.customprops
com.livecode.pi.datagrid
com.livecode.pi.datagridcolumns
com.livecode.pi.decorations
com.livecode.pi.dgcolumnbehavior
com.livecode.pi.dimension
com.livecode.pi.distribute
com.livecode.pi.editorlist
com.livecode.pi.enum * Comma-delimited list of values to choose from
* Naked comma denotes an empty value		 .options: comma-delimited list
.default: entry selected in the menu that shows the options
com.livecode.pi.equalize
com.livecode.pi.file
com.livecode.pi.filelist
com.livecode.pi.font
com.livecode.pi.geometry
com.livecode.pi.gradient
com.livecode.pi.gradientramp
com.livecode.pi.graphiceffect
com.livecode.pi.imageid
com.livecode.pi.integer synonym for com.livecode.pi.number
com.livecode.pi.multiplechoice
com.livecode.pi.navbar
com.livecode.pi.nowraptext synonym for com.livecode.pi.text
com.livecode.pi.nudge
com.livecode.pi.number
com.livecode.pi.pattern
com.livecode.pi.point
com.livecode.pi.radiogroup
com.livecode.pi.relayer
com.livecode.pi.script
com.livecode.pi.set
com.livecode.pi.stackfiles
com.livecode.pi.string
com.livecode.pi.styledtext synonym for com.livecode.pi.textcontents
com.livecode.pi.svgicon
com.livecode.pi.svgiconfilter
com.livecode.pi.text
com.livecode.pi.textalign
com.livecode.pi.textcontents
com.livecode.pi.textstyle
com.livecode.pi.timezone

Location in the LiveCode Bundle

If you need to examine the built-in editors, they are generally located at Contents/Tools/Toolset/palettes/inspector/editors/com.livecode.pi.*

NOTE There are also editors that are not enumerated, above. example. com.livecode.pi.integer

Creating Custom Property Editors

If you want to either have a separate panel (tab) for the properties for your widget or you want to implement a property type that the other editors cannot support, you are going to be creating a custom editor stack. This stack will be loaded into the Property Inspector either inline or as its own panel (tab), depending on how you configure the metadata for the property.

Specifications for Custom Property Editors

  • Custom property editors are implemented as separate stacks.
  • Store custom editors and their behaviors in the Editors folder at the same level as the module's .lcb file.
  • Editor stack names are of the form <id>.editor.editorName.livecode (where <id> is the id of the widget), and their behavior stacks <id>.editor.editorName.behavior.livecodescript.
  • Make sure the editor stack's name is the same as the filename (without the suffix): <id>.editor.editorName
  • Each editor is a stack with a group called "template", containing all the controls
  • The behavior stack must implement required editor behaviors.
  • The metadata .editor line for the property just uses the full name of the editor stack (minus the suffix).

Example:

If you have a widget called community.livecode.myWidget, and you decide to call your editor myData, your directory would look something like this:

Screen Shot 2022-09-21 at 19 51 34

Your editor metadata would be:

metadata <propertyName>.editor is "community.livecode.myWidget.editor.myData"

The first line of your editor behavior stack would be:

script "community.livecode.myWidget.editor.myData"

Custom Property Editor Behaviors

Behaviors must implement 4 basic handlers, as well as any custom code for the editor:

Handler Name Description
editorInitialize Handles any initial setup of the editor
editorResize Called when the Property Inspector is resized. Use this handler to control layout of the elements in the editor.
editorUpdate Called when the property value is set, including:
* Property Inspector Opens
* Property is set in script
valueChanged * Call when the value of the property changes to process it.
* The following lines are necessary to cause the property to be applied:
set the editorValue of me to ...
updateProperty

There are a number of properties of the editor stack that can be set and used by both the editor and the Property Inspector. These are managed by the revIDELibrary.

Editor Property Name Description
editorDefault
editorEffective
editorEnabled
editorLabel The label passed in for the property
editorMinWidth Minimum width of the editor. Useful for when grouping properties, for example, to ensure they all appear on the same line. or both the label and the property value are visible.
editorMaxWidth
editorOptions
editorValue The value of the property.
* Don't forget to update this in the valueChanged handler, using the values of the controls in the editor.
* Call updateProperty after set the editorValue of me to ...to cause the IDE to accept and process the updated property.
editorWidth
rowShowLabel

Extending LiveCode's Property getters and setters

Implemented in revIDELibrary, in case you need to add some novel behavior. In most cases, you should just be able to have your LiveCode Builder setter and getter handle an array, and then have your Property Editor do the same.

Notes for building up this wiki page:

In /behaviors/revinspectorgroupbehavior.livecodescript we have

   // Some editors are only slight variants of each other. In this case 
   // we allow the editor behavior itself to configure the options
   switch pPropertyInfo["editor"]
      case "com.livecode.pi.integer"
         put "com.livecode.pi.number" into tEditor
         break
      case "com.livecode.pi.nowraptext"
         put "com.livecode.pi.text" into tEditor
         break
      case "com.livecode.pi.styledtext"
         put "com.livecode.pi.textcontents" into tEditor
         break
      default
         put pPropertyInfo["editor"] into tEditor
         break
   end switch

   inspectorOpenEditor tEditor

   # Create the editor (need to decide if it's a classic editor (clone a group) 
   # or a new widget editor, in which case it's create control.
   if there is not a stack tEditor then
      put "com.livecode.pi.string" into tEditor
      inspectorOpenEditor tEditor
   end if

also in /behaviors/com.pi.editorlist.livecodescript we have

   if tEditorType is "com.livecode.pi.integer" then
      put "com.livecode.pi.number" into tEditorType
   end if

References

Clone this wiki locally