Class Documentation

Name:Movement
Version:1.0
ID:ID_MOVEMENT
Status:Unspecified
Category:GUI
Date:February 2003
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 2000-2003. All rights reserved.
Short:  Used to react to the user's movement within the GUI.



Description

The Movement class is used to detect the movement of any 'pointing device' that the user is moving on the display. In the vast majority of cases this means dealing with mouse pointers, although touch screens can also express movement, as well as joysticks and other devices that can move the pointer.

The Movement class supports a number of native actions that can be performed when movement is detected, including:

  • Can move objects to the back or front of the display.
  • Can alter the frame of its monitored object.
  • Will send Activate messages to all children of the movement object, which can then perform whatever commands you specified.
  • By default, a movement object will monitor the user's motion in the local container. The handling of movement is split into three parts - movement entry, internal movement and movement exit. The default behaviour is to monitor movement entry, which causes the movement object to react only when the pointer moves over the object for the first time. You can do the opposite and monitor for a user exit by setting the Exit field to TRUE.

    Structure

    The Movement object consists of the following public fields:

    Drawable  Refers to the drawable to be used for movement monitoring.
    Enter  Set to TRUE to activate child object/s when the user enters the monitored area.
    Exit  Set to TRUE to activate child object/s when the user leaves the monitored area.
    ExitFrame  Enables frame switching when the user leaves the monitored object.
    Frame  Enables frame switching when the user enters the monitored object.
    Height  Defines the height of a Movement object's monitored area.
    MoveToBack  Can refer to an object that should be moved to the back when movement is detected.
    MoveToFront  Can refer to an object that should be moved to the front when movement is detected.
    Pointer  Defines the pointer cursor to use when the pointer enters the vicinity of the movement area.
    State  Reflects the current state of the movement object.
    Width  Defines the width of a Movement object's monitored area.
    XCoord  The horizontal position of a Movement object's monitored area.
    XOffset  Specifies the horizontal offset of a Movement object's monitored area.
    YCoord  The vertical position of a Movement object's monitored area.
    YOffset  Specifies the vertical offset of a Movement object's monitored area.
    Field:Drawable
    Short:Refers to the drawable to be used for movement monitoring.
    Type:OBJECTID
    Status:Read/Write

    In most cases, when you create a Movement object it should be contained by a drawable area, such as a Render object. However there may be situations where you want to initialise a Movement object to a non-graphical container. If this is the case then you must set the Drawable field so that the Movement object knows what drawable it needs to monitor for movement.


    Field:Enter
    Short:Set to TRUE to activate child object/s when the user enters the monitored area.
    Type:BOOLEAN
    Status:Read/Write

    If this field is set to TRUE, the Movement object will activate all of its child objects when the user enters the monitored area.


    Field:Exit
    Short:Set to TRUE to activate child object/s when the user leaves the monitored area.
    Type:BOOLEAN
    Status:Read/Write

    If this field is set to TRUE, the Movement object will activate all of its child objects when the user leaves the monitored area.


    Field:ExitFrame
    Short:Enables frame switching when the user leaves the monitored object.
    Type:LONG
    Status:Read/Write

    If you would like the Movement object to change the frame number of its related drawable when the user leaves the object, set this field to the frame number that you want to use.


    Field:Frame
    Short:Enables frame switching when the user enters the monitored object.
    Type:LONG
    Status:Read/Write

    If you would like the Movement object to change the frame number of its related drawable when the user enters the object, set this field to the frame number that you want to use.


    Field:Height
    Short:Defines the height of a Movement object's monitored area.
    Type:FLOAT
    Status:Read/Write

    If you want a Movement object to monitor a specific region of the drawable that it is connected to, set the XCoord, YCoord, Width and Height fields. If you would rather have the Movement object monitor the entire area of the drawable, do not set any of the fields.

    To set a relative height, use the FD_PERCENT flag when setting the field; otherwise a fixed height is assumed.


    Field:MoveToBack
    Short:Can refer to an object that should be moved to the back when movement is detected.
    Type:OBJECTID
    Status:Read/Write

    When the user enters the monitored area, you can move a selected object to the back of its container by setting this field to that object's ID. Here is an example that moves a Render object to the back when the user enters it:

      <render name="drawable" width="100" height="100" colour="#606000">
        <movement object="drawable" movetoback="[drawable]"/>
      </render>
    

    Field:MoveToFront
    Short:Can refer to an object that should be moved to the front when movement is detected.
    Type:OBJECTID
    Status:Read/Write

    When the user enters the monitored area, you can move a selected object to the front of its container by setting this field to that object's ID. Here is an example that moves a Render object to the front when the user enters it:

      <render name="drawable" width="100" height="100" colour="#606000">
        <movement object="drawable" movetofront="[drawable]"/>
      </render>
    

    Field:Pointer
    Short:Defines the pointer cursor to use when the pointer enters the vicinity of the movement area.
    Type:STRING
    Status:Get/Set

    Set the Pointer field if you would like to use a special pointer image when the user's pointer enters the movement area. Valid image names for the pointer are defined in the Pointer class documentation.


    Field:State
    Short:Reflects the current state of the movement object.
    Type:LONG
    Status:Read

    The current state of the Movement object in relation to the user is always reflected in this field. The numbers that may be returned from the field are as follows:

      ENTERED = 1
      INSIDE  = 2
      EXITED  = 3
    

    The ENTERED state means that the user has just entered the monitored area. The INSIDE state means that the user is moving within the monitored area. The EXITED state means that the user has left the monitored area.


    Field:Width
    Short:Defines the width of a Movement object's monitored area.
    Type:FLOAT
    Status:Get/Set

    If you want a Movement object to monitor a specific region of the drawable that it is connected to, set the XCoord, YCoord, Width and Height fields. If you would rather have the Movement object monitor the entire area of the drawable, do not set any of the fields.

    To set a relative width, use the FD_PERCENT flag when setting the field; otherwise a fixed width is assumed.


    Field:XCoord
    Synonyms:X
    Short:The horizontal position of a Movement object's monitored area.
    Type:FLOAT
    Status:Get/Set

    If you want a Movement object to monitor a specific region of the drawable it is connected to, set the XCoord, YCoord, Width and Height fields. If you would rather have the Movement object monitor the entire area of the drawable, do not set any of the fields.

    To set a relative/percentage based value, you must use the FD_PERCENT flag or the value will be interpreted as fixed. Negative values are permitted.


    Field:XOffset
    Short:Specifies the horizontal offset of a Movement object's monitored area.
    Type:FLOAT
    Status:Get/Set

    The XOffset has a dual purpose depending on whether or not it is set in conjunction with an X coordinate or a Width based field.

    If set in conjunction with an X coordinate then the monitored area will be from that X coordinate up to the width of the container, minus the value given in the XOffset. This means that the width of the area is dynamically calculated in relation to the width of the container.

    If the XOffset field is set in conjunction with a fixed or relative width then the monitored area will start from an X coordinate calculated from the formula "XCoord = ContainerWidth - Width - XOffset".


    Field:YCoord
    Synonyms:Y
    Short:The vertical position of a Movement object's monitored area.
    Type:FLOAT
    Status:Get/Set

    If you want a Movement object to monitor a specific region of the drawable it is connected to, set the XCoord, YCoord, Width and Height fields. If you would rather have the Movement object monitor the entire area of the drawable, do not set any of the fields.

    To set a relative/percentage based value, you must use the FD_PERCENT flag or the value will be interpreted as fixed. Negative values are permitted.


    Field:YOffset
    Short:Specifies the vertical offset of a Movement object's monitored area.
    Type:FLOAT
    Status:Get/Set

    The YOffset has a dual purpose depending on whether or not it is set in conjunction with a Y coordinate or a Height based field.

    If set in conjunction with a Y coordinate then the monitored area will be from that Y coordinate up to the height of the container, minus the value given in the YOffset. This means that the height of the area is dynamically calculated in relation to the height of the container.

    If the YOffset field is set in conjunction with a fixed or relative height then the monitored area will start from a Y coordinate calculated from the formula "YCoord = ContainerHeight - Height - YOffset".