Class Documentation

Name:View
Version:1.0
ID:ID_VIEW
Status:In Development
Category:GUI
Date:January 2004
Author:Rocklyte Systems
Copyright:  Rocklyte Systems, 2003-2004. All rights reserved.
Short:  The View class is used to display XML data in a number of possible formats to the user.



Description

The View is an interface class that is designed to ease the display and management of multiple items within a container. It is capable of displaying items in a number of formats, including a simple list, tree view and column view. The ability to sort data and handle different types of data such as date and time information is provided. The View class is commonly used for file display and certain classes such as the FileView are dependent on the functionality that it provides.

Items are created and stored within each View as a large XML statement and are managed via the XML class. This simplifies the creation and retrieval of item data and also allows you to develop hierarchies and tree structures for complex item arrangement.

The View class inherits the fields and functionality of the XML class, which you can use for scanning view items after they have been added. The Font class is also inherited, allowing you to set details such as the default font face through the view.

When the user double-clicks on a view item, the object will activate itself. Once activated, the view object will send Activate actions on to any children that have been initialised to the view. This allows you to develop a response for user interaction with the view. If the sensitive option has been enabled as one of the Flags attributes, activation will occur whenever the user selects a file (thus single clicks will be enough to cause object activation).

Actions

The View class supports the following actions:

Clear  Clears a view of all internal content and updates the display.
DataChannel  Items can be added to the view using data channels.
Disable  Disables the view.
Enable  Enables a view that has been disabled.
Focus  Activates keyboard monitoring (by force).
GetUnlistedField  Special field types are available via unlisted field support.
Hide  Hides the view from the display.
LostFocus  Deactivates keyboard monitoring (by force).
Refresh  Refreshes the display.
ScrollToPoint  Scrolls the graphical content of a view.
Show  Redisplays the view if it has been hidden.
Sort  Resorts XML data in the view when it has been manually altered.
UserClick  User-click emulations can be passed through this action.
UserClickRelease  User-click emulations can be passed through this action.
UserMovement  User movement emulations can be passed through this action.

Methods

The View class implements the following methods:

CacheIcon  Caches icons in the View object.
InvertSelection  Inverts all currently selected items in the view.
RemoveViewItem  Removes an item from the view.
RemoveViewTag  Removes an XML tag without updating the view (for optimisation only).
SelectAll  Selects all items in the view for the user.
SelectItem  Manually select items for the user.
SelectNone  Deselects all currently selected items.
SetViewItem  Changes the attributes of any item in the view.
SortColumn  Sorts the view by column.
SortColumnIndex  Sorts the view by column (index).

Structure

The View object consists of the following public fields:

BorderOffset  Sets the X, Y, XOffset and YOffset to a single value.
Columns  Active columns for 'column mode' may be set via this field.
DateFormat  Sets the format to use when displaying date types.
HScroll  If scrolling is required, use this field to refer to a horizontal scroll bar.
Height  Defines the height of a view.
HighlightColour  Defines the colour when an item is selected via mouse-over or user focus.
ItemColour  The default font colour to use for view items.
SelectColour  Defines the colour when an item is selected via mouse-over or user focus.
SelectedTags  Returns an array of tag indexes for all currently selected items.
Selection  Indicates the currently selected file or directory.
SelectionIndex  Indicates the index number of the currently selected file or directory.
Style  The style of view that is displayed to the user is configured here.
TotalSelected  The total number of currently selected items.
VScroll  If scrolling is required, use this field to refer to a vertical scroll bar.
Width  Defines the width of a view.
XCoord  The horizontal position of a view.
XOffset  The horizontal offset of a view.
YCoord  The vertical position of a view.
YOffset  The vertical offset of a view.
Action:DataChannel
Short:Items can be added to the view using data channels.

To add new items to a view, it is recommended that you use the data channel system. New items can be added as raw text or as a series of XML statements.

When DATA_TEXT data is sent to a view, it will be added as a single item to the view list. You will need to send multiple fragments of text data if you need to more than one item using this method.

DATA_XML information is supported in an abstract fashion. Each root tag that you pass to the view will be interpreted as a new item. Child items within each root tag will be interpreted as extra information, to be used in certain view types such as column mode (please refer to the Columns field for further information on special tag types). Special attributes may also be set in each root tag for interpretation by the view object. Currently the "icon" attribute is available for defining the icon that should be displayed against the item when icon graphics are enabled in the view.

The following example demonstrates the XML code that the FileView class uses to add new files to view objects:

  <file icon="filetypes/audio">audio.wav
    <size sort="0002106">2106</size>
    <date>20031118 14:10:32</date>
  </file>

The content of the root tag, in this case "audio.wav" is used as the item text. An icon has been specified to accompany the item. The size and date tags are special tag types that are specific to column mode and will be ignored when not in use.


Action:GetUnlistedField
Short:Special field types are available via unlisted field support.

The View class supports the following field types via the unlisted field mechanism:

Selection(Index,Attribute) Returns the content of the selection at the requested Index (the Index value may not exceed the value in the TotalSelected field). The Attribute parameter is optional. It should be specified if there is a certain XML attribute that you want to read instead of the default item content.

Active(Attribute) Returns the content of the most recently active item. The most recently active item is defined as the one that the user has most recently clicked on or activated. The item does not necessarily have to be selected.


Action:Refresh
Short:Refreshes the display.

Calling the Refresh action will update the view so that its display reflects the most current data in its XML definition. A request for a complete redraw of the view will be posted to the view's drawable.

Use of the Refresh action is most useful if you directly update the XML content of the view without its knowledge.


Method:CacheIcon()
Short:Caches icons in the View object.
Arguments:
STRING Icon  The icon that you want to cache. Use the format "category/icon".

The CacheIcon method is used for pre-caching commonly used icons in a view object. It is particularly useful in large views that repeat the same icon for multiple items. Pre-caching an icon can be useful if you clear the view on a regular basis and do not want to re-load commonly used icons on each refresh.

The icon must be referenced using the string format "category/icon".

Result
ERR_Okay  Operation successful.
ERR_Args  The Icon argument was not specified.
ERR_ArrayFull  The cache is at maximum capacity.

Method:InvertSelection()
Short:Inverts all currently selected items in the view.

This method will invert the selections in the view, so that selected items become deselected and all other items are selected. The view will be redrawn as a result of calling this method.


Method:RemoveViewItem()
Synonym:RemoveItem
Short:Removes an item from the view.
Arguments:
LONG ID  The ID of the item that you want to remove, or -1 if you want to use a TagIndex.
LONG TagIndex  The index of the XML tag that you want to remove (ID must be -1). Ignored if the ID is set to any other value.

Use the RemoveViewItem() method to remove an item from the view. This method is provided mostly for script usage, as it can be faster to talk to the XML object directly and use the Refresh action than to make multiple calls to RemoveViewItem().

In order to call RemoveViewItem() successfully, you should have an awareness of the XML tag structure that you have used for creating the view items. You will need to pass the ID of the item that you want to update (thus you must have used the 'id' parameter when constructing the original XML tags), the name of tag to change (NULL is acceptable for the default) and the attribute to set (NULL is acceptable to change the XML content that represents the item data). The new string to be set is defined in the Value parameter.

If you update the content of an item by passing a NULL Attrib value, then a completely redraw of the view will occur so that the display accurately reflects the view data.

Result
ERR_Okay  Operation successful.
ERR_Args  The Icon argument was not specified.

Method:RemoveViewTag()
Synonym:RemoveTag
Short:Removes an XML tag without updating the view (for optimisation only).
Arguments:
LONG TagIndex  The index of the XML tag that you want to remove.

Use the RemoveViewTag() method to delete an XML tag without updating the view display. This method is recommended for optimisation purposes only, and serves as a replacement for the XML version of this method, RemoveXMLTag(). By using this method you can correctly delete an XML tag without having adverse affects on the view (e.g. if the tag is associated with an icon, the icon will be deallocated from the system).

Result
ERR_Okay  Operation successful.
ERR_Args  The Icon argument was not specified.

Method:SelectAll()
Short:Selects all items in the view for the user.

This method will select all items in the view, as if the user had selected them himself. The view will be redrawn as a result of calling this method.


Method:SelectItem()
Short:Manually select items for the user.
Arguments:
STRING Tag  The name of the tag that you want to scan for in each item. If not set, the default tag will be scanned.
STRING Item  The string that you want to match against for item selection.

The SelectItem method is used to manually select items in the view for the benefit of the user. To select an item you need to indicate the name of the XML tag that you want to scan for, and the item string that will be used for finding the correct item.

To illustrate correct usage of this method, imagine that you have filled the view with a series of tags similar to the following one:

  <file icon="filetypes/audio">audio.wav
    <size sort="0002106">2106</size>
    <date>20031118 14:10:32</date>
  </file>

To select the first audio item we could use a Tag of 'file' and an item of 'audio.wav'. If we want to make the selection based on the icon, we would use a Tag of 'file:icon' and an item of 'filetypes/audio'. Note the use of the colon character to indicate the name of the tag attribute in this case. We could also scan for the size and date tags simply by specifying those names in the Tag field.

In the event that multiple tags could match the given parameters, only the first tag will be selected by the selection routine. If there is a high probability that the data strings are repeated, you should implement a unique ID for each tag and use that for the selection of specific tags.

Note that selections are inclusive with other selections when in MULTISELECT mode. Use the Clear action first if you want the selection to be the only selected item in the list.

Result
ERR_Okay  The item was selected successfully.
ERR_Args  Invalid arguments were specified.

Method:SelectNone()
Short:Deselects all currently selected items.

This method will deselect all items in the view, as if the user had deselected them himself. The view will be redrawn as a result of calling this method.


Method:SetViewItem()
Synonym:SetItem
Short:Changes the attributes of any item in the view.
Arguments:
LONG ID  The ID of the item that you want to set. Set to -1 if you want to use a tag index.
LONG TagIndex  The index of the XML tag that you want to set. The ID must be set to -1. Ignored if the ID is set to any other value.
STRING Tag  The name of the child tag that you want to set within the item. Set to NULL for the default tag.
STRING Attrib  The name of the attribute that you want to set in the XML tag. May be NULL to set the tag's content.
STRING Value  The value that you want to set against the attribute.

Use the SetViewItem() method to change the attributes of items that are in in the view. This method is provided mostly for script usage, as it can be faster to talk to the XML object directly and use the Refresh action than to make multiple calls to this method.

In order to call SetViewItem() successfully, you should have an awareness of the XML tag structure that you have used for creating the view items. You will need to pass the ID of the item that you want to update (thus you must have used the 'id' parameter when constructing the original XML tags), the name of tag to change (NULL is acceptable for the default) and the attribute to set (NULL is acceptable to change the XML content that represents the item data). The new string to be set is defined in the Value parameter.

If you update the content of an item by passing a NULL Attrib value, then a completely redraw of the view will occur so that the display accurately reflects the view data.

Result
ERR_Okay  The item was set successfully.
ERR_Args  Invalid arguments were specified.
ERR_Search  The index, tag and/or attrib values did not lead to a match.

Method:SortColumn()
Short:Sorts the view by column.
Arguments:
STRING Column  The name of the column you want to sort by.
LONG Descending  Set to TRUE if the sort should be descending.

The SortColumn routine will sort the View on the column name that you indicate. The sort will be ascending by default, which you can reverse by setting the Descending parameter to TRUE. The View will automatically redraw itself to reflect the newly sorted content.

This method will fail if the referenced column does not exist. Use a Column value of NULL if you want to sort on item content by default (useful if you have not defined any columns for the view).

Result
ERR_Okay  The column was sorted successfully.
ERR_Args  Invalid arguments were specified.
ERR_Search  The referenced column could not be found.

Method:SortColumnIndex()
Short:Sorts the view by column (index).
Arguments:
LONG Column  The index of the column that you want to sort by (starts from zero).
LONG Descending  Set to TRUE if the sort should be descending.

The SortColumnIndex() method will sort the view by the column index that you indicate. The sort will be ascending by default, which you can reverse by setting the Descending parameter to TRUE. The view will automatically redraw itself to reflect the newly sorted content.

This method will fail if the referenced index is invalid. Both hidden and visible columns are taken into account when determining the column that the index refers to.


Field:BorderOffset
Short:Sets the X, Y, XOffset and YOffset to a single value.
Type:LONG
Status:Set

This field is provided for the convenience of setting the X, Y, XOffset and YOffset fields in one hit. The value that you specify will be written to all of the aforementioned fields as a fixed pixel-width value.


Field:Columns
Short:Active columns for 'column mode' may be set via this field.
Type:STRING
Status:Get/Set

When a view object is in column or tree mode (as defined in the Style field), you need to tell the view object what XML tags should be translated into column areas. Failure to register any column names means that only the default column will be displayed. Examine the following XML structure:

  <file>
    readme.txt
    <size>19431</size>
    <date>20030503 11:53:19</date>
  </file>

The size and date tags will need to be registered as columns in order for the view object to display them. To show them in the order specified, we can pass the string "size(text:'File Size', len:140, type:bytesize); date(text:Date, len:180, type:date)" to the Columns field. The optional information that we've specified in the brackets tells the view object the column name, the default pixel width of the column and the display type.

Currently recognised data types are 'bytesize', 'numeric' and 'date'. Use the bytesize type if the value is a number that can be represented in bytes, kilobytes, megabytes or gigabytes. The date type can be used if the values are stored in the date format "YYYYMMDD HH:MM:SS". The numeric type can be used for any type of number (integer or floating point). If the type is not specified, the view object will assume that the column is a standard string or variant type.

If you would like to change the arrangement of the default column so that it appears at a different position, you may refer to it using a column name of 'default'.


Field:DateFormat
Short:Sets the format to use when displaying date types.
Type:STRING
Status:Get/Set

Use the DateFormat field to define how dates should be displayed when they are used in columns. For information on how to set valid date formats, refer to the StrFormatDate() function in the Strings module.

If you do not set this field then the user's preferred date format will be used.


Field:HScroll
Short:If scrolling is required, use this field to refer to a horizontal scroll bar.
Type:OBJECTID
Status:Read/Set

If you want to attach a horizontal scrollbar to a view object, set this field to an object belonging to the Scroll class. So long as the Scroll object is set up to provide full scrollbar functionality, the user will be able to scroll the text display along the horizontal axis.


Field:Height
Short:Defines the height of a view.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

A view 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.


Field:HighlightColour
Short:Defines the colour when an item is selected via mouse-over or user focus.
Type:STRING
Status:Set

The HighlightColour defines the colour that is used when the user rolls the mouse pointer over an item, or uses the cursor keys to change the item focus. The colour must be in hexadecimal or CSV format - for example to create a pure red colour, a setting of "#ff0000" or "255,0,0" would be valid.


Field:ItemColour
Short:The default font colour to use for view items.
Type:STRING
Status:Set

The ItemColour defines the font colour that is applied to new items. The default is black. Items may override the default by using the colour attribute in their XML definition.

The colour string must be in hexadecimal or CSV format - for example to create a pure red colour, a setting of "#ff0000" or "255,0,0" would be valid.


Field:SelectColour
Short:Defines the colour when an item is selected via mouse-over or user focus.
Type:STRING
Status:Set

The SelectColour defines the colour that is used when the user rolls the mouse pointer over an item, or uses the cursor keys to change the item focus. The colour must be in hexadecimal or CSV format - for example to create a pure red colour, a setting of "#ff0000" or "255,0,0" would be valid.


Field:SelectedTags
Short:Returns an array of tag indexes for all currently selected items.
Type:LONG *
Status:Get

A complete list of currently selected items can be retrieved by reading the SelectedTags field. The data is returned as an array of 32-bit tag indexes, terminated with a value of -1. An error code will be returned if there are no currently selected items.

The array remains valid up until the next time that you read the SelectedTags field.


Field:Selection
Short:Indicates the currently selected file or directory.
Type:STRING
Status:Get/Set

The Selection field provides a method for retrieving the content of the currently selected item. If no selection is active then this field will return an error code and a NULL pointer.

You can also manually select an item by writing a valid item string to this field. The string must refer to the name of an item in the default column of the view.


Field:SelectionIndex
Short:Indicates the index number of the currently selected file or directory.
Type:STRING
Status:Get/Set

The SelectionIndex field provides a method for retrieving the index of the currently selected item. If no selection is active then this field will return a value of -1.

You can also manually select an item by writing a valid index number to this field. Changing the index will cause the item to become highlighting and the view's children will be activated automatically to inform them of the change. An error will be returned if the index number is outside of the available range. An index of -1 will deselect any currently selected items.


Field:Style
Short:The style of view that is displayed to the user is configured here.
Type:LONG
Status:Read/Set

The style of the view display can be configured by writing this field. You should set this field on initialisation, and may change it at any time if the user wishes to switch to a different style. Available view styles are as follows:

FlagDescription
COLUMNColumn mode is used when items carry more than one element of information. For instance, a file item may carry the file name, date and size, each of which can have its own column. The format of the column display is refined in the Columns field.
ICONIcon mode displays each item as a large icon with the default item text written underneath.
LISTList mode displays items using small icons and writes the item text on the right. The arrangement of the items is from top to bottom, left to right.
LONGLISTThis type is the same as the LIST view but the items will not wrap back to the top of the view when the bottom edge of the drawable is encountered.
TREETree mode can be used if the items are arranged in a hierarchy, where items can be embedded within items. The tree view provides small buttons that the user can click to expand the tree and view hidden items.

Field:TotalSelected
Short:The total number of currently selected items.
Type:LONG
Status:Get

This readable field will tell you the total number of items that are currently selected by the user.


Field:VScroll
Short:If scrolling is required, use this field to refer to a vertical scroll bar.
Type:OBJECTID
Status:Read/Set

If you want to attach a vertical scrollbar to a view object, set this field to an object belonging to the Scroll class. So long as the Scroll object is configured to provide full scrollbar functionality, the user will be able to scroll the text display along the vertical axis.


Field:Width
Short:Defines the width of a view.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

A view 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.


Field:XCoord
Short:The horizontal position of a view.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

The horizontal position of a view 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:The horizontal offset of a view.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

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

If set in conjunction with an X coordinate then the view will be drawn 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 View 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 view will be drawn at an X coordinate calculated from the formula "XCoord = ContainerWidth - ViewWidth - XOffset".


Field:YCoord
Short:The vertical position of a view.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

The vertical position of a View 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:The vertical offset of a view.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

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

If set in conjunction with a Y coordinate then the view will be drawn 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 view 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 view will be drawn at a Y coordinate calculated from the formula "YCoord = ContainerHeight - ViewHeight - YOffset".