UDN
Search public documentation:

UnrealScriptDelegates


Interested in the Unreal Engine?
Visit the Unreal Technology site.

Looking for jobs and company info?
Check out the Epic games site.

Questions about support via UDN?
Contact the UDN Staff

UnrealScript Delegates

Applies to: CodeDrop versions 831 and above.

Original author was Jack Porter (EpicGames). Wiki cleanup by Vito Miliano (UdnStaff).

Introduction

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.

Using Delegates

Declaring a delegate

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

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 );
    }

Assigning a delegate to point to a function

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.

Advanced

Delegates and deleted objects

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.

Declaring a body to a delegate

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.

Calling delegates from C++

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().