Component Writer's Guide :: Property Editors

Property editors are special objects that help the component user to get a more friendly experience when using the component inside the IDE. There are several types of property editors:

Integrated Property Editors

The IDE is aware of common properties you may have on your components and provide a built-in mechanism to edit them on the Object Inspector, so you have to tell the IDE, when registering your components, which properties must be edited on an specific way, let's see some examples:

registerBooleanProperty("Frame","Resizeable");

This line tells the IDE that Resizable property of the Frame component (an all descendants) is boolean, and because of that, must show a drop down combo with the values true and false

If you want to specify a set of values for a property, you can use this method:

registerPropertyValues("Frame","Scrolling",array('fsAuto','fsYes','fsNo'));

This tells the IDE to show a drop down with the values fsAuto, fsYes and fsNo when editing the property Scrolling of the Frame component.

And finally, if you provide only an option for the dropdown, the IDE will interpret you want to link to an object:

registerPropertyValues("Control","PopupMenu",array('PopupMenu'));

So when the user edits the PopupMenu property for any Control descendant, the IDE will show a list of all PopupMenu components (and descendants).

And finally, the last option is to tell the IDE to call a component in design type to get the drop-down list values:

registerPropertyValues("Control","Style",array('StyleSheet::Styles'));

This tells the IDE, when the user edits the Style property in the Object Inspector, for any Control descendant, to call the Styles method of all StyleSheet components and show the values returned by that property, which must be an array property.

Follow this link to get a list of available built-in property editors: Component Writer's Guide :: Built-in property editors

PHP Property Editors

The IDE also allows you to develop property editors using PHP code, while this method is not the most convenient because the speed is not as fast as Native Property Editors and the possibilities are not so much, it can be useful for you as you won't need to get Delphi for Win32.

To register a PHP Property Editor:

   registerPropertyEditor("Control","Color","ColorPropertyEditor","designide.inc.php");

This tells the IDE to show an ellipsis button (...) on the Color property for all Control descendants, and when clicked, the IDE must create a PHP property editor, which class is ColorPropertyEditor and the code for it is stored on the unit designide.inc.php.

Examples for PHP Property Editors can be found on designide.inc.php, for example:

class ColorPropertyEditor extends PropertyEditor
{
        function getAttributes()
        {
                $result="sizeable=0\n";
                $result.="width=557\n";
                $result.="height=314\n";
                $result.="caption=Color Property editor\n";
 
                return($result);
        }
 
        function getOutputPath()
        {
                return(dirname(__FILE__).'/resources/coloreditor/');
        }
 
        function Execute($current_value)
        {
                $this->value=$current_value;
 
                if (isset($_POST['selcolor']))
                {
                        echo "newvalue:\n";
                        echo urldecode($_POST['selcolor']);
                }
                else
                {
                        if ($this->value=="") $this->value="#FFFFFF";
                        use_unit("resources/coloreditor/coloreditor.php");
                }
        }
}

Let check some details:

        function getAttributes()
        {
                $result="sizeable=0\n";
                $result.="width=557\n";
                $result.="height=314\n";
                $result.="caption=Color Property editor\n";
 
                return($result);
        }

The IDE calls this method of the property editor before showing it, and here you can dump out some attributes for the IDE to know how to handle it. In this case, we are telling the IDE the property editor window is NOT sizeable, setting the width and height and setting also the caption for the window.

        function getOutputPath()
        {
                return(dirname(__FILE__).'/resources/coloreditor/');
        }

The IDE calls also this method to get the path where the interface for the property editor resides, as the internal webserver will point this folder as the document root.

        function Execute($current_value)
        {
                $this->value=$current_value;
 
                if (isset($_POST['selcolor']))
                {
                        echo "newvalue:\n";
                        echo urldecode($_POST['selcolor']);
                }
                else
                {
                        if ($this->value=="") $this->value="#FFFFFF";
                        use_unit("resources/coloreditor/coloreditor.php");
                }
        }

