Window Manager Programmer Notes

The window manager is used to make all the different control station modules to appear to be one application. Any application within the control station system uses the window manager engine to open windows, update menus and configure window placement.

Contents

Window Manager Standards
Application Codes
Linking to the WindowManger
Adding an Application to the Window Manager
Linking to the Window Manager Utilities

Window Manager Standards

Window Sizes

Small Windows (1x1) have an internal size of 310 x 220 pixels.

Large Windows (2x2) have an internal size of 630 x480 pixels.

(2 x 3) have an internal size of 630 x 740 pixels.

(4 x 2) have an internal size of 1260 x 480 pixels.

Menus

Menus are 130 pixels wide,
Each button on the menu is a lightbutton 20 pixels high, 120 pixels wide, Flat boxtype
 
Color

Color is used to provide information to the operator in a compact space. The color of objects can be used to determine the type of object. In the figure below is an example of a form showing three types of objects: command objects, output objects, and inactive command objects. In general objects which colored gray, are command objects and can be manipulated and used to control some function. If the label on that object is black it's currently active. A gray label indicates that the specific object is inactive. Objects which are not gray, generally are colored the same as the background, are output displays only and can not be manipulated.

Many buttons and display indicators use color to convey the current status of the process represented. Below is a chart of the colors used to display information along with definitions used for generic and specific functions.

 Color  Color Definition  Generic Definition  Command Status Command Authority  Software Process
 Green  MOD_RUNNING_COL  Confirmed On Command On Confirmed Authority Given  Running
 Blue  MOD_PENDING_COL  Pending On Command On given, but not Confirmed Authority Pending  Pending On
 Gray  MOD_DEFAULT_COL  Confirmed Off  Command Off Confirmed No Authority, But Allowed  Off
 Yellow  MOD_PENDINGOFF_COL  Pending Off  Command Off given, but not Confirmed Authority Removal Pending  Pending Off
 Red  MOD_CRASHED_COL  Error  Error Authority Removed  Crashed
 Black  MOD_CANT_COL  Not Allowed  N/A  No Authority, Not Allowed  N/A
 Dark Gray MOD_DEACTIVATE_COL Deactivated Object      
 Background Blue MOD_BACKGROUND_COL Telemetry Object  N/A  N/A  N/A

The last two colors defined in the table above are used to indicate that an object can not be used to command. When a label of a button or other object is not black, but a dark gray, than that object is inactive. This typically occurs when not in a proper control mode or if no command authority exist. Objects which are the color of the background color can not command either, they are used to monitor output data from the project.

In the figure above there are several sliders in the center of the form. Half of them are colored blue, they represent the commanded data to the vehicle. Since it is not know if that data will make it to the vehicle, it is considered pending. The other sliders are colored green, they represent information from the vehicle, which is confirmed.

Input Fields

Input fields are small boxes that either display text or allow the operator to type in text. There is a minimum size required so that the text can be displayed, the table below shows the height and width according to font size, input box type, and number of characters displayed.

 Helvetica Font Size Input Field Boxtype Input Height Pixels Input Width Pixels
 8 FL_FRAME_BOX
16
18 Bold
6 digits = 40
9 digits = 55
 8  FL_DOWN_BOX 18
6 digits = 42
9 digits = 58
10 digits = 62
 10 FL_FRAME BOX 22  
 10  FL_DOWN_BOX 24  


Application Codes

The window manager connects all the modules within the control system. One module can open any form from another module. The status of each module is known by the whole control system. This ability is done by using shared memory and using individual codes destinguishing each module. These code are used in many ways and are listed below.

 Code Program Description Executable Name
11 Input Device Display IODisplay
12 Dynamics Controller DynCont
13 Graphical Simulation gfx_sim
14 Command Checker CmdChecker
15 SCAMP Control Station scamp
     
20 Ranger NBV Flight Control NBVFlight
21 Ranger NBV Buoyancy Compensation Control BCS
22 Ranger NBV Thrusters Feedback Thrusters
23 Ranger NBV Software Control NBVSc
28  Joe Grave's Estimation Program EGI2
     
