win.window - WIN

Class window
Inherits from __classBase.

The window class object provides the base window function. Typically classes are derived from window for specific window types.

Properties

x
number Parent relative x position of window.
y
number Parent relative y position of window.
width
number Width of window.
height
number Height of window.
gdi GDI Window GDI object.
wnd__alive boolean Indicator used during destruction.
wnd__bg_color
number Window background colour.
wnd__color
number Window text/fore colour.
wnd__cursor_x
number Window relative cursor x position.
wnd__cursor_y
number Window relative cursor y position.
wnd__enabled boolean Window enabled property.
wnd__frame_class
number Window's frame class.
wnd__hidden boolean Window visibility property.
wnd__id number Window id number.
wnd__invalid rect Window's invalidated rectangle.
wnd__nodes table Child window list.
wnd__owner parentFrame Owner frame (for popups).
wnd__parent window Parent window.
wnd__popup parentFrame Current popup (for frames).
wnd__scroll_x number Scroll x offset (always positive).
wnd__scroll_y number Scroll y offset (always positive).
wnd__scroll_width number Scrollable width of window.
wnd__scroll_height number Scrollable height of window.
wnd__text string Window text property.
wnd__want_focus
boolean True if window can take input focus.
wnd__want_key_input
number Indicator if on screen keyboard should be invoked on touch.
wnd__do_keyboard
boolean Flag to indicate if on screen keyboard should be invoked.

Properties x, y, width and height may be read but should be altered through move. Property gdi may be queried, for drawing gain it through get_GDI.

Methods

See also API Reference, WIN.

Creation

win.window:constructor

wnd window:constructor (parent, id, x, y, width, height)

Constructs and returns the instantiated window.

Parameters
parent window Parent window in window hierarchy.
id number Numeric id value for the window.
x number Parent relative x position.
y number Parent relative y position.
width number Width of the window.
height number Height of the window.

Returns
wnd window The instantiated window object.

Remarks
The parent may be nil but typically should not be. Objects higher in the system hierarchy cannot be retrieved if no parent has ever been set.

The returned object provides the base function of a window object, but draws nothing and fires no control events.

The coordinate parameters are floored to integer values.


top


win.window:destroy_wnd

window:destroy_wnd ()

Destroys this window and all of its children.

Parameters
none


Returns
none


Remarks
The window:on_destroy_wnd handler is called in this process.

After this call the window object should not be used, and any reference to it should be released (made nil or fall out of scope).


top


Positioning

win.window:get_client_size

width, height window:get_client_size ()

Returns the client size of the window. This is the window size less any currently visible scroll bars.

Parameters
none


Returns
width number Width of window client area (excluding any scroll bars).
height number Height of window client area (excluding any scroll bars).

Remarks


top


win.window:get_wnd_rect

rt window:get_wnd_rect ()

Returns the window's parent relative coordinates as a rectangle object.

Parameters
none


Returns
rt rect Window's parent relative coordinates.

Remarks
See window:get_screen_rect.


top


win.window:hit_test

hit window:hit_test (x, y)

Returns a value indicating the window item at the point given.

Parameters
x number Window relative x position.
y number Window relative y position.

Returns
hit number Hit item indicator.

Remarks
The return value will be one of the following
win.HT_NOWHERE     = 0
win.HT_CLIENT      = 1
win.HT_LINEUP      = 2
win.HT_LINEDOWN    = 3
win.HT_PAGEUP      = 4
win.HT_PAGEDOWN    = 5
win.HT_LINELEFT    = 6
win.HT_LINERIGHT   = 7
win.HT_PAGELEFT    = 8
win.HT_PAGERIGHT   = 9
The coordinate parameters are floored to integer values.


top


win.window:move

window:move (x, y, width, height, z)

Moves and/or re-dimensions the window.

Parameters
x number/nil Parent relative x position.
y number/nil Parent relative y position.
width number/nil Window width.
height number/nil Window height.
z number/nil Sibling window relative position.

Returns
none


Remarks
If any parameter is omitted or nil that coordinate is unaffected.

The z parameter moves the window in the parent's children z order by the given amount. -1 will bring it up one, 1 down one. If z is win.WND_TOP the window is brought to the top of the parent's child windows, if win.WND_BOTTOM to the bottom (drawn behind all others and last in the tab order).
win.WND_TOP    = 0
win.WND_BOTTOM = 100000
Invalidation is done and the on_move handler is called.

The x, y, width and height parameters are floored to integer values.


top


win.window:screen_to_wnd

x, y window:screen_to_wnd (x, y)

Converts screen relative coordinates to window relative coordinates.

Parameters
x number Screen relative x coordinate.
y number Screen relative y coordinate.

Returns
x number Window relative x coordinate.
y number Window relative y coordinate.

Remarks
Coordinates are zero based from top, left.

See window:wnd_to_screen.


top


win.window:scroll_to_wnd

x, y window:scroll_to_wnd (x, y)

Converts scroll relative coordinates (window coordinates adjusted for any scrolling) to window relative coordinates.

Parameters
x number Scroll relative x coordinate.
y number Scroll relative y coordinate.

Returns
x number Window relative x coordinate.
y number Window relative y coordinate.

Remarks
Coordinates are zero based from top, left.

See window:wnd_to_scroll.


top


win.window:wnd_at_point

wnd window:wnd_at_point (x, y, disabled, hidden)

Returns the window at the given point, or nil if none found.

Parameters
x number Window relative horizontal position.
y number Window relative vertical position.
disabled boolean Include disabled windows if true, not if false.
hidden boolean Include invisible windows if true, not if false.

Returns
wnd window The sort window object, or nil if none found.

Remarks
A window can only check itself and any children, not sibling or parent windows.

The coordinate parameters are floored to integer values.

See window:wnd_from_point.


top


win.window:wnd_from_point

