A GUI-based User Prompt Function

Topic
The IDL language has two built-in routines designed to facilitate the task of inviting one-line text entries: 

a) READ, which turns the IDL> command line into a prompt for user entries, and 

b) CW_FIELD, which is a user prompt component that can be inserted into other widget programs. 

The READ approach has a bit of a primitive look to it, and limited user-friendliness, while using CW_FIELD requires a knowledge of widget programming, which many IDL programmers may not have. This Help Article presents a simple utility for inviting one-line user text entries, which can be called with just one line of code from either non-GUI or GUI-based programs. The code for this utility can either be copied and pasted from the text below, or downloaded from the link right above.

Discussion
'gui_prompt.pro' is essentially a top-level WIDGET_BASE wrapper and event handler for IDL's built-in CW_FIELD function. It allows CW_FIELD to be a stand-alone prompting tool. With syntax like:

userEntry = GUI_PROMPT('Enter value here: ', $
    TITLE='Input any real number', $
    XSIZE=30, XOFFSET=100, YOFFSET=100, $
    VALIDATE_TYPE=size(0.0, /TYPE))
; The VALIDATE_TYPE syntax above is for real numbers

it will bring up on the user's screen a small GUI like the one below.

This dialog box will block further IDL processing until the user presses the 'Enter' key or hits the dialog window close button. Upon closing, the function returns the user's entry as a string datatype.

The source code for this function is displayed below, or you can download the code via this link: 'gui_prompt.pro'.

Solution

; The event handler
PRO gui_prompt_event, event
widget_control, event.id, GET_VALUE=userEntry, GET_UVALUE=pReturnValue
*pReturnValue = userEntry
widget_control, event.top, /DESTROY
END

; The widget creation code
FUNCTION gui_prompt, promptText, $
    TITLE=windowTitle, VALIDATE_TYPE=datatype, XSIZE=nCharacters, $
    XOFFSET=xoffset, YOFFSET=yoffset, _EXTRA=_extra
if n_elements(promptText) eq 0 then return, ''
; Optional keyword for validating user entries. The values are based
; on IDL type ID's as seen in table in Online Help for SIZE function.
if keyword_set(datatype) then begin
    switch datatype of
    1:    ; Integer types
    2:
    3:
    12:
    13:
    14:
    15: begin
        validateLong = 1
        break
    end
    4:    ; floating-point types
    5: begin
        validateReal = 1
        break
    end
    else: returnValue = ''    ; default type is /STRING
    endswitch
endif
if n_elements(windowTitle) eq 0 then winTitle = 'Entry Form'
device, GET_SCREEN_SIZE=displayDims
; By default, center the prompt (approximately) on the display
if n_elements(xoffset) eq 0 then xoffset = displayDims[0] / 2
if n_elements(yoffset) eq 0 then yoffset = displayDims[1] / 2
; By default, set the entry textbox width to 20
if n_elements(nCharacters) eq 0 then nCharacters = 20
tlb = widget_base(TITLE=windowTitle, XOFFSET=xoffset, YOFFSET=yoffset)
pReturnValue = ptr_new(/ALLOCATE_HEAP)
wPromptBox = cw_field(tlb, TITLE=promptText, FLOATING=validateReal, $
    LONG=validateLong, UVALUE=pReturnValue, $
    /RETURN_EVENTS, XSIZE=nCharacters, _EXTRA=_extra)
widget_control, tlb, /REALIZE
xmanager, 'gui_prompt', tlb
if n_elements(*pReturnValue) eq 0 $
    then returnValue='' $
else $
    returnValue = strtrim(*pReturnValue, 2)
ptr_free, pReturnValue
return, returnValue
END