win.applicationFrame - WIN

Class applicationFrame
Inherits from parentFrame.

The applicationFrame class provides the application's main frame. Each running instance of an application has one applicationFrame which is the top frame of the application. The class is defined as global so base implementation calls are possible from an application program, but an applicationFrame window should never be instantiated directly. During construction the applicationFrame must be linked up with the appropriate desktop. Once linked up all display device information is propagated through the window hierarchy. The win.create_app_frame function is used to create the application's main frame in the application's program file.

Printing is implemented by overriding the applicationFrame:on_print_data and applicationFrame:on_print_page methods specifically for the application's needs. Then calling applicationFrame:print_doc to run the printing loop.

Properties

appFrame__app_path
string Stores the full path to the application program file.
appFrame__app_thread
thread Stores the coroutine thread for the application.
appFrame__yield_point
string The thread's last yield point.

Methods

See also API Reference, WIN.

local get_printer_status

status get_printer_status (gdi)

Internal helper function to query the status of a printer during a print loop operation.

Parameters
gdi
GDI
GDI object for the printer to query.

Returns
status string
The printer's status.

Remarks
Not accessible outside of applicationFrame.


top


win.applicationFrame:constructor

frame applicationFrame:constructor (dir)

Constructs and returns the instantiated application frame window.

Parameters
dir string Desktop directory under /win/devices.

Returns
frame applicationFrame The instantiated frame window.

Remarks
Application frames are created through the win.create_app_frame function, not directly.


top


win.applicationFrame:draw

applicationFrame:draw (gdi, bounds)

Erases the title bar if required.

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

Returns
none


Remarks
See window:draw.


top


win.applicationFrame:dress

applicationFrame:dress (title)


Adds a title bar and close button to the applicationFrame. The title is displayed in the title bar and set as the applicationFrame window's text value.

Parameters
title string Displayed in the title bar and set as window text.

Returns
none


Remarks
The close button is at the top of the z order and is set to receive input focus.

The window text value of the application's applicationFrame window is displayed in the running applications list to identify the instance of the application.


top


win.applicationFrame:get_app_path

path applicationFrame:get_app_path ()

Returns the full path to this application's program file.

Parameters
none


Returns
path string Full path to this application's program file.

Remarks


top


win.applicationFrame:on_create

result applicationFrame:on_create ()

Override method to construct the application frame and initialize the application.

Parameters
none


Returns
result boolean True if successfully created, false if not.

Remarks
This method is called by applicationFrame:run_app, and is typically overridden in derived classes to construct the application frame's contents and initialize the application. If it returns true the process continues into modal mode. If false the application frame is immediately destroyed and the application quits.

This implementation does nothing and returns true.


top


win.applicationFrame:on_frame_close

result applicationFrame:on_frame_close ()

This handler is called for the frame in response to a frame_close event (Ctrl+Alt+X or closeButtonWindow). Calls applicationFrame:quit_app to end the modal state and quit the application's thread.

Parameters
none


Returns
result boolean Always true.

Remarks
See window:on_frame_close.


top


win.applicationFrame:on_print_data

data applicationFrame:on_print_data (title, user_data, pages, bgcolor)

Calls cmndlg.print to get printer and optionally a page range from the user, and returns a printData object containing information for the print run. If the user cancels the cmndlg.print nil is returned.

This method is overridden and calls this base implementation with appropriate parameter values for the application, such that no parameter values are required for the overridden version.

Parameters
title string Document title.
user_data any Custom data passed to the printing mechanism.
pages number Total pages in document. Zero means unspecified (cmndlg.print does not display page range, and data.from_page and data.to_page are zero).
bgcolor number The background color for the cmndlg.print popup frame. If nil the theme's popup_back color is used.

Returns
data printData The constructed printData object containing information for the print run, or nil if cancelled.

Remarks
See applicationFrame:on_print_page.


top


win.applicationFrame:on_print_page

continue applicationFrame:on_print_page (gdi, page, data)

Called for each page in succession to print the page. This method is overridden to provide for the printing needs of an application.

Parameters
gdi GDI GDI object to use for drawing.
page number 1 based page number to print.
data printData Print data object containing information about the print run.

Returns
continue boolean Always false.

Remarks
This base implementation does nothing and returns false.

If the overridden handler returns true printing continues, otherwise printing stops.

See applicationFrame:on_print_data.


top


win.applicationFrame:on_quit

result applicationFrame:on_quit ()

Called when the application is quitting.

Parameters
none


Returns
result boolean Always false.

Remarks
If the overridden version of this handler returns true the quit operation is cancelled.

This base implementation does nothing and returns false.


top


win.applicationFrame:on_resize

result applicationFrame:on_resize ()

Resizes the frame to the work area of the desktop, and moves the title bar and close button if required.

Parameters
none


Returns
result boolean Always true.

Remarks
See desktopWindow:get_work_area, window:on_resize.


top


win.applicationFrame:print_doc

applicationFrame:print_doc ()

Implements the printing mechanism by calling on_print_data and passing its return value to applicationFrame:print_loop.

Parameters
none


Returns
none


Remarks
Printing is implemented by overriding the applicationFrame:on_print_data and applicationFrame:on_print_page methods specifically for the application's needs.


top


win.applicationFrame:print_loop

applicationFrame:print_loop (data)

Implements the printing loop, calling on_print_page for each page to print. This method is called by applicationFrame:print_doc.

Parameters
data printData Print data object containing information for the print run. If nil the loop does not run and returns immediately.

Returns
none


Remarks
See applicationFrame:on_print_data.


top


win.applicationFrame:quit_app

applicationFrame:quit_app ()

Terminates the modal state and quits the application.

Parameters
none


Returns
none


Remarks
If on_quit returns true this operation is cancelled.


top


win.applicationFrame:resume

result applicationFrame:resume (wnd, ...)

Resumes the application's thread.

Parameters
wnd window Window the event is for.
... any Any additional parameters.

Returns
result boolean/table For events: the returned value from the event handler.
For other yields: all parameters passed back from the yield.
On failure false is returned.

Remarks


top


win.applicationFrame:run_app

applicationFrame:run_app ()

Calls on_create. If on_create returns true then enters modal state, processing events from the system until dismissed with applicationFrame:quit_app. Then the frame is destroyed and the application quits. If on_create returns false then modal state is not entered. The frame is immediately destroyed and the application quits.

Parameters
none


Returns
none


Remarks
A call to this method through the instantiated applicationFrame window should be the last statement in the application program file.


top


win.applicationFrame:set_title

applicationFrame:set_title (title)

Sets the applicationFrame title bar text (if it has one) and also the applicationFrame window text with the same value.

Parameters
title string Displayed in the title bar (if required) and set as window text.

Returns
none


Remarks
The window text value of the application's applicationFrame window is displayed in the running applications list to identify the instance of the application.

See window:set_text.


top


win.applicationFrame:status

status applicationFrame:status ()

Returns the status of the applications thread.

Parameters
none


Returns
status string The thread's status.

Remarks
Valid return values:
running The thread is currently running.
normal The thread is active but has resumed another thread.
dead The thread has returned or thrown an uncaught error.
modal The thread yielded from its modal loop.
other
The first parameter of any other type of yield.


top


See also API Reference, WIN.