private.desktopWindow - WIN

Class desktopWindow
Inherits from window.

The desktopWindow class provides a window class object to serve as the top, administrative window in the hierarchy on a single display device.

Properties

dt__app_list appListFrame The running applications list window.
dt__capture_mouse_wnd window/nil The window that currently has mouse capture, if any.
dt__clipboard_data any Holds the clipboard data.
dt__clipboard_type number Holds the clipboard's data type.
dt__drag_wnd window/nil The window that last received a click event.
dt__home_page homePageFrame The home page window.
dt__keyboard keyboardFrame The keyboard overlay window when it's active.
dt__keyboard_fullscreen
boolean
Stores full screen mode while keyboard is active.
dt__lock_screen lockScrnFrame
The lock screen window.
dt__lockable boolean
Whether this desktop can be locked.
dt__sys_msgbox sysMsgBoxFrame
The system message box window.
dt__taskbar taskBarFrame The task bar window.
dt__theme desktopTheme The desktop theme object.

Methods

See also API Reference, WIN.

private.desktopWindow:can_lock

result desktopWindow:can_lock ()

Returns whether the lock screen can be activated on the desktop.

Parameters
none


Returns
result boolean True if can lock, false if not.

Remarks
See desktopWindow:is_locked, desktopWindow:lock_screen.


top


private.desktopWindow:capture_mouse

desktopWindow:capture_mouse (wnd)

Sets or releases mouse capture.

Parameters
wnd window/nil The window to receive mouse capture. If nil mouse capture is released.

Returns
none


Remarks
Use window:capture_mouse and window:release_mouse to set and release mouse capture.


top


private.desktopWindow:captured_mouse

wnd desktopWindow:captured_mouse ()

Returns the window object that currently has mouse capture, or nil if none.

Parameters
none


Returns
wnd window The window that currently has mouse capture, or nil if none.

Remarks
See window:captured_mouse.


top


private.desktopWindow:constructor

desktop desktopWindow:constructor (type, dir, width, channels)

Constructs and returns the instantiated 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 The instantiated desktop window.

Remarks


top


private.desktopWindow:create_bars

desktopWindow:create_bars ()

Creates the task bar and system page frames, running them in modal state, then initializes and displays the home page.

Parameters
none


Returns
none


Remarks


top


private.desktopWindow:create_theme

theme desktopWindow:create_theme ()

Attempts to load the theme object from the desktop theme file. If unable to, a new theme is created and saved to the desktop theme file. A theme object is always returned.

Parameters
none


Returns
theme desktopTheme Desktop theme object.

Remarks
See desktopWindow:load_theme, desktopWindow:save_theme.


top


private.desktopWindow:dismiss_keyboard

desktopWindow:dismiss_keyboard ()

Dismisses the keyboard overlay if it is active.

Parameters
none


Returns
none


Remarks
See desktopWindow:do_keyboard.


top


private.desktopWindow:do_idle

desktopWindow:do_idle (count)

Sends the idle event to each of its children (frame level windows).

Parameters
count number Number of successive times (1 based) the idle event was propagated since any other event type was processed.

Returns
none


Remarks
See window:on_idle.


top


private.desktopWindow:do_keyboard

desktopWindow:do_keyboard (target_wnd)

Displays the keyboard overlay. The target_wnd is adopted by the keyboard overlay while it is active.

Parameters
target_wnd window The window to receive key input from the overlay.

Returns
none


Remarks
See desktopWindow:dismiss_keyboard.


top


private.desktopWindow:drop_app

desktopWindow:drop_app (frame)

Drops the application's main frame, destroying it and all its popups and children.

Parameters
frame applicationFrame The application main frame to drop.

Returns
none


Remarks
This method should not be called while the application is in modal state.

Use applicationFrame:quit_app to quit an application.


top


private.desktopWindow:enum_apps

iterator, frame desktopWindow:enum_apps (iterator)

Returns the next application frame from the desktop's children.

Parameters
iterator number Iterator passed back at the last call.

Returns
iterator number Iterator to pass back at the next call.
frame applicationFrame Next application frame or nil when no more.

Remarks
The iterator should be nil for the first call, and passed back at each successive call. When there are no more application frames the frame object returned is nil.
local itor, frame = desktop:enum_apps ()
while frame do
   -- do something
   itor, frame = desktop:enum_apps (itor)
end

top


private.desktopWindow:get_active_app_frame

frame desktopWindow:get_active_app_frame ()

Returns the application main frame currently lowest in the z order (on top of all others), or nil if none. System applicationFrame windows not included.

Parameters
none


Returns
frame applicationFrame/nil The top application main frame, or nil if none loaded.

