INFO
After creating objects like texts, images, shapes etc., you can move, position, scale, turn them or whatever using the commands shown below.

OBJECT COMMANDS
Note: all Sprite Candy commands have the prefix "HUD" at the beginning, regardless if they're related to HUDs, layers or objects.

* The marked commands can be either used with single objects or object groups ( see "Object Groups" ).

       Z-ORDER
  HUD_SwapObjectOrder
  HUD_SetObjectOrder
  HUD_GetObjectOrder
  HUD_ObjectToFront

       COLORS, ALPHA, SHADOWS ETC.
  HUD_SetObjectColor *
  HUD_SetObjectGradient *
  HUD_SetObjectAlpha *
  HUD_GetObjectAlpha
  HUD_SetObjectShadow *
  HUD_GetObjectShadow
  HUD_SetObjectBG *
  HUD_GetObjectBG
  HUD_SetObjectBorder *
  HUD_GetObjectBorder
  HUD_SetObjectVisibility *
  HUD_GetObjectVisibility

       OBJECT VERTICES
  HUD_CountObjectVertices
  HUD_EnableVertexColor
  HUD_SetVertexColor
  HUD_SetVertexAlpha
  HUD_GetVertexColor

       OBJECT SIZE & COORDINATES
  HUD_SetObjectScale *
  HUD_GetObjectScaleX
  HUD_GetObjectScaleY
  HUD_SetObjectSize
  HUD_GetObjectWidth
  HUD_GetObjectHeight
  HUD_GetObjectX
  HUD_GetObjectY
  HUD_GetObjectCoords
  HUD_GetObjectMinX, GetObjectMaxX
  HUD_GetObjectMinY, GetObjectMaxY

       ROTATION & POSITIONING
  HUD_TurnObject *
  HUD_SetObjectRotation *
  HUD_GetObjectRotation
  HUD_MoveObject *
  HUD_PositionObject *
  HUD_SetObjectOrigin *




Z-ORDER
HUD_SwapObjectOrder

HUD_SwapObjectOrder (  Object_Handle1%,  Object_Handle2%  )

Swaps the depth order (display order) of two objects. Note: it doesn't make any sense to swap the depth orders of two objects that aren't placed on the same layer. Use HUD_SwapLayerOrder then.

Object_Handle1% , Object_Handle2%
Handle of two objects.

JUMP TO TOP OF PAGE


HUD_SetObjectOrder

HUD_SetObjectOrder (  Object_Handle%,  zOrder%  )

Sets the depth order (display order) of an object.

You can change the depth order of HUDs, layers or individual objects.

Object_Handle%
Handle of an object (text, image, shape etc.)

zOrder%
Integer value from 0 to ... Objects with higher depth order values will appear in front (on top), where objects with a lower depth order will appear behind others. Object with a depth order set to 0 will appear behind all other objects, for example.

JUMP TO TOP OF PAGE


HUD_GetObjectOrder

zOrder% =  HUD_SetObjectOrder (  Object_Handle%  )

Returns the current depth order (display order) of an object.

JUMP TO TOP OF PAGE


HUD_ObjectToFront

zOrder% =  HUD_ObjectToFront ( Object_Handle% )

Sets the z-order value (display order) of an object automatically to display it on top of all other objects within the same layer and returns the new z-order of this object.

Note: if you want to place an object behind all other objects within the same layer, use HUD_SetObjectOrder with a z-order value of 0.

Object_Handle%
Handle of an object (text, image, shape etc.)

JUMP TO TOP OF PAGE



COLORS, APLHA, SHADOWS ETC.
HUD_SetObjectColor

