Undocumented Matlab JIDE Property Grids

JIDE Property Grids

Posted By Yair Altman On April 21, 2010 | 17 Comments

I would like to welcome guest blogger Levente Hunyadi ^[1].

Matlab’s property inspector

We often wish to edit properties of heterogeneous objects using a common interface. Matlab’s property inspector, invoked with the built-in inspect ^[2] function, answers this need. The inspector is based on a two-column table of property names and values. Properties and their values are populated automatically, and the user can edit values in-place. The inspector enables property categorization, sub-categorization and sorting, which help users find and modify properties easily. For each property, the inspector displays a matching edit control: editbox/combobox/checkbox etc. This simplifies property value editing and prevents illegal value entry. Matlab’s GUI builder, GUIDE ^[3], uses the inspector to let users edit GUI properties such as position, color etc. It is also used by other tools such as the Plot Editor ^[4].

The Matlab inspector can be embedded, with not-too-much effort, within Matlab GUI applications. Examples of this can be found in the FindJObj ^[5] and UIInspect ^[6] utilities.

Unfortunately, Matlab’s property inspector is limited to Handle Graphics, Java and COM objects, and cannot be used for structures or user-defined Matlab classes. We shall see below how to set up our own property grid, populate it with data, and subscribe to property change events. This is a rather procedural approach. It is usually more convenient to use a declarative approach in which a structure or Matlab class is passed to a function that automatically discovers its properties and their meta-information. The Property Grid ^[8] utility at Matlab File Exchange provides these services.

A simple property grid

Matlab’s property inspector is based on a property grid control by JIDE Software ^[9]. JIDE Grids is a collection of components that extend the standard Java Swing JTable ^[10] component, and is included in each Matlab installation (/java/jarext/jide/jide-grids.jar under the Matlab root). In particular, JIDE Grids includes the PropertyTable class, which is a fully customizable property grid component. You can find further details on JIDE Grids in the Developer Guide ^[11] and the Javadoc documentation ^[12].
There are several related classes associated with the PropertyTable ^[13] class. First, a PropertyTableModel ^[14] encapsulates all properties that are visualized in the property grid. Each property derives from the Property ^[15] abstract class, which features some common actions to properties, most notably to get and set property value. DefaultProperty ^[16] is a default concrete subclass of Property. Finally, PropertyPane ^[17] decorates a property grid with icons for changing category view to alphabetically sorted view as well as expanding and collapsing categories, and a description text box at the bottom that can be shown or hidden.
Here are the DefaultProperty fields and their respective roles:

Field	Role
Name	Interal property name, not necessarily displayed, used as a key to identify the property.
DisplayName	A short property name shown in the left column of the property grid.
Description	A concise description of the property, shown at the bottom of the property pane, below the grid.
Type	The Java type associated with the property, used to invoke the appropriate renderer or editor.
EditorContext	An editor context object. If set, both the type and the context are used to look up the renderer or editor to use. This lets, for instance, one flag value to display as a true/false label, while another as a checkbox.
Category	A string specifying the property’s category, for grouping purposes.
Editable	Specifies whether the property value is modifiable or read-only.
Value	The current property value, as a Java object.

Just as with any Java object, these fields may either be accessed with the Java get/set semantics (e.g. getName() or setName(name)), or the Matlab get/set semantics (e.g. get(prop,’Name’) or set(prop,’Name’,name)). When using the Matlab syntax, remember to wrap the Java object in a handle() call, to prevent a memory leak ^[18].
To use a property grid in Matlab, first construct a set of DefaultProperty objects. For each object, set at least the name, type and initial value. Next, add the properties to a table model. Finally, construct a property grid with the given table model and encapsulate in a property pane:

% Initialize JIDE's usage within Matlab
com.mathworks.mwswing.MJUtilities.initJIDE;
% Prepare the properties list
list = java.util.ArrayList();
prop1 = com.jidesoft.grid.DefaultProperty();
prop1.setName('stringProp');
prop1.setType(javaclass('char',1));
prop1.setValue('initial value');
prop1.setCategory('My Category');
prop1.setDisplayName('Editable string property');
prop1.setDescription('A concise description for my property.');
prop1.setEditable(true);
list.add(prop1);
prop2 = com.jidesoft.grid.DefaultProperty();
prop2.setName('flagProp');
prop2.setType(javaclass('logical'));
prop2.setValue(true);
prop2.setCategory('My Category');
prop2.setDisplayName('Read-only flag property');
prop2.setEditable(false);
list.add(prop2);
% Prepare a properties table containing the list
model = com.jidesoft.grid.PropertyTableModel(list);
model.expandAll();
grid = com.jidesoft.grid.PropertyTable(model);
pane = com.jidesoft.grid.PropertyPane(grid);
% Display the properties pane onscreen
hFig = figure;
panel = uipanel(hFig);
javacomponent(pane, [0 0 200 200], panel);
% Wait for figure window to close & display the prop value
uiwait(hFig);
disp(prop1.getValue());

