====== cdPython script examples ======




===== Using variable handles =====

Certain Zeolite operations return variable handles, like a ZVAR.  To associate a proxy object with the variable represented by this handle, you can use the Attach method.

The example below creates a Zeolite list that has a single string item, which the user can edit through it's user interface.

<code>
import zeolite

args = zeolite.CzList()

handle = args.CreateItem(zeolite.VarID_string, 'name')

# Create a CzStr object and attach it to the handle
mapname_str = zeolite.CzStr()
mapname_str.Attach(handle)
mapname_str.SetText('Hello World')

args.EditUI('parameters')

print mapname_str.GetText()
</code>

Because all Zeolite variables such as ZMAP and ZFORMAT are types of ZVAR, we need to 'cast' these derived type handles appropriately.  Attach for example, requires a ZVAR.

cdPython provides the following methods to cast these type handles:

<code>
foo = zeolite.zmap_to_zvar(bar)    # converts ZMAP to ZVAR
foo = zeolite.zlist_to_zvar(bar)   # converts ZLIST to ZVAR
foo = zeolite.zformat_to_zvar(bar) # converts ZFORMAT to ZVAR
foo = zeolite.zfunc_to_zvar(bar)   # converts ZFUNC to ZVAR
foo = zeolite.zvar_to_zmap(bar)    # converts ZVAR to ZMAP, potentially unsafe
foo = zeolite.zvar_to_zlist(bar)   # converts ZVAR to ZLIST, potentially unsafe
foo = zeolite.zvar_to_zfunc(bar)   # converts ZVAR to ZFUNC, potentially unsafe
foo = zeolite.zvar_to_zformat(bar) # converts ZVAR to ZFORMAT, potentially unsafe
</code>

The example below saves the height field as a gray scale bmp file:

<code>
import zeolite

string = zeolite.CzStr()
string.Create(None)
string.EditUI("Enter filename")

hmap = zeolite.CzMap()
hf = zeolite.cvar.theAPI.project_GetMap("HF")

# Attach requires a ZVAR handle
hmap.Attach(zeolite.zmap_to_zvar(hf))

format = zeolite.CzFormat()
format.GetByExt("HF", 0, "bmp")

filename = string.GetText() + ".bmp"

# SaveFile requires a ZFORMAT handle
hmap.SaveFile(filename, zeolite.zvar_to_zformat(format.GetZVAR()), True, True)

</code>

===== Using the core Zeolite API instance =====

Sometimes, there may be a method you are unable to access through the Zeolite helper objects (CzStr, CzMap, CzFormat etc etc).  In this case you can call a method on the core API instance, which is a member of the Zeolite cvar attribute.

The example below logs an error to the L3DT event log, use the ReportError method:

<code>
import zeolite

zeolite.cvar.theAPI.ReportError('Some kind of error...')
</code>

===== Using pointers to atomic C types =====

Because Python doesn't use pointers, and the Zeolite API requires a pointer to a C type in some cases, notably the CzVar:SetValue method, some additional type wrappers have been included into the Zeolite Python module to handle this.

Here are the wrapper classes:

<code>
zeolite.intp
zeolite.shortp
zeoite.boolp
zeolite.floatp
zeolite.doublep
</code>

Here's an example of using the intp class (all of the wrapper classes above have identical methods):

<code>
minheight = zeolite.intp()  # create an intp
minheight.assign(50)        # set the value of the int to 50

minheight_var = zeolite.CzVar(args.CreateItem(zeolite.VarID_int, 'min height'))

minheight_var.SetValue(zeolite.VarID_int, minheight.cast())   # minheight.cast() returns a pointer to the integer

integer_value = minheight.value()  # retrieve the value of the integer
</code>



===== Using an extension function =====

The following example opens the 3D rendering window in the [[:plugins:Sapphire]] plugin by calling an extension function that it exports. 

<code>
import zeolite
f = zeolite.CzFunc()
f.GetFunc("Sapphire.ShowWnd")
f.Execute()
</code>

The steps were:
  - create a CzFunc object
  - Retrieve the handle to the "Sapphire.ShowWnd" extension function.
  - Execute the function (note: this particular function takes no arguments).