Document: ggi Purpose: Describes Ggi, the GIPSY graphical user interface Category: USER-INTERFACE, SYSTEM File: ggi.src Author: J.P. Terlouw Description: Ggi (``GIPSY graphical interface'') is a collection of routines which allows the programmer to construct a graphical user interface for a task. It is based on the X Toolkit and the almost universally available Athena widgets. It makes use of GIPSY's event-handling facilities. The following routines are available: 1. routines which define some global setting: -------------------------------------------- GgiAutoLayout sets Ggi's layout policy, either automatic or explicit. GgiPostponeRealize causes Ggi to postpone realization of elements on the screen until this is explicitly requested. GgiRealize realize created elements. GgiSetHeight set the application's main window height. GgiSetWidth set the application's main window width. GgiConfigure for automatic layout policy, set a number of dimensions. GgiSetResources set the application's fallback resources. void GgiSetDisplay override the default display name. 2. routines which create a user interface element: -------------------------------------------------- a. simple elements ------------------ GgiTextField create a text input field. GgiEditor create a text editor element. GgiButton create a push-down button. GgiMenu create a roll-down menu. GgiList create a list-selector element. GgiGauge create a bar-shaped analog valuator. GgiDial create a dial-shaped analog valuator. GgiLabel create a text output field. GgiLogo create the GIPSY logo. GgiProgress create a "progress bar". GgiPlotField create a PGPLOT-compatible plot area. GgiCanvas create an element without built-in behaviour. GgiShell create a secondary window containing other elements. GgiDialog like GgiShell, but interaction limited to this window. GgiForm create a container element for other elements. GgiViewport create a scrollable container element. b. elements constructed from other elements ------------------------------------------- GgiPrompter prompter element implementing a simple dialog. GgiPlotPrompter prompter element for selecting a plot device. GgiVerify question pop-up window waiting for user action. GgiPlotColorEditor colormap editing element for plot fields. GgiFileBrowser directory browser and file selector. GgiInset set, subset and box input element. GgiHelpMenu configurable menu with associated help text pop-up. GgiColorMenu menu for selecting standard PGPLOT colors GgiTextMenu menu for selecting text items GgiHeaderButton button with associated GDS set header text pop-up. 3. routines which manipulate a user interface element: ------------------------------------------------------ GgiActivate make the element sensitive to user interaction. GgiDeactivate make the element insensitive to user interaction. GgiHelpText set or modify the element's help text ('tip'). GgiSetLabel set or modify the element's descriptive label. GgiSetBitmap set or modify a bitmap in the element's label. GgiAlignLabel modify the label's alignment (left, center, right). GgiSetPosition set or modify the element's position. GgiSetRange modify the range of an analog valuator element. GgiSetFormat modifies an analog valuator's output format. GgiSetCircular cause an analog valuator to wrap around outside its range. GgiSetKeyword modifies an element's associated user input keyword GgiMenuLabels modify the entry labels of a menu element. GgiListLabels modify the entry labels of a list element. GgiDelete delete the element. GgiUseShell specify secondary window in which to create elements. GgiShowShell make secondary window visible or invisible. GgiPlotExport make plotfield available for other tasks. GgiPlotXor set non-destructive plotting mode. GgiPlotColors obtain colors for the plotfields master table. GgiPlotMapColors map plotfield colors to colors from the master table. GgiPlotFrames create off-screen pixmaps associated with plot field. GgiPlotRecord record current plot in specified pixmap. GgiPlotShow copy specified pixmap to current plot window. GgiPlotCopy copy specified pixmap to another pixmap GgiPlotDest specify destination pixmap for plotting GgiPlotColorEditor modify parameters in colormap editing element. ScheduleGgiPlotCursor register function receiving coordinates from a plot field. DescheduleGgiPlotCursor de-register coordinate function. 4. miscellaneous routines: -------------------------- GgiWidth return the element's width in pixels. GgiHeight return the element's height in pixels. GgiShowDoc pop up a document. GgiDisplay return the X11 display identification. GgiWindow return the element's X11 window identification. GgiWidget return the element's active widget. GgiContext return the Xt application context. GgiIsRealized test whether element is realized. GgiHandleEvents explicitly process outstanding events. GgiKeyIdent return a user input keyword's identification number. GgiMpeg Record a movie in MPEG format. GgiPlotMovie Record a movie in MPEG format (Simple interface to GgiMpeg) All 'active' elements are associated with a user input keyword through which user inputs are transferred to the application. Once the user interface has been constructed, the task normally only communicates with the user through keywords. This communication is bi-directional: e.g. when the user makes a change in a text input field, this is notified to the application code, but when the application changes the keyword value by calling wkey_c(), the text input field is also updated. This also works for analog valuators, buttons, etc. It is possible to have more than one element associated with a particular keyword, e.g. both a valuator and a text field. In this case, when one element is manipulated, the other element(s) will follow it. Ggi must be initialized before scheduling any event handlers. Creating any element implicitly initializes Ggi. Updates: Jan 14, 1998: JPT, Document created. Feb 24, 1998: JPT, GgiWidget and GgiContext added. Feb 26, 1998: JPT, Plot field added. Mar 4, 1998: JPT, GgiPlotXor added. Improved help pop-up. Mar 9, 1998: JPT, GgiMenuLabels, GgiWidth and GgiHeight added. Mar 16, 1998: JPT, Bug in plot initialization fixed. Mar 23, 1998: JPT, Bug fixed in GgiMenuLabels, plotcursor improved. Mar 25, 1998: JPT, GgiSetBitmap added. Mar 31, 1998: JPT, Shell element added. Apr 17, 1998: JPT, Use Slider2 widget for gauge. May 13, 1998: JPT, Form element added. Jun 8, 1998: JPT, Small improvements. Jun 22, 1998: JPT, Small improvements. Jun 24, 1998: JPT, GgiDialog added. Jul 2, 1998: JPT, Improved XOR plot mode; special menu entries. Aug 26, 1998: JPT, Small improvements. Sep 11, 1998: JPT, Improved plot driver, added GgiHandleEvents. Nov 9, 1998: JPT, Plot driver modified for PGPLOT 5.2.0. Feb 8, 1999: JPT, Updated document for new features. Feb 19, 1999: JPT, Textfields now always generate event on RETURN. Mar 31, 1999: JPT, Recursive deletion. GgiPrompter added. Apr 27, 1999: JPT, GgiSetKeyword added. May 3, 1999: JPT, Fixed bug in SHELLdelete method May 28, 1999: JPT, GgiPlotPrompter added. Jun 23, 1999: JPT, Merge resource strings. Jul 1, 1999: JPT, GgiProgress added. Aug 4, 1999: JPT, GgiVerify added. Sep 20, 1999: JPT, GgiPlotMapColors, GgiPlotColorEditor and GgiIsRealized added. Nov 2, 1999: JPT, GgiViewport, GgiList and GgiListLabels added. Nov 25, 1999: JPT, GgiFileBrowser and GgiInset added. Feb 17, 2000: JPT, GgiHelpMenu added. Feb 18, 2000: JPT, Prevent window manager close. Apr 18, 2000: JPT, Changed plotcursor and other small improvements. Jun 23, 2000: JPT, Canvas now Simple widget instead of Label. Jul 12, 2000: JPT, Documented GgiHelpMenu, GgiHeaderButton and GgiKeyIdent. Aug 21, 2000: JPT, Added GgiColorMenu and GgiTextMenu. Sep 5, 2000: JPT, Added ggiGetMap to GgiPlotColorEditor. Jan 10, 2001: JPT, Check for pseudocolor visual; added GgiSetDisplay. Feb 1, 2001: JPT, Support for non-default visuals. Mar 12, 2001: JPT, Support for TrueColor visuals. Mar 15, 2001: JPT, Improved keyboard mapping for plots. Mar 22, 2001: JPT, Added arrow keys for plots. Apr 24, 2001: JPT, Logging feature added. May 9, 2001: JPT, General options pop-up. Oct 9, 2001: JPT, Keyword interaction for GgiViewport. Nov 12, 2001: JPT, Fixed visual bug in GgiMenuLabels. Nov 23, 2001: JPT, Allow multiple X server screens. May 9, 2003: JPT, Handle expose events for non-backing X servers. Jun 25, 2004: JPT, GgiPlotColorEditor: x-y manipulation added. Aug 13, 2004: JPT, Added GgiPlotExport. Nov 04, 2004: JPT, Changed keyboard focus for plotfields. Dec 08, 2004: JPT, Implemented MPEG recording. Mar 10, 2005: JPT, Implemented GgiPlotCopy and GgiPlotDest. Mar 16, 2006: JPT, Modified GgiShowShell() to prevent KDE losing dialog pop-ups; (temporarily) disabled GgiTextfield's text selection feature. Mar 23, 2006: JPT, Optimized plotfield expose event handling. Sep 19, 2007: JPT, Empty help message string pop-up suppressed. Apr 21, 2008: JPT, Reversed default colour behaviour for GGIOPT=. Apr 23, 2008: JPT, Fixed help text background problem. Dec 20, 2008: JPT, Changed fallback resources font specs. Jun 2, 2010: JPT, Avoid some X servers' XGetImage inefficiency.