wnd window:wnd_from_point (x, y)

Returns the window at the given point, or nil if none found.

Parameters
x number Window relative horizontal position.
y number Window relative vertical position.

Returns
wnd window The sort window object, or nil if none found.

Remarks
Child windows are included in the search, but invisible windows are not. If the window at the point is disabled or none found, nil is returned.

A window can only check itself and any children, not sibling or parent windows.

The coordinate parameters are floored to integer values.

See window:wnd_at_point.


top


win.window:wnd_to_screen

x, y window:wnd_to_screen (x, y)

Converts window relative coordinates to screen relative coordinates.

Parameters
x number Window relative x coordinate.
y number Window relative y coordinate.

Returns
x number Screen relative x coordinate.
y number Screen relative y coordinate.

Remarks
Coordinates are zero based from top, left.

See window:screen_to_wnd.


top


win.window:wnd_to_scroll

x, y window:wnd_to_scroll (x, y)

Converts window relative coordinates to scroll relative coordinates (window coordinates adjusted for any scrolling).

Parameters
x number Window relative x coordinate.
y number Window relative y coordinate.

Returns
x number Scroll relative x coordinate.
y number Scroll relative y coordinate.

Remarks
Coordinates are zero based from top, left.

See window:scroll_to_wnd.


top


Drawing

win.window:draw

window:draw (gdi, bounds)

Draws the content area of the window.

Parameters
gdi GDI GDI object to use for drawing.
bounds rect Invalidated area of the window.

Returns
none


Remarks
This base implementation does nothing. An object derived from window should override this method to draw its contents using the gdi given. Do not call window:release_GDI from this method.

This method is called during the update process to draw its contents.

See window:update.


top


win.window:get_GDI

gdi window:get_GDI ()

Returns the window's GDI object after preparing it for adhoc drawing.

Parameters
none


Returns
gdi GDI The returned gdi object.

Remarks
window:release_GDI must be called once when finished with the GDI object. This is not a stacked process, window:get_GDI and window:release_GDI must be called one for one.


top


win.window:invalidate

window:invalidate (x, y, width, height)

Invalidates (flags as needs drawing) the given rectangle of the window.

Parameters
x number/nil Window relative x coordinate.
y number/nil Window relative y coordinate.
width number/nil Width to invalidate.
height number/nil Height to invalidate.

Returns
none





Remarks
Any parameter omitted (or nil) is assumed at its extreme. To invalidate the whole window:
wnd:invalidate ()
The coordinate parameters are floored to integer values.


See window:validate.

top


win.window:print

window:print (gdi, children, hidden)

Draws the window into the given gdi object.

Parameters
gdi GDI The GDI object to use for drawing.
children boolean If true child windows are also draw.
hidden boolean If the window is invisible and this parameter is true, the window is still drawn. Otherwise an invisible window is not drawn.

Returns
none


Remarks
The caller is responsible for managing the gdi object.

This method calls window:draw.


top


win.window:release_GDI

window:release_GDI ()

Releases the window's GDI object after it has been gained through window:getGDI.

Parameters
none


Returns
none


Remarks
This is not a stacked process, window:get_GDI and window:release_GDI must be called one for one.


top


win.window:update

rt window:update (force)

Updates (redraws) the window.

Parameters
force boolean If true the whole window 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
See window:draw.


top


win.window:validate

window:validate ()

Flags the whole window as valid (no drawing needed).

Parameters
none


Returns
none


Remarks
See window:invalidate.


top


State

win.window:enable

window:enable (enable)

Sets the enabled state of the window.

Parameters
enable boolean True to enable, false to disable.

Returns
none


Remarks
The window is invalidated.

See window:is_enabled.


top


win.window:get_bg_color

color window:get_bg_color ()

Returns the background color for the window.

Parameters
none


Returns
color number The window's background color.

Remarks
See also window:set_bg_color.


top


win.window:get_color

color window:get_color ()

Returns the fore (text) color for the window.

Parameters
none


Returns
color number Window's fore color.

Remarks
See also window:set_color.


top


win.window:get_id

id window:get_id ()

Returns the id of the window.

Parameters
none


Returns
id number Window's numeric id.

Remarks
See also window:set_id.


top


win.window:get_dir

dir window:get_dir ()

Returns the desktop directory under /win/devices this window object belongs to.

Parameters
none


Returns
dir
string The desktop directory.

Remarks
This value is retrieved from the window's GDI object. If no parent has ever been set the return value is "".


top


win.window:get_text

text window:get_text ()

Returns the string value associated with the window.

Parameters
none


Returns
text string Window's text value.

Remarks
See window:set_text.


top


win.window:get_want_focus

want window:get_want_focus ()

Returns true if the window can be set as the active input window, false if not.

Parameters
none


Returns
want boolean True if the window can have input focus, false if not.

Remarks
See window:set_want_focus.


top


win.window:get_want_key_input

want window:get_want_key_input ()

Returns the window's on screen keyboard desired action.

Parameters
none


Returns
want number Value indicating desired action.

Remarks
One of the following is returned:
win.KEYINPUT_NONE = 0 -- No on screen keyboard.
win.KEYINPUT_LINE = 1 -- Dismiss keyboard on cancel or enter keys.
win.KEYINPUT_EDIT = 2 -- Dismiss keyboard on cancel key only.

See window:set_want_key_input.


top


win.window:is_enabled

enabled window:is_enabled ()

Returns the enabled state of the window.

Parameters
none


Returns
enabled boolean True if enabled, false if disabled.

Remarks
If the window or any parent is disabled then false is returned. If it and all its parents are enabled then true.

See window:enable.


top


win.window:is_shown

shown window:is_shown ()

Returns the visibility state of the window.

Parameters
none       

Returns
shown    boolean    True if visible, false if not.

Remarks
description

Parameters
none


