9.2 Common Dialogs

GoFiler Legato Script Reference

Legato v 1.5b

Application v 5.24b

Table of Contents	< < Previous	Next >>

Chapter Nine — Dialog Functions (continued)

9.2 Common Dialogs

9.2.1 Introduction

Common dialogs allow for a unified, consistent interface between the user and a script for performing basic, common operations, including querying the user for a file to open, presenting printing options, and prompting the user where to save a file. Common dialogs are modal dialogs with their appearance and behavior controlled by the script engine. While this limits their customizability, it enhances the ease of their use.

9.2.2 Message Box Functions

Message box function allow for the presentation of simple message boxes without having to design a dialog and supporting code. Message box functions are as follows:

9.2.3 Password Functions

Password box function allow for the presentation and querying passwords using simple dialog boxes without having to design a dialog and supporting code. Password box functions are as follows:

9.2.4 Browse Function Overview

File browse functions allow the selection of folders and files by the user for common file actions, such as opening a file, closing a file, and saving a file. Legato offers common dialogs for these purposes: BrowseFolder, BrowseOpenFile, BrowseOpenFiles, and BrowseSaveFile.

9.2.5 Filters

Filters allow only certain types of files (by the extension) to be viewed in a browse dialog. They are formed as follows: a description and a list with a delimiter to express multiple filters.

My File Type *.dog|*.dog;*.k9

The description is separated from the actual filter by a vertical bar (‘|’) character. Multiple filters for the same type are separated by semicolon (‘;’). To have more than one filter option, use an ampersand (‘&‘) to connect each filter:

All Files *.*|*.*&My File Type *.dog|*.dog;*.k9

Failure to format filters correctly will result in functions supporting a filter list to fail, and in these cases, the GetLastError function will return ERROR_SYNTAX. Note that when the automatic parameter extension is added to certain functions, the filter list should contain an ‘all files’ *.* to allow for extensions not within the provided scope.

9.2.6 Path Scoping

Browse functions can be path scope restricted. In other words, the user can be prevented from opening or saving files except to specific locations. The BrowseAddOpenScope and BrowseAddSaveScope functions set allowed paths for open and save functions, respectively. A scope can also be cleared.

Scoping functions do not impact low-level file access primitives such as opening, read and writing. Rather, scoping restricts the location of files when the user accesses them through the common browse functions.

On user interfaces that allow file selection without use of a browse functions such as from a text edit control, whether called from the application or from a script, the dialog must be manually coded restrict the location scope of the selected file.

In some cases, scope settings need to be ignored. For example, a dialog that needs to access areas of the system not related to document production or processing. Generally, if the programmer wants to completely lock down the application, it must restrict functions that adjust settings and check any area that allows manual entry.

Save and open, each has its own scope list. If the state is not set (particularly when selecting a folder location), the ‘explore’ mode is employed which combines the open and save scopes. As such, if a scope is not set for one mode, the explore path will be left unrestricted.

9.2.7 Path Substitution

The application supports a number of substitution groups such that as paths are added, the programmer does not have to translate paths. These are as follows:

	Term		Description

	%AppPath%		Application area.
	%DesktopPath%		User desktop folder.
	%DocumentsPath%		User ‘Documents’ or ‘My Documents’ folder.
	%ProjectPath%		The project path.
	%MyProjectsPath%		The specified location is for project folders.
	\\%NetworkBrowse%\		This is not a substitution but rather a term to be used by the places and folder areas of browse dialogs. Adding a specific UNC to the scope will not present a network neighborhood.

In addition to the above, Windows environment variables can be substituted using the ExpandEnvironmentalStrings function.

9.2.8 File Browse Functions

Table of Contents	< < Previous	Next >>

© 2012-2024 Novaworks, LLC. All rights reserved worldwide. Unauthorized use, duplication or transmission prohibited by law. Portions of the software are protected by US Patents 10,095,672, 10,706,221 and 11,210,456. GoFiler™ and Legato™ are trademarks of Novaworks, LLC. EDGAR® is a federally registered trademark of the U.S. Securities and Exchange Commission. Novaworks is not affiliated with or approved by the U.S. Securities and Exchange Commission. All other trademarks are property of their respective owners. Use of the features specified in this language are subject to terms, conditions and limitations of the Software License Agreement.