Here, com.mathworks.mwswing.MJUtilities.initJIDE is called to initialize JIDE’s usage within Matlab. Without this call, we may see a JIDE warning message in some Matlab releases. We only need to initJIDE once per Matlab session, although there is no harm in repeated calls.
javaclass is a function (included in the Property Grid ^[8] utility, or directly downloadable from here ^[19]) that returns a Java class for the corresponding Matlab type with the given dimension: javaclass(‘logical’) or javaclass(‘logical’,0) (a single logical flag value) returns a java.lang.Boolean class; javaclass(‘char’,1) (a character array) returns a java.lang.String class; javaclass(‘double’,2) (a matrix of double-precision floating point values) returns double[][].
javacomponent is the undocumented built-in Matlab function that adds Java Swing components to a Matlab figure, using the given dimensions and parent handle. When the user closes the figure, prop.getValue() fetches and displays the new property value.

Next week’s article will show how to add more complex renderers and editors (display the flag value as a checkbox for example), define nested properties, and subscribe to property value change events. So stay tuned…

Categories: Guest bloggers, GUI, Java, Medium risk of breaking in future versions, Undocumented feature

17 Comments (Open | Close)

17 Comments To "JIDE Property Grids"

#1 Comment By Jason McMains On April 27, 2010 @ 09:18

This is great! I love finding new ways to display information!

#2 Comment By Simon On April 29, 2010 @ 02:44

Hi,
When executing the code I have a problem when initialising “prop1” wth the DefaultProperty constructor:

com.jidesoft.grid.DefaultProperty()
 ??? Undefined variable "com" or class "com.jidesoft.grid.DefaultProperty".

I’m using Matlab R2007b, it might be linked to this?

Thanks!

#3 Comment By Yair Altman On April 29, 2010 @ 02:46

@Simon – which platform/OS/Java version are you using? i.e., what’s the output of ver in your Matlab Command Prompt?

#4 Comment By Simon On April 29, 2010 @ 03:02

Hhi! Thanks for reactivity!

here is what ‘ver’ gives me:

————————————————————————————-
MATLAB Version 7.5.0.342 (R2007b)
MATLAB License Number: 320981
Operating System: Microsoft Windows XP Version 5.1 (Build 2600: Service Pack 3)
Java VM Version: Java 1.6.0 with Sun Microsystems Inc. Java HotSpot(TM) Client VM mixed mode
————————————————————————————-
MATLAB Version 7.5 (R2007b)
Data Acquisition Toolbox Version 2.11 (R2007b)
Filter Design Toolbox Version 4.2 (R2007b)
Fixed-Point Toolbox Version 2.1 (R2007b)
MATLAB Compiler Version 4.7 (R2007b)
Signal Processing Toolbox Version 6.8 (R2007b)
XML Toolbox for Matlab Version 3.2.0

Trademarks
——————
MATLAB, Simulink, Stateflow, Handle Graphics, Real-Time Workshop, and xPC
TargetBox are registered trademarks and SimBiology, SimEvents, and
SimHydraulics are trademarks of The MathWorks, Inc. Other product or
brand names are trademarks or registered trademarks of their respective
holders.

#5 Comment By Maarten van der Seijs On April 29, 2010 @ 06:54

Simon, I experienced the same with Matlab 2007b. Sadly enough, the DefaultProperty class is not included in the jide-grids.jar that comes with 2007b. There is a class Property, but this an abstract class and you cannot instantiate this without defining a concrete javaclass.

As a rough solution, you may repace the jide .jar files in the folder ‘MATLABROOT\java\jarext\jide’ with the jar-files of for example Matlab 2008b (if you have it), this solves most of the problems. You can also include the jar files using the dynamic javaclasspath; this will add the DefaultProperty, but still gives errors.

