Properties in qooxdoo comes with a bit overhead, as they do value validation and comes with event support and so on. If you don’t need these features or your variable you want to store is really time critical it is the best to omit the usage of qooxdoo properties. Then please create your own setters and getters (if needed) and store the value just a a hidden private variable (not really private, as JavaScript does not have this feature) in “_varName” inside your object.

Here comes the explanation of the arguments of the modifier (these are always the same)

• propValue: New property value
• propOldValue: Old (previous) property value
• propData: The hash table which has defined these property (referenced) using addProperty()

In propData you can define all the given attributes of the properties. Also the name and the camelcase (method) and uppercase (up) variant which could be sometimes very useful (Also it performs better than create these converted string each time the modifier will be called).

This property implementation is really rich. There are many things more I will explain in the following parts more detailed.

Each property could also have a default value. This could be easily defined using the key “defaultValue”. Take a look at this example:

qx.OO.addProperty({ name : "tagName", type : "string", defaultValue : "div" });

The default default value is null.

If you don’t want to allow a value null (which is by default allowed), simply do it like this code shows:

qx.OO.addProperty({ name : "title", type : "string", allowNull : false, defaultValue : "" });

The best if to also define the default value then. Otherwise the default value (which will not be checked) itself is incorrect for the property. The example above is a nice example what to do if you only want to allow strings as valid values.

One often used feature is that you are able to use the same modifier for multiple properties. You then define the “impl” with a common string in each property defintion. A small examples which is used the same way in Widget:

qx.OO.addProperty({ name : "clipLeft", type : "number", impl : "clip" });
qx.OO.addProperty({ name : "clipTop", type : "number", impl : "clip" });
qx.OO.addProperty({ name : "clipWidth", type : "number", impl : "clip" });
qx.OO.addProperty({ name : "clipHeight", type : "number", impl : "clip" });
 
qx.Proto._modifyClip = function(propValue, propOldValue, propData) {
  return this._compileClipString();
};

Other than that mentioned modify function you can define, there is also a check function which you can use to check, validate, transform whatever with your incoming value, before it will stored and send to the real modifier.

This is not so often used (currently only inside RangeManager as it seems to limit the value to the defined min/max values) but nice if you need it in your application or other classes.

Use the following for example to limit the value to 100:

qx.Proto._checkWidth = function(propValue, propData) {
  return Math.min(propValue, 100);
};

You can also define one getter alias and one setter alias for each property. Sometimes this is nice to have a better sounding method than the typically getProperty and setProperty.

qx.OO.addProperty({ name : "readOnly", type : "boolean", defaultValue : false, getAlias : "isReadOnly" });

It works identical with _setAlias_.

You can also define that a property, when changed, automatically add itself to the job or layout queue. Here comes an example:

qx.OO.addProperty({ name : "marginTop", type : "number", addToQueue : true, defaultValue : 0 });

This means that with each change of the property it will automatically added to the queue system. The layout manager will then do the rest. You don’t have even to define any line of modifier to do this. Great.

This is a bit more advanced and currently limited to layout properties like left, height, ... This is currently only useable for them. But we could code sometimes a bit more there to make it more flexible.

The idea behind is that we want to have a common interface to detect types of values (more advanced one like: percent, flex, auto, ...) in a common manner.

qx.OO.addProperty({ name : "left", addToQueue : true, unitDetection : "pixelPercent" });

This will call a method named unitDetectionPixelPercent to compute the type and parse the values correctly.

You can check for the typeof a value coming in. But you can also seperate qooxdoo objects from each other if you use them as a property value (for example in borders, tooltips or contextmenus).

Then you can easily define a classname or a instance to check against. Here comes the code:

qx.OO.addProperty({ name : "border", type : "object", instance : "qx.renderer.border.Border" });

The instance is defined here as a string. This is the best to make it more stable, as it is possible that the class is not already available or there is a typo somewhere.

You can also define the exact classname of the incoming widget. Sometimes it is a bit hard to understand the difference between the instance and the classname check here: The classname check do a explicit classname check. The instance check only verifies if the incoming object is a object which is a instanceof an object, but it must not be an object of this class itself. The property defined above also accepts qx.renderer.border.BorderObject for example, which is an instanceof qx.renderer.border.Border but the exact classname is qx.renderer.border.BorderObject. Hopefully this helps a bit.

To check for a classname do the following:

qx.OO.addProperty({ name : "border", type : "object", classname: "qx.renderer.border.Border" });

Another often used possibility of the properties is the key “possibleValues”. Here you can define in detail, as the name says, which values are allowed. All others will be lead to an error message. The value of “possibleValues” is a array, where each entry is a possible value. Here an short example:

qx.OO.addProperty({ name : "moveMethod", type : "string", defaultValue : "opaque", possibleValues : [ "opaque", "frame", "translucent" ] });

You can even modify existing properties. This mean for example you can change the default value of a property in a child class.

This is sometimes a better idea, than set the property in the constructor to the new value, because it’s faster (as it will be done only once for all instances of these object).

To modify a property simply do a:

yourClass.changeProperty({ [...] });

The best is to give this function call all the key-value pairs of the addProperty call and change the ones which need modification.