Documentation: Powercursor Components

Home » Documentation » Powercursor Components

Introduction

The PowerCursor toolkit consists of a set of library elements that can be included in any Flash project. They reside in the library of a Flash document next to the movieclips created by the user. By adding the PowerCursor movieclips on the stage, optically simulated haptic feedback can be added to any Flash project. Each element has a set of parameters (like for instance force strength, color, etc.) that can be set to control its functioning. The engine and a cursor object are required for the toolkit to function, all other objects are optional.

In this section, all parts of the PowerCursor toolkit are described. Every entry consists of a short paragraph describing the part's function or use and, where applicable, details of the inner workings. A table then lists the object's public properties, which can be accessed using Actionscipt code. All of these properties are both readable and writable.

Structure: Generic & Mergeable Components

In the design of the various objects in the PowerCursor toolkit, it would have been relatively easy to create objects for specific purposes, such as a square hole the size of a desktop icon, or an object that exactly fits Windows’ default minimize-maximize-close buttons. Instead, we chose to make PowerCursor objects very generic, to allow for a broad range of new cursor behaviors to be implemented by them. Their shapes are generic (round or rectangular), rotatable and scalable, their graphics can be modified independent of their functionality, and the forces they apply to cursors are configurable. Moreover, the behaviour objects are designed to expand existing symbols of any shape. This makes it even easier for designers to add PowerCursor functionality to their designs: PowerCursor functionality can be added to any shape, logo, or other graphic in Flash. Such graphics can be made into a hole, or a wall, or a slick area by simply adding a ‘behaviour’ object to that graphic. It is also possible to combine PowerCursor objects with other Flash symbols, including other PowerCursor objects, into new compound symbols. And by adding a special Dimmer object to other objects, specific sections of objects can be deactivated. This makes it possible to produce new shapes such as gutters cut in half or quarter-hills. Through this mechanism, one can also combine parts of objects with each other, which could for example result in a circular area which is half hill and half hole.

Essential components: Engine and Cursor

PC_Engine (required)

As its name implies, the engine is the heart of the PowerCursor toolkit. Without it, none of the other parts will operate properly. One of the few requirements for using the toolkit is that the Engine always be placed in the ‘root’ of the Flash document. This way, the engine can always be located by all objects and cursors. The engine is the only entity that has a list of all the cursors, and is therefore always the link between objects and cursors. It acts as a mediator between objects and cursors, both providing the cursors’ information to the objects and propagating the object’s forces to the cursors. However, it does not simply pass on these forces but compiles them into one single displacement per frame. Objects such as hills and gutters request every cursor’s position continuously (e.g., at every frame) through the engine. They then compare the cursors’ coordinates with their own, testing whether any cursors are touching the object’s area. If so, the object will calculate a (2-dimensional) force for each of those cursors, and sends these forces to the engine. Every frame, the engine may thus receive a multitude of forces from different objects and targeted at different cursors. It is the engine’s task to combine these forces with each other (which can be done in several ways) and with other data. The Engine object has various parameters that determine how the forces are calculated. Like for instance, whether forces should be scaled along with the visibility of objects, whether forces should be ignored if the cursor reaches a certain speed, whether forces of overlapping objects are added, or only the strongest or topmost object should be able to exert a force to the cursor. These parameters can be set in the component panel of the PowerCursor Engine object. Taking into account the forces as well as the cursor’s current speed, grip, inertia, and mouse movements, the engine then calculates a (2-dimensional) displacement vector for every cursor and sends it to the cursors involved.

Parameter	Type	Use (default)
Bouncing balls	Boolean	Determines if ball-type cursors bounce (default="true").
Hide Real Cursor	Boolean	Because flash can not displace the system cursor, a mockup cursor is used in powercursor application. If this value is set true, the system cursor is hidden. Setting this value to false will result in multiple cursors on the screen (default="true")..
Base Force	Integer (0-500)	The base value of all forces. By adjusting this value all operating forces can be increased/decreased (default=100).
Combine Forces	"Add","Strongest","Topmost"	Defines how overlapping forces are combined. (default="Add").
Ignore forces at	"Low speed","Average speed","High speed","Never"	This parameter can be used to ignore all forces above a certain mouse speed. When the cursor is moving at high speed, this usally means the user is targeting at something and doesn't want to disturbed by intervening forces. Hence, by default forces, are ignored at high speed (default="High speed").
Scale forces to _alpha	Boolean	If set to "true", forces applied by an object are scaled to the _alpha of that object. So that you can adjust the force strenght of an object by adjusting the transparancy of the object (default="false").
Hide all object	Boolean	If set to "true" all powercursor objects are made invisible at runtime (default="false").

