 # Calling sequence and line styles

This section (not including the two large tables at the end) is a good introduction to how to use plt and the differences between plt and the native Matlab plot.

Usually you will call plt with at least two arguments:

plt(x,y);

This plots the data in vector x along the horizontal axis and the data in vector y along the vertical axis. x and y may be row or column vectors. plt will transpose one of the arguments if needed to line things up, so x could be a row vector while y was a column vector. x and y must be the same length however. If not you will get an error message saying that the vectors must be the same length.

If y is a real vector, plt(y) is equivalent to plt(1:length(y),y).

To plot more than one trace, include the x and y vectors for each trace in the argument list. For example this command plots three traces:

plt(x1,y1,x2,y2,x3,y3)

Quite often several traces share the same x vector. In this case we can simply repeat the x vector in the argument list, as in:

plt(x,y1,x,y2,x,y3)
or
plt(x,[y1;y2;y3]). (a shorthand way of writing the above).

That would work only if the y1,y2,y3 were row vectors. If they were column vectors you would need to write:

plt(x,[y1 y2 y3])

You can call plt using an output argument, which will return a column vector of trace handles. For example:

h = plt(x,[y1 y2 y3])

will return a 3 by 1 column vector h of handles. h(1) of course would be the line handle associated with the y1 trace. Most often when you type the plt command at the command prompt you don't need to save plt's return value. However when plt is called from a program sometimes the line handles are needed to allow further manipulations of the plot.

If x and y are both matrices of the same size, plt(x,y) will create one trace per column.

None of this so far should come as a surprise since it is identical to Matlab's plot command.
Some of the ways that plt and plot differ will become clear from what follows.

With plot the data to be plotted must be passed in via the argument list.
However, you may call plt without any arguments, allowing you to choose the data to plot interactively.
Find out about this method here: The Workspace Plotter.

Unlike plot, plt will accept data passed in cell arrays. For example the following two commands do the same thing:

plt(x,[y1; y2; y3])
plt(x,{y1; y2; y3})

Although in the example above, y1, y2, and y3 must be the same length so there really isn't a big advantage for the cell array input. However, now consider these two commands (again, these two lines are equivalent to each other):

plt(x1,y1,x2,y2,x3,y3)
plt({x1 x2 x3},{y1 y2 y3})

With plot you must use the first form because cell arrays are not allowed. You can't combine the arguments into vectors because they may be different lengths. When typing in the command window the first form is probably easier anyway, but inside a program the second form is far more convenient, especially when the data is be read from files.

If y is a complex vector, plt(y) is equivalent to plt(real(y),imag(y)). Matlab's native plot works that way too. Unlike plot however, plt treats complex arguments this way no matter where they appear in the argument list. For instance if a and b are both complex, plt(a,b) is equivalent to  plt(real(a),imag(a),real(b),imag(b)). (Why this doesn't work with plot has sometimes been a mystery and an annoyance to me.)

Also like the plot command you can include any line property in the argument list. For example:

plt(x,y,'LineWidth',2) is equivalent to set(plt(x,y),'LineWidth',2)

However the behaviors of plt and plot differs in that with plot these line properties must appear after all the data vectors in the argument list. (plot gives an error otherwise). With plt the line properties may occur in the middle of the argument list. In that case, the line property is applied only to the lines defined earlier in the argument list. For example:

plt(x,[y1;y2],'Marker','Diamond',x,[y3;y4]);

only sets the Marker property for the first two traces. An equivalent to the above is:

a=plt(x,[y1;y2;y3;y4]); set(a(1:2),'Marker','Diamond');

By using cell arrays, you can set properties differently on each trace. For example:

plt(x,[y1;y2;y3;y4],'LineWidth',{2 2 4 2});

