==============
Search the API
==============

.. index:: Search the API, API, documentation

.. |a| image:: /images/all/blender-basics/b-find-information/figure-100.png

Objectives
==========

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

+-------+----------------------------------------------------------------------+
|  |a|  | Creating objects from a menu as with *Add » Mesh » ...* is easy.     | 
|       | The same gaol is also achievable within a Python script.             |
|       | The API is important to get the necessary informations.              |
+-------+----------------------------------------------------------------------+


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

1. Create an new Python script. 
2. Create a function that lists all methods available in Blender 
   who create a mesh objects (primitive) .
3. Create one instance from each object in your scene. No object should touch an other.
4. Create a figure as a composition from a cone and a sphere (UV_Sphere). There are two 
   possible solutions. Maybe you will find a third version.

Structure of the API
====================
All available functionality is grouped by different modules. Only the first 
two are required in the beginning.

**Application Modules**

- *Data Access (bpy.data)*
- *Operators (bpy.ops)*
- Types (bpy.types)
- Utilities (bpy.utils)
- Path Utilities (bpy.path)
- Application Data (bpy.app)
- Property Definitions (bpy.props)

**Standalone Modules**

- Math Types & Utilities (mathutils)
- Font Drawing (blf)
- Audio System (aud)

**Game Engine Modules**

- Game Engine bge.types Module
- Game Engine bge.logic Module
- Game Engine bge.render Module
- Game Engine bge.events module


Which »primitives« are available?
=================================
If you start creating a complex world in 3D/Blender, often a good starting point 
is to create simple objects. Lets create the available mesh objects. 
But which objects are available?


1. First and easiest solution: have a look at the menu  *Add » Mesh » ...* and look 
   at the tooltip at the mouse pointer.

2. RTFM (read the fine manuals)

   a) | Online documentation, search for »mesh primitive« on :blenderdocs:`Blenderdocs<>`
   
   b) | Search the file »OperatorList.txt«. 
      | You can open it in the Blender editor using the menu sequence: 
      | *Help » Operator Sheet Sheet*.
      | A copy is also included in the appendix: :ref:`OperatorList.txt <operatorlist>`
  
3. If you are familiar with the structures in Blender, the console is a 
   good starting point to discover the API.

4. If your are not successful searching the API, ask the community. 
   A linklist is available in the appendix.


:Note: It is essential to work with the API, 
       nobody is able to remember all possibilities!


Finding the right method(s)
===========================
Add mesh objects with Python instead using the menu is shown in a screenshot where the console is used. This is error prone, using a script is a good alternative.

.. image:: /images/all/blender-basics/b-find-information/for-loop.png

Create the objects
==================
Now that we know how to create new objects lets create a script for this task.
Where to place the new object, is controlled by the parameter *location*, a :ref:`tuple <tuple>` (values in rounded braces) with tree Values for the x-, y- und z-aches.

Here is a fragment...

.. code:: python

   bpy.ops.mesh.primitive_cube_add(location=(2, 2, 0))
   bpy.ops.mesh.primitive_cylinder_add(location=(-2, -2, 0))

And so the final solution might look like:

.. image::  /images/all/blender-basics/b-find-information/objects.png


Short video about using the API
================================

.. raw:: html

   <iframe width="560" height="315" 
        src="http://www.youtube.com/embed/2H4ug9RRCWI" 
        frameborder="0" allowfullscreen>
   </iframe>

Showcase
========
Try to recreate the following construct unsing only cubes and the menu *Add » Mesh » ...*!


.. todo:: create a script...