Navigation: Templates > Template Language Reference > Annotated Examples > Control Template: DOSFileLookup >====== Control Template: DOSFileLookup ====== | |
The DOSFileLookup Control template adds an ellipsis (…) button which leads the end user to a standard Open File dialog. You can specify a file mask, and a return variable to hold the end user's choice.
#CONTROL(DOSFileLookup,'Lookup a DOS file name'),WINDOW,MULTI
CONTROLS
BUTTON('…'),AT(,,12,12),USE(?LookupFile)
END
#BOXED('DOS File Lookup Prompts')
#PROMPT('&File Dialog Header:',@S60),%DOSFileDialogHeader,REQ,DEFAULT('Choose File')
#PROMPT('&DOS FileName Variable:',FIELD),%DOSFileField,REQ
#PROMPT('D&efault Directory:',@S80),%DOSInitialDirectory
#PROMPT('&Return to original directory when done.',CHECK),%ReturnToOriginalDir,AT(10)
#PROMPT('&Use a variable to specify the file mask(s).',CHECK),%DOSVariableMask,AT(10)
#ENABLE(%DOSVariableMask)
#PROMPT('Vari&able Mask Value:',FIELD),%DOSVariableMaskValue
#ENDENABLE
#ENABLE(NOT %DOSVariableMask)
#PROMPT('F&ile Mask Description:',@S40),%DOSMaskDesc,REQ,DEFAULT('All Files')
#PROMPT('Fi&le Mask',@S50),%DOSMask,REQ,DEFAULT('*.*')
#BUTTON('More Fil&e Masks'),MULTI(%DOSMoreMasks,%DOSMoreMaskDesc&'-'&%DOSMoreMask)
#PROMPT('File Mask Description:',@S40),%DOSMoreMaskDesc,REQ
#PROMPT('File Mask',@S50),%DOSMoreMask,REQ
#ENDBUTTON
#ENDENABLE
#ENDBOXED
#LOCALDATA
DOSDialogHeader CSTRING(40)
DOSExtParameter CSTRING(250)
DOSTargetVariable CSTRING(80)
#ENDLOCALDATA
#ATSTART
#DECLARE(%DOSExtensionParameter)
#DECLARE(%DOSLookupControl)
#FOR(%Control),WHERE(%ControlInstance = %ActiveTemplateInstance)
#SET(%DOSLookupControl,%Control)
#ENDFOR
#IF(NOT %DOSVariableMask)
#SET(%DOSExtensionParameter,%DOSMaskDesc & '|' & %DOSMask)
#FOR(%DOSMoreMasks)
#SET(%DOSExtensionParameter,%DOSExtensionParameter & '|' & %DOSMoreMaskDesc &|
& '|' & %DOSMoreMask)
#ENDFOR
#END
#ENDAT
#AT(%ControlEventHandling,%DOSLookupControl,'Accepted')
IF NOT %DOSFileField
#INSERT(%StandardValueAssignment,'DOSTargetVariable',%DOSInitialDirectory)
ELSE
DOSTargetVariable = %DOSFileField
END
#INSERT(%StandardValueAssignment,'DOSDialogHeader',%DOSFileDialogHeader)
#IF(%DOSVariableMask)
DOSExtParameter = %DOSVariableMaskValue
#ELSE
DOSExtParameter = '%DOSExtensionParameter'
#ENDIF
#IF(%ReturnToOriginalDir)
IF FILEDIALOG(DOSDialogHeader,DOSTargetVariable,DOSExtParameter,FILE:KeepDIR)
#ELSE
IF FILEDIALOG(DOSDialogHeader,DOSTargetVariable,DOSExtParameter,0)
#ENDIF
%DOSFileField = DOSTargetVariable
DO RefreshWindow
END
#ENDAT
This starts, as all Control templates must, with a #CONTROL statement. The WINDOW attribute allows you to populate it onto a window, but not onto a report. The MULTI attribute specifies that the template may be populated multiple times ontothe same window. The CONTROLS section pre-defines the BUTTON control for the window.
The #BOXED structure places a box around all the prompts that display on the Actions tab for this Control template. The first #PROMPT asks for the text for the caption of the Open File dialog, and the next asks for the name of a variable to receive the end user's choice. The third allows you to explicitly set the directory in which the Open File dialog starts.
The fourth #PROMPT is a check box asking whether the program should return to the directory from which it started from the Open File dialog. The fifth #PROMPT is a check box asking whether the programmer will explicitly set the file mask(s) for the Open File dialog, or use a variable to determine them at run time. When checked, the first #ENABLE activates the Variable Mask Value #PROMPT to get the name of the variable toi use at run time. If not checked, the second #ENABLE activates its set of prompts to get each explicit file mask to pass to the Open File dialog.
The #LOCALDATA section defines three local variables that generate automatically as part of the procedure. These local variables are only used in the code generated by this Control template as the actual variables passed as parameters to the FILEDIALOG procedure.
The #ATSTART statement begins a section of template code that executes before any source code generates for the procedure. This means it is only appropriate to initialize user-defined template symbols and perform any necessary set up to generate correct source for the control template into the procedure. This section does not generate source code. The #DECLARE statements declare two symbols used only during source generation for this Control template.
#FOR(%Control),WHERE(%ControlInstance=%ActiveTemplateInstance) executes the enclosed #SET statement only for the single control populated by this Control template. The #SET statement then places the field equate label of the control into %DOSLookupControl.
The #IF structure checks whether the programmer checked the Use a Variable to specify the file mask(s) box and if not, sets up the specific file masks the programmer chose to pass to the FILEDIALOG procedure. The #ENDAT statement terminates the #ATSTART section.
The next #AT generates Clarion code into the embed point for the Accepted event for the control populated by this Control template to perform the file lookup. The IF NOT %DOSFileField structure detects whether the user has performed the lookup. If they haven't the initial directory is assigned to the DOSTargetVariable. If the user has performed the lookup, the ELSE clause assigns the result of the previous lookup as the starting point for the next.
The #INSERT statement creates assignment statements to initialize the File Open dialog's title. Next, the #IF(%DOSVariableMask) conditionally generates an assignment to initialize the file mask to pass to the File Open dialog.
The #IF (%ReturnToOrigianlDir) generates the correct IF FILEDIALOG structure performs the actual lookup for the file, either to return to the original directory or not. If the user selects a file from the File Open dialog, the selected filename is assigned to variable the user selected in the DOS FileName Variable prompt, then he DO RefreshWindow statement ensures that all data on the window is current. The #ENDAT statement terminates the #AT section.