ScreenDriver (P2J - Progress 4GL to Java Conversion and Runtime)

Type Parameters:

O - the type of output manager

All Known Subinterfaces:

GuiDriver<F,I>

All Known Implementing Classes:

AbstractChuiDriver, AbstractDriver, AbstractGuiDriver, BatchDriver, ChuiWebDriver, ConsoleDriver, GuiWebDriver, SwingChuiDriver, SwingGuiDriver
```
public interface ScreenDriver<O extends OutputManager<?>>
```
Common interface for all screen drivers.
This interface contains all implementation-specific methods which should be implemented from scratch for each particular driver implementation. The part of the driver which is more hardware independent is listed in OutputPrimitives interface and DriverPrimitives abstract class.
General requirements to the implementation:
At present only character based UI is supported. Therefore, all interaction with the driver assumes existence of some kind of character-based terminal. All coordinates passed are coordinates of the character row and column (Y and X respectively). All coordinates are 0-based and Y axis has down direction. Upper left corner has coordinates (0,0) and lower right - (@link OutputPrimitives#screenWidth()} - 1, {OutputPrimitives.screenHeight() - 1). There is no limitations on actual terminal size, but at present dynamic screen size change is not supported - once application starts it assumes that terminal has fixes size which remains stable until application if finished. Particular implementation may return terminal screen size different than phisical screen size, but in this case it is responsible for handling of necessary scrolling/panning/clipping, because P2J has no support for this funtionality and assumes that entire reported by driver screen area is visible to user. Note that requirement for fixed size of terminal screen applies even if terminal is suspended and then resumed. Handling size changes (if necessary) is up to the driver implementation.

Nested Class Summary

Nested Classes
Modifier and Type Interface and Description

static class ScreenDriver.UriPathAnchor
Directs how to resolve a resource relative path.

Nested Classes
Modifier and Type	Interface and Description
`static class`	`ScreenDriver.UriPathAnchor` Directs how to resolve a resource relative path.

Method Summary

All Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`void`	`beep()` Provide an audible feedback to user by generating a beep signal.
`boolean`	`captureMouseEvents(boolean state)` Enable or disable capture of mouse events.
`default ChooseFileResult`	`chooseFiles(java.lang.String title, boolean multiple, boolean upload, java.lang.String uploadDir, java.lang.String[] filters)` Supported by web-based drivers.
`void`	`clear()` Clear screen.
`default void`	`clientReady()` Notify the driver that the client is ready (useful for embedded mode, to notify the embedded app the client can handle messages).
`O`	`createOutputManager(BootstrapConfig cfg)` Get the `OutputManager` instance associated with this driver.
`default void`	`deregisterWidget(int wid)` Deregister the specified widget for mouse events.
`ChildProcessFactory`	`getChildProcessFactory()` Get driver-specific child process factory.
`WidgetFactory<?>`	`getFactory()` Get driver-specific widget factory.
`long`	`getHostByName(java.lang.String name)` Returns the currently connected client's machine name for session.
`java.lang.String`	`getHostName()` Returns the currently connected client's machine name for session.
`java.lang.String`	`getName()` Get the driver name.
`OutputPrimitives`	`getPrimitives()` Get driver-specific direct output primitives implementation.
`java.lang.String`	`getWindowSystem()` Get the default WINDOW-SYSTEM used by this driver.
`void`	`handleMouseEvent(int sourceID, java.awt.event.MouseEvent evt)` Handle the specified event, in the context of the specified widget.
`boolean`	`inBackgroundMode()` Checks if the current driver is running in background mode.
`boolean`	`inBatchMode()` Checks if the current driver is running in batch mode.
`void`	`init()` Driver initialization.
`boolean`	`isChui()` Get screen interface type.
`default boolean`	`isEmbeddedClient()` Returns true if this client runs in embedded mode.
`default boolean`	`isWeb()` All web-based drivers return `true`.
`default void`	`lockMousePointer(int widgetId, MousePtrWrapper ptr)` Lock the mouse pointer (suppress widget-specific changes) or unlock it
`default void`	`openMimeResource(boolean deleteContent, java.lang.String mimeType, java.lang.String uriString, boolean embedded)` Opens the specified resource in a browser's window.
`default void`	`openMimeResource(java.lang.String mimeType, java.lang.String resourcePath, ScreenDriver.UriPathAnchor uriPathAnchor)` Opens the specified resource in a browser's window given by its relative path in respect to the host system.
`default void`	`propagate(int windowId, int wid, MousePtrWrapper ptr)` Push information about the loaded mouse pointer for widget
`KeyCode`	`readKey()` Read single keystroke from keyboard.
`void`	`resetMode()` Reset current screen mode.
`void`	`resume()` Resume normal driver operation.
`default void`	`resume(boolean silent)` Resume normal driver operation.
`default void`	`setControl(boolean control)` Notify the driver which side has control (client-side (when `true`) or server, otherwise).
`default void`	`setCurrentLanguage(java.lang.String language)` Set new current session language for the client.
`boolean`	`setCursorStatus(boolean on)` Set cursor status (ON/OFF).
`void`	`setTerminalType(java.lang.String name)` Change terminal type to specified one.
`void`	`shutdown()` Perform driver shutdown.
`void`	`suspend()` Suspend all screen I/O operations.
`default void`	`suspend(boolean silent)` Suspend all screen I/O operations.
`java.lang.String`	`terminalType()` Obtain system/implementation specific terminal type string.
`void`	`updateClientMetrics(ClientMetrics metrics)` Updates the screen metrics.
`default void`	`widgetStateChanged(int widgetId)` Notification that this widget's state has changed (visibility, sensitivity, z-order).

- Method Detail
  - getName
```
java.lang.String getName()
```
    Get the driver name.
    
    Returns:
    
    See above.
  - createOutputManager
```
O createOutputManager(BootstrapConfig cfg)
```
    Get the OutputManager instance associated with this driver.
    
    Parameters:
    
    cfg - The initial configuration for this driver.
    
    Returns:
    
    See above.
  - setCursorStatus
```
boolean setCursorStatus(boolean on)
                 throws java.lang.IllegalStateException
```
    Set cursor status (ON/OFF).
    The implementation of this method should show/hide actual screen cursor visible to user. Remaining code assumes that actual cursor status visible to user is properly changed upon exit from this method.
    
    Parameters:
    
    on - true - show cursor, false - hide cursor.
    
    Returns:
    
    true if operation was successful.
    
    Throws:
    
    java.lang.IllegalStateException
  - clear
```
void clear()
```
    Clear screen.
    This method should clear the screen and perform necessary flushing of the system-specific buffers if necessary. Users of this method assume that actual screen appearance as it is visible to the user is properly changed upon exit from this method.
  - beep
```
void beep()
```
    Provide an audible feedback to user by generating a beep signal.
    There is no specific requirements to this method and actual implementation may do nothing if there is no way to perform audible notification to the user.
  - deregisterWidget
```
default void deregisterWidget(int wid)
```
    Deregister the specified widget for mouse events.
    
    Parameters:
    
    wid - The widget ID.
  - inBatchMode
```
boolean inBatchMode()
```
    Checks if the current driver is running in batch mode.
    
    Returns:
    
    true for batch mode, false otherwise.
  - inBackgroundMode
```
boolean inBackgroundMode()
```
    Checks if the current driver is running in background mode.
    
    Returns:
    
    true for background mode, false otherwise.
  - isEmbeddedClient
```
default boolean isEmbeddedClient()
```
    Returns true if this client runs in embedded mode.
    
    Returns:
    
    See above.
  - readKey
```
KeyCode readKey()
```
    Read single keystroke from keyboard. Returned code should be either proper Progress 4GL/P2J key code or -1 if environment-specific input cannot be properly translated.
    The list of codes and detailed description is provided in Keyboard class. The KeyProcessor can serve as an example of the key translation implementation.
    
    Returns:
    
    key code or null if no keys were pressed since last call.
  - resetMode
```
void resetMode()
```
    Reset current screen mode.
    Upon exit from this method P2J assumes that screen is in correct state and can be used for interaction with the user.
  - suspend
```
void suspend()
```
    Suspend all screen I/O operations. If implementation is terminal-based, then terminal should be released to allow other application executed from P2J access terminal.
  - resume
```
void resume()
```
    Resume normal driver operation. If implementation is terminal-based, they terminal should be acquired again and driver should be ready to perform regular screen I/O operations.
  - suspend
```
default void suspend(boolean silent)
```
    Suspend all screen I/O operations. If implementation is terminal-based, then terminal should be released to allow other application executed from P2J access terminal.
    
    Parameters:
    
    silent - silent mode flag value that can change driver reaction for some suspend/resume.
  - resume
```
default void resume(boolean silent)
```
    Resume normal driver operation. If implementation is terminal-based, they terminal should be acquired again and driver should be ready to perform regular screen I/O operations.
    
    Parameters:
    
    silent - silent mode flag value that can change driver reaction for some suspend/resume.
  - terminalType
```
java.lang.String terminalType()
```
    Obtain system/implementation specific terminal type string.
    At present this is used to implement 4GL TERMINAL function and do some terminal-specific workarounds. At present workarounds exist for "vt320" terminal type. If implementation requires no special workarounds, then it should avoid returning "vt320" as terminal type string.
    
    Returns:
    
    terminal type string.
  - setTerminalType
```
void setTerminalType(java.lang.String name)
```
    Change terminal type to specified one. The terminal-based implementation should try to change terminal type to specified one. It is assumed that passed terminal string is specific to particular driver implementation and recognized by it.
    
    Parameters:
    
    name -
  - getPrimitives
```
OutputPrimitives getPrimitives()
```
    Get driver-specific direct output primitives implementation.
    
    Returns:
    
    driver-specific instance of direct screen output primitives.
  - getFactory
```
WidgetFactory<?> getFactory()
```
    Get driver-specific widget factory.
    
    Returns:
    
    The reference to the widget factory.
  - getChildProcessFactory
```
ChildProcessFactory getChildProcessFactory()
```
    Get driver-specific child process factory.
    
    Returns:
    
    The reference to the factory.
  - init
```
void init()
```
    Driver initialization.
  - getWindowSystem
```
java.lang.String getWindowSystem()
```
    Get the default WINDOW-SYSTEM used by this driver. See ClientParameters for the list of possible values.
    
    Returns:
    
    See above.
  - isChui
```
boolean isChui()
```
    Get screen interface type.
    
    Returns:
    
    true is ChUI false is GUI
  - captureMouseEvents
```
boolean captureMouseEvents(boolean state)
```
    Enable or disable capture of mouse events.
    
    Parameters:
    
    state - true to capture mouse events, false to ignore them.
    
    Returns:
    
    The previous state.
  - handleMouseEvent
```
void handleMouseEvent(int sourceID,
                      java.awt.event.MouseEvent evt)
```
    Handle the specified event, in the context of the specified widget.
    
    Parameters:
    
    sourceID - The source widget ID.
    
    evt - The mouse event.
  - shutdown
```
void shutdown()
```
    Perform driver shutdown.
  - getHostName
```
java.lang.String getHostName()
```
    Returns the currently connected client's machine name for session.
    
    Returns:
    
    The current system logged in for the given session.
  - getHostByName
```
long getHostByName(java.lang.String name)
```
    Returns the currently connected client's machine name for session.
    
    Parameters:
    
    name - The name of the host to get IP.
    
    Returns:
    
    The current system logged in for the given session.
  - lockMousePointer
```
default void lockMousePointer(int widgetId,
                              MousePtrWrapper ptr)
```
    Lock the mouse pointer (suppress widget-specific changes) or unlock it
    
    Parameters:
    
    widgetId - the id of the active DropDown which caused the pointer lock or -1
    
    ptr - the locked mouse pointer or null for unlock
  - propagate
```
default void propagate(int windowId,
                       int wid,
                       MousePtrWrapper ptr)
```
    Push information about the loaded mouse pointer for widget
    
    Parameters:
    
    windowId - to level window id
    
    wid - widgetId
    
    ptr - mouse pointer
  - openMimeResource
```
default void openMimeResource(boolean deleteContent,
                              java.lang.String mimeType,
                              java.lang.String uriString,
                              boolean embedded)
                       throws java.net.URISyntaxException
```
    Opens the specified resource in a browser's window.
    
    Parameters:
    
    deleteContent - Indicates if the source content will be deleted after the document is loaded by the client.
    
    mimeType - The resource mime type.
    
    uriString - The string presentation of the target resource.
    
    embedded - The document is embedded in the template document.
    
    Throws:
    
    java.net.URISyntaxException - If the string presentation of the target resource is not formatted strictly according to to RFC2396 and cannot be converted to a URI.
  - openMimeResource
```
default void openMimeResource(java.lang.String mimeType,
                              java.lang.String resourcePath,
                              ScreenDriver.UriPathAnchor uriPathAnchor)
```
    Opens the specified resource in a browser's window given by its relative path in respect to the host system.
    
    Parameters:
    
    mimeType - The resource mime type.
    
    resourcePath - The relative path to the resource in respect to the host service.
    
    uriPathAnchor - Instructs how to resolve the given resource path.
  - clientReady
```
default void clientReady()
```
    Notify the driver that the client is ready (useful for embedded mode, to notify the embedded app the client can handle messages).
  - setControl
```
default void setControl(boolean control)
```
    Notify the driver which side has control (client-side (when true) or server, otherwise).
    
    Parameters:
    
    control - Flag indicating (when true) that the client-side has control.
  - widgetStateChanged
```
default void widgetStateChanged(int widgetId)
```
    Notification that this widget's state has changed (visibility, sensitivity, z-order).
  - updateClientMetrics
```
void updateClientMetrics(ClientMetrics metrics)
```
    Updates the screen metrics.
    
    Parameters:
    
    metrics - The instance to update.
  - isWeb
```
default boolean isWeb()
```
    All web-based drivers return true.
    
    Returns:
    
    see above.
  - chooseFiles
```
default ChooseFileResult chooseFiles(java.lang.String title,
                                     boolean multiple,
                                     boolean upload,
                                     java.lang.String uploadDir,
                                     java.lang.String[] filters)
```
    Supported by web-based drivers. Provides web-native UI for selecting or uploading files from the web-browser local files to the web server file system. The method blocks until the file upload UI is not dismissed.
    
    Parameters:
    
    title - Upload title.
    
    multiple - true to allow upload or selection of multiple files.
    
    upload - When true the selected files will be uploaded to the web server, when false only the selected file names will be returned.
    
    uploadDir - The directory on the web server the files will be uploaded to.
    
    filters - Defines the file types the file input should accept. The first element denotes a filter name and the next element defines a file specification expression.
    
    Returns:
    
    ChooseFileResult instance.
  - setCurrentLanguage
```
default void setCurrentLanguage(java.lang.String language)
```
    Set new current session language for the client.
    
    Parameters:
    
    language - The language identifier

Interface ScreenDriver<O extends OutputManager<?>>

Nested Class Summary

Method Summary

Method Detail

getName

createOutputManager

setCursorStatus

clear

beep

deregisterWidget

inBatchMode

inBackgroundMode

isEmbeddedClient

readKey

resetMode

suspend

resume

suspend

resume

terminalType

setTerminalType

getPrimitives

getFactory

getChildProcessFactory

init

getWindowSystem

isChui

captureMouseEvents

handleMouseEvent

shutdown

getHostName

getHostByName

lockMousePointer

propagate

openMimeResource

openMimeResource

clientReady

setControl

widgetStateChanged

updateClientMetrics

isWeb

chooseFiles

setCurrentLanguage