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 (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
  • Rolf (18 days 8 hours ago): Disclosure: This comes from the developer/vendor of the Code Checker for MATLAB. Have a look at the Code Checker for MATLAB by MonkeyProof Solutions which has many such (configurable)...
  • Yair Altman (26 days 2 hours ago): In theory you could use the data: URI scheme (e.g. .load('data:text/html,<html ><body>Hello world</body></html>')), but for some reason it doesn’t work well in...
  • Sebastian (26 days 7 hours ago): Thanks for your update to the now unsupported `HTMLBrowserPanel`. I tried to replace it with the `LightweightHelpPanel` but the application I am working on is showing generated...
  • Leuze (48 days 8 hours ago): Hello, I would like to add a new object into SLDD and display columns according to my object properties <>
  • Eric Delgado (77 days 11 hours ago): Hey Yair, I think your site is the right place to share that I wrote ccTools, a lib that allows a lot of customizations of Matlab built-in web components (such as uifigure,...
  • Eric Delgado (77 days 11 hours ago): Hey guys, first of all, thanks to @Yair, your site saved me a lot of times! 🙂 That’s why I am sharing that I wrote m2mlapp (*.m => *.mlapp) file conversion, that...
  • François (94 days 8 hours ago): more than 10 years later it helps me after struggling few hours, so thanks you very much !
  • Yair Altman (95 days 6 hours ago): I am not familiar with a universal catch-all tab-completion mechanism for all functions, and it also doesn’t make much sense to me, because different functions use...
  • Arye (96 days 1 hour ago): hi, is there a universal functionSignature.json file that will allow my to get the function hints when opening brackets of my funcs? something that automaticly recognize my function...
  • Sunham (98 days 19 hours ago): This is an old article, but the issue persists even in 2023. 2023a: z = mat2cell(1:1e6,1,repmat(1,1,1e 6)); f = @() cellfun(‘isempty’, z); g = @() cellfun(@isempty,z);...
  • Yair Altman (108 days 9 hours ago): Robot only runs when you tell it to run a command such as keyPress. If you don’t tell it to run a command, it uses no CPU, so there’s no need to remove the Robot...
  • Eric (108 days 21 hours ago): Hey @Kevin, can you share your code about create group of figures in the AppContainer? The container of multiples uifigures could be an amazing improvement over AppDesigner and its...
  • Elsa Smith (109 days 11 hours ago): I recently used java.awt.Robot to perform GUI testing on MATLAB and found it to be an extremely easy and useful way to control mouse movements.
  • Elsa Smith (109 days 12 hours ago): I’m suspecting that the slow performance of my GUI may be due to the use of java.awt.Robot. Is there a way to cancel/stop/remove the robot after it has been created, or is...
  • Michelle Kline (110 days 5 hours ago): *edit* tip about fopen(), not about fwrite(). ‘Wb’ vs. ‘wb’
Contact us
Captcha image for Custom Contact Forms plugin. You must type the numbers shown in the image
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