CallFunction - Learn To Code - PlayBASIC Documentation

CallFunction

CallFunction FunctionName$,[Parameter1, Parameter2....]

Parameters:

FunctionName$ = Name of the function, you can also use the FunctionIndex of the function.

Returns: NONE

     CallFunction command allows us to execute a user function or psub's within our program by name or by FunctionIndex.

      To call a function we must provide CallFunction with either the name of the function or the index of the function (See FunctionIndex). This is to be followed by any input parameters the function expects. These must match the functions parameter types, if not, the call is unlikely to be successful.

      This type of functionality tends to pop up when we need to write code that's going to be used between many projects, while still remaining generic. One example usage that comes to mind, would be when writing a GUI library. This would allow GUI could be written to call a particular user defined action(s), without having to modify the library code all the time.

      For example, if the GUI detected a button click, the GUI could check if the button has an associated function (something the designer could to do at design time). This GUI function could then call the code that react to this button click. So the programmer wouldn't have to explicitly add code to react to the each button click

      Another situation could be in collision detection. If each object had a user associated 'destroy function', then the collision code could be simplified into a more generic version. This would allow the programmer to add more object types and destroy methods, without having to patch them into all the collision routines. So basically CallFunction can act as a type of call back mechanism.

FACTS:

* CallFunction can only pass Integer,Float,String and Pointers in PlayBASIC V1.64N3

* CallFunction only supports passing Array handles when calling Psubs PlayBASIC V1.64N3

* CallFunction can't currently handle return values in PlayBASIC V1.64n3

Mini Tutorial:

This example sets up an string array that will contain our list of function names. Then at run time, we can pass these names to CallFunction to execute the function on demand.

  Print "Dynamic Function Calling"
  Dim FunctionNames$(1)

; Store the function names in array,
; so we can select which function to call
  FunctionNames$(0)="Yeah"
  FunctionNames$(1)="SubYeah"

  Do

   ; clear the screen
     Cls

   ; Run through and the call functions
     For lp=0 To 1
        Name$=FunctionNames$(lp)
        CallFunction Name$,Rnd(100),Rnd#(200),Name$
     Next

     Sync
  Loop


