Real-time displays

Within FELIX, there are several options for generating, displaying, and manipulating data in real time. Three of these options involve hard-coded commands, where the layout and function of the real-time display are controlled by the program itself. These options include the real-time phasing interface (rph), the 1D peak fitter (fit), and the real-time baseline-correction feature (rpl). The use of these real-time displays is described in more detail in the chapter describing 1D data processing.

In addition to the hard-coded real-time display commands, there also exist FCL commands for creating real-time displays via user-written macros. By combining the appropriate commands in the right sequence, virtually any symbol (and thus any corresponding display) can be manipulated in real time using tools such as buttons and sliders. Real-time displays are simply menus with special tools that adjust the displayed screen whenever you manipulate the tool. The real-time menus are in fact non-modal menus that you can display on the screen using the command:

     mnu a menu_file_name x_origin y_origin
In fact, the only major limitation so far encountered with incorporating real-time displays throughout the menus is the speed of your computer.


Graphical interface tools

Real-time macro displays are generated using a combination of four graphical interface tools: buttons, sliders, option menus, and text boxes. Together with other macro-oriented commands, these features allow you to build and customize interactive processing and analysis macros.


Buttons

You can create buttons within a real-time display macro using the following command sequence in a menu file:

     *u x_origin y_origin width label exit_status call_back_
macro 

The label argument defines the text that appears on the button, as well as a symbol name and a macro label. x_origin and y_origin reflect the position of the button in character units, and width defines the size of the button in character units. An exit_status of 0 removes the real-time display from the screen, and all other exit_status values simply call the call_back_macro and keep the real-time display active on the screen. Buttons are commonly used in a real-time display to reset symbol values and other relevant parameters to some known state or to exit the real-time display mode. To apply the function described by the button, simply click that button with the cursor. For example, to exit the real-time display and apply the current window function, click the keep button. To exit the display without updating the window function, click the quit button. The function of any button should be adequately defined by that button's label.

The button and its symbol have only have two possible states: zero or one. Zero denotes off, and in this state the button text is red; all other values denote on, and when on, the button text is black. When you select the button, it calls the call_back_macro, which performs the action intended by that button.


Sliders

A slider is a vertical or horizontal box with an adjustable "value bar" within them. Sliders are created within a real-time display macro using the following command sequence.

     *a x_origin y_origin x_size_or_y_size minimum maximum deci-
mal orientation drag_mode symbol label call_back_macro

x_origin and y_origin reflect the position of the slider in character units, and x_size or y_size define the length of the slider in character units. minimum and maximum define the minimum and maximum values of the slider. decimal tells FELIX how many decimal places to display for the slider position. orientation determines the orientation of the slider. When the orientation value is 1, the slider is drawn horizontally; otherwise it is drawn vertically. drag_mode tells the program when to call the call_back_macro: 0 means to call the call_back_macro whenever the mouse button is released, otherwise the call_back_macro is called whenever the value of the slider changes. symbol is what is updated when the slider is moved, depending on the drag_mode. The label is the text that appears within the slider. call_back_macro is the macro to be executed when the slider changes its value, depending on the drag_mode. Sliders are used within a real-time display to interactively execute a macro based on the new value for the defined symbol.

Every slider has a corresponding text entry box that you can type in to change the value of the slider. Also, text boxes are provided for the minimum and maximum values.


Option menus

Option menus are provided for real-time menus. The syntax for this tool is:

     *n x_origin y_origin width # text1 ... textN symbol call_
back_macro

x_origin and y_origin specify the position of the option menu in character units. width is the width of the option menu. # is the number of items that appear in the option menu. text1...textN are the labels that appear on the menu. symbol is the value that the option menu has before the call_back_macro is called. call_back_macro is the macro to execute when the option menu has changed its value.


Text entry boxes

The text entry box command for real-time tools has a different syntax from the regular control-panel entry box command:

     *i x_origin y_origin width type symbol call_back_macro

x_origin and y_origin specify the position of the entry box in character units. width is the width of the entry box. The type (which can be c, i, or r) defines the format of the box: a c means that the box accepts characters, an i means that the box accepts an integer, and an r means that it accepts a real number. symbol can be either a reserved symbol name or a user symbol name. In either case, the current value of the symbol is displayed in the box. The call_back_macro is called when you press <Enter> on the keyboard after changing the value in the entry box.


Writing real-time display menus and macros

The basic format of a real-time display menu is the same as the control-panel format, except that real-time display menus use different tools.


A very simple example

The example given below also exists within FELIX as an example file named macs/rt_test.mac. The macro simply creates two sliders, an option menu, and a text entry box. You can execute the macro by selecting it from the user macro list.

c**rt_test.mac
;
; Display a real-time menu
;
def tmina 1.0 ; Slider A min value
def tmaxa 10.0 ; Slider A max value
def tminb 20.0 ; Slider B min value
def tmaxb 60.0 ; Slider B max value
def tscaa 5.3 ; Slider A initial value
def tscab 25.0 ; Slider B initial value
def topt 1 ; Options current value
def tinput 3.124 ; Entry box initial value
mnu a rt_test 10 10 ; Open the control panel
return
end


c**rt_testscalea.mac
;
; Test the real-time draw scroll tool
;
tym Slider A value = &tscaa
ret
end


c**rt_testscaleb.mac
;
; Test the real-time draw scroll tool
;
tym Slider B value = &tscab
ret
end


c**rt_testoption.mac
;
; Test the real-time option menu
;
tym Option Menu selected = &topt
ret
end


c**rt_testinput.mac
;
; Test the real-time entry box
;
tym Value entered = &tinput
ret
end


c**rt_button1.mac
;
; Test the real-time button
;
if &_arg1 eq 0 then
tym Button 0 was pressed.
else
if &_arg1 eq 1 then
tym Button 1 was pressed.
else
if &_arg1 eq 2 then
tym Button 2 was pressed.
eif
eif
eif
ret
end


c**rt_test.mnu

15 50
*h 1 1 15 `REAL-TIME MENU TEST'
*a 3 4 25 tmina tmaxa 2 0 1 tscaa `Slider A' "ex rt_testscalea"
*a 3 7 25 tminb tmaxb 1 0 0 tscab `Slider B' "ex rt_testscaleb"
*c 3 10 8 `Press the left mouse on this menu'
*n 25 10 8 4 `Menu1' `Menu2' `Menu3' `Menu4' topt "ex rt_testoption"
*c 3 13 8 `Enter a Floating point number'
*i 21 13 8 r tinput "ex rt_testinput"
*u 10 16 10 `Keep' 1 "ex rt_button 1"
*u 20 16 10 `Press Me' 2 "ex rt_button 2"
*u 30 16 10 `Quit' 0 "ex rt_button 0"