User Button Gadget:      

  This gadget places buttons on your diagrams.  The buttons 
  become active during simulations.  When pressed, the buttons call
  your designated functions.  To place such a button in a diagram,
  instantiate a model in your diagram that contains the following
  function call:

	user_button( label, x, y, your_function, your_data );

  The label is a character string containing the word you wish
  to appear on the button, (ie. "on", "off").  

  The x and y values are the floating-point coordinate 
  offsets where you want to place the button on your diagram relative 
  to the box under which it is instantiated.  An x-y value of (0.0,0.0) 
  will place the button at the upper left corner of the box where it is 
  instantiated.  A value of (1.0,1.0) will place the button on the lower
  corner of the box.  Any value in between will place the button within
  the box.  Values less then 0.0, or greater than 1.0 will place the button
  outside the box from which it is instantiated.

  The your_function is the name of the function that you want
  to be called when the button gets pressed.  You should define this
  function within a DEFINE_GLOBAL: area.

  The your_data is a pointer to a structure that you wish to pass
  to your called routine.  For example, this could be used to determine 
  which of several buttons was pressed.


  For example:

	DEFINE_GLOBAL:

	 /* Prototype the standard function. */
	 void user_button( char *label, float x, float y, 
			   void *u_func, void *data );

	 /* Define your (user) function. */
	 void user_test( void *event, void *data )
	  {
	   char *msg=(char *)data;
	   printf("Button Pressed. '%s'\n", msg );
	  }

	END_DEFINE_GLOBAL.


	/* Define your box-model that contains some buttons. */
	DEFINE_DEVICE_TYPE:  Button_Box
	  char *msg;

	  DEFINE_THREAD: start_up
	  {
	   msg = strdup( "My Message" );
	   user_button( "Here", 0.1, 0.1, user_test, msg );
	   msg = strdup( "Your Message" );
	   user_button( "There", 0.1, 0.4, user_test, msg );
	  }
	 END_DEFINE_THREAD.

	END_DEFINE_DEVICE_TYPE.


  To try this example, you would create a diagram that instantiates
  a box of type Button_Box.  If you built and ran the simulation
  containing this example-model, you will see two buttons appear
  on the box;  one below the other, due to the y-offsets of 0.1 and 0.4.
  The labels on the buttons would be: Here and There.

  If you click the first button, it will call the function user_test
  which will print:
	
	Button Pressed. 'My message'
	
  in the text window, reflecting the value 10 being passed to it.

  If you click the second button, it will call the function user_test
  which will print:
        
        Button Pressed. 'Your message'
       
  in the text window, again, reflecting the value 20 being passed to it.

  You can establish any number of buttons, and they can call any number
  of functions that you define.

  In this example, a pointer to a character-string was passed.  However,
  you can pass a pointer to any other kind of structure instead.
  Such structures may contain multiple values - if needed.  (Be carefull
  to pass a pointer to a persistant structure.  For example, do not pass
  a pointer of a local variable which may not exist by the time the button is
  pressed. Also be careful to not accidently or prematurely free the pointer
  before the button is pressed.)  If you do not need to pass any data, just
  call the user_button function with 0 or NULL in the data parameter.

General Purpose Button Box Model -

There is a complete example in the user_contributed models directory, called generic_button_example.sim. It instantiates four buttons with test boxes. Pressing a button lights the box it is connected to. Try it by building and running it.