Cursors in general (at least one cursor is required on stage)

In order for the software to function a cursor has to be present on the stage. As described earlier, flash sandbox system does not allow displacing the system cursor. To bypass this limitation, the system cursor is usually made invisible and a mockup cursor that can be displaced is created on stage.
The toolkit offers two types of cursor: PC_ArrowCursor and PC_CursorMaker. The simplest is ArrowCursor which mimics the operating system cursor arrow. Like a regular system cursor, it can change its appearance according to systems state (finger icon while hovering over buttons, hand icon during dragging, etc). Alternatively, the CursorMaker could be used. This object does not have a graphic defined, but by placing it within an existing movieclip a cursor behavior can be added to that clip. With this element it is possible to create a custom graphic that behaves like a cursor, including all forces exercised by the engine.

All cursors broadcast some events. These are detailed in Events section .

PC_ArrowCursor

The PC_ArrowCursor is the default cursor of the PowerCursor toolkit. It has the same appearance as the standard Windows/Mac operating system cursor.

Parameter	Type	Use (default)
CursorStyle	"Arrow","Finger", "Ball", "Grabhand"	Determines the standard visualisation of the cursor icon (default="Arrow").
Force Grip	Integer (0-100)	The force grip of the cursor (default=50)..
Force Inertia	Integer (0-10)	The inertia of the force (default=10).
Mouse as Force	Boolean	Set whether mousemovements are added to the force calculation systems as force (true) or as absolute mouse displacement (false) (default=false).

PC_CursorMaker (behaviour)

The PC_CursorMaker is a modifier that can turn any symbol into a cursor. The CursorMaker symbol should be combined with another symbol in a new compound symbol. The CursorMaker will then render itself invisible and apply its displacements and events on the new compound symbol.

Parameter	Type	Use (default)
Force Grip	Integer (0-100)	The force grip of the cursor (default=50)..
Force Inertia	Integer (0-10)	The inertia of the force (default=10).

Basic Ready Made Objects: PC_Objects

The PowerCursor toolkit includes many force field objects, divided into ready-made objects and behaviours. As their name implies, ready-made objects work right out of the box, and they can be added to a Flash document simply by dragging them onto the stage. Ready-made objects have some default graphics, and are perfect for quick prototyping or a first exploration of the toolkit. Some objects actively assert a force upon the mousecursor (Hill, Gutter, Ramp), some only alter the users mouse movement (Sand, Slick), others manipulate the functioning of other objects (Dimmer) or provide functionality to script interactive behaviors (Button). The size, rotation and visualization of the objects, as well as parameters that determine the sound and cursor icon when entering and leaving an object can be set by the user. Below we will shortly introduce the objects available in the toolkit.

PC_Ramp

The simplest object of all is the ramp. It simply pushes cursors in a certain direction with constant force. Such an effect could also be described as ‘wind’, or ‘gravity’ (when going down). We have chosen to consistently describe the force fields in terms of physical slopes and thus named this effect a ‘ramp’. The direction is specified by an angle parameter (in degrees). It is relative to the object, so when the object is rotated on stage, it will push cursors in a different direction as well.

Parameter	Type	Use (default)
CursorSound	String	Determines the rolloversound.(default="").
CursorStyle	"Null","Finger", "Ball", "Grabhand","Arrow", "Default"	Determines the cursor icon when rolling over the object (default="Null").
Force Angle	Integer (0-360)	The angle of the applied force in degrees (default=0)..
Force Strength	Integer (0-10)	The strength of the force (default=3).
Graphics Style	"None","Square","Square with shading", "Just shading"	The runtime visualisation of the object on stage (default="Square with shading").
Graphics Tint	RGB color	The color of the object during runtime (default="#DD2424").

PC_Hill, PC_Hole

The Hill is a circular object that pushes cursors away from its centre. A round, force-free ‘hilltop' can be created in its centre using the ‘plateau’ parameter. Depending on its Strength, the Hill can push harder or weaker, and the shape parameter determines how its force changes with distance from the centre. Different slope-shapes can be chosen. The Hole works exactly like the Hill, except it pulls cursors towards its centre instead of pushing them away. It also looks the same, with the exception of its graphic shading. When the Hill or Hole is assigned a negative strength parameter, it will act like the other type (a Hill will become a Hole and vice-versa).

