Interactive List Box in a GUIDE GUI

About the Example

This example shows how to create a list box to display the files in a folder. When you double click a list item, MATLAB® opens the item:

  • If the item is a file, MATLAB opens the file using the appropriate application.

  • If the item is a folder, MATLAB reads the contents of that folder into the list box.

To get and view the example code:

  1. Copy the example FIG-file and code file to your current (writeable) folder and open the FIG-file in GUIDE and the with the following commands:

    copyfile(fullfile(docroot, 'techdoc','creating_guis',...
    'examples','lbox2*.*')), fileattrib('lbox2*.*', '+w')
    guide lbox2.fig
    
  2. From GUIDE Layout Editor, click the Editor button .

    The lbox2.m code displays in the MATLAB Editor.

Implement the List Box GUI

The following sections describe the implementation:

  • Specify the Folder — shows how to pass a folder path as input argument when the GUI runs.

  • Load the List Box — describes the local function that loads the contents of the folder into the list box. This local function also saves information about the contents of a folder in the handles structure.

  • Code List Box Behavior — describes how the list box is coded to respond to double clicks on items in the list box.

Specify the Folder

By default, GUI code files generated by GUIDE open the GUI when there are no input arguments, and call a local function when the first input argument is a character string. This example changes the behavior so that if you put the example files, lbox2.m and lbox2.fig, on the MATLAB path you can run the GUI displaying a particular folder. To do so, pass the dir function as a string for the first input argument, and a string that specifies the path to the folder for the second input argument. For instance, from the Command Window, run the following to have the list box display the files in C:\myfiles:

lbox2('dir','C:\my_files')

The following code from lbox2.m shows the code for lbox2_OpeningFcn, which sets the list box folder to:

  • The current folder, if no folder is specified.

  • The specified folder, if a folder is specified.

    function lbox2_OpeningFcn(hObject, eventdata, handles, varargin)
    % This function has no output args, see OutputFcn.
    % hObject    handle to figure
    % eventdata  reserved - to be defined in a future version of MATLAB
    % handles    structure with handles and user data (see GUIDATA)
    % varargin   command line arguments to untitled (see VARARGIN)
    
    % Choose default command line output for lbox2
    handles.output = hObject;
    
    % Update handles structure
    guidata(hObject, handles);
    
    if nargin == 3,
        initial_dir = pwd;
    elseif nargin > 4
        if strcmpi(varargin{1},'dir')
            if exist(varargin{2},'dir')
                initial_dir = varargin{2};
            else
                errordlg({'Input argument must be a valid',...
                         'folder'},'Input Argument Error!')
                return
            end
        else
            errordlg('Unrecognized input argument',...
                     'Input Argument Error!');
            return;
        end
    end
    % Populate the listbox
    load_listbox(initial_dir,handles)

Load the List Box

A local function loads items into the list box. This local function accepts the path to a folder and the handles structure as input arguments and performs these steps:

  • Changes to the specified folder so that the GUI can navigate up and down the tree, as required.

  • Uses the dir command to get a list of files in the specified folder and to determine which name is a folder and which is a file. dir returns a structure (dir_struct) with two fields, name and isdir, containing this information.

  • Sorts the file and folder names (sortrows) and saves the sorted names and other information in the handles structure so that this information can be passed to other functions.

    The name structure field is passed to sortrows as a cell array, which is transposed to get one file name per row. The isdir field and the sorted index values, sorted_index, are saved as vectors in the handles structure.

  • Calls guidata to save the handles structure.

  • Sets the list box String property to display the file and folder names and set the Value property to 1, ensuring that Value never exceeds the number of items in String, because MATLAB software updates the Value property only when a selection occurs; not when the contents of String changes.

  • Displays the current folder in the text box by setting its String property to the output of the pwd command.

The load_listbox function is called by the opening function, as well as by the list box callback.

function load_listbox(dir_path, handles)
cd (dir_path)
dir_struct = dir(dir_path);
[sorted_names,sorted_index] = sortrows({dir_struct.name}');
handles.file_names = sorted_names;
handles.is_dir = [dir_struct.isdir];
handles.sorted_index = sorted_index;
guidata(handles.figure1,handles)
set(handles.listbox1,'String',handles.file_names,...
	'Value',1)
set(handles.text1,'String',pwd)

Code List Box Behavior

The listbox1_Callback code handles only one case: a double-click of an item. Double clicking is the standard way to open a file from a list box. If the selected item is a file, it is passed to the open command; if it is a folder, the GUI changes to that folder and lists its contents.

  • Define how to open file types

    The open command can handle a number of different file types, however, the callback treats FIG-files differently. Instead of opening the FIG-file as a standalone figure, it opens it with guide for editing.

  • Determine which item was selected

    Since a single click of an item also invokes the list box callback, you must query the figure SelectionType property to determine when you have performed a double click. A double-click of an item sets the SelectionType property to open.

    All the items in the list box are referenced by an index from 1 to n. A value of 1 refers to the first item, and a value of n is the index of the nth item. The software saves this index in the list box Value property.

    The callback uses this index to get the name of the selected item from the list of items contained in the String property.

  • Determine whether the selected item is a file or directory

    The load_listbox function uses the dir command to obtain a list of values that indicate whether an item is a file or folder. These values (1 for folder, 0 for file) are saved in the handles structure. The list box callback queries these values to determine if current selection is a file or folder and takes the following action:

    • If the selection is a folder — change to the folder (cd) and call load_listbox again to populate the list box with the contents of the new folder.

    • If the selection is a file — get the file extension (fileparts) to determine if it is a FIG-file, which is opened with guide. All other file types are passed to open.

    The open statement is called within a try, catch block to capture errors in an error dialog box (errordlg), instead of returning to the command line.

    You can extend the file types that the open command recognizes to include any file having a three-character extension. Do this by creating a MATLAB code file with the name openxyz.m. xyz is the file extension for the type of files to be handled. Do not, however, take this approach for opening FIG-files, because openfig.m is a MATLAB function which is needed to open GUIs. For more information, see open and openfig.

listbox1_Callback code.  

function listbox1_Callback(hObject, eventdata, handles)
get(handles.figure1,'SelectionType');
% If double click
if strcmp(get(handles.figure1,'SelectionType'),'open')
    index_selected = get(handles.listbox1,'Value');
    file_list = get(handles.listbox1,'String');
    % Item selected in list box
    filename = file_list{index_selected};
    % If folder
    if  handles.is_dir(handles.sorted_index(index_selected))
        cd (filename)
        % Load list box with new folder.
        load_listbox(pwd,handles)
    else
        [path,name,ext] = fileparts(filename);
        switch ext
            case '.fig'
                % Open FIG-file with guide command.
                guide (filename)
            otherwise
                try
                    % Use open for other file types.
                    open(filename)
                catch ex
                    errordlg(...
                      ex.getReport('basic'),'File Type Error','modal')
                end
        end
    end
end
Was this topic helpful?