HUD_SetObjectColor (  Group_Handle%|Object_Handle%,  R%,  G%,  B%,  [alpha#] )

Colorizes the specified object (or all objects of a group, if a group handle was specified). By default, an object's RGB color is set to 255,255,255.

Group_Handle% | Object_Handle%
Handle of an object (text, image, shape etc.) or an object group.

R% , G% , B%
The red, green and blue values where each may range from 0 (dark) to 255 (full color).

alpha#
You can also specify an alpha transparency. Use a float value from 0.0 (full transparency) to 1.0 (opaque, solid).

JUMP TO TOP OF PAGE


HUD_SetObjectGradient

HUD_SetObjectGradient (  Group_Handle%|Object_Handle%,  R1%,  G1%,  B1%,    R2%,  G2%,  B2%,  [mode%] )

Applies a color gradient of two colors to the specified object (or all objects of a specified object group), either horizontally or diagonally.

Group_Handle% | Object_Handle%
Handle of an object (text, image, shape etc.) or an object group.

R1% , G1% , B1%
The red, green and blue values of the first color, where each may range from 0 (dark) to 255 (full color).

R2% , G2% , B2%
The red, green and blue values of the second color.

mode%

  • 1 = Horizontal, straight color gradient (default)
  • 2 = Diagonal color gradient

    JUMP TO TOP OF PAGE


    • HUD_SetObjectAlpha

    HUD_SetObjectAlpha (  Group_Handle%|Object_Handle%,  alpha#  )

    Sets the transparency (alpha) value of a single object or all objects of a specified group.

    Group_Handle% | Object_Handle%
    Handle of an object (text, image, shape etc.) or an object group.

    alpha#
    Float value from 0.0 (transparent) to 1.0 (opaque, solid).

    JUMP TO TOP OF PAGE


    HUD_GetObjectAlpha

    alpha# =  HUD_GetObjectAlpha (  Object_Handle%  )

    Returns the current alpha value of the specified object.

    JUMP TO TOP OF PAGE


    HUD_SetObjectShadow

    HUD_SetObjectShadow (  Group_Handle%|Object_Handle%,  mode%,  [offset%]  )

    Adds or removes a dropshadow to the specified object or to all objects of the specified group.

    Group_Handle% | Object_Handle%
    Handle of an object (text, image, shape etc.) or an object group.

    mode%

  • TRUE - Adds a shadow
  • FALSE - Removes an existing shadow

    offset%
    The shadow's offset in pixels. A negative value will place the shadow left and to the top, a positive value will place it on the right and to the bottom.

    JUMP TO TOP OF PAGE


    • HUD_GetObjectShadow

    state% =  HUD_GetObjectShadow (  Object_Handle%  )

    Returns TRUE, if the specified object has a shadow attached, otherwise FALSE.

    JUMP TO TOP OF PAGE


    HUD_SetObjectBG

    HUD_SetObjectBG (  Group_Handle%|Object_Handle%,  mode%,  [R%],  [G%],  [B%],  [alpha#]  )

    Adds or removes a colored background to the specified object or to all objects of the specified group.

    Group_Handle% | Object_Handle%
    Handle of an object (text, image, shape etc.) or an object group.

    mode%

  • TRUE - Adds a colored background.
  • FALSE - Removes an existing background.

    R% , G% , B%
    The red, green and blue value of the background's color (each may range between 0 and 255).

    alpha#
    The transparency (alpha) value of the background color (may range between 0.0 and 1.0).

    JUMP TO TOP OF PAGE


    • HUD_GetObjectBG

    state% =  HUD_GetObjectBG (  Object_Handle%  )

    Returns TRUE, if the specified object has a colored background attached, otherwise FALSE.

    JUMP TO TOP OF PAGE


    HUD_SetObjectBorder

    HUD_SetObjectBorder (  Group_Handle%|Object_Handle%,  mode%,  [R%],  [G%],  [B%],  [alpha#],  [size%]  )

    Adds or removes a colored border (frames) to the specified object or to all objects of a group. The border will be placed behind the object, so you won't see it when used with non-transparent images, for example.

    Group_Handle% | Object_Handle%
    Handle of an object (text, image, shape etc.) or an object group.

    mode%

  • TRUE - Displays a colored frame around the object.
  • FALSE - Removes an existing frame.

    R% , G% , B%
    The red, green and blue value of the frame's color (each may range between 0 and 255).

    alpha#
    The transparency (alpha) value of the frame color (may range between 0.0 and 1.0).

    size%
    The width of the line, in pixels (default: 2)

    JUMP TO TOP OF PAGE


    • HUD_GetObjectBorder

    state% =  HUD_GetObjectBorder (  Object_Handle%  )

    Returns TRUE, if the specified object has a colored frame attached, otherwise FALSE.

    JUMP TO TOP OF PAGE


    HUD_SetObjectVisibility

    HUD_SetObjectVisibility ( Group_Handle%|Object_Handle%,  state% )

    Use this command to show or hide objects individually. Hidden objects will not be rendered. If the object has been declared as a button, it will not checked for mouse events while hidden.

    Group_Handle% | Object_Handle%
    Handle of an object (text, image, shape, etc.) or an object group.

    state%

  • TRUE: The object will be shown.
  • FALSE: The object will be hidden.

    JUMP TO TOP OF PAGE



    • OBJECT VERTICES
    HUD_CountObjectVertices

    HUD_CountObjectVertices ( Object_Handle%  )

    Returns the number of vertices that are used to build this object. A common Sprite Candy image uses four vertices by default. Tiled images, shapes or texts use a custom number of vertices.

    Object_Handle%
    Handle of an object (text, image, shape, etc.).

    JUMP TO TOP OF PAGE


    HUD_EnableVertexColor

    HUD_EnableVertexColor ( Object_Handle%,  state% )

    You can change the color and alpha value of each individual object vertex, too. To do so, you must enable the vertex color mode for this object first by using this command. Then you can set the color or alpha value of each vertex individually.

  • An object's vertex color mode is set to disabled by default.
  • You can enable / disable the vertex color mode for an object at any time.
  • HUD_SetObjectAlpha( ) can still be used while vertex color mode is enabled.
  • HUD_SetObjectColor( ) will be ingored while the vertex color mode of an object is enabled. You must set each vertex color seperately then.

    • Object_Handle%
    Handle of an object (text, image, shape, etc.).

    state%

  • TRUE: Enable vertex color for the specified object.
  • FALSE: Disable vertex color for the specified object.

    JUMP TO TOP OF PAGE


    • HUD_SetVertexColor

    HUD_SetVertexColor ( Object_Handle%,  index%,  R%,  G%,  B%,  alpha#  )

    After you enabled the vertex color mode for an object using HUD_EnableVertexColor( ), you can modify the color and alpha value of each individual object vertex. Common Sprite Candy images are built using four vertices (in the order top-left, top-right, bottom-right, bottom-left). Tiled images, shapes or texts are usually built with a different number of vertices. You can retrieve the vertex count of an object using HUD_CountObjectVertices( ).

    Object_Handle%
    Handle of an object (text, image, shape, etc.).

    index%
    The index number of the vertex you want to modify, starting at 0. A common image, for example, has four vertices that are numbered 0-3. You can also find the index number of the last vertex by using HUD_CountObjectVertices ( Object% ) - 1

    R% , G% , B%
    The red, green and blue component of the color. Each one may range from 0 (dark, no color) to 255 (bright, full color).

    alpha#
    Alpha (transparency) value that may range from 0.0 (transparent) to 1.0 (opaque, solid). If not specified, a default value of 1.0 will be used here.

    JUMP TO TOP OF PAGE


    HUD_SetVertexAlpha

    HUD_SetVertexAlpha ( Object_Handle%,  index%,  alpha#  )

    Sets the alpha (transparency) value of an individual object vertex to a specified value.

    Object_Handle%
    Handle of an object (text, image, shape, etc.).

    index%
    The index number of the vertex you want to modify, starting at 0. A common image, for example, has four vertices that are numbered 0-3. You can also find the index number of the last vertex by using HUD_CountObjectVertices ( Object% ) - 1

    alpha#
    Alpha (transparency) value that may range from 0.0 (transparent) to 1.0 (opaque, solid).

    JUMP TO TOP OF PAGE


    HUD_GetVertexColor

    HUD_GetVertexColor ( Object_Handle%,  index%,  what$  )

    This command returns either the red, green, blue or alpha value of the specified object vertex - or a combined ARGB value.

    Object_Handle%
    Handle of an object (text, image, shape, etc.).

    index%
    The index number of the vertex you want to modify, starting at 0. A common image, for example, has four vertices that are numbered 0-3. You can also find the index number of the last vertex by using HUD_CountObjectVertices ( Object% ) - 1

    what$

  • "R" - The command returns the red component of the vertex color (0 - 255).
  • "G" - The command returns the green component of the vertex color (0 - 255).
  • "B" - The command returns the blue component of the vertex color (0 - 255).
  • "A" - The command returns the alpha value of the vertex (0.0 - 1.0).
  • "" (empty, default) - The command returns the ARGB value (all values combined).

    JUMP TO TOP OF PAGE


    • HUD_GetObjectVisibility

    state% =  HUD_GetLayerVisibility ( Object_Handle% )

    Returns TRUE if the specified object is currently visible or FALSE if this object has been set to hidden.

    JUMP TO TOP OF PAGE



    OBJECT SIZE & COORDINATES
    HUD_SetObjectScale

    HUD_SetObjectScale ( Group_Handle%|Object_Handle%,  scale_x#,  scale_y#  )

    Scales an object (or all objects of a group) horizontally (x) or vertically (y).

    Group_Handle% | Object_Handle%
    Handle of an object (text, image, shape, etc.) or an object group.

    scale_x# , scale_y# A scale factor from 0.1 to ..., where 1.0 is the original object scale. Use values below 1.0 to shrink the object or values above 1.0 to enlarge it.

    JUMP TO TOP OF PAGE


    HUD_GetObjectScaleX

    scale_x# =  HUD_GetObjectScaleX ( Object_Handle% )

    Returns the object's current x-scale factor (1.0 if not scaled).

    JUMP TO TOP OF PAGE


    HUD_GetObjectScaleY

    scale_y# =  HUD_GetObjectScaleY ( Object_Handle% )

    Returns the object's current y-scale factor (1.0 if not scaled).

    JUMP TO TOP OF PAGE


    HUD_SetObjectSize

    HUD_SetObjectSize ( Object_Handle%,  width%,  height%  )

    Scales an object to set it's size to the specified absolute width and height (in pixels).

    Object_Handle%
    Handle of an object (text, image, shape, etc.).

    width% , height%
    The desired width and height of the object, in pixels.

    JUMP TO TOP OF PAGE


    HUD_GetObjectWidth

    width% =  HUD_GetObjectWidth ( Object_Handle%,  [onScreen%]  )

    Returns either the relative or absolute width of an object (in pixels). The absolute and relative width are the same when the object has not been rotated.

    Object_Handle%
    Handle of an object (text, image, shape, etc.).

    onScreen%

  • TRUE: Returns the absolute object width (as seen on screen)
  • FALSE: (Default) Returns the relative object width (as seen from one object corner to another)

    JUMP TO TOP OF PAGE


    • HUD_GetObjectHeight

    height% =  HUD_GetObjectHeight ( Object_Handle%,  [onScreen%]  )

    Returns either the relative or absolute height of an object (in pixels). The absolute and relative height are the same when the object has not been rotated.

    Object_Handle%
    Handle of an object (text, image, shape, etc.).

    onScreen%

  • TRUE: Returns the absolute object height (as seen on screen)
  • FALSE: (Default) Returns the relative object height (as seen from one object corner to another)

    JUMP TO TOP OF PAGE


    • HUD_GetObjectX

    x# =  HUD_GetObjectX (  Object_Handle%,  [onScreen%]  )

    Returns the object's current x-cordinate, either as seen on the screen (absolute) or as seen from it's parent layer (relative).

    Object_Handle%
    Handle of an object (text, image, shape, etc.).

    onScreen%

  • TRUE: Returns the object's x-coordinate, as seen on screen (global).
  • FALSE: (Default) Returns the object's x-coordinate, as seen from it's parent layer (which could be rotated or scaled, for example).

    JUMP TO TOP OF PAGE


    • HUD_GetObjectY

    y# =  HUD_GetObjectY (  Object_Handle%,  [onScreen%]  )

    Returns the object's current y-cordinate, either as seen on the screen (absolute) or as seen from it's parent layer (relative).

    Object_Handle%
    Handle of an object (text, image, shape, etc.).

    onScreen%

  • TRUE: Returns the object's y-coordinate, as seen on screen (global).
  • FALSE: (Default) Returns the object's y-coordinate, as seen from it's parent layer (which could be rotated or scaled, for example).

    JUMP TO TOP OF PAGE


    • HUD_GetObjectCoords

    x% | y% =  HUD_GetObjectCoords (  Object_Handle%,  value$,  [corner%]  )

    This command returns useful coordinates of the specified object, like the x / y coordinates of each object corner, the object's center, the minimum or maximum coordinates of the object on screen. Retrieving the minimum or maximum coordinates can be quite useful when the object has been rotated for example and you don't know exactly where the object's corners are.


    Object_Handle%
    Handle of an object (text, image, shape etc.)

    value$

  • "MinX" - Returns the leftmost x-coordinate that the object occupies.
  • "MaxX" - Returns the rightmost, maximum x-coordinate of the object.
  • "MinY" - Returns the topmost, minimum y-coordinate of the object.
  • "MaxY" - Returns the lowest, maximum y-coordinate of the object.
  • "CornerX" - Returns the x-coordinate of a specified corner.
  • "CornerY" - Returns the y-coordinate of a specified corner.

    corner%
    When value$ has been set to "CORNERX" or "CORNERY", you must specify the corner number here, otherwise you can ignore this parameter.

  • 0 - center point
  • 1 - upper-left corner
  • 2 - upper-right corner
  • 3 - lower-right corner
  • 4 - lower-left corner

    JUMP TO TOP OF PAGE


    • HUD_GetObjectMinX, GetObjectMaxX

    minX% =  HUD_GetObjectMinX (  Object_Handle%  )
    maxX% =  HUD_GetObjectMaxX (  Object_Handle%  )

    These commands return the x-coordinate of the leftmost or rightmost object corner. This becomes useful when an object has been rotated and you would like to find the minimum or maximum x-coordinates of the object.

    Object_Handle%
    Handle of an object (text, image, shape, etc.).

    JUMP TO TOP OF PAGE


    HUD_GetObjectMinY, GetObjectMaxY

    minY% =  HUD_GetObjectMinY (  Object_Handle%  )
    maxY% =  HUD_GetObjectMaxY (  Object_Handle%  )

    These commands return the y-coordinate of the topmost or lowest object corner. This becomes useful when an object has been rotated and you would like to find the minimum or maximum y-coordinates of the object.

    Object_Handle%
    Handle of an object (text, image, shape, etc.).

    JUMP TO TOP OF PAGE



    ROTATION & POSITIONING
    HUD_TurnObject

    HUD_TurnObject (  Group_Handle%|Object_Handle%,  degrees#  )

    Turns an object (or all objects of a group) relative to its current orientation.

    Group_Handle% | Object_Handle%
    Handle of an object (text, image, shape, etc.) or an object group.

    degrees#
    Angle in degrees that the object will be turned. Negative values will turn the object counter-clockwise.

    JUMP TO TOP OF PAGE


    HUD_SetObjectRotation

    HUD_SetObjectRotation (  Group_Handle%|Object_Handle%,  angle#  )

    Turns an object (or all objects of a group) to an absolute rotation angle.

    Group_Handle% | Object_Handle%
    Handle of an object (text, image, shape, etc.) or an object group.

    angle#
    Absolute rotation angle, from 0 (no rotation) to 360 (full rotation).

    JUMP TO TOP OF PAGE


    HUD_GetObjectRotation

    angle# =  HUD_GetObjectRotation (  Object_Handle%  )

    Returns the object's current rotation angle (0-360 degrees).

    Object_Handle%
    Handle of an object (text, image, shape, etc.).

    JUMP TO TOP OF PAGE


    HUD_MoveObject

    HUD_MoveObject (  Group_Handle%|Object_Handle%,  step_x#,  step_y#,  [relative%]  )

    Moves an object (or all objects of a group) either absolutely or relative to its current orientation.

    Although you can move an object smoothly using float values, you should use integer values, if possible. An object MUST be placed on an integer x / y position in order to keep it pixel-sharp. Otherwise it may appear blurry (anti-aliased).

    Group_Handle% | Object_Handle%
    Handle of an object (text, image, shape, etc.) or an object group.

    step_x# , step_y#
    x- and y-amount that the object will be moved by (in pixels).

    relative%

  • TRUE: The object will be moved relative to it's current orientation.
  • FALSE: (Default) The object will be moved into an absolute direction.

    JUMP TO TOP OF PAGE


    • HUD_PositionObject

    HUD_PositionObject (  Group_Handle%|Object_Handle%,  x#,  y#,  [onScreen%]  )

    Positions an object (or all objects of a group) either at an absolute screen coordinate (as seen on the monitor) or using the (relative) coordinate system of it's parent layer (which could be rotated or scaled, for example).

    Although you can position an object using float values, you should use integer values, if possible. An object MUST be placed on an integer x / y position in order to keep it pixel-sharp. Otherwise it may appear blurry (anti-aliased).

    Group_Handle% | Object_Handle%
    Handle of an object (text, image, shape, etc.) or an object group.

    x# , y#
    Absolute (screen) coordinates or relative (layer) coordinates where that object will be positioned at.

    onScreen%

  • TRUE: The object will be positioned using the global (screen) coordinate system.
  • FALSE: (Default) The object will be positioned using the coordinate system of it's parent layer (which could be rotated or scaled, for example).

    JUMP TO TOP OF PAGE


    • HUD_SetObjectOrigin

    HUD_SetObjectOrigin (  Group_Handle%|Object_Handle%,  originx#,  originy#,  [usePixels%]  )

       

    By default, an object's origin (the 'rotation center') is placed in the middle of the object (there are two exceptions: text objects with text-flow set to LEFT or RIGHT). An object will be turned or scaled around that reference point. This command moves the origin in x- or y-direction, so you can rotate or scale an object around any point inside the object's boundaries.

  • The origin of text objects can be changed in y-direction only (otherwise the text would change it's position when updated).

    • Group_Handle%|Object_Handle%
    Handle of an object (text, image, shape etc.) or an object group.

    originx# , originy#
    Defines the object origin's position using either a float value (where 0.0 is the object's center and -1.0 or 1.0 are placed at the object's boundary) when usePixels is set to FALSE or an exact pixel offset integer (when usePixels is set to TRUE).

    usePixels%

  • FALSE (Default) - originx and originy must be a value between -1.0 and 1.0, where 0 is the object's center.
  • TRUE - The specified originx and originy values will be interpreted as exact pixel offsets, where originx and originy may range from 0 (top / left) to the object's width / height.

    JUMP TO TOP OF PAGE


    • ©2004,2005 Mike Dogan / X-PRESSIVE.COM
    X-PRESSIVE.COM is a label and working title of Mike Dogan, est. 1999
    All artwork, including graphics, text, images and sounds are property of Mike Dogan, X-PRESSIVE.COM. Trademarks belong to their respective owners. All rights reserved.