custom.pi - Make your own Property-Inspector-Function for your Widget

[astu]

I apologize that I do not post screenshots with, I may not upload anything here yet

I have been working on my new version of my customRect widget the days.
My goal was to set the label text of the widget on the canvas like in a text field right or left aligned. Also, i wanted to have the ability to set the label to top or bottom as well.

Preferably via the property inspector, since I don't have to script the position of the label every time.
Unfortunately the default editor com.livecode.pi.textalign which is used for this only allows center, right and left justified. So every customRect label can only be adjusted via script?

Nope, is out of question for me lazy dog. I rather build my own *.pi -function so that I don't have to set the label by script in the future.

So let's take a closer look at the whole construct.

I have created a small example widget which shows me a label and I can test the function of the alignment.
You can find the structure of the widget here: https://github.com/Hoerwi/openXTalk-custom.pi
How the widget is built doesn't matter. It is mainly about how the function of the label-align is built up.
But let's have a look how it looks like in the standard:

With the metadata textalign.editor the entry in the Property-Inspector is displayed with com.livecode.pi.textalign. As you can see only Left - Center - Right is possible. Offsetting to top and bottom is not possible.
If we search now in the program directory of Livecode for "com.livecode.pi" we find some entries under \Toolset\palettes\inspector\editors
There you can also find two files for the com.livecode.pi.textalign
This is a script and a Stack file.

If we now look at the stack file we see that just the segmented widget in there. Nothing more. No script, only the appearance defined by the Property-Inspectors. The function of the Align tool is described in the appropriate script.
What annoys me personally about it is that it, like almost all *.pi -functions is hardly or not at all documented or commented.

If you look at it this way, the structure is so simple that you can quickly assemble a new *.pi- function yourself.
We use the standard Align tool as a template. But we do not change it, because other functions of the IDE depend on this pi.

Let's first build the appropriate stack

So we open a default stack in LC / oXT and drag in the segmented widget on it.
We make the settings as follow in the propertys of this widget:
Under Basic:
[*]Number of Segments: 5
[*]Segment names and labels on left / center / right / top / bottom
[*]minimum segment widths = 30
[*]Clicking toggels highlight = true
[*]Show border = true
[*]Display style = Icons
[*]Corner radius = 5

Under Icons we set the Segment Icons and Hilited Segment icons.
Here I chose the Chevron Signs for the direction of the alignment, for Center just the black Circle.

Under Position we set the Width to 150 and Height to 21

At this point, the developers got a little mean and put the Segmentcontrol widget group in a Group "template"!
Of course we do this as well.

!!! If this is not done, nothing will be displayed in the Property Inspector!!!

Now we can save the stack with the name custom.pi.btnalign to \Toolset\palettes\inspector\editors
With this we already have the representation of our Property-Inspector entry.

Now we only need the appropriate script for it.

We have to write this as a separate script. Writing the whole thing directly into the custom.pi.btnalign stack unfortunately doesn't work.

But here we get really lazy and copy the content of the file com.livecode.pi.textalign.behavior.livecodescript into a new file and save it under the name custom.pi.btnalign.behavior.livecodescript
I recommend to do this in a separate editor like Notepad++ or Atom

Now we need to make a few small adjustments in the new script at the following places:

Code: Select all

1: script "custom.pi.btnalign.behavior"
...
3: set the editorMinWidth from me to 150
4: set the editorMaxWidth from me to 150
...
28: set the width of widget 1 of me to 150
...

and save the whole thing to \Toolset\palettes\inspector\editors
Once everything is saved, we need to restart Livecode or openXTalk!

Now we can prepare and test this in the example widget

I will now only go into the required entries in the LCB script.
The full script for the test widget can be found on GitHub.

First we have to define a variable for the mBtnAlign:

Code: Select all

private variable mBtnAlign as String

next we need the appropriate property to display the whole thing in the property inspector:
with the metadata btnalign.editor we call our new *.pi.*- element we just created

Code: Select all

property "btnalign" get mBtnAlign set setBtnAlign
	metadata btnalign.editor is "custom.pi.btnalign“
	metadata btnalign.section is "Basic"

What must not be missing, of course, is the handler:

Code: Select all

public handler setBtnAlign(in pBtnAlign as String) returns nothing
put pBtnAlign into mBtnAlign
redraw all
end handler	

But to make it work properly and put the label in the right place of the widget we have to add the following in the handler:

Code: Select all

