Back to Contents

The Interface class

Summary:

See also: Classes and Objects.

Syntax

The Interface class is a built-in class provided to manipulate the user interface.

Syntax:

ui.Interface

Notes:

  1. This class does not have to be instantiated.

Methods:

Class Methods
Name Description
frontCall( module STRING, name STRING, parameter-list, returning-list ) Calls the front end function name of the module module.
See Front End Functions for more details.
getDocument()
  RETURNING om.DomDocument		 Returns the DOM document owning the Abstract User Interface tree.
getFrontEndName()
  RETURNING STRING		 Returns the type of the front end.
getFrontEndVersion()
  RETURNING STRING		 Returns the front end version string.
getRootNode()
  RETURNING om.DomNode		 Returns the root DOM node of the Abstract User Interface tree.
loadStartMenu( file STRING ) Loads the start menu defined in an XML file into the AUI tree. See StartMenus for more details.
loadToolBar( file STRING ) Loads the toolbar defined in an XML file into the AUI tree. See Toolbars for more details.
loadTopMenu( file STRING ) Loads the topmenu defined in an XML file into the AUI tree. See TopMenus for more details.
loadActionDefaults( file STRING ) Loads the default decoration for actions from a specific XML file into the AUI tree. See Action Defaults for more details.
loadStyles( file STRING ) Loads styles defined in an XML file into the AUI tree. See Presentation Styles for more details.
setName( name STRING ) Sets the name to identify the program on the front-end.
getName()
  RETURNING STRING		 Returns the identifier of the program.
setText( title STRING ) Defines a title for the program.
getText()
  RETURNING STRING		 Returns the title of the program.
setImage( name STRING ) Sets the name of the icon to be used for this program.
getImage()
  RETURNING STRING		 Returns the name of the icon.
setType( type STRING ) Defines the type of program.
getType()
  RETURNING STRING		 Returns the type of the program.
setSize( height STRING, width STRING ) Defines the initial size of the main window when using the traditional mode or when configuring a WCI container.
setContainer( name STRING ) Defines the name of the parent container of this program.
getContainer()
  RETURNING STRING		 Returns the name of the parent container of this program.
getChildCount()
  RETURNING INTEGER		 Returns the number of children in this container.
getChildInstances( name STRING )
  RETURNING INTEGER		 Returns the number of children identified by name.
refresh() Synchronizes the front end with the current AUI tree.

Usage

Getting the root DOM document

The ui.Interface.getDocument() class method returns the DomDocument object of the Abstract user Interface tree.

Getting the current front-end identifier

The ui.Interface.getFrontEndName() class method returns the type of the front-end used by the application. This is mainly provided for debugging purposes. Returned values can for example be 'GDC', 'GWC', 'Console'.

Getting the current front-end version

The ui.Interface.getFrontEndVersion() class method returns the version number of the front-end used by the application. This is mainly provided for debugging purposes.

Getting the root node of the DOM document

The ui.Interface.getRootNode() class method returns the root DomNode of the Abstract user Interface tree.

Defining the name of the application

The ui.Interface.setName() class method can be used to identify the application on the front-end. For example, this name is used in MDI configuration.

Getting the name of the application

Use the ui.Interface.getName() class method to get the name of the application previously set by setName().

Defining the title of the application

The ui.Interface.setText() class method can be used to define a main title for the application on the front-end. This title is displayed in the main Window.

Getting the title of the application

Use the ui.Interface.getText() class method to get the title of the application previously set by setText().

Defining the icon of the application

The ui.Interface.setImage() class method can be used to define the icon of the application on the front-end. This icon will be used in taskbars, for example.

Getting the icon of the application

Use the ui.Interface.getImage() class method to get the image name of the application previously set by setImage().

Defining the type of the application

The ui.Interface.setType() class method can be used to define the type of the application, typically used in MDI configurations.

Possible values can be 'normal', 'container' or 'child'.

Getting the type of the application

Use the ui.Interface.getType() class method to get the type of the application, previously set by setType().

Specify the initial size of the parent container window

The ui.Interface.setSize(height,width) class method can be used to define the initial size of the parent container window of an MDI application. The parameters can be integer or string values. By default the unit is the character grid cells, but you can add the px unit to specify the height and width in pixels.

The setSize() method can also be used to configure the size of the main window when using traditional mode, as a replacement of fgl_setsize() built-in function.

See also MDI configuration.

Defining the parent container of the application

The parent container can be specified with the ui.Interface.setContainer() class method, typically used in MDI configurations.

Getting the parent container of the application

Use the  ui.Interface.getContainer() method to get the name of the parent container of the application.

Getting the number of children in a parent container

Use the ui.Interface.getChildCount() class method to get the current number of child applications in this parent WCI.

See also MDI configuration.

Getting the number of child instances for a given application name

If you need to known how many child instances of the same application are started in the current WCI container,  call the ui.Interface.getChildInstances() class method. This method takes the application name as a parameter (the one defined with setName())

See also MDI configuration.

Refreshing the user interface

Use the ui.Interface.refresh() class method to synchronize the server-side AUI tree with the frond-end AUI tree. For more details, see "When is the front-end synchronized?".

Examples

Example 1: Get the type and version of the front end.

01 MAIN
02   MENU "Test"
03     COMMAND "Get"
04       DISPLAY "Name = " || ui.Interface.getFrontEndName()
05       DISPLAY "Version = " || ui.Interface.getFrontEndVersion()
06     COMMAND "Exit"
07       EXIT MENU
08   END MENU
09 END MAIN

Example 2: Get the AUI root node and save it to a file in XML format.

01 MAIN
02   DEFINE n om.DomNode
03   MENU "Test"
04     COMMAND "SaveUI"
05       LET n = ui.Interface.getRootNode()
06       CALL n.writeXml("auitree.xml")
07     COMMAND "Exit"
08       EXIT MENU
09   END MENU
10 END MAIN

Example 3: Using the Window Container Interface

The WCI parent program:

01 MAIN
02   CALL ui.Interface.setName("main1")
03   CALL ui.Interface.setText("This is the MDI container")
04   CALL ui.Interface.setType("container")
05   CALL ui.Interface.setSize("600px","600px")
06   CALL ui.Interface.loadStartMenu("appmenu")
07   MENU "Main"
08     COMMAND "Help" CALL help()
09     COMMAND "About" CALL aboutbox()
10     COMMAND "Exit"
11       IF ui.Interface.getChildCount()>0 THEN
12          ERROR "You must first exit the child programs."
13       ELSE
14          EXIT MENU
15       END IF
16   END MENU
17 END MAIN

The WCI child program:

01 MAIN
02   CALL ui.Interface.setName("prog1")
03   CALL ui.Interface.setText("This is module 1")
04   CALL ui.Interface.setType("child")
05   CALL ui.Interface.setContainer("main1")
06   MENU "Test"
07     COMMAND "Exit"
08       EXIT MENU
09   END MENU
10 END MAIN

Example 4: Synchronizing the AUI tree with the front end.

01 MAIN
02   DEFINE cnt INTEGER
03   OPEN WINDOW w WITH FORM "myform"
04   FOR cnt=1 TO 10
05     DISPLAY BY NAME cnt
06     CALL ui.Interface.refresh()
07     SLEEP 1
08   END FOR
09 END MAIN