=======================
Parameter and functions
=======================

.. index:: scripts with parameter, parameter, print, bprint, print (bprint)

.. |a| image:: /images/all/blender-basics/a-scripts/parameter-100.png

Objectives
==========
   
.. tabularcolumns:: | c | l |
   :border: none

+-------+-------------------------------------------------------------------------+
|  |a|  | You learned about the structure of a script and how to run it. Now we   |
|       | define a new function with a parameter. This increases the flexibility  |
|       | of our own code and programms.                                          |
+-------+-------------------------------------------------------------------------+

 
Instructions
============
:Tasks:

1. Create a new scrtipt and save it as *bprint.py* in your project folder.
2. Run the script and check the output in the 3D View.
3. Rewrite the script, the output function should set the text on a given position
   in the 3D-View. Use a second parameter for this task.
4. How is the function call for the mascot of Blender, the monkey named »Suzanne«?
   
   .. image:: /images/all/blender-basics/a-scripts/script-start-100.png

bprint -- output into the 3D view
=================================
How can you create text in a 3D world? With our own function we can add new functionality.
A new function named bprint (b stands for Blender) will be created and used.
Have a look at the complete script.

.. literalinclude:: files/bprint.py
   :language: python
   :linenos:


Defining parameters
===================
In our template we used a parameter with the function *print*:

.. code-block:: python

   print(__name__)

The definition of the new funktion *bprint* defines a parameter as well. The parameter is named »print_text« - the name of the parameter(s) can be choosen freely.

.. literalinclude:: files/bprint.py
   :language: python
   :emphasize-lines: 12

:Note: Parameters are placed between the rounded braces behind the name of the function.


Optional parameters
===================
If you define a function like in the example above, you can not call the function without passing an argument into the function. If you want to make the parameter optional you can give the parameter a default value. If that parameter does not get fed an argument when the function is called, the default value is used instead. This is useful if many parameters are possible but not all are mandatory. Examples for optional parameters:

.. code-block:: python

   def my_functions(location=(0,0,0))
   def my_function(rotation=(0,1,1))
   def my_function(text="hello, world")

:note: An optional parameter is defined as a key-value-pair, as shown in the examples above.

Blender showcase for parameters
===============================
Now let's have a look at an example in Blender. First of all enlarge the info window 
in Blender:

|
.. image:: /images/all/blender-basics/a-scripts/info-window.png
   :width: 450px

|
| You are now able to see all functioncalls that your are doing. If you add 
| a cylinder, selecting the menu *Add » Mesh » Cylinder* you will see a very
| long function call. 
| You can select a line by right clicking it - then you can copy and paste the line
| to your text window.
|
.. image:: /images/all/blender-basics/a-scripts/long-line.png
   :width: 450px

|
For better readability of this »ASCII-tapeworm« all parameters are broken up to
separate lines:

.. code-block:: python

   bpy.ops.mesh.primitive_cylinder_add(vertices=32,
                                       radius=1, 
                                       depth=2, 
                                       end_fill_type='NGON',
                                       view_align=False, 
                                       enter_editmode=False,
                                       location=(-4.93998, -5.74176, 4.41665), 
                                       rotation=(0, 0, 0), 
                                       layers=(True, 
                                               False, False, False, False, 
                                               False, False, False, False, 
                                               False, False, False, False, 
                                               False, False, False, False, 
                                               False, False, False))

Most of the lines are optional. The shortest version is:

.. code-block:: python

   bpy.ops.mesh.primitive_cylinder_add(location=(-4.93998, -5.74176, 4.41665))

And with some better readable parameter values:

.. code-block:: python

   bpy.ops.mesh.primitive_cylinder_add(location=(2, 2, 2))

|
| Now you have a new way to discover useful and/or new function in Blender.