Undocumented Matlab
  • SERVICES
    • Consulting
    • Development
    • Training
    • Gallery
    • Testimonials
  • PRODUCTS
    • IQML: IQFeed-Matlab connector
    • IB-Matlab: InteractiveBrokers-Matlab connector
    • EODML: EODHistoricalData-Matlab connector
    • Webinars
  • BOOKS
    • Secrets of MATLAB-Java Programming
    • Accelerating MATLAB Performance
    • MATLAB Succinctly
  • ARTICLES
  • ABOUT
    • Policies
  • CONTACT
  • SERVICES
    • Consulting
    • Development
    • Training
    • Gallery
    • Testimonials
  • PRODUCTS
    • IQML: IQFeed-Matlab connector
    • IB-Matlab: InteractiveBrokers-Matlab connector
    • EODML: EODHistoricalData-Matlab connector
    • Webinars
  • BOOKS
    • Secrets of MATLAB-Java Programming
    • Accelerating MATLAB Performance
    • MATLAB Succinctly
  • ARTICLES
  • ABOUT
    • Policies
  • CONTACT

Matlab toolstrip – part 8 (galleries)

February 3, 2019 5 Comments

In previous posts I showed how we can create custom Matlab app toolstrips using various controls (buttons, checkboxes, drop-downs, lists etc.). Today I will show how we can incorporate gallery panels into our Matlab toolstrip.

Toolstrip Gallery (in-line & drop-down)

Toolstrips can be a bit complex to develop so I’m proceeding slowly, with each post in the miniseries building on the previous posts. I encourage you to review the earlier posts in the Toolstrip miniseries before reading this post.

Also, remember to add the following code snippet at the beginning of your code so that the relevant toolstrip classes will be recognized by Matlab:

import matlab.ui.internal.toolstrip.*

import matlab.ui.internal.toolstrip.*

Gallery sub-components

Toolstrip gallery popup components
Toolstrip gallery popup components
Toolstrip galleries are panels of buttons (typically large icons with an attached text label), which are grouped in “categories”. The gallery content can be presented either in-line within the toolstrip (a Gallery control), or as a drop-down button’s popup panel (a DropDownGalleryButton control). In either case, the displayed popup panel is a GalleryPopup object, that is composed of one or more GalleryCategory, each of which has one or more GalleryItem (push-button) and/or ToggleGalleryItem (toggle-button).

  • Gallery or DropDownGalleryButton
    • GalleryPopup
      • GalleryCategory
        • GalleryItem or ToggleGalleryItem
        • GalleryItem or ToggleGalleryItem
        • …
      • GalleryCategory
      • …


For a demonstration of toolstrip Galleries, see the code files in %matlabroot%/toolbox/matlab/toolstrip/+matlab/+ui/+internal/+desktop/, specifically showcaseToolGroup.m and showcaseBuildTab_Gallery.m.

GalleryPopup

We first create the GalleryPopup object, then add to it a few GalleryCategory groups of GalleryItem, ToggleGalleryItem buttons. In the example below, we use a ButtonGroup to ensure that only a single ToggleGalleryItem button is selected:

import matlab.ui.internal.toolstrip.*
popup = GalleryPopup('ShowSelection',true);
% Create gallery categories
cat1 = GalleryCategory('CATEGORY #1 SINGLE'); popup.add(cat1);
cat2 = GalleryCategory('CATEGORY #2 SINGLE'); popup.add(cat2);
cat3 = GalleryCategory('CATEGORY #3 SINGLE'); popup.add(cat3);
% Create a button-group to control item selectability
group = matlab.ui.internal.toolstrip.ButtonGroup;
% Add items to the gallery categories
fpath = [fullfile(matlabroot,'toolbox','matlab','toolstrip','web','image') filesep];  % icons path
item1 = ToggleGalleryItem('Biology', Icon([fpath 'biology_app_24.png']), group);
item1.Description = 'Select the Biology gizmo';
item1.ItemPushedFcn = @(x,y) ItemPushedCallback(x,y);
cat1.add(item1);
item2 = ToggleGalleryItem('Code Generation', Icon([fpath 'code_gen_app_24.png']), group);
cat1.add(item2);
item3 = ToggleGalleryItem('Control', Icon([fpath 'control_app_24.png']), group);
cat1.add(item3);
item4 = ToggleGalleryItem('Database', Icon([fpath 'database_app_24.png']), group);
cat1.add(item4);
...

