win.popupFrame - WIN

Class popupFrame
Inherits from parentFrame.

The popupFrame class provides a dialog frame window, associated with the current top frame of the application (the owner frame). The owner frame is disabled while this popupFrame is displayed. The popupFrame runs in a modal state, halting the process of the calling thread until the popupFrame is dismissed.

The size of the popupFrame is trimmed to the work area of the desktop if needed and the popupFrame is centered in the same.

A popupFrame can be create by calling parentFrame:create_popup, or deriving a class from popupFrame and instantiating an object from it, then calling popupFrame:do_modal to run it.

Popups are usually created locally to get user input and then destroyed.
-- popup ids
local ID_USERINPUT = 201
local ID_OK = 202


-- myPopup class -------------------------------------------------------
local myPopup = win.popupFrame:base ()


-- return false on failure
function myPopup:on_create (current_value)
self:dress ("Set Title")

self.user_input = tostring (current_value)

local inp = win.inputWindow:new (self, ID_USERINPUT, 1, 2, 14, tostring (current_value), "Input")
inp:set_sel (0, -1)
inp:set_focus ()

win.buttonWindow:new (self, ID_OK, 11, 4, " Ok ")

self:move (nil, nil, 16, 6)

return true
end


-- handles events for myPopup
function myPopup:on_event (event, p1, p2, p3, p4, p5, ...)
if event == "btn_click" then
if p1:get_id () == ID_OK then
local inp = self:get_wnd_by_id (ID_USERINPUT)

if inp then
self.user_input = inp:get_text ()
end

self:close (ID_OK)

return true
end
end

return false
end
-- end myPopup class ---------------------------------------------------


-- using the popup
function appFrame:do_popup ()
local pop = myPopup:new (self)

if pop then
local result = pop:do_modal ("some value")

if result == ID_OK then
return pop.user_input
end
end

return nil
end


Properties

none       

Methods

See also API Reference, WIN.

win.popupFrame:close

closed popupFrame:close (result)

Closes (and destroys) the popupFrame. The on_close handler is called in this process. If the on_close handler returns true this operation is cancelled.

Parameters
result number The value to be returned by popupFrame:do_modal.

Returns
closed boolean True if the popupFrame was closed, false if not.

Remarks


top


win.popupFrame:constructor

frame popupFrame:constructor (owner_frame, width, height)

Constructs and returns the instantiated frame window.

Parameters
owner_frame parentFrame The owner frame of this frame.
width number Width of the frame.
height number Height of the frame.

Returns
frame popupFrame The instantiated frame window object.

Remarks
The owner frame must be the frame process running the popup. The will be the application's applicationFrame or another popupFrame if being called from within another popup.

The frame is trimmed to the desktop work area, and initially centered on the same.

See desktopWindow:get_work_area.


top


win.popupFrame:do_modal

result popupFrame:do_modal (...)

Calls on_create. If on_create returns true then enters modal state, processing events from the system until dismissed with popupFrame:close. Then the frame is destroyed returning the value passed to popupFrame:close. If on_create returns false then modal state is not entered. The frame is immediately destroyed and returns nil.

Parameters
... varying Varying on specific implementation. Passed directly to on_create.

Returns
result number/nil The value passed to popupFrame:close. If on_create return false then nil.

Remarks
The parameters passed to do_modal are dependent on the required parameters to the overridden version of on_create. This implementation does not require any.


top


win.popupFrame:draw

popupFrame:draw (gdi, bounds)

Erases the title bar if required and draws the frame around the popup frame.

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

Returns
none


Remarks
See window:draw.


top


win.popupFrame:dress

popupFrame:dress (title)

Adds a title bar and close button to the popupFrame. The title is displayed in the title bar and set as the popupFrame 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.


top


win.popupFrame:move

popupFrame:move (x, y, width, height)

Moves and/or redimensions the window.

Parameters
x number/nil Screen relative x position. If nil then centered horizontally.
y number/nil Screen relative y position. If nil then centered vertically.
width number/nil Window width. If nil then unchanged.
height number/nil Window height. If nil then unchanged.

Returns
none


Remarks
Dimensions and positions are trimmed to the desktop work area.

See desktopWindow:get_work_area.


top


win.popupFrame:on_close

result popupFrame:on_close ()

Called when the popupFrame is closing.

Parameters
none


Returns
result boolean Always false.

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

This base implementation does nothing and returns false.

See popupFrame:close.


top


win.popupFrame:on_create

result popupFrame:on_create (...)

Override method to construct the popup frame.

Parameters
... varying The parameters passed to popupFrame:do_modal, if any.

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

Remarks
This method is called by popupFrame:do_modal, and is typically overridden in derived classes to construct the popup frame's contents. If it returns true the process continues into modal mode. If false the popup frame is immediately destroyed and popupFrame:do_modal returns nil.

This implementation does nothing and returns true.


top


win.popupFrame:on_frame_close

result popupFrame:on_frame_close ()

This handler is called for the frame in response to a frame_close event (Ctrl+Alt+X or closeButtonWindow). Calls popupFrame:close with a value of win.ID_CLOSE to end the modal state and close the popup frame.

Parameters
none


Returns
result boolean Always true.

Remarks
See window:on_frame_close.


top


win.popupFrame:on_move

result popupFrame:on_move ()

Repositions the close button if present.

Parameters
none



Returns
result
boolean
Always false.

Remarks
See window:on_move.

top


win.popupFrame:on_resize

result popupFrame:on_resize ()

Centers the popupFrame and trims its size to the desktop work area if required. Moves the close button if required.

Parameters
none


Returns
result boolean Always true.

Remarks
The popupFrame is always centered.

See window:on_resize.


top


win.popupFrame:set_title

popupFrame:set_title (title)

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

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

Returns
none


Remarks
See window:set_text.


top


See also API Reference, WIN.