Program with APIs for Beginners

APIs can be used to perform various actions in an application. For example, the AddPage API can be used to add a page within the project.

  1. Open the command window to start programming with APIs.
    • Drag the horizontal sash next to the horizontal scroll box near the bottom of the page.
    • From the View menu, select Command Window.
    Once you are in the command console, start programming.
    Figure 1. Command Window


  2. Open handles.

    To program using the APIs, handles must be opened.

    Each API is found within a hierarchy of objects (handles). APIs are used to open handles, but are also found within handles and cannot be used unless the handle is opened. To get to specific APIs, you must determine which handles need to be opened in order to get to that API and open the handles needed.

    Once a handle is open, it is free to use until it is released (closed). Handles can be opened and released indefinitely. This is important to reusing the handle.

    The handle is always obtained from its parent; the two handles must be related in some way. All handles are obtained from their parent object.
    Figure 2. Class Hierarchy of Handles. APIs are not shown in this chart.


    For example, to use the AddPage API on a hwIProject handle, you must open the session handle followed by the project handle.
    • When each handle is opened, a name is given to the handle for further use.
      • hwi GetSessionHandle sess

        *hwi is the first parent handle, which connects every API together.

        *sess is the name given to the session handle. You can use any name you want, as long as it is unique.

    • When opening some handles, you may need to specify which handle out of many options that you want to use. For example, when opening a page handle, you must specify which page you want to get the handle from, as there can be several pages.
      • hwi GetSessionHandle sess
      • sess GetProjectHandle proj
      • proj GetPageHandle p1 1

    All APIs are in the form:

    Handle Method args

    Some have no arguments (args), some have many. Some handles cannot be opened until an object is added, for there is no handle to open without the object. For example, to open a curve handle in a plot, you must add a curve before opening the handle.
    • hwi GetSessionHandle sess
    • sess GetProjectHandle proj
    • proj GetPageHandle p1 1
    • p1 GetWindowHandle w1 1
    • w1 GetClientHandle plot
    • plot AddCurve
    • plot GetCurveHandle c1 1

    If you do not know how to use specific APIs (especially those that open up handles), please reference the commands listed in this help system and look up the particular API. Another way of exploring APIs is using the ListMethods command. When the list methods command is called after a handle, a list of APIs available for use in that handle is returned.

    After an API is called, SOMETHING will be returned. A value, handle, list, success (0) or error code (a number in red) will be returned.

    For a more in-depth explanation of API programming, see the Program with Tcl/Tk Command Tutorials.