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

UE3 Home > UnrealScript > UnrealScript Delegates

UnrealScript Delegates


Overview


A delegate 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.

Declaring a delegate


The first thing you need to do is declare 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 );

Delegate as function argument

In Unreal Engine 3 delegates can also be used as function arguments. You first need to declare a delegate as show above. Then you can use that declared delegate in a function like this:

   function DoStuff(delegate<OnClick> ClickDelegate)
   {
   }

A function with the same footprint as the declared delegate can be passed as argument when calling this function. For example:

   function MyOnClick( Button B, int MouseX, int MouseY )
   {
   }

   function CallFunction()
   {
       DoStuff(MyOnClick);
   }

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

Or in case of a function argument:

   function DoStuff(delegate<OnClick> ClickDelegate)
   {
       ClickDelegate(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();
    }

    event Initialized()
    {
        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.

Alternatively, you can assign the delegate in the defaultproperties{} block of the class, as follows:

    DefaultProperties
    {
        OKButton.OnClick=MyClick
        CancelButton.OnClick=MyClick
    }

You can also assign a delegate to None, which will cause the delegate to do nothing when called.

Delegates passed as function arguments can in turn be used to assign the delegate property in the class.

   function DoStuff(delegate<OnClick> ClickDelegate)
   {
       OKButton.OnClick = ClickDelegate;
   }

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.