Class Documentation

Name:Render
Version:1.0
ID:ID_RENDER
Status:Stable
Category:GUI
Date:August 2003
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 2000-2003. All rights reserved.
Short:  Manages the display and positioning of 2-Dimensional rendered graphics.



Description

The Render class is the primary tool that is used for interface construction. On its own the Render class does very little in terms of creating graphics, but it has the sole responsibility of managing 2-Dimensional graphics space and keeping everything organised for the display.

Graphically, each render object represents a rectangular area of space on the display. The biggest render object, often referred to as the 'Master' represents the screen space, and is as big as the display itself, if not larger. render objects can be placed inside the master and are typically known as children. You can place more render objects inside of these children, causing a hierachy to develop that consists of many objects that are all working together on the display.

In order to actually draw graphics onto the display, classes that have been specifically created for drawing graphics must be used to create a meaningful interface. Classes such as Box, Image, Text and Gradient are able to create an assemblance of imagery that has meaning to the user. The interface is then enhanced through the use of user-interactive classes such as OnClick, Movement and Pointer. With a little effort and imagination, a customised interface can thus be assembled and presented to the user without much difficulty on the part of the developer.

While this is a simple concept, the Render class is at the base of its foundation and is one of the largest and most important classes in the system. It provides a great deal of functionality which cannot be summarised in this introduction, but you will find a lot of technical detail on each individual field in this manual. The DML Whitepaper has a good summary as to the basic use of the Render class. It is also recommended that you refer to the DML scripts that come with Athene if you require a real-world view of how the class is typically used.

Actions

The Render class supports the following actions:

Activate  Shows a render object on the display.
ClosingTag  Activates a render object.
Disable  Disables a render object.
Draw  Redraws the contents of a render object.
Enable  Enables a disabled render object.
Focus  Informs a render object that it has received the user focus.
Hide  Hides a render object from the display.
LostFocus  Informs a render object that it has lost the user focus.
Move  Moves a render object to a new display position.
MoveToBack  Moves a render object to the back of its container.
MoveToFront  Moves a render object to the front of its container.
MoveToPoint  Moves a render object to an absolute coordinate.
Redimension  Moves and resizes a render object in a single action call.
Resize  Resizes a render object's dimensions.
SaveImage  Saves the graphical image of a render object.
Scroll  Scrolls rendered content to a new position.
ScrollToPoint  Moves the content of a render object to a specific point.
Show  Shows a render object on the display.
UserClick  Informs a render object that the user has clicked on it.
UserClickRelease  Used to inform a render object when a user click has been released.
UserMovement  Used to notify render object's of user movement in and out of their graphical areas.

Methods

The Render class implements the following methods:

Expose  Redraws a render region to the display, preferably from its graphics buffer.
InvalidateRegion  Redraws all of the content in a render object.
MoveContent  Shifts the graphical content of a render object to a new position.
SetDisplay  Sets the screen display (applies to screen based render objects only).
SetOpacity  Alters the opacity of a render object.
SetRenderCallback  Allows you to hook into the drawing process of a rendered object.

Structure

The Render object consists of the following public fields:

AbsX  The absolute horizontal position of a render object.
AbsY  The absolute vertical position of a render object.
Align  This field allows you to align a rendered area within its owner.
Bitmap  Readable field that returns a pointer to a render object's drawable Bitmap.
Bottom  Returns the bottom-most coordinate of a render object.
BottomLimit  Prevents a render object from moving beyond a given point at the bottom of its container.
BottomMargin  Manipulates the bottom margin of a render object.
Buffer  If set to TRUE, buffering will be used when drawing a render object.
Colour  String-based field for setting the background colour.
ColourRGB  An RGB based field for manipulating the background colour.
Drag  This object-based field is used to control the dragging of objects around the display.
FastResize  Enables fast resizing when set to TRUE.
Flags  Special flags.
Frame  Manipulates the frame number that a render object has on display.
Height  Defines the height of a render object.
Hide  Set to TRUE to hide a render object from the display.
Host  If this field is enabled, the render object will be able to host drawables from foreign processes.
InsideHeight  Reflects the amount of space between the vertical margins.
InsideWidth  Reflects the amount of space between the horizontal margins.
Invisible  Defines a render object as being transparent (no drawable content).
LeftLimit  Prevents a render object from moving beyond a given point on the left-hand side.
LeftMargin  Manipulates the left margin of a render object.
MaxHeight  Prevents the height of a render object from exceeding a certain value.
MaxWidth  Prevents the width of a render object from exceeding a certain value.
MinHeight  Prevents the height of a render object from shrinking beyond a certain value.
MinWidth  Prevents the width of a render object from shrinking beyond a certain value.
Movement  Limits the movement of a render object to vertical or horizontal shifts.
Opacity  Affects the level of translucency applied to a render object.
Precopy  Enables the masking feature for render objects.
Region  Specifies whether or not a render object is acting as a simple region.
Right  Returns the right-most coordinate of a render object.
RightLimit  Prevents a render object from moving beyond a given point on the right-hand side.
RightMargin  Manipulates the right margin of a render object.
RouteFocus  Diverts render focussing through a specific path.
StickToBack  Set to TRUE if you want a render object to stick to the back of its container.
StickToFront  Set to TRUE if you want a render object to stick to the front of its container.
Sticky  Set this field to TRUE to prevent a render object from being moved around.
TopLimit  Prevents a render object from moving beyond a given point at the top of its container.
TopMargin  Manipulates the top margin of a render object.
UserFocus  Refers to the render object that has the current focus.
VisibleHeight  Reflects the visible height of a rendered area within its container.
VisibleWidth  Reflects the visible width of a rendered area within its container.
Visible  Indicates the visibility of a render object.
Width  Defines the width of a render object.
WindowHandle  Refers to a render object's window handle, if relevant.
X  Determines the horizontal position of a render object.
XOffset  Determines the horizontal offset of a render object.
YCoord  Determines the vertical position of a render object.
YOffset  Determines the vertical offset of a render object.
Action:Draw
Short:Redraws the contents of a render object.

