ssCore.Guides.create

Add a new guide object.


Availability:

First available in version 3.0 build 2039.


Input Parameters:

name - An identifier that will be used to reference this guide object.

lower - [Optional] - The guide to be used as the lower bound for this guide.

upper - [Optional] - The guide to be used as the upper bound for this guide.

orientation - The orientation of the new guide, can be either HORIZONTAL or VERTICAL. The orientation of this guide must match the orientation of the guides specified as the lower and upper bounds. Valid values include: HORIZONTAL and VERTICAL.

offset - A percentage or an absolute offset in pixels. Using a percentage (e.g. '30%') means the new guide will be positioned 30% of the way between the lower bound guide and the upper bound guide. An absolute value of '10' means the new guide will be 10 pixels to the right of (or below) the lower bound guide. An absolute value of '-10' means the new guide will be 10 pixels to the left of (or above) the upper bound guide.


Output Parameters:

No output parameters.


Asynchronous Mode:

When this method is called asynchronously, a return object containing the output parameters is passed to the specified callback function.

ssCore.Guides.create( paramsObject [, callbackParamsObject] [, errorParamsObject] );


Synchronous Mode:

When this method is called synchronously, a return object containing the output parameters is returned to the caller immediately.

var returnObject = ssCore.Guides.create( paramsObject );


Notes:

The lower and upper parameters specify two existing guides to be used as boundaries, one lower bound and and one upper bound. Lower means lower in numerical positional value so this will be the left-most (for vertical guies) and top-most (for horizontal guides). It might not make sense at first to call the topmost guide the lower bound, but it is the one with the lower numerical value. That means that the upper bound will be the right-most (for vertical guies) and bottom-most guides (for horizontal guides).

Vertical guides must be bounded by two existing vertical guides and horizontal guides must be bounded by two horizontal guides. Your first guide will, obviously, be bounded by two the four default guides ("top", "bottom", "left" and "right").

The offset parameter allows you to specify where the new guide should appear between the two bounding guides by specifying an offset that is either (i) an absolute number of pixels away from one of the guides or (ii) a percentage which defines a relative position between the bounding guides.

Using a positive pixel value for the offset means that you want your new guide to be a fixed number of pixels from the lower guide. If you use a negative pixel value for the offset, that tells SWF Studio that you want your new guide to be a fixed number of pixels from the upper guide.


Examples:

Create a new guide called "middle" that is located 50% of the way between the left and right edges of the player window. This separates the player window nicely into two sections that we can use to contain our ActiveX controls.

ssCore.Guides.create(
{
    // the name of our new guide
    name:"middle",

    // this new guide is bounded by the predefined "left" and "right" guides
    lower:"left", upper:"right",

    // "middle" will be a vertical guide
    orientation:"vertical",

    // this guide will be 50% of the way between the bounding guides
    offset:"50%"
});

Now suppose that instead of two equal sized sections we wanted the left section to always be 200 pixels wide. To do this we just have to change the offset from a percentage, to a fixed value of 200.

ssCore.Guides.create(
{
    // the name of our new guide
    name:"middle",

    // this new guide is bounded by the predefined "left" and "right" guides
    lower:"left", upper:"right",

    // "middle" will be a vertical guide
    orientation:"vertical",

    // this guide will be 200 pixels from the lower bound ("left") guide
    offset:"200"
});