Difference between revisions of "Solo: GUI SoloParamHandles"

From Bcontrol
(Menus)
(Menus)
Line 16: Line 16:
  
 
[[Image:basic_menu_param.jpg|left|200px]]
 
[[Image:basic_menu_param.jpg|left|200px]]
 +
 +
We can access the value of this SoloParamHandle just as we access the value of any other SoloParamHandle:
 +
 +
  >> value(menuvar)
 +
  ans =
 +
      10
 +
 +
There’s an extra useful wrinkle, which we can see if we ask what type of object the value of the menuvar is:
 +
 +
  >> class(value(menuvar))
 +
 +
  ans =
 +
      double
 +
 +
Menu items are defined as strings. However, the Solo system checks to see whether the string for the current menu value is something that can be converted into a number. If it is, then the value that is stored is the number itself. The reason for this is that most often, when the value of a menu is the string for a number, we want the number. Thus we can do:
 +
 +
  >> menuvar + 5
 +
  ans =
 +
      15
 +
 +
Whenever a user changes the graphics object, the value of menuvar, the SoloParamHandle, will also auomatically change. Try it! Change the menu on the figure, and then type value(menuvar).
 +
 +
Conversely, if the value of menuvar, the SoloParamHandle, changes, the graphics object will also automatically change— the graphics object and the variable are tied together. Thus you can try:
 +
 +
  >> menuvar.value = ‘blank’;
 +
 +
or
 +
 +
  >> menuvar.value = ‘10’;
 +
 +
or
 +
 +
  >> menuvar.value = 10;
 +
 +
Notice that the last two have exactly the same effect. When you set a menu SoloParamHandle to a numeric value, the system (1) first checks to see whether a string that matches that number exists in the menu; if so, sets the menu to that value; (2) if approach #1 failed, the system then checks to see whether the number is an integer and there are at least that number of items in the menu; if so, sets the menu to the value of that item number. Thus, using our example, “menuvar.value = 1;” would result in setting the value to ‘blank’, the first of the items in the menu.
 +
 +
=== Optional parameters common to all graphics SoloParamHandle types: ‘position’ and ‘TooltipString’. ===
 +
 +
''Position.'' Suppose you want to add a second menu to your window. You don’t want this new menu to overlay the existing one, of course! An optional parameter when creating any GUI SoloParamHandle, is ‘position’, a 1-by-4 vector specifying [x y width height], in units of pixels. The x and y refer to the position of the lower left hand corner of the GUI, relative to the lower left hand corner of the figure; width and height are again, in pixels, and indicate the total width and height of the GUI and the label next to it.
 +
 +
So, for example, we can create:
 +
 +
  >> SoloParamHandle(‘base’, ‘secondmenu’, ‘type’, ‘menu’, ‘string’, …
 +
      {‘another’ ‘menu’}, ‘label’, ‘secondmenu’, ‘value’, 2, …
 +
  ‘position’, [100 100 150 20]);
 +
 +
 +
''TooltipString.'' For most control windows and most protocols, you will soon find that you have a million menus and buttons and parameters, and remembering what each of them does is quite difficult. It is very convenient to have a little text window with explanatory text that pops up whenever the mouse rests over the GUI or the label. To do this, you can either add a tooltip string after creation, or pass it as an optional parameter during creation. For example.
 +
 +
  >> set_tooltipstring(secondmenu, ‘This is the second menu’);
 +
 +
Place the mouse over secondmenu to see the effect of this.  Alternatively, if defining the tooltip string upon creation, you could have done:
 +
 +
  >> SoloParamHandle(‘base’, ‘secondmenu’, ‘type’, ‘menu’, ‘string’, …
 +
      {‘another’ ‘menu’}, ‘label’, ‘secondmenu’, ‘value’, 2, …
 +
‘position’, [100 100 150 20], ‘TooltipString’, ‘version 2’);
 +
 +
To do multiple lines, you can do it like this:
 +
 +
  >> set_tooltipstring(secondmenu, sprintf(‘First line;\nSecond line.’));
 +
 +
=== MenuParam() shortcut function ===
 +
 +
A slightly shorter way of creating a menu type SoloParamHandle is with a utility function called MenuParam.m:
 +
 +
  function [sp] = MenuParam(obj, parname, parlist, parval, x, y)
 +
 +
The first argument, as usual, is  either an object or the string ‘base’, and the second is the name of the variable to be created. The third is the list of strings for the menu items. The fourth indicates the initial value of the menu. The fifth and sixth are the position, in pixels, of the lower left corner of the menu object. The width and height take on a default value. Thus we can call
 +
 +
  >> MenuParam(‘base’, ‘thirdmenu’, {‘a third’ ‘menu’}, 2, 140 100);
 +
  >> value(thirdmenu)
 +
 +
  ans =
 +
      menu
 +
 +
After the first six obligatory parameters, MenuParam.m takes other, optional arguments, one of which is ‘TooltipString’, for example:
 +
 +
  >> MenuParam(‘fourthmenu’, {‘still’ ‘another’}, 1, 140, 200, …
 +
  ‘TooltipString’, ‘detailed tooltips are better than short ones’);
 +
 +
 +
See MenuParam.m’s documentation (under construction) for  information on other optional parameters.

Revision as of 00:46, 18 March 2009

The main motivation for writing the Solo system was to assist in user interfaces; so in this section we now we finally get to the source of it all, the user interface!