Drawing a render object causes all child objects belonging to that render object to be sent a Draw action. This has the effect of redrawing all graphics within the render object. The procedure is as follows:

  • If the render object's Colour field has been set, it will clear its background to that colour.
  • Every child belonging to the render object is then sent a Draw notification so that the contents are redrawn.
  • The video display is then updated.

There are just two important notes to be aware of: 1. If the render object contains other render objects, they will not be sent a Draw action unless they are using special effects such as transparency. 2. If the render object has not had its background colour set or if masking is not enabled, the current contents will not be automatically cleared. (This is advantageous in situations where a particular object will clear the rendered area first).


Action:SaveImage
Short:Saves the graphical image of a render object.

If you need to store the image (graphical content) of a render object, use the SaveImage action. Calling SaveImage on a render object will cause it to generate an image of its contents and save them to the given destination object. Any child drawables in the region will also be included in the resulting image data.

The image data will be saved in the data format that is indicated by the setting in the ClassID argument. Options are limited to members of the Picture class, for example ID_PNG, ID_JPEG, ID_PCX and ID_PICTURE. If no ClassID is specified, the default file format is used.


Action:Scroll
Short:Scrolls rendered content to a new position.

Calling the Scroll action on a render object with the SCROLLCONTENT flag set will cause it to move its contents in the requested direction. The Render class uses the Move action to achieve scrolling, so any objects that do not support Move will remain at their given position. Everything else will be shifted by the same amount of units as specified in the XChange, YChange and ZChange arguments.

Some objects may support a 'sticky' field that can be set to TRUE to prevent them from being moved. This feature is present in the Render class, amongst others.

If the render object does not have the SCROLLCONTENT flag set, the call will flow through to any objects that may be listening for the Scroll action on the drawable.


Method:InvalidateRegion()
Short:Redraws all of the content in a render object.

Invalidating a render object will cause everything within a specified area to be redrawn. This includes child render objects that intersect with the area that you have specified. Parent regions that overlap are not included in the redraw.

To quickly redraw an entire render object's content, call this method directly without supplying an argument structure. If you want to redraw a render object and ignore all of its render children then you should use the Draw action instead of this method.

If you want to refresh a rendered area to the display then you should use the Expose method instead. Exposing will use the graphics buffer to refresh the graphics, thus avoiding the speed loss of a complete redraw.


Method:MoveContent()
Short:Shifts the graphical content of a render object to a new position.
Arguments:
LONG XCoord  Horizontal coordinate of the source area.
LONG YCoord  Vertical coordinate of the source area.
LONG Width  Width of the source area.
LONG Height  Height of the source area.
LONG XDest  Horizontal destination within the render object.
LONG YDest  Vertical destination within the render object.
LONG ClipLeft  Clip restriction for the left edge.
LONG ClipTop  Clip restriction for the top edge.
LONG ClipRight  Clip restriction for the right edge.
LONG ClipBottom  Clip restriction for the bottom edge.
LONG Flags  Optional flags. MCF_IGNORECHILDREN will ignore all child drawables during the move process. MCF_INVALIDATE will invalidate any exposed areas rather than performing a complete redraw.

The MoveContent method provides the necessary functionality to shift the graphical content of a render object to a new location. The graphical area that you shift will be limited to the area available to the render object, i.e. other render objects that obscure the display of the target will not be affected by the shift of content.

In most cases, shifting the content of a render object will leave an uncovered area that will need to be redrawn. The routine will automatically redraw them for you by sending Draw messages to the render object.