import matlab.ui.internal.toolstrip.* popup = GalleryPopup('ShowSelection',true); % Create gallery categories cat1 = GalleryCategory('CATEGORY #1 SINGLE'); popup.add(cat1); cat2 = GalleryCategory('CATEGORY #2 SINGLE'); popup.add(cat2); cat3 = GalleryCategory('CATEGORY #3 SINGLE'); popup.add(cat3); % Create a button-group to control item selectability group = matlab.ui.internal.toolstrip.ButtonGroup; % Add items to the gallery categories fpath = [fullfile(matlabroot,'toolbox','matlab','toolstrip','web','image') filesep]; % icons path item1 = ToggleGalleryItem('Biology', Icon([fpath 'biology_app_24.png']), group); item1.Description = 'Select the Biology gizmo'; item1.ItemPushedFcn = @(x,y) ItemPushedCallback(x,y); cat1.add(item1); item2 = ToggleGalleryItem('Code Generation', Icon([fpath 'code_gen_app_24.png']), group); cat1.add(item2); item3 = ToggleGalleryItem('Control', Icon([fpath 'control_app_24.png']), group); cat1.add(item3); item4 = ToggleGalleryItem('Database', Icon([fpath 'database_app_24.png']), group); cat1.add(item4); ...

Single-selection GalleryPopup (icon view)
Single-selection GalleryPopup (icon view)

Note that in a real-world situation, we’d assign a Description, Tag and ItemPushedFcn to all gallery items. This was elided from the code snippet above for readability, but should be part of any actual GUI. The Description only appears as tooltip popup in icon-view (shown above), but appears as a visible label in list-view (see below).

Gallery items selection: push-button action, single-selection toggle, multiple selection toggle

If we use ToggleGalleryItem without a ButtonGroup, multiple gallery items can be selected, rather than just a single selection as shown above:

...
item1 = ToggleGalleryItem('Biology', Icon([fpath 'biology_app_24.png']));item1.Description = 'Select the Biology gizmo';
item1.ItemPushedFcn = @(x,y) ItemPushedCallback(x,y);
cat1.add(item1);
item2 = ToggleGalleryItem('Code Generation', Icon([fpath 'code_gen_app_24.png']));
cat1.add(item2);item3 = ToggleGalleryItem('Control', Icon([fpath 'control_app_24.png']));
cat1.add(item3);
item4 = ToggleGalleryItem('Database', Icon([fpath 'database_app_24.png']));cat1.add(item4);
...

... item1 = ToggleGalleryItem('Biology', Icon([fpath 'biology_app_24.png'])); item1.Description = 'Select the Biology gizmo'; item1.ItemPushedFcn = @(x,y) ItemPushedCallback(x,y); cat1.add(item1); item2 = ToggleGalleryItem('Code Generation', Icon([fpath 'code_gen_app_24.png'])); cat1.add(item2); item3 = ToggleGalleryItem('Control', Icon([fpath 'control_app_24.png'])); cat1.add(item3); item4 = ToggleGalleryItem('Database', Icon([fpath 'database_app_24.png'])); cat1.add(item4); ...

Multiple-selection GalleryPopup (icon view)
Multiple-selection GalleryPopup (icon view)

Alternatively, if we use GalleryItem instead of ToggleGalleryItem, the gallery items would be push-buttons rather than toggle-buttons. This enables us to present a gallery of single-action state-less push-buttons, rather than state-full toggle-buttons. The ability to customize the gallery items as either state-less push-buttons or single/multiple toggle-buttons supports a wide range of application use-cases.

Customizing the GalleryPopup

Properties that affect the GalleryPopup appearance are:

  • DisplayState – initial display mode of gallery items (string; default=’icon_view’, valid values: ‘icon_view’,’list_view’)
  • GalleryItemRowCount – number of rows used in the display of the in-line gallery (integer; default=1, valid values: 0,1,2). A Value of 2 should typically be used with a small icon and GalleryItemWidth (see below)
  • GalleryItemTextLineCount – number of rows used for display of the item label (integer; default=2, valid values: 0,1,2)
  • ShowSelection – whether or not to display the last-selected item (logical; default=false). Needs to be true for Gallery and false for DropDownGalleryButton.
  • GalleryItemWidth – number of pixels to allocate for each gallery item (integer, hidden; default=80)
  • FavoritesEnabled – whether or not to enable a “Favorites” category (logical, hidden; default=false)

