Class Documentation

Name:Resize
Version:1.1
ID:ID_RESIZE
Status:Unspecified
Category:GUI
Date:January 2004
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 2000-2004. All rights reserved.
Short:  The Resize class controls the resizing of rendered areas.



Description

The Resize class is used for creating user-interactive resizing areas. In most cases it is applied to the edges of Render objects so that the user can make simple adjustments to display areas. When creating a new Resize object, you can choose what edges of the drawable border should be monitored for resizing, or alternatively you may pin-point the resizing area through standard dimension specifications. The following example demonstrates the use of both methods:

  <render x="50" y="70" width="250" height="300">
    <resize border="left|right|top|bottom" bordersize="10"/>

    <resize xoffset="10" yoffset="10" width="20" height="20" direction="all"/>
  </render>

The first Resize object monitors all four sides of the rendered area, to a region not exceeding 10 units on either edge. To do this, we simply specified the borders that are to be monitored through the Border field. The second Resize object monitors an area that is 20x20 units in size at an offset of 10 units from the bottom right edge. The Direction field has been set to a value of 'all', which means that the user can resize the drawable area in any direction by interacting with the Resize object.

When using Resize objects to manage the dimensions of rendered areas, it is recommended that the MinWidth, MinHeight, MaxWidth and MaxHeight fields are used to prevent excessive shrinkage or expansion. These values must be set in the Render object that the resize functionality is being applied to.

Structure

The Resize object consists of the following public fields:

Border  Set this field to define the borders that should be monitored.
BorderSize  Determines the size of the monitored regions when borders are used.
Button  Defines the user button that starts the resize process.
Direction  Limits the directions in which the user can apply resizing.
Height  Specifies the height of the resize area.
Object  Defines the object that is to be the recipient of the Resize() action.
Width  Specifies the width of the resize area.
XCoord  Specifies the horizontal beginning of the resize area.
XOffset  Specifies the horizontal offset of the resize area.
YCoord  Specifies the vertical beginning of the resize area.
YOffset  Specifies the vertical offset of the resize area.
Field:Border
Short:Set this field to define the borders that should be monitored.
Type:LONG/FLAGS
Prefix:EDGE_
Status:Read/Write

If your Resize object needs to monitor the borders of the drawable area that it is being applied to, use the Border field to specify which borders should be monitored. If you do not supply any border flags then the Resize object will expect you to provide the dimensions for an area to monitor.

Valid Border flags are as follows:

   TOP
   BOTTOM
   LEFT
   RIGHT
   TOPLEFT
   TOPRIGHT
   BOTTOMLEFT
   BOTTOMRIGHT

The size of the borders that are to be monitored must be set through the BorderSize field.


Field:BorderSize
Short:Determines the size of the monitored regions when borders are used.
Type:LONG
Status:Read/Write

If you have used the Border field to determine what borders should be monitored, it is recommended that you set the BorderSize field to define the size of the border areas. If you do not set the BorderSize field then a default value will be used for determining the border size.


Field:Button
Short:Defines the user button that starts the resize process.
Type:LONG
Status:Read/Write

By default, the user can interact with a resize area by moving the mouse over it and pressing/holding the left mouse button or its nearest equivalent. If you would like to change the button that the Resize object reacts to, you can set the Button field to a different value. Valid settings are:

   1 = Left Mouse Button
   2 = Right Mouse Button
   3 = Middle Mouse Button

Field:Direction
Short:Limits the directions in which the user can apply resizing.
Type:LONG/FLAGS
Status:Read/Write

If you are using a Resize object to monitor a specific region rather than using the border functionality, you will need to tell the object what directions the user is allowed to apply the resize. Valid directions are UP, DOWN, LEFT and RIGHT. Setting a direction such as UP|LEFT would allow the user to resize towards the top left corner of the display, but not the bottom right corner.

If you have set the Border field then there is no need to set the Direction as it will be ignored.


Field:Height
Short:Specifies the height of the resize area.
Type:FLOAT|PERCENTAGE
Status:Read/Write

A resize area can be given a fixed or relative height by setting this field to the desired value. To set a relative height, use the FD_PERCENT flag when setting the field - otherwise a fixed height is assumed.


Field:Object
Short:Defines the object that is to be the recipient of the Resize() action.
Type:OBJECTID
Status:Read/Write

This field determines the object that receives resize messages when the user interacts with the Resize object. By default the Resize object's container will receive the messages, but setting this field directly allows you to change who the recipient is.


Field:Width
Short:Specifies the width of the resize area.
Type:FLOAT
Status:Get/Set

A resize area can be given a fixed or relative width by setting this field to the desired value. To set a relative width, use the FD_PERCENT flag when setting the field - otherwise a fixed width is assumed.


Field:XCoord
Short:Specifies the horizontal beginning of the resize area.
Type:FLOAT/PERCENTAGE
Status:Read/Write

The horizontal position of a resize area can be set to an absolute or relative coordinate by writing a value to the XCoord field. 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 the resize area.
Type:FLOAT
Status:Read/Write

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 resize 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 resize area will start from an X coordinate calculated from the formula "XCoord = ContainerWidth - ResizeWidth - XOffset".


Field:YCoord
Short:Specifies the vertical beginning of the resize area.
Type:FLOAT
Status:Read/Write

The vertical position of a resize area can be set to an absolute or relative coordinate by writing a value to the YCoord field. 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 the resize area.
Type:FLOAT
Status:Write

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 resize 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 resize area will start from a Y coordinate calculated from the formula "YCoord = ContainerHeight - ResizeHeight - YOffset".