Method:SetOpacity()
Synonym:SetRenderOpacity
Short:Alters the opacity of a render object.
Arguments:
DOUBLE Value  The new opacity value between 0 and 100% (ignored if you have set the Adjustment parameter).
DOUBLE Adjustment  Adjustment value to add or subtract from the existing opacity (set to zero if you want to set a fixed Value instead).

This method will change the opacity of the drawable and execute a redraw to make the changes to the display.

Result
ERR_Okay  The opacity of the render object was changed.
ERR_Args  Invalid arguments were specified.

Method:SetRenderCallback()
Synonym:SetCallback
Short:Allows you to hook into the drawing process of a rendered object.
Arguments:
LONG Data  32-bit data to be passed as the first argument to the draw function.
APTR Routine  Pointer to the callback routine.

The SetRenderCallback method is used to draw graphics to render areas. By hooking into the render object you will be able to draw to its Bitmap every time that the Draw action is executed. The render object will call the address specified in the Routine argument using the following function specification:

   void Draw(LONG Data, struct Render *Drawable, struct Bitmap *Bitmap)

The Data argument is a customised 32-bit parameter that you specify when calling the SetRenderCallback method for the first time. The Drawable argument refers to the address of the render object that you subscribed to. The Bitmap argument refers to the bitmap object that your graphics must be drawn to.

To draw to the render object, write to the bitmap surface as you would with any bitmap object (refer to the Bitmap class). To get the width and height of the available drawing space, please read the Width and Height fields from the Drawable object.

Result
ERR_Okay  Success
ERR_Args  Invalid arguments were specified.

Field:AbsX
Short:The absolute horizontal position of a render object.
Type:LONG
Status:Get/Set

If you need to know the absolute horiziontal position of a render object then you can read this field. The absolute value is calculated based on the render object's position relative to the top most render object in the local hierarchy.

It is possible to set this field, but only after initialisation of the render object has occurred.


Field:AbsY
Short:The absolute vertical position of a render object.
Type:LONG
Status:Get/Set

If you need to know the absolute vertical position of a render object then you can read this field. The absolute value is calculated based on the render object's position relative to the top most render object in the local hierarchy.

It is possible to set this field, but only after initialisation of the render object has occurred.


Field:Align
Short:This field allows you to align a rendered area within its owner.
Type:LONG/FLAGS
Prefix:ALIGN
Status:Read/Write

If you would like to set an abstract position for a drawable area, you can give it an alignment. This feature is most commonly used for horizontal and vertical centering, as aligning to the the edges of a rendered area is already handled by existing dimension fields. Note that setting the alignment over-rides any settings in related coordinate fields. Valid alignment flags are as follows:

BOTTOM
CENTER/MIDDLE
LEFT
HORIZONTAL
RIGHT
TOP
VERTICAL


Field:Bitmap
Short:Readable field that returns a pointer to a render object's drawable Bitmap.
Type:*Bitmap
Status:Get

In order to draw graphics to a render object, it is necessary to obtain a pointer to the drawable Bitmap. To get the correct pointer, you need to read this field while you have exclusive access to the render object.

Due to the way that the graphics system has been designed, the only time that you can safely draw to a render object is through the action notification scheme. This means that you have to tell the render object that you want to listen to the Draw action. When the render object receives a Draw action, it will notify all listeners by calling ActionNotify() for every connected object. When you receive notice, you can obtain the Bitmap and draw to it safely.

In all other situations, trying to retrieve the Bitmap will most likely result in a NULL value being returned.


Field:Bottom
Short:Returns the bottom-most coordinate of a render object.
Type:LONG
Status:Read

You can read this field to find out what the bottom-most coordinate of a render object is. This is basically the opposite of the YCoord field, and is calculated by adding the YCoord and Height fields together.


Field:BottomLimit
Short:Prevents a render object from moving beyond a given point at the bottom of its container.
Type:LONG
Status:Read/Write

You can prevent a render object from moving beyond a given point at the bottom of its container by setting this field. If for example you were to set the BottomLimit to 5, then any attempt to move the render object into or beyond the 5 units at the bottom of its container would fail.

Limits only apply to movement, as induced through the Move() action. This means that limits can be over-ridden by setting the coordinate fields directly (which can be useful in certain cases).


Field:BottomMargin
Short:Manipulates the bottom margin of a render object.
Type:LONG
Status:Read/Write

The Render class supports margin settings, which are similar to the concept of margins on printed paper. Margin values have no significant meaning or affect on a render object itself, but they are often used by other objects and can be helpful in interface construction. For instance, the Window template uses margins to indicate the space available for placing graphics and other render objects inside of it.

By default, all margins are set to zero when a new render object is created.


Field:Buffer
Short:If set to TRUE, buffering will be used when drawing a render object.
Type:LONG|BOOLEAN
Status:Get/Set