Parameter	Type	Use (default)
CursorSound	String	Determines the rolloversound.(default="").
CursorStyle	"Null","Finger", "Ball", "Grabhand","Arrow", "Default"	Determines the cursor icon when rolling over the object (default="Null").
Force Plateau Diam.	Integer (0-100)	The size of the force free center plateau (default=20)..
Force Shape	"V-Shaped","U-Shaped","Sine-Shaped"	The shape of the hole/hill object can be set linear, U-shaped or Sine-Shaped (default="U-shaped").
Force Strength	Integer (0-10)	The strength of the force (default=3).
Graphics Style	"None","Square","Square with shading", "Just shading"	The runtime visualisation of the object on stage (default="Square with shading").
Graphics Tint	RGB color	The color of the object during runtime (default="#DD2424").

PC_Gutter, PC_PushGutter

The Gutter is a rectangular area which draws cursors towards its bottom, which is its centre line. In this respect, it works like a hole, but in only one dimension instead of two. The Gutter is useful for guiding cursors along a line. If the Gutter's Strength parameter were to be set to a negative value, the Gutter turns into a dam. The different shapes available for Gutters are the same as those for hills and holes. The Pushgutter is a combination of the Gutter and the Slope, creating a rectangular area that draws the cursor towards its center line, while pushing it through..

Parameter	Type	Use (default)
CursorSound	String	Determines the rolloversound.(default="").
CursorStyle	"Null","Finger", "Ball", "Grabhand","Arrow", "Default"	Determines the cursor icon when rolling over the object (default="Null").
Force Plateau Diam.	Integer (0-100)	The size of the force free center plateau (default=20)..
Force Shape	"V-Shaped","U-Shaped","Sine-Shaped"	The shape of the hole/hill object can be set linear, U-shaped or Sine-Shaped (default="U-shaped").
Force Strength	Integer (0-10)	The strength of the force (default=3).
Push Strength (PC_Pushgutter only)	Integer (0-10)	The strength of the force pushing the cursor through the gutter (pushgutter only) (default=3).
Graphics Arrows	"None","Still","Animated"	Show animated, still or no arrows in the push direction (pushgutter only) (default="Still").
Graphics Style	"None","Rectangle","Block","Just shading", "Rectangle with shading","Block with shading"	The runtime visualisation of the object on stage (default="Block with shading").
Graphics Tint	RGB color	The color of the object during runtime (default="#DD2424").

PC_Twister

The twister acts much like a Hill or Hole, but instead of affecting cursors straight to or from its centre, it spins them around. This can give a ‘drainy' effect, where cursors twirl down the vortex like water down a drain. This can be especially useful in combination with the ‘PC_Plateau’ event, which is activated whenever a cursor hits the twister's centre – in other words, the bottom of the drain.

Parameter	Type	Use (default)
CursorSound	String	Determines the rolloversound.(default="").
CursorStyle	"Null","Finger", "Ball", "Grabhand","Arrow", "Default"	Determines the cursor icon when rolling over the object (default="Null").
Force Plateau Diam.	Integer (0-100)	The size of the force free center plateau (default=20)..
Force Shape	"V-Shaped","U-Shaped","Sine-Shaped"	The shape of the hole/hill object can be set linear, U-shaped or Sine-Shaped (default="U-shaped").
Force Spin	"Right-in","Right-out","Left-in","Left-out"	The drain direction of the twister can be set "right" (clockwise) or "left" (counter-clockwise) and "in" or "out" to deterimine if cursor is dragged to the center or to the border of the twister (default="Right-in").
Force Strength	Integer (0-10)	The strength of the force (default=3).
Graphics Style	"None","Circle","Disc", "Just shading","Circle with shading","Disk with shading"	The runtime visualisation of the object on stage (default="Disc with shading").
Graphics Tint	RGB color	The color of the object during runtime (default="#DD2424").
Graphics Vortex	"None","Still","Animated"	The animation of the twister shading (default="still").

PC_Sand

The Sand object is an area that is hard for cursors to get through. It can be used to simulate a sandy or sticky texture. It has both a Roughness and a Stickyness parameter: the first controls the semi-random forces this object applies to the cursor, the second governs the additional speed decrease this object imposes. The forces this object applies should hinder the cursor when it moves, but be absent when the cursor is still. To achieve this, the force calculated is in proportion to the cursor's current speed and in the opposite direction. Because a random factor is added as well, the exact force applied is different per frame, which suggests a rough texture.

Parameter	Type	Use (default)
CursorSound	String	Determines the rolloversound.(default="").
CursorStyle	"Null","Finger", "Ball", "Grabhand","Arrow", "Default"	Determines the cursor icon when rolling over the object (default="Null").
Dir. dep. angle	Integer (0-360)	Sets the angle under which the sand structure is active in degrees (default=0)..
Direction dependency	"None","One-way","Two-way"	Determines if the structure is active in all directions or only when the cursor is moving along the direction of the Dir.dep.angle (default="None")..
Strength (Roughness)	Integer (0-10)	The strength of the semi-random force applied to the cursor (default=3).
Strength (Stickyness)	Integer (0-10)	The strength of the additional speed decrease force applied to the cursor (default=3).
Graphics Style	"None","Square","Square with shading", "Just shading"	The runtime visualisation of the object on stage (default="Square with shading").
Graphics Tint	RGB color	The color of the object during runtime (default="#DD2424").

