private.workSpace - WIN

Class workSpace
Inherits from __classBase.

The workSpace class provides the top WIN system object. The class, and a single object private.workspace, are defined privately in the win API. While the work space object is obtainable through window:get_workspace, generally it is not required as its features are more conveniently available through the available class objects.

Properties

ws__app_dir string Desktop directory under /win/devices for link up at application start up.
ws__app_frame applicationFrame Application frame for link up at application start up.
ws__app_path string Application program file path for link up at application start up.
ws__app_thread thread Application thread for link up at application start up.
ws__comms number Count of system (permanent) comm connections.
ws__desktops table Collection of desktops.
ws__last_update number
Last time (of os.clock ()) that the desktops were automatically updated.
ws__shutdown number
Indicates if a shutdown operation is required (1 = reboot, 2 = shutdown).
ws__syscomms table Collection of comm objects.
ws__timers table List of registered timers and alarms.
ws__wnd_events table List of registered desired window events.

Methods

See also API Reference, WIN.

private.workSpace:altkey

depressed workSpace:altkey ()

Returns true if the alternate key is active, false if not.

Parameters
none


Returns
depressed boolean True if depressed, false if not.

Remarks
See workSpace:shiftkey, workSpace:ctrlkey.


top


private.workSpace:combo_keys

match workSpace:combo_keys (ctrl, alt, shift)

Returns true if the current key state of the control, alternate and shift keys matches those indicated through the parameters, false if not.

Parameters
ctrl boolean True for control key depressed, false for not.
alt boolean True for alternate key depressed, false for not.
shift boolean True for shift key depressed, false for not.

Returns
match boolean True if keys state matches.

Remarks
Use window:combo_keys instead.


top


private.workSpace:comm_close

result workSpace:comm_close (name)

Closes a comm connection in the system's collection.

Parameters
name string The name of the connection to close.