The Buffer field can be set to a value of TRUE if you wish to enable graphical buffering in a render object. This feature must be used on occasions where a graphical class needs read access to a render object's graphical area (for instance, translucency and alpha blended effects require read access). Buffering can also be used to eliminate flickering if a large amount of overlapped drawing is occurring.

Buffering can slow down drawing operations as it introduces an extra step to the drawing process (instead of drawing directly to the display, graphics objects will draw to a buffer, which is then blitted to the display on their behalf). On the other hand, buffering will almost always give dramatic speed increases when extensive read operations are taking place.

It is possible to check whether or not a render object is using buffering by reading this field, or by checking for the BUFFER bit in the Flags field.


Field:Colour
Short:String-based field for setting the background colour.
Type:STRING
Status:Set

If the render object should have a plain background colour, set this field to the colour value that you want to use. The colour must be specified in the standard format of '#RRGGBB' for hexadecimal or 'Red,Green,Blue' for a decimal colour.

Render objects that do not have a set colour will not be cleared when being drawn. This means that the background will consist of 'junk' graphics and it is your job to clear the background as you see fit. Either way, you have the power to choose the most appropriate drawing model to suit your needs.

If you set the Colour and later want to turn the background colour off, write a NULL value to the Colour field. Note that writing to the Colour field while a render object is on display will always cause a graphical redraw.


Field:ColourRGB
Short:An RGB based field for manipulating the background colour.
Type:RGB
Status:Get/Set

This RGB based field has the same properties as the Colour field but is manipulated using an RGB structure.


Field:Drag
Short:This object-based field is used to control the dragging of objects around the display.
Type:OBJECTID
Status:Read/Write

Allowing the user to drag objects around the display is a feature that no interface is complete without. The Drag field provides you with an easy way to set-up rendered areas that can be dragged around when the user clicks and holds an area while moving the pointing device around the display.

To use, simply write this field with a reference to an external Render object that is to be dragged when the user interacts with the object. For instance, if you create a window with a title-bar at the top, you would set the Drag field of the title-bar to point to the object ID of the window. If necessary, you can set the Drag field to point back to your render object (this can be useful for creating icons and other small items).

To turn off dragging, simply write back to the field with a NULL value.


Field:FastResize
Short:Enables fast resizing when set to TRUE.
Type:LONG|BOOLEAN
Status:Get/Set

Setting the FastResize field to TRUE enables fast resizing, a feature which can speed up the resizing process by eliminating any unnecessary redrawing.

By default, when a render object is resized it will be completely redrawn, so that all graphical objects dependent on the size of the drawable are displayed correctly. However, if the graphics inside the render object are not dependent on its size then this process will only waste time, especially if the rendered area is being shrunk. By enabling the FastResize option, the rendered area will never be redrawn when shrunk, and only exposed areas will be redrawn if the rendered area is being enlarged.


Field:Flags
Short:Special flags.
Type:LONG|FLAGS
Prefix:RNF
Status:Read

The Flags field allows you to set special options for a render object. Note that you must use the OR option when setting this field so that you do not overwrite any existing flags. Forgetting to do so will inevitably give you some head-scratching problems!

Here are the available flag settings:

FlagDescription
AFTERCOPYRead-only. Indicates that after-copy mode has been enabled.
AUTOQUITWhen this flag is set the render object will send a quit message to its supporting task when and if the Close method is called. This flag is typically used when a render object represents a core window for an application.
CLEARRead-only. This flag is automatically set if the render object has been asked to clear its background.
DISABLEDThis flag is set if the Disable action has been called on a render object. Calling the Enable action will turn off the flag setting.
HASFOCUSRead-only. If set, this flag indicates that the render object currently has the focus.
HOSTIf the render object is intended to host drawables from foreign processes, the host flag will be enabled.
INVISIBLEThis flag is turned on if the invisible option has been enabled (refer to the Invisible field). Note that invisibility in this sense means that the render object contains no drawable content. It does not mean that the render object has no representation on the display.
NOVERTICALTurns off all vertical movement (applies to the Move action only).
NOHORIZONTALTurns off all horizontal movement (applies to the Move action only).
PERVASIVECOPYThis flag can be set in conjunction with after-copy mode. It forces the after-copy support routine to copy graphics over the entire drawable area, rather than avoiding the graphics of child drawables.
PRECOPYRead-only. Indicates that pre-copy mode has been enabled.
REGIONRead/Init only. This flag is set if the Region option has been used.
SCROLLCONTENTIf set, the render object will send Move and MoveToPoint messages if the Scroll and ScrollToPoint actions are ever called on the object.
STICKTOBACKThis flag is turned on if the render object has been asked to stick to the back of its container (refer to the StickToBack field).
STICKTOFRONTThis flag is turned on if the render object has been asked to stick to the front of its container (refer to the StickToFront field).
STICKYSet the STICKY flag if you wish to prevent the render object from responding to the Move action.
VISIBLEIf a render object is visible to the user, the VISIBLE flag will be set. If the flag is not set, the render object is hidden.
VIDEOSet this flag if you would like the render object's data to be managed in video. While this can give some speed advantages, be warned that video based drawables are limited to write-only operations.

