Office Assistant Package v3.25 |
Copyright © 1999-2003 Kambiz R. Khojasteh. All rights reserved.
The Office Assistant package has one non-visual component named TAssistant. Each instance of this component can manage one animated character (actor) and message boxes, hints and tips, and search balloons. The main features of TAssistant component are:
Office Assistant Package is built for Borland Delphi 3 and higher. Because Delphi 3 does not support bi-directional languages and variant variables, when using the package on this version of Delphi, consider the following notes:
To install the Office Assistant Package follow the procedure below:
Property Name | Data Type | Description |
ActorLibrary | String | Specifies the filename of the currently loaded actor library. |
ActorName |
String | Contains the actor's name of the currently loaded actor library. |
ActorVerInfo |
String | This property is an array of version informations for the currently loaded actor library. For example ActorVerInfo['Language'] returns language name of the actor. |
AlwaysOnTop | Boolean | Indicates wether the actor should be the top most window even when the application is not active. |
Animations |
TAnimation | This property is an array of animations data that indexed from 1 to AnimationCount. |
AnimationCount |
Word | Contains the number of animations in the currently loaded actor library. |
AutoIdle | Boolean | Controls whether the assistant plays the idle animations automatically. |
Balloon | TBalloonOptions | Contains the balloon properties. |
TColor | Specifies the border color of the balloon. | |
TColor | Specifies the background color of the balloon. | |
TFont | Controls the attributes of text written on the balloon. | |
TFont | Determines the font of buttons when the cursor is over them. | |
Class of TControl | Determines the control class that the component will use for displaying text labels. When this property set to something other than TLabel, OnAdjustCustomLabel event will fire to initialize properties of custom labels. | |
Boolean | Determines whether Office 2000 look is applied to balloons. | |
BalloonAnchor | TWinControl | Determines the form or windowed-control that the balloon attaches to it. When value of this property is not assigned, the anchor is the assistant. When Anchor item is not visible, balloon centeres to desktop and BalloonPos property sets to bpCenter. |
BalloonPos |
TBalloonPos | Indicates the position of the balloon relative to the BalloonAnchor form. |
BiDiMode | TBiDiMode | Specifies the bi-directional mode for the balloons and assistant's popup menu. |
BlockingMove | Boolean | When this property is true, call to MoveTo
method executes in main VCL thread. To move the actor asynchronously, set
this property to false. Note: When this property is true and assistant is moving, any attempt to show a modal balloon fails and the function immediately returns mrNone. |
BoundsRect | TRect | Indicates the bounding rectangle of the actor on the Windows desktop or DockSite. |
CustomDialog | TAssistantBalloon | Determines the form which will be used as custom balloon. By calling
ShowCustom or ShowCustomModal
methods the custom balloon will be displayed. To create a custom balloon
please follow the procedures below:
|
DockSite | TWinControl | Determines the form or windowed control, which
actor placed on it. When this property is not assigned, the actor will be
float on the Windows desktop. Note: Assistant's position is relative to DockSite. |
Draggable | Boolean | If set to true, the actor can be repositioned by dragging it. |
Dragging |
Boolean | While Dragging is true, the user is dragging the assistant window. |
Empty |
Boolean | Determines whether an actor library is loaded to the component. |
FastShowHide | Boolean | When this property is false, the assistant automatically plays SHOW and HIDE animations on changes in Visibile property. |
GuideDlg | TGuideDlgOptions | Contains the Guide balloon options. |
Boolean | If AcceptRequest is false, the edit box and search button will not be displayed on the Guide balloon. | |
String | Contains a short description about the found topics. | |
TIcon | Specifies an icon for the guide balloon. | |
String | Contains the requested search text entered by the user. | |
Boolean | Indicates whether topics are result of a user request's search or not. When RequestResult is true, topics will be displayed followed by a circle button, otherwise a bulb will be displayed instead of circle button. | |
String | Specifies the title of the Guide balloon. | |
TTopicsList | Specifies the list of found topics according to the user search request. | |
TGuideDlgButtons | Determines which button appear on the Guide balloon. | |
Height | Integer | Specifies the vertical size of the assistant in pixels. |
HintBulb | Boolean | Indicates whether a hint bulb appear beside the assistant. |
HintDlg | THintDlgOptions | Contains the Hint balloon options. |
String | Contains the hint itself or a short description about available hints. | |
TIcon | Specifies an icon for the Hint balloon. | |
String | Specifies the title of the Hint balloon. | |
TTopicsList | Specifies the list of available hint topics. | |
MaxIdleTime | Word | Determines the maximum time in milliseconds, which actor can stay freezed before playing an Idle animation. When AutoIdle is false, this property has no meaning. |
MinIdleTime | Word | Determines the minimum time in milliseconds, which actor can stay freezed before playing an Idle animation. When AutoIdle is false, this property has no meaning. |
ModalBalloon |
Boolean | If ModalBalloon is true, the visible balloon has been shown as modal. |
MoveStep | Byte | Specifies the amount of movements, in pixels, in every step of MoveTo method. |
MovingTo |
Boolean | Determines whether the actor is moving on the screen using a call to MoveTo method. |
MovingToSync |
Boolean | Determines whether the actor is moving on the screen using a call to MoveTo method as blocking move. When this property is true any attempt to show a modal balloon fails and the function immediately returns mrNone. |
MsgDlg | TMsgDlgOptions | Contains the Message balloon options. |
TCheckBoxOptions | Contains check box options. | |
Boolean | Determines whether check box can be in "grayed" state. | |
String | Specifies the display text of check box. | |
Boolean | Determines whether the check box appears checked. | |
Boolean | Determines whether the check box is enabled. | |
TCheckBoxState | Indicates whether the check box is selected, deselected, or grayed. | |
Boolean | Determines whether the check box is visible. | |
TIcon | When Type parameter of MessageDlg method is mtCustom, the balloon shows the icon specified by this property.. | |
String | Determines the title of the Message balloon. | |
Mute | Boolean | Controls whether the assistant makes sound. |
Name | String | Specifies the name of the assistant as referenced in code. |
PlayIdling |
Boolean | Indicates whether an idle animation is playing on the idle time. |
Playing |
Boolean | If Playing is true, indicates an animation is playing. |
PlayingID |
TRequestID | Identifies the ID of current playing animation |
PopupMenu | TPopupMenu | Identifies the pop-up menu associated with the assistant. |
Priority | TThreadPriority | Determines the priority of the animation sequencer thread. |
Showing |
Boolean | Indicates whether the is currently visible. This property is true when Visible property is true and the Empty property is false. |
Speed | Word | Specifies the relational speed of animations according to the original animation speed in percent. |
StageLeft | Integer | Specifies the horizontal coordinate of the left edge of the assistant window relative to the Windows desktop or DockSite. |
StageTop | Integer | Specifies the vertical coordinate of the top edge of the assistant window relative to the Windows desktop or DockSite. |
Tag | Integer | Stores an integer value as part of the component. |
TipsDlg | TTipsDlgOptions | Contains the Tips balloon options. |
Integer | Specifies the index of the current selected tip on the Tips balloon. | |
TStringList | Contains the list of tip strings. | |
TTipsDlgButtons | Determines which button appear on the Tips balloon. | |
Visible | Boolean | Determines whether the assistant should be visible. |
VisibleBalloon |
TBalloonKind | Indicates the kind of visible balloon. If balloon is not visible the value of this property is bkNone. |
Width | Integer | Specifies the horizontal size of the assistant in pixels. |
Methods |
procedure BringToFront; |
procedure CloseBalloon; Closes the current visible balloon. |
constructor Create(AOwner: TComponent); Creates and initializes a new TAssistant. |
destructor Destroy; Destroys an instance of TAssistant. |
function GestureAt(X, Y: Integer): TRequestID; Plays the gesture animation according to the screen coordinate specified by X and Y parameters. The function returns a unique id for played animation or zero on error. |
function GlanceAt(X, Y: Integer): TRequestID; Plays the glance animation according to the screen coordinate specified by X and Y parameters. The function returns a unique id for played animation or zero on error. |
procedure Hide(Fast: Boolean = False); Hides the assistant. If Fast is true, the hide animation will not play. |
function InputQuery(const ACaption, APrompt:
String; var Value: String): Boolean; Displays an input balloon that enables the user to enter a string. |
function IsJustPlayed(Actions:
TActorActions = []): Boolean; Returns true if one of the specified actions are just played but its return animation is not played, otherwise the function returns false. When set of Actions is empty, the function looks for any action, which is just played. |
function IsPlaying(Actions:
TActorActions = []): Boolean; If one of the specified actions are playing or waiting to play, the function returns true. When set of Actions is empty, the function looks for any playing action. |
function IsValid(RequestID: TRequestID):
Boolean; If the specified RequestID is playing or waiting to play, the function returns true. |
function LookAt(X, Y: Integer): TRequestID; Plays the look animation according to the screen coordinate specified by X and Y parameters. The function returns a unique id for played animation or zero on error. |
function MessageDlg(const
Msg: String; AType: TMsgDlgType; AButtons: TMsgDlgButtons; HelpCtx: LongInt):
Word; This function is as same as Delphi MessageDlg function except that this method shows a balloon. |
function MessageDlgDef(const
Msg: String; AType: TMsgDlgType; AButtons: TMsgDlgButtons; HelpCtx: LongInt;
DefButton: TMsgDlgBtn): Word; This function works as same as MessageDlg method except that this method has an extra parameter that determines which button has focus as default. |
procedure MoveBalloonTo(Point: TPoint); Moves the visible balloon to the specified point. |
procedure MoveBalloonToControl(Control: TControl); Moves the visible balloon over the specified control. |
procedure MoveBalloonToCursor; Moves the visible balloon to the mouse cursor's position. |
procedure MoveTo(X, Y: Integer); Moves the assistant to the specified coordinate of X and Y relative to DockSite and plays the approperiate animations. When BlockingMove is false, the procedure returns immediately. |
All versions: function Play(Action: TActorAction): TRequestID; Delphi 3: function PlayAction(Action: TActorAction): TRequestID; Plays randomly one of animations associated to the action. The function returns a unique id for played animation or zero on error. |
Delphi 4 and Higher: function Play(Index: Word): TRequestID; Delphi 3: function PlayIndex(Index: Word): TRequestID; Plays the animation specified by the animation's index. The function returns a unique id for played animation or zero on error. |
All versions: function Play(const Name: String): TRequestID; Delphi 3: function PlayName(const Name: String): TRequestID; Plays the animation specified by the animation's name. The function returns a unique id for played animation or zero on error. |
Delphi 4 and higher: |
function PlaySafe(Action:
TActorAction): TRequestID; Plays randomly one of animations associated to the action if there is no running animation or actor is playing an idle animation. Besides that, if the Action parameter is one of aaGetAttention, aaRead, or aaWrite, the function may convert them respectively to aaGetAttentionContinued, aaReadContinued, or aaWriteContinued actions to prevent jumping in actor sequences. The function returns a unique id for played animation or zero on error. |
procedure ResetIdle; Resets the ideling level to the first level and if it is neccessary, returns the assistant to rest pose state. |
procedure SetPosition(X,
Y: Integer); Moves the assistant to the specified coordinate of X and Y relative to DockSite without playing the approperiate animations. |
procedure Show(Fast: Boolean = False); Shows the assistant. If Fast is true, the show animation will not play. |
procedure ShowCustom; Shows the custom balloon. Custom balloon determines by CustomDialog property. |
function ShowCustomModal: Word; Shows the custom balloon as modal. Custom balloon determines by CustomDialog property. The retuned value is the modal result. |
procedure ShowHint; Shows the Hint balloon. |
function ShowHintModal: Word; Shows the Hint balloon as modal. The retuned value is the id or index of the selected hint topic. |
procedure ShowGuide; Shows the Guide balloon. |
function ShowGuideModal: Word; Shows the Guide balloon as modal. The retuned value is the id or index of the selected guide topic. |
procedure ShowTips; Shows the Tips balloon. |
procedure Speak(const Msg: String; Timeout:
Integer = 0); Shows a balloon containing the Msg and wait for timeout to hide the balloon. The timeout is in milliseconds and if it is zero the balloon will be hide only by calling the CloseBalloon method. |
procedure Stop(RequestID: TRequestID
= 0); Stops the specified animation if it is playing otherwise removes it from the queue. Zero RequestID passed as parameter means the current running animatin. |
procedure StopAll(Cut:
Boolean = False); Stops the current playing animation and empties the animation queue. When Cut is true, the return sequence of the stopped animation will not played. |
procedure Think(const Msg: String; Timeout:
Integer = 0); Shows a think balloon containing the Msg and wait for timeout to hide the balloon. The timeout is in milliseconds and if it is zero the balloon will be hide only by calling the CloseBalloon method. |
function WaitFor(RequestID:
TRequestID = 0): Boolean; Waits for specified animation until it stops to play. If the specified animation has an infinite loop, the function returns immediately with a false result. Zero RequestID passed as parameter means the current running animatin. |
function WaitForMove:
Boolean; Waits for an asynchronous call to MoveTo method. If a blocking move is running, the function returns immediately with false result. |
Event Name | Type | Description |
OnAdjustCustomLabel | TCustomLabelEvent | Occurs when a control class other than TLabel has been defined for LabelClass property of the component. Use this event for initializing properties of the new label control. For example, if the new control class has a word-wrap property, in this event set it to true. |
OnBalloonHide | TNotifyEvent | Occurs when the balloon hides. |
OnBalloonShow | TNotifyEvent | Occurs when the balloon shows. |
OnChange | TNotifyEvent | Occurs whenever the ActorLibrary changes. |
OnClick | TNotifyEvent | Occurs when the user clicks on the assistant. |
OnDblClick | TNotifyEvent | Occurs when the user double-clicks on the assistant. |
OnDragging | TNotifyEvent | Occurs when the user is dragging the assistant. |
OnDragStart | TNotifyEvent | Occurs when the user begins to drag the assistant. |
OnDragStop | TNotifyEvent | Occurs when the dragging of the assistant ends. |
OnGuideOptionsClick | TNotifyEvent | Occurs when the user clicks on the options button of the Guide balloon. |
OnGuideRequestChange | TNotifyEvent | Occurs when the user changes the text of the edit box on the Guide balloon. |
OnGuideSearchClick | TNotifyEvent | Occurs when the user clicks on the search button of the Guide balloon. |
OnGuideTopicClick | TTopicClickEvent | Occurs when the user clicks on the one of topics displayed on the Guide balloon. |
OnHide | TNotifyEvent | This event just triggered when the assistant goes to hide. |
OnHintBlubClick | TNotifyEvent | Occurs when the user clicks on the hint bulb. |
OnHintTopicClick | TTopicClickEvent | Occurs when the user clicks on the one of topics displayed on the Hint balloon. |
OnIdle | TIdleEvent |
This event triggered when the assistant needs to play an idle
animation. |
OnMoveStarts | TNotifyEvent | Occurs when just before the assistant begins to move on the screen.
This event occurs only by calling MoveTo method. Note: When BlockingMove is false, this event does not occur in the main VCL thread. |
OnMoveStop | TNotifyEvent |
Occurs when just before the assistant ends to move on the screen.
This event occurs only by calling MoveTo method. |
OnMoving | TNotifyEvent | Occurs when while the assistant is moving on the screen. This event
occurs only by calling MoveTo method. Note: When BlockingMove is false, this event does not occur in the main VCL thread. |
OnPlayStart | TPlayEvent | This event just triggered when an animation begins to play. Note: This event does not occur in the main VCL thread. |
OnPlayStop | TPlayEvent | This event triggered when an animation terminates. Note: This event does not occur in the main VCL thread. |
OnResize | TTNotifyEvent | Occurs immediately after the assistant is resized. |
OnShow | TNotifyEvent | This event just triggered when the assistant goes to show. |
OnTipsTipChange | TNotifyEvent | This event triggered after changing the current tip of the Tips balloon. |
Here, is a list of classes, type definitions, and constants that declared and used by Office Assistant package. The multi-language application developers can change string constants to the appropriate language.
Classes |
TTopicsList = class(TStringList); |
property Count: Integer; Determines the number of topics in the list. This property is read-only. |
property Strings [Index: Integer]: String; Contains list of topics' titles. |
property Options [Index: Integer]: TTopicOptions; Contains the list of topic options. |
constructor Create; Default constructor of the class. |
function Add(const S: String): Integer; Adds a new topic to end of the topic list. |
function AddOptions(const S: String; AOptions:
TTopicOptions): Integer; Adds a new topic to end of the topic list and set its options. |
function AddID(const S:
String; ID: Integer): Integer; Adds a new topic to end of the topic list and set its reference ID. |
function AddStyle(const S: String; AStyles:
TTopicStyles): Integer; Adds a new topic to end of the topic list and set its display style. |
function AddStyleID(const
S: String; AStyles: TTopicStyles;
ID: Integer): Integer; Adds a new topic to end of the topic list and set its display style and reference ID. |
procedure Assign(Source: TPersistent); Copies the contents of another topic list to the object where the method is executed. |
procedure Delete(Index: Integer); Deletes the topic with the specified index from the list of topics. |
procedure Clear; Deletes all topics from the list. |
TTopicOptions = class(TPersistent); |
property ID: Integer; Determines the ID of the topic. If this value is zero or a non-negative value, by selecting the topic the second parameter of OnGuideTopicClick or OnHintTopicClick events will be the topic ID otherwise index of the topic in the topics list will be used. |
property Styles: TTopicStyles; Determines the visual style of the topic item. |
property OnSelect: TTopicClickEvent; Occurs when user selects the topic. If this event is not assigned OnGuideTopicClick or OnHintTopicClick events will be called. |
Type Definitions | ||||||||||||||||||
TRequestID = Cardinal; This type holds a unique id for playing or queued animations. By this id you can stop an animation or wait until it be finished. The low order word of TRequestID contains animation's index. |
||||||||||||||||||
TBalloonKind =
(bkNone, bkMessage, bkTips, bkHint, bkGuide, bkSpeak, bkThink, bkQuery,
bkCustom
|
||||||||||||||||||
TBalloonPos = (bpCenter,
bpTopLeft, bpTopRight, bpRightTop, bpRightBottom, bpBottomRight, bpBottomLeft,
bpLeftBottom, bpLeftTop);
|
||||||||||||||||||
TExitType = (etNone,
etAnimation, etExitBranch);
|
||||||||||||||||||
TTipsDlgBtn = (tbClose,
tbNext, tbBack); TTipsDlgButtons = set of TTipsDlgBtn;
|
||||||||||||||||||
TGuideDlgBtn =
(gbClose, gbOptions, gbTips, gbSearch, gbBackPage, gbNextPage); TGuideDlgCmdBtn = gbClose..gbSearch; TGuideDlgNavBtn = gbBackPage..gbNextPage; TGuideDlgButtons = set of TGuideDlgCmdBtn;
|
||||||||||||||||||
THintDlgBtn = (hbClose,
hbBackPage, hbNextPage); THintDlgCmdBtn = hbClose..hbClose; THintDlgNavBtn = hbBackPage..hbNextPage; THintDlgButtons = set of THintDlgCmdBtn;
|
||||||||||||||||||
TQueryDlgBtn =
(qbClose, qbCancel); TQueryDlgButtons = set of TQueryDlgCmdBtn;
|
||||||||||||||||||
TActorAction =
(aaNone, aaAcknowledge, aaAlert, aaAnnounce, aaBlink, aaConfused, aaCongratulate,
aaDecline, aaDoMagic, aaDontRecognize, aaExplain, aaGestureDown, aaGestureDownLeft,
aaGestureDownRight, aaGestureLeft, aaGestureRight, aaGestureUp, aaGestureUpLeft,
aaGestureUpRight, aaGetAttention, aaGetAttentionContinued, aaGlanceDown,
aaGlanceDownLeft, aaGlanceDownRight, aaGlanceLeft, aaGlanceRight, aaGlanceUp,
aaGlanceUpLeft, aaGlanceUpRight, aaGreet, aaHear, aaHearing, aaHide, aaIdlingLevel1,
aaIdlingLevel2, aaIdlingLevel3, aaListen, aaListening, aaLookDown, aaLookDownLeft,
aaLookDownRight, aaLookLeft, aaLookRight, aaLookUp, aaLookUpLeft, aaLookUpRight,
aaMoveDown, aaMoveDownLeft, aaMoveDownRight, aaMoveLeft, aaMoveRight, aaMoveUp,
aaMoveUpLeft, aaMoveUpRight, aaPleased, aaProcess, aaProcessing, aaRead,
aaReadContinued, aaReading, aaRestPose, aaSad, aaSearch, aaSearching, aaShow,
aaSpeak, aaSpeaking, aaStartListening, aaStopListening, aaSuggest, aaSurprised,
aaThink, aaThinking, aaUncertain, aaWave, aaWrite, aaWriteContinued, aaWriting);
TActorActions = set of TActorAction; The ActorAction is a predefined identifier for animations of an actor library. Each animation may be assigned to one or more ActorAction and vice versa. |
||||||||||||||||||
TAnimation = record Name: String[255]; Actions: TActorActions; case ExitType: TExitType of etNone: (); etAnimation: (ReturnName: String[255]); etExitBranch: (); end; end; This record holds specifications of the animation. |
||||||||||||||||||
TTopicStyle = (tsHeader,
tsUnderline, tsBold, tsItalic, tsHoverUnderline, tsHoverBold, tsHoverItalic); TTopicStyles = set of TTopicStyle;
|
||||||||||||||||||
TCustomLabelEvent
= procedure(Sender: TObject; TheLabel: TControl) of object; This is type of OnAdjustCustomLabel event. TheLabel parameter is the new created label control that you may want to initialize its properties. |
||||||||||||||||||
TIdleEvent = procedure(Sender:
TObject; Level: Integer; var Handled: Boolean) of object; This is type of OnIdle event. Level parameter Indicates the level of idling and is a value between 1 and 3. If you want to ignore the default handler, set Handled parameter to true. |
||||||||||||||||||
TPlayEvent = procedure(Sender:
TObject; RequestID: TRequestID) of object; This is type of OnPlayStart and OnPlayStop events. RequestID is the unique id of the played or stopped animation. |
||||||||||||||||||
TTopicClickEvent
= procedure(Sender: TObject; TopicID: Integer) of Object; This is type of OnGuideTopicClick and OnHintTopicClick events. If ID of the selected topic is negative, TopicID parameter refers to the index of the topic otherwise it is its ID. |
Constants |
DefMsgDlgBtns
: array [TMsgDlgBtn] of String = ('&Yes', '&No', '&OK', 'Cancel', '&Abort',
'&Retry', '&Ignore', 'All', This constant contains the caption of Message balloon buttons. |
DefTipsDlgBtns
: array [TTipsDlgBtn] of String = ('Close', '&Next',
'&Back'); This constant contains the caption of Tips balloon buttons. |
DefGuideDlgBtns
: array [TGuideDlgBtn] of String = ('Close',
'&Options', '&Tips', '&Search', This constant contains the caption of Guide balloon buttons. |
DefHintDlgBtns
: array [THintDlgBtn] of String = ('&OK', This constant contains the caption of Hint balloon buttons. |
DefQueryDlgBtns
: array [TQueryDlgBtn] of String = ('&OK', 'Cancel'); This constant contains the caption of Input Query balloon buttons. |
The Actor Library is a DLL file with .aal extension that stores the assistant's actor definitions and animations. Each actor has a set of animations that may be assigned to one or more predefined actions and vice versa. Each animation has one or many frames and each frame may be had a sound. Some animation after stop needs to another animation so that returns the actor to its original state (RestPose). Return animations may be created as a separate animation or may be defined by exit branches in the first animation. Each actor has at least one animation assigned to its RestPose action.
Actor libraries can be used as compressed. ASPack is an exe compressor
that has been tested for compressing actor libraries and works great. You could
download ASPack from http://www.aspack.com.
Thanks to Bill Miller for giving
me this information.
Note: Office Assistant Package needs at least one Actor Library. You can find some actor libraries at Office Assistant's Page.
On my web site there is a simple editor for creating actor libraries. Unfortunately this editor does not have help file or documentation and needs Delphi command line compiler (DCC32.EXE) to build libraries.
The Office Assistant Package is provided "AS IS" without any warranty of any kind, either express or implied. The entire risk as to the quality and performance of the software is with you. The author is not liable for any damages resulting from the use and misuse of the software.
The Office Assistant Package is freeware. You may copy it as long as you copy all of files. If you want to change the source code in order to improve the components' features, performance, etc. please send to the author the new source code so that the author can have a look at it. The changed source code should contain descriptions what you have changed, and your name. The only thing you may not change is the original copyright information.
If you have any bug reports, suggestions, or comments please post a topic in my forum at http://www.delphiarea.com/forum. You can also visit Office Assistant's web page at http://www.delphiarea.com/products/assistant to find out about the latest updates or to download the actor libraries.
|