As a natural follow-up to last week’s article about rich-content log panels (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 utility:
% Prepare the log editbox hEditbox = uicontrol('Style','edit', 'String','Matlab', ...); % Get the underlying Java editbox jEditbox = findjobj(hLogPanel); try % Multi-line editboxes are contained within a scroll-panel jEditbox = handle(jEditbox.getViewport.getView, 'CallbackProperties'); catch % probably a single-line editbox end |
Borders
As I have explained 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 jEditbox.repaint; |
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 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
- 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,' ... '''SelectedTextColor'',java.awt.Color.blue)']; set(jEditbox, 'FocusGainedCallback', cbStr);
- 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 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(1.0,0,0)); jEditbox.setCaretColor(java.awt.Color.red); % an alternative |
Behavior
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 (itsjEditbox
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 ($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.
[…] 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 […]
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?
Greetings
@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.
Hi,
of course i meant multiline editbox 🙂 I figured it out myself with the addHighlight method of jEditbox 🙂
Thanks anyway
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?
@Nipurn – yes this is possible using findjobj:
There’s also a corresponding
setCaretPosition(position)
method.See related: https://undocumentedmatlab.com/blog/setting-line-position-in-edit-box-uicontrol
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.
@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: https://undocumentedmatlab.com/blog/tag/uifigure
Hi Yair,
Thanks for the quick reply. I will take a look!