PC_Slick

The Slick object does not actually exert forces on cursors. Instead, it is an area with a low surface grip, which causes cursors to lose speed more slowly. Cursors will maintain higher speeds on a Slick object, giving the impression of a slippery or ‘icy' surface. Setting the Strength parameter of this object to a negative value effectively turns it into a sticky surface, where cursors lose speed more quickly than normal.

Parameter	Type	Use (default)
CursorSound	String	Determines the rolloversound.(default="").
CursorStyle	"Null","Finger", "Ball", "Grabhand","Arrow", "Default"	Determines the cursor icon when rolling over the object (default="Null").
Dir. dep. angle	Integer (0-360)	Sets the angle under which the sand structure is active in degrees (default=0)..
Direction dependency	"None","One-way","Two-way"	Determines if the structure is active in all directions or only when the cursor is moving along the direction of the Dir.dep.angle (default="None")..
Strength (Roughness)	Integer (0-10)	The strength of the semi-random force applied to the cursor (default=3).
Strength (Stickyness)	Integer (0-10)	The strength of the additional speed decrease force applied to the cursor (default=3).
Graphics Style	"None","Square","Square with shading", "Just shading"	The runtime visualisation of the object on stage (default="Square with shading").
Graphics Tint	RGB color	The color of the object during runtime (default="#DD2424").

PC_Wedge

The wedge object acts like a piece of pie taken out of an hill or hill (depending on force settings). The cursor will be guided towards or away from the tip of the wedge object.

Parameter	Type	Use (default)
CursorSound	String	Determines the rolloversound.(default="").
CursorStyle	"Null","Finger", "Ball", "Grabhand","Arrow", "Default"	Determines the cursor icon when rolling over the object (default="Null").
Force Strength	Integer (0-10)	The strength of the force dragging the cursor to the wedge tip. Use a negative value to push the cursor away from the wedge tip (default=3).
Graphics Style	"None","Wedge with shading","Wedge", "Just shading"	The runtime visualisation of the object on stage (default="Square with shading").
Graphics Tint	RGB color	The color of the object during runtime (default="#DD2424").

PC_Wall

While other objects act on any cursor that touches it, the Wall is an object that cannot be touched at all. When the Engine is about to displace a cursor, it first checks whether this displacement would position it on a wall. If this is the case, the displacement is cancelled and the Engine will try to find an alternative movement that will not put the cursor on any wall. Although this makes it impossible to move a cursor onto a wall area, it is possible to ‘jump’ over a wall by moving the mouse briskly. This can cause the cursor to move from one side of the wall object to the other without touching it.

Parameter	Type	Use (default)
CursorSound	String	Determines the rolloversound.(default="").
CursorStyle	"Null","Finger", "Ball", "Grabhand","Arrow", "Default"	Determines the cursor icon when rolling over the object (default="Null").
Graphics Tint	RGB color	The color of the object during runtime (default="#DD2424").

PC_Target

The target is designed specifically to ease target acquisition of icons, buttons and other clickable interface elements. When the force enters the target it is pushed towards the centre. Once the cursor reached the inner (dish) area the force field is dimmed. The result is in an object that is easy to enter and leave. Target object is a dynamic version of the hole object.

Parameter	Type	Use (default)
CursorSound	String	Determines the rolloversound.(default="").
CursorStyle	"Null","Finger", "Ball", "Grabhand","Arrow", "Default"	Determines the cursor icon when rolling over the object (default="Null").
Force Plateau Diam.	Integer (0-100)	The size of the bullseye plateau. Once the cursor enters the bullseye the forces draggin the cursor towards the center are turned off (default=20)..
Force Shape	"V-Shaped","U-Shaped","Sine-Shaped"	The shape of the hole/hill object can be set linear, U-shaped or Sine-Shaped (default="U-shaped").
Force Strength	Integer (0-10)	The strength of the force (default=3).
Graphics Style	"None","Circle","Disc", "Just shading","Circle with shading","Disk with shading"	The runtime visualisation of the object on stage (default="Disc with shading").
Graphics Tint	RGB color	The color of the object during runtime (default="#DD2424").
Show Bullseye	Boolean	Determines wheather to show the bullseye (default="true").

