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
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
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
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
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
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
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
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
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
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
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
Remarks
See window:set_text.
top
See also API
Reference, WIN.