A few days ago, a CSSM forum reader asked how to modify Matlab’s listbox scrollbars. Another user asked how to configure line-wrapping. I thought this is a good opportunity to describe how listbox and editbox scrollbars can be customized. The timing is particularly opportune, after I have recently described how the Matlab Editbox can be customized by accessing its underlying Java object using the FindJObj utility.
Both the listbox and the multi-line editbox uicontrols share a similar design: a multi-line Java control embedded within a JViewport within a JScrollPane (note that for historical reasons, the Java view-port class is called JViewport rather than the more standard camel-cased JViewPort). In addition to the view-port, the containing scroll-pane also contains two scrollbars (horizontal and vertical), as expected from standard Java scroll-panes.
JScrollPane components
Scrollbar policies
Control of the scroll-pane’s scrollbar behavior is done via the JScrollPane’s VerticalScrollBarPolicy and HorizontalScrollBarPolicy properties.
VerticalScrollBarPolicy accepts the self-explanatory values of:
- VERTICAL_SCROLLBAR_ALWAYS (=22)
- VERTICAL_SCROLLBAR_NEVER (=21)
- and VERTICAL_SCROLLBAR_AS_NEEDED (=20)
HorizontalScrollBarPolicy accepts:
- HORIZONTAL_SCROLLBAR_ALWAYS (=32)
- HORIZONTAL_SCROLLBAR_NEVER (=31)
- and HORIZONTAL_SCROLLBAR_AS_NEEDED (=30)
All these properties are static enumerated constants that can be referred using either their Java notation (e.g., JScrollPane.VERTICAL_SCROLLBAR_ALWAYS) or their equivalent numeric values. Using the non-numeric format is better, since it is more readable and the numeric values may change, but the choice is yours.
By default, Matlab implements a VerticalScrollBarPolicy of VERTICAL_SCROLLBAR_ALWAYS for sufficiently tall uicontrols (>20-25 pixels, which practically means always) and VERTICAL_SCROLLBAR_NEVER for shorter uicontrols.
For the horizontal scrollbar, Matlab implements a HorizontalScrollBarPolicy of HORIZONTAL_SCROLLBAR_NEVER for all editboxes and for narrow listboxes (<35 pixels), and HORIZONTAL_SCROLLBAR_AS_NEEDED for wide listboxes.
These settings are generally satisfactory. However, in some cases users may wish to modify the settings. For example, the default VerticalScrollBarPolicy setting of VERTICAL_SCROLLBAR_ALWAYS causes the vertical scrollbar to appear even when unneeded (the entire editbox content is visible). Also, we may wish to have a horizontal scrollbar on narrow listboxes and editboxes, something that the standard HORIZONTAL_SCROLLBAR_NEVER prevents. In both cases, a *_SCROLLBAR_AS_NEEDED policy might be more appropriate.
To modify these settings, we simply need to get the uicontrol’s underlying Java reference handle (using the FindJObj utility), and modify the appropriate property. For example:
% Create a multi-line (Max>1) editbox uicontrol hEditbox = uicontrol('style','edit', 'max',5, ...); % Get the Java scroll-pane container reference jScrollPane = findjobj(hEditbox); % Modify the scroll-pane's scrollbar policies % (note the equivalent alternative methods used below) set(jScrollPane,'VerticalScrollBarPolicy',20); % or: jScrollPane.VERTICAL_SCROLLBAR_AS_NEEDED jScrollPane.setHorizontalScrollBarPolicy(30); % or: jScrollPane.HORIZONTAL_SCROLLBAR_AS_NEEDED
default scrollbars (VERTICAL_SCROLLBAR_ALWAYS)
non-default scrollbars (VERTICAL_SCROLLBAR_AS_NEEDED)
Note that updating the uicontrol handle (hEditbox)’s Position property has the side-effect of automatically reverting the scrollbar policies to their default values (HORIZONTAL_SCROLLBAR_NEVER and VERTICAL_SCROLLBAR_ALWAYS/NEVER). This also happens whenever the uicontrol is resized interactively (by resizing its container figure window, for example). It is therefore advisable to set jScrollPane’s ComponentResizedCallback property to “unrevert” the policies:
cbStr = sprintf('set(gcbo,''VerticalScrollBarPolicy'',%d)', ... jScrollPane.VERTICAL_SCROLLBAR_AS_NEEDED); hjScrollPane = handle(jScrollPane,'CallbackProperties'); set(hjScrollPane,'ComponentResizedCallback',cbStr);
Line-wrapping
By default, line-wrapping is turned on, effectively disabling horizontal scrolling (which is why Matlab set the HorizontalScrollBarPolicy to HORIZONTAL_SCROLLBAR_NEVER. However, in some cases it may be more useful to turn line-wrapping off and horizontal scrolling on using the TextArea’s setWrapping() method. Here’s a usage example:
jViewPort = jScrollPane.getViewport; jEditbox = jViewPort.getComponent(0); jEditbox.setWrapping(false); % do *NOT* use set(...)!!! newPolicy = jScrollPane.HORIZONTAL_SCROLLBAR_AS_NEEDED; set(jScrollPane,'HorizontalScrollBarPolicy',newPolicy);
multi-line editbox with wrapping on
multi-line editbox with wrapping off
Notes:
- setWrapping() only works for the default EditorKit, and fails for HTMLEditorKit – This is due to HTML’s inherent wrapping behavior, as can easily be seen in any browser webpage.
- while setWrapping() may seem like a regular setter method for a Wrapping property, in reality it is not. Actually, set(jEditbox,’wrapping’,flag) may crash Matlab. So, always use the setWrapping(flag) method variant, which is entirely safe.
Related posts:
- Rich Matlab editbox contents The Matlab editbox uicontrol does not handle HTML contents as do other uicontrols. In this article I show how this limitation can be removed....
- Setting listbox mouse actions Matlab listbox uicontrol can be modified to detect mouse events for right-click context menus, dynamic tooltips etc....
- Customizing uicontrol border Matlab uicontrol borders can easily be modified - this article shows how...
- Customizing Matlab labels Matlab's text uicontrol is not very customizable, and does not support HTML or Tex formatting. This article shows how to display HTML labels in Matlab and some undocumented customizations...
- Customizing uitree nodes – part 2 This article shows how Matlab GUI tree nodes can be customized with checkboxes and similar controls...
- Customizing uitree This article describes how to customize Matlab GUI tree controls created using the undocumented uitree function...
I’m trying to turn off the ‘always on’ behavior of the vertical scrollbar in an edit control when I’ve made it multiline.
I also tried jScrollPane.VERTICAL_SCROLLBAR_NEVER in place of the 21, but am getting this error:
??? There is no ‘VerticalScrollBarPolicy’ property in the
‘com.mathworks.hg.peer.EditTextPeer$hgTextField’ class.
Any suggestions? I downloaded and added findjobj to my path. Is there some other m-file I’m missing?
EditTextPeer$hgTextField is the single-line edit-box component, which does not have scrollbars. This is expected, since you ran findjobj immediately after creating your editbox as a single-line control. To turn the control to multi-line, you need to set the control’s Max property to a value greater than 1. If you now run findjobj you’ll see EditTextPeer$hgTextEditMultiline, which does indeed contain scrollbars.
Found the answer. Well, first I was trying to do this on the wrong edit control in my code – needed to do it on a multiline edit control.
Second, when using the findjobj, it returned a 1×2 matrix of objects. Turned out the UIScrollPane was the second object in the matrix, so to set the scrollbar, I did:
Of note, Matlab said “No appropriate method, property, or field … when I tried to use jScrollPane(2).VERTICAL_SCROLLBAR_AS_NEVER instead of 21.
Thanks Yair. Sorry I didn’t see your post before I posted my final solution. I didn’t mean to seem ungrateful for your response.
@Carrie – it’s VERTICAL_SCROLLBAR_NEVER (without the “_AS_”). Only VERTICAL_SCROLLBAR_AS_NEEDED has an “_AS_”.
Sorry. Just a typo in my post. I tried …AS_NEEDED and …_NEVER in my code – no luck, but the numbers work great. Thanks.
i tryed this code, for horizontal scrollbar,
but am getting this error:
?? No appropriate method, property, or field HORIZONTAL_SCROLLBAR_AS_NEEDED for class javahandle_withcallbacks.com.mathworks.hg.peer.utils.UIScrollPane.
Error in ==> blblblb at 8
newPolicy = jScrollPane.HORIZONTAL_SCROLLBAR_AS_NEEDED;
@Camilo – it would help to know which Matlab version, Java version and OS you have – in short, the output of the ver function in your Matlab command prompt.
In the meantime, you can try Carrie’s solution above – simply use the number 30 instead of jScrollPane.HORIZONTAL_SCROLLBAR_AS_NEEDED
Hi Yair,
It works only half for me, hopefully you can point me in the correct direction. Currently working with :
———————————————————————————–
MATLAB Version 7.4.0.287 (R2007a)
Operating System: Microsoft Windows XP Version 5.1 (Build 2600: Service Pack 3)
Java VM Version: Java 1.5.0_07 with Sun Microsystems Inc. Java HotSpot(TM) Client VM mixed mode
———————————————————————————–
For testing I put a button and edit on a figure in GUIDE, I have a function to change the properties of the edit:
I used the integer-values for the scrollbars because the named constants are not part of the Java object.
Problem: when I call the above function from the button-callback, then it works. But this is not what I want, I want that when the figure is made visible, the scrollbars are automatically OK. So what I tried:
1) call ‘set_edit_props’ from edit create-callback:
jScrollPane =
handle: 0-by-0
No appropriate method or public field getViewport for class handle.handle.
2) call ‘set_edit_props’ after a 2 secs delay (timer-object) started within edit create-callback (try to let everything become visible before access is requested):
jScrollPane =
handle: 1-by-0
No appropriate method or public field getViewport for class handle.handle.
3) call ‘set_edit_props’ from OpeningFcn: result as with 2)
4) call ‘set_edit_props’ via timer from OpeningFcn: result as with 1) (!)
Nothing works. Maybe you have some ideas….
Regards,
Jeroen
@Jeroen – It doesn’t work in your creation callbacks because the figure is not yet visible at that point and findjobj requires a visible figure to find the underlying Java handles. This is why you see an empty handle list. This is also the reason it doesn’t work in your _OpeningFcn() function. Instead, place your code in the _OutputFcn() function, which is called immediately after the figure becomes visible.
@Carrie, @Camilo and others: If you get an error when you try to use the enumerated (non-numeric) policy values, then you can simply cast the Matlab handle() of the Java reference back into a Java reference. For example:
Alternately, as mentioned above, you can always use the numeric values of these enumerated policies. They are less readable/maintainable, but they always work
Hello Yair,
I show three edit text boxes. I want that when you move the first one`s slider( so you get the text from the line 12, for example) the other two show the text from the same line as the first one.
Do you know any way to do so?
Thanks,
Gonzalo
@Gonzalo – you can do this in the callback function for the slider. If you need help in this development (for a fee), then contact me offline using the email link at the top-left of this page.
I want maintain the scroll bar with respect to my matching text .For example in my page if there is Adeel in first existance than the scroll bar set on this Index. Please help me out
Hi Sir,
I am using Matlab 7.6.0(R2008a). When i used the same code for multiline edit, i am getting the following error:
??? Undefined function or method ‘findjobj’ for input arguments of type ‘double’.
I sincerely request your help to get rid of this problem.
And also how to make the display window to span across the entire screen?
Thank you.
@Charan – you need to download the findjobj utility from the Matlab File exchange (link). See a detailed explanation here.
Regarding window maximization, read here.
Hi Sir,
Thanks a lot for your “jet” reply.
I downloaded findjobj and now working fine. I am able to maximize the figure window also.
But still there persists a small problem.
The horizontal scroll bar is getting visible only after i press “Maximize” button in the control box (located on the top right hand corner); otherwise it is not visible, eventhough the text is crossing.
Thank you
Charan
Hi Yair,
I would like to stop a uitable from automatically scrolling back to the top after a cell has been edited in the table – instead staying at the same viewing position.
How would I go about doing this?
Many thanks,
Ben
By updating the cell at the Java level rather than updating the uitable’s Data property