Remarks
See desktopWindow:get_active_frame.


top


private.desktopWindow:get_active_frame

frame desktopWindow:get_active_frame ()

Returns the frame window lowest in the z order after the task bar (on top of all others), or nil if none. The returned frame may be either a popupFrame window or an applicationFrame window, including the system's home and list pages.

Parameters
none


Returns
frame parentFrame The top frame window.

Remarks
nil should only be returned during start up as the system's page windows should exist after that.

See desktopWindow:get_active_app_frame.


top


private.desktopWindow:get_clipboard

type, data desktopWindow:get_clipboard ()

Returns the current type and data from the desktop's clipboard.

Parameters
none


Returns
type number Clipboard data type.
data any Clipboard data.

Remarks
If the clipboard is empty the type is win.CB_EMPTY, and data is nil.

See window:get_clipboard, desktopWindow:set_clipboard.


top


private.desktopWindow:get_focus_wnd

wnd desktopWindow:get_focus_wnd ()

Returns the window that currently has input focus on the desktop (the focus window of the active frame), or nil if none.

Parameters
none


Returns
wnd window/nil The window that has input focus, or nil if none.

Remarks
See window:get_focus.


top


private.desktopWindow:get_fullscreen

fullscreen desktopWindow:get_fullscreen ()

Returns whether the desktop is in full screen mode.

Parameters
none


Returns
fullscreen boolean True if desktop is in full screen mode, false if not.

Remarks
See desktopWindow:set_fullscreen.


top


private.desktopWindow:get_lockable

lockable desktopWindow:get_lockable ()

Returns whether the desktop setting allows locking.

Parameters
none



Returns
lockable boolean
True if lockable, false if not.

Remarks
This method does not check if there is a password.

See desktopWindow:set_lockable.


top


private.desktopWindow:get_next_app_frame

appframe desktopWindow:get_next_app_frame (frame)

Returns the next applicationFrame window after the frame given in the desktop's children z order, or nil if none or the frame is not a child. The search excludes system page frame windows.

Parameters
frame parentFrame The frame to search from.

Returns
appframe applicationFrame The next application frame window in the z order.

Remarks
See desktopWindow:get_active_app_frame.


top


private.desktopWindow:get_password

password desktopWindow:get_password ()

Returns the system's password. An empty string is returned if a password is not set.

Parameters
none


Returns
password string The system's password.

Remarks
See desktopWindow:lock_screen.


top


private.desktopWindow:get_taskbar_index

index desktopWindow:get_taskbar_index ()

Returns the 1 based index position of the task bar window in the desktop's children's z order, or zero if not found.

Parameters
none


Returns
index number Task bar window index.

Remarks


top


private.desktopWindow:get_theme

theme desktopWindow:get_theme ()

Returns the desktop's theme object.

Parameters
none


Returns
theme desktopTheme Desktop's theme object.

Remarks
See window:get_theme, window:get_colors.


top


private.desktopWindow:get_work_area

rt desktopWindow:get_work_area ()

Returns the desktop area not obscured by the task bar.

Parameters
none


Returns
rt rect A rectangle of the desktop work area, in screen coordinates.

Remarks


top


private.desktopWindow:hide_lock_screen

desktopWindow:hide_lock_screen ()

Hides the lock screen if currently displayed.

Parameters
none



Returns
none


Remarks
See desktopWindow:is_locked, desktopWindow:lock_screen.


top


private.desktopWindow:hide_msgbox

desktopWindow:hide_msgbox ()

Hides the system message box if currently displayed.

Parameters
none


Returns
none


Remarks
See desktopWindow:msgbox.


top


private.desktopWindow:is_locked

result desktopWindow:is_locked ()

Returns whether the lock screen is active on the desktop.

Parameters
none


Returns
result boolean True if locked, false if not.

Remarks
See desktopWindow:can_lock, desktopWindow:lock_screen.


top


private.desktopWindow:is_touch

x, y desktopWindow:is_touch (channel, msg)

Determines if a digilines message is a touch message from a monitor attached to this desktopWindow.

Parameters
channel string Digilines channel of the devices sending the message.
msg any The digilines message.

Returns
x number/nil The monitor's x character coordinate touched or nil if not from this desktop monitor device.
y number/nil The monitor's y character coordinate touched or nil if not from this desktop monitor device.

Remarks


top


private.desktopWindow:load_app_list

desktopWindow:load_app_list ()

Reloads the list of running applications on the system's running applications list page.

Parameters
none


Returns
none


Remarks


top


private.desktopWindow:load_theme

theme desktopWindow:load_theme ()

Loads and returns the theme object loaded from the desktop theme file, at "/win/<side>/theme.ini".

