- Undocumented Matlab - http://undocumentedmatlab.com -

Customizing editboxes

Posted By Yair Altman On September 25, 2013 | 9 Comments

As a natural follow-up to last week’s article about rich-content log panels [1] (multi-line editbox), today I discuss some additional customizations that can be done to Matlab’s editbox control.

Matlab’s dual editbox controls

There are two distinct uicontrols called ‘editbox’ in Matlab: a single-line editbox and a multi-line editbox. Matlab automatically uses the single-line control if the Max property is set to 1 (the default value, backward compatible with early Matlab versions). If Max > 1, the multi-line editbox is used. Today’s article will focus on features shared by both the single-line and multi-line editbox controls.
Beware of a possible pitfall using Matlab’s editbox controls: when switching styles, including switching between the single-line and multi-line editbox versions, Matlab replaces the underlying Java component with a new component that has default properties. Therefore, if we need any customizations to the uicontrol, then we should ensure that they are done after setting the final uicontrol style, otherwise they will be discarded.

Underlying Java object

As discussed in many prior articles, the first step in customization is to get access to the Matlab control’s underlying Java control. This is done using the findjobj [2] utility:

% Prepare the log editbox
hEditbox = uicontrol('Style','edit', 'String','Matlab', ...);
% Get the underlying Java editbox
jEditbox = findjobj(hLogPanel);
    % Multi-line editboxes are contained within a scroll-panel
    jEditbox = handle(jEditbox.getViewport.getView, 'CallbackProperties');
    % probably a single-line editbox


As I have explained [3] long ago, all uicontrol borders can be customized using the underlying jEditbox handle’s Border property:

% Create a new border
lineColor = java.awt.Color(1,0,0);  % =red
thickness = 3;  % pixels
roundedCorners = true;
newBorder = javax.swing.border.LineBorder(lineColor,thickness,roundedCorners);
% Override the default control's border
jEditbox.Border = newBorder;  % or: set(jEditbox,'Border',newBorder) or: jEditbox.setBorder(newBorder)
% Remove the border altogether
jEditbox.Border = [];
% Redraw the modified control after we have changed its appearance

editbox with regular border
editbox with regular border
editbox with custom border
editbox with custom border
editbox with no border
editbox with no border

Much more complex and interesting borders can be created in much the same way. Interested readers are referred to the official documentation of Java Borders [4] or any decent Swing textbook.

Text selection

