Class Documentation

Name:Focus
Version:1.0
ID:ID_FOCUS
Status:Unspecified
Category:GUI
Date:June 2003
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 2000-2003. All rights reserved.
Short:  The Focus class manages user focussing.



Description

This class is designed to aid the handling of the 'user focus' on graphical areas. As the user moves the mouse pointer around the display and clicks on the various rendered objects, the system automatically records the object that has the current focus, and notifies those that do not. If you're in a situation where you need to respond to the focus being lost or received, then you'll need to use the focus class.

In order to create a functional focus object, all you need to do is set the Object field to point to the object that you are interested in monitoring. By default, the Focus object will only take action when the focus is received. If you want to take action when the focus is lost, set the Lost field to TRUE. When the focus object receives a positive notification of change, it will do two things:

The following example creates a render object that has the focus, then self-destructs when the focus is lost (which will occur when the user clicks on something else):

  <render name="drawable" x="10" y="10" width="100" height="100">
    <focus object="[owner]" lost>
      <action static call="free" object="[drawable]"/>
    </focus>
    <action call="focus" object="[owner]"/>
  <render>

If you require more examples, the best idea is to search some of the existing DML files that are distributed with Athene.

Structure

The Focus object consists of the following public fields:

Drawable  Determines the drawable to use for frame setting.
Frame  Setting this field allows the object to alter rendered frames.
Lost  Set to TRUE if the focus object should pay attention to focus loss.
Object  Set this field to determine what object is to be monitored for the focus.
Field:Drawable
Short:Determines the drawable to use for frame setting.
Type:OBJECTID
Status:Read/Write

In most cases, when you create a Focus object it should be contained by a drawable area, such as a Render object. If this is not possible then you will need to set this field to point to the drawable object that you want to monitor.


Field:Frame
Short:Setting this field allows the object to alter rendered frames.
Type:LONG
Status:Read/Write

You may want to use the focus object to provide a graphical response to the focus being received or lost. If so, set this field to the number of the frame that you wish to draw to when the focus is changed.


Field:Lost
Short:Set to TRUE if the focus object should pay attention to focus loss.
Type:BOOLEAN
Status:Read/Write

If you set this field to TRUE then the focus object will reverse its behaviour and perform only when the focus is lost, rather than when the focus is received.


Field:Object
Short:Set this field to determine what object is to be monitored for the focus.
Type:OBJECTID
Status:Read/Write

Before initialising a Focus object, you should first set the Object field so that the correct object is monitored for focus events. If you do not set this field, the Focus object will monitor the container that is active at the time of initialisation.