The popup pseudo object




Just as the edit pseudo object described above may replace an edit uicontrol, the popup pseudo object described here may be used to replace a popup uicontrol (uicontrol('Style','Popup')). The pop pseudo object has the same advantages as those listed above for the edit pseudo object.

The popup pseudo object is highly customizable, but here is a typical example. This is the popup in its closed state.

Click on the current selection ("square" in this example) and the popup will open to show the options as shown here. Note that in its opened state the currently selected item is shown in bold. As you would expect, simply clicking on the new selection you want, closes the popup with the new selection.

Notice there is a black "X" in the lower right corner of the opened popup. You can click on that to close the popup without making any selection if you opened the popup unintentionally. Alternatively you could just click on the currently selected choice (in bold), however this is not quite the same since the popup callback will then be called (if defined). The cancel ("X") will never invoke the popup callback.

The label may also be placed above the selection which sometimes works better to save space. (See the popup in the fseries.m example in the sig folder. It has the same choices as the popup shown here except the label is placed above the popup). Or of course you can omit the label if one is not needed.

The following table describes the popup pseudo object properties that you may set and query, although how to use these properties may not become clear until later when the commands are discussed:

Property
Name		 Property
Value
choices A cell array of strings specifying the choices given when the popup is selected. If all the choices are numeric you can use a numeric array instead of the cell array. For example [3 5 7.5] is equivalent to {'3' '5' '7.5'}.
index An integer specifying the current choice (default = 1, i.e. the 1st element of the choices cell array). After the popup is set to the specified index, the popup is closed if it had been open. The callback is not normally called when the popup choice is set using the index parameter, however if you specify the negative of the index desired, then the callback will be called after the index is set.
callbk A callback to be executed when the popup value is changed.
If the callback is defined with a string, then:
Occurrences of '@IDX' will be replaced with the popup index.
Occurrences of '@STR' will be replaced with the popup string.
position
or
pos		 [x y width height] for the opened popup in pixels or normalized units (relative to the figure window).
Note: You might initially get confused because you expect that the closed popup should be somewhere near the (x,y) position in the figure. However this is only true with the default offset (i.e. the closed popup is near the top of the open popup. But when the popup is near the bottom of the screen, one has to choose a zero (or small) offset which means the closed popup is near the bottom of the open popup. In that case the closed popup is not close to (x,y).

Two other options may be enabled by making the x or y value negative. Therefore these two lines are equivalent:

plt('pop','pos',[-.3 .5 .1 .2],...)
plt('pop','pos',[ .3 .5 .1 .2],'offset',0,...)

Likewise the following two lines are also equivalent:

plt('pop','pos',[.3 -.5 .1 .2],...)
plt('pop','pos',[.3  .5 .1 .2],'swap',0,...)

In both these examples the second line is preferred for its clarity. Refer to the descriptions of the offset and swap parameters below. Note that you also can make both x and y negative to enable both the offset and swap options.

If the position was specified previously you can use a scalar argument to modify just the height component or a two element vector to modify just the width and height components.
offset y or [x y] which specifies the location of the closed popup relative to the opened popup.
x is set to 0.08 if it is not specified (where 0/1 represent horizontal position of the left/right edges of the opened popup). The meaning of the y variable becomes clear by considering the example where the choices cell array contained 4 elements. Then:
  • y = 0:   represents the vertical position of the bottom of the opened popup
  • y = 0.5: represents the vertical position of choice{1} of the opened popup
  • y = 1.5: represents the vertical position of choice{2} of the opened popup
  • y = 2.5: represents the vertical position of choice{3} of the opened popup
  • y = 3.5: represents the vertical position of choice{4} of the opened popup
  • y = 4.0: represents the vertical position of the top of the opened popup
Note that negative values for x or y may be used to indicate that the closed popup position should be to the left of or above the position of the opened popup.

If the offset parameter is not included, then the closed popup will be at the top of the opened popup, i.e. at position [0.08 n] (where n is the number of popup choices). To put the closed popup at the bottom of the opened popup simply include 'offset',0 in the parameter list.
colorbk The background color used when the popup is open. (default = [0 .3 .4]);
colorfr The foreground color used when the popup is open. (default = [.1 1 .9])
enable -1=invisible, 0=disabled, 1=enabled (default=1)
swap Normally a left-click on the pseudo popup control opens the popup to reveal the list of choices while a right click merely advances to the next choice without opening the popup. Sometimes it is useful to reverse the roles of the left and right-click - a mode I refer to as the "super-button" mode. In fact if there is only a single choice, it behaves exactly like a uicontrol button in that the only effect from clicking on it is that its callback is called. If there are two choices in the choices cell array, it behaves similarly except that the button text toggles between the two choices with every click. Usually if there are fewer than four choices, the super-button mode is more convenient than the regular mode. The super-button mode is selected by including the swap parameter in the argument list. Often you will want to make the super-button look at least somewhat like a button by including a box around the super-button text. The color of this box is specified by the swap parameter. For example swap,'blue' will draw a blue box around the button text. Or instead of a Matlab color string, you can use an [r g b] color triple. Set the parameter to zero to use the current foreground color (which defaults to [.1 1 .9]). If the parameter is missing (which is only possible if the 'swap' argument is at the end) or if the parameter is set to '' or [] or 'none' then no box is drawn around the button text. Sometimes it is useful to be able to toggle the super-button mode on or off interactively. This is possible with the following quick procedure:
  1. First open the popup. (A left or a right click will do this, depending on which mode you are in.)
  2. Then use the mouse to move the figure window a very small amount (less than 15 pixels in any direction).
  3. And finally close the popup by clicking on any of the choices in the drop down list.
The 15 pixel requirement makes it quite unlikely that this action is performed unintentionally, especially since one rarely thinks of moving the figure while adjusting a control. The text swap toggled will appear in the Matlab command window to assure you that the operation worked as intended.
hide A list of objects to hide before opening the popup. When the popup is later closed, these objects are shown again (unless they were hidden before the popup opened). The hide parameter is used to remove the distraction of objects that overlap or are too close to the popup list. If there is a zero in the list, before the list is used the zero will be replaced with the handle (or handles) of the plot grid lines. (This is convenient because grid lines are the most common object to overlap with opened popups.) Also setting the hide parameter to '' or [] or not supplying a parameter at all (only possible if the 'hide' argument is the last one) is equivalent to setting the parameter to zero.
interp 'none' or 'tex' (default='none')
label {'LabelString', offset, 'Property1',Value1,'Property2',Value2, ...}

A label for the popup will be created as a text object in the same axis that is used to display the popup choices and will contain the string 'LabelString' (the first element of the cell array argument). The 2nd element of the cell array is a complex number containing the offset for the label position in pixels from the closed popup. (The real part is the x offset and the imaginary part is the y offset). For example if the 2nd element of the cell array is -10+20i, then the label will be positioned 10 pixels to the left and 20 pixels above the closed popup.

The remaining cell array elements (if any) must contain property/value pairs, and the properties must be valid text object property names. The specified properties will be applied to the closed popup text string.

Specifying an offset of '' or [] is equivalent to specifying the number 5 for this cell array element. (i.e. the default offset is 5 pixels to the left.)

Instead of specifying a cell array for the label argument, you may also specify a string. For example, the argument 'LabelString' is equivalent to {'LabelString',''}. Since the default offset is usually sufficient, it turns out that this shorter form is used far more often than the cell array parameter.
labely This behaves just like the label parameter above except for the fact that the default offset when it isn't specified is 16i (instead of 5 as is used by the label parameter). This is the usual offset needed for placing the popup label directly above the closed popup text.
***** If a property name is given which isn't in the list above then the property is applied to the popup text object itself. (It must be a valid text property.)  The text color ('color') is usually set this way, however if that property is not specified, the default color is [1 1 .4].

The following commands are used to create a popup pseudo object:

H = plt('pop',
    'Property1',Value1,
    'Property2',Value2,...) 		The property names allowed and the interpretation of the property values are shown in the table above. You many use as many or as few properties as you need in whatever order you choose. If you favor clarity over conciseness, there is no need to consider the alternate forms shown below.
H = plt('pop',
    [x y width height],
    {'choice1', ... 'choiceN'},
    'Property3',Value3,...) 		Both the 'position' and the 'choices' properties are required, so for conciseness you may omit those property names if the property values appear first and in this order. A command such as this equivalent to this longer form:
H = plt('pop','pos',[x y width height],'choices',{'choice1', ... 'choiceN'},'Property3',Value3,...)
Note that in any of these commands you may use either pixel or normalized units. (You aren't required to included the 'units' property since plt can figure out this property from the size of the numbers in the position vector.)
H = plt('pop',
    [x y width height],
    {'choice1', ... 'choiceN'},
    @cb,'Property4',Value4,...) 		This command is equivalent to:
H = plt('pop',[x y width height],v,'callbk',@cb,'Property4',Value4,...)
Since most pseudo popup objects will be created with a callback, the 'callbk' property name can also be omitted by specifying the callback immediately after the position and choices arguments. In this example the callback is specified by a function handle (@cb) but it may also be specified as a string. Property names other than these three ('pos', 'choices', 'callbk') may not be omitted.

The above calls create a popup pseudo object and returns the handle of the text object that is visible when the popup is closed. This handle (H) may be used to modify or query the popup pseudo object parameters using the forms below:

plt('pop',H,
    'Property1',Value1,
    'Property2',Value2,...) 		The specified property values are applied to the popup pseudo object identified by handle H. The property names may include the ones listed in the table shown at the top of this page as well as standard Matlab property names of the popup text object. To see a list of the allowed property names and values, type set(text(0,0,'')) in the command window.
plt('pop',H,'get','string')returns the currently selected element of the choices cell array.
Equivalent to the shorter command: get(H,'string')
plt('pop',H,'get','axis')returns the handle of the axis used to display the opened popup.
plt('pop',H,'get','choices')returns the cell array of choices that was set via the 'choices' parameter
plt('pop',H,'get','index')returns the index number of the specified edit pseudo object (between 1 and the length of the choices cell array). For conciseness, this command may also be written without the last argument: plt('pop',H,'get') or even without the last two arguments: plt('pop',H)
plt('pop',H,'get','callbk')returns the function handle or string that was set via the 'callbk' parameter
plt('pop',H,'get','offset')returns the number or vector that was specified via the 'offset' parameter
plt('pop',H,'get','colorfr')returns the 3 element vector or color string that was specified via the 'colorfr' parameter
plt('pop',H,'get','enable')returns -1/0/1 if the pseudo object is hidden/disabled/enabled
plt('pop',H,'get','hide')returns the vector of handles that was set via the 'hide' parameter
plt('pop',H,'get','interp')returns the string that was set via the 'interp' parameter
plt('pop',H,'get','label')returns the label handle
plt('pop',H,'get','swap')returns true if the swap (super-button) mode is selected.
plt('pop',H,'get','cell')returns an 11 element cell array that is a concatenation of the previous 11 get commands:
{axis choices index callbk offset colorfr enable hide interp label}. Note that this does not include the first get command ('string') listed above. Also 'cell' in this call may be replaced by any string other than one of the other 12 valid 'get' arguments.
plt('pop',H,'open')opens the popup revealing the popup choices.

Mouse behavior:
Left-clicking on the popup text object "opens" the popup. What this means is that the popup string is replaced by a list of the popup choices (rendered using colorfr/colorbk). The user then clicks on the desired choice which then becomes the new text string. right-clicking on the popup text object changes the text string to the next available choice. If the last choice is already selected, then right-clicking will change the text string to the first available choice (in the "choices" array). If you hold down the right mouse button, the selection will continuously advance cyclically. You can alter the rate at which the cycling proceeds by setting the figure application data repeat property. The use of this property is more completely explained above in the description of the edit pseudo object.

Creating, querying, or modifying multiple pseudo sliders:

The techniques for this are pretty much the same as for the pseudo edit and pseudo slider objects, so you can look near the end of those sections for explicit instructions. But it will probably suffice just to follow a simple example. Try typing the following lines into the command window: 
 
    figure('color','black'); % create a figure to hold the 3 pseudo popups created by the next line
    h = plt('pop',arrange(3),prin('{choice%d!row}',1:6),'label',{'first' 'second' 'third''});
    plt('pop',h,'index',{6 5 4});   % Change the popup settings to choice 6,5,4 respectively.
    plt('pop',h)                    % verify this worked by displaying the 3 index values
    plt('pop',h,'get','string')     % verify this worked by displaying the 3 popup strings
    plt('pop',h,'get','cell')       % display a 3x11 cell array. Row k shows all information for popup k
    g = plt('pop',h,'get','label'); % get the handles of the popup labels
    set([h;g],'vis','off');         % make all four pseudo popups invisible
    set([h;g],'vis','on');          % make them visible again


The first two lines above create the figure here (on the left) with all three popups in their closed state. If you click on "choice 1" of the third popup, the popup will open showing you the six possible choices as shown in the figure to the right.

In this example, all 3 popups have the same six choices. That may be want you want, but it's somewhat unusual. Suppose instead of the prin argument above we had used:

{prin('{aa%d!row}',1:3) prin('{bb%d!row}',1:2) prin('{cc%d!row}',1:7)}

(i.e. a cell array of cell arrays), then the first popup would have the 3 choices aa1,aa2,aa3 and the second popup would have the 2 choices bb1,bb2 and the last popup would have the 7 choices cc1,cc2,cc3,cc4,cc5,cc6,cc7.

See the following demo programs for examples of the use of the pseudo popup object:

demo folder:     pltn,   gui1,   wfall*,  
sig folder:         afilt,   erip,   fseries,   psdZoom*,   winplt,  
math folder:      curves,   gpsLog,   julia,   motion*,  
util folder:         pltwater*,  

The four examples listed above followed by an asterisk use the swap parameter of the popup pseudo object to create a "super button".