Parameters
none


Returns
theme desktopTheme The loaded theme, or nil on error.

Remarks
See desktopWindow:create_theme, desktopWindow:save_theme.


top


private.desktopWindow:lock_screen

desktopWindow:lock_screen ()

Invokes a lockScrnFrame if not already active, blocking user interaction until the password is entered.

Parameters
none


Returns
none


Remarks
If no system's password is set, or nolock is true for this desktop this call is ignored.

See desktopWindow:can_lock, desktopWindow:is_locked.


top


private.desktopWindow:msgbox

desktopWindow:msgbox (title, message, bgcolor)

Displays the message in a system msgBoxFrame.

Parameters
title string Title bar text.
message string Message to display.
bgcolor number Background color of the message box, if nil the theme's popup_back color is used.

Returns
none


Remarks
The desktop interface is disabled until the message box is dismissed.


top


private.desktopWindow:on_resize

result desktopWindow:on_resize ()

Resizes the desktop then sends a monitor_resize event to each of its children (frame level windows).

Parameters
none


Returns
result boolean Always true.

Remarks
See window:on_resize.


top


private.desktopWindow:run_app

desktopWindow:run_app (path, ...)

Starts the program given by path passing it the arguments, then reloads the running applications list.

Parameters
path string Full path to program file to run.
... string Any command line arguments. They may be one or a series of string parameters.

Returns
none


Remarks
Individual arguments containing spaces may be delimited with double quotes. Any arguments are parsed before passing them as individual arguments to the called program.

See workSpace:run_app.


top


private.desktopWindow:save_theme

result desktopWindow:save_theme (theme)

Saves the given theme object to the theme file for the desktop, at /win/devices/<desktop>/theme.ini.

Parameters
theme desktopTheme The theme object to save.

Returns
result boolean True if successful, false if not.

Remarks
See desktopWindow:create_theme, desktopWindow:load_theme.


top


private.desktopWindow:set_active_frame

result desktopWindow:set_active_frame (frame)

Brings the frame to the top (after the task bar in the z order). The frame must be a child of the desktop.

Parameters
frame parentFrame The frame to make active.

Returns
result boolean True if the frame is active, false if not.

Remarks
If the active frame is changed the on_frame_activate handler is called for the deactivated and activated frames, and the on_blur and on_focus handlers for windows as appropriate.


top


private.desktopWindow:set_clipboard

desktopWindow:set_clipboard (data, cbType)

Sets the desktop's clipboard with the data and type.

Parameters
data any Data to place on clipboard.
type number Type of data.

Returns
none


Remarks
If data is nil then the type is set to win.CB_EMPTY. If data is given and type is nil (or omitted) then the type is set to win.CB_TEXT. Custom clipboard data types may be implemented by using unique type indicators.

See window:set_clipboard, desktopWindow:get_clipboard.


top


private.desktopWindow:set_fullscreen

desktopWindow:set_fullscreen (fullscreen)

Sets the desktop in or out of full screen mode.

Parameters
fullscreen boolean/nil True sets full screen. False resets normal screen. nil toggles the current mode.

Returns
none


Remarks
See desktopWindow:get_fullscreen.


top


private.desktopWindow:set_lockable

desktopWindow:set_lockable (lockable)

Sets whether this desktop can be locked.

Parameters
lockable boolean
True to set lockable, false for not.

Returns
none



Remarks
See desktopWindow:get_lockable.


top


private.desktopWindow:set_text_scale

desktopWindow:set_text_scale (scale)

Sets the text scale for the monitor device this desktop is displayed on. If the device is not a monitor the call is ignored.

Parameters
scale number The text scale to set (1 - 5).

Returns
none


Remarks


top


private.desktopWindow:show_home_page

desktopWindow:show_home_page ()

Sets the system's home page as the active top frame.

Parameters
none


Returns
none


Remarks
See desktopWindow:show_list_page.


top


private.desktopWindow:show_list_page

desktopWindow:show_list_page ()

Sets the system's running applications list page as the active top frame.

Parameters
none


Returns
none


Remarks
See desktopWindow:show_home_page.


top


private.desktopWindow:show_lock_screen

desktopWindow:show_lock_screen ()

Displays the lock screen if a password is set.

Parameters
none


Returns
none


Remarks


top


private.desktopWindow:update

rt desktopWindow:update (force)

Updates (redraws) the desktop.

Parameters
force boolean If true the whole desktop is redrawn, otherwise only the invalidated area (if any).

Returns
rt rect Screen relative affected area of drawing. It may be empty, if no area was drawn.

Remarks


top


See also API Reference, WIN.