Quick GUI Library

From OC Systems Wiki!
Jump to: navigation, search

quick_gui Library

quick_gui.ual is a library of functions to provide simple Java GUI support to a user-written probe. The interface is defined in $APROBE/include/quick_gui.h, and includes histogram and plot graph support, as well pop-up Yes/No and message dialogs. Use of this library is illustrated by the $APROBE/examples/learn/visualize_data example.

The contents of quick_gui.h is reproduced here with some additional comments and an example.

Histogram

For each monitored variable in your program, call ap_CreateHistogram() to allocate an object that will keep track of its values' frequency distribution.

typedef struct _ap_HistogramObject_ *ap_HistogramObjectPtrT;
 
 ap_HistogramObjectPtrT ap_CreateHistogram(
      ap_NameT Title,
      int      Granularity);

void ap_UpdateHistogram(
      ap_HistogramObjectPtrT Histogram,
      int                    NewValue);

Call ap_UpdateHistogram() with the current value of the monitored variable. This can be done periodically, or every time the variable changes.

ap_UpdateHistogramValues() will add a new value to the histogram, but will not redraw it. Use it when you want to display a large number of updates in one batch operation.

void ap_UpdateHistogramValues(
      ap_HistogramObjectPtrT Histogram,
      int                    NewValue);

Call ap_DisplayHistogram() to redraw the histogram with the current values. This can be done periodically (using ap_DoPeriodically()), while ap_UpdateHistogramValues() could be called for each new value of the monitored variable.

void ap_DisplayHistogram(
      ap_HistogramObjectPtrT Histogram);

XY Graph

This is a traditional XY graph, such as used by the Heap Probe. To use it, you create a graph object with a few basic attributes, then send points to be plotted on the graph.

Call ap_CreateXYGraph() to create a new empty XY graph object. Provide the title and the labels for the axes.

MaxNumberOfPoints indicates the maximum number of pairs kept in the graph, before the data scroll off the left side of the graph. Give zero to keep all the data points and compress the X axis instead of scrolling.

typedef struct _ap_XYGraphObject_ *ap_XYGraphObjectPtrT;

ap_XYGraphObjectPtrT ap_CreateXYGraph(
      ap_NameT Title,
      ap_NameT X_AxisName,
      ap_NameT Y_AxisName,
      int      MaxNumberOfPoints);


Call ap_PlotGraphUpdate() with the current X and Y coordinates.

void ap_UpdateXYGraph(
   ap_XYGraphObjectPtrT Graph,
   double               X,
   double               Y);

Yes-No Dialog

ap_AskYesOrNo() is a simple call you can make to prompt the user before taking some action. Returns TRUE if Yes, FALSE otherwise.

ap_BooleanT ap_AskYesOrNo(
   ap_NameT QuestionToAsk,
   ap_NameT Title,
   ap_NameT HelpText);

Message Dialog

ap_DisplayMessageAndWait() simply pops up a dialog containing the message provided, and waits for the user to click OK.

void ap_DisplayMessageAndWait(
   ap_NameT Title,
   ap_NameT Message,
   ap_NameT HelpText);

Text Input Dialog

Call ap_InputText() to prompt the user for a text string, such as a name or value, and wait for the user to click OK or Cancel. Returns TRUE and the InputTextBuffer if the user chose OK; returns FALSE if Cancel was pressed.

ap_BooleanT ap_InputText(
   ap_NameT Title,
   ap_NameT Prompt,
   ap_NameT HelpText,
   char     *InputTextBuffer);

Example

The following is "visualize_data.apc" found on-line with the corresponding test program in [../examples/learn/visualize_data/README $APROBE/examples/learn/visualize_data]. This probe will graphically display the value of the target variable MyTargetVariable by plotting its value every second and by drawing the histogram of the frequency distribution for each value of it.

The first part shows the declaration of the graph objects and the function that is called to update them. The second is the "probe program on entry" action that initializes the graph objects and registers the update function to be called periodically.

 #include "quick_gui.h"
 
 static ap_HistogramObjectPtrT HistogramObjectPtr = NULL;
 static ap_XYGraphObjectPtrT   XYGraphObjectPtr   = NULL;
 
 // Define the action that updates the graph, to be called by
 // ap_DoPeriodically()
 
 void '''MyPeriodicAction'''(void *EP)
 {
   // Note the use of the target expression $MyTargetVariable.
   // MyTargetVariable is not declared in this file, but rather is the name
   // of a variable declared in the target program.
 
 ap_UpdateHistogram(
     HistogramObjectPtr,           // Pointer to the histogram object
     $MyTargetVariable);           // Integer value to update the histogram with
 
   ap_UpdateXYGraph(
     XYGraphObjectPtr, // Pointer to the XYGraph object
     ap_TimeToSeconds(ap_ElapsedTime()),
                 // Seconds since the program start
     $MyTargetVariable);           // vs. the value of <code>MyTargetVariable
 }
 

Example D-13a. Define Graph Objects and Update Function

 probe program
 {
   on_entry
   {
     // Create a new histogram object that could be used in updates
     HistogramObjectPtr = '''ap_CreateHistogram'''(
       "My Histogram",         // Title of the histogram
       5);   // Granularity of the histogram
 
     // Create a new XYGraph object that could be used for plotting
     XYGraphObjectPtr = '''ap_CreateXYGraph'''(
       "My Plot",        // Title of the Graph
       "Time",       // X coordinate name
       "Value of 'MyTargetVariable'",
               // Y coordinate name
       0);       // Number of points, 0 => keep them all
 
     // Register to update the graphs every second.
     ap_DoPeriodically(
       MyPeriodicAction,           // Periodic action to perform
       1,            // Do it every 1 second
       NULL);            // No data to pass to the periodic routine
    }
 }
 

Example D-13b. Create Graphs and Register Update Function