 |
|
 |
|
|
|
Please take note! For mod developers working with Unreal Tournament 2003, this documentation is meant to be a starting point for your own explorations into UT2003, not a definitive guide. There will be differences between the documentation here and the product in your hands, and you may have to figure out quite a bit for yourself. Check out the Unreal Tournament 2003 page in the Unreal Powered area for links to community sites if you're having problems. UDN is a licensee support site, and cannot provide technical support or game-specific assistance to end users.
|
|
|
|
|
 |
UnrealScriptDelegates |
 |
|
|
|
|
|
Licensees can log in.
Interested in the Unreal engine? Check out the licensing page.
Questions about UDN itself? Contact the UDN Staff.
|
|
|
|
|
|
|
|
|
|
Applies to: Warfare versions 831 and above.
Original author was Jack Porter (EpicGames). Wiki cleanup by Vito Miliano (UdnStaff).
- UnrealScript Delegates
- Introduction
- Using Delegates
- Declaring a delegate
- Calling a delegate
- Assigning a delegate to point to a function
- Advanced
- Delegates and deleted objects
- Declaring a body to a delegate
- Calling delegates from C++
A delegates is a reference to a function bound to an object. This document describes how to use them in UnrealScript. Their main use is to provide a callback mechanism, for example to provide event notification in a user interface system.
The first thing you need to do is delcare the delegate. A delegate declaration looks similar to an event declaration. For example:
Class Button extends Window;
delegate OnClick( Button B, int MouseX, int MouseY );
Calling a delegate works just like calling a regular function:
Class Button extends Window;
var int MouseDownX, MouseDownY;
delegate OnClick( Button B, int MouseX, int MouseY );
function MouseDown( int MouseX, int MouseY )
{
MouseDownX = MouseX;
MouseDownY = MouseY;
}
function MouseUp( int MouseX, int MouseY )
{
if( MouseX == MouseDownX && MouseY == MouseDownY )
OnClick( Self, MouseX, MouseY );
}
To do something with a delegate, you need to assign a function to it. Usually this function is in another object. To assign a function reference to a delegate, the function declaration must have the exact same parameter types and return type (if any) as the delegate declaration. Here's an example:
Class MyDialogBox extends Window;
var Button OKButton, CancelButton;
function MyClick( Button B, int MouseX, int MouseY )
{
if( B == OKButton )
SaveDetails();
CloseWindow();
}
function Create()
{
OKButton = CreateWindow(class'Button', 40, 100, 64, 32 );
CancelButton = CreateWindow(class'Button', 120, 100, 64, 32 );
OKButton.Caption = "OK";
CancelButton.Caption = "Cancel";
OKButton.OnClick = MyClick;
CancelButton.OnClick = MyClick;
}
The last two lines of Create assign the OnClick delegates for both buttons to MyDialogBox's MyClick function. When the Button class' MouseUp function calls the OnClick delegate, MyDialogBox's MyClick functions will be called instead. Without delegates you'd have to subclass Button to implement this functionality.
You can also assign a delegate to None, which will cause the delegate to do nothing when called.
When you delete an Actor which a delegate references, and the delegate is called, the delegate will do nothing, as if it was assigned the value None.
In the case of non-actor Objects, a delegate reference acts just like a regular object reference and will prevent the object from being garbage collected. If you manually delete a non-actor Object without removing a delegate reference to one of its functions, a call to the delegate will cause a crash.
You can declare a body to a delegate, for example:
Class Button extends Window;
delegate OnClick( Button B, int MouseX, int MouseY )
{
Log("This is the default action");
}
If you call the OnClick delegate when it points to None, it'll execute the delegate's body. You can use this mechanism to provide a default action for the case where OnClick hasn't been assigned.
When you export an autogenerated EngineClasses.h type file for a package which has a native class with a delegate in it, a C++ stub function will be generated for the delegate (just like an event), to allow you to call it from C++. For the above examples, the C++ function would be named delegateOnClick().
|
|