However, there should be a way to code the missing concrete classes in addition to the jide package of matlab 2007b. Personally, I would be very interested in such a solution. Perhaps someone with some more Java-skills can enlighten us? Meanwhile I have coded a property-inspector for matlab classes using the open-source package ^[26], but I still have mixed feelings about its capabilities compared to the professional jide tools.

A note to Yair and Levente: as you probably know, the class-structured PropertySheet and PropertyGrid products are not compatible with Matlab 2007b. I think the biggest (but solvable) problems lie in the method and property attributes, for example: replacing qualifiers like (Access = private) by (SetAccess = ‘private’) already solves most of the problems.

#6 Comment By Yair Altman On April 29, 2010 @ 10:22

Thanks for the detailed comments, Maarten

#7 Comment By Jason On May 4, 2010 @ 09:57

Hi Yair,

Can you explain where

javaclass

comes from? I tried

which('javaclass')

but it cannot find anything. I can’t seem to find this on your site in many places, nor is it a submission on the file exchange. I pasted the ver information below. Also, I did try this in R2009b with the same results.

Thanks,
Jason

MATLAB Version 7.10.0.499 (R2010a)
Operating System: Microsoft Windows XP Version 5.1 (Build 2600: Service Pack 3)
Java VM Version: Java 1.6.0_12-b04 with Sun Microsystems Inc. Java HotSpot(TM) Client VM mixed mode

#8 Comment By Yair Altman On May 4, 2010 @ 10:07

@Jason – as explained in the article, javaclass is a function that is included in the ^[27], or directly downloadable from ^[28]. After downloading this Java class, you need to place it in your Java classpath (see javaclasspath).

#9 Comment By Jason On May 4, 2010 @ 10:29

Hi Yair,

My apologies. I thought the explanation for the example was all above the code itself. Leave it to a programmer to read a tutorial “serially”. 🙂

#10 Pingback By Date selection components | Undocumented Matlab On June 29, 2010 @ 23:43

[…] fact that Matlab uses JIDE components for many of its GUI components. As already explained earlier, JIDE controls are pre-bundled in Matlab (/java/jarext/jide/jide-grids.jar under the Matlab root). […]

#11 Comment By Guillaume On August 23, 2011 @ 09:08

Hello,

Thanks a lot for this incredibly helpful blog !

I’ve got a question concerning this “homemade” Property inspector. I’ve been running your example with good results but now I would like my inspector to be resizable. Do you have any idea on how to achieve that ?

Here is my way of doing right now ( adapted last lines of your example ) :

 
% Display the properties pane onscreen
hFig = figure('MenuBar','none',...
              'Position',[200 200 200 300],...
              'Name','My Property Inspector',...
              'NumberTitle','off');
panel = uipanel(hFig,'ResizeFcn',{@propResiz,pane});
javacomponent(pane, [0 0 200 300], panel);
 
% Wait for figure window to close & display the prop value
uiwait(hFig);
disp(prop1.getValue());

function propResiz(src,eventdata,pane)
   pos = get(gcf,'Position');
   javacomponent(pane, [0 0 pos(3) pos(4)], src);
end

But I feel like there must be something better that I can’t see because of my lack of Java and javacomponent knowledge…

Thanks,

Guillaume

#12 Comment By Yair Altman On August 23, 2011 @ 11:11

@Guillaume – use the second output argument returned from javacomponent and simply set its Units property to ‘normalized’ – it should then resize automatically with your figure, without the need for propResize at all:

panel = uipanel(hFig);
[hjPane, hcPane] = javacomponent(pane, [0 0 200 300], panel);
set(hcPane,'Units','norm');

If you do want to keep using ResizeFcn, then you need to fix your code: Each time you use javacomponent in your propResiz function, you are recreating the component container etc. Instead, create the Java pane just once and keep the container handle. Then simply set this container’s Position property in the propResiz function. Something like this:

panel = uipanel(hFig);
[hjPane, hcPane] = javacomponent(pane, [0 0 200 300], panel);
set(panel,'ResizeFcn',{@propResiz,hcPane});

function propResiz(src,eventdata,hcPane)
   pos = getpixelposition(gcf);  % ensure we get it in [pixels]
   set(hcPane, 'Position', [0 0 pos(3) pos(4)]);
end

Additional information on the javacomponent function can be found ^[29].

