Popup function [Revelation On-Line Wiki]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Popup function ======

 
==== Description ====
 
Displays tabular data and allows user selection.

Note:  As of Version 4.1.3, the popup() function has been modified to sort dates and any other output converted data correctly.
 
==== Syntax ====
 
//result// = **Popup** (//ownerwindow//, //typeoverride//[, //name//])
 
==== Parameters ====
 
The Popup function has the following parameters:

^Parameter^Description^
|//ownerwindow//|Contains the name of the window from which to display the specified popup, typically @WINDOW.\\ \\ Note: When using an MDIFrame, the ownerwindow will always be the frame regardless of the value passed to the variable.\\ \\ **{{{guides:programming:programmers_reference_manual:caution.gif?28x21}}Caution:**   If there is no window, Popup will use the screen. In this case, there is no modality and no values will be returned to your program.|
|//typeoverride//|An @fm-delimited record containing the specification for the Popup, or override information if //name// is supplied.|
|//name//|The name of the Popup stored in the repository, or null if the entire Popup definition is being passed in //typeoverride//.|


A popup can be called either by\\ \\ Repository("EXECUTE", //popupentID//, //window// [, //typeoverride//]);\\ \\ - OR -\\ \\ Popup (window, typeoverride, popupname).

==== Record structure ====


These column positions are defined in the POPUP_EQUATES insert record.

^Column position^Name^Description^
|1|//col//|The X position (in pixels) of the popup relative to its calling window, //ownerwindow//. If set to -1, the popup will center itself in //ownerwindow//. If set to -2, it will center itself on the screen. The default is -1.|
|2|//row//|The Y position (in pixels) of the popup relative to its calling window, //ownerwindow//. If set to -1, the popup will center itself in //ownerwindow//. If set to -2, it will center itself on the screen. The default is -1.|
|3|//width//|The number of visible columns in the popup window. Scroll bars will allow the user to access all other "cells" not shown within the confines of the popup window. A -1 will cause the popup to have a width equal to the total number of columns. Default is -1.|
|4|//height//|The number of visible rows in the popup window. Scroll bars will allow the user to access all other "cells" not shown within the confines of the popup window. A -1 will cause the popup to have a height equal to the total number of rows. Default is -1.|
|5|//bkcolor//|Background color. An RGB @VM-delimited list is used (for example 255:@VM:0:@VM:0 is red, 0:@VM:255:@VM:0 is green).|
|6|//font//|The font to be used in the edit table.\\ For more information on this @svm-delimited structure, see Utility("CHOOSEFONT") and the FONT property.|
|7|//file//|Data source information; mode specific.\\ \\ __mode Value__ - __Description__\\ //C, F, K, R, T// - OpenInsight table name.\\ //D// - <7, 1>: DataSet name; <7, 2>: DataSet handle (allows an existing DataSet to be used as the data source for the Popup).\\ //N// - <7, 1>: Database Name;  <7, 2>: "NOTESFORM" or "NOTESVIEW"; <7, 3>: @SVM-delimited list of forms/views;  <7, 4>: For the form or view specified by <7,3,i>, an @TM-delimited list fields or columns is specified in <7,4,i>.\\ //L// - not applicable|
|8|//display//|Determines what information will be displayed; mode specific.\\ \\ __mode Value__ - __Description__\\ //C// - Cursor number 0-9 (0 is default)\\ //D// - <8, 1>: @SVM-delimited list of argument values; <8, 2>: @SVM-delimited list of corresponding argument names. If names are not supplied then argument numbers are assumed by position of argument values.\\ //F// - <8, 1>: OpenInsight Table Key; <8, 2>: Field Number.\\ //K// - @VM-delimited list of OpenInsight Table Keys.\\ //L//: @VM/@SVM-delimited array of literal data.\\ //N// - @VM- (as opposed to @FM) delimited SearchInfo record. (See "OpenNote() function" in //Programmer's Reference Manual// for details); - OR - Select script; for example "Select @all"; - OR -"USE" ViewName; for example "Use Contacts_by_Company".\\ //R// - OpenInsight Table Key.\\ //T// - Rlist selection and sorting criteria; for example "WITH COST < 100.00 BY COST".|
|9|//format//|An @VM/@SVM-delimited array of format information.\\ \\ __Parameter__ - __Description__\\ //Field// - Column name or number.\\ //Width// - Width of column (of characters).\\ //text justification// - //L//, //R//, or //C.//\\ //heading justification// - //L,// //R//, or //C//\\ //Oconv// - Output conversion pattern.\\ //Heading// - Heading text of column.|
|10|//mode//|Specifies how the Popup gets its data.\\ \\ __mode__ - __Description__\\ //C// - The popup row corresponds to a record retrieved from a Native Tables cursor.\\ //D// - The popup row corresponds to a DataSet row.\\ //F// - The popup row corresponds to a value in a multi-valued field in an Native Tables record.\\ //K// - The popup row corresponds to a Native Tables record identified by the passed Key.\\ //L// - The popup row corresponds to an @SVM-delimited array element of //display.//\\ //N// - The popup row corresponds to a Lotus Notes document.\\ //R// - The popup row corresponds to a field from the specified table.\\ //T// - The popup row corresponds to a Native Tables record selected using Rlist.|
|11|//select//|Specifies how many items the user can choose.\\ \\ __Value__ - __Description__\\ 0 - No selection.\\ 1 - One selection (default).\\ 2 - Multiple selections.\\ 3 - Ordered multiple selections.|
|12|//title//|Caption for the Popup.|
|13|//field//|Used to return a field from a Native table or DataSet; used with //type// C or F.|
|14|//type//|This defines the return type of the Popup.\\ \\ __Parameter__ - __Description__\\ //C// - **C**olumn:  Data from column //field// are returned (@VM-delimited list if multiple selections allowed). //field// specifies a column name (from the dictionary) or a number (as a column number in the row). Use //C// when you want to return data that is not displayed in the popup, but is part of each row.\\ //E// - **E**ntire row: Entire row is returned. (Multiple rows are delimited by @FM.).\\ //F// - Popup **f**ield:  Data from Popup column //field// are returned (@VM-delimited list if multiple selections allowed). //field// specifies a column number from the actual displayed data; i.e. column 1 is the first column in the Popup.\\ //K// - Row **k**ey: row key(s) of selected data (@VM-delimited list if multiple selections allowed). The Notes document ID is returned if the mode is //N//.\\ //P// - Row **p**osition: Row numbers of selected data are returned (@VM-delimited list if multiple selections allowed).\\ //R// - **R**ead only:  No value is returned.|
|15|//colhdr//|(Boolean) If TRUE, the column headings are visible on the Popup's edit table. Defaults to TRUE.|
|16|//rownum//|(Boolean) If TRUE, the row numbers are visible on the Popup's edit table. Defaults to TRUE.|
|17|//rowbtn//|(Boolean) If TRUE, the row buttons are visible on the Popup's edit table. Defaults to TRUE.|
|18|//hgrid//|(Boolean) If TRUE, the horizontal grid is visible on the Popup's edit table. Defaults to TRUE.|
|19|//vgrid//|(Boolean) If TRUE, the vertical grid is visible on the Popup's edit table. Defaults to TRUE.|
|20|//resize//|(Boolean) If TRUE, the columns in the Popup's edit table are resizeable. Defaults to TRUE.|
|21|//border//|(Boolean) If TRUE, borders are placed on the Popup's edit table. Defaults to TRUE.|
|22|//btnsbelow//|(Boolean) If TRUE, buttons are placed across the bottom, instead of on the right. Defaults to FALSE.|
|23|//search//|(Boolean) If TRUE, allows searching the Popup for a user specified value. Defaults to FALSE.|
|24|//sort//|(Boolean) If TRUE, allows column sorting. Defaults to FALSE.\\ \\ **Note:** Right justified columns are sorted right-justified, all others are sorted left-justified.|
|25|//lock//|The number of columns set to "scroll lock." Defaults to 0.|
|26|//user-defined//|This column reserved for user-defined information; it is not set or altered by Popup Designer.|
|27|//subfile//|Secondary data source information; mode specific.\\ \\ __mode Value__ - __Description__\\ //D// - <27, 1>: DataSource name; <27, 2>: Connection Object handle (Supplied at runtime).|
|28|initselect|@VM list of row numbers to initially select when the Popup is executed.|
|29|showmissing|(Boolean) If TRUE, show the phrase 'Record Missing' in columns.|
|30|print|(Boolean) If TRUE, show the print button.|
|31|showGauge|(Boolean) If TRUE, display a gas gauge message when the system is populating the popup.|
|32|captureEsc|(Boolean) If TRUE, return CHAR(27) when the Cancel button in the Popup window is clicked.|

 
==== Notes ====
 
For a Popup with mode //D//, when the Popup is executed it determines what data source to use in this order.

1.       If a DataSet handle is passed in <7, 2> (//file//), then that DataSet is used.

2.       If a Connection Object handle is passed in <27, 2> (//subfile//), then the DataSet is created and executed using that handle.

3.       If a DataSource name is passed in <27, 1> (//subfile)//, then a connection handle is created for that DataSource name using XOInstance and that handle is used to create and execute the DataSet.

Otherwise, the DataSource name specified in the DataSet Designer is used to create a connection which in turn is used to create and execute the DataSet passed in <7, 1> (File).
 
==== See Also ====
 
POPUP_EQUATES (Insert record).
 
==== Example ====

<code>
* Call a popup to Named 'EMP', fill in the EMP_NO control
* Use DEFPROP property, Send LOSTFOCUS event to trigger system events such as read or updating dependent controls
ans = popup(atWindow, '', 'EMP')
If ans Then
     Call Set_Property(atWindow:'.EMP_NO', 'DEFPROP', ans)
     Call Send_Event(atWindow:'.EMP_NO','LOSTFOCUS')
end
</code>

<code>
* Call a popup, override the definition to use a list of product keys related to this order

* Enable OI10 object notation for get, set property
#pragma precomp event_precomp

$insert popup_equates
declare subroutine send_Event
ctrl = atWindow:'.PRODUCT_CODE'
prod_codes = Xlate('ORDERS_REL', ordered, 'PRODUCTS', 'X')
override = ""
If prod_codes != null$ Then
     override<pMode$> = 'K' ; * list of keys
     override<pDisplay$> = prod_codes
     ans = popup(atWindow, override, 'SVC_CODE')
     If ans Then  
         @ctrl->DefProp = ans ; * same as set property
         Send_Event(object,'LOSTFOCUS')
    end
end
</code>

<code>

* Create a popup on the fly
* display a list stored in a user defined property

display = get_Property(atWindow, udp_route_list$)     
display_format = "1":@svm:"6":@svm:"R":@svm:"C":@svm:"":@SVM:"Route"

* Define the popup ( see POPUP_EQUATES )
def = ""
def<pTITLE$>     = 'Routes'
def<pMODE$>      = "L"                        ;* display will be literal data
def<pFORMAT$>    = display_format             ;* column format information (@vm delim'd by column, @svm by attribute) field, width, just, heading just, oconv, heading
def<pDISPLAY$>   = display                    ;* for mode 'L', the data to display, vm delimited by row, svm delimited by column
def<pGREENBAR$>  = true$                      ;* alternating colored rows in the display
def<pSEARCH$>    = true$                      ;* sortable
def<pSORT$>      = true$                      ;* searchable 
     
ans = Popup(atWindow, def)
If ans ne "" Then
     @CtrlEntID->Defprop = ans
     Call Send_Event(CtrlEntID, 'LOSTFOCUS')
end
</code> 

<code>
* launch a popup next to the control
ctrl = atWindow:'.EF_FOR'
itemSize = @ctrl->Size
xPos = ( itemSize<1> + itemSize<3>)  ; * x + width
yPos = ( itemSize<2> )               ; * y

override = ""
override<pRow$> = yPos
override<pCol$> = xPos
ans = popup(atWindow, override, 'EMP')
If ans Then
     @ctrl->DefProp = ans
     Send_Event(ctrl,'LOSTFOCUS')
end
</code>