home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Garbo
/
Garbo.cdr
/
mac
/
source
/
dialgmgr.sit
/
Dialog.Doc
< prev
next >
Wrap
Text File
|
1990-01-04
|
20KB
|
613 lines
Dialog - A Very-High Level Dialog Manager
Version 1.0 1/5/90
Copyright 1986-1990 Stackhouse Software
Introduction
Dialog is a series of objects and methods to manage a dialog. In addition to
simple dialog items such as buttons, radio items, and check boxes, support is
provided for the following:
- Drawing the bold oval around the default button.
- Groups of radio items, boxed with titles at top or on side of group.
- PopUp Menus.
- Adjusting PopUp Menus to align with a StaticText items.
- Adjusting List Items to exactly display a given number of items.
- Items in a scrolling list.
- User Items.
- Keyboard equivalents for any radio item, check box, or button.
- Change the cursor over to an I-Beam when over EditText items.
- Managing update events when dialogs or windows overlap the dialog.
Complex dialogs can be displayed and information retrieved from them with
a few simple lines of source code. While Dialog uses Object-Oriented techniques
in its' implementation, the interface is a simple and can be used in any
existing program without even modifiying the event loop.
Dialog is written using Think's Pascal 2.0 and contains about 2200 lines of
code which compiles into between 3K and 10K bytes of code. The size of the code
depends on which Dialog features are selected using compile time options. The
complete source files are included. Also included is a sample program (source,
project, and resource).
Dialogs is shareware and may be used in other shareware without royalty as
long as credit is given. I will attempt to answer questions and accept bug
reports by either E-Mail or US Mail. The shareware fee is $35. Please send
checks to:
Bill Stackhouse
13 Sawin Street
Natick, MA 01760
------------------------------------------------------------------------------
This manual is divided into 3 parts:
Installation and Compilation
Description of Types
Description of Procedures
Complete Interface Definition
[note this document is formatted using Monaco 9pt with tabs set for 4 spaces.]
------------------------------------------------------------------------------
Installation and Compilation
Dialog is a collection of source programs. They should be placed in a folder
separate from the source for a program being developed to allow sharing
among several projects. Under the Project menu in Think's Pascal 2.0, specify
the options that are required. The values should be TRUE or FALSE; For Example:
UserListItem=TRUE;
If a value is not defined, it defaults to FALSE. If a feature is not used, the
source for it may be omitted from the project. All Dialog source may be
compiled with the debug/name/range/overflow options set without ill effect.
Those locations in the source that would otherwise cause a problem, have the
options explicitly turned off.
The source file(s) which use Dialog must have TObject, and TDialogs in the
uses statement. (TObject should be the name of the unit that defines TObject).
The compiler options are:
UseUserItem
UseListItem
UsePopUpMenu
UseTextGroup
UseKeyGroup
UseRadioGroup
The order of the source programs in the project are:
-- File -- -- Notes --
Object.p required, but may use any object named TObject with
a procedure named Free with no parameters.
KeyGroup.p optional
PopUpMenu.p optional
RadioGroup.p optional
StringDB.p optional, required if UseListItem = TRUE
ListItem.p optional
TextGroup.p optional
UserItem.p optional
Centered.p required
Dialogs.p required
------------------------------------------------------------------------------
Sample Program Fragment
var
theDialog: TDialog;
new(ListDialog);
theDialog.Init;
theDialog.Define(2001, [10], 12);
theDialog.RadioGroup(6, [5, 6, 7], 'Color', FALSE);
theDialog.RadioGroup(8, [8, 9], 'Age', TRUE);
theDialog.TextGroup(11, 3);
theDialog.PopMenu(Nil, 2000, 16, 2);
theDialog.KeyButton(CHR(ReturnCode), OK);
theDialog.KeyButton(CHR(EnterCode), OK);
theDialog.KeyButton('o', OK);
theDialog.KeyButton('.', Cancel);
theDialog.ItemListText('Natick');
theDialog.ItemListText('Boston');
theDialog.ItemListText('Cambridge');
theDialog.ItemListText('Salem');
theDialog.ItemListText('Seattle');
theDialog.ItemListText('Portland');
theDialog.ItemListText('San Diego');
theDialog.ItemListText('San Francisco');
theDialog.ItemListText('Marin');
theDialog.ItemListText('Orlando');
theDialog.Display(TRUE);
theItem := theDialog.Accept;
theDialog.ItemListGet(1, number, text);
theDialog.RadioGroupGet(1, number);
theDialog.RadioGroupGet(2, number);
theDialog.PopMenuGet(1, number, text);
theDialog.Free;
------------------------------------------------------------------------------
Description of Types
type DialogNumber
The numbers 1 to 255. 255 is the maximum number of items that a dialog may
have and be supported by Dialog.
type DialogSet
A set of DialogNumbers.
------------------------------------------------------------------------------
Description of Procedures
Procedure TDialog.Init;
Initializes all internal data structures; Should be called once after creating
dialog variable.
var theDialog : TDialog;
begin
new(theDialog);
theDialog.Init;
end;
Procedure TDialog.Define (
pNumber: Integer;
pChkDefault: DialogSet;
pTextDefault: DialogNumber);
Defines basic information for the dialog;
pNumber - the resource number of the dialog;
pChkDefault - a set of the check boxes that are initially checked.
pTextDefault - the number of the EditText box that is initially selected.
theDialog.Define (1000, [3,5,7], 12);
Procedure TDialog.Display (center: Boolean);
This procedure will display the dialog. It should be called after all items
and groups have been defined.
center - TRUE if the dialog is to be positioned in the center of the screen
horizontally and one-third down from the menu bar.
theDialog.Display (TRUE);
Function TDialog.Accept: Integer;
This procedure will wait for any button item to be pressed. The number of the
button pressed will be returned.
theItem := theDialog.Accept;
Function TDialog.Error: Integer;
This procedure will return the status of the last operation. The possible
errors are:
{ Return Codes }
DialogNoErr = 0; {all's well with the world}
DialogNotNumber = -1; {Edit/Static text item did not have a number in it}
DialogInvalidOp = -2; {Operation requested with support compiled out}
DialogInvalidItem = -3; {item type invalid for op. eg. GetString on a
{radio control}
DialogGroupIgnored = -10; {too many groups, key, menus, or user items were
{added}
IF theDialog.Error <> DialogNoErr THEN
foo;
Procedure TDialog.Free;
This procedure will remove the dialog from the screen and free all internal
data structures including the dialog. It should be called after retrieving
all values from the dialog.
theDialog.Free;
Procedure TDialog.RadioGroup (
pOn: DialogNumber;
pBtns: DialogSet;
pTitle: String;
pTitleTop: Boolean);
This procedure defines a group of radio items that will have only a single
item on at any time. Optionally the group may have a box drawn around them
and a title placed either at the top or the side of the group. There may not
be more than 15 radio groups in a dialog, additional groups will be ignored.
pOn - the radio item that is currently on.
pBtns - the set of radio items in the group.
pTitle - the title to be drawn with the box. If the title is a null string,
no box or title is drawn.
pTitleTop - if TRUE, the title is drawn at the top of the group. If FALSE,
the title is drawn at the side of the group.
theDialog.RadioGroup (white, [red, white, blue], 'Flag Colors', TRUE);
theDialog.RadioGroup (front, [front, side, back], '', TRUE);
IF theDialog.Error = DialogGroupIgnored THEN
foo;
Procedure TDialog.RadioGroupGet (
pGroup: Integer;
Var pItem: Integer);
After TDialog.Accept returns, this procedure will return the item number of
the radio item that was last on.
pGroup - the radio group number. The first group defined is number 1.
pItem - the actual item number.
Procedure TDialog.RadioGroupSetOn (
pGroup: Integer;
pItem: Integer);
This procedure will set an item on in a group. All other items in the group
will be off just as if one item in the group had been clicked on.
pGroup - the radio group number. The first group defined is number 1.
pItem - the actual item number.
theDialog.RadioGroupGet(1, theItem);
Procedure TDialog.TextGroup (
pBtn: DialogNumber;
pText: DialogNumber);
This procedure defines a relationship between a radio item or check box and
an EditText item. When the button is clicked on, the related EditText item is
selected. There may not be more than 15 text groups in a dialog, additional groups
will be ignored.
pBtn - the button item number.
pText - the EditText item number.
theDialog.TextGroup (5,8);
Procedure TDialog.PopMenu (
pMenu: MenuHandle;
pMenuRes: Integer;
pStatic: DialogNumber;
pNowOn: Integer);
This procedure defines a PopUp Menu that is associated with a StaticText item.
The PopUp Menu itself must not have a UserItem defined for it. The Menu Items
are defined as a standard resource. The StaticText item will be adjusted in
size to correctly align with a select menu item. The width of the rectangle
for the PopUp Menu will be determined by the width of the menu resource. There
may not be more than 15 PopUp Menus in a dialog, additional menus will be
ignored.
pMenu - the Handle to the menu. If it is nil, it will be read out of the
resource file.
pMenuRes - the resource number of the menu.
pStatic - the item number of the StaticText item associated with the menu.
pNowOn - the menu item number initially selected.
theDialog.PopMenu (menuHandle, 1000, 3, 1);
Procedure TDialog.PopMenuGet (
pGroup: Integer;
Var pItem: Integer;
Var pText: Str255);
After TDialog.Accept returns, this procedure will return the menu item number
of the menu item last selected and its text.
pGroup - the radio group number. The first group defined is number 1.
pItem - the menu item number. The first item is number 1.
pText - the menu item text.
theDialog.PopMenuGet (1, theItem, theText);
Procedure TDialog.PopMenuCallBack (pCallBack: ProcPtr);
This procedure defines a procedure which will be called each time any popup
menu for this dialog is accessed. No parameters are passed to the procedure.
It is assumed that the call back has access to the object for the dialog
and can call any of the procedures defined for TDialog.
theDialog.PopMenuCallBack(@callBack);
Procedure TDialog.UserItems (
pBtn: DialogNumber;
pDraw, pEvent, pSelect: ProcPtr;
pBox: Rect);
This procedure defines a UserItem. Call backs for drawing the item, processing
events for it, and selections are provided. There may not be more than 10 user
items in a dialog, additional items will be ignored.
pBtn - the item number.
pDraw -
pEvent -
pSelect -
pBox -
theDialog.UserItems (4, @draw, @event, @select, theBox);
Procedure TDialog.ItemList (
pBtn: DialogNumber;
pInitiallyOn: Integer;
pShown: Integer);
This procedure defines a scrollable list of items. The List should be defined
as a UserItem in the resource file but any rectangle will do. The rectangle
will be reduced by 16 pixels if it is necessary to show a scroll bar. The
rectangle will be adjusted vertically to insure that the requested number
of items will show. Because of the adjustments, the rectangle does not have
to be exactly right, only that enough space is provided. There may not be more
than 10 list items in a dialog, additional lists will be ignored.
pBtn - the item number.
pInitiallyOn - the item number of the initial item to be selected
(highlighted). The first item number is 1.
pShown - the maximum number of words to be shown at once.
theDialog.ItemList (5, 40, 6);
Procedure TDialog.ItemListText (pText: Str255);
This procedure will add a single item to the scrollable list. This must be
called after TDialog.ItemList and before TDialog.Display. If there is
insufficient memory to store the new item, it will be ignored and Error will
return the value DialogGroupIgnored. The group will be displayed with the
items that were successfully added.
pText - The text of the item to be added.
theDialog.ItemListText('Boston');
IF theDialog.Error = DialogGroupIgnored THEN {did it get added?}
foo;
Procedure TDialog.ItemListGet (
pGroup: Integer;
Var pItem: Integer;
Var pText: Str255);
After TDialog.Accept returns, this procedure will return the list item number
of the list item last selected and its text. The item only need to be clicked
on rather than double clicked. Multiple items may not be selected.
pGroup - the radio group number. The first group defined is number 1.
pItem - the list item number. The first item is number 1.
pText - the list item text.
theDialog.ItemListGet (1, theItem, theText );
Procedure TDialog.KeyButton (
pKey: char;
pItem: DialogNumber);
This procedure will define the relationship between a command/letter and any
check box, radio item, or button). Pressing CMD - letter while the dialog is
displayed will be the same as clicking on the item with the mouse. An item
may have several keyboard equivalents. There may not be more than 25 keyboard
equivalents in a dialog, additional pairs will be ignored.
pKey - the actual key. Case is not distinguished. 'A' is different than 'a'.
pItem - the item number to click on.
theDialog.KeyButton ('.', Cancel);
Function TDialog.GetBooleanValue (pItem: Integer): Boolean;
This function will return the value of a check box or radio after Accept
returns.
pItem - the Item number.
result - TRUE if the item is ON. If the item is not a check box or radio item
the result will be FALSE.
IF theDialog.GetBooleanValue (4) THEN
foo;
Function TDialog.GetLongintValue (pItem: Integer): Longint;
This function will return the numeric value of any EditText Item after Accept
returns.
pItem - the Item number.
result - the numeric value. If the item is not a Edit or Static item or does
not contain a number, the result will be 0 and Error will return
DialogInvalidItem or DialogNotNumber.
IF theDialog.GetLongintValue (6) = 25 THEN
foo;
Function TDialog.GetStringValue (pItem: Integer): Str255;
This function will return a string value of any EditText or StaticText Item
after Accept returns.
pItem - the Item number.
result - the string value. If the item is not a Edit or Static item the result
will be a null string and Error will return DialogInvalidItem
IF theDialog.GetStringValue (6) = 'Joe' THEN
foo;
Procedure TDialog.SetBooleanValue (
pItem: Integer;
pValue: Boolean);
This function will set the value of a check box or radio item prior to Display.
pItem - the Item number.
pValue - TRUE if the item is to be ON.
theDialog.SetBooleanValue (4, TRUE);
Procedure TDialog.SetLongintValue (
pItem: Integer;
pValue: Longint);
This function will set the numeric value of any EditText Item prior to Display.
pItem - the Item number.
pValue - the numeric value.
theDialog.SetLongintValue (6, 25);
Procedure TDialog.SetStringValue (
pItem: Integer;
pValue: Str255);
This function will set a string value of any EditText or StaticText Item prior
to Display.
pItem - the Item number.
pValue - the string value.
theDialog.SetStringValue (6, 'Joe');
Procedure TDialog.CenterText (pItem: Integer);
This function will display the text in an EditText centered.
pItem - the Item number.
theDialog.CenterText (6);
Procedure TDialog.SelectText (pItem: Integer);
This function will select the text in an EditText.
pItem - the Item number.
theDialog.CenterText (6);
------------------------------------------------------------------------------
Complete Interface Definition
const
DialogMaxItems = 255;
ReturnCode = 13; {ASCII code generated by Return and Enter keys. Note that}
EnterCode = 3; {this is good for any keyboard, no matter how it's mapped}
{ Return Codes }
DialogNoErr = 0; {all's well with the world}
DialogNotNumber = -1; {Edit/Static text item did not have a number in it}
DialogInvalidOp = -2; {Operation requested with support compiled out}
DialogInvalidItem = -3; {item type invalid for op. eg. GetString on a
{radio control}
DialogGroupIgnored = -10; {too many groups, key, menus, or user items were
{added}
type
DialogNumber = 0..DialogMaxItems;
DialogSet = packed set of DialogNumber;
TDialog = object(TObject)
fPrivate: Handle;
{ Init - initialize internal data structures }
{ Define - define basic information about dialog }
{ Display - show dialog }
{ Accept - process all event until any button item is pressed }
{ Error - returns error from last operation }
{ Free - take dialog window down, clean up internal data structures }
procedure TDialog.Init;
procedure TDialog.Define (pNumber: Integer; {dialog number}
pChkDefault: DialogSet; {which check boxes
default on}
pTextDefault: DialogNumber); {which editText to put I-
Beam}
procedure TDialog.Display (center: Boolean);
function TDialog.Accept: Integer;
function TDialog.Error: Integer;
procedure TDialog.Free;
override;
{ RadioGroup - define a group of related radio buttons which are
exclusive of each other }
{ RadioGroupGet - find which button in the group is on }
{ RadioGroupSetOn - set a button in the group }
procedure TDialog.RadioGroup (pOn: DialogNumber; {which is initially on}
pBtns: DialogSet; {which btns in a single group}
pTitle: string; {if length > 0, then title with box}
pTitleTop: Boolean); {TRUE - title on top, FALSE - title at left}
procedure TDialog.RadioGroupGet (pGroup: Integer;
var pItem: Integer);
procedure TDialog.RadioGroupSet (pGroup: Integer;
pItem: Integer);
{ TextGroup - a check box / TextEdit pair. When the check is on, the
edit is selected}
procedure TDialog.TextGroup (pItem: DialogNumber; {pairs of btn/edit text
{items}
pText: DialogNumber); {button item number}
{ PopMenu - define a popup menu relative to a StaticText item }
{ PopMenuGet - find which menu item is currently on along with text }
{ PopMenuCallBack - user call back when popup used. No parms passed back }
{ since obj known }
procedure TDialog.PopMenu (pMenu: MenuHandle; {nil or menu handle}
pMenuRes: Integer; {resource number}
pStatic: DialogNumber; {related StaticText item number}
pInitiallyOn: Integer); {menu item number initially on}
procedure TDialog.PopMenuGet (pGroup: Integer; {group number}
var pItem: Integer; {menu item number currently on}
var pText: Str255); {menu item text currently on}
procedure TDialog.PopMenuCallBack (pCallBack: ProcPtr); {proc addr}
{ UserItems - define a user item }
procedure TDialog.UserItems (pItem: DialogNumber; {user item number}
pDraw, pEvent, pSelect: ProcPtr; {draw/event/select call backs}
pBox: Rect); {Rect that contains the
item}
{ ItemList - define a single column scrollable list }
{ ItemListText - add a single row to the list }
{ ItemListGet - find which item and its' text was last clicked }
procedure TDialog.ItemList (pItem: DialogNumber; {item number}
pInitiallyOn: Integer; {item
initially selected}
pShown: Integer); {max items to show}
procedure TDialog.ItemListText (pText: Str255); {text single list item}
procedure TDialog.ItemListGet (pGroup: Integer; {group number}
var pItem: Integer; {list item number currently
selected}
var pText: Str255); {list item text currently
selected}
{ KeyButton - define keyboard equivalents }
procedure TDialog.KeyButton (pKey: char; {command key}
pItem: DialogNumber); {button}
{ General utilities to set and retrieve dialog item values }
function TDialog.GetBooleanValue (pItem: Integer): Boolean;
function TDialog.GetLongintValue (pItem: Integer): Longint;
function TDialog.GetStringValue (pItem: Integer): Str255;
procedure TDialog.SetBooleanValue (pItem: Integer;
theValue: Boolean);
procedure TDialog.SetLongintValue (pItem: Integer;
theValue: Longint);
procedure TDialog.SetStringValue (pItem: Integer;
theValue: Str255);
{ CenterText - center the displayed text in the EditText }
{ SelectText - select the entire text in the EditText box }
procedure TDialog.CenterText (pItem: Integer);
procedure TDialog.SelectText (pItem: Integer);
end;