And finally, it calls the Execute method sending the property value in $current_value, in this case, if there is no $_POST, we show the color property editor, which is stored in resources/coloreditor/coloreditor.php (not included in the rpcl source code at this moment), and when there is something in $_POST, that means the user has submited the form, and to close the property editor and instruct the IDE to set the new property:

  echo "newvalue:\n";
  echo urldecode($_POST['selcolor']);

Echo the new value with the "newvalue:" tag.

We decided not to release PHP property editors with this release, as they are really slow compared with Native ones, so we will try to improve this area on next releases.

Native Property Editors

To develop Native Property Editors you need to get a Delphi for Win32 (2006) license, as the code you need to write is pascal code, you can see some samples of property editors in the /plugins folder of your RadPHP copy, they are released as LGPL also.

To create a Native Property Editor, you need to:

• Create a new package
• Add D4PHPTools.dcp to the requires clause
• Add D4PHPIntf to your uses clause
• Inherit from TD4PHPPropertyEditor

    TSamplePropertyEditor = class(TD4PHPPropertyEditor)
    public
        function Execute(value: string; out newvalue: string): boolean; override;
    end;

• Write the functional code

{ TSamplePropertyEditor }
 
function TSamplePropertyEditor.Execute(value: string; out newvalue: string): boolean;
var
    rgbColor: TColorRef;
begin
    with TColorDialog.Create(application) do begin
        try
            //Set to black if none
            if (value = '') then value := '#000000';
 
            //Strip the #
            if (value[1] = '#') then value := copy(value, 2, length(value));
 
            //Get the color
            color := RGB(
                StrToInt('$' + Copy(value, 1, 2)),
                StrToInt('$' + Copy(value, 3, 2)),
                StrToInt('$' + Copy(value, 5, 2))
                );
 
            result := execute;
 
            //Convert the color to the new value
            if (result) then begin
                rgbColor := ColorToRGB(color);
                newvalue := '#' + Format('%.2x%.2x%.2x', [GetRValue(rgbColor), GetGValue(rgbColor),
                                                          GetBValue(rgbColor)]);
            end;
        finally
            free;
        end;
    end;
end;

• Register the property editor

initialization
    //Register this property editor to all Control descendants with a Color property
    registerPropertyEditor('Control', 'Color', TSamplePropertyEditor);

• Compile your package and copy your .bpl to the plugins folder inside RadPHP folder

Let's check the code:

function TSamplePropertyEditor.Execute(value: string; out newvalue: string): boolean;

In this method, you get the current value in the value parameter (everything are strings) and, if you want to update the component, set the new value on newvalue and return true as the result for the method.

This sample property editor just popups the ColorDialog, sets the color to the current value and if the user accepts the selection, converts the color back to HTML format and returns true.

The file D4PHPIntf.pas contains all the stuff you can use right now to interact with the IDE, this, of course, is not an OpenTools API, but we will expand it on next releases.

Here is an excerpt of the possibilities you have:

//Register a native property editor for a classname (and all the children)
procedure RegisterPropertyEditor(const classname: string; const propertyname: string; editorclass: 
TD4PHPPropertyEditorClass);
 
//Register a layout manager for an specific layout type
procedure RegisterLayoutManager(const layouttype: string; layoutmanagerclass: TD4PHPLayoutManagerClass);
 
//Converts and Array to an StringList, array must be passed php-serialized
function ArrayToStringList(const serializedphparray: string; strings: TStrings): boolean;
 
//Converts an stringlist to an array
function StringListToArray(strings: TStrings; keyvaluepar: boolean = true): string;
 
//Return a list of existing events in code
procedure GetExistingEvents(list: TStrings);
 
//Return a list of components in the current form
procedure GetComponents(classname:string; list: TStrings);
 
//Add an event to code
procedure addEvent(eventcode: string; eventname: string; var x: integer; var y: integer);
 
//Move the editor to an specific position
procedure GotoPos(x, y: integer);
 
//Converts a treeview to an array
function TreeViewToArray(const tree: TTreeView): string;
 
//Converts an array to a treeview
function ArrayToTreeView(const serializedphparray: string; const tree: TTreeView): boolean;