Returns
shown boolean True if visible, false if not.

Remarks
If the window or any parent is not set to visible then false is returned. If it and all its parents are set visible then true. Does not test if the window is currently visible on the device.

See window:show.


top


win.window:set_bg_color

window:set_bg_color (color)

Sets the background colour for the window.

Parameters
color number Color to set.

Returns
none


Remarks
Must be a correct color value or zero. If zero the window's background is not erased during the drawing process.

The window is invalidated.

See window:get_bg_color.


top


win.window:set_color

window:set_color (color)

Sets the fore (text) color for the window.

Parameters
color number Color to set.

Returns
none


Remarks
Must be a correct color value.

The window is invalidated.

See window:get_color.


top


win.window:set_id

window:set_id (id)

Set the number id for the window.

Parameters
id number Numeric id value for window.

Returns
none


Remarks
See window:get_id.


top


win.window:set_text

window:set_text (text)

Sets the string value associated with the window.

Parameters
text string Text value to set.

Returns
none


Remarks
The window is invalidated.

See window:get_text.


top


win.window:set_want_focus

window:set_want_focus (want)

Sets whether the window can be set as the active input window.

Parameters
want boolean True if the window can have input focus, false if not.

Returns
none


Remarks
See window:get_want_focus.


top


win.window:set_want_key_input

window:set_want_key_input (want)

Sets the window's on screen keyboard desired action.

Parameters
want number Value indicating desired action.

Returns
none


Remarks
Want value may be one of the following:
win.KEYINPUT_NONE = 0 -- No on screen keyboard.
win.KEYINPUT_LINE = 1 -- Dismiss keyboard on cancel or enter keys.
win.KEYINPUT_EDIT = 2 -- Dismiss keyboard on cancel key only.
See window:get_want_key_input.


top


win.window:show

window:show (show)

Sets the visibility state of the window.

Parameters
show boolean True to show, false to hide.

Returns
none


Remarks
The window is invalidated.

See window:is_shown.


top


Communications

win.window:comm_close

result window: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_open, workSpace:comm_close.


top


win.window:comm_enabled

result window:comm_enabled ()

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

Parameters
none


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

Remarks
See workSpace:comm_enabled.


top


win.window:comm_find

com window:comm_find (name)

Finds and returns a matching comm connection.

Parameters
name string/nil The name of the connection.

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

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

See also  workSpace:comm_find.


top


win.window:comm_open

com window:comm_open (name, timeout)

Opens a new comm connection and returns the comm object.

Parameters
name string The name of the connection. If nil a unique name is generated.
timeout number 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_close, workSpace:comm_open.


top


win.window:send_message