Returns
result boolean True if the connection was closed, false if not (the connection wasn't found).

Remarks
See window:comm_close, workSpace:comm_open.


top


private.workSpace:comm_enabled

result workSpace:comm_enabled ()

Returns whether there are any system comm connections (created from the /win.ini file).

Parameters
none


Returns
result boolean True if there are any connections, otherwise false.

Remarks
See window:comm_enabled.


top


private.workSpace:comm_find

com workSpace:comm_find (name)

Finds and returns a matching comm connection.

Parameters
name string/nil The name of the connection. If nil the first connection created is returned, if any.

Returns
com comm The comm object or nil if none matching found.

Remarks
If name is nil the first connection created is returned, if any. Generally this is the first connection in the /win.ini file.

See window:comm_find.


top


private.workSpace:comm_open

com workSpace:comm_open (name, timeout)

Opens a new comm connection and returns the comm object.

Parameters
name string/nil The name of the connection. If nil a unique name is generated.
timeout number/nil Count of os.clock () an operation will wait/attempt until a failure is accepted. If nil the default is 5.

Returns
com comm The comm connection object, or nil if the connection could not be established.

Remarks
The created connection is maintained in the system's collection.

If an application opens a connection for its own purposes, it should close it when no longer required.

See window:comm_open, workSpace:comm_close.


top


private.workSpace:comm_register

result workSpace:comm_register (wnd, application, name)

Registers an interest in the comm connection to receive messages and sent notifications.

Parameters
wnd window The window registering the interest.
application string Identifier for filtering which messages should be passed to the sent notification and receive handlers.
name string/nil The name of the connection to register the interest with. If nil the first connection created is used, if any.

Returns
result boolean True if the interest was successfully registered, false if not (no appropriate connection was found).

Remarks
If name is nil the first connection created is used, if any. Generally this is the first connection in the /win.ini file.

When the interest in the connection is no longer required it should be unregistered with workSpace:comm_unregister.

See window:on_receive, window:on_sent, window:want_messages.


top


private.workSpace:comm_send

message_id workSpace:comm_send (recipient, application, context, data, name)

Send a message across a comm connection.

Parameters
recipient string/number/nil The intended recipient computer's label or id number. If nil the message is broadcasted to all computers.
application string Identifier for message filtering. This should match the sender's and recipient's registered application filter.
context string Message specific context. This states the purpose/structure of the data.
data any
The data for the message, if any.
name string/nil The name of the connection to use to send the message. If nil the first connection created is used, if any.

Returns
message_id number Unique identifier for the message, or nil if the send was not successful (no appropriate connection or the message was addressed to the sending computer). This can be used to identify the message in the sent handler.

Remarks
While a message may be sent without registering an interest in the connection, sent notifications cannot be implemented without it.

Messages are not sent directly through this call, but are queued to be sent by the mechanism. It will be sent repeatedly by the system's idle processor up to the timeout value or until a confirmation is received.

See window:send_message.


top


private.workSpace:comm_unregister

result workSpace:comm_unregister (wnd, application, name)

Unregisters an interest in the comm connection registered with workSpace:comm_register.

Parameters
wnd window The window that registered the interest.
application string/nil The message filtering identifier the interest was registered with.
name string/nil The name of the connection the interest was registered with. If nil the first connection created is used, if any.

Returns
result boolean True if the interest was successfully unregistered, false if not (a matching interest was not found on the specified connection).

Remarks
The parameters passed to workSpace:comm_unregister should match those passed to workSpace:comm_register to register the interest. If only the wnd parameter is given all interests for that window on all connections are unregistered, in which case the return value is always true.

See window:unwant_messages.


top


private.workSpace:constructor

ws workSpace:constructor ()

Constructs and returns the instantiated work space object.

Parameters
none


Returns
ws workSpace The instantiated work space object.

Remarks


top


private.workSpace:create_desktop

desktop workSpace:create_desktop (type, dir, width, channels)

Creates the desktop window for the given side if a display device exists, returning the created desktop window. .

Parameters
type
string
Type of device. Can be:
"term"
"monitor"
dir
string
Desktop directory under /win/devices.
width
number
Display width for multi-monitor devices. Ignored for others.
channels
string/list
The digilines channel/s of the attached device.

Returns
desktop desktopWindow Desktop window or nil if not created.

Remarks


top


private.workSpace:create_desktops

workSpace:create_desktops ()

Creates and initializes the desktops as required.

Parameters
none


Returns
none


Remarks


top


private.workSpace:ctrlkey

depressed workSpace:ctrlkey ()

Returns true if the state of the control key is active, false if not.

Parameters
none


Returns
depressed boolean True if depressed, false if not.

Remarks
See workSpace:shiftkey, workSpace:altkey.


top


private.workSpace:desktop_startup

workSpace:desktop_startup (dir)

Implements the startup.ini file for the desktop indicated by dir, if the file and desktop exist.

Parameters
dir
string
Desktop directory under /win/devices.

Returns
none


Remarks


top


private.workSpace:desktops

dirs workSpace:desktops ()

Returns an indexed table of strings of desktop directories under /win/devices, one for each device with a desktop.

Parameters
none


Returns
dirs
table Tables of desktop directories.

Remarks
See workSpace:get_desktop.


top


private.workSpace:dispatch_event

workSpace:dispatch_event (event, p1, p2, p3, p4, p5, ...)

The main system's pump. Called internally by the system's main loop, workSpace:run.

Parameters
event string The event type.
p1 any First parameter for the event or nil if not used.
p2 any Second parameter for the event or nil if not used.
p3 any Third parameter for the event or nil if not used.
p4 any Fourth parameter for the event or nil if not used.
p5 any Fifth parameter for the event or nil if not used.
... any Any additional parameters.

Returns
none


Remarks


top


private.workSpace:get_desktop

desktop workSpace:get_desktop (dir)

Returns the desktop window object for the given directory (under /win/devices). If none or dir is invalid, nil is returned.

Parameters
dir
string Desktop directory under /win/devices.

Returns
desktop desktopWindow The desktop for the given directory, or nil if none.

Remarks
See workSpace:desktops, window:get_desktop.


top


private.workSpace:get_focus_wnd

wnd workSpace:get_focus_wnd (dir)

Returns the window that currently has input focus on the desktop for the given directory. If none or dir is invalid, nil is returned.

Parameters
dir string Desktop directory under /win/devices.

Returns
wnd window The window that currently has input focus on the sort desktop, or nil if none.




Remarks
Use window:get_focus instead.


top


private.workSpace:kill_alarm

workSpace:kill_alarm (wnd, alarm_id)

Removes an alarm set with workSpace:set_alarm.

Parameters
wnd
window
Window associated with the alarm.
alarm_id number
The id of the alarm returned by workSpace:set_alarm to remove.

Returns
none



Remarks
See window:set_alarm.


top


private.workSpace:kill_idle_timer

workSpace:kill_idle_timer ()

Stops the idle timer if set.

Parameters
none



Returns
none


Remarks


top


private.workSpace:kill_timer

workSpace:kill_timer (wnd, timer_id)

Removes a timer set with workSpace:start_timer.

Parameters
wnd window
Window associated with the timer.
timer_id number
The id of the alarm returned by workSpace:start_timer to remove.

Returns
none



Remarks
See window:start_timer.


top


private.workSpace:kill_timers

workSpace:kill_timers (wnd)

Removes all timers and alarms for the given window.

Parameters
wnd window The window to kill the timers and alarms for.

Returns
none


Remarks


top


private.workSpace:pump_event

result workSpace:pump_event (wnd, ... )

Passes the event to the appropriate application thread for processing.

Parameters
wnd window Window the event is for.
... any Event parameters.

Returns
result boolean The value returned by the handler for the event.

Remarks


top


private.workSpace:run

workSpace:run ()

The system's main loop.

Parameters
none


Returns
none


Remarks
This function never returns.

See win.start.


top


private.workSpace:run_app

workSpace:run_app (dir, path, ...)

Starts the program given by path passing it the arguments in the desktop indicated by side.

Parameters
dir
string Desktop directory under /win/devices.
path string Full path to program file to run.
... string Any command line arguments. Each argument must be a separate string parameter.

Returns
none


Remarks
Use the desktopWindow:run_app method instead.


top


private.workSpace:set_alarm

id workSpace:set_alarm (wnd, time)

Sets an alarm with the given time value and associates it with the wnd object for event routing, returning the alarm id.

Parameters
wnd window The window associated with the alarm.
time number The time the alarm will fire.

Returns
id number The identifier for the alarm.

Remarks
Use the window:set_alarm method instead.


top


private.workSpace:shiftkey

depressed workSpace:shiftkey ()

Returns true if the state of the shift key is active, false if not.

Parameters
none


Returns
depressed boolean True if depressed, false if not.

Remarks
See workSpace:altkey, workSpace:ctrlkey.


top


private.workSpace:start_idle_timer

workSpace:start_idle_timer ()

Restarts the idle event timer if the time from the last invocation has elapsed.

Parameters
none


Returns
none


Remarks


top


private.workSpace:start_timer

id workSpace:start_timer (wnd, timeout)

Starts a timer with the given timeout value and associates it with the wnd object for event routing, returning the timer id.

Parameters
wnd window The window associated with the timer.
timeout number The timer elapse time in seconds.

Returns
id number The timer id.

Remarks
Use the window:start_timer method instead.


top


private.workSpace:startup

workSpace:startup ()

Implements any settings from the system's /win.ini file, if required, and creates any desktops.

Parameters
none


Returns
none


Remarks


top


private.workSpace:unwant_event

result workSpace:unwant_event (wnd, event)

Unregisters the window from receiving the event, returning true if it was registered, false otherwise. If event is nil all events for the window are unregistered and true is returned.

Parameters
wnd window The window to unregister the event/s for.
event string/nil The event to unregister, nil for all events.

Returns
result boolean True if successful, false if not.

Remarks
Use window:unwant_event instead.


top


private.workSpace:want_event

result workSpace:want_event (wnd, event)

Registers the window to receive the event.

Parameters
wnd window The window to receive the event.
event string The event wanted by the window. The wildcard "*" will send all non-standard routed events to the window.

Returns
result boolean True if successfully registered, false otherwise.

Remarks
Use window:want_event instead.


top


See also API Reference, WIN.