PC_Dimmer

The Dimmer is a special object, since it does not apply forces itself. Instead, it can create areas that weaken or disable forces created by other objects. Dimmers add their dimming effect to cursor just like other objects add forces to them. When forces are combined in the Engine, it inspects whether any of those forces should be weakened by a dimmer, and scales the forces appropriately. Dimmers have either a global or a local scope. Global dimmers weaken every force on the cursor they affect, while local dimmers only weaken forces from objects with the same parent symbol as the dimmer itself. Dimmers can also be used to weaken or disable the effect of the user’s mouse-movements upon the cursor.

Parameter	Type	Use (default)
Scope	"Global Forces", "Local Forces", "Mouse"	The scope of the dimmer can be set to work globally on all forces, locally on the forces within the symbol or on the mouse, which dims the users movemovement (default="Global Forces").
CursorSound	String	Determines the rolloversound.(default="").
CursorStyle	"Null","Finger", "Ball", "Grabhand","Arrow", "Default"	Determines the cursor icon when rolling over the object (default="Null").
Dim to ... %	Integer (0-100)	Sets the percentage of forces are dimmed to, where 100 is no dimming and 0 is maximal dimming (default=0).
Dir. dep. angle	0	Sets the directional dependance angle, if direction dependance is on
Direction dependency	"None","One-way","Two-way"	Determines if the structure is active in all directions or only when the cursor is moving along the direction of the Dir.dep.angle (default="None").
Graphics Tint	RGB color	The color of the object during runtime (default="#DD2424").

PC_Button

The PC_Button object does not apply any forces. Instead, it creates a simple button that can be used to create interactive behaviors. The button visualization style can be set by the user.