All of these properties are defined as private in the GalleryPopup class, and can only be specified during the class object’s construction. For example, instead of the default icon-view, we can display the gallery items as a list, by setting the GalleryPopup‘s DisplayState property to 'list_view' during construction:

popup = GalleryPopup('DisplayState','list_view');

popup = GalleryPopup('DisplayState','list_view');

GalleryPopup (list view)
GalleryPopup (list view)

Switching from icon-view to list-view and back can also be done by clicking the corresponding icon near the popup’s top-right corner (next to the interactive search-box).

Gallery and DropDownGalleryButton

Now that we have prepared GalleryPopup, let’s integrate it in our toolstrip.
We have two choices — either in-line within the toolstrip section (using Gallery), or as a compact drop-down button (using DropDownGalleryButton):

% Inline gallery
section = hTab.addSection('Multiple Selection Gallery');
column = section.addColumn();
popup = GalleryPopup('ShowSelection',true);
% add the GalleryPopup creation code above
gallery = Gallery(popup, 'MinColumnCount',2, 'MaxColumnCount',4);
column.add(gallery);
% Drop-down gallery
section = hTab.addSection('Drop Down Gallery');
column = section.addColumn();
popup = GalleryPopup();
% add the GalleryPopup creation code above
button = DropDownGalleryButton(popup, 'Examples', Icon.MATLAB_24);
button.MinColumnCount = 5;
column.add(button);

% Inline gallery section = hTab.addSection('Multiple Selection Gallery'); column = section.addColumn(); popup = GalleryPopup('ShowSelection',true); % add the GalleryPopup creation code above gallery = Gallery(popup, 'MinColumnCount',2, 'MaxColumnCount',4); column.add(gallery); % Drop-down gallery section = hTab.addSection('Drop Down Gallery'); column = section.addColumn(); popup = GalleryPopup(); % add the GalleryPopup creation code above button = DropDownGalleryButton(popup, 'Examples', Icon.MATLAB_24); button.MinColumnCount = 5; column.add(button);

Toolstrip Gallery (in-line & drop-down)

Clicking any of the drop-down (arrow) widgets will display the associated GalleryPopup.
The Gallery and DropDownGalleryButton objects have several useful settable properties:

  • Popup – a GalleryPopup object handle, which is displayed when the user clicks the drop-down (arrow) widget. Only settable in the constructor, not after object creation.
  • MinColumnCount – minimum number of item columns to display (integer; default=1). In Gallery, this property is only settable in the constructor, not after object creation; if not enough width is available to display these columns, the control collapses into a drop-down. In DropDownGalleryButton, this property can be set even after object creation (despite incorrect internal documentation), and controls the width of the popup panel.
  • MaxColumnCount – maximal number of items columns to display (integer; default=10). In Gallery, this property is only settable in the constructor, not after object creation. In DropDownGalleryButton, this property can be set even after object creation but in any case seems to have no visible effect.
  • Description – tooltip text displayed when the mouse hovers over the Gallery area (outside the area of the internal gallery items, which have their own individual Descriptions), or over the DropDownGalleryButton control.
  • TextOverlay – a semi-transparent text label overlaid on top of the gallery panel (string, default=”). Only available in Gallery, not DropDownGalleryButton.

For example:

gallery = Gallery(popup, 'MinColumnCount',2, 'MaxColumnCount',4);
gallery.TextOverlay = 'Select from these items';

gallery = Gallery(popup, 'MinColumnCount',2, 'MaxColumnCount',4); gallery.TextOverlay = 'Select from these items';

Effect of TextOverlay
Effect of TextOverlay

Toolstrip miniseries roadmap

The next post will discuss popup forms. These are similar in concept to galleries, in the sense that when we click the drop-down widget a custom popup panel is displayed. In the case of a popup form, this is a fully-customizable Matlab GUI figure.
Following that, I plan to discuss toolstrip collapsibility, the Toolpack framework, docking layout, DataBrowser panel, QAB (Quick Access Bar), underlying Java controls, and adding toolstrips to figures – not necessarily in this order.
Matlab toolstrips can be a bit complex, so I plan to proceed in small steps, each post building on top of its predecessors.
If you would like me to assist you in building a custom toolstrip or GUI for your Matlab program, please let me know.