Field:Frame
Short:Manipulates the frame number that a render object has on display.
Type:LONG
Status:Read/Write

Through clever use of the Frame field, the graphics of a render object can be organised into individual frames that can be switched in-and-out of the display by updating the current frame number. To use the Frame field effectively you need to use frame-enabled objects and tell them what frames to group themselves into. You will also need a controlling object (e.g. an Animation object) or some other mechansim for manipulating the frame number. Here is an example that creates a basic animation based on frames:

  <render center width="20%" height="20%" colour="#a0a0a0">
    <animation speed="1" framecount="2"/>
    <box width="10" height="10" border="#000000" center frame="1">
    <ellipse width="10" height="10" center frame="2" border="#000000">
  </render>

Almost all graphical objects support frames, and other frame-control classes are available in the form of the Movement and OnClick classes, as well as others.

Please note that to see the results of a new Frame setting, you will need to redraw the render object.


Field:Height
Short:Defines the height of a render object.
Type:LONG/PERCENTAGE
Status:Read/Write

The height of a render object is manipulated through this field, although you can also use the Resize() action, which is faster if you need to set both the Width and the Height. You can set the Height as a fixed value by default, or as a relative value if you set the FD_PERCENT field. Relative heights are always calculated in relationship to a render object's container, e.g. if the container is 200 pixels high and render Height is 80%, then your render object will be 160 pixels high.

Setting the Height while a render object is on display causes an immediate graphical update to reflect the change. Any objects that are within the rendered area will be re-drawn and resized as necessary.

Height values of 0 or less are illegal, and will result in an ERR_OutOfRange error-code.


Field:Hide
Short:Set to TRUE to hide a render object from the display.
Type:BOOLEAN
Status:Init

You can decide whether a render object should be hidden or not by writing to this field prior to initialisation. Just set the field to TRUE and the render object will not show up on the display when you initialise it.

Note that after initialisation, the correct way to manage the visibility of a render object is to use the Hide and Show actions.


Field:Host
Short:If this field is enabled, the render object will be able to host drawables from foreign processes.
Type:LONG|BOOLEAN
Status:Get/Init

Setting the Host field to a value of TRUE allows you to create a render object that can contain render objects from foreign processes. This is a must for creating desktop areas where tasks will want to open their own windows. Failure to use the host option correctly will cause failures when foreign processes try to open drawables that connect with your task space.

Note that setting the host option forces the system to allocate a graphics buffer equal to the size of the rendered area. All drawable children will also be forced to allocate graphics buffers. Because this can be memory intensive, please do not use the host option lightly.


Field:InsideHeight
Short:Reflects the amount of space between the vertical margins.
Type:LONG
Status:Read

You can determine the internal height of a render object by reading the InsideHeight field. The returned value is the result of calculating this formula:

  Height - TopMargin - BottomMargin

If you have not set the TopMargin and/or BottomMargin fields, then the returned value will be equal to the render object's height.


Field:InsideWidth
Short:Reflects the amount of space between the horizontal margins.
Type:LONG
Status:Read

You can determine the internal width of a render object by reading the InsideWidth field. The returned value is the result of calculating this formula:

  Width - LeftMargin - RightMargin

If you have not set the LeftMargin and/or RightMargin fields, then the returned value will be equal to the render object's width.


Field:Invisible
Short:Defines a render object as being transparent (no drawable content).
Type:LONG|BOOLEAN
Status:Get/Set

If you need a render object to be completely transparent, set this field. This will make the render object invisible, causing the background of the parent drawable to show through. The render object will behave normally in every other respect.

While it is possible to draw graphics to transparent objects, this only works if you take the responsibility of graphics maintenance (in certain cases you may need to manually tell the render object when to redraw for instance).

Invisible objects are best used only in cases where you want to mount a collection of render objects inside a clearly defined rectangular area and have an advantage in maintaining low overhead. If you need more advanced handling for graphical transparent regions, set the Precopy field instead.


Field:LeftLimit
Short:Prevents a render object from moving beyond a given point on the left-hand side.
Type:LONG
Status:Read/Write

You can prevent a render object from moving beyond a given point at the left-hand side of its container by setting this field. If for example you were to set the LeftLimit to 3, then any attempt to move the render object into or beyond the 3 units at the left of its container would fail.

Limits only apply to movement, as induced through the Move() action. This means that you can override limits by setting the coordinate fields directly (which can be useful in certain cases).


