win.GDI - WIN

Class GDI
Inherits from __classBase.

GDI objects are intermediary interfaces for device drawing and information, providing an universal mechanism for drawing to devices. Each window object has its own GDI, which clips its drawing to its window surface. GDIs support the terminal, monitors and printers. Adhoc GDIs can be created (typically for printers) with the digilines channel of the attached device and a nil value for the window.

Properties

gdi__bounds	rect	Holds the effected rectangle of the attached device in screen coordinates.
gdi__channels	string/list	The digilines channel/s of the attached device.
gdi__device	interface	The peripheral interface for the attached device.
gdi__device_type	string	Type of attached device: `"term"` `"monitor"` `"printer"`
gdi__stored_bg_color	number/nil	Stored background color.
gdi__stored_blink	boolean/nil	Stored blink state (cursor is visible).
gdi__stored_bounds	rect	Stored bounds rectangle.
gdi__stored_cursor_x	number/nil	Stored cursor x coordinate, nil when not stored.
gdi__stored_cursor_y	number/nil	Stored cursor y coordinate, nil when not stored.
gdi__stored_fg_color	number/nil	Stored foreground color.
gdi__stored_x_org	number/nil	Stored x coordinate offset for drawing.
gdi__stored_y_org	number/nil	Stored y coordinate offset for drawing.
gdi__type	number	Value indicating the type of device. Will be one of the following: `private.GDI_TERM` `private.GDI_MONITOR` `private.GDI_PRINTER`
gdi__width	number	Display width for multi-monitor devices.
gdi__wnd	window/nil	Window this GDI is associated with, nil for printer.
gdi__x_org	number	x coordinate offset for drawing.
gdi__y_org	number	y coordinate offset for drawing.

Methods

General
Drawing
Printer

General

win.GDI:add_bounds

GDI:add_bounds (rt)

Adds (combines) the given rectangle to the GDI's bounds rectangle.

Parameters

rect

The rectangle to add to the GDI's bounds, in screen coordinates.

Returns

none

Remarks

top

win.GDI:constructor

gdi GDI:constructor (device_type, dir, wnd, width, channels)

Constructs the GDI object attached to the device, and associated with the window if given.

Parameters

device_type	string	Type of device. Can be: `"term"` `"monitor"` `"printer"`
dir	string	Desktop directory under /win/devices or digilines channel for printers.
wnd	window/nil	Window object associated with this GDI object, or nil for none.
width	number	Display width for multi-monitor devices. Ignored for others.
channels	string/list	The digilines channel/s of the attached device.

Returns

gdi

GDI

The instantiated and attached GDI object, or nil on failure.

Remarks
Window GDIs are typically created by the window object when the parent window is set. To create a printing GDI use GDI:new_for_printer.

top

win.GDI:from_GDI

result GDI:from_GDI (gdi, wnd)

Re-configures this GDI object based on another GDI object.

Parameters

gdi	GDI	The GDI to copy from.
wnd	window	The window for this GDI.

Returns

result

boolean

True if successful, false if not.

Remarks
Used when setting parent of a window.

top

win.GDI:get_blink

result GDI:get_blink ()

Returns the current blink state for the device attached to the GDI object.

Parameters

none

Returns

result

boolean

True if cursor is currently visible, false if not.

Remarks
GDIs attached to printers always return false.

top

win.GDI:get_bounds

rt GDI:get_bounds (clear)

Returns a rectangle object of the GDI's bounds rectangle. This is a rectangle of the area affected by the drawing operations. If clear is true the GDI's bounds rectangle is made empty.

Parameters

clear

boolean

Resets the GDI's bounds rectangle to empty if true. If false the rectangle is unaffected.

Returns

rect

A rectangle of the drawing effected bounds of the device in screen coordinates.

Remarks
If no drawing has been done since the rectangle was reset the returned rectangle is empty.

top

win.GDI:get_colors

fgcolor, bgcolor GDI:get_colors ()

Returns the foreground and background colors from the device associated with the GDI.

Parameters

none

Returns

fgcolor	number	foreground color
bgcolor	number	background color

Remarks
See GDI:set_colors.

top

win.GDI:get_cursor

x, y GDI:get_cursor ()

Returns the cursor position for the device associated with the GDI.

Parameters

none

Returns

x	number	Horizontal cursor position.
y	number	Vertical cursor position.