Related posts:

  1. Matlab toolstrip – part 7 (selection controls) – Matlab toolstrips can contain a wide variety of selection controls: popups, combo-boxes, and galleries. ...
  2. Matlab toolstrip – part 6 (complex controls) – Multiple types of customizable controls can be added to Matlab toolstrips...
  3. Matlab toolstrip – part 9 (popup figures) – Custom popup figures can be attached to Matlab GUI toolstrip controls. ...
  4. Matlab toolstrip – part 5 (icons) – Icons can be specified in various ways for toolstrip controls and the app window itself. ...
  5. Matlab toolstrip – part 4 (control customization) – Matlab toolstrip components (controls) can be customized in various ways, including user-defined callbacks. ...
  6. Matlab toolstrip – part 3 (basic customization) – Matlab toolstrips can be created and customized in a variety of ways. ...
Figure GUI Toolstrip Undocumented feature
Print Print
« Previous
Next »
5 Responses
  1. gep February 4, 2019 at 12:33 Reply

    Hello and thank you for all the toolstrip tips 🙂

    I have one question w.r.t. to performance: assuming a gui app, not based on GUIDE, which is fairly optimized (I am following your advice/books for years), is there a significant overhead converting/using a toolstrip?

    • Yair Altman February 4, 2019 at 12:40 Reply

      @Gep – yes, apps and toolstrip take a few seconds to render before being ready. This is noticeably slower than corresponding legacy (Java-based figure) GUIs. Hopefully the performance will improve in future Matlab releases.

      That being said, apps and toolstrips provide a radically different way for UI interactivity than the legacy GUI, and the performance impact might well be offset by the sleek-looking appearance. This tradeoff is not much different from that of AppDesigner-vs.-GUIDE — AppDesigner-created uifigures display much more polished UIs than GUIDE, yet are significantly slower to render.

      The big benefit here is that you have a choice. You can decide for yourself, based on your specific needs and aesthetic preferences, whether to base your GUI on (1) pure legacy figures, or (2) a combination of apps/toolstrips/figures, or (3) pure AppDesigner/uifigures. I am a strong advocate of not hiding the full set of available tools from users, and letting users decide for themselves what’s best for them.

      • Gep February 4, 2019 at 13:25

        Thank you for your answer.
        Except the initial performance hit you mentioned when rendering the figure with toolstrip for the first time, is there also a UI response degradation while using/updating the figure axes/contents assuming option 1 (pure legacy figures) ?

      • Yair Altman February 4, 2019 at 13:29

        I think the only major performance hit is in the initial rendering. I did not notice any sluggishness when updating the internal figures, but I never ran a thorough benchmark.

      • Gep February 4, 2019 at 13:47

        Can’t thank you enough for your quick response.
        Hope the api doesn’t change much so we can play as long as possible 🙂

Leave a Reply
HTML tags such as <b> or <i> are accepted.
Wrap code fragments inside <pre lang="matlab"> tags, like this:
<pre lang="matlab">
a = magic(3);
disp(sum(a))
</pre>
I reserve the right to edit/delete comments (read the site policies).
Not all comments will be answered. You can always email me (altmany at gmail) for private consulting.

Click here to cancel reply.

Useful links
  •  Email Yair Altman
  •  Subscribe to new posts (email)
  •  Subscribe to new posts (feed)
  •  Subscribe to new posts (reader)
  •  Subscribe to comments (feed)
 
Accelerating MATLAB Performance book
Recent Posts

Speeding-up builtin Matlab functions – part 3

Improving graphics interactivity

Interesting Matlab puzzle – analysis

Interesting Matlab puzzle

Undocumented plot marker types

Matlab toolstrip – part 9 (popup figures)

Matlab toolstrip – part 8 (galleries)

Matlab toolstrip – part 7 (selection controls)

Matlab toolstrip – part 6 (complex controls)

Matlab toolstrip – part 5 (icons)

Matlab toolstrip – part 4 (control customization)

Reverting axes controls in figure toolbar

Matlab toolstrip – part 3 (basic customization)

Matlab toolstrip – part 2 (ToolGroup App)

Matlab toolstrip – part 1

