Stony Brook Modula-2 archive
(***************************************************************************)
(* *)
(* Copyright (C) 1992-2003 *)
(* by Stony Brook Software *)
(* *)
(* All rights reserved. *)
(* *)
(***************************************************************************)
DEFINITION MODULE BasicDialogs;
(* This module provides a host of basic dialogs common for various
simple tasks where it would be useful to have something that is
ready to go without the need for writing code.
The parent window of all dialogs is the value returned by
DlgShell.GetDialogParent()
*)
(* about threads
Win32 - you may use the GUI features in a fully multi threaded
manner.
Gtk - Only one thread, the main thread, may use the GUI features.
*)
<*IF StonyBrook THEN*>
<*/NOPACK*>
(* a hack so we can do editing and compiling for syntax of Mac code
using our compiler. *)
<*/VALIDVERSION:MAC*>
%IF p1 %THEN(*how we signal compiling Mac code*)
<*/NOVERSION:WIN32*>
<*/VERSION:MAC*>
%END
<*ELSIF p1 THEN*>
<*ASSIGN (AlignModelPPC, TRUE)*>
<*DEFINE (MAC, TRUE)*>
<*ELSE*>
fix me
<*END*>
FROM WinShell IMPORT
FontInfo, PrintDriverInfo;
TYPE
MessageTypes = (MsgInfo,
MsgQuestion,
MsgWarning,
MsgAppError,
MsgException);
PromptListWidth = (NormalListWidth, WideListWidth);
VAR
MessageTitle : ARRAY [0..79] OF CHAR;
(* The title bar for all basic dialogs not specifically specifying a title *)
(* the parent of all basic dialogs is DlgShell.GetDialogParent() *)
<*IF StonyBrook THEN*>
%IF DLL %THEN
<*/EXPORTALL/PROPAGATEEXCEPTIONALL/COPYATTRIBUTES*>
%END
<*END*>
PROCEDURE MessageBox(mess : ARRAY OF CHAR; msgType : MessageTypes);
(* displays mess in a system message box
the message box will have a single "ok" button
carriage return/line feeds are allowed in the string and are
correctly processed.
msgType determines what type of ICON and sound are used when the
message box is displayed.
The MsgException type also displays the exception address in the dialog.
*)
PROCEDURE MessageBoxId(mess : CARDINAL; msgType : MessageTypes);
(* mess is a string resource identifier specifying the string
to load from the resource and display in the message box.
See MessageBox
*)
PROCEDURE YesNo(prompt : ARRAY OF CHAR; default : CHAR) : CHAR;
(* displays the prompt in a message box
the message box will have a "yes" and "no" buttons
if default = "Y" then the yes button will be the default button when
the dialog opens otherwise the no button will be the default
upon return the function will return "Y" or "N"
"Y" is returned if the yes button is pressed
"N" is returned if the no button is pressed
*)
PROCEDURE YesNoId(prompt : CARDINAL; default : CHAR) : CHAR;
(* prompt is a string resource identifier specifying the string
to load from the resource and display in the message box.
See YesNo
*)
PROCEDURE YesNoCancel(prompt : ARRAY OF CHAR;
default : CHAR) : CHAR;
(* displays the prompt in a message box
the message box will have a "yes", "no" and "cancel" buttons
if default = "Y" then the yes button will be the default button when
the dialog opens, if default = "N" then the no button will be the default
otherwise the cancel button will be the default button
upon return the function will return "Y", "N" or "C"
"Y" is returned if the yes button is pressed
"N" is returned if the no button is pressed
"C" is returned if the cancel button is pressed
*)
PROCEDURE YesNoCancelId(prompt : CARDINAL; default : CHAR) : CHAR;
(* prompt is a string resource identifier specifying the string
to load from the resource and display in the message box.
See YesNoCancel
*)
PROCEDURE OkCancel(prompt : ARRAY OF CHAR;
default : CHAR;
msgType : MessageTypes) : CHAR;
(* displays the prompt in a message box
the message box will have a "ok" and "cancel" buttons
if default = "O" then the ok button will be the default button when
the dialog opens otherwise the cancel button will be the default button
upon return the function will return "O" or "C"
"O" is returned if the ok button is pressed
"C" is returned if the cancel button is pressed
msgType determines what type of ICON and sound are used when the
message box is displayed.
*)
PROCEDURE OkCancelId(prompt : CARDINAL;
default : CHAR;
msgType : MessageTypes) : CHAR;
(* prompt is a string resource identifier specifying the string
to load from the resource and display in the message box.
See OkCancel
*)
PROCEDURE OpenBusyBox(prompt : ARRAY OF CHAR) : BOOLEAN;
(* opens a modeless dialog box.
A return value of FALSE signifies failure.
the dialog can display a single line of text, prompt, of a limited length.
this is generally used when your application is performing a lengthy
operation.
*)
PROCEDURE OpenBusyBoxId(prompt : CARDINAL) : BOOLEAN;
(* prompt identifies a string resource to retrieve the text to be
displayed in the dialog.
See OpenBusyBox
*)
PROCEDURE CloseBusyBox;
(* close a previously opened busy box dialog *)
PROCEDURE PromptString(prompt : ARRAY OF CHAR;
VAR INOUT response : ARRAY OF CHAR) : BOOLEAN;
(* open a modal dialog with a single edit field and a text label
for the edit field contained in "prompt".
the string value in "response" will be preloaded into the edit field on entry.
RETURNs TRUE if the user clicked "OK" to close the dialog, ottherwise FALSE.
on return "response" contains the users entered text.
*)
PROCEDURE PromptStringId(prompt : CARDINAL;
VAR INOUT response : ARRAY OF CHAR) : BOOLEAN;
(* prompt identifies a string resource to retrieve the text to be
displayed in the dialog.
See PromptString
*)
PROCEDURE PromptPassword(prompt : ARRAY OF CHAR;
VAR INOUT response : ARRAY OF CHAR) : BOOLEAN;
(* same as the PromptString dialog except the text the user enters
will be "greeked" and not be visible to anyone to looking at the screen.
the string value in "response" will be preloaded into the edit field on entry.
RETURNs TRUE if the user clicked "OK" to close the dialog, ottherwise FALSE.
*)
PROCEDURE PromptPasswordId(prompt : CARDINAL;
VAR INOUT response : ARRAY OF CHAR) : BOOLEAN;
(* prompt identifies a string resource to retrieve the text to be
displayed in the dialog.
See PromptPassword
*)
PROCEDURE PromptCard(prompt : ARRAY OF CHAR;
min, max : CARDINAL;
allowZero : BOOLEAN;
VAR INOUT response : CARDINAL) : BOOLEAN;
(* open a modal dialog with a single edit field and a text label
for the edit field contained in "prompt".
returns TRUE if the user enters a valid number and presses OK
otherwise FALSE
the edit field is preloaded with the number in response on entry.
the number entered is contained in response on return of TRUE.
min and max provide range checking for the number entered.
if allowZero = TRUE then the number zero will be allowed even if outside
the allowed number range. This can be used to allow the user to enter a
"null" value.
*)
PROCEDURE PromptCardId(prompt : CARDINAL;
min, max : CARDINAL;
allowZero : BOOLEAN;
VAR INOUT response : CARDINAL) : BOOLEAN;
(* prompt identifies a string resource to retrieve the text to be
displayed in the dialog.
See PromptCard
*)
PROCEDURE PromptListStr(prompt : ARRAY OF CHAR;
VAR INOUT list : ARRAY OF CHAR;
listSep : CHAR;
VAR INOUT selStr : ARRAY OF CHAR;
listWidth : PromptListWidth) : BOOLEAN;
(* open a modal dialog with a single list box and a text label
for the list field contained in prompt.
returns TRUE if the user selects an item in the list and presses OK,
or double clicks a list item.
otherwise FALSE is returned.
the item selected is contained in selStr. The value is the text of
the item in the list.
the list of items is contained in the parameter 'list'. Each item in the
list is separated by the character listSep. The parameter list must be
null terminated.
If on entry selStr contains a value that matches an item in the list
then that item will initially be selected, otherwise no item will be
initially selected.
listWidth specifies the size of the list box. Choose an appropriate size
depending on the length of the list item strings.
The list box will display a scroll bar when necessary.
*)
PROCEDURE PromptListStrId(prompt : CARDINAL;
VAR INOUT list : ARRAY OF CHAR;
listSep : CHAR;
VAR INOUT selStr : ARRAY OF CHAR;
listWidth : PromptListWidth) : BOOLEAN;
(* prompt identifies a string resource to retrieve the text to be
displayed in the dialog.
See PromptListStr
*)
PROCEDURE PromptListIndex(prompt : ARRAY OF CHAR;
VAR INOUT list : ARRAY OF CHAR;
listSep : CHAR;
VAR INOUT selIndex : CARDINAL;
listWidth : PromptListWidth) : BOOLEAN;
(* as PromptListStr except you specify the selection by position in the
list starting with the value zero. Therefore the first item in the
list has a value of zero and the second one, and so on.
MAX(CARDINAL) signifies no selection
*)
PROCEDURE PromptListIndexId(prompt : CARDINAL;
VAR INOUT list : ARRAY OF CHAR;
listSep : CHAR;
VAR INOUT selIndex : CARDINAL;
listWidth : PromptListWidth) : BOOLEAN;
(* prompt identifies a string resource to retrieve the text to be
displayed in the dialog.
See PromptListIndex
*)
PROCEDURE PromptOpenFile(VAR INOUT name : ARRAY OF CHAR;
filters : ARRAY OF CHAR;
VAR INOUT defFilter : CARDINAL;
defDir : ARRAY OF CHAR;
defExt : ARRAY OF CHAR;
title : ARRAY OF CHAR;
createable : BOOLEAN) : BOOLEAN;
(* Opens an operating system common dialog for opening a file.
filters specifies a list of file extension filters.
The format for filters is as follows.
Title,null,filters,null {Title,null,filters,null} null
where filters can be one or more file filters each separated by semicolons.
Example...
assume the '|' character is the null character.
"Reports|*.rpt|Html|*.htm;*.html|All|*||"
defFilter = the filter to initially display, 1 based.
on return this is the index of the filter the user selected.
defDir = the default directory to start the dialog in
an empty string "" means use the current directory.
Mac - this parameter is not supported. the system remembers the last directory
used in an application.
defExt = the default file extension to use if the user does not
provide an extension. "" means no default extension.
the extension should *not* have a leading '.' character.
title = the caption text of the dialog. title can be empty "".
in this case the default operating system title is used.
If createable = TRUE then the file need not already exist, otherwise
the file must exist for the dialog to return successful.
Mac - this parameter is not supported. createable is always FALSE.
the file choosen must always exist.
RETURNs TRUE if successful and name will contain the file specification
for the file the user has given.
*)
<*IF MAC THEN*>
PROCEDURE SetSaveFileCreatorAndType(fileCreator, fileType : ARRAY OF CHAR);
(* The systeem File Save As common dialog wants the file type and creator
fields. use this API to set those values before calling PromptSaveAsFile *)
<*END*>
PROCEDURE PromptSaveAsFile(VAR INOUT name : ARRAY OF CHAR;
filters : ARRAY OF CHAR;
VAR INOUT defFilter : CARDINAL;
defDir : ARRAY OF CHAR;
defExt : ARRAY OF CHAR;
title : ARRAY OF CHAR) : BOOLEAN;
(* As PromptOpenFile except this dialog is for saving a file. *)
TYPE
FontOptions = (FixedPitchOnly, ScalableOnly, NoStyle, NoSize);
FontOptionSet = PACKEDSET OF FontOptions;
PROCEDURE PromptChooseFont(VAR INOUT font : FontInfo;
opt : FontOptionSet) : BOOLEAN;
(* opens an operating system common dialog for selecting a font.
RETURNs TRUE if successful and font will then contain the information
describing the font the user selected. otherwise returns FALSE
FixedPitchOnly if set will limit the font selections to fixed pitch
fonts.
ScalableOnly if set will limit the font selections to scalable fonts. No bitmap fonts.
NoStyle if set will not allow the user to select a font style
such as Bold, Italic, etc..
NoSize if set will not all the user to select a font point size
*)
TYPE
PrintInfo =
RECORD
fromPage : CARDINAL; (* in out *)
toPage : CARDINAL; (* in out *)
minPage : CARDINAL; (* in *)
maxPage : CARDINAL; (* in *)
copies : CARDINAL; (* in out *)
selected : BOOLEAN; (* in out *)
duplex : BOOLEAN; (* out *)
collate : BOOLEAN; (* in out *)
driverInfo : PrintDriverInfo; (* in out *)
END;
PROCEDURE PromptPrint(VAR INOUT info : PrintInfo) : BOOLEAN;
(* opens an operating system common dialog for selecting a printer and
various printer options for a specific print job.
info contains the information to initialize the dialog fields
an to also return the user entered information.
Returns TRUE if the user does not cancel the dialog. In this case you
continue by performing the print action the user has specified.
*)
(*
fromPage - initializes the dialog with the starting page to print, and upon
return contains the starting page to print entered by the user.
Normally initialized with 1. See toPage.
toPage - initializes the dialog with the ending page to print, and upon
return contains the ending page to print entered by the user.
If this value is initialized with 0 then the user will not be allowed
to select a page range to print and no value is returned.
minPage - Only valid if toPage is initialized with a non zero value.
The minimum page number the user will be allowed to enter in
fromPage and toPage.
maxPage - Only valid if toPage is initialized with a non zero value.
The maximum page number the user will be allowed to enter in
fromPage and toPage.
copies - The number of copies to be printed. Normally initialized with a value
of 1. Upon return the number of copies the user wants printed.
If the printer driver supports multiple copies you will never
reveive a value other than 1 upon return.
selected - If TRUE the user will be allowed to select if the current
"selection" is to be printed, otherwise the entire document is
assumed. Upon return TRUE means that the user wants only the
selection to be printed.
duplex - Upon return if TRUE the document is to be printed two sided. This
value can only be true if the printer supports duplex printing.
collate - If initialized with TRUE then the user will be allowed to select
collated printing when printing multiple copies, otherwise they
will not be allowed to make such a selection. Upon return the
multiple copies of the document must be printed in a collated manner.
It is up to you to do this since the printer driver does not have
support doing this. If the printer driver supports collation you
will never receive a value of TRUE.
driverInfo - This value may be initialized with NIL or a previously obtained
value from PromptPrintSetup or this procedure.
See PromptPrintSetup
*)
PROCEDURE PromptPrintSetup(VAR INOUT info : PrintDriverInfo) : BOOLEAN;
(* opens an operating system common dialog for setting up a printer and
various custom printer options.
Normally you will have a global variable that is initialized with a value
of NIL and thereafter use that value. In this way your application will
remember settings the user has made and not force them to reenter them
every time they want to print.
This value is usually passed to PromptPrint, although the user generally
also has access to printer setup from the print dialog as well.
*)
PROCEDURE GetPrintDriverInfo(printerName : ARRAY OF CHAR;
VAR OUT info : PrintInfo) : BOOLEAN;
(* this procedure allows you to get print information if you know the
system information detailing a printer driver
this procedure exists for an application to support the operating system
Print and PrintTo shell commands (right click and drag and drop). These
commands are for files that are registered with the operating system.
The operating system provides the first three parameters to you
in the Print and PrintTo commands.
If printerName = "" then the information for the default printer
is returned.
The function returns TRUE is successful
*)
END BasicDialogs.
© Norman Black, Stony Brook Software. Reproduced with permission.