The slider pseudo object




When using a uicontrol slider to control a parameter in a GUI, besides the slider object itself, one generally also wants an edit box to show the current slider value as well as to allow data entry by typing a number. Also a label is usually required to identify the slider's purpose and two more labels indicating the minimum and maximum allowed values are also desirable. The pseudo slider object combines those five objects into one which makes it much easier to use sliders in your GUI designs. The additional movement and quantization modes often reduce the amount of code you need to make the control work as desired. To create a slider pseudo object, use the command:

H = plt('slider',In1,In2,In3,In4,In5,In6,In7)

This creates a pseudo object which usually looks something like this:

The five component uicontrols that are created for the pseudo object are identified as:
    ------------label----------
    min     ValueEditbox    max
    -----------slider----------

The variables used in the above slider initialization command are described below:

  H The return value is the pseudo slider's handle which is used to read and modify the pseudo slider's properties. (See the get and set commands below.)
 In1  [x,y,width] in pixels or normalized units. Values less than one are assumed to be normalized. Mixing units is ok although x & y must use the same units. [x,y] are the coordinates of the lower left corner of the pseudo slider label (which is also the upper left coordinate of the min value text). If width is missing 120 is assumed.

When the position is specified with a 2 or 3 element as just described, the pseudo slider will look similar to the object shown above which includes all 5 subcomponents. The second way to specify the pseudo slider position is with a 4-element vector in the traditional Matlab format (i.e. [xLeft,yBottom,Width,Height]). When using this form, the position vector only specifies the position and size of the actual slider uicontrol. plt will calculate what is hoped to be the optimal position and size of the label and edit box components. If the Width value specified is larger than the Height value, then the pseudo slider will end up looking similar to this:

