propertiesGUI

Last week I presented a detailed explanation of the uiinspect utility, which displays a GUI listing all the properties, callbacks and internal methods of an inspected object. Something like Matlab’s inspect tool on steroids. I explained that uiinspect uses com.mathworks.mlwidgets.inspector.PropertyView, which in turn uses JIDE’s PropertyTable. PropertyView automatically extracts the inspected object’s properties and displays them using a corresponding renderer in the PropertyTable.

propertiesGUI demo

We often need to present a non-object Matlab construct. For example, it is very common to store an application’s configuration properties in a struct (using Matlab objects is often impractical and unwarranted) — it would be very useful to present this configuration dynamically, without having to programmatically scan all struct fields and build a dedicated GUI table. Unfortunately, PropertyView cannot automatically retrospect Matlab structs, which is the reason that the built-in inspect function fails for such objects. In the general case, we may wish to present a PropertyTable using row-specific renderers and editors, when we have such an un-inspectable object (struct, cell array etc.), or even for a dynamically-created table of properties that is not stored in any single object.

Another limitation of PropertyView is that it immediately assigns updated property values to the inspected object, without allowing any sanity checks to be conducted on the new values, and without enabling the user to cancel property changes.

Last but not least, PropertyView does not enable users to easily modify the way that certain properties are presented. Boolean properties (true/false) always use a checkbox cell-renderer/editor, while we may wish to display a string (on/off) or combo-box instead.

In short, PropertyView is great unless you want to customize stuff, or do something slightly out-of-the-ordinary.

Enter propertiesGUI, the subject of today’s article.

The propertiesGUI utility

propertiesGUI, which can be downloaded from the Matlab File Exchange, presents a generic solution to this problem. propertiesGUI is based on Levente Hunyadi’s articles here back in 2010, and on his “Property grid” utility on the File Exchange.

propertiesGUI expects the following syntax:

[hPropsPane, parameters] = propertiesGUI(hParent, parameters)

where:

• hParent (input) is an optional handle of a parent GUI container (figure/uipanel/uitab) in which the properties table will appear. If missing or empty or 0, the table will be shown in a new modal dialog window; otherwise it will be embedded in the parent container.
• parameters (input) is an optional struct or object with data fields. The fields are processed separately to determine their corresponding cell renderer and editor. If parameters is not specified, then the global test_data will be used. If test_data is also empty, then a demo of several different data types will be used.
• hPropsPane (output) is the handle of the generated properties panel widget, which can be customized to display field descriptions, toolbar, etc.
• parameters (output) is the resulting (possibly-updated) parameters struct. Naturally, this is only relevant in case of a modal dialog.

When passing the properties in an input parameters struct, propertiesGUI automatically inspects each struct field and assigns a corresponding cell-editor with no description and a field label that reflects the field name. The properties are automatically set as modifiable (editable) and assigned a default callback function (propUpdatedCallback sub-function).

The global test_data variable is updated internally when the <OK> button is clicked. It is meant to enable easy data passing between the properties GUI and other application component. Using global vars is generally discouraged as bad programming, but it simplifies GUI component interaction and has performance advantages. In this specific case I decided that the benefits of simplicity outweigh the pedagogical aspects. After all, propertiesGUI is meant to illustrate how to customize/use a properties pane, not to teach GUI programming best practices. In your real-world application you should consider using other information-sharing mechanisms (getappdata or guidata, for example).

Usage demo

For an illustration of propertiesGUI, simply run it without any parameters to display its demo (see screenshot above):

propertiesGUI;

This creates (in the demoParameters sub-function) the following demo parameters struct:

      floating_point_property: 3.14159265358979
      signed_integer_property: 12
    unsigned_integer_property: 12
                flag_property: 1
                file_property: ''
              folder_property: 'C:\Yair'
                text_property: 'Sample text'
        fixed_choice_property: {'Yes'  'No'  'Maybe'}
     editable_choice_property: {'Yes'  'No'  'Maybe'  ''}
                date_property: [1x1 java.util.Date]
        another_date_property: 734895.957829132
                time_property: '22:59:16'
            password_property: '*****'
          IP_address_property: '10.20.30.40'
                  my_category: [1x1 struct]
               color_property: [0.4 0.5 0.6]
       another_color_property: [1x1 java.awt.Color]

A template for customization

propertiesGUI is meant to be used either as stand-alone, or as a template for customization. For example, we can attach a unique description to each property that will be shown in an internal sub-panel: see the customizePropertyPane and preparePropsList sub-functions.

We can have specific control over each property’s description, label, editability, cell-editor and callback function. See the preparePropsList sub-functions for some examples. Additional cell-editors/renderers can be added in the newProperty sub-function.

Specific control over the acceptable property values can be achieved by entering custom code into the checkProp sub-function. For example, checkProp already contains skeleton code to highlight missing mandatory field values in yellow, and non-editable properties in gray (see highlighted lines; the necessary modifications to make it work should be self-evident):

function isOk = checkProp(prop)
  isOk = true;
  oldWarn = warning('off','MATLAB:hg:JavaSetHGProperty');
  warning off MATLAB:hg:PossibleDeprecatedJavaSetHGProperty
  propName = get(prop, 'UserData');
  renderer = com.jidesoft.grid.CellRendererManager.getRenderer(get(prop,'Type'), get(prop,'EditorContext'));
  warning(oldWarn);
 
  mandatoryFields = {};  % TODO - add the mandatory field-names here  if any(strcmpi(propName, mandatoryFields)) && isempty(get(prop,'Value'))      propColor = java.awt.Color.yellow;      isOk = false;
  elseif ~prop.isEditable      %propColor = java.awt.Color.gray;      propColor = renderer.getBackground();
  else
      propColor = java.awt.Color.white;
  end
  renderer.setBackground(propColor);
end  % checkProp

So if we wish to check the validity of the input or user updates, we simply need to enter the relevant checks into checkProp.

Additional control over the appearance and functionality can be achieved via the hPropsPane reference that is returned by propertiesGUI.

As an example for such customizations, here is a variant of the properties pane, embedded within a uitab panel. Note the unique description of the properties, and the absence of the OK/Cancel buttons:

Properties panel Integrated within a GUI

TODO

Even as a template for customization, propertiesGUI is still far from perfect. Some potential items on my TODO list for this utility include:

• Fix the renderer/editor for numeric and cell arrays
• Enable more control over appearance and functionality via input parameters (for example: display or hide the OK/Cancel buttons)
• Add additional built-in cell editors/renderers: time, slider, point, rectangle (=position), font, …

Do you find propertiesGUI useful in your work? If so then please share your experience in a comment below. Suggestions for improvement of the utility will also be gladly accepted.

1. Advanced JIDE Property Grids JIDE property grids can use complex cell renderer and editor components and can signal property change events asynchronously to Matlab callbacks...
2. JIDE Property Grids The JIDE components pre-bundled in Matlab enable creating user-customized property grid tables...
3. Uitable customization report In last week’s report about uitable sorting, I offered a report that I have written which covers uitable customization in detail. Several people have asked for more details about the...
4. Date selection components The JIDE package, pre-bundled in Matlab, contains several GUI controls for selecting dates - this article explains how they can be used...