Remarks
This method calls the device interface directly. The returned coordinates are 0, 0 based.

See GDI:set_cursor.

top

win.GDI:get_dir

dir GDI:get_dir ()

Returns the desktop directory under /win/devices or printer's digilines channel the device associated with this GDI is attached to.

Parameters

none

Returns

dir

string

The desktop directory or printer's channel.

Remarks

top

win.GDI:get_org

x, y GDI:get_org ()

Returns the GDI's drawing offset.

Parameters

none

Returns

x	number	x coordinate offset for drawing.
y	number	y coordinate offset for drawing.

Remarks
The origin point for the GDI is the device zero based coordinates that drawing 0, 0 is translated to.

top

win.GDI:get_size

width, height GDI:get_size ()

Returns the drawing size of the device associated with the GDI.

Parameters

none

Returns

width	number	Drawing width of the device.
height	number	Drawing height of the device.

Remarks
If the device is a printer the page size is returned. If no device is associated returns 0, 0.

top

win.GDI:is_monitor

result GDI:is_monitor ()

Returns true if the device associated with the GDI is a monitor, false if not.

Parameters

none

Returns

result

boolean

true if associated with a monitor, false if not.

Remarks

top

win.GDI:is_printer

result GDI:is_printer ()

Returns true if the device associated with the GDI is a printer, false if not.

Parameters

none

Returns

result

boolean

true if associated with a printer, false if not.

Remarks

top

win.GDI:is_term

result GDI:is_term ()

Returns true if the device associated with the GDI is the terminal, false if not.

Parameters

none

Returns

result

boolean

true if associated with the terminal, false if not.

Remarks

top

win.GDI:is_touch

x, y GDI:is_touch (channel, msg)

Determines if a digilines message is a touch message from the monitor attached to this GDI object.

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 monitor.
y	number/nil	The monitor's y character coordinate touched or nil if not from this monitor.

Remarks

top

win.GDI:restore

GDI:restore ()

Restores the GDI object and device to their state when GDI:store was called.

Parameters

none

Returns

none

Remarks
This process is not stacked, one call to GDI:store followed by one call to GDI:restore. If GDI:store was not called this call is ignored.

top

win.GDI:set_blink

GDI:set_blink (blink)

Sets the cursor blink state for the device attached to this GDI object.

Parameters

blink

boolean

True to display cursor, false to hide.

Returns

none

Remarks
This call is ignored for printers.

top

win.GDI:set_colors

GDI:set_colors (fgcolor, bgcolor)

Sets the colors for the device associated with this GDI.

Parameters

fgcolor	number/nil	The foreground color to set, or nil for no change.
bgcolor	number/nil	The background color to set, or nil for no change.

Returns

none

Remarks
A color must be a correct color value.

top

win.GDI:set_cursor

GDI:set_cursor (x, y)

Sets the cursor position for the device associated with the GDI.

Parameters

x	number	Horizontal cursor position.
y	number	Vertical cursor position.

Returns

none

Remarks
This method calls the device interface directly. The coordinates are 0, 0 based.

top

win.GDI:set_device

result GDI:set_device (device_type, dir, width, channels)

Sets up the GDI object for the given device.

Parameters

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

Returns

result

Remarks
This method is called internally.

top

win.GDI:set_org

GDI:set_org (x, y)

Sets the GDI's drawing offset.

Parameters

x	number	x coordinate offset for drawing.
y	number	y coordinate offset for drawing.

Returns

none

Remarks
The origin point for the GDI is the device zero based coordinates that drawing 0, 0 is translated to.

top

win.GDI:set_scale

GDI:set_scale (scale)

Sets the scale for the monitor device associated with this GDI.

Parameters

scale

number

The scale to set (1 to 5).

Returns

none

Remarks
The call is ignored if the device is not a monitor.

top

win.GDI:store

GDI:store ()

Stores the state of the GDI object, which can be restored with a call to GDI:restore, for the device associated with the GDI.

Parameters

none

Returns

none

Remarks
This process is not stacked, one call to GDI:store followed by one call to GDI:restore. If the GDI object's state is already stored this call is ignored.

top

win.GDI:update

GDI:update ()

Flushes any drawing changes to the monitor attached to this GDI object.

Parameters

none

Returns

none

Remarks
If the GDI object's device is not a monitor this call is ignored.

top

Drawing

win.GDI:clear

GDI:clear (x, y, width, height)