#13 Pingback By uiinspect | Undocumented Matlab On January 27, 2013 @ 02:14

[…] displays the callbacks data (callbacks property name and value) in a Java table (JIDE PropertyTable, JIDE TreeTable, or failing those a simple JTable). […]

#14 Pingback By propertiesGUI | Undocumented Matlab On January 30, 2013 @ 11:09

[…] 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. […]

#15 Pingback By treeTable | Undocumented Matlab On August 6, 2013 @ 04:25

[…] by Matlab’s inspect function and my generic propertiesGUI utility or Levente Hunyadi’s Property Grid utility. But in this case we wish to display a general multi-column table, so PropertyTable is a […]

#16 Pingback By propertiesGUI | Undocumented Matlab On June 10, 2014 @ 03:13

[…] 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 […]

#17 Comment By Jette On March 28, 2017 @ 13:31

Hello,

we’ve used severeal Jide classes (at least PropertyTableClass and PropertyTable) in our project for quite a long time. Recently, we migrated the project from R2010b to R2015b. Unfortunatly, in R2015b we get a warn dialog while compiling our application. The warning comes frome JIDE Software, Inc. and states “You get this message box because you didn’t input a correct license key. …”.

Do you know if it is possible to compile MATLAB code based on JIDE classes without this warning?

Thanks

Article printed from Undocumented Matlab: https://undocumentedmatlab.com

URL to article: https://undocumentedmatlab.com/articles/jide-property-grids

URLs in this post:

[1] Levente Hunyadi: http://www.mathworks.com/matlabcentral/fileexchange/authors/60898

[2] inspect: http://www.mathworks.com/access/helpdesk/help/techdoc/ref/inspect.html

[3] GUIDE: http://www.mathworks.com/access/helpdesk/help/techdoc/creating_guis/f7-998368.html

[4] Plot Editor: http://www.mathworks.com/access/helpdesk/help/techdoc/creating_plots/f9-47085.html#f9-43456

[5] FindJObj: http://undocumentedmatlab.com/blog/findjobj-gui-display-container-hierarchy/

[6] UIInspect: http://www.mathworks.com/matlabcentral/fileexchange/17935

[7] Image: http://undocumentedmatlab.com/images/findjobj.png

[8] Property Grid: http://www.mathworks.com/matlabcentral/fileexchange/28732

[9] JIDE Software: http://www.jidesoft.com

[10] JTable: http://java.sun.com/docs/books/tutorial/uiswing/components/table.html

[11] Developer Guide: http://www.jidesoft.com/products/JIDE_Grids_Developer_Guide.pdf

[12] Javadoc documentation: http://www.jidesoft.com/javadoc/

[13] PropertyTable: http://www.jidesoft.com/javadoc/com/jidesoft/grid/PropertyTable.html

[14] PropertyTableModel: http://www.jidesoft.com/javadoc/com/jidesoft/grid/PropertyTableModel.html

[15] Property: http://www.jidesoft.com/javadoc/com/jidesoft/grid/Property.html

[16] DefaultProperty: http://www.jidesoft.com/javadoc/com/jidesoft/grid/DefaultProperty.html

[17] PropertyPane: http://www.jidesoft.com/javadoc/com/jidesoft/grid/PropertyPane.html

[18] memory leak: http://undocumentedmatlab.com/blog/uicontrol-callbacks/#memory_leak

[19] here: http://undocumentedmatlab.com/files/javaclass.m

[20] Advanced JIDE Property Grids : https://undocumentedmatlab.com/articles/advanced-jide-property-grids

[21] Using JIDE combo-boxes : https://undocumentedmatlab.com/articles/using-jide-combo-boxes

[22] Setting class property types : https://undocumentedmatlab.com/articles/setting-class-property-types

[23] Getting default HG property values : https://undocumentedmatlab.com/articles/getting-default-hg-property-values

[24] Property value change listeners : https://undocumentedmatlab.com/articles/property-value-change-listeners

[25] Plot LineSmoothing property : https://undocumentedmatlab.com/articles/plot-linesmoothing-property

[26] : http://www.l2fprod.com/common/

[27] : http://www.mathworks.com/matlabcentral/fileexchange/26873

[28] : https://undocumentedmatlab.com/files/javaclass.m

[29] : https://undocumentedmatlab.com/blog/javacomponent/

Click here to print.

Matlab’s property inspector

A simple property grid

Related posts: