Class Documentation

Name:Render
Version:1.0
ID:ID_RENDER
Status:Beta
Category:GUI
Date:October 2001
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 2000-2001. 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 object. 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.
Draw  Redraws the contents of a 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.
Resize  Resizes a Render object's dimensions.
SaveImage  Saves the graphical image of a Render object.
Scroll  Tells a Render object to scroll its contents.
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.

Structure

The Render object consists of the following public fields:

AmtColours  Tells you the total amount of colours available to the Render object.
Bitmap  Readable field that returns a pointer to the drawable Bitmap.
BitsPerPixel  Tells you the number of bits-per-pixel used by the Render object.
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.
BytesPerPixel  Tells you the number of bytes-per-pixel used by the Render object.
Children  A sorted list of Render objects that have been declared as children of the parent.
Colour  String-based field for setting the background colour.
ColourRGB  RGB-based field for manipulating the background colour.
Drag  This object-based field is used to control the dragging of objects around the display.
Flags  Special flags.
Frame  Manipulates the frame number that the Render object has on display.
Height  Defines the height of a Render object.
Hide  Set to TRUE to hide the Render object from the display.
InsideHeight  Reflects the amount of space between the vertical margins.
InsideWidth  Reflects the amount of space between the horizontal margins.
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.
Mask  String-based field for setting the masking colour of the rendered graphic.
MaskRGB  RGB-based field for manipulating the masking colour of the rendered graphic.
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 the Render object to vertical or horizontal shifts.
Resize  This object-based field is used to control graphics resizing.
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 the Render object to stick to the back of its container.
StickToFront  Set to TRUE if you want the Render object to stick to the front of its container.
Sticky  Set this field to TRUE to prevent the 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.
XClient  Special field used for X11 based Athene systems.
XCoord  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. If the Render object contains other Render objects, those objects will not be included in the resulting image data.

The image data will be saved in the data format that is indicated by your file extension, if the destination object supports a Location field. If the extension does not reflect a supported file format of the Picture class, the default image format will be used to save the data.

 

Action:Scroll
Short:Tells a Render object to scroll its contents.

Calling the Scroll action on a Render object 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.

 

Field:AmtColours
Short:Tells you the total amount of colours available to the Render object.
Type:LONG
Status:Read

If you need to know the total amount of colours available to a Render object then you can read this field. Common return values are 256, 32768, 65536, and 16777216.

 

Field:Bitmap
Short:Readable field that returns a pointer to the drawable Bitmap.
Type:*Bitmap
Status:Read

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:BitsPerPixel
Short:Tells you the number of bits-per-pixel used by the Render object.
Type:LONG
Status:Read

This low-level field tells you the total number of bits-per-pixel (BPP) used for each pixel in the Render object. The number is closely tied to the amount of colours used - for instance 15 bits equals 32,768 colours, 16 bits equals 65,526 colours and so forth. The only time when the BitsPerPixel setting bears no relationship to the number of colours are when extra bits are being used for colour management.

 

Field:Bottom
Short:Returns the bottom-most coordinate of a Render object.
Type:FLOAT
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:FLOAT
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:FLOAT
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:BytesPerPixel
Short:Tells you the number of bytes-per-pixel used by the Render object.
Type:LONG
Status:Read

This low-level field tells you the total number of bytes used for each pixel in the Render object. For instance, if 16.8 million colours are used then you will most likely get a return value of 3. The BytesPerPixel field is a reflection of the graphics display, so there is no way for an individual Render object to have a different BytesPerPixel setting than that of the Screen it belongs to.

 

Field:Children
Short:A sorted list of Render objects that have been declared as children of the parent.
Type:struct RenderChild *
Status:Get

To obtain a list of drawable class objects that have been initialised as children of a rendered area, read this field. The returned pointer is an array of RenderChild structures that represent each child object. The list is sorted from the bottom-most to top-most objects, with non-drawable classes at the start of the list and rendered areas at the end. The list is terminated by a final entry that has all fields set to NULL.

The RenderChild structure is arranged as follows:

   struct RenderChild {
      OBJECTID ObjectID;    The unique ID of the object.
      CLASSID  ClassID;     The class that owns the object.
   }

 

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

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 the Render object is on display will always cause a graphical re-draw.

 

Field:ColourRGB
Short:RGB-based field for manipulating the background colour.
Type:RGB
Status:Read

This RGB-based field has the same properties as the Colour field but is manipulated using RGB structures.

 

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:Flags
Short:Special flags.
Type:LONG/FLAGS
Prefix:RNF
Status:Read

The Flags field is currently a read-only value that reflects special options that have been turned on for a Render object. Here are the flag settings:

FlagDescription
MASKThis flag is turned on if the masking option has been enabled (refer to the Mask and MaskRGB fields).
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).
REVERSEHEIGHT  Setting this flag causes the resizing of the Render object's height to be made in reverse. For example, if the height is extended from 40 to 50, the extra 10 units will be added to the top rather than the bottom of the drawable area. This flag affects settings made to the Height field as well as calls to the Resize action.
REVERSEWIDTHSetting this flag causes the resizing of the Render object's width to be made in reverse. For example, if the width is extended from 85 to 100, the extra 15 units will be added to the left rather than the right of the drawable area. This flag affects settings made to the Width field as well as calls to the Resize action.

 

Field:Frame
Short:Manipulates the frame number that the 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:FLOAT/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 the Render object from the display.
Type:BOOLEAN
Status:Init

You can decide whether the 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:InsideHeight
Short:Reflects the amount of space between the vertical margins.
Type:FLOAT
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:FLOAT
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:LeftLimit
Short:Prevents a Render object from moving beyond a given point on the left-hand side.
Type:FLOAT
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 limits can be over-ridden 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:FLOAT
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:Mask
Short:String-based field for setting the masking colour of the rendered graphic.
Type:STRING
Status:Write

If the Render object is to be masked (that is, the rendered area should not be confined to a rectangular shape) then set this field to the colour that is to be used for the mask. Any pixel in the Render object matching that colour will be 'invisible', meaning that anything underneath that area will show through the Render object.

Masking is commonly used for small rendered objects such as icons, but if necessary it can be applied to much larger graphics areas, even windows. Masks are dynamic, so every time that the Render object is redrawn, the mask will be recalculated. Dynamic masking is particularly useful for animated graphics.

Masking can be turned off by writing the Mask field with a NULL value.

 

Field:MaskRGB
Short:RGB-based field for manipulating the masking colour of the rendered graphic.
Type:RGB
Status:Read/Write

This is the RGB equivalent of the Mask field. Refer to it for more detail on how masking works.

 

Field:MaxHeight
Short:Prevents the height of a Render object from exceeding a certain value.
Type:FLOAT
Status:Read/Write

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.

 

Field:MaxWidth
Short:Prevents the width of a Render object from exceeding a certain value.
Type:FLOAT
Status:Read/Write

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.

 

Field:MinHeight
Short:Prevents the height of a Render object from shrinking beyond a certain value.
Type:FLOAT
Status:Read/Write

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:FLOAT
Status:Read/Write

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 the Render object to vertical or horizontal shifts.
Type:LONG/FLAGS
Prefix:MOVE_
Status:Write

You can limit the movement of a Render object by setting the movement flags. By default, a Render object is capable of moving in all directions but often there are times when you want to limit movement to just one direction. You can set the Movement field to one of three possible combinations:

   HORZIONTAL           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:Resize
Short:This object-based field is used to control graphics resizing.
Type:OBJECTID
Status:Read/Write

The Resize field allows you to create a Render object that performs resizing when the user clicks on the object and then moves the pointing device around the display. The functionality is similar to the Resize class but only provides basic support - e.g. an area definition cannot be set, and you cannot restrict the direction of the resize.

To use, simply write this field with a reference to an external Render object that is to be resized when the user interacts with the object. For instance, if you create a window with a resize gadget at the bottom right, you would set the Resize field of the gadget to point to the object ID of the window. If necessary, you can set the Resize field to point back to your Render object, although such use would be considered unusual.

To turn off resizing, you can write the field with a NULL value.

 

Field:Right
Short:Returns the right-most coordinate of a Render object.
Type:FLOAT
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:FLOAT
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:FLOAT
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/Init

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, and 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, but lies outside of the primary hierachy. Imagine that Render2 represents a menu, and Render1 is a window. Clicking on Render2 will cause Render1 to lose the focus, which is not what we want to happen 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 examples of focus routing being used in Athene's menu system (refer to templates:menu.dml for a real-world example).

 

Field:StickToBack
Short:Set to TRUE if you want the Render object to stick to the back of its container.
Type:BOOLEAN
Status:Write

If you want the 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 the 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 the Render object to stick to the front of its container.
Type:BOOLEAN
Status:Write

If you want the 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 the 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 the Render object from being moved around.
Type:BOOLEAN
Status:Read/Write

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:FLOAT
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:FLOAT
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:Read

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:FLOAT
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:FLOAT
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:BOOLEAN
Status:Read

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:FLOAT/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:XClient
Short:Special field used for X11 based Athene systems.
Type:LONG
Status:Read/Write

Note: This field applies to X11 based Athene systems only.

If a Render object contains an X11 client window, this field will refer to the ID of that X Window. In most cases you will only ever need to use this field if you need to interact with an X11 client. In all other cases you should avoid using it as it is considered to be an internal field for supporting window management.

 

Field:XCoord
Synonyms:X
Short:Determines the horizontal position of a Render object.
Type:FLOAT/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:FLOAT/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:FLOAT/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:FLOAT/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".