message_id window:send_message (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 on the connection's port/channel.
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 table/string/number The data for the message, if any.
name string/nil The name of the connection to use to send the message.

Returns
message_id number Unique identifier for the message, or nil if the send was not successful (no appropriate connection). 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:on_receive, window:on_sent, workSpace:comm_send.


top


win.window:unwant_messages

result window:unwant_messages (application, name)

Unregisters an interest in the comm connection registered with window:want_messages.

Parameters
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.

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 window:unwant_messages should match those passed to window:want_messages to register the interest. If no parameters are given all interests for this window on all connections are unregistered, in which case the return value is always true.

See workSpace:comm_unregister.


top


win.window:want_messages

result window:want_messages (application, name)

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

Parameters
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.

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 window:unwant_messages.

See  window:on_receive, window:on_sent, workSpace:comm_register.


top


Heirarchy

win.window:add_child

window:add_child (child)

Adds the given window to the children of this window.

Parameters
child window The child window to add.

Returns
none


Remarks
The child is added to the end of the children list but no parentage is adopted.

The child must be derived from a window object, and this window maintains a reference to it. When this window is destroyed so are its child windows.

This is a primary method, typically use window:set_parent for this operation.


top


win.window:child_index

index window:child_index (child)

Returns the 1 based index of the child window in this window's list of children, or zero if it is not a child.

Parameters
child number The child window to find.

Returns
index number Child window's index, or zero if not found.

Remarks


top


win.window:children

count window:children ()

Returns the count of child windows this window contains.

Parameters
none


Returns
count number Count of child windows.

Remarks


top


win.window:get_app_frame

frame window:get_app_frame ()

Returns the applicationFrame object this window belongs to.

Parameters
none


Returns
frame applicationFrame The application frame object.

Remarks
The return will be nil if no parent is set.

Application frames (applicationFrame objects) return themselves.


top


win.window:get_child

child window:get_child (index)

Returns the child window at the given index in this window's list of children, or nil if the index is out of range (1 based).

Parameters
index number Index of child to retrieve (1 based).

Returns
child window/nil The child window, or nil if index is out of range.

Remarks


top


win.window:get_colors

colors window:get_colors ()

Returns the desktopTheme object's color table for the desktop this window is under.

Parameters
none


Returns
colors table Desktop theme's color table.

Remarks
If no parent has ever been set for the window, the color table from the default theme object __defaultTheme is returned.

See window:get_theme.


top


win.window:get_desktop

desktop window:get_desktop ()

Returns the desktop window this window is under.

Parameters
none


Returns
desktop desktopWindow The desktop window object.

Remarks
If the parent has never been set nil is returned.


top


win.window:get_parent

parent window:get_parent ()

Returns the parent window of this window.

Parameters
none


Returns
parent window Parent window.

Remarks
The return value will be nil if the parent is not set.

See also window:set_parent.


top


win.window:get_parent_frame

frame window:get_parent_frame ()

Returns the parent frame (applicationFrame or popupFrame) this window belongs to

Parameters
none


Returns
frame window The parent frame window object, or nil if none.

Remarks
The parent frame window does not have to be the immediate parent of the window.


top


win.window:get_theme

theme window:get_theme ()

Returns the theme object for the desktop this window is under.

Parameters
none


Returns
theme desktopTheme Desktop theme object.

Remarks
If no parent has ever been set for the window, the default theme object private.defaultTheme is returned.

See window:get_colors.


top


win.window:get_wnd_by_id

wnd window:get_wnd_by_id (id, recursive)

Returns the child window matching the given id value.

Parameters
id number The window id to search for.
recursive boolean If not false, the search recursively checks child windows after all immediate children have been checked. If nil, defaults to true.

Returns
wnd window The sort window object, or nil if not found.

Remarks


top


win.window:get_workspace

workspace window:get_workspace ()

Returns the workSpace object (the top system object).

Parameters
none


Returns
workspace workSpace The top system object.

Remarks
This object is rarely needed as it's useful features are more accessible through the window object directly.


top


win.window:remove_child

removed window:remove_child (child)

Removes the child window from this window's list of children. Returns true if the child was found and removed, false if not.

Parameters
child window The child window to remove.

Returns
removed boolean true if the child was removed, false if not.

Remarks
The child window is not destroyed nor is parentage affected.

This is a primary method, typically use window:set_parent to remove a child or change parent window.


top


win.window:set_parent

window:set_parent (parent)

Set the parent window for this window.

Parameters
parent window Window to set as parent of this window.

Returns
none


Remarks
Invalidation is handled.

See window:get_parent.


top


Scrolling

win.window:get_scroll_org

x, y window:get_scroll_org ()

Returns the scroll (view) left, top position of the window.

Parameters
none


Returns
x number Left scroll origin position.
y number Top scroll origin position.

Remarks
These values are always zero or greater.

See also window:set_scroll_org.


top


win.window:get_scroll_size

width, height window:get_scroll_size ()

Returns the current scroll size for the window.

Parameters
none


Returns
width number Window scroll width.
height number Window scroll Height.

Remarks
See window:set_scroll_size.


top


win.window:has_scroll_bars

vertical, horizontal window:has_scroll_bars ()

Returns whether the respective scroll bar is currently visible.

Parameters
none


Returns
vertical boolean True if the vertical scroll bar is currently visible, false if not.
horizontal boolean True if the horizontal scroll bar is currently visible, false if not.

Remarks


top


win.window:scroll_cols

window:scroll_cols (cols)

Scrolls the window the given number of columns (characters). If cols is negative, scrolls left. If positive then right.

Parameters
cols number Columns (characters) to scroll.

Returns
none


Remarks
Scrolling is trimmed to within range if required.

See window:scroll_lines.


top


win.window:scroll_lines

window:scroll_lines (lines)

Scrolls the window the given number of lines. If lines is negative, scrolls up. If positive then down.

Parameters
lines number Lines to scroll.

Returns
none


Remarks
Scrolling is trimmed to within range if required.

See window:scroll_cols.


top


win.window:set_scroll_org

window:set_scroll_org (x, y)

Sets the scroll (view) left, top position of the window.

Parameters
x number Left scroll origin position.
y number Top scroll origin position.

Returns
none


Remarks
The values are trimmed between zero and the greatest value for the current scroll sizes.

Invalidation is handled.

See window:get_scroll_org.


top


win.window:set_scroll_size

window:set_scroll_size (width, height)

Sets the current scroll size for the window.

Parameters
width number Window scroll width.
height number Window scroll height.

Returns
none


Remarks
Any currently set scroll origin is adjusted to within range if required.

Invalidation is handled.

See window:get_scroll_size.


top


Cursor

win.window:get_cursor_pos

x, y window:get_cursor_pos ()

Returns the current cursor scroll relative position for the window.

Parameters
none


Returns
x number Cursor scroll relative x position.
y number Cursor scroll relative y position.

Remarks
Each window records it's own cursor position. This is not the device's cursor position as returned by the GDI object.

See also window:set_cursor_pos.


top


win.window:hide_cursor

window:hide_cursor ()

Hides the cursor directly through the gdi object.

Parameters
none


Returns
none


Remarks
Typically this method should only be called by a window when it currently has input focus.


top


win.window:set_cursor_blink

window:set_cursor_blink (blink)

Sets the cursor blink state directly through the gdi device.

Parameters
blink boolean True to display cursor, false to hide.

Returns
none


Remarks
Typically this method should only be called by a window when it currently has input focus.


top


win.window:set_cursor_pos

window:set_cursor_pos (x, y)

Sets the cursor's scroll relative position for the window.

Parameters
x number Cursor scroll relative x position.
y number Cursor scroll relative y position.

Returns
none


Remarks
If the cursor's position is within the window's client area the cursor state is set to blinking. If outside the client area the cursor is hidden.

Typically this method should only be called by a window when it currently has input focus.

See window:get_cursor_pos.


top


win.window:show_cursor

window:show_cursor ()

Show the cursor at its current scroll relative position.

Parameters
none


Returns
none


Remarks
Typically this method should only be called by a window when it currently has input focus.


top


User Input

win.window:captured_mouse

wnd window:captured_mouse ()

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

Parameters
none


Returns
wnd window Window object that has capture, or nil if none.

Remarks
See window:capture_mouse, window:release_mouse.


top


win.window:capture_mouse

window:capture_mouse ()

Sets this window to receive all mouse (and touch) input.

Parameters
none


Returns
none


Remarks
See window:captured_mouse, window:release_mouse.


top


win.window:combo_keys

match window: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
The keys do not distinguish between left and right, either one.

See also Special Keys, workSpace:combo_keys.


top


win.window:get_focus

wnd window:get_focus ()

Returns the window object that currently has input focus or nil if none.

Parameters
none


Returns
wnd window Window with input focus, or nil if none.

Remarks
See window:set_focus.


top


win.window:release_mouse

window:release_mouse ()

Releases any set window (not just this one) from mouse capture.

Parameters
none


Returns
none


Remarks
See window:captured_mouse, window:capture_mouse.


top


win.window:set_focus

focused window:set_focus ()

Sets this window to have input focus.

Parameters
none


Returns
focused boolean True if made focused window (for the frame), false if not.

Remarks
The focused window is exclusive to each parent frame window. If this window does not belong to the current top frame, it will receive input focus when the frame is brought to the top.

See also window:get_focus.


top


win.window:set_suspend_keyboard

window:set_suspend_keyboard (suspend)

Temporarily sets whether the on screen keyboard should display for the window, for windows that would usually display it.

Parameters
suspend boolean
True to stop keyboard from displaying, false to display.

Returns
none



Remarks


top


Clipboard

win.window:get_clipboard

type, data window: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:set_clipboard.


top


win.window:set_clipboard

window:set_clipboard (data, type)

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.
win.CB_EMPTY = 0
win.CB_TEXT  = 1
See window:get_clipboard.


top


Timer

win.window:kill_alarm

window:kill_alarm (alarm_id)

Removes an alarm set with window:set_alarm.

Parameters
alarm_id number
The id of the alarm returned by window:set_alarm to remove.

Returns
none



Remarks
See window:set_alarm.

top


win.window:kill_timer

window:kill_timer (timer_id)

Removes a timer set with window:start_timer.

Parameters
timer_id number The id of the timer returned by window:start_timer to remove.

Returns
none


Remarks
See window:start_timer.


top


win.window:set_alarm

alarm_id window:set_alarm (time)

Sets an alarm (through os.start_timer) associated with this window and returns the id.

Parameters
time number Time value for alarm.

Returns
alarm_id number Alarm id.

Remarks
Override the window:on_alarm event handler to implement.

See window:kill_alarm, window:start_timer.


top


win.window:start_timer

timer_id window:start_timer (timeout)

Sets a timer (through os.start_timer) associated with this window and returns the id.

Parameters
timeout number Timeout value in seconds.

Returns
timer_id
number Timer id.

Remarks
Override the window:on_timer event handler to implement.

See window:kill_timer, window:set_alarm.


top


Event Routing

win.window:route_child_event

result window:route_child_event (wnd, event, p1, p2, p3, p4, p5, ... )

Routes a child event to the appropriate handler for the parent frame (applicationFrame or popupFrame).

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

Returns
result boolean Return value from the child event handler.

Remarks
Child event routing to the parent frame gives the frame the opportunity to pre-process an event for a child window if required (such as implement accelerator keys). The return value is the value returned from the handler. If true the event is not sent to the child window.

This method is not usually called directly.


top


win.window:route_event

result window:route_event (wnd, event, ... )

This is the primary event router, that routes the event through either window:route_child_event or window:route_wnd_event, capturing any event errors and relaying them to the run loop.

Parameters
wnd window The window object the event is for.
event string The event type.
... any Any additional parameters.

Returns
result boolean Return value from the event handler.

Remarks
The return value is the returned value from the handler or false on an error.

Do not call this method directly, use window:send_event instead.


top


win.window:route_wnd_event

result window:route_wnd_event (event, p1, p2, p3, p4, p5, ... )

Routes an event to the appropriate handler for the window.

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

Returns
result boolean Return value from the event handler.

Remarks
The return value is the value returned from the handler, and is not used.

This method is not usually called directly.


top


win.window:send_event

return window:send_event (event, ... )

Sends an event directly through this windows routing system, returning the return value from the handler, or false on event error or not handled.

Parameters
event string The event type.
... any Any additional parameters.

Returns
result boolean Return value from the event handler.

Remarks
The event is routed directly through the window's routing system in the calling process's space, not through the window's application event loop.


top


win.window:unwant_event

result window:unwant_event (event)

De-registers a single event or all events registered with window:want_event.

Parameters
event string/nil Event type, or nil for all wanted events.

Returns
result boolean True if successful or false if not (the event was not registered for the window). Always true if event is nil (or omitted).

Remarks


top


win.window:want_event

result window:want_event (event)

Registers the window to receive the given event.

Parameters
event string Event type. The wildcard "*" will send all non-standard routed events to the window.

Returns
result boolean True if registered successfully or false if not (the event is already registered for this window).

Remarks
Some events do not have an obvious target window to send them to. This method may be used so this window will receive the event. This is only the events received through the system's event queue. Arbitrary events can be sent directly to a window with window:send_event. Receiving the event is not exclusive, any window that registers for an event will get them. Filtering in the handler may be required to ensure the event is of interest to the window. The following events are not automatically routed, as well as any custom events implemented:

"mesecons"
"digilines"
"bundle_on"
"bundle_off"
"wireless"
"disk"
The wildcard "*" should not be used in conjunction with individual event registering.

The "timer" and "alarm" events can also be registered, but these events are only sent if they are not associated with a window. They are also registered if the wildcard is used

See window:unwant_event.


top


Handlers

win.window:on_alarm

result window:on_alarm (id)

This handler is called for a window in response to an alarm event.

Parameters
id number The alarm id (gained when the alarm was set).

Returns
result boolean Always false.

Remarks
This base implementation does nothing and returns false.


top


win.window:on_blur

result window:on_blur (focused)

Handler called when the window loses input focus.

Parameters
focused window The window gaining focus, it may be nil.

Returns
result boolean Always false.

Remarks
This base implementation hides the cursor and returns false.

See blur, window:on_focus.


top


win.window:on_char

result window:on_char (char, ascii)

This handler is called for the window that currently has input focus when a char event occurs.

Parameters
char string Single character string; the character input by user.
ascii number
The character code of the input character.

Returns
result boolean Always false.

Remarks
This base implementation does nothing and returns false.


top


win.window:on_child_blur

result window:on_child_blur (wnd, focused)

This handler is called for a frame (applicationFrame or popupFrame) window when one of its child windows is about to lose input focus.

Parameters
child window Child window the event is for.
focused window The window gaining focus, it may be nil.

Returns
result boolean Always false.

Remarks
This base implementation does nothing and returns false.

If the overridden handler returns true the event is not routed to the child window.


top


win.window:on_child_char

result window:on_child_char (wnd, char, ascii)

This handler is called for a frame (applicationFrame or popupFrame) window when one of its child windows is about to receive a char event.

Parameters
child window Child window the event is for.
char string Single character string; the character input by user.
ascii number The character code of the input character.

Returns
result boolean Always false.

Remarks
This base implementation does nothing and returns false.

If the overridden handler returns true the event is not routed to the child window.


top


win.window:on_child_clipboard

window:on_child_clipboard (wnd, text)

This handler is called for a frame (applicationFrame or popupFrame) window when one of its child windows is about to receive a clipboard event.

Parameters
child window Child window the event is for.
text string The text data to paste.

Returns
result boolean Always false.

Remarks
This base implementation does nothing and returns false.

If the overridden handler returns true the event is not routed to the child window.


top


win.window:on_child_event

result window:on_child_event (wnd, event, p1, p2, p3, p4, p5, ... )

This handler is called for a frame (applicationFrame or popupFrame) window when one of its child windows is about to receive any event that has no specific child event handler.

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

Returns
result boolean Always false.

Remarks
This base implementation does nothing and returns false.

If the overridden handler returns true the event is not routed to the child window.


top


win.window:on_child_focus

result window:on_child_focus (wnd, blurred)

This handler is called for a frame (applicationFrame or popupFrame) window when one of its child windows is about to receive input focus.

Parameters
child window Child window the event is for.
blurred window The window losing focus, it may be nil.

Returns
result boolean Always false.

Remarks
This base implementation does nothing and returns false.

If the overridden handler returns true the event is not routed to the child window.


top


win.window:on_child_key

result window:on_child_key (wnd, key, ctrl, alt, shift)

This handler is called for a frame (applicationFrame or popupFrame) window when one of its child windows is about to receive a key event.

Parameters
child window Child window the event is for.
key number Key code.
ctrl boolean True if control key is depressed.
alt boolean True if alternate key is depressed.
shift boolean True if shift key is depressed.

Returns
result boolean Always false.

Remarks
This base implementation does nothing and returns false.

If the overridden handler returns true the event is not routed to the child window.


top


win.window:on_child_key_up - not implemented

result window:on_child_key_up (wnd, key)

This event is not implemented.

This handler is called for a frame (applicationFrame or popupFrame) window when one of its child windows is about to receive a key_up event.

Parameters
child window Child window the event is for.
key number Key code.

Returns
result boolean Always false.

Remarks
This base implementation does nothing and returns false.

If the overridden handler returns true the event is not routed to the child window.


top


win.window:on_child_left_click

result window:on_child_left_click (wnd, x, y, count)

This handler is called for a frame (applicationFrame or popupFrame) window when one of its child windows is about to receive a mouse left button click event.

Parameters
child window Child window the event is for.
x number Screen relative x position.
y number Screen relative y position.
count number The number of times this same position was repeatedly clicked, with each successive click within the double_click_time.

Returns
result boolean Always false.

Remarks
This base implementation does nothing and returns false.

If the overridden handler returns true the event is not routed to the child window.


top


win.window:on_child_left_drag - not implemented

result window:on_child_left_drag (wnd, x, y)

This event is not implemented.

This handler is called for a frame (applicationFrame or popupFrame) window when one of its child windows is about to receive a mouse left button drag event.

Parameters
child window Child window the event is for.
x number Screen relative x position.
y number Screen relative y position.

Returns
result boolean Always false.

Remarks
This base implementation does nothing and returns false.

If the overridden handler returns true the event is not routed to the child window.


top


win.window:on_child_left_up - not implemented

result window:on_child_left_up (wnd, x, y)

This event is not implemented.

This handler is called for a frame (applicationFrame or popupFrame) window when one of its child windows is about to receive a mouse left button release event.

Parameters
child window Child window the event is for.
x number Screen relative x position.
y number Screen relative y position.

Returns
result boolean Always false.

Remarks
This base implementation does nothing and returns false.

If the overridden handler returns true the event is not routed to the child window.


top


win.window:on_child_middle_click - not implemented

result window:on_child_middle_click (wnd, x, y, count)

This event is not implemented.

This handler is called for a frame (applicationFrame or popupFrame) window when one of its child windows is about to receive a mouse middle button click event.

Parameters
child window Child window the event is for.
x number Screen relative x position.
y number Screen relative y position.
count number The number of times this same position was repeatedly clicked, with each successive click within the double_click_time.

Returns
result boolean Always false.

Remarks
This base implementation does nothing and returns false.

If the overridden handler returns true the event is not routed to the child window.


top


win.window:on_child_middle_drag - not implemented

result window:on_child_middle_drag (wnd, x, y)

This event is not implemented.

This handler is called for a frame (applicationFrame or popupFrame) window when one of its child windows is about to receive a mouse right button drag event.

Parameters
child window Child window the event is for.
x number Screen relative x position.
y number Screen relative y position.

Returns
result boolean Always false.

Remarks
This base implementation does nothing and returns false.

If the overridden handler returns true the event is not routed to the child window.


top


win.window:on_child_middle_up - not implemented

result window:on_child_middle_up (wnd, x, y)

This event is not implemented.

This handler is called for a frame (applicationFrame or popupFrame) window when one of its child windows is about to receive a mouse middle button release event.

Parameters
child window Child window the event is for.
x number Screen relative x position.
y number Screen relative y position.

Returns
result boolean Always false.

Remarks
This base implementation does nothing and returns false.

If the overridden handler returns true the event is not routed to the child window.


top


win.window:on_child_right_click - not implemented

result window:on_child_right_click (wnd, x, y, count)

This event is not implemented.

This handler is called for a frame (applicationFrame or popupFrame) window when one of its child windows is about to receive a mouse right button click event.

Parameters
child window Child window the event is for.
x number Screen relative x position.
y number Screen relative y position.
count number The number of times this same position was repeatedly clicked, with each successive click within the double_click_time.

Returns
result boolean Always false.

Remarks
This base implementation does nothing and returns false.

If the overridden handler returns true the event is not routed to the child window.


top


win.window:on_child_right_drag - not implemented

result window:on_child_right_drag (wnd, x, y)

This event is not implemented.

This handler is called for a frame (applicationFrame or popupFrame) window when one of its child windows is about to receive a mouse right button drag event.

Parameters
child window Child window the event is for.
x number Screen relative x position.
y number Screen relative y position.

Returns
result boolean Always false.

Remarks
This base implementation does nothing and returns false.

If the overridden handler returns true the event is not routed to the child window.


top


win.window:on_child_right_up - not implemented

result window:on_child_right_up (wnd, x, y)

This event is not implemented.

This handler is called for a frame (applicationFrame or popupFrame) window when one of its child windows is about to receive a mouse right button release event.

Parameters
child window Child window the event is for.
x number Screen relative x position.
y number Screen relative y position.

Returns
result boolean Always false.

Remarks
This base implementation does nothing and returns false.

If the overridden handler returns true the event is not routed to the child window.


top


win.window:on_child_touch

result window:on_child_touch (wnd, x, y)

This handler is called for a frame (applicationFrame or popupFrame) window when one of its child windows is about to receive a monitor touch event.

Parameters
child window Child window the event is for.
x number Screen relative x position.
y number Screen relative y position.

Returns
result boolean Always false.

Remarks
This base implementation does nothing and returns false.

If the overridden handler returns true the event is not routed to the child window


top


win.window:on_clipboard

result window:on_clipboard (text)

This handler is called for the window that currently has input focus when a system's paste event occurs.

Parameters
text string The text data to paste.

Returns
result boolean Always false.

Remarks
This base implementation does nothing and returns false.


top


win.window:on_destroy_wnd

window:on_destroy_wnd ()

This handler is called for a window when it is being destroyed.

Parameters
none


Returns
none


Remarks
This base implementation does nothing.


top


win.window:on_event

result window:on_event (event, p1, p2, p3, p4, p5, ... )

This handler is called for the window in response to any event that has no specific handler.

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

Returns
result boolean Always false.

Remarks
This base implementation does nothing and returns false.

This handler is commonly overridden in frame windows to handle control, wanted and custom events. When an event is fully handled true should be returned, otherwise false.


top


win.window:on_focus

result window:on_focus (blurred)

Handler called when the window receives input focus.

Parameters
blurred window The window losing focus, it may be nil.

Returns
result boolean Always false.

Remarks
This base implementation hides the cursor and returns false.

See focus, window:on_blur.


top


win.window:on_frame_close

result window:on_frame_close ()

This handler is called for a window in response to a "frame_close" event (Ctrl+Alt+X).

Parameters
none


Returns
result boolean Always false.

Remarks
This base implementation does nothing and returns false.


top


win.window:on_h_scroll

result window:on_h_scroll (direction, page)

This handler is called for the window in response to a "hbar_scroll" event.

Parameters
direction number -1 if scrolled up, 1 if down.
page boolean True for page action, false for column action.

Returns
result boolean Always true.

Remarks
This base implementation does the appropriate scrolling and returns true.

See window:on_v_scroll.


top


win.window:on_idle

result window:on_idle (count)

This handler is called by the system when no other event is being processed, and is only called for frame window objects.

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

Returns
result boolean Always false.

Remarks
Code in the overridden handler should be kept to a minimum as it is fired frequently, and should only be used for low priority processing.

This base implementation does nothing and returns false.

See Special Keys.


top


win.window:on_key

result window:on_key (key, ctrl, alt, shift)

This handler is called for the window that currently has input focus when a key event occurs.

Parameters
key number Key code.
ctrl boolean True if control key is depressed.
alt boolean True if alternate key is depressed.
shift boolean True if shift key is depressed.

Returns
result boolean Always false.

Remarks
This base implementation does nothing and returns false.

See Special Keys.


top


win.window:on_key_up - not implemented

result window:on_key_up (key)

This event is not implemented.

This handler is called for the window that currently has input focus when a key_up event occurs.

Parameters
key number Key code.

Returns
result boolean Always false.

Remarks
 This base implementation does nothing and returns false.

See Special Keys.


top


win.window:on_left_click

result window:on_left_click (x, y, count)

This handler is called for the window under the mouse when a mouse left button click occurs.

Parameters
x number Window relative x position.
y number Window relative y position.
count number The number of times this same position was repeatedly clicked, with each successive click within the double_click_time.

Returns
result boolean True if scroll bar actioned, false if not.

Remarks
This base implementation sets input focus to the window if its window:get_want_focus value is true, and implements the scroll bar events "vbar_scroll" and "hbar_scroll" as required. If this handler is overridden the base implementation should be called, and return true immediately if true is returned from the base.

See window:wnd_to_scroll.


top


win.window:on_left_drag - not implemented

result window:on_left_drag (x, y)

This event is not implemented.

This handler is called for the window of the preceding left click event until the drag action is complete.

Parameters
x number Window relative x position.
y number Window relative y position.

Returns
result boolean Always false.

Remarks
This base implementation does nothing and returns false.

See window:wnd_to_scroll.


top


win.window:on_left_up - not implemented

result window:on_left_up (x, y)

This event is not implemented.

This handler is called for the window under the mouse when a mouse left button release occurs.

Parameters
x number Window relative x position.
y number Window relative y position.

Returns
result boolean Always false.

Remarks
This base implementation does nothing and returns false.

See window:wnd_to_scroll.


top


win.window:on_middle_click - not implemented

result window:on_middle_click (x, y, count)

This event is not implemented.

This handler is called for the window under the mouse when a mouse middle button click occurs.

Parameters
x number Window relative x position.
y number Window relative y position.
count number The number of times this same position was repeatedly clicked, with each successive click within the double_click_time.

Returns
result boolean Always false.

Remarks
This base implementation sets input focus to the window if its window:get_want_focus value is true, and returns false.

See window:wnd_to_scroll.


top


win.window:on_middle_drag - not implemented

result window:on_middle_drag (x, y)

This event is not implemented.

This handler is called for the window of the preceding middle click event until the drag action is complete.

Parameters
x number Window relative x position.
y number Window relative y position.

Returns
result boolean Always false.

Remarks
This base implementation does nothing and returns false.

See window:wnd_to_scroll.


top


win.window:on_middle_up - not implemented

result window:on_middle_up (x, y)

This event is not implemented.

This handler is called for the window under the mouse when a mouse middle button release occurs.

Parameters
x number Window relative x position.
y number Window relative y position.

Returns
result boolean Always false.

Remarks
This base implementation does nothing and returns false.

See window:wnd_to_scroll.


top


win.window:on_move

result window:on_move ()

This handler is called for a window when its positioning or dimensions are altered.

Parameters
none


Returns
result boolean Always false.

Remarks
This base implementation does nothing and returns false.

See window:move.


top


win.window:on_receive

result window:on_receive (msg)

Called for a window with a registered interest in a comm connection when a message is received.

Parameters
msg msg The message received.

Returns
result boolean Always false.

Remarks
This base implementation does nothing and returns false.

This handler is commonly overridden to process received messages. When a message is handled true must be returned, otherwise false.

See window:want_wessages, window:on_sent, comm_receive.


top


win.window:on_resize

result window:on_resize ()

This handler is called for frame (applicationFrame and popupFrame) windows when a monitor or terminal resize event occurs, or text scale or full screen mode changes.

Parameters
none


Returns
result boolean Always false.

Remarks
This base implementation does nothing and returns false.

See window:on_move.


top


win.window:on_right_click - not implemented

result window:on_right_click (x, y, count)

This event is not implemented.

This handler is called for the window under the mouse when a mouse right button click occurs.

Parameters
x number Window relative x position.
y number Window relative y position.
count number The number of times this same position was repeatedly clicked, with each successive click within the double_click_time.

Returns
result boolean Always false.

Remarks
This base implementation sets input focus to the window if its window:get_want_focus value is true, and returns false.

See window:wnd_to_scroll.


top


win.window:on_right_drag - not implemented

result window:on_right_drag (x, y)

This event is not implemented.

This handler is called for the window of the preceding right click event until the drag action is complete.

Parameters
x number Window relative x position.
y number Window relative y position.

Returns
result boolean Always false.

Remarks
This base implementation does nothing and returns false.

See window:wnd_to_scroll.


top


win.window:on_right_up - not implemented

result window:on_right_up (x, y)

This event is not implemented.

This handler is called for the window under the mouse when a mouse right button release occurs.

Parameters
x number Window relative x position.
y number Window relative y position.

Returns
result boolean Always false.

Remarks
This base implementation does nothing and returns false.

See window:wnd_to_scroll.


top


win.window:on_scroll

window:on_scroll ()

This handler is called for a window when its scroll position changes.

Parameters
none


Returns
none


Remarks
This base implementation does nothing.


top


win.window:on_scroll_wheel - not implemented

result window:on_scroll_wheel (direction, x, y)

This event is not implemented.

This handler is called for the window under the mouse when a mouse wheel event occurs.

Parameters
direction number -1 if scrolled up, 1 if down.
x number Window relative x position.
y number Window relative y position.

Returns
result boolean Always true.

Remarks
This base implementation performs appropriate scrolling for the window and returns true. If the mouse is over the horizontal scroll bar this action scrolls columns, otherwise lines.

See window:wnd_to_scroll.


top


win.window:on_sent

result window:on_sent (msg, success)

Called for a window with a registered interest in a comm connection to receive sent notifications.

Parameters
msg msg The message that was sent.
success boolean True if the message was successfully sent, false if failed (an addressed message that did not receive a confirmation).

Returns
result boolean Always false.

Remarks
This base implementation does nothing and returns false.

See window:want_messages, window:on_receive, comm_sent.


top


win.window:on_timer

result window:on_timer (id)

This handler is called for a window in response to a timer event.

Parameters
id number Timer id (gained when the timer was started).

Returns
result boolean Always false.

Remarks
This base implementation does nothing and returns false.

See window:start_timer.


top


win.window:on_touch

result window:on_touch (x, y)

This handler is called for the window at the point where a monitor touch occurs.

Parameters
x number Window relative x position.
y number Window relative y position.

Returns
result boolean True if scroll bar actioned, false if not.

Remarks
This base implementation sets input focus to the window if its window:get_want_focus value is true, and implements the scroll bar events "vbar_scroll" and "hbar_scroll" as required. It also invokes the on screen keyboard on a monitor if required. If this handler is overridden the base implementation should be called, and return true immediately if true is returned from the base.

See window:wnd_to_scroll.


top


win.window:on_v_scroll

result window:on_v_scroll (direction, page)

This handler is called for the window in response to a "vbar_scroll" event.

Parameters
direction number -1 if scrolled up, 1 if down.
page boolean True for page action, false for line action.

Returns
result boolean Always true.

Remarks
This base implementation does the appropriate scrolling and returns true.

See window:on_h_scroll.


top


See also API Reference, WIN.