KDevelop API Documentation

KDevelop Property Editor library description

What is Property Editor?

Property editor is a collection of facilities to store and edit the properties of an object. For example, look at Qt Designer. Each widget has a list of properties that can be edited in a nice table form. Same ideology is used to edit properties in Kugar Report Designer (from KOffice distribution). In KDevelop project manager can also display the properties of currently selected build item in property editor.

Library Overview

This PropertyEditor library is a redesign of Kugar property editing library with the goal to be more generic and extensible.

Library provides a Property class which stores property name, value and some more important information like description or the list of possible values. Using Property class adds more overhead over Q_PROPERTY but provides more flexibility. You can subclass Property and create your custom properties. Custom properties can have either predefined type (see PropertyType) or custom type. Custom type should be used if a custom property editor widget is necessary.

Properties are organized into lists. PropertyList is designed to store such lists in most efficient manner. It also allows to group properties (for example think about "geometrical" properties like "x", "y", etc.).

Property lists can be displayed in PropertyEditor widget which will display them in a table form. Note that PropertyEditor takes not a PropertyList object, but PropertyAccessor instead.

PropertyAccessor is designed to provide a method to access an intersection of property lists. For example, let's consider object A with property list a_list abd object B with list b_list. Now let's imagine we want to display common properties from a_list and b_list in one PropertyEditor widget. Obviously, we need to "intersect" a_list with b_list and display the result of intersection. This is why PropertyAccessor is used for editing. If we change the value of a property in the editor, PropertyAccessor will update both properties from underlying a_list and b_list.

PropertyEditor at the same time shows only one editor for selected property in the list. Each PropertyType has corresponding PropertyWidget which displays property editor or draws a property in the list if it is not edited. More exactly, if PropertyEditor needs to display editor widget, it displays PropertyWidget, else it calls PropertyWidget::drawViewer function. Custom property widgets should be subclasses of PropertyWidget.

To create property widgets at runtime, a factory is used. Factory class is called PropertyMachineFactory. Static function PropertyMachineFactory::getInstance can be used to obtain the reference to the factory instance. Factory creates and returns so-called Machine for each registered property type (either predefined or user defined).

Machine contains PropertyWidget and a list of "detailed" machines. Usually only property widget is necessary for a property but there are complex properties like "Font" for example. We would like to see separate editors for font family, size, etc. and a button to choose all of these in the dialog. For that "Font" property, a PropertyWidget with a "choose font" button and also number of detailed widgets like "font family" combo, etc. can be created.

Examples

A simple example on how to create a property editor and use it with one property list:
    PropertyEditor *m_editor = new PropertyEditor(this);
    
    PropertyList *list = new PropertyList;
    list->addProperty("My Group", new Property(Integer, "First Property",
        "This is my first property", -5));
    list->addProperty("My Group", new Property(String, "Second Property",
        "This is my second property", "Hello"));
    list->addProperty(new Property(Color, "Third Property",
        "This is my third property", QColor("green")));
        
    m_editor->populateProperties(*list);

More advanced example with property accessors and list intersection:

    PropertyEditor *m_editor = new PropertyEditor(this);
    
    PropertyList *list = new PropertyList;
    list->addProperty("My Group", new Property(Integer, "First Property",
        "This is my first property", -5));
    list->addProperty("My Group", new Property(String, "Second Property",
        "This is my second property", "Hello"));
    list->addProperty(new Property(Color, "Third Property",
        "This is my third property", QColor("green")));

    PropertyList *list2 = new PropertyList;
    list2->addProperty("My Group", new Property(Integer, "First Property",
        "This is my first property", -7));
    list2->addProperty("My Group", new Property(String, "Second Property",
        "This is my second property", "Hello"));
    list2->addProperty(new Property(String, "Third Property",
        "This is my third property", "green"));

    PropertyAccessor *ac = list->intersect(*list2);
    
    m_editor->populateProperties(ac);
In this example only properties named "First Property" and "Second Property" will be shown in editor. "Third Property" has different types in list and list2 and will not be included in intersection.
KDE Logo
This file is part of the documentation for KDevelop Version 3.1.2.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Tue Feb 22 09:50:05 2005 by doxygen 1.3.9.1 written by Dimitri van Heesch, © 1997-2003