# Common Dialog Windows

Common Dialog windows are predefined resources that can provide certain specialized functions in a simple to use way. Basically they are windows with controls in them and almost all the event processing is handled by Windows - from a programmers perspective this is an attractive attribute indeed! Examples of Common Dialogs are the "Open" and "Save as" windows that appear when a user wishes to graphically select a file name from disk to open or save a file. The Message Box is a special example of a Dialog window.
In ARWEN Common Dialog windows are Modal and never Modeless. An explanation of these terms is in order: A Modal window is one where the message loop handling of the owner application is suspended while the Modal window is in operation. A call is made to open the Modal window and doesn't return until the user closes the Modal window. An example of this is the Message Box window. The whole operation can be invoked in a single line which makes Modal Dialog windows very convenient. Although the normal message loop is interrupted with a Modal Dialog box ARWEN still enables the IDLE handler routine to keep operating. A Modeless window is a window that doesn't cause any interruption in the flow of the application message loop. The main window in an application is Modeless and any child windows would normally be too. ARWEN does not have an associated Resource Compiler that would enable it to fabricate Modeless Common Dialog windows and therefore major customisations to Dialog windows are not possible. However, minor customisations are possible for certain features of some Common Dialog windows when they are initialized. ARWEN allows access to these - see the specific calling routines for more details. Please note that MessageBox is a special dialog box not normally considered as part of the Common Dialog box group but I am showing it here since the implementation is essentially identical. Only one Common Dialog box can be open for operation at any one time with the exception of the Message Box dialog.
Copy

    global function messageBox(sequence title, sequence text, object style)

This dialog box was copied from the Euphoria distribution files. Basically, all I have done is alter the parameters order so that the title of the window is first and then the actual text of the window is placed second. The customary sequence of parameters was defined long ago by the Win32 API but it didn't seem logical to me so I changed it. Do you think I should change it back? I also tidied up the constants and added WarnErr(sequence text) and FatalErr(sequence text) routines.
title
This is the text string that will be displayed in the title bar of the window. It could be something like Error or Warning etc..
text
This is the message text that will be displayed in the window itself. You must insert '\n' characters where you want the line breaks to occur. Windows will automatically resize the dialog box to encompass the message.
style
Can be any combination of the following predefined constants:
MB_APPLMODAL User must respond before doing something else
MB_SYSTEMMODAL All applications suspended until user responds
MB_TASKMODAL Similar to MB_APPLMODAL
MB_TOPMOST
MB_DEFAULT_DESKTOP_ONLY
MB_DEFBUTTON1 First button is default button
MB_DEFBUTTON2 Second button is default button
MB_DEFBUTTON3 Third button is default button
MB_DEFBUTTON4 Fourth button is default button
MB_OK Message box contains one push button: OK
MB_OKCANCEL Message box contains OK and Cancel
MB_ABORTRETRYIGNORE Abort, Retry, Ignore
MB_YESNOCANCEL Message box contains Yes, No, and Cancel
MB_YESNO Message box contains Yes and No
MB_RETRYCANCEL Message box contains Retry and Cancel
MB_USERICON -- What's this for?
MB_ICONASTERISK
MB_ICONERROR
MB_ICONEXCLAMATION Exclamation-point appears in the box
MB_ICONHAND Same as MB_ICONERROR
MB_ICONINFORMATION Lowercase letter i in a circle appears
MB_ICONQUESTION A question-mark icon appears
MB_ICONSTOP Same as MB_ICONERROR
MB_ICONWARNING Same as MB_ICONEXCLAMATION
MB_RIGHT Windows 95: The text is right-justified
MB_RTLREADING Windows 95: For Hebrew and Arabic systems
MB_SERVICE_NOTIFICATION Windows NT: The caller is a service
MB_SETFOREGROUND Message box becomes the foreground window
MB_HELP Windows 95: Help button generates help event
One of the following values will be returned when the MessageBox is closed:
IDERROR -- FAILURE (constant doesn't exist)
IDOK -- OK button was selected.
IDCANCEL -- Cancel button was selected.
IDABORT -- Abort button was selected.
IDRETRY -- Retry button was selected.
IDIGNORE -- Ignore button was selected.
IDYES -- Yes button was selected.
IDNO -- No button was selected.
Copy

    global function getOpenFileName(integer id, sequence fName, sequence filters, object flags)
    global function getSaveFileName(integer id, sequence fName, sequence filters, object flags)

These Dialogs allows a user to navigate available disk drives to select a file to either 'open' or to 'save as'. Multiple files can be selected for getOpenFileName() by including the OFN_ALLOWMULTISELECT flag. This flag is ignored for getSaveFileName(). If the routine fails it will return NULL otherwise it returns the strings of the selection.
If one file is selected the return value will be { "path\name" }, eg: { "c:\Euphoria\bin\ex.exe" }.
If multiple files are selected then the return value will be { "path\", "nameFile1.ext", "namefile2.ext", .. }
id - ID of the owner window. You can have NULL in this field but the IDLE handler will not fire while the Dialog box is open.
fName - default name of the file to appear in the edit field of the Dialog.
filters - a sequence of paired strings in this form: {displayStr1, patternStr1, displayStr2, patternStr2...} eg, { "Text Files", "*.TXT", ... } To specify multiple filter patterns for a single display string, use a semicolon to separate the patterns, eg: "*.TXT;*.DOC;*.BAK" This field can contain a blank sequence if no filter patterns are required.
flags - any OR'ed combination of the following. Please note that other flags exist but are not supported by ARWEN. For a full description of each flag please refer to the Win32 API documentation.
OFN_ALLOWMULTISELECT -- User can select more than one file but, for some reason, old-style 'Open' dialogs have short directory names.
OFN_CREATEPROMPT
OFN_FILEMUSTEXIST
OFN_HIDEREADONLY
OFN_NOCHANGEDIR
OFN_NONETWORKBUTTON
OFN_NOVALIDATE
OFN_OVERWRITEPROMPT
OFN_PATHMUSTEXIST
OFN_READONLY
OFN_SHAREAWARE
OFN_SHOWHELP
If you need to separate the path, filename or file extension from the return results of these Dialog boxes then you can use extractPathAndName() and extractNameAndExtn().

Copy

    global function browseForFolder(sequence message)

`message` refers to any text information that you wish to display when the window opens. If this parameter is an empty string then no text message will be shown except what is in the title bar which always is "Browse for Folder" (or language equivalent).
This dialog box is a modal window used to visually select a directory (aka folder). If the function is successfull it will return the fully qualified path to the folder otherwise it will return an empty string.
Copy

    global function getChooseColor(integer id)

`id` is the window owner. If a non-Window control is specified the function will abort with a warning, otherwise a modal dialog-box is opened. If `id` is NULL then the dialog box will be modeless - just like another window. Be very careful if you want to try this last approach.
The Color dialog box enables the user to choose a predefined colour or specify their own. The function will return an integer specifying either a colour in RGB format or -1. Please note that the Red component occupies the lower 8 bits; the green component the next 8 bits and the Blue component the upper 8 bits.
In theory, the user could edit up to 16 custom colours that they might like to provide but if anyone wants this provision to be enabled then please contact me to discuss it.
Copy

    global function choosefont() -- NOT YET IMPLEMENTED

Copy

    global function pageSetup() -- NOT YET IMPLEMENTED

Copy

    global function printDlg() -- NOT YET IMPLEMENTED

Copy

    global function findText() -- NOT YET IMPLEMENTED, not sure if I want to anyway

Copy

    global function replaceText() -- NOT YET IMPLEMENTED, not sure if I want to anyway