Categories
  • Desktop (45)
  • Figure window (59)
  • Guest bloggers (65)
  • GUI (165)
  • Handle graphics (84)
  • Hidden property (42)
  • Icons (15)
  • Java (174)
  • Listeners (22)
  • Memory (16)
  • Mex (13)
  • Presumed future risk (394)
    • High risk of breaking in future versions (100)
    • Low risk of breaking in future versions (160)
    • Medium risk of breaking in future versions (136)
  • Public presentation (6)
  • Semi-documented feature (10)
  • Semi-documented function (35)
  • Stock Matlab function (140)
  • Toolbox (10)
  • UI controls (52)
  • Uncategorized (13)
  • Undocumented feature (217)
  • Undocumented function (37)
Tags
ActiveX (6) AppDesigner (9) Callbacks (31) Compiler (10) Desktop (38) Donn Shull (10) Editor (8) Figure (19) FindJObj (27) GUI (141) GUIDE (8) Handle graphics (78) HG2 (34) Hidden property (51) HTML (26) Icons (9) Internal component (39) Java (178) JavaFrame (20) JIDE (19) JMI (8) Listener (17) Malcolm Lidierth (8) MCOS (11) Memory (13) Menubar (9) Mex (14) Optical illusion (11) Performance (78) Profiler (9) Pure Matlab (187) schema (7) schema.class (8) schema.prop (18) Semi-documented feature (6) Semi-documented function (33) Toolbar (14) Toolstrip (13) uicontrol (37) uifigure (8) UIInspect (12) uitools (20) Undocumented feature (187) Undocumented function (37) Undocumented property (20)
Recent Comments
  • Santiago (13 days 4 hours ago): It works perfectly. Thanks so much.
  • Yair Altman (13 days 9 hours ago): Santiago – you can get the mouse X,Y positions from the Java eventData object (getX(), getY()), convert this into a point (p=java.awt.Point(x,y)), then use the JTable...
  • Santiago (14 days 1 hour ago): Hi Yair. I’m using the MouseReleasedCallback but I need to get the indices of the selected cell. I can get them without problems with left clicks but, if I try to do it with...
  • Yair Altman (32 days 5 hours ago): Adam – perhaps there is a builtin syntax-pane control for uifigures, but I am not aware of one. Perhaps you can try to implement a uihtml panel with a GeSHi...
  • Yair Altman (32 days 5 hours ago): Marcel – 12 years and ~25 releases since I wrote this article, it is no surprise at all that some things no longer work the same way. In fact, the surprising thing is that...
  • Yair Altman (32 days 5 hours ago): See the documentation of the uitree function. The text in my article refers to the legacy (Java-based) uitree version, which is not documented, whereas it is documented and...
  • SOULEYMANE Zakaria (37 days 11 hours ago): Hello. Thank you for sharing. I would like to know if someone could help me with the syntax it takes to use uitree on “Appdesigner”. When I use the syntax you...
  • Nicholas (37 days 23 hours ago): Hello Yair, Have you, or anyone else, had an opportunity to try this demo in R2022a/b? I cannot get the HTMLBrowserPanel object to update with html text (nor with an html file, if...
  • Marcel (50 days 11 hours ago): Hi, I am trying to set the legend to Static, but this command seems not to work in R2022a anymore: set(gca,’LegendColorbarL isteners’,[]); Any ideas? THANKS / marcel
  • Gres (50 days 15 hours ago): In 2018b, you can get the icons by calling [hh,icons,plots,txt] = legend({‘Line 1’});
  • Adam (52 days 3 hours ago): Hi Yair, Is there any way to implement this SyntaxPane functionality in the new uifigure-based apps? Thanks!
  • Yair Altman (52 days 10 hours ago): @Mitchell – in most cases the user wants a single string identifier for the computer, that uniquely identifies it with a distinct fingerprint that is different from any...
  • Mitchell (52 days 19 hours ago): Great post! I’m not very familiar with the network interfaces being referenced here, but it seems like the java-based cross-platform method concatenates all network...
  • Yair Altman (55 days 12 hours ago): Dani – You can use jViewport.setViewPosition(java .awt.Point(0,0)) as I showed in earlier comments here
  • dani (56 days 8 hours ago): hi!! how i can set the horizontal scrollbar to the leftside when appearing! now it set to right side of text
Contact us
Undocumented Matlab © 2009 - Yair Altman
This website and Octahedron Ltd. are not affiliated with The MathWorks Inc.; MATLAB® is a registered trademark of The MathWorks Inc.
Scroll to top