Several jEditbox properties control the text-selection functionality:

  • SelectionStart, SelectionEnd control the characters within the displayed text that are selected (typically with some shaded background color). A value of 0 means the first character, 1 means the second character etc. Setting SelectionStart=0 and SelectionEnd=intmax selects the entire text. We can also use jEditbox.select(selectionStart,selectionEnd). For example:
    set(jEditbox, 'SelectionStart',1, 'SelectionEnd',5);
    jEditbox.select(1,5)  % equivalent alternative

    Setting the selected text
    Setting the selected text
  • SelectionColor, SelectedTextColor change the foreground and background colors of the selected text. These properties are overridden whenever the editbox gains focus, so we need to be override them in the editbox’s FocusGainedCallback:
    cbStr = ['set(gcbo,''SelectionColor'',java.awt.Color.red,' ...
    set(jEditbox, 'FocusGainedCallback', cbStr);

    Non-standard selection colors and FocusGainedCallback
    Non-standard selection colors, FocusGainedCallback
  • SelectedText is a read-only property holding the text currently selected, between the SelectionStart and SelectionEnd positions. Associated property Text holds the entire text within the editbox. Note that both these properties hold a java.lang.String object, which should be cast to a Matlab string via Matlab’s built-in char function, unless we use Matlab’s get function (which does this conversion for us automatically):
    str = char(jEditbox.getSelectedText);
    str = get(jEditbox,'SelectedText');  % equivalent alternative

Customizing the input caret

The Caret property, which is common to all Java Swing data-entry components, references a javax.swing.text.DefaultCaret [5] object that controls the text caret appearance (this is naturally relevant only for editable editboxes).
The caret object has its own properties that can be customized. For example: BlinkRateRate, Visible and UpdatePolicy. The caret’s StateChangedCallback is invoked whenever the caret position is updated.
Some additional caret-related properties can be set using jEditbox properties: CaretColor and CaretPosition (which uses 0-based, like SelectionStart and SelectionEnd above). Here is an example that modifies the default caret color to something a bit more lively:

% Set the caret color to red
jEditbox.setCaretColor(java.awt.Color.red);	% an alternative

Red CaretColor
Red CaretColor


Several properties of the jEditbox handle control the editbox behavior beyond what is available by the Matlab uicontrol:

  • Editable – (default=true) a boolean flag indicating whether or not the editbox text can be modified. Note that the Matlab HG handle (hEditbox) only allows setting the Enable property (its jEditbox Java counterpart property is called Enabled), but not to set an enabled yet uneditable control – this can only be done using the Java Editable property.
  • DisabledTextColor controls the text color (default=gray) when the editbox is disabled.
  • DragEnabled – (default=false) a boolean flag indicating whether the editbox contents can be mouse-dragged externally as a DND source (for example, onto an editor, command line or any DND target). The DropMode, DropLocation, DropTarget and TransferHandler properties enable the editbox act as a DND target, accepting externally-dragged data as input sources.
  • FocusAccelerator – (default=char(0)) sets the keyboard accelerator sequence that will cause the receiving text component to get the focus. The accelerator will be the key combination of the <Alt> key and the specified character, converted to upper-case. Any previous key accelerator setting, including menu-bar accelerators, will be superseded. A char(0) key has the effect of turning off the focus accelerator. By default, there is no focus accelerator key (i.e., an accelerator of \0=char(0)). For example, let us set the accelerator to <Alt>-E, overriding the menu-bar’s default accelerator for the Edit menu:
    >> jEditbox.setFocusAccelerator('e');
    >> jEditbox.getFocusAccelerator		% let us check...
    ans =
    E	% 'e' converted to 'E', meaning an Alt-E accelerator

Additional editbox behavior can be customized using the dozens of callback functions that jEditbox exposes. These callbacks enable modifying the appearance and behavior of the editbox based on events such as mouse movements (into/over/out-of), focus gain/loss, key-clicks (that enable input data validation) etc. I plan to describe a data input-validation function based on these callbacks, using some of the customizations shown above, in next week’s article.

Available report – “Advanced Customizations of Matlab Uicontrols”

Interested readers can find more information about these and other possible customizations in my report on “Advanced Customizations of Matlab Uicontrols“. This 90-page PDF report can be purchased here [6] ($29, please allow 24 hours for delivery by email). The report explains how to customize Matlab’s uicontrols in ways that are simply not possible using documented Matlab properties. This includes treatment of push buttons, toggle buttons, radio buttons, checkboxes, editboxes, listboxes, popup menus (aka combo-boxes/drop-downs), sliders, labels, and tooltips. Much of the information in the report is also available in hard-copy format in chapter 6 of my Matlab-Java programming book [7].

Categories: GUI, Java, Low risk of breaking in future versions, UI controls

9 Comments (Open | Close)

9 Comments To "Customizing editboxes"

#1 Pingback By Editable combo-box | Undocumented Matlab On October 9, 2013 @ 08:41

[…] underlying Java control, thereby improving its appearance and functionality. My two previous articles on the Matlab editbox were a classic example of this mechanism. Unfortunately, this technique does […]

#2 Comment By Raj On March 7, 2014 @ 08:23

Hey Yair,
I’ve got a question. Your Text Selection Method works fine! I’ve tried make a search function for my editbox so it can mark(select) every word he found. But the Selection does work only once. Is there no way of multiple selections?

#3 Comment By Yair Altman On March 10, 2014 @ 10:13

@Raj – I do not think that this is supported in a single-line editbox, but you can always use a multi-line editbox or listbox.

#4 Comment By Raj On March 12, 2014 @ 01:39

of course i meant multiline editbox 🙂 I figured it out myself with the addHighlight method of jEditbox 🙂
Thanks anyway

#5 Comment By Nipurn Jain On March 13, 2018 @ 08:57

How to determine cursor position in ‘edit’ uicontrol?

I have an application where there are several buttons that apply a specific function to the data. The user can also enter values in the edit box. However if the cursor is positioned in the edit box and a button is pressed the new function will appear at the end of the edit box and I need that this appear at cursor position how to do this?
Is it possible by using javaframe available on matlab?

#6 Comment By Yair Altman On March 13, 2018 @ 10:45

@Nipurn – yes this is possible using [14]:

hEditbox = uicontrol('style','edit', ...); drawnow
jEditbox = findjobj(hEditbox);
try jEditbox = jEditbox.getViewport.getView; end  % in case it's a multi-line editbox
caretPos = jEditbox.getCaretPosition;  % or: =get(jEditbox,'CaretPosition');

There’s also a corresponding setCaretPosition(position) method.
See related: [15]

#7 Comment By David On May 8, 2018 @ 18:08

Is there anyway to get this to work with app designer? I can’t seem to find any java objects in app designer and I am not sure if there is a way that I just don’t know about.

#8 Comment By Yair Altman On May 8, 2018 @ 18:36

@David – almost all the GUI customizations described in this blog relate only to the legacy (Java-based) figures. AppDesigner-created figures (so-called “uifigures”) are web-based HTML pages displayed in a browser window, which is an entirely different technology. To customize uifigure controls see the series of posts on uifigure customization: [16]

#9 Comment By David On May 8, 2018 @ 18:42

Hi Yair,

Thanks for the quick reply. I will take a look!

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

URL to article: http://undocumentedmatlab.com/articles/customizing-editboxes

URLs in this post:

[1] rich-content log panels: http://undocumentedmatlab.com/blog/rich-contents-log-panel/

[2] findjobj: http://undocumentedmatlab.com/blog/findjobj-find-underlying-java-object/

[3] explained: http://undocumentedmatlab.com/blog/customizing-uicontrol-border/

[4] official documentation of Java Borders: http://docs.oracle.com/javase/tutorial/uiswing/components/border.html

[5] javax.swing.text.DefaultCaret: http://docs.oracle.com/javase/6/docs/api/javax/swing/text/DefaultCaret.html

[6] here: https://www.paypal.com/cgi-bin/webscr?cmd=_xclick&currency_code=USD&business=altmany@gmail.com&amount=29&item_name=Matlab+uicontrols+customization+report

[7] Matlab-Java programming book: http://undocumentedmatlab.com/matlab-java-book/

[8] Customizing menu items part 2 : http://undocumentedmatlab.com/articles/customizing-menu-items-part-2

[9] Customizing Matlab labels : http://undocumentedmatlab.com/articles/customizing-matlab-labels

[10] Setting line position in an edit-box uicontrol : http://undocumentedmatlab.com/articles/setting-line-position-in-edit-box-uicontrol

[11] Customizing listbox & editbox scrollbars : http://undocumentedmatlab.com/articles/customizing-listbox-editbox-scrollbars

[12] Customizing combobox popups : http://undocumentedmatlab.com/articles/customizing-combobox-popups

[13] Customizing listbox/combobox items : http://undocumentedmatlab.com/articles/customizing-listbox-combobox-items

[14] : https://undocumentedmatlab.com/blog/findjobj-find-underlying-java-object

[15] : https://undocumentedmatlab.com/blog/setting-line-position-in-edit-box-uicontrol

[16] : https://undocumentedmatlab.com/blog/tag/uifigure

Copyright © Yair Altman - Undocumented Matlab. All rights reserved.