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

See also API Reference, WIN.

General

win.GDI:add_bounds

GDI:add_bounds (rt)

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

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


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

Color must be a correct color value.

See GDI:set_pixel_wnd.


top


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


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:write_wnd.


top


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.