Parameter	Type	Use (default)
Colors	Event | Color	Define colors for button events, pc_mouse, pc_mousedown, pc_rollin, pc_rollover, pc_rollin. (default=#DD2424).
Events	Event | Action | Parameter | Target	Define events linked to the butto for pc_mouse, pc_mousedown, pc_rollin, pc_rollover, pc_rollin.
CursorSound	String	Determines the rolloversound.(default="").
CursorStyle	"Null","Finger", "Ball", "Grabhand","Arrow", "Default"	Determines the cursor icon when rolling over the object (default="Null").
Graphics Style	"None","Basic rectangle","Basic rounded", "Basic circle", "Powercursor"	Choose between various graphic styles..

PC_Powerball

The Powerball doesn’t apply any forces itself. It is a passive free floating object which movements are determined by the forces of underling objects. It is a variant on the cursor object, except that it is not connected to the mouse movements of the user.

Parameter	Type	Use (default)
Force Grip	Integer (0-100)	Determines the force grip (default=50).
Force Inertia	Integer (0-100)	Determines the force inertia (default=10).
Graphics Tint	RGB color	The color of the object during runtime (default="#DD2424").

Behaviours: PC_Behaviours

Behaviours are objects which can achieve similar effects as the ready-made objects, but they have no shade themselves. Instead, they can add PowerCursor functionality to any symbol or shape in Flash. For example, it is possible to draw any custom shape in Flash using the Brush tool and subsequently make that surface sticky or rough or impassable by adding the appropriate modifier to it.

All modifiers apply their functionality to their parent symbol. To use a modifier, the modifier itself should be included in a new symbol, together with the symbol or shape it should modify. Although the new parent symbol defines the object's shape and also broadcasts it events, the modifier's parameters are still maintained within the modifier symbol itself.

PC_RampMaker

The PC_RampMaker works exactly like the PC_Ramp object, except that the RampMaker has no surface itself but applies the roughness to another symbol. It can be used to create a slippery or icy surface in a custom shape.

Parameter	Type	Use (default)
CursorSound	String	Determines the rolloversound.(default="").
CursorStyle	"Null","Finger", "Ball", "Grabhand","Arrow", "Default"	Determines the cursor icon when rolling over the object (default="Null").
Force Angle	Integer (0-360)	The angle of the applied force in degrees (default=0)..
Force Strength	Integer (0-10)	The strength of the force (default=3).

PC_HillMaker

The PC_HillMaker is a modifier with an effect similar to the PC_Hill object. Because the PC_Hill object is of a fixed size, it can displace the cursor according to various interesting slope-shapes, but the HillMaker does not have that advantage. Therefore, the PC_HillMaker simply detects the nearest edge and pushes the cursor in that direction. Because the HillMaker has no way of knowing the shape of its parent object, it has to find the nearest edge through trial-and-error. This is rather inefficient, and because it happens every frame for every cursor touching it, the HillMaker can be quite a calculation-intensive component. Having numerous HillMaker objects with several cursors touching them may lead to performance issues.

Parameter	Type	Use (default)
CursorSound	String	Determines the rolloversound.(default="").
CursorStyle	"Null","Finger", "Ball", "Grabhand","Arrow", "Default"	Determines the cursor icon when rolling over the object (default="Null").
Force Strength	Integer (0-10)	The strength of the force (default=3).

PC_SandMaker

The SandMaker works exactly like the PC_Sand object, except that the SandMaker has no surface itself but applies the roughness to another symbol. It can be used to create a sandy or sticky surface in a custom shape that is hard for cursors to get through. It can be used to simulate a sandy or sticky texture. It has both a Roughness and a Stickyness parameter: the first controls the semi-random forces this object applies to the cursor, the second governs the additional speed decrease this object imposes. The forces this object applies should hinder the cursor when it moves, but be absent when the cursor is still. To achieve this, the force calculated is in proportion to the cursor's current speed and in the opposite direction. Because a random factor is added as well, the exact force applied is different per frame, which suggests a rough texture.

Parameter	Type	Use (default)
CursorSound	String	Determines the rolloversound.(default="").
CursorStyle	"Null","Finger", "Ball", "Grabhand","Arrow", "Default"	Determines the cursor icon when rolling over the object (default="Null").
Dir. dep. angle	Integer (0-360)	Sets the angle under which the sand structure is active in degrees (default=0)..
Direction dependency	"None","One-way","Two-way"	Determines if the structure is active in all directions or only when the cursor is moving along the direction of the Dir.dep.angle (default="None")..
Strength (Roughness)	Integer (0-10)	The strength of the semi-random force applied to the cursor (default=3).
Strength (Stickyness)	Integer (0-10)	The strength of the additional speed decrease force applied to the cursor (default=3).

PC_SlickMaker

The SlickMaker works exactly like the PC_Slick object, except that the SlickMaker has no surface itself but applies the roughness to another symbol. It can be used to create a slippery or icy surface in a custom shape.

Parameter	Type	Use (default)
CursorSound	String	Determines the rolloversound.(default="").
CursorStyle	"Null","Finger", "Ball", "Grabhand","Arrow", "Default"	Determines the cursor icon when rolling over the object (default="Null").
Dir. dep. angle	Integer (0-360)	Sets the angle under which the sand structure is active in degrees (default=0)..
Direction dependency	"None","One-way","Two-way"	Determines if the structure is active in all directions or only when the cursor is moving along the direction of the Dir.dep.angle (default="None")..
Strength (Roughness)	Integer (0-10)	The strength of the semi-random force applied to the cursor (default=3).
Strength (Stickyness)	Integer (0-10)	The strength of the additional speed decrease force applied to the cursor (default=3).

PC_WallMaker

The WallMaker is a modifier version of the PC_Wall object. It works exactly like that object, except that the WallMaker has no shape itself and is meant to create a wall in a custom shape. The WallMaker applies its wall-making ability to its parent object. In the example on the right this object is a maze structure of which the drawn parts become inaccessible after the WallMaker behaviour is added.

Parameter	Type	Use (default)
CursorSound	String	Determines the rolloversound.(default="").
CursorStyle	"Null","Finger", "Ball", "Grabhand","Arrow", "Default"	Determines the cursor icon when rolling over the object (default="Null").
Graphics Tint	RGB color	The color of the object during runtime (default="#DD2424").

PC_ForceDimmer

The PC_ForceDimmer is a special modifier that does not use forces. Instead, it can create areas that weaken or disable forces. Dimmers add their dimming effect to cursor just like other objects add forces to them. When forces are combined in the Engine, it inspects whether any of those forces should be weakened by a dimmer, and scales the forces appropriately. Dimmers have either a global or a local scope. Global dimmers weaken every force on the cursor they affect, while local dimmers only weaken forces from objects with the same parent symbol as the dimmer itself. The example shows a forcedimmer being used to disable the forces underneath the right part of a hill object.

Parameter	Type	Use (default)
Scope	"Global Forces", "Local Forces", "Mouse"	The scope of the dimmer can be set to work globally on all forces, locally on the forces within the symbol or on the mouse, which dims the users movemovement (default="Global Forces").
CursorSound	String	Determines the rolloversound.(default="").
CursorStyle	"Null","Finger", "Ball", "Grabhand","Arrow", "Default"	Determines the cursor icon when rolling over the object (default="Null").
Dim to ... %	Integer (0-100)	Sets the percentage of forces are dimmed to, where 100 is no dimming and 0 is maximal dimming (default=0).
Dir. dep. angle	0	Sets the directional dependance angle, if direction dependance is on
Direction dependency	"None","One-way","Two-way"	Determines if the structure is active in all directions or only when the cursor is moving along the direction of the Dir.dep.angle (default="None").

PC_ButtonMaker

The PC_ButtonMaker does not displace cursors. Instead, it uses PowerCursor's events and an event listener to create button-like behaviour. When the ButtonMaker is touched by a cursor, it can jump to a different frame of its parent MovieClip. On a mouse click, the ButtonMaker can move to yet another frame. These target frames can be set using parameters.

The ButtonMaker was included in the toolkit because the button-like use of event dispatchers it implements is probably one of the most used applications of PowerCursor's events. This modifier could also be created by coding an appropriate event listener in an EventDispatcher, but to accommodate for non-programmers this modifier was included separately.

Parameter	Type	Use (default)
'Out' frame	Integer / String	Sets the frame number or label of the _parent movieclip where the playhead will jump after the cursor moves 'out' (default="1").
'Over' frame	Integer / String	Sets the frame number or label of the _parent movieclip where the playhead will jump after the cursor moves 'over' (default="2").
'Down' frame	Integer / String	Sets the frame number or label of the _parent movieclip where the playhead will jump after the cursor moves 'down' (default="3").
'Up' frame	Integer / String	Sets the frame number or label of the _parent movieclip where the playhead will jump after the cursor moves 'up' (default="2").
CursorSound	String	Determines the rolloversound.(default="").
CursorStyle	"Null","Finger", "Ball", "Grabhand","Arrow", "Default"	Determines the cursor icon when rolling over the object (default="Finger").

PC_DraggerMaker

With the PC_DraggerMaker behaviour, a symbol can be made dragable, meaning that once the left mouse button is pressed while the cursor is inside the object, it will be connected to the cursor.

Parameter	Type	Use (default)
CursorSound	String	Determines the rolloversound.(default="").
CursorStyle	"Null","Finger", "Ball", "Grabhand","Arrow", "Default"	Determines the cursor icon when rolling over the object (default="Null").

PC_ImageToSlope

The PC_ ImageToSlope is a very powerful object. It can be used to transform bitmap images to force objects. This allows users to draw their own height maps, where the brightest regions of the image are interpreted as the highest, while the darkest regions are the lowest. The result is a force that pushes the cursor towards the darker regions of the bitmap.

Parameter	Type	Use (default)
CursorSound	String	Determines the rolloversound.(default="").
CursorStyle	"Null","Finger", "Ball", "Grabhand","Arrow", "Default"	Determines the cursor icon when rolling over the object (default="Null").
Accuracy	"Very High","High", "Average", "Low","Very Low"	Sets the accuracy of the mapping of pixels to the slope (default="Average").
Adapt to Colorspectrum	Boolean	Determines is the image to slope mapping is color sensitive (default="true").

PC_EventDispatcher

The PC_EventDispatcher is an empty subclass of PC_Modifier. It does nothing more than dispatch the standard PowerCursor events that every object dispatches when its parent its parent MovieClip is touched by cursors. .

Parameter	Type	Use (default)
Events	Event | Action | Parameter | Target	Define events linked to the butto for pc_mouse, pc_mousedown, pc_rollin, pc_rollover, pc_rollin.
CursorSound	String	Determines the rolloversound.(default="").
CursorStyle	"Null","Finger", "Ball", "Grabhand","Arrow", "Default"	Determines the cursor icon when rolling over the object (default="Null").

PC_Synchronizer

The PC_Synchronizer is a special behaviour that synchronizes PowerCursor’s mock cursors with the system cursor. As discussed in section 5.1.2, Flash sandbox security prohibits manipulation of the system cursor position. Therefore, Powercursor hides the system cursor and shows a mock cursor of which the position can be manipulated. Over time the dislocation of the mock cursor and the hidden system cursor will increase, which can, for instance when the system cursor reaches the screen border, lead to problems. In some rare cases, for instance when working with third party components that are programmed to respond on the system cursor, it can be necessary to synchronize the location of the mock cursor with the real system cursor. The synchronizer object aims to smoothly synchronize the two cursor locations. This is accomplished by applying forces aimed at the system cursor. This will push the cursor towards the system cursor until their disparity is negligible. The subtlety parameter can make the synchronization process more unobtrusive, but a low strength parameter also goes a long way in achieving this.

Parameter	Type	Use (default)
CursorSound	String	Determines the rolloversound.(default="").
CursorStyle	"Null","Finger", "Ball", "Grabhand","Arrow", "Default"	Determines the cursor icon when rolling over the object (default="Null").
Force Strength	Integer (0-10)	Determines the force strength of the synchronizer.(default=3).
Subtle	Boolean	Determines wheather synchronisation should be subtle (true) or abrupt (false).(default=true).

Debug Tools: PC_Debug

PC_Watcher

The Watcher displays some information about a single cursor. It shows the cursor's position, speed (gained from forces), and by which objects the cursor is currently affected. Objects that try to affect the cursor but are dismissed by the engine's force combination method are displayed between brackets. The Watcher was included in the toolkit for educational and debugging purposes.

Property	Type (default)	Use	Parameter?
averaging	Number (7)	Over how many frames the watcher's data should be averaged. Not averaging (by setting this parameter to 1) leads to a very irregular display.	Averaging (frames)
updateTime	Number (1)	How often the watcher should redraw its data. Minimum = 1 (every frame).	Update time (frames)
target	Number (1)	Which cursor the watcher should study. Cursor 1 is the cursor that was added to the stage first, cursor 2 was added second, and so on.	Target Cursor

PC_ForceSensor

The ForceSensor is a special kind of cursor. When the Engine sends it a displacement, it does not reposition itself, but instead it draws an arrow indicating the direction and strength of the displacement. In this way, the ForceSensor can be used to inspect the forces at a particular point of the stage. It was included as an authoring tool, not to be included in any final design.

Parameter	Type	Use (default)
Averaging (frames)	Integer (1-100)	Determines the number frames averaged over to calculate the force (default=7).
Update time (frames)	Integer (1-100)	Determines the frequenty of the sensor update in frames (default=1).
Force Grip	Integer (1-100)	Determines the force grip (default=50).
Force Inertia	Integer (1-100)	Determines the force inertia (default=10).

PC_PowerGrid

The PowerGrid is a much more powerful object, than the , since it can monitor forces not only at a specific location, but at a selected area of the stage. It visualizes all the forces underneath the grid area by distorting the grid according to the forces active underneath. Users can set the size and resolution of the grid and drag it during runtime. Especially when working with complex composed force objects the PowerGrid is a handy tool to visualize the active forces.

Parameter	Type	Use (default)
gridPoints	Integer (10-500)	Determines the number of points in the grid. Setting this value high may lead to high processor load.(default=100).
lineColor	RGB color	Determines the color of the grid lines (default="#000000l").
lineSize	Integer (1-10)	Determines the thickness of the grid lines (default=1).

Events

PowerCursor events are dispatched in a universal way. PowerCursor events are dispatched from its cursors and its objects. Because the events are implemented in the PC_Object and PC_Cursor superclasses, all individual subclasses handle events in the same way. The specifications of these events can be found below.

Three different events are dispatched by cursors. These can be dispatched once per frame per cursor at maximum.

Event name	Description
pc_forceStart	Triggered when objects try to apply forces to this cursor, and this did not happen in the previous frame.
pc_force	Triggered when objects try to apply forces to this cursor
pc_forceEnd	Triggered when no object tries to apply forces to this cursor, although this did happen in the previous frame.

Six distinct events are dispatched by objects. These can be dispatched once per frame per object per cursor at maximum.

Event name	Description
pc_rollin	Triggered when the number of cursors touching this object increases.
pc_rollover	Triggered whenever any cursor touches this object.
pc_rollout	Triggered when the number of cursors touching this object decreases.
pc_mousedown	Triggered when, at the moment the mouse button is pressed, any cursors touch this object.
pc_mouseup	Triggered when, at the moment the mouse button is released, any cursors touch this object.
Pc_plateau	Triggered whenever any cursor hits the force-free plateau in the centre of certain objects.

All object events carry an event object with them, which contains information on the cursor that triggered the event. (The cursor events have no event object.) To access the event object, an event listener needs to be coded in Flash. The code required for such an event listener may differ for distinct Flash versions but instructions can be found in the accompanying Flash documentation. The event object that is attached to the PowerCursor objects' events contains the following information:

Property	Type	Description
type	String	The event type, such as pc_rollin or pc_mousedown.
target	String	The path to the object that dispatched this event.
x	Number	The x-coordinate of the cursor that caused this event.
y	Number	The y-coordinate of the cursor that caused this event.
xLastDisp	Number	The last horizontal displacement (in other words, the horizontal speed) of the cursor that triggered this event. A positive number denotes rightward movement.
yLastDisp	Number	The last horizontal displacement (in other words, the vertical speed) of the cursor that triggered this event. A positive number denotes downward movement.
path	String	The path to the cursor symbol that triggered this event.

Home | About | Download | Examples | Documentation | Forum | Faq | Colofon

CC 2009 Powercursor.com