Note that the min/max labels are not rendered when the position is specified this way which makes it more compact. If the Width value is smaller than the Height value then the slider will be oriented vertically with the label placed at the top and the editbox placed at the bottom. (See the demo programs motion.m and pltmap.m for examples of the use of both these forms. If the label and editbox are not wide enough for your taste you can fix it by adding spaces to the left and right sides of the label since plt uses the length of the label string to determine the width of those two elements. Alternatively, you may include a 5th element to the position vector which specifies the width of both the label and the editbox. If you are very picky, you can set In1 to be an eight-element vector. In that case, the first four elements specify the position of the slider component and the last four elements specify the position of the label component (using the traditional Matlab positioning style). The editbox component will then be set to be the same size as the label component and placed on the opposite side of the slider from the label.

Finally, there is one last method (very rarely used) when complete flexibility is required where the In1 argument is specified by a cell array. This cell array must have either 2 or 5 elements. For the 5 element form, the entries specify the positions of the Label, Slider, MinText, MaxText, and EditBox components respectively. These positions must all be in either normalized or pixel units and each component must be either a 4-element Matlab-style position vector or an empty vector which indicates that the associated element is to be invisible. The 2 element form can be used when the MinText and MaxText elements are not needed. In that case first element specifies the position of the slider and the second element specifies the position of the label. The position of the editbox will be computed automatically so that it is the same size as the label but on the other side of the slider.

In1 is the only required parameter for this function.
 In2 [value, smin, smax, emin, emax]
value is the initial value assigned to the slider.
smin/smax are the slider values at the leftmost/rightmost positions.
emin/emax are the smallest/largest values allowed when entering numbers into the edit box. If emin and emax are missing, 1e-99 and 1e99 are assumed.

If In2 is not supplied, [50 0 100] is assumed.
 In3 Slider label. If you don't want a label, don't supply this parameter, or set In3 to ''.
 In4 Slider callback. This expression will be evaluated whenever the user moves the slider control or enters a number in the edit box. Occurrences of '@VAL' will be replaced with the current value. This parameter is optional, however, you must include it if you want to specify any of the three parameters shown below. If you need to supply this parameter for that reason, but you don't need the callback, simply set In4 to ''.
  Although the previous three parameters are optional, they must be supplied in the indicated order. For example, if you want to specify a slider callback (In4) you must also supply In2 and In3. The next three parameters are also optional but are different in that they may be supplied in any order since the data type can be used to identify which parameter is being supplied. They have been identified below as In5, In6, and In7 Although these three parameters (or any subset of them) may be included in the argument list in any order you choose (after In4 of course).
 In5 This parameter controls how the slider moves when the slider left/right arrows are clicked or when clicking in the space to the left or right of the slider button.
In5 Movement   Quantization
 1 Linear   none
 2 Linear   rounded to nearest integer
 3 Linear   rounded to nearest power of two
[4 q]   Linear   rounded to nearest multiple of q
 5 Logarithmic   none
[6 q] Linear   rounded to nearest integer for slider arrows
  and to the nearest multiple of q for slider trough
If In5 is not provided then 1 is assumed.
For modes 4 & 6, q defaults to 10 if not specified.
 In6 'fmin fval fmax'
fmin/fmax are formatting strings for the min/max labels and fval is the formatting string for the edit box. These 3 strings are concatenated together as one string separated by spaces. Each formatting string may contain c style printf formatting codes or the W,V,w,v formats. (Type "help prin" for a description of these formats).

For example: '%4w %5.2f %2w' specifies the w format with 4 and 2 digits respectively for the fmin and fmax values and the %5.2f floating point format for the edit box. Since the w format is the assumed default you may be slightly more concise by leaving out the w, ('%4 %5.2f %2' in this example). Instead of a concatenated string, you can use also use a cell array, as in {'%4' '%5.2f' '2'} for this example. However, the cell array form is discouraged because it can't be used in plt calls that create multiple pseudo sliders in a single call. (See below.)

Often it is sufficient to only specify the format for fval and accept the defaults for fmin and fmax (which are '%2w' and '%3w' respectively). We can do this by simply specifying a single format code. For example '%5.2f' is equivalent to '2 %5.2f 3'.

If In6 is not provided, then '6' (or equivalently '2 6 3') is assumed - i.e. the w format is used for all three elements.
 In7 [LabelBG; EditBG; LabelFR; EditFR]
This is an array containing 3 columns and up to 4 rows. Columns 1/2/3 respectively represent the proportion (0 to 1.0) of red/green/blue used in the control. The first two rows are the background colors for the label and edit fields respectively. The last two rows are optional and contain the label and edit field foreground colors. If the foreground colors are not specified then black is assumed (i.e. [0 0 0]).

If In7 is not provided then [.75 .75 .75; 0 1 1] is assumed.

For the commands below, H is the handle returned from the above slider initialization command.

The get commands:

plt('slider',H,'get','value') returns the pseudo slider's current value
plt('slider',H,'get') equivalent to the above
plt('slider',H) also equivalent to the above (the shortest and most cryptic method of getting the slider's value)
plt('slider',H,'get','visible') returns 1 if the slider is visible, 0 otherwise
plt('slider',H,'get','ena') returns 1 if the slider is enabled, 0 otherwise
plt('slider',H,'get','position') returns the slider position coordinates [x y width] in the same units as originally specified.
plt('slider',H,'get','pos') same as above
plt('slider',H,'get','obj') returns the slider object handles:
[  Label;   Slider;   MinText;   MaxText;   EditBox ]

The set commands:

plt('slider',H,'set',a) Sets the slider to value a.
Returns a possibly limited value.
plt('slider',H,a) The form above (or the form below using 'value') is recommended for clarity but if you want to be as concise as possible, this form is equivalent to the command above.
plt('slider',H,'value',a) Equivalent to the two forms above. You may also use the extra parameter 'set' to add clarity as in plt('slider',H,'set','value',a) if you prefer. In fact, this extra parameter is allowed (immediately after the slider handle) in all the remaining commands shown in this table.
plt('slider',H,'val',a) Same as above except the slider callback is not executed
plt('slider',H,'position',a) Sets the slider position.
(See In1 in the slider initialization description above).
plt('slider',H,'pos',a) Same as above.
plt('slider',H,'minmax',a,b) a contains [smin,smax,emin,emax] (see In2 above)
b is a new slider value (optional)
Returns a possibly limited value.
plt('slider',H,'visON') Makes slider visible.
plt('slider',H,'visOFF) Makes the slider invisible.
plt('slider',H,'enaON') Enables the slider.
plt('slider',H,'enaOFF') Disables the slider
plt('slider',H,'label',a) Sets the label string to a. If a is empty, the label is made invisible.
plt('slider',H,'mode',a) Sets the slider movement mode. (See In5 above).
Returns a possibly limited value.

Creating multiple pseudo sliders with one command:

If the position argument (In1) is a cell array, then multiple pseudo sliders will be created. For example the command:

H = plt('slider',{p1 p2 p3},In2,{In3A In3B In3C},In4,In5);

would have the same effect as the following 3 commands:
H = [plt('slider',p1,In2,In3A,In4,In5);
     plt('slider',p2,In2,In3B,In4,In5);
     plt('slider',p3,In2,In3C,In4,In5)];
Note that when a cell array is used as an input, the nth element of the cell array is used for the nth slider, whereas when the input is not a cell array, that same input is used for all the sliders. In this example, In3 was a cell array while In2, In4, and In5 were not, but it could just as easily be the other way around, or any other combination. Also, this example happened to use five slider parameters (In1 thru In5) but it could have used just one parameter (The position In1) or as many as seven parameters. When multiple pseudo sliders are created, the return argument (H) is a column vector of pseudo slider handles.

The number of pseudo sliders created is always equal to the size of the first cell array (In1). Consider the following command:

H = plt('slider',{p1 p2},In2,In3,In4,In5,{In6A In6B In6C});

This creates two pseudo sliders (at positions p1 and p2). The values in the last cell array (In6) will not be distributed to the created objects because that cell array does not have the same number of elements as In1. So instead the entire cell array is used for the In6 parameter, making this command equivalent to the following two commands:
H = [plt('slider',p1,In2,In3,In4,In5,{In6A In6B In6C});
    plt('slider',p2,In2,In3,In4,In5,{In6A In6B In6C})];

Querying or modifying multiple pseudo sliders:

All the commands shown above where the first argument (after 'slider') is a handle may also accept vectors of handles or cell arrays of handles causing the command to operate on more than one pseudo slider. The rules are the same as mentioned above ... i.e. cell array arguments of the same length as the vector of handles are distributed so that the nth cell array element applies to the nth pseudo slider handle. To experiment with this notion, consider typing these commands into the command window:

    % create 4 pseudo sliders with labels 'first' 'second' 'third' 'fourth'
    h = plt('slider',arrange(4),[],{'first' 'second' 'third' 'fourth'}); % a figure will appear similar to below
    plt('slider',h,'value',{90 60 10 50}); % move the slider bars to 90,60,10,50 respectively
    plt('slider',h);                       % verify this worked by displaying the 4 slider values
    plt('slider',h,'get','pos')            % display 4x3 array (row k is the position of slider k components)
    plt('slider',h,'get','obj')            % display 4x5 handle array (row k are the handles for slider k)
    plt('slider',h,'visOFF');              % make all four pseudo sliders invisible
    plt('slider',h,'visON');               % make them visible again
    


See the following programs for examples of the use of the pseudo slider object:
      demo folder:   gui1, pltmap, subplt16, trigplt, wfall
      math folder: carlo, motion
      sig folder: afilt, editz, erip, psdZoom, winplt
      util folder: pltwater