Field:LeftMargin
Short:Manipulates the left margin of a render object.
Type:LONG
Status:Read/Write

The Render class supports margin settings, which are similar to the concept of margins on printed paper. Margin values have no significant meaning or affect on a render object itself, but they are often used by other objects and can be helpful in interface construction. For instance, the Window template uses margins to indicate the space available for placing graphics and other render objects inside of it.

By default, all margins are set to zero when a new render object is created.


Field:MaxHeight
Short:Prevents the height of a render object from exceeding a certain value.
Type:LONG
Status:Read/Set

You can limit the maximum height of a render object by setting this field. Limiting the height affects resizing, making it impossible to use the Resize() action to extend beyond the height you specify.

It is possible to circumvent the MaxHeight by setting the Height field directly. Note that the MaxHeight value refers to the inside-height of the drawable area, thus the overall maximum height will include both the TopMargin and BottomMargin values.


Field:MaxWidth
Short:Prevents the width of a render object from exceeding a certain value.
Type:LONG
Status:Read/Set

You can limit the maximum width of a render object by setting this field. Limiting the width affects resizing, making it impossible to use the Resize() action to extend beyond the width you specify.

It is possible to circumvent the MaxWidth by setting the Width field directly. Note that the MaxWidth value refers to the inside-width of the drawable area, thus the overall maximum width will include both the LeftMargin and RightMargin values.


Field:MinHeight
Short:Prevents the height of a render object from shrinking beyond a certain value.
Type:LONG
Status:Read/Set

You can prevent the height of a render object from shrinking too far by setting this field. This feature specifically affects resizing, making it impossible to use the Resize() action to shrink the height of a render object to a value less than the one you specify.

It is possible to circumvent the MinHeight by setting the Height field directly.


Field:MinWidth
Short:Prevents the width of a render object from shrinking beyond a certain value.
Type:LONG
Status:Read/Set

You can prevent the width of a render object from shrinking too far by setting this field. This feature specifically affects resizing, making it impossible to use the Resize() action to shrink the width of a render object to a value less than the one you specify.

It is possible to circumvent the MinWidth by setting the Width field directly.


Field:Movement
Short:Limits the movement of a render object to vertical or horizontal shifts.
Type:LONG|FLAGS
Prefix:MOVE_
Status:Read/Set

You can limit the movement of a render object by setting the flags in the Movement field. By default, a render object is capable of moving in all directions. By altering this field, you can restrict the movement of a render object to a specific direction. There are three possible flag combinations:

   HORIZONTAL           Horizontal movement only.
   VERTICAL             Vertical movement only.
   HORIZONTAL|VERTICAL  Permit movement in all directions.

This field is only effective in relation to the Move action, and it is possible to circumvent the restrictions by setting the coordinate fields directly.


Field:Opacity
Short:Affects the level of translucency applied to a render object.
Type:FLOAT
Status:Get/Set

This field determines the translucency level of a drawable area. The default setting is 100%, which means that the drawable will be solid. Any other value that you set here will alter the impact of a drawable over its destination area. High values will retain the boldness of the graphics, while low values can render it close to invisible.

Note: The translucent drawing routine works by drawing the render content to its internal buffer first, then copying the graphics that are immediately in the background straight over the top with an alpha-blending routine. This is not always ideal and you can sometimes get better results by using the pre-copy option instead (see the Precopy field).

Please note that the use of translucency is realised at a significant cost to the CPU's time.


Field:Precopy
Short:Enables the masking feature for render objects.
Type:LONG|BOOLEAN
Status:Get/Set

If you need a render object to use masked or blended graphics, set this field. Enabling the precopy option allows you to draw graphics into your render object with all the graphics immediately behind the drawable pre-copied into the drawing buffer.

Precopying is commonly used for creating icons, designer windows and alpha blending effects.

If you are not going to draw graphics into the drawable area, you should use the Invisible option to allow the background to show through. Precopying introduces an extra step in the drawing process which is realised at a cost of CPU time.


Field:Region
Short:Specifies whether or not a render object is acting as a simple region.
Type:LONG|BOOLEAN
Status:Get/Set

Setting the Region field to a value of TRUE allows you to create render objects that act as basic drawable regions. Region based render objects are identical to normal render objects in most respects, except they do not participate in the layered drawing process. This means that they are susceptible to the influence of other graphics within their parent object, because they are treated no differently to Box, Text or other graphical class types.

Region based render areas are most useful when you can sacrifice functionality for speed. Buttons, menu content and title bars are often implemented as regions because they are small and consist of only a small group of graphical objects.

Depending on the arrangement of the region and parent object's graphics, drawing around regions can cause flickering. Use of the Buffer option can avoid this problem if it becomes an issue.


Field:Right
Short:Returns the right-most coordinate of a render object.
Type:LONG
Status:Read

