PageRenderTime 38ms CodeModel.GetById 10ms RepoModel.GetById 0ms app.codeStats 0ms

/AutoHotkey.docset/Contents/Resources/Documents/objects/Functor.htm

https://gitlab.com/ahkscript/Autohotkey.docset
HTML | 78 lines | 70 code | 7 blank | 1 comment | 0 complexity | 4fcf65cd45a4e635ba0b04c9c8ae645f MD5 | raw file
    

  1. <!DOCTYPE HTML>
    2. 

  2. <html>
    3. 

  3. <head>
    4. 

  4. <title>Function Objects</title>
    5. 

  5. <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    6. 

  6. <meta http-equiv="X-UA-Compatible" content="IE=edge">
    7. 

  7. <link href="../static/theme.css" rel="stylesheet" type="text/css" />
    8. 

  8. <script src="../static/content.js" type="text/javascript"></script>
    9. 

  9. </head>
    10. 

  10. <body>
    11. 

  11. 

  12. <h1>Function Objects</h1>
    13. 

  13. 

  14. <p>"Function object" usually means any of the following:</p>
    15. 

  15. <ul>
    16. 

  16.   <li>A reference to a <a href="Func.htm">Func object</a>, which represents an actual <a href="../Functions.htm">function</a>; either built-in or defined by the script.</li>
    17. 

  17.   <li>A user-defined object which can be called like a function.  This is sometimes also referred to as a "functor".</li>
    18. 

  18.   <li>Any other object which can be called like a function, such as a <a href="#BoundFunc">BoundFunc object</a> or a JavaScript function object returned by a COM method.</li>
    19. 

  19. </ul>
    20. 

  20. <p>Function objects can be used with the following:</p>
    21. 

  21. <ul>
    22. 

  22.   <li><a href="../commands/Gui.htm#label">Gui control events</a> (g-labels)</li>
    23. 

  23.   <li><a href="../commands/Hotkey.htm#Functor">Hotkey</a></li>
    24. 

  24.   <li><a href="../commands/Menu.htm#Functor">Menu</a></li>
    25. 

  25.   <li><a href="../commands/OnClipboardChange.htm">OnClipboardChange()</a></li>
    26. 

  26.   <li><a href="../commands/OnExit.htm">OnExit()</a></li>
    27. 

  27.   <li><a href="../commands/OnMessage.htm">OnMessage()</a></li>
    28. 

  28.   <li><a href="../commands/SetTimer.htm#Functor">SetTimer</a></li>
    29. 

  29. </ul>
    30. 

  30. 

  31. <h2 id="User-Defined">User-Defined</h2>
    32. 

  32. <!-- TODO: Explain how a user-defined object could be useful -->
    33. 

  33. <p>User-defined function objects should follow this general pattern:</p>
    34. 

  34. <pre>class YourClassName {
    35. 

  35.     Call(a, b) {  <em>; Declare parameters as needed, or an <a href="../Functions.htm#Variadic">array*</a>.</em>
    36. 

  36.         <em>;...</em>
    37. 

  37.     }
    38. 

  38.     __Call(method, args*) {
    39. 

  39.         if (method = "")  <em>; For <a href="../Functions.htm#DynCall">%fn%()</a> or fn.()</em>
    40. 

  40.             return this.Call(args*)
    41. 

  41.         if (IsObject(method))  <em>; If this function object is being used as a method.</em>
    42. 

  42.             return this.Call(method, args*)
    43. 

  43.     }
    44. 

  44.     <em>;...</em>
    45. 

  45. }
    46. 

  46. </pre>
    47. 

  47. <p>Exactly which parts are needed depends on the usage:</p>
    48. 

  48. <ul>
    49. 

  49.   <li><code>method</code> is an empty string if the script used <code><a href="../Functions.htm#DynCall">%this%()</a></code> or <code>this.()</code>.</li>
    50. 

  50.   <li>If the object is being used as a method, <code>IsObject(method)</code> is true and <code>method</code> contains a reference to the target object. For example, if <code>x.y</code> refers to <code>this</code> function object, <code>x.y()</code> &rarr; <code>this[x]()</code> &rarr; <code>this.__Call(x)</code> &rarr; <code>this.Call(x)</code>.</li>
    51. 

  51.   <li><span class="ver">[v1.1.20+]:</span> If the object is being used by one of the built-in functions which accept a callback function, such as OnMessage or SetTimer, only the Call method is needed.</li>
    52. 

  52. </ul>
    53. 

  53. <p>The work can also be done directly in __Call. However, having __Call redirect to Call is recommended to ease the transition to AutoHotkey v2, which will change the behaviour of <code>%this%()</code> and method calls to call the Call method directly.</p>
    54. 

  54. 

  55. <h2 id="BoundFunc">BoundFunc Object <span class="ver">[v1.1.20+]</span></h2>
    56. 

  56. <p>Acts like a function, but just passes predefined parameters to another function.</p>
    57. 

  57. <p>There are two ways that BoundFunc objects can be created:</p>
    58. 

  58. <ul>
    59. 

  59.   <li>By calling the <a href="Func.htm#Bind">Func.Bind()</a> method, which binds parameter values to a function.</li>
    60. 

  60.   <li>By calling the <a href="../commands/ObjBindMethod.htm">ObjBindMethod()</a> function, which binds parameter values and a method name to a target object.</li>
    61. 

  61. </ul>
    62. 

  62. <p>BoundFunc objects can be called as shown in the example below. No other methods are supported. When the BoundFunc is called, it calls the function or method to which it is bound, passing any bound parameters followed by any which were passed by the caller. For example:</p>
    63. 

  63. <pre>fn := Func("RealFn").Bind(1)
    64. 

  64. 

  65. %fn%(2)    <em>; Shows "1, 2"</em>
    66. 

  66. fn.Call(3) <em>; Shows "1, 3"</em>
    67. 

  67. 

  68. RealFn(a, b) {
    69. 

  69.     MsgBox %a%, %b%
    70. 

  70. }</pre>
    71. 

  71. <p><a href="../commands/ObjBindMethod.htm">ObjBindMethod()</a> can be used to bind to a method when it isn't possible to retrieve a reference to the method itself.  For example:</p>
    72. 

  72. <pre>file := FileOpen(A_ScriptFullPath, "r")
    73. 

  73. getLine := ObjBindMethod(file, "ReadLine")
    74. 

  74. MsgBox % %getLine%()  <em>; Shows the first line of this file.</em></pre>
    75. 

  75. <p>For a more complex example, see <a href="../commands/SetTimer.htm#ExampleClass">SetTimer</a>.</p>
    76. 

  76. 

  77. </body>
    78. 

  78. </html>
    79. 

  79.