Interactive graphics objects often have “callback” functions attached to them: when the user interacts in some way with the graphics object, the callback corresponding to it gets called. This allows for great flexibility (and we will talk much more about callbacks below), but quite often all one wants from the callback is to make the internal variable, corresponding to the GUI, have a value that matches whatever the user sets in the GUI. SoloParamHandles (following the functionality of Exper) do this automatically, so users don’t have to write callback functions for this.

There are a number of predefined graphics objects types in Solo, all of which share some optional parameters and settings. We’ll go through one of them in detail – the Menu type – and use it to illustrate some of the common parameters. After that we’ll go a little faster through the other types (Edit, Numedit, Toggle, Pushbutton, Header, and Subheader).

Menus

Ok, let’s start with the Menu example. We’ll open a new figure, and put a pop-up menu on it. There will be three possible items on the menu, which we’ll give the strings ‘blank’, ‘10’, and ‘20’.

  >> figure;
  >> SoloParamHandle(‘base’, ‘menuvar’, ‘type’, ‘menu’, ‘string’, …
     {‘blank’, ‘10’, ‘20’}, ‘value’, ‘10’, ‘label’, ‘menuvar’);

This will bring up the following picture in your figure:

Basic menu param.jpg

We can access the value of this SoloParamHandle just as we access the value of any other SoloParamHandle:

  >> value(menuvar)
  ans = 
     10

There’s an extra useful wrinkle, which we can see if we ask what type of object the value of the menuvar is:

  >> class(value(menuvar))
  ans =
     double

Menu items are defined as strings. However, the Solo system checks to see whether the string for the current menu value is something that can be converted into a number. If it is, then the value that is stored is the number itself. The reason for this is that most often, when the value of a menu is the string for a number, we want the number. Thus we can do:

  >> menuvar + 5
  ans = 
     15

Whenever a user changes the graphics object, the value of menuvar, the SoloParamHandle, will also auomatically change. Try it! Change the menu on the figure, and then type value(menuvar).

Conversely, if the value of menuvar, the SoloParamHandle, changes, the graphics object will also automatically change— the graphics object and the variable are tied together. Thus you can try:

  >> menuvar.value = ‘blank’;

or

  >> menuvar.value = ‘10’;

or

  >> menuvar.value = 10;

Notice that the last two have exactly the same effect. When you set a menu SoloParamHandle to a numeric value, the system (1) first checks to see whether a string that matches that number exists in the menu; if so, sets the menu to that value; (2) if approach #1 failed, the system then checks to see whether the number is an integer and there are at least that number of items in the menu; if so, sets the menu to the value of that item number. Thus, using our example, “menuvar.value = 1;” would result in setting the value to ‘blank’, the first of the items in the menu.

Optional parameters common to all graphics SoloParamHandle types: ‘position’ and ‘TooltipString’.

Position. Suppose you want to add a second menu to your window. You don’t want this new menu to overlay the existing one, of course! An optional parameter when creating any GUI SoloParamHandle, is ‘position’, a 1-by-4 vector specifying [x y width height], in units of pixels. The x and y refer to the position of the lower left hand corner of the GUI, relative to the lower left hand corner of the figure; width and height are again, in pixels, and indicate the total width and height of the GUI and the label next to it.

So, for example, we can create:

  >> SoloParamHandle(‘base’, ‘secondmenu’, ‘type’, ‘menu’, ‘string’, …
      {‘another’ ‘menu’}, ‘label’, ‘secondmenu’, ‘value’, 2, …
  	‘position’, [100 100 150 20]);


TooltipString. For most control windows and most protocols, you will soon find that you have a million menus and buttons and parameters, and remembering what each of them does is quite difficult. It is very convenient to have a little text window with explanatory text that pops up whenever the mouse rests over the GUI or the label. To do this, you can either add a tooltip string after creation, or pass it as an optional parameter during creation. For example.

  >> set_tooltipstring(secondmenu, ‘This is the second menu’);

Place the mouse over secondmenu to see the effect of this. Alternatively, if defining the tooltip string upon creation, you could have done:

  >> SoloParamHandle(‘base’, ‘secondmenu’, ‘type’, ‘menu’, ‘string’, …
     {‘another’ ‘menu’}, ‘label’, ‘secondmenu’, ‘value’, 2, …

‘position’, [100 100 150 20], ‘TooltipString’, ‘version 2’);

To do multiple lines, you can do it like this:

  >> set_tooltipstring(secondmenu, sprintf(‘First line;\nSecond line.’));

MenuParam() shortcut function

A slightly shorter way of creating a menu type SoloParamHandle is with a utility function called MenuParam.m:

  function [sp] = MenuParam(obj, parname, parlist, parval, x, y)

The first argument, as usual, is either an object or the string ‘base’, and the second is the name of the variable to be created. The third is the list of strings for the menu items. The fourth indicates the initial value of the menu. The fifth and sixth are the position, in pixels, of the lower left corner of the menu object. The width and height take on a default value. Thus we can call

  >> MenuParam(‘base’, ‘thirdmenu’, {‘a third’ ‘menu’}, 2, 140 100);
  >> value(thirdmenu)
  ans = 
     menu

After the first six obligatory parameters, MenuParam.m takes other, optional arguments, one of which is ‘TooltipString’, for example:

  >> MenuParam(‘fourthmenu’, {‘still’ ‘another’}, 1, 140, 200, …
  	‘TooltipString’, ‘detailed tooltips are better than short ones’);


See MenuParam.m’s documentation (under construction) for information on other optional parameters.