You can read this field to find out what the right-most coordinate of a render object is. This is basically the opposite of the XCoord field, and is calculated by adding the XCoord and Width fields together.


Field:RightLimit
Short:Prevents a render object from moving beyond a given point on the right-hand side.
Type:LONG
Status:Read/Write

You can prevent a render object from moving beyond a given point at the right-hand side of its container by setting this field. If for example you were to set the RightLimit to 8, then any attempt to move the render object into or beyond the 8 units at the right-hand side of its container would fail.

Limits only apply to movement, as induced through the Move() action. This means that limits can be over-ridden by setting the coordinate fields directly (which can be useful in certain cases).


Field:RightMargin
Short:Manipulates the right margin of a render object.
Type:LONG
Status:Read/Write

The Render class supports margin settings, which are similar to the concept of margins on printed paper. Margin values have no significant meaning or affect on a render object itself, but they are often used by other objects and can be helpful in interface construction. For instance, the Window template uses margins to indicate the space available for placing graphics and other render objects inside of it.

By default, all margins are set to zero when a new render object is created.


Field:RouteFocus
Short:Diverts render focussing through a specific path.
Type:OBJECTID
Status:Read/Set

As the user manipulates the objects on the screen display, focus messages are sent to individual objects to let them know when they have received or have lost the focus. If you are creating an interface with complex focus management, then you may need to use the RouteFocus field for some render objects.

The RouteFocus field alters the path that is normally taken when a collection of objects receive focus messages. To illustrate by example, take the following hierarchy of render objects:

  SystemDisplay
    Render1
      Render1.1
      Render1.2
      Render1.3
        Render1.3.1
    Render2
      Render2.1
    Render3

Imagine that the SystemDisplay object currently has the focus, then the user clicks on render object 1.3.1, which represents a button. This causes the primary focus to be immediately set to 1.3.1, then focus notifications are sent to Render1.3 and Render1, because they are immediate parents of 1.3.1. Notification is not sent to the SystemDisplay, because prior to the user-click, the SystemDisplay object already had the focus. This particular example illustrates the normal chain of events when a new object takes the focus.

However, this is not suitable if a render object needs to form part of a focus chain when it lies outside of the normal hierachy. Imagine that Render2 represents a menu, and Render1 is a window. Clicking on Render2 will cause Render1 to lose the focus, which is innapropriate because the menu should be closely linked to the application represented by the window. To fix this, we set the RouteFocus field belonging to the Render2 object to point to Render1. By doing this, after Render2 receives the focus the algorithm will be diverted down a different path, thus 'fooling' Render1 into believing that one of its immediate children has the focus.

Focus routing is a rarely used feature, but can be vital in building complex interfaces that do not follow a hierarchical GUI structure. You can see many examples of focus routing being used in Athene's menu system.


Field:StickToBack
Short:Set to TRUE if you want a render object to stick to the back of its container.
Type:LONG|BOOLEAN
Status:Set

If you want a render object to stick to the back of its container, set this field to TRUE. When a render object is stuck to the back, other objects will not be allowed to move behind it when the MoveToBack action is called on them.

Note that use of the StickToBack option is no guarantee that a render object will remain at the very back of its container (there may be other objects also using the StickToBack option).


Field:StickToFront
Short:Set to TRUE if you want a render object to stick to the front of its container.
Type:LONG|BOOLEAN
Status:Set

If you want a render object to stick to the front of its container, set this field to TRUE. When a render object is stuck to the front, other objects will not be allowed to move in front of it when the MoveToFront action is called on them.

Note that use of the StickToFront option is no guarantee that a render object will remain at the very front of its container (there may be other objects also using the StickToFront option).


Field:Sticky
Short:Set this field to TRUE to prevent a render object from being moved around.
Type:LONG|BOOLEAN
Status:Get/Set

When the Sticky field is set to TRUE, any attempts to Move the object will fail, which causes the object to stick to its position. This feature is typically used on objects that should hold their position under most circumstances, e.g. buttons and icons.

It is possible to circumvent the Sticky field by writing to the coordinate fields directly.


Field:TopLimit
Short:Prevents a render object from moving beyond a given point at the top of its container.
Type:LONG
Status:Read/Write

You can prevent a render object from moving beyond a given point at the top of its container by setting this field. If for example you were to set the TopLimit to 10, then any attempt to move the render object into or beyond the 10 units at the top of its container would fail.

Limits only apply to movement, as induced through the Move() action. This means that limits can be over-ridden by setting the coordinate fields directly (which can be useful in certain cases).


Field:TopMargin
Short:Manipulates the top margin of a render object.
Type:LONG
Status:Read/Write