This would set the LineWidth of the trace associated with y3 to 4 and the other three traces to 2. A column ({2;2;4;2}) would have worked equally as well. The number of elements in the row or column vector must identical to the number of traces defined so far in the argument list. (so as above, traces defined after the LineWidth parameter will just be assigned to the default LineWidth. Note that this is not possible with plot, unless you collect the various trace handles and use set commands to set the LineWidths as desired. (plt tries to insulate you from this need to become familiar with handle graphics).

Two more examples:

plt(x,[y1;y2;y3;y4],'LineStyle',{'-' ':' '-.' 'none'});

plt(x,[y1;y2;y3],'Marker',{'square','none','+'});

This method of assigned properties works with any line property. In the two particular line properties used above, you could have replaced 'LineStyle' with 'Styles' and 'Marker' with 'Markers' and the results would be the same. Styles and Markers are not really line properties, however plt allows you to use those alternate forms to allow some additional flexibility in how you write the parameter that follows it. (For example a character array may be used in place of the cell array.)  The details of the additional flexibility provided by using these two alternate parameters are described in the Trace properties section.

The special plot types vertical bars, error bars, and vector fields (arrows) are plotted with the help of auxiliary functions Pvbar, Pebar and Pquiv. The use of these functions is described in the Auxiliary functions section.

### plt vs. pltinit

Most of the code for this toolbox is broken up into these two routines:

 pltinit.m Contains the code used to create a new plt pseudo object which means creating a new plot axis or set of axes. This also normally means creating a new figure window as well. (The only exception to that is when the 'Fig' parameter is included in the parameter list.) plt.m Contains the code used to create or modify any of the remaining pseudo objects (including cursor, grid, edit, pop, slider, image, ColorPick, and HelpText).

From this description you might expect that since all the command examples shown above create a new plot, that they should really be calling pltinit( ) instead of plt( ). While this is technically true, plt recognizes from the syntax when a new plot is being created and simply passes all of its arguments on to pltinit. The advantage of this is that "plt" is shorter and faster to type which is especially important when used from the command window. To create a new plot from a script or function, it is more a matter of taste which function you use. For a complicated gui, pltinit would be a better choice because your gui will likely have many calls to plt as well and it will be a lot easier to see where the plots are created if a different function call is used.

This completes the introduction. What remains in this section and in fact all the remaining help file sections might be too long and detailed to serve as an ideal way to learn about these parameters and commands. Perhaps an easier way to learn how to program with plt is to run thru all the demo programs (conveniently done with demoplt.m) while reading the comments at the top of each example program. The program comments may also be found next to a screen capture of each demo program in the Programming examples section . You will learn about nearly every plt parameter and option this way. Then you can use what follows merely as reference material.

### Figure application data:

After a call to plt, the following information is available from the figure application data:
(The quoted strings are case sensitive.)

 getappdata(gcf,'axis') Returns a row vector of handles of the axes containing the plotted data. The first handle in the vector is the left hand main plot. This is followed by the subplot axes (if any) from the bottom up. Finally, the last element of the vector will be the handle of the main plot right hand axis (if any). get(ax,'user') Returns the cursor ID for the axis with handle ax which may be any axis that appears in the vector returned from the command above. getappdata(gcf,'cid') Returns the cursor IDs for each axis, starting with the main (lower) axis and working upwards to include all the subplot axes. (There is not a cursor object associated with the right hand axis since the main axis cursor also displays data from the right hand axis.) getappdata(gcf,'Lhandles') Returns a list of all handles of all data traces created by plt. Note that this is identical to the plt return value. getappdata(ax,'Lhandles') Each axis (including the right hand axis) also has a 'Lhandles' application data value. This contains a list of all lines contained in that axis. The main (lower) plot is an exception since its Lhandles list includes the traces on both the left and right hand axis. findobj('name','Abc') If the plt call includes a parameter such as 'FigName','Abc' then this command will return the handle of the figure window that plt created. This can be useful in programs that create multiple plt figures. findobj(gcf,'user','TraceID') Various plt arguments may be used to modify the location, appearance, or contents of the TraceID box. However occasionally you may want to make further modifications after the plt call and this command will allow you to do that by returning the handle of the TraceID box. findobj(gcf,'tag','MenuBox') This command will return the handle of the MenuBox. Assuming the menu box is in it's default configuration, a command such as get(findobj(gcf,'tag','MenuBox'),'child') will return a list of text objects with string properties of 'Help', 'LinX', 'LinY', 'Grid', 'Menu', 'Zout', and 'XY<->' . findobj(gcf,'user','grid') This command returns a column vector containing the line handles of the plot grids for all the axes in the figure. If there is just a single axis (i.e. one grid object) then this is equivalent to plt('grid',0,'get'). getappdata(gcf,'params') Returns a cell array list of the parameters specified on the plt command line. (All plt arguments are included except the arguments specifying the data arrays.) getappdata(ax,'xstr') Returns the value that was specified in the 'Xstring' parameter when plt was called. ax refers to the primary left hand axis. getappdata(ax,'ystr') Returns the value that was specified in the 'Ystring' parameter when plt was called. ax refers to the primary left hand axis. getappdata(gcf,'multi') Returns a column vector of handles to the objects used to render the Multi-cursor (the text objects, followed by the markers, followed by the dotted vertical line). If the multi-cursor is not currently enabled, then this vector will be empty.

### Single argument actions:

The command strings here (as with most plt commands) are not case sensitive.
So for example "plt help" and "plt HELP" are equivalent.

 plt help Displays the plt help file. You could also use the functional form of this command: plt('help'). Alternatively, if you just want a one page list of the plt parameters type type help plt. plt version Returns the plt version. Same as: plt('version') plt save Opens a dialog box allowing you to select a .plt figure file that can be opened later using the plt open item in the file menu. If you want to avoid the file dialog box add the file name as a 3rd argument (i.e. plt save filename). The use of these plt figure files are described in more detail in the Menu box section. Note that this command is also available from the file menu. plt open Opens a dialog box allowing you to select a .plt figure file that was saved using the plt save item in the file menu. If you want to avoid the file dialog box add the file name as a 3rd argument (i.e. plt open filename). Note that this command is also available from the file menu. plt close If a programming error causes plt to crash, you may find it difficult to close the plt figure windows (because they use the close request function). This command solves the problem by closing all currently open plt figure windows. Figure windows not created by plt are not closed. (And of course you may also use the functional form.) plt show If the current figure was created by plt, then this command, or the equivalent functional form plt('show'), will return a list of trace numbers that are currently being displayed. For example if you run the demo program "plt5.m" (which has five traces) and then turn off traces 3 and 4 (by clicking on their trace IDs) then this command will return [1 2 5] showing that those three traces are currently active. You can also use this command with an argument (the functional form only) from a program or the command window to set the traces you want active for the current figure. For example after running plt5.m, the command plt('show',2:5) will turn off the first trace while leaving the remaining four traces on. Note that the TraceIDs will change their appearance to indicate which traces are enabled just as if you had done the same operation by clicking on the trace names in the TraceID box. To disable all traces, use plt('show','') and to enable all traces, use plt('show','all') or plt('show',1:n) where n is the number of traces defined. plt HelpTextplt HelpText offplt HelpText on The first two forms to the left (off or with no argument) deletes the help text and the last form (on) recreates that help text again (which it can do by retrieving the help text information using getappdata(gcf,'helptext')). Help text is usually created by using the 'HelpText' parameter when the plt window is created (this is described in the Labels and figure properties section.) (And of course you may also use the functional form, i.e. plt('HelpText','on');). plt move This command (which has the same effect as right-clicking on the delta cursor button) sets the current plt figure into its repositioning mode. This allows all gui objects to be resized and/or repositioned using the mouse. The new positions are displayed in the command window. Typing plt move a second time cancels the repositioning mode and returns the controls to their prior functions. Details may be found here: GUI building with plt