Public handler onPaint()
…
if mBtnAlign is "right" then
     fill text mLabel at right of tRectangle on this canvas
else if mBtnAlign is "left" then
     fill text mLabel at left of tRectangle on this canvas
else if mBtnAlign is "top" then
     fill text mLabel at top of tRectangle on this canvas
else if mBtnAlign is "bottom" then
     fill text mLabel at bottom of tRectangle on this canvas
else
     fill text mLabel at center of tRectangle on this canvas
end if
…
end handler

Thats all...

Oh I forgot to mention: the widget created with this "library" can only be used by you locally when scripting. If you pass the widget on, it will not work for others.
This only affects the widget itself, not the standalones!

[astu]

A small note... the prefixes *.livecodescript and *.livecode can also be omitted or exchanged for other prefixes.

It is only important that the files are in the correct directory

[OpenXTalkPaul]

Excellent, thanks for writing all that up!

I probably would've just added a popup menu for label position via the Widget's metadata and property definitions, but where's the fun in that when we can mod the IDE itself? Seriously this will certainly come in handy I think.

I have edited a few of those property inspector files, but just to make button text black for DarkMode PI.

There's tab separated prefs settings related controls that go in these folder:
OpenXTalk.app/Contents/Tools/Toolset/resources/supporting_files/property_definitions

I guess they're default values for props for various classic controls:

Screen Shot 2021-11-29 at 9.30.42 PM.png (646.93 KiB) Viewed 13191 times

There's also an readme in that folder:

Property data files
The IDE uses the files in this directory to store information on object properties so that they can be controlled appropriately by IDE palettes (notably the property inspector).

The file propertyInfo.txt contains all the base information about object properties. Each of the files com.livecode.interface.classic.<objtype> contain information on object properties in the context of the given object type.

Structure
Excluding some optional information about object types, the property data file consists of lines of tab-delimited data, one line for each property.

The items are, in order:

Property name
The property name may also contain information about what getter and setter to use for the property in case it shouldn't use the IDE's default method. If these are present, they should be separated from the property name by colons, eg propname:customGetter:customSetter

If the custom getters and setters are present, they will be used by the property inspector automatically. Note the setter must be a command taking parameters <objectLongID>, <propertyName>, <propertyValue>, and the getter must be a function taking parameters <objectLongID>, <propertyName>.

Label
This is the label that will be used in the property inspector if the user prefers to use readable labels instead of the property name.

Section
This is the section that the property data will appear under. These correspond to the tabs in the property inspector.

Editor
This is the editor to be used to edit the property. See the [Extending LiveCode](../../../../Documentation/guides/Extending Livecode.md) guide for more information on property editors.

User Visible
Controls whether the property appears in the property inspector.

Read Only
Controls whether the property can be modified in the property inspector.

Group
Properties can be grouped in the inspector so that they appear in the same row. If there is more than one property in a group, their editors will be arranged side-by-side if possible.

Default
The default value for the property. When the object is created in the IDE (eg by dragging from the Tools palette), all properties are set to their defaults.

Default values may use the execute: syntax. If they do, the script is executed, and the default value for the property is whatever is in the it variable afterward.

Occurrences of \n in not-executable default values are replaced by return characters.

Options
The options for an enum or set property. These should be comma delimited.

If the display value of an option differs from its actual value, this can be achieved by using colon separation, eg opt1:Option 1,opt2:Option 2,...

Option values may use the execute: syntax. If they do, the script is executed, and the options for the property are whatever is in the it variable afterward.

Subsection
Not currently used, but may be in the future to specify a level of grouping between group and section.

Min
The minimum value of a numeric property.

Max
The maximum value of a numeric property.

Step
The amount by which a numeric property should be incremented/decremented by any numeric twiddle.

Here's the one for com.livecode.interface.MultipleObjects as used by the PI's Align pane (I was sort of rebuilding this as a separate align/distribute palette)

Screen Shot 2021-11-29 at 9.37.41 PM.png (332.12 KiB) Viewed 13191 times

[OpenXTalkPaul]

propertyInfo.tsv as spread sheet, printed to a PDF:

propertyInfo.pdf.zip

(270.01 KiB) Downloaded 521 times

[astu]

propertyInfo.tsv as spread sheet, printed to a PDF:
propertyInfo.pdf.zip

Thanks for the info, Paul.

I'll browse through it.
A few of the PIs could do with an "upgrade"... I'll see what I can do or whether I can even build additional independent PI functions.

Here you really have to be careful that you don't shoot something to pieces...