The Render class supports margin settings, which are similar to the concept of margins on printed paper. Margin values have no significant meaning or affect on a render object itself, but they are often used by other objects and can be helpful in interface construction. For instance, the Window template uses margins to indicate the space available for placing graphics and other render objects inside of it.

By default, all margins are set to zero when a new render object is created.


Field:UserFocus
Short:Refers to the render object that has the current focus.
Type:OBJECTID
Status:Get

This readable field will tell you the drawable object that has the current user focus (within the context of the object hierarchy). If no object has the user's focus, this field will return a value of NULL.


Field:VisibleHeight
Short:Reflects the visible height of a rendered area within its container.
Type:LONG
Status:Read

Sometimes it can be useful to know how much of a rendered area is visible to the user and how much is obscured or clipped by its container. The easiest way to ascertain the visibility level is to read the VisibleWidth and VisibleHeight fields which do the necessary calculations for you.

If none of the rendered area is visible then zero is returned, otherwise the amount of visible units are returned back to you. The returned value is always positive.


Field:VisibleWidth
Short:Reflects the visible width of a rendered area within its container.
Type:LONG
Status:Read

Sometimes it can be useful to know how much of a rendered area is visible to the user and how much is obscured or clipped by its container. The easiest way to ascertain the visibility level is to read the VisibleWidth and VisibleHeight fields, which do the necessary calculations for you.

If none of the rendered area is visible then zero is returned, otherwise the amount of visible units are returned back to you. The returned value is always positive.


Field:Visible
Short:Indicates the visibility of a render object.
Type:LONG|BOOLEAN
Status:Get/Set

If you need to know if a render object is visible or hidden, you can read this field to find out either way. A TRUE value is returned if the object is visible and FALSE is returned if the object is invisible. Note that visibility is subject to the properties of the container that the render object resides in. For example, if a render object is visible but is contained within a render object that is invisible, the end result is that both objects are actually invisible.

Visiblity is directly affected by the Hide and Show actions if you wish to change the visiblity of a render object.


Field:Width
Short:Defines the width of a render object.
Type:LONG/PERCENTAGE
Status:Read/Write

The width of a render object is manipulated through this field, although you can also use the Resize() action, which is faster if you need to set both the Width and the Height. You can set the Width as a fixed value by default, or as a relative value if you set the FD_PERCENT field. Relative widths are always calculated in relationship to a render object's container, e.g. if the container is 200 pixels wide and render Width is 80%, then your render object will be 160 pixels wide.

Setting the Width while a render object is on display causes an immediate graphical update to reflect the change. Any objects that are within the rendered area will be re-drawn and resized as necessary.

Width values of 0 or less are illegal, and will result in an ERR_OutOfRange error-code.


Field:WindowHandle
Short:Refers to a render object's window handle, if relevant.
Type:LONG
Status:Get/Init

This field refers to the window handle of a render object, but only if such a thing is relevant to the platform that the system is running on. Currently, this field is only usable when creating a primary render object within an X11 window manager or Microsoft Windows.

It is possible to set the WindowHandle field prior to initialisation if you want a render object to be based on a window that already exists.


Field:X
Synonyms:X
Short:Determines the horizontal position of a render object.
Type:LONG/PERCENTAGE
Status:Read/Write

The horizontal position of a render object can be set through this field. You have the choice of setting a fixed coordinate (the default) or a relative coordinate if you use the FD_PERCENT flag.

If you set the XCoord while the render object is on display, the position of the rendered area will be updated immediately.


Field:XOffset
Short:Determines the horizontal offset of a render object.
Type:LONG/PERCENTAGE
Status:Read/Write

The XOffset has a dual purpose depending on whether or not it is set in conjunction with the XCoord or Width fields.

If set in conjunction with the XCoord field, the width of the render object 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 render object is dynamically calculated in relation to the width of its container.

If the XOffset field is set in conjunction with a fixed or relative width then the render object will be positioned at an X coordinate calculated from the formula "XCoord = ContainerWidth - RenderWidth - XOffset".


Field:YCoord
Synonyms:Y
Short:Determines the vertical position of a render object.
Type:LONG/PERCENTAGE
Status:Read/Write

The vertical position of a render object can be set through this field. You have the choice of setting a fixed coordinate (the default) or a relative coordinate if you use the FD_PERCENT flag.

If you set the YCoord while the render object is on display, the position of the rendered area will be updated immediately.


Field:YOffset
Short:Determines the vertical offset of a render object.
Type:LONG/PERCENTAGE
Status:Read/Write

The YOffset has a dual purpose depending on whether or not it is set in conjunction with the YCoord or Height fields.

If set in conjunction with the YCoord field, the height of the render object 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 render object is dynamically calculated in relation to the height of its container.

If the YOffset field is set in conjunction with a fixed or relative height then the render object will be positioned at a Y coordinate calculated from the formula "YCoord = ContainerHeight - RenderHeight - YOffset".