Function  Yeah(x,y#,Name$)
  Ink $ff0000
  Print "Running Function ["+Name$+"]"
  Print x
  Print y#
  Ink $ffffff
EndFunction



Psub  SubYeah(x,y#,Name$)
  Ink $00ff00
  Print "Running Psub ["+Name$+"]"
  Print x
  Print y#
  Ink $ffffff
EndPsub

Attached Example:

This attached example builds a simple GUI frame work around the concept of call backs using callFunction.

Example Source: Download This Example

;*=-----------------------------------------------------------------------------=*
;
;                                             >> Action Based GUI  <<
;
;                                  By Kevin Picone
;
;                            Built Using PlayBASIC V1.64n2
;
;                  Copyright 2012 by Kevin Picone, All Rights Reserved.
;
;*=-----------------------------------------------------------------------------=*
;                                   www.UnderwareDesign.com  -  www.PlayBASIC.com
;*=-----------------------------------------------------------------------------=*
;
; About:
; ======
;
;   This example using the Action GUI library demos a how the GUI can use
; CallFunction to call user defined code on demand.   Action GUI is really
; simple, so simple it only creates basic window/panels object.    Each panel
; is given Class Name, the GUI uses the class name to hook back into user code
; for that class.
;
;   Each class has four basic action functions associated with it, those being
; CREATE, DELETE, REDRAW and UPDATE.   So if the user creates a window with a
; class name  of "TEST", then the GUI would expect to find Functions
; TEST_CREATE, TEST_DELETE TEST_REDRAW and TEST_UPDATE.   The Create and
; Delete functions are called when the use the NewWindow or DeleteWindow
; functions.  These let us customize the  newly created window, where the Update
; function is called  when the is mouse Over / input stuff and the redraw is
; when we want to repaint the window.

;    Bellow, we've got a simple randomized scene with a bunch of windows, where
; each window has it's own backdrop colours, with a click-to-position circle.
; If you  look closely at the code, the "GadgetWindow" class inherits from
; the GUI_WINDOW type.  This means we're adding fields to the GUI_WINDOW
; structure, basically customizing it.  The GUI can't see these extra fields,
; since they don't exist as far as it's concerned.  But we can access them
; inside the Action functions as need be. Here i'm just getting the pointer
; and away we go.
;
;
; Controls:
; ========
;
;               Mouse = Clicks render /position
;       ESC = EXIT
;
;*=-----------------------------------------------------------------------------=*






  // ---------------------------------------
  // Create a Gadget Window
  // ---------------------------------------
  index = NewWindow("GadgetWindow",370,200)
  PositionWindow(Index,200,50)


  // ---------------------------------------
  // Spawn a bunch of windows of "GadgetWindow" type
  // ---------------------------------------
  For lp=0 To 10

   ; randomly calc a size and position for  this new window panel
     Width     =RndRange(100,300)
     Height=RndRange(100,200)
     Xpos     =Rnd(800-Width)
     Ypos     =Rnd(600-Height)

     ThisWindow = NewWindow("GadgetWindow",Width,Height)
     PositionWindow(ThisWindow,Xpos,Ypos)

  Next





; *=----------------------------------------------------------------------=*
; *=----------------------------------------------------------------------=*
;      *=---------------------- MAIN LOOP ---------------------------=*
; *=----------------------------------------------------------------------=*
; *=----------------------------------------------------------------------=*

  SetFPS 60

  Do
     Cls $203060

     RenderWindows()

     // query what panel we're over (if any.  zer0 = screen)
     //Index=FindWindowUnderPoint(MouseX(),MouseY())
     //print Index

     Sync
  Loop

  End



; *=----------------------------------------------------------------------=*
; *=----------------------------------------------------------------------=*
;         *=--------------- GADGET WINDOW CLASS --------------------=*
; *=----------------------------------------------------------------------=*
; *=----------------------------------------------------------------------=*

  // Each window has it's own variables
  Type GadgetWindow As GUI_Window

     // Backdrop
     BackDropColour(4)

     // coords of some thing that is to be positioned by left clicks
     // on the window
     CircleX
     CircleY
     CircleSize
     CircleColour
  EndType


; *=----------------------------------------------------------------------=*
; *=----------------------------------------------------------------------=*
;         *=---------------------- CREATE ---------------------------=*
; *=----------------------------------------------------------------------=*
; *=----------------------------------------------------------------------=*
;
;    Here we're  pulling a bit of swifty and inserting our own
; replacement structure interited from GUI_Windows Structure.
;
;    The Create function is called twice. Before the GUI creates it own
; structure and then after it's set up the default fields.
;
; *=----------------------------------------------------------------------=*

Psub GadgetWindow_Create(Index)

  // Initial Allocation
  If GUI_WIndows(Index)=0
     GUI_WIndows(Index)=New GadgetWindow
  Else

     // Secondary allocation (setup)
     Dim Me As GadgetWindow Pointer
     Me=GetMePointer(Index)

     For lp =0 To 3
        me.BackdropColour(lp)=RndRGB()
     Next


     me.CircleSize     =RndRange(10,20)
     me.CircleColour=RndRGB()


     RenderToImage Me.Image
     ShadeBox 0,0,Me.Width,Me.Height,me.BackdropColour(0),me.BackdropColour(1),me.BackdropColour(2),me.BackdropColour(3)
     Text 0,0,Me.Name$+" "+Str$(Me.Index)

  EndIf

EndPsub


; *=----------------------------------------------------------------------=*
; *=----------------------------------------------------------------------=*
;         *=---------------------- DELETE ---------------------------=*
; *=----------------------------------------------------------------------=*
; *=----------------------------------------------------------------------=*


Psub GadgetWindow_Delete(Index)

  // Delete any media or extra stuff you've created for use in this window
  Dim Me As GadgetWindow Pointer
  Me=GetMePointer(Index)

EndPsub



; *=----------------------------------------------------------------------=*
; *=----------------------------------------------------------------------=*
;         *=---------------------- RENDER ---------------------------=*
; *=----------------------------------------------------------------------=*
; *=----------------------------------------------------------------------=*


Psub GadgetWindow_Render(Index)

  Dim Me As GadgetWindow Pointer
  Me=GetMePointer(Index)

  RenderToImage Me.Image
  ShadeBox 0,0,Me.Width,Me.Height,me.BackdropColour(0),me.BackdropColour(1),me.BackdropColour(2),me.BackdropColour(3)
  Text 0,0,Me.Name$+" "+Str$(Me.Index)

  If Me.mb
     CircleC Me.CircleX,Me.CircleY,me.CircleSize,true,me.CircleColour
  EndIf


EndPsub



; *=----------------------------------------------------------------------=*
; *=----------------------------------------------------------------------=*
;         *=---------------------- UPDATE ---------------------------=*
; *=----------------------------------------------------------------------=*
; *=----------------------------------------------------------------------=*


Psub GadgetWindow_Update(Index)

  Dim Me As GadgetWindow Pointer
  Me=GetMePointer(Index)

  If Me.mb

     #Print "on click"

     // set the
     Me.CircleX = Me.MX
     Me.CircleY = Me.MY

     Me.repaint =true
  EndIf


EndPsub


Related Info:	FunctionExist \| FunctionIndex :