Clears the rectangle to the currently set background color.

Parameters

x	number	Left position of the rectangle.
y	number	Top position of the rectangle.
width	number	Width of the rectangle.
height	number	Height of the rectangle.

Returns

none

Remarks
If the GDI is associated with a window, the coordinates are window relative accounting for any scrolling, and the drawing is clipped to the window's client area (excluding any scroll bars).

See GDI:clear_wnd.

top

win.GDI:clear_wnd

GDI:clear_wnd (x, y, width, height)

Clears the rectangle to the currently set background colour.

Parameters

x	number	Left position of the rectangle.
y	number	Top position of the rectangle.
width	number	Width of the rectangle.
height	number	Height of the rectangle.

Returns

none

Remarks
If the GDI is associated with a window, the coordinates are window relative and the drawing is clipped to the window.

See GDI:clear.

top

win.GDI:set_pixel

GDI:set_pixel (x, y, color)

Draws the pixel at x, y with color.

Parameters

x	number	x coordinate of the pixel (character).
y	number	y coordinate of the pixel (character).
color	number	Color to draw the pixel.

Returns

none

win.GDI:set_pixel_wnd

GDI:set_pixel_wnd (x, y, color)

Draws the pixel at x, y with color.

Parameters

x	number	x coordinate of the pixel (character).
y	number	y coordinate of the pixel (character).
color	number	Color to draw the pixel.

Returns

none

Remarks
If the GDI is associated with a window, the coordinates are window relative and the drawing is clipped to the window.

Color must be a correct color value.

See GDI:set_pixel.

top

win.GDI:write

GDI:write (text, x, y)

Draws the text at x, y with the currently set colours.

Parameters

text	string	The text to draw.
x	number	x coordinate to draw the text.
y	number	y coordinate to draw the text.

Returns

none

win.GDI:write_wnd

GDI:write_wnd (text, x, y)

Draws the text at x, y with the currently set colours.

Parameters

text	string	The text to draw.
x	number	x coordinate to draw the text.
y	number	y coordinate to draw the text.

Returns

none

Remarks
If the GDI is associated with a window, the coordinates are window relative and the drawing is clipped to the window.

See GDI:write.

top

Printer

win.GDI:end_page

GDI:end_page ()

Ends the page and prints the page to the output tray for the printer device associated with this GDI.

Parameters

none

Returns

none

Remarks
If the device is not a printer this call is ignored.

See GDI:start_page.

top

win.GDI:get_ink_level

level GDI:get_ink_level ()

Returns the ink level of the printer device associated with this GDI.

Parameters

none

Returns

level

number/nil

Printer ink level, or nil if the device is not a printer.

Remarks

top

win.GDI:get_page_size

width, height GDI:get_page_size ()

Gets the page size of the printer device associated with this GDI.

Parameters

none

Returns

width	number/nil	Drawing width of the page, or nil if not a printer.
height	number/nil	Drawing height of the page, or nil if not a printer.

Remarks

top

win.GDI:get_paper_level

paper GDI:get_paper_level ()

Returns the available paper of the printer device associated with this GDI.

Parameters

none

Returns

paper

number/nil

Number of paper pages available, or nil if not a printer.

Remarks

top

win.GDI:get_status

status GDI:get_status ()

Returns the staus of the printer device associated with this GDI.

Parameters

none

Returns

status string/nil One of:
"ready" - the printer is ready to print.
"printing" - the printer is currently printing.
"no ink" - printer is out of ink.
"no paper" - printer is out of paper.
"tray full" - printer output tray is full.
nil - not a printer or printer didn't respond.

Remarks

top

win.GDI:new_for_printer

gdi GDI:new_for_printer (channel)

Constructs a new GDI object for a printer.

Parameters

channel

string

The digilines channel of the printer.

Returns

gdi

GDI

The new GDI object, or nil if failed.

Remarks
These GDI objects are usually created to run a print cycle and are destroyed when finished.

Only one GDI object should be created for a printer at a time.

top

win.GDI:start_page

result GDI:start_page (title, pageno)

Starts a new page for the printer device associated with this GDI.

Parameters

title	string	The title of the page. If nil or empty string "untitled" is used.
pageno	number	The page number for this page. If > 1 the page number is append to the title.

Returns

none

Remarks
If the device is not a printer this call is ignored.

See GDI:end_page.

top

See also API Reference, WIN.