30 Left Arm Summary Control LarmSum
31 Left Arm Parameters Control LarmParam
32 Left Arm Force/Torque Sensor LarmFT
33 Left Arm Software Control LarmSc
     
40 Right Arm Summary Control RarmSum
41 Right Arm Parameters Control RarmParam
42 Right Arm Force/Torque Sensor RarmFT
43 Right Arm Software Control RarmSc
     
50 Grapple Arm Summary Control GarmSum
51 Grapple Arm Parameters Control GarmParam
52 Grapple Arm Force/Torque Sensor GarmFT
53 Grapple Arm Software Control GarmSc
     
60 Video Arm Summary Control VarmSum
61 Video Arm Parameters Control VarmParam
62 Video Arm Force/Torque Sensor VarmFT
63 Video Arm Software Control VarmSc
     
 70 Command Authority Control dmsca
     
80 Left 8DOF Arm Summary Control Larm8Sum
81 Left 8DOF Arm Parameters Control Larm8Param
82 Left 8DOF Arm Force/Torque Sensor Larm8FT
83 Left 8DOF Arm Software Control Larm8Sc
     
90 Right 8DOF Arm Summary Control Rarm8Sum
91 Right 8DOF Arm Parameters Control Rarm8Param
92 Right 8DOF Arm Force/Torque Sensor Rarm8FT
93 Right 8DOF Arm Software Control Rarm8Sc
     
100 Positioning Leg Summary Control ParmSum
101 Positioning Leg Parameters Control ParmParam
102 Positioning Leg Force/Torque Sensor ParmFT
103 Positioning Leg Software Control ParmSc
     
110 Video 7DOF Arm Summary Control Varm7Sum
111 Video 7DOF Arm Parameters Control Varm7Param
112 Video 7DOF Arm Force/Torque Sensor Varm7FT
113 Video 7DOF Arm Software Control Varm7Sc


Linking to the Window Manager

The following notes are to be used by a programmer to link a new control station module to the window manager. When these changes have been made, the entire control station system should be remade, then all the applications can interface with the new module.

Development Path: ACS/csWindowManager

Files Required

 headers

wm_extern.h

wm_standards.h - when using the standards macros

 files

wm_forms.c - functions which create the window menus

wm_CB.c - holds most functions

 libraries

libforms.a

libforms.so - needed at run time

API Functions

 Function Prototype:
void wm_setupWm(int argc, char *argv[])
 Description: This function performs the many initialization operations required to run the window manager
 Notes: Call after fl_initialize()
 Function Prototype:
void wm_checkToOpenWindow (void)
 Description: This function reads the shared memory segment to determine if any windows of this module require showing or hiding. It the performs the appropriate steps.
 Notes:  Call in main event loop
 Function Prototype:
void wm_updateMenu (void)
 Description: This function reads the shared memory segment to determine the status of all windows for all modules in the application. The menus are updated to indicate the windows' staus.
 Notes: Call infrequently in main event loop
 Function Prototype:
void programQuitCB(void)
 Description: This function allows the programmer to clean up the local application. This could include freeing memory, closing a file, or terminating additional processes.
 Notes: Must use the flag -DPROGRAMQUITCB in Makefile to be able to use the function. This fuction will then automatically be called when the application is terminated.


Adding an Application to the Window Manager

wm_CB.h

Add window application definition, use other definitions as a template

 #ifdef WmAppl##
	.
	.
 #endif

May need to change definition of Wm_runPath, Wm_runExec to include the new application.

 

wm_CB.c

wm_create_the_forms

add if created new menu option on Display Menu results in a new menu. This will allow the new menu to be displayed appropriately.

wm_setupMenus

add raw callback to any new menu created

wm_setupForms

add window definitions to name each form and label it. , use other definitions as a template

  #ifdef WmAppl##
  .
  .
  #endif
wm_loadApplicationFile

add new fscanf line to execute the applicaiton

wm_displayMenuCB

add a new case to either show menu or open the application

wm_updateMenu

add case using another as template

update numwindows, displayMenuButton[?] and button inside any new menu.

 

wm_rangerPath.dat

add a line for the new application path

 

wm_form.c, wm_forms.h

Use forms designer, fdesign, to create new menu item on an exsisting menu or create a new menu.

1) Button on display menu

Name: displayMenuButton[x]

CB: displayMenuCB(x)

x should be different from any other button on display menu

2) If a new menu is generated call it <>Menu eg. FlightMenu

Buttons of the menue called <>MenuButton[i] with a callback of

wm_openWindowCB(x)

where x = Wm_appl*100 + i

Use the same convention if adding a button to exsisting menu


Linking to the Window Manager Utilities

The window manager utilities are extensions to the window manager engine. Although not required most control station modules use them. Two utilities are currently in these files. First timing utilities which allow the modules to run a specific loop rate, freeing up the processor for other applications. Second, a utility to fix a bug for applicaitons which monitor the command authrority of the data management system.

Development Path: ACS/csWindowManager

Files Required
 headers

wmu_CB.h

wmu_extern.h - although I haven't needed it yet

 files wmu_CB.c
 libraries NONE

API Functions
 Function Prototype:
void wmu_initTimer(long sec, long usec)
 Description: This function initiates the timer for an application. When sigpause(SIGALRM) is called in the main event loop. The programwill wait until the timer has expired then the function wmu_catcher is activated. This allows for a program to run at the speed of the timer, or slower.
 Notes: Call during initialization and any time to change the main event loop rate.
 Function Prototype:
void wmu_catcher(void)
 Description: This function is called when the timer function has expired, sigpause(SIGALRM). It is required by the timer function, however no other use occurs.
 Notes: Called automatically when an alarm is generated, this could be due to the SIGALARM as set when initilaizing the timer. However other alarm messages may call this function as well.
 Function Prototype:
float wmu_updateLoopRate (short tick)
 Description: This function updates the loop rate input field in the preferences window. Called within the main loop and passed the number of loop cycles (tick) which has passed, this function determines the time that has expired and averages the event loop rate.
 Notes:

Call infrequently in main event loop

Only wmu_updateLoopRate or (wmu_forceLoopRate and wmu_sginap) are used in the program not both.

 Function Prototype:
float wmu_forceLoopRate (short tick, short target)
 Description: This function updates the loop rate input field in the preferences window. Called within the main loop and passed the number of loop cycles, target, which has passed, this function determines the time that has expired and averages the event loop rate. This function also updates the amount of time spent in wmu_sginap. This additional feature allows to compensate for error which seem to occur using just the sigpause() function. This compensation occurs when the number of cycles that have occured (tick) is not close to the number that should have occured (target).
 Notes:

Call infrequently in main event loop

Only wmu_updateLoopRate or (wmu_forceLoopRate and wmu_sginap) are used in the program not both.

 Function Prototype:
void wmu_sginap(void)
 Description: This function calls sginap using the global variable wmu_nap, which is continually updated to keep the program running at its target loop rate.
 Notes: Call in the main event loop after wmu_forceLoopRate
 Function Prototype:
void wmu_loadCmdDes(Cmd_Auth_Type *archive, 
 Cmd_Auth_Type_Msg data)
 Description: This function loads the host/process information (data) into a global variable (archive). This variable can be accesed later to recall this information. This is required because the ST_<>_Cmd_Des variable is accedently overwritten for modules with DMS monitor commands.
 Notes: Call before Polling the DMS Command Authority Consumer
 Function Prototype:
void wmu_reloadCmdDes(Cmd_Auth_Type *archive,
 Cmd_Auth_Type_Msg data)
 Description: This function reloads the host/process information (archive) back into the Desired Command symbol (data). This is required because the ST_<>_Cmd_Des variable is accedently overwritten for module with monitor commands.
 Notes: Call after Polling the DMS Command Authority Consumer