This page was created by the IDL library routine
mk_html_help. For more information on
this routine, refer to the IDL Online Help Navigator
or type:
? mk_html_help
at the IDL command line prompt.
Last modified: Sun Oct 26 20:43:11 2008.
NAME:
CATATOM
PURPOSE:
This is second most basic object in the CATALYST Object Library. It is a subclassed
CATCONTAINER object and implements an IDL object hierarchy. All objects in
the CATALYST Object Library are subclassed from the CATATOM object. Object
error handling, object reporting and documentation, object messaging, and
widget event handling are all set up in this object, allowing all objects
in the CATALYST Object Library to partake in this functionality.
AUTHORS:
FANNING SOFTWARE CONSULTING BURRIDGE COMPUTING
1645 Sheely Drive 18 The Green South
Fort Collins Warborough, Oxon
CO 80526 USA OX10 7DN, ENGLAND
Phone: 970-221-0438 Phone: +44 (0)1865 858279
E-mail: davidf@dfanning.com E-mail: davidb@burridgecomputing.co.uk
SUPERCLASSES:
CATCONTAINER, IDLITCOMPONENT
IDL_CONTAINER
SYNTAX:
atomObject = Obj_New('CATATOM')
CLASS_STRUCTURE:
class = { CATATOM, $ ; The CATATOM object class name.
_controlPanel : OBJ_NEW (), $ ; The control panel for the object.
_errorLevel : 0B, $ ; The error reporting level.
_event_method : "", $ ; The name of the event method associated with this object.
_event_objects : OBJ_NEW (), $ ; The object(s) to whom events for this object are passed.
_excl_event_object : OBJ_NEW (), $ ; An exclusive event object.
_messageRecipients : OBJ_NEW (), $ ; A list of objects to be notified of method calls.
_reportLevel : 0B, $ ; The info reporting level.
_trash : OBJ_NEW(), $ ; A trash container for destroying other objects.
_uvalue : PTR_NEW (), $ ; A user value placeholder for the object.
INHERITS CatContainer, $ ; All objects in the Catalyst Library are containers
INHERITS IDLitComponent $ ; Inherits the IDLitComponnet class for object properties.
}
MODIFICATION_HISTORY:
Written by: David Burridge, 13 March 2003.
Made sure there are no duplicated registrations in RegisterForMessage. DWF. 15 May 2004.
Made a change in the way EVENT_METHOD is assigned. If not passed in, will try to get EVENT_METHOD
from the parent first, before assigning EventHandler as method. 9 August 2004. DWF.
Removed TOP_OBJECT reference. It was not being used and got in the way of saving/restoring
object. 22 January 2005. DWF.
Added TRASH container and ADDTOTRASH method. 27 July 2005. DWF.
(See C:\IDL\Catalyst\source\core\catatom__define.pro)
NAME:
CATATOM::ADDTOTRASH
PURPOSE:
This procedure adds a specified object to the trash container. The purpose
is to have a place to store objects that need to be cleaned up when another
object is destroyed. Every object in the Catalyst system has a trash container.
SYNTAX:
object -> AddToTrash, anotherObject
ARGUMENTS:
anotherObject: The object, or array of objects, to be added to the trash container.
KEYWORDS:
None.
(See C:\IDL\Catalyst\source\core\catatom__define.pro)
NAME:
CATATOM::CLEANUP
PURPOSE:
This is the CATATOM object class destructor method.
SYNTAX:
Called automatically when the object is destroyed.
ARGUMENTS:
None.
KEYWORDS:
None.
MODIFICATIONS:
I have commented out the code that destroys the control panel, if it exits. While
programs work fine with this code in the IDLDE, the code causes errors on program
exit in run-time programs. I believe this is because of the order in which objects
are destroyed. In any case, control panels always destroy themselves in my experience
and commenting this code out here has not resulted in any memory leakage in any of
the programs I have tested. DWF. 10 Sept 2003.
(See C:\IDL\Catalyst\source\core\catatom__define.pro)
NAME:
CatAtom::CONTROLPANEL
PURPOSE:
This method creates a control panel for the object. A control
panel is a graphical user interface for setting object
properties.
SYNTAX:
theObject -> ControlPanel, baseObject
ARGUMENTS:
baseObject: The object reference of a base widget for this control to
be added to. If not supplied, the control panel will be in a
self contained window (i.e., a TOPLEVELBASE object).
KEYWORDS:
_EXTRA: Any keywords appropriate for the CatControlPanel::INIT method.
(See C:\IDL\Catalyst\source\core\catatom__define.pro)
NAME:
CATATOM::COPY
PURPOSE:
This procedure takes an object and returns a copy of it. Note that
this is a "deep" copy in so far as all the data referred to by the
object is copied. Also note that this is an inherently SLOW process!!
This routine uses a temporary file during execution, so ensure that
some disk space is available. The temporary file is stored in the
current directory unless the TEMPDIR keyword is set or the default
variable TEMPDIR has been defined with CatSetDefault.
SYNTAX:
copy = obj -> Copy, object, TempDir=tempdir
ARGUMENTS:
OBJECT: The object to be copied. If not supplied, self is copied.
KEYWORDS:
TEMPDIR: The directory to be used for the temporary file.
(See C:\IDL\Catalyst\source\core\catatom__define.pro)
NAME:
CATATOM::DOCUMENT
PURPOSE:
This method creates an HTML file (usually files, since superclass
objects are also documented) for the object. If running on Windows,
a Internet Explorer is spawned to read the documentation files.
SYNTAX:
self -> Document
ARGUMENTS:
None.
KEYWORDS:
DIRECTORY: The name of directory where the HTML files should be saved.
By default, the method will try to use the default variable DOCDIR,
which can be set with CatSetDefault. Otherwise, the user is asked
to specify a currently-existing directory. If none is specified,
the current directory is used.
(See C:\IDL\Catalyst\source\core\catatom__define.pro)
NAME:
CATATOM::DRAW
PURPOSE:
This method propogates a DRAW method invocation to the children of this
object. We expect the method to be called automatically by all subclasses
of the CatAtom class. On those occasions when you do NOT want the DRAW method
of children invoked, set the NO_CHILDREN keyword and the DRAW method returns
immediately. If an invalid child object is discovered, it is removed from
the parent container.
SYNTAX:
self -> Draw
ARGUMENTS:
None.
KEYWORDS:
REQUESTER: This optional keyword is set to the object that requests a DRAW of the
object. This is helpful sometimes when messages are received by other
objects.
NO_CHILDREN: If this keyword is set, the DRAW method is not propogated to the
object children, but the DRAW method returns immediately.
(See C:\IDL\Catalyst\source\core\catatom__define.pro)
NAME:
CATATOM::ERROR
PURPOSE:
This method implements an error report into a log file or to standard output.
The method should normally only be called from within a CATCH error handler.
It relies on !ERROR_STATE having current information about the error.
SYNTAX:
self -> Error
ARGUMENTS:
None.
KEYWORDS:
None.
(See C:\IDL\Catalyst\source\core\catatom__define.pro)
NAME:
CATATOM::EVENTHANDLER
PURPOSE:
A dummy event handler method to catch widget events. If events come here, they
are dispatched, if possible, to the first parent of this object. If there are
no parents, an error message is delivered.
SYNTAX:
Called from the CATEVENTDISPATCHER utility routine.
ARGUMENTS:
Event: The event structure from a widget event.
KEYWORDS:
None.
(See C:\IDL\Catalyst\source\core\catatom__define.pro)
NAME:
CATATOM::GETPROPERTY
PURPOSE:
This method is used to get the object's properties.
SYNTAX:
self -> GetProperty, Name=objectName
ARGUMENTS:
None.
KEYWORDS:
AUTO_DESTROY: A flag indicating whether this objects lifecycle
is controlled my the memory management system.
CONTROLPANEL: The object reference of the control panel. If none exists, a null object
is returned.
ERRORLEVEL: The error reporting level for this object.
EVENT_METHOD: The name of the current event method for this object.
EVENT_OBJECTS: This keyword returns the widget object or objects that will handle events for this
particular object.
EXCLUSIVE_EVENT_OBJECT: The exclusive event object, if available.
NAME: The name given to this object.
PARENTS: An array of the parents of this object.
REPORTLEVEL: The informational reporting level for this object.
TOP: A reference to the object at the top of the object hierarchy to which this
object belongs.
NO_COPY: Set this keyword to transfer the UVALUE without copying.
UVALUE: A user value pointer. Can be used to store any IDL variable type.
(See C:\IDL\Catalyst\source\core\catatom__define.pro)
NAME:
CATATOM::GETSTATE
PURPOSE:
This method is used to get the object's properties as a structure. It
is primarily intended to be used with the corresponding SETSTATE method.
SYNTAX:
state = self -> GetState ()
ARGUMENTS:
None.
KEYWORDS:
SCALARS: Set this keyword to include scalar properties. If no type
keywords are specified, this will be set. (Input)
ARRAYS: Set this keyword to include array properties. If no type
keywords are specified, this will be set. (Input)
POINTERS: Set this keyword to include pointer properties. If no type
keywords are specified, this will NOT be set. (Input)
OBJECTS: Set this keyword to include object reference properties. If no type
keywords are specified, this will NOT be set. (Input)
ALL: Set this keyword to include the all the above types. (Input)
INHERITED: Set this keyword to include properties inherited from the
superclass. (Input)
(See C:\IDL\Catalyst\source\core\catatom__define.pro)
NAME:
CATATOM::HELP
PURPOSE:
This method allows you to look at the current value of the object class structure.
It is similar to doing a Help, object, /Structure call at the IDL command line.
It depends upon having defined an output parameter for the CLASSNAME__DEFINE procedure
of any object that uses the method. All Catalyst objects use this convention:
PRO CLASSNAME__DEFINE, class
class = {....}
END
SYNTAX:
anObject = self -> Help
ARGUMENTS:
theField: The name of a particular field you would like HELP on.
KEYWORDS:
FIELDS: Set this keyword to see a list of the structure field names.
(See C:\IDL\Catalyst\source\core\catatom__define.pro)
NAME:
CATATOM::INIT
PURPOSE:
This is the CATATOM object class creator method.
SYNTAX:
Called automatically when the object is created.
ARGUMENTS:
None.
KEYWORDS:
ERRORLEVEL: The error level for this object. The default value is 2. Values can be:
0: Silently ignore the error. No visual output to the user.
1: Notify the user of the error by writing traceback information in the command log
or journal file. No graphical user interface notification.
2: Default. Notify the user with a graphical dialog and also write traceback
information in the command log or journal file.
EVENT_METHOD: Set this keyword to the name of the event method that should be
called when an event is generated for this widget. If undefined,
the event method is "EventHandler".
EVENT_OBJECT: This is an object reference to an object that will receive the
event from a specific widget event. It is the equivalent (in
widget terms) of specifying an EVENT_PRO or EVENT_FUNC keyword.
In other words, it is a way of deflected an event from the EVENTHANDLER
method of the object that generated the event to the EVENTHANDLER
method of the object specified with this keyword.
EXCLUSIVE_EVENT_OBJECT: If this keyword is set to a vaid object, events are passed directly
and only to this object, ignoring the other event objects. To disable this,
set this keyword to be a NULL object or zero. This keyword is designed for
situations where an object wishes to hog the events for a limited period.
NO_COPY: Set this keyword to transfer the UVALUE without copying.
PARENT: A parent container object. Must be subclassed from IDL_CONTAINER. The object
will be added to its parent container. (Input)
REPORTLEVEL: This sets the report level for the object. Reports are sent with the REPORT
method with a ReportLevel value. If the ReportLevel value is less than the
REPORTLEVEL value set here, then the report is suppressed. The default REPORTLEVEL
value is 2, allowing normal and debug messages to be recorded while suppressing
more verbose reporting. Report levels correspond to these values:
0: An "alert" message is sent.
1: An "informational" message is sent.
2: A "debug informational" message is sent.
3: A "normal" message is sent. (This is the default for the REPORT method.)
Reports are sent to a log file (if the Catalyst Library global variable
LOGFILENAME is defined) or or the command log window.
UVALUE: A user-value pointer. Can be used to store any IDL variable type.
_EXTRA: Any keyword appropriate for the IDL_CONTAINER::INIT method.
(See C:\IDL\Catalyst\source\core\catatom__define.pro)
NAME:
CATATOM::MESSAGEHANDLER
PURPOSE:
This method receives notification of a SENDMESSAGE call from another object's
method. This method should be overridden in any object that expects to receive
messages from objects. Be sure your MessageHandler methods define the arguments
and keywords shown here. If the message gets here, we issue an error message.
SYNTAX:
thisObject -> MessageHandler, title, SENDER=sender, DATA=data
ARGUMENTS:
TITLE: The title of the message.
KEYWORDS:
DATA: A keyword that contains any information the sender wishes to pass
with the message. It can be empty.
SENDER: The object that generated the message
(See C:\IDL\Catalyst\source\core\catatom__define.pro)
NAME:
CATATOM::PRINT
PURPOSE:
This method prints a simple display showing the hierarchy rooted
at this object.
SYNTAX:
self -> Print
ARGUMENTS:
None.
KEYWORDS:
Level: The depth in the hierarchy of this object. Note that this
is normally set internally as the program recurses through
the hierarchy.
(See C:\IDL\Catalyst\source\core\catatom__define.pro)
NAME:
CATATOM::REGISTERFORMESSAGE
PURPOSE:
This method enables an object to request messages of a specific title. These
messages, when generated, will be passed to the MessageHandler method of the
recipient object. This method can also be used to unregister for a message
by setting the UNREGISTER keyword.
SYNTAX:
thisObject -> Register_For_Message, recipient, title
ARGUMENTS:
RECIPIENT: The object that requires notification.
TITLE: The title of messages to pass.
KEYWORDS:
UNREGISTER: Set this keyword to unregister an object that has previously
registered itself for messages. The RECIPIENT and TITLE must
be the same as when the RECIPIENT registered the message.
(See C:\IDL\Catalyst\source\core\catatom__define.pro)
NAME:
CATATOM::REPORT
PURPOSE:
This method is used to send program reports either to a log file or to standard
output. If the self._reportLevel variable is less than or equal to that requested,
the message is output. This allows great flexibility
in the kinds of reports that get reported, and in particular it allows the user to turn
reporting to a higher level for a specific object than for other objects. This is
extremely useful in debugging object programs.
Reports are sent to a log file if the LogFileName system default is not a NULL string.
An "alert" message throws up a DIALOG_MESSAGE widget that the user must repond to.
SYNTAX:
self -> Report, theMessage, reportLevel
ARGUMENTS:
theMessage: The message text.
reportLevel: The type of report. 0: alert, 1: informational, 2: verbose report.
All reports depend upon a comparison between the ReportLevel,
the self._reportLevel and the input reportLevel values. The largest of these
three values is used to set the report level.
KEYWORDS:
COMPLETED: A "completed" standard verbose message.
FAILED: A "failed" standard verbose message.
STARTED: A "started" standard verbose message.
(See C:\IDL\Catalyst\source\core\catatom__define.pro)
NAME:
CATATOM::SELECT
PURPOSE:
This method is a dummy method for a "selection" process. An object who wishes
to be "selected" must override this method. A "selected" object will return its
own object reference.
SYNTAX:
thisObject -> Select, x, y
ARGUMENTS:
X: A dummy parameter. Perhaps the X location in a draw widget.
Y: A dummy parameter. Perhaps the Y location in a draw widget.
KEYWORDS:
SUCCESS: Set to 1 if a selection is made. To 0 otherwise.
_EXTRA: Any extra keywords.
(See C:\IDL\Catalyst\source\core\catatom__define.pro)
NAME:
CATATOM::SENDMESSAGE
PURPOSE:
This method dispatches messages to objects that have registered to receive
them (using the RegisterForMessage method).
SYNTAX:
thisObject -> SendMessage, title, DATA=data
ARGUMENTS:
TITLE: The title of the message. The message will be sent to objects that have
registered to receive messages with this title.
KEYWORDS:
DATA: A keyword for passing relevant data along with the message.
(See C:\IDL\Catalyst\source\core\catatom__define.pro)
NAME:
CATATOM::SETPROPERTY
PURPOSE:
This method is used to set the object's properties.
SYNTAX:
self -> SetProperty, NAME=theName
ARGUMENTS:
None.
KEYWORDS:
AUTO_DESTROY: Set this keyword to use memory management to destroy the object. (Input)
CONTROLPANEL: A control panel object. Must be subclassed from CATCONTROLPANEL. (Input)
DRAW: Set this keyword to call the draw method after setting properties (Input).
ERRORLEVEL: Set this keyword to modify the behaviour when an error occurs (Input).
EVENT_METHOD: Set this keyword to the name of the object method that will
handle the events for this object. It is roughly equivalent
to setting EVENT_PRO in a widget program.
EVENT_OBJECTS: This is an object reference to an object that will receive the
event from a specific widget event. It is the equivalent (in
object terms) of specifying an EVENT_PRO or EVENT_FUNC keyword.
In other words, it is a way of deflected an event from the EVENTHANDLER
method of the object widget that generated the event to the EVENTHANDLER
method of the object specified with this keyword. It may be an array of
objects. Any objects currently defined as event objects will be replaced.
EXCLUSIVE_EVENT_OBJECT: If this keyword is set to a vaid object, events are passed directly
and only to this object, ignoring the other event objects. To disable this
set this keyword to be a NULL object or zero. This keyword is designed for
situations where an object wishes to hog the events for a limited period.
GROUP_LEADER: The group leader widget ID. Must be used for floating and
modal base widgets.
NAME: The "name" of the object. Used to keep track of the object in the code. (Input)
NO_COPY: Set this keyword to transfer the UVALUE without copying.
REPORTLEVEL: Set this keyword to modify the behaviour when an message is invoked (Input).
UVALUE: A user-value pointer. Can be used to store any IDL variable type.
(See C:\IDL\Catalyst\source\core\catatom__define.pro)
NAME:
CATATOM::SETSTATE
PURPOSE:
This method is used to set the object's properties using a structure. It
is primarily intended to be used with the corresponding GETSTATE method.
SYNTAX:
self -> SetState (state)
ARGUMENTS:
STATE: A structure whose tag names match some/all of the object properties.
Normally this structure would be from a GETSTATE method invocation
for this object or another of the same class.
KEYWORDS:
IGNORE_CLASS: The state structure returned by the GETSTATE method has a name
identifying it as the state structure for a partucular class. If
an attempt is made to apply it to another class, the call fails.
To override this behaviour, set the UNMATCHED keyword. (Input)
(See C:\IDL\Catalyst\source\core\catatom__define.pro)
NAME:
CATATOM::WHOMESSAGERECIPIENTS
PURPOSE:
This method prints out the name of all current message recipients and
which messages they are regestered for. This is a debugging method.
SYNTAX:
thisObject -> WhoMessageRecipients
ARGUMENTS:
None.
KEYWORDS:
None
(See C:\IDL\Catalyst\source\core\catatom__define.pro)
NAME:
CatContainer
PURPOSE:
This is the most basic object in the Catalyst Library. It is actually a simple
wrapper around the IDL_CONTAINER object, adding get-by-name, reference counting,
and memory management. Reference counting is what assures that objects in the
Catalyst system are not destroyed until every other object in the system is done
using them. For the most part, users can completely ignore this feature of
the program and their programs will clean themselves up miraculously. To avoid
memory leaks, all you have to do is make sure you destroy all pointers and objects
you use to hold information in your program in your CLEANUP method. (And be *absolutely*
sure you call the superclass CLEANUP method.) But any objectyou add to another object is
destroyed automatically. This feature alone is worth the astronomical cost of the Catalyst Library!
AUTHORS:
FANNING SOFTWARE CONSULTING BURRIDGE COMPUTING
1645 Sheely Drive 18 The Green South
Fort Collins Warborough, Oxon
CO 80526 USA OX10 7DN, ENGLAND
Phone: 970-221-0438 Phone: +44 (0)1865 858279
E-mail: davidf@dfanning.com E-mail: davidb@burridgecomputing.co.uk
SUPERCLASSES:
IDL_CONTAINER
SYNTAX:
catContainerObject = Obj_New('CatContainer')
CLASS_STRUCTURE:
struct = { CatContainer, $ ; The CatContainer object class name.
_autoDestroy : 0B, $ ; A flag denoting whether the object self destructs
when reference count reaches 0.
_name : "", $ ; The "name" of the object.
_parents : OBJ_NEW (), $ ; A list (container) of parent objects.
_memoryManagement : 0B, $ ; A flag to show if objects contained within this
object know about this object.
_indexed : 0B, $ ; A flag to specify whether the list is specifically indexed.
INHERITS IDL_CONTAINER $
}
MODIFICATION_HISTORY:
Written by: David Burridge, 12th March 2003
Added OCHILD and OSYBLING keywords to the GetProperty method. 24 June 2005. DWF.
(See C:\IDL\Catalyst\source\core\catcontainer__define.pro)
NAME:
CatContainer::ADD
PURPOSE:
This method overrides the IDL_CONTAINER Add method to allow
the user to add an child object to this container.
If the child is a CatContainer (or subclass of), it is
notified of the additional parent.
SYNTAX:
container -> Add, object
ARGUMENTS:
object: The object to add to the container. (Required)
KEYWORDS:
POSITION: The position index where the object should be added to
the container.
(See C:\IDL\Catalyst\source\core\catcontainer__define.pro)
NAME:
CatContainer::ADDPARENT
PURPOSE:
This method is used to notify this object that it has been added to a new
parent object. This is used internally in the object and should not be
called from the outside.
SYNTAX:
container -> AddParent, object
ARGUMENTS:
object: The parent object to which this one has been added. (Required)
KEYWORDS:
NONE.
(See C:\IDL\Catalyst\source\core\catcontainer__define.pro)
NAME:
CatContainer::CLEANUP
PURPOSE:
This is the CatContainer object class destructor method.
SYNTAX:
Called automatically when the object is destroyed.
ARGUMENTS:
None.
KEYWORDS:
None.
(See C:\IDL\Catalyst\source\core\catcontainer__define.pro)
NAME:
CatContainer::FindByName
PURPOSE:
This method is returns the positions (indices) of named objects in the container.
SYNTAX:
locns = container -> FindByName( searchName )
ARGUMENTS:
searchName: The name of the object you are looking for in this container (Required)
KEYWORDS:
CASE_SENSITIVE: Set this keyword to 1 to indicate a case-sensitive search. By default, the
search is case-insensitive.
COUNT: Set this keyword to a named variable that upon exit will contain the number
of objects returned that meet the searchName description. (Output)
REGEXP: Set this keyword to 1 to indicate the searchName is a regular expression.
_EXTRA: Any keywords supported by STREGEX can also be used. Requires REGEXP to be set.
(See C:\IDL\Catalyst\source\core\catcontainer__define.pro)
NAME:
CatContainer::GET
PURPOSE:
This method overrides the IDL_CONTAINER GET method to allow the user to return
an object or objects by "name".
SYNTAX:
object = self -> Get(searchName)
RETURN_VALUE:
object: The found object or an array of objects (if more than one meet the search criteria).
A null object is retuned if there are no matches.
ARGUMENTS:
searchName: The name of the object to find in the containment hierarchy. If absent,
the superclass IDL_CONTAINER::GET method is called and the first object
in the container (if there is one) is returned. Otherwise, a null object
is returned. You may use a regular expression for the searchName, if the
REGEXP keyword is set. For example, to find all objects with the names
beginning with capital C through G, the searchName would be "[C-G.]".)
KEYWORDS:
ALL: Set this keyword to return an array of object references to all of the objects
in the container.
CASE_SENSITIVE: Set this keyword to do a case-sensitive search for the objects. Searches
are case-insensitive by default.
COUNT: The number of objects found. Check this output keyword instead of the return value
to indicate success. (Output)
ISA: Set this keyword equal to a class name or vector of class names. This keyword is used
in conjunction with the ALL keyword. The ISA keyword filters the array returned by the
ALL keyword, returning only the objects that inherit from the class or classes specified
by the ISA keyword. This keyword is ignored if the ALL keyword is not provided.
POSITION: Set this keyword equal to a scalar or array containing the zero-based indices
of the positions of the objects to return.
RECURSIVE_SEARCH: If this keyword is set, the seach is conducted on all objects
in the object hierarchy below the entry point. In other words, the search
is done not only on child objects, but grandchild objects, great-grandchild
objects. etc.
REGEXP: Set this keyword to indicate the searchName is a regular expression.
_EXTRA: Any keywords supported by STREGEX can also be used. Requires REGEXP to be set.
(See C:\IDL\Catalyst\source\core\catcontainer__define.pro)
NAME:
CatContainer::GETNAME
PURPOSE:
This method is used to return the object's name.
SYNTAX:
name = self -> GetName()
ARGUMENTS:
None.
KEYWORDS:
None.
(See C:\IDL\Catalyst\source\core\catcontainer__define.pro)
NAME:
CatContainer::GETPROPERTY
PURPOSE:
This method is used to get the object's properties.
SYNTAX:
self -> GetProperty, Name=objectName
ARGUMENTS:
None.
KEYWORDS:
AUTO_DESTROY: A flag specifying whether this object self destructs when its parent
reference count reduces to zero. (Output)
OCHILD: Returns the first child in the object container. If there are no children,
a null object is returned. Used to traverse the object hierarchy.
FIRST_PARENT: This keyword will return the first parent in the _parents container.
If there are no parents, it will return a null object.
INDEXED: A flag specifying whether the list is indexed.
MEMORY_MANAGEMENT: A flag specifying whether the children of this object know about
this parent (and therefore whether their existance depends on this object)
(Output)
NAME: The "name" of the object. Used to keep track of the object in the code. (Output)
PARENTS: An array of parent objects.
OSYBLING: Returns the first sybling in the object container. If there are no children,
a null object is returned. Used to traverse the object hierarchy.
(See C:\IDL\Catalyst\source\core\catcontainer__define.pro)
NAME:
CATCONTAINER::GETPROPERTY (function)
PURPOSE:
This function method is a wrapper around the GetProperty procedure method. It
is primarily intended for convenience in getting a single property. Note that
it takes about twice as long to execute as its procedure counterpart.
SYNTAX:
result = self -> GetProperty (/KEYWORD)
ARGUMENTS:
None.
KEYWORDS:
KEYWORD: By setting any keyword appropriate for the GetProperty method of this
object, that property is returned by the function. If more than one
property is set, the function will fail.
(See C:\IDL\Catalyst\source\core\catcontainer__define.pro)
NAME:
CatContainer::INIT
PURPOSE:
This is the CatContainer object class creator method.
SYNTAX:
Called automatically when the object is created.
ARGUMENTS:
PARENT: A parent container object. Must be subclassed from IDL_CONTAINER. The object
will be added to its parent container. (Input)
KEYWORDS:
AUTO_DESTROY: The CATCONTAINER object keeps track of the number of parents it has (reference
counting). When the reference count changes from 1 to 0, the object is automatically
destroyed. Setting AUTO_DESTROY to 0 will prevent this automatic destruction.
By default, this keyword is set to 1. Note that if you set AUTO_DESTROY=0
you will be responsible for destroying the object when you are finished with it.
(In reference counting, when an object's reference count goes to 0, the object
is automatically destroyed. Setting this keyword prevents the automatic destruction
that would occur otherwise.)
INDEXED: If set, the objects that are added to the container will always have
the same index value they are assigned when they are added to the container.
If objects are later removed from the container, a null object is added in that
indexed space, thus assuring that all objects keep their assigned index number.
MEMORY_MANAGEMENT: Setting this keyword to 0 disables automatic memory management for
this container. This means that objects added to the container will not realize they
are children of this container. The default is to set this keyword to 1. (This
is "reference counting".)
NAME: The "name" of the object. Used to keep track of the object in the code.
You can "GET" an object by its name, for example. Any string is acceptible. (Input)
POSITION: This object's position in the parent container. See the IDL_CONTAINER
documentation. (Input)
(See C:\IDL\Catalyst\source\core\catcontainer__define.pro)
NAME:
CatContainer::PRINT
PURPOSE:
This method is used to print a list of the objects contents.
SYNTAX:
container -> Print
ARGUMENTS:
None.
KEYWORDS:
LABEL: Any text passed through 'Label' will be prepended onto the printed lines.
RECURSIVE: If set, this keyword prints the contents of any child objects who
are also containers. (input)
(See C:\IDL\Catalyst\source\core\catcontainer__define.pro)
NAME:
CatContainer::REMOVE
PURPOSE:
This method overrides the IDL_CONTAINER REMOVE method to allow the user to remove by
name an object with reference counting.
SYNTAX:
self -> Remove, object
ARGUMENTS:
object: Either the object reference or name (searchName) of the object to remove.
KEYWORDS:
ALL: Set this keyword to remove all objects from the container. If both the object parameter and
this keyword is set, all objects of the specified type/name will be removed.
POSITION: Set this keyword equal to the zero-based index of the object to be removed. If the
SearchName argument is supplied, this keyword is ignored.
REGEXP: Set this keyword to indicate the searchName is a regular expression.
_EXTRA: Any keywords supported by STREGEX can also be used. Requires REGEXP to be set.
(See C:\IDL\Catalyst\source\core\catcontainer__define.pro)
NAME:
CatContainer::REMOVEPARENT
PURPOSE:
This method removes a parent reference from an object list. It is used internally in
the container object and should not be called from outside.
If the last parent is removed and the AutoDestroy property is TRUE, the object will
self destruct (as it is no longer required).
SYNTAX:
container -> RemoveParent, thisParent
ARGUMENTS:
thisParent: The object reference of the parent to be removed.
KEYWORDS:
NODESTROY: If this keyword is set, the AUTO_DESTROY keyword is set to 0 on the object
before its parent is removed, and set back to its input value on exit. The
point of setting the NODESTROY keyword is to be able to remove object
parents prior to SAVING the object. (If this is not done, the entire
object hierarchy will be SAVED with the SAVE file.)
(See C:\IDL\Catalyst\source\core\catcontainer__define.pro)
NAME:
CatContainer::SETPROPERTY
PURPOSE:
This method is used to set the object's properties.
SYNTAX:
self -> SetProperty, NAME=theName
ARGUMENTS:
None.
KEYWORDS:
AUTO_DESTROY: The CATCONTAINER object keeps track of the number of parents it has (reference
counting). When the reference count changes from 1 to 0, the object is automatically
destroyed. Setting AUTO_DESTROY to 0 will prevent this automatic destruction.
By default, this keyword is set to 1. Note that if you set AUTO_DESTROY=0
you will be responsible for destroying the object when you are finished with it.
NAME: The "name" of the object. Used to keep track of the object in the code. (Input)
(See C:\IDL\Catalyst\source\core\catcontainer__define.pro)
NAME:
CATCONTAINER::SHOWCONTENTS
PURPOSE:
This method is used to graphically represent the contents of an object.
It does a recursive search through the object containers.
SYNTAX:
self -> ShowContents
ARGUMENTS:
None.
KEYWORDS:
_EXTRA: Any keywords appropriate for the PROPERTYPANEL object.
(See C:\IDL\Catalyst\source\core\catcontainer__define.pro)
NAME:
CATCONTROLPANEL
PURPOSE:
The purpose of this routine is to implement a control panel as an object. It
automatically deals with whether the CP is embedded or standalone and adds
OK, APPLY and CANCEL buttons if required. Control panels are most often
represented by propertysheet widgets, but don't have to be. Our original
notion was that every object in the Catalyst system could have its own control
panel to allow the user to manipulate the properties of that object. See the
ControlPanel method of the IMGAXES object as an example of how to create control
panels for objects.
Objects can (and should) customise the control panel by adding other widget
objects. Note that the events for these will be passed to the caller object
event handler.
AUTHORS:
FANNING SOFTWARE CONSULTING BURRIDGE COMPUTING
1645 Sheely Drive 18 The Green South
Fort Collins Warborough, Oxon
CO 80526 USA OX10 7DN, ENGLAND
Phone: 970-221-0438 Phone: +44 (0)1865 858279
E-mail: davidf@dfanning.com E-mail: davidb@burridgecomputing.co.uk
CATEGORY:
Object widgets.
SYNTAX:
aCatControlPanel = Obj_New("CatControlPanel", callerObject)
SUPERCLASSES:
WIDGETATOM
CATATOM
IDL_CONTAINER
CLASS_STRUCTURE:
class = { CatControlPanel, $
_caller : OBJ_NEW (), $ ; The object that calls the Control Panel.
_tlb : OBJ_NEW (), $ ; The pseudo-TLB of the Control Panel widgets.
_event_destination: OBJ_NEW(), $ ; The object that will receive events.
INHERITS BaseWidget $
}
MODIFICATION_HISTORY:
Written by: David Burridge, 19th August 2002.
(See C:\IDL\Catalyst\source\core\catcontrolpanel__define.pro)
NAME:
CATCONTROLPANEL::CLEANUP
PURPOSE:
This method cleans up a control panel.
SYNTAX:
Called automatically on destruction, thus:
OBJ_DESTROY, aCatControlPanel
ARGUMENTS:
None.
KEYWORDS:
_EXTRA: Any keywords valid for the "BASEWIDGET::CLEANUP" method.
(See C:\IDL\Catalyst\source\core\catcontrolpanel__define.pro)
NAME:
CATCONTROLPANEL::CREATED_OWN_TLB
PURPOSE:
This method returns a 1 if the control panel object created it's own TLB, and a 0 otherwise.
SYNTAX:
IF aCatControlPanel -> CREATED_OWN_TLB(tlb) THEN tlb -> Draw ELSE cp -> Show
ARGUMENTS:
tlb : The object reference stored in the self._tlb field of the object. (Output)
KEYWORDS:
None.
(See C:\IDL\Catalyst\source\core\catcontrolpanel__define.pro)
NAME:
CATCONTROLPANEL::DRAW
PURPOSE:
This method draws the control panel.
SYNTAX:
aCatControlPanel -> Draw
ARGUMENTS:
None.
KEYWORDS:
_EXTRA: Any keywords accepted by the "BASEWIDGET::DRAW" method.
(See C:\IDL\Catalyst\source\core\catcontrolpanel__define.pro)
NAME:
CATCONTROLPANEL::EVENTHANDLER
PURPOSE:
This method serves as an event handler for the "OK", "APPLY" and "CANCEL" buttons
(if they exist for this control panel). When an event is received, and new CATCONTROL_PANEL
event structure is created with the name of the button as the VALUE field. This event
structure is then sent to the real object handling the events for this control panel.
SYNTAX:
Called automatically by the event dispatcher.
ARGUMENTS:
event: A structure describing the event.
KEYWORDS:
None.
(See C:\IDL\Catalyst\source\core\catcontrolpanel__define.pro)
NAME:
CATCONTROLPANEL::INIT
PURPOSE:
This method creates a default control panel.
SYNTAX:
Called automatically by initialisation, thus:
aCatControlPanel = OBJ_NEW ('CatControlPanel', caller)
ARGUMENTS:
CALLER: The object reference of the object the control panel controls.
KEYWORDS:
BASEWIDGET: A parent object for the control panel. If this is a base widget object
the control panel will be mounted upon it. Otherwise, the control panel
will be in its own window (see the TITLE and TLB_FRAME_ATTR keywords below).
EVENT_OBJECT: The object that should receive the events generated by this control panel.
If not provided, this will be the same as the CALLER.
NAME: The name of the control panel. By default, it is set to the name of the
caller object with " Control Panel" appended to it.
NO_APPLY: Set this keyword to specify no "Apply" button on the interface. This keyword
only applies if the CatControlPanel creates its own top-level base.
NO_CANCEL: Set this keyword to specify no "Cancel" button on the interface. This keyword
only applies if the CatControlPanel creates its own top-level base.
NO_OK: Set this keyword to specify no "OK" button on the interface. This keyword
only applies if the CatControlPanel creates its own top-level base.
PARENT: A parent object for the control panel. If this is a base widget object
the control panel will be mounted upon it. Otherwise, the control panel
will be in its own window (see the TITLE and TLB_FRAME_ATTR keywords below).
TITLE: The title attributes of the top-level base of the Control Panel. Only
used if baseObj is not provided.
TLB_FRAME_ATTR: The frame attributes of the top-level base of the Control Panel. Only
used if BASEWIDGET keyword is not provided.
_EXTRA: Any keywords valid for the "BASEWIDGET::INIT" method.
(See C:\IDL\Catalyst\source\core\catcontrolpanel__define.pro)
NAME:
CATCONTROLPANEL::REFRESH_PROPERTIES
PURPOSE:
This method searches in the ControlPanel base widget for a child
that is a PropertySheet widget. If it finds one, it sets the
REFRESH_PROPERTY keyword to 1 so that all the properties in the
control panel are updated at once.
SYNTAX:
aCatControlPanel -> Refresh_Properties
ARGUMENTS:
None.
KEYWORDS:
PROPERTIES: The string or string array listing the properties that should be refreshed.
If not provided, all properties are refreshed.
(See C:\IDL\Catalyst\source\core\catcontrolpanel__define.pro)
NAME:
CATCONTROLPANEL::SHOW
PURPOSE:
This method shows the control panel on the screen. If the control panel
already exists, it gets popped to the front.
SYNTAX:
aCatControlPanel -> Show
ARGUMENTS:
None.
KEYWORDS:
None.
(See C:\IDL\Catalyst\source\core\catcontrolpanel__define.pro)
NAME:
CATIPTOOL
PURPOSE:
The purpose of this routine is to implement an image processing command
as a tool object, giving the command the ability to be undone. Any
image processing command can be used. The command will call the GETDATA
method on the target image object to obtain the data to processes. Any
number of keywords are supported in the object.
AUTHORS:
FANNING SOFTWARE CONSULTING BURRIDGE COMPUTING
1645 Sheely Drive 18 The Green South
Fort Collins Warborough, Oxon
CO 80526 USA OX10 7DN, ENGLAND
Phone: 970-221-0438 Phone: +44 (0)1865 858279
E-mail: davidf@dfanning.com E-mail: davidb@burridgecomputing.co.uk
CATEGORY:
Objects.
SYNTAX:
aTool = Obj_New("CATIPTOOL", command, targetImageObject, Keyword=keyword)
SUPERCLASSES:
CATTOOL
CATATOM
CATCONTAINER
IDL_CONTAINER
CLASS_STRUCTURE:
class = { CATIPTOOL, $ ; The CATIPTOOL object class.
INHERITS CATTOOL, $ ; Inherits the CATTOOL object class.
_command: "", $ ; The IDL image processing command.
_p1: Ptr_New(), $ ; The first additional parameter of the command.
_p2: Ptr_New(), $ ; The second additional parameter of the command.
_p3: Ptr_New(), $ ; The third additional parameter of the command.
_nparams: 0L, $ ; The number of additional parameters.
_keywords: Ptr_New() $ ; A structure of keywords used with the command.
}
MODIFICATION_HISTORY:
Written by: David Fanning, July 14, 2003.
(See C:\IDL\Catalyst\source\core\catiptool__define.pro)
NAME:
CATIPTOOL::APPLY
PURPOSE:
This method applies or executes the image processing command.
;
SYNTAX:
thisObject -> Apply
ARGUMENTS:
None.
KEYWORDS:
DRAW: Set this keyword if you wish to call the draw method of the target object
after the command has been applied.
(See C:\IDL\Catalyst\source\core\catiptool__define.pro)
NAME:
CATIPTOOL::CLEANUP
PURPOSE:
This is the CATIPTOOL object class destructor method.
SYNTAX:
Called automatically when the object is destroyed.
ARGUMENTS:
None.
KEYWORDS:
_EXTRA: Any keyword appropriate for the "TOOLATOM::Cleanup" method.
(See C:\IDL\Catalyst\source\core\catiptool__define.pro)
NAME:
CATIPTOOL::GETPROPERTY
PURPOSE:
This method enables the getting of the CATIPTOOL object class
properties.
SYNTAX:
aGraphicsCmd -> GetProperty ...
ARGUMENTS:
None.
KEYWORDS:
_EXTRA: Any keywords appropriate for the superclass SetProperty methods.
(See C:\IDL\Catalyst\source\core\catiptool__define.pro)
NAME:
CATIPTOOL::INIT
PURPOSE:
This is the CATIPTOOL object class initialization method.
SYNTAX:
Called automatically when the object is created.
ARGUMENTS:
command: This is the name of the image processing "command" that is to be executed.
It should be a string. The image processing command should also be a function.
For example, "SOBEL" or "SMOOTH".
targetObject: The image object that will provide the image data to be processed by this
image processing command object.
p1: This is the first additional parameter of the image processing command.
The *first* parameter of the image processing command is always the
image data obtained from the targetObject with the GETDATA method. For
example, in this case P1 will be equal to 7:
smoothObj = Obj_New('CATIPTOOL', 'Smooth', targetObject, 7)
And the command that will be executed is this:
targetObject -> SetData, Smooth(targetObject->GetData(), 7)
p2: This is the second additional parameter of the image processing command.
p3: This is the third additional parameter of the image processing command.
KEYWORDS:
AUTO_DESTROY: This object keeps track of the number of parents it has (reference counting). When
this value changes from 1 to 0, the object will be destroyed unless Auto_Destroy
has been set to zero. (Input)
EVENT_OBJECT: This is an object reference to an object that will receive the
event from a specific widget event. It is the equivalent (in
object terms) of specifying an EVENT_PRO or EVENT_FUNC keyword.
In other words, it is a way of deflected an event from the EVENTHANDLER
method of the object widget that generated the event to the EVENTHANDLER
method of the object specified with this keyword.
EXCLUSIVE_EVENT_OBJECT: If this keyword is set to a vaid object, events are passed directly
and only to this object, ignoring the other event objects. To disable this
set this keyword to be a NULL object or zero. This keyword is designed for
situations where an object wishes to hog the events for a limited period.
INDEXED: If set, the contents of this container will remain at the same index(ie:
indices will not automatically be re-used.
MEMORY_MANAGEMENT: Setting this keyword to zero disables automatic memory management for
this container. This means that child objects will not realize that they
are children of this container.
NAME: The "name" of the object. Used to keep track of the object in the code.
You can "GET" an object by its name, for example. Any string is acceptible. (Input)
NO_COPY: Set this keyword to transfer the UVALUE without copying.
NOCACHE: Set this keyword to indicate that the input data should not be cached
or stored in the storage location.
ORIGINAL: If set to 1, act on original image data instead of image display data.
PARENT: A parent container object. Must be subclassed from IDL_CONTAINER. The object
will be added to its parent container. (Input)
POSITION: This object's position in the parent container. See the IDL_CONTAINER
documentation. (Input)
REPORTLEVEL: The reporting level for the atom. This is honored only if the reporting
level for the atom is higher than the reporting level in the !Smart system
variable. It is used primarily for debugging purposes. Values between 0 and 2. (Input)
TARGETOBJECT: The image object that is the target of this command. Note that a target object
is REQUIRED for the command to work correctly, although you do not have to
set the target in the INIT method. You can set it via the LOADCOMMAND and SETPROPERTY
methods, too. There must be a valid target at the time the APPLY method is called,
or an error is generated. The targetObject must be a valid CATIMAGE2D object.
UVALUE: A user-value pointer. Can be used to store any IDL variable type.
_EXTRA: Any keywords appropriate for the image processing command.
(See C:\IDL\Catalyst\source\core\catiptool__define.pro)
NAME:
CATIPTOOL::LoadCommand
PURPOSE:
This method allows the user to load a command into the object.
SYNTAX:
aGraphicsCmd -> LoadCommand, 'command', targetObject, p1, p2, p3
ARGUMENTS:
command: This is the name of the image processing "command" that is to be executed.
It should be a string. The image processing command should also be a function.
For example, "SOBEL" or "SMOOTH".
targetObject: The image object that will provide the image data to be processed by this
image processing command object.
p1: This is the first additional parameter of the image processing command.
The *first* parameter of the image processing command is always the
image data obtained from the targetObject with the GETDATA method. For
example, in this case P1 will be equal to 7:
smoothObj = Obj_New('CATIPTOOL', 'Smooth', TARGETOBJECT=targetObject, 7)
And the command that will be executed is this:
targetObject -> SetData, Smooth(targetObject->GetData(), 7)
p2: This is the second additional parameter of the image processing command.
p3: This is the third additional parameter of the image processing command.
KEYWORDS:
DRAW: Set this keyword to immediately call the Draw method when the command is executed.
TARGETOBJECT: The image object that is the target of this command. Note that a target object
is REQUIRED for the command to work correctly, although you do not have to
set the target in the INIT method. You can set it via the LOADCOMMAND and SETPROPERTY
methods, too. There must be a valid target at the time the APPLY method is called,
or an error is generated. The targetObject must be a valid CATIMAGE2D object.
_EXTRA: Any keywords appropriate for command may be used.
(See C:\IDL\Catalyst\source\core\catiptool__define.pro)
NAME:
CATIPTOOL::REDO
PURPOSE:
This method attempts to redo the previous command operation.
;
SYNTAX:
thisObject -> REDO
ARGUMENTS:
None.
KEYWORDS:
DRAW: Set this keyword if you wish to call the DRAW method on the target object
after the REDO operation.
(See C:\IDL\Catalyst\source\core\catiptool__define.pro)
NAME:
CATIPTOOL::SETPROPERTY
PURPOSE:
This method enables the setting of the CATIPTOOL object class
properties.
SYNTAX:
aGraphicsCmd -> SetProperty ...
ARGUMENTS:
None.
KEYWORDS:
TARGETOBJECT: The image object that is the target of this command. Note that a target object
is REQUIRED for the command to work correctly, although you do not have to
set the target in the this method. You can set it via the LOADCOMMAND and INIT
methods, too. There must be a valid target at the time the APPLY method is called,
or an error is generated. The targetObject must be a valid CATIMAGE2D object.
_EXTRA: Any keywords appropriate for the superclass SetProperty methods.
(See C:\IDL\Catalyst\source\core\catiptool__define.pro)
NAME:
CATIPTOOL::UNDO
PURPOSE:
This method attempts to undo the previous command operation by restoring
the cached image data.
;
SYNTAX:
thisObject -> UNDO
ARGUMENTS:
None.
KEYWORDS:
DRAW: Set this keyword if you wish to call the DRAW method on the target object
after the UNDO operation.
(See C:\IDL\Catalyst\source\core\catiptool__define.pro)
NAME:
CATLAYER::APPLYCOLORS
PURPOSE:
This method sets up the colors for the layer object if they exist. For this
reason, sub-classes *MUST* call this method at the *START* of their draw methods.
SYNTAX:
self -> ApplyColors
ARGUMENTS:
None.
KEYWORDS:
None.
(See C:\IDL\Catalyst\source\core\catlayer__define.pro)
NAME:
CATLAYER::APPLYCOORDS
PURPOSE:
This method sets up the coordinates for the data object if they exist. For this
reason, sub-classes *MUST* call this method at the *START* of their draw methods.
SYNTAX:
self -> ApplyCoords
ARGUMENTS:
None.
KEYWORDS:
None.
(See C:\IDL\Catalyst\source\core\catlayer__define.pro)
NAME:
CATLAYER::CLEANUP
PURPOSE:
This is the CATLAYER object class destructor method.
SYNTAX:
Called automatically when the object is destroyed.
ARGUMENTS:
None.
KEYWORDS:
None.
(See C:\IDL\Catalyst\source\core\catlayer__define.pro)
NAME:
CATLAYER::CONTROLPANEL
PURPOSE:
This method creates a control panel for the CATLAYER object. A
control panel is a graphical user interface for setting object
properties. If you create a control panel, the events are typically
sent to the EVENTHANDLER method.
SYNTAX:
theObject -> ControlPanel, baseObject
ARGUMENTS:
baseObject: The object reference of a base widget for this control to
be added to. If not supplied, the control panel will be in a
self contained window (i.e., a TOPLEVELBASE object).
KEYWORDS:
_EXTRA: Any keywords appropriate for the CatControlPanel::INIT method.
(See C:\IDL\Catalyst\source\core\catlayer__define.pro)
NAME:
CATLAYER::DRAW
PURPOSE:
This method may or may not be needed by your object, depending
upon whether a graphical representation of the object is required.
If you wish the DRAW method to automatically propogates down to any
objects contained in this object's container, call the superclass DRAW
method.
SYNTAX:
theObject -> Draw
ARGUMENTS:
None.
KEYWORDS:
None.
(See C:\IDL\Catalyst\source\core\catlayer__define.pro)
NAME:
CATLAYER::EVENT_HANDLER
PURPOSE:
This method is the event handler for the CATLAYER object. It will typically
be used to respond to events from widget objects created in the CONTROLPANEL
method.
SYNTAX:
This method is called automatically by the event handling mechanism.
ARGUMENTS:
event: The event structure as described in the IDL help files, except
that the ID, TOP and HANDLER tags will be object references.
KEYWORDS:
None.
(See C:\IDL\Catalyst\source\core\catlayer__define.pro)
NAME:
CATLAYER::GETPROPERTY
PURPOSE:
This method allows the user to obtain CATLAYER properties. Be sure
you ALWAYS call the superclass GETPROPERTY method if you have extra
keywords!
SYNTAX:
theObject -> GetProperty ...
ARGUMENTS:
None.
KEYWORDS:
COLOR_OBJECT: Use this keyword to get the contained COLORTOOL object.
COORD_OBJECT: Use this keyword to get the contained CATCOORD object.
SELECTABLE: Set to 1 if the layer is selectable, otherwise to 0.
VISIBLE: Set to 1 if the layer is visible, otherwise to 0.
_REF_EXTRA: Any keywords appropriate for the superclass GetProperty method.
(See C:\IDL\Catalyst\source\core\catlayer__define.pro)
NAME:
CATLAYER::INIT
PURPOSE:
This is the CATLAYER object class initialization method
SYNTAX:
Called automatically when the object is created.
ARGUMENTS:
parent: The parent object reference.
KEYWORDS:
COLOR_OBJECT: Use this keyword to load a color object for setting up colors for data display.
COORD_OBJECT: Use this keyword to load a coordinate object for setting up the data coordinate
system for data display.
SELECTABLE: Set this keyword to 0 to turn layer selectability OFF and to 1 to turn selectability ON.
Selectability is set to 1 by default.
VISIBLE: Set this keyword to 0 to turn layer visibilty OFF and to 1 to turn visibility ON.
Visibility is set to 1 by default.
_EXTRA: Any keywords appropriate for the superclass INIT method.
(See C:\IDL\Catalyst\source\core\catlayer__define.pro)
NAME:
CATLAYER::SELECT
PURPOSE:
This method passes on a selection event to its SELECTABLEOBJECT children, and returns
all possible selected objects.
SYNTAX:
selectedObject = theObject -> Select, x, y
ARGUMENTS:
X: The X location of a point in device or window coordinates.
Y: The Y location of a point in device or window coordinates.
KEYWORDS:
SUCCESS: Set to 1 if a selection is made. To 0 otherwise.
(See C:\IDL\Catalyst\source\core\catlayer__define.pro)
NAME:
CATLAYER::SETPROPERTY
PURPOSE:
This method allows the user to set the CATLAYER object's properties. Be sure
you ALWAYS call the superclass SETPROPERTY method if you have extra keywords!
SYNTAX:
theObject -> SetProperty ...
ARGUMENTS:
None.
KEYWORDS:
SELECTABLE: Set this keyword to 0 to turn layer selectability OFF and to 1 to turn selectability ON.
Selectability is set to 1 by default.
VISIBLE: Set this keyword to 0 to turn layer visibilty OFF and to 1 to turn visibility ON.
_EXTRA: Any keywords appropriate for the superclass SetProperty method.
(See C:\IDL\Catalyst\source\core\catlayer__define.pro)
NAME:
CATLAYER__DEFINE
PURPOSE:
The purpose of this routine is to implement a container object that can be used
for layering or overlaying graphic elements in a draw widget, on an image, etc.
Essentially, it is a means of grouping graphic elements (e.g., annotations) in
a way that make them easy to draw and easy to turn on/off.
AUTHORS:
FANNING SOFTWARE CONSULTING BURRIDGE COMPUTING
1645 Sheely Drive 18 The Green South
Fort Collins Warborough, Oxon
CO 80526 USA OX10 7DN, ENGLAND
Phone: 970-221-0438 Phone: +44 (0)1865 858279
E-mail: davidf@dfanning.com E-mail: davidb@burridgecomputing.co.uk
CATEGORY:
Objects.
SYNTAX:
theObject = Obj_New("CATLAYER")
SUPERCLASSES:
CATATOM
CATCONTAINER IDLITCOMPONENT
IDL_CONTAINER
CLASS_STRUCTURE:
class = { CATLAYER, $
_coords : OBJ_NEW(), $ ; A CATCOORD object of some type.
_colors : OBJ_NEW(), $ ; A COLORTOOL object for setting up color tables.
_visible : 0L, $ ; A flag that indicates the layer is visible (1), or not (0).
_selectable: 0L, $ ; A flag that indicates if the layer will allow selection on contained objects.
INHERITS CATATOM $
}
MESSAGES:
None.
MODIFICATION_HISTORY:
Written by: David W. Fanning, 18 January 2005.
(See C:\IDL\Catalyst\source\core\catlayer__define.pro)
NAME:
CatList
PURPOSE:
This is object is part of the Catalyst Library. It presents a mechanism for
dynamically creating and retrieving lists of information of any data type.
It is like a hash in the perl programming language. CATLISTVALUE objects
are stored in the CATLIST.
AUTHORS:
FANNING SOFTWARE CONSULTING BURRIDGE COMPUTING
1645 Sheely Drive 18 The Green South
Fort Collins Warborough, Oxon
CO 80526 USA OX10 7DN, ENGLAND
Phone: 970-221-0438 Phone: +44 (0)1865 858279
E-mail: davidf@dfanning.com E-mail: davidb@burridgecomputing.co.uk
SUPERCLASSES:
CAT_CONTAINER
IDL_CONTAINER
SYNTAX:
CatListObject = Obj_New('CatList')
CLASS_STRUCTURE:
class = { CatList $ ; The CatContainer object class name.
INHERITS CatContainer $ ; Sub-class of CatContainer
}
MODIFICATION_HISTORY:
Written by: David Burridge, 12th March 2003
(See C:\IDL\Catalyst\source\core\catlist__define.pro)
NAME:
CatList::ADD
PURPOSE:
This method overrides the default ADD method to provide two possiblities:
either child objects of class CatListValue can be added, or a name and
value can be specified which causes the CatListValue to be created.
SYNTAX:
defaultsObj -> Add, name, Value=value, Success=success
ARGUMENTS:
NAME: If this is a text string, a CatListValue object of this name is
created to add. If this is a CatListValue object it is added directly
to this container.
KEYWORDS:
VALUE: The value to enter into the list if NAME is a string. Can be of any IDL
type. If NAME is specified without VALUE, VALUE will be a NULL string.
SUCCESS: A flag indicating the success of the routine. If set, the
routine will fail quietly.
(See C:\IDL\Catalyst\source\core\catlist__define.pro)
NAME:
CatList::ADDVALUE
PURPOSE:
This method adds child objects of class CatListValue or a name and
value can be specified which causes the CatListValue to be created
and added to the list.
SYNTAX:
defaultsObj -> AddValue, name, Value=value, Success=success
ARGUMENTS:
NAME: If this is a text string, a CatListValue object of this name is
created to add. If this is a CatListValue object it is added directly
to this container.
KEYWORDS:
VALUE: The value to enter into the list if NAME is a string. Can be of any IDL
type. If NAME is specified without VALUE, VALUE will be a NULL string.
SUCCESS: A flag indicating the success of the routine. If set, the
routine will fail quietly.
(See C:\IDL\Catalyst\source\core\catlist__define.pro)
NAME:
CatList::CLEANUP
PURPOSE:
This is the CatList object class destructor method.
SYNTAX:
Called automatically when the object is destroyed.
ARGUMENTS:
None.
KEYWORDS:
None.
(See C:\IDL\Catalyst\source\core\catlist__define.pro)
NAME:
CatList::GetValue
PURPOSE:
This function method gets a named value from the container. Note that
only one value can be returned at a time. To implement multiple Gets,
Use the normal GET method and extract the values sequentially.
SYNTAX:
Value = ListObject -> GetValue (name)
ARGUMENTS:
NAME: The name of the value to retrieve from the container. (Required)
KEYWORDS:
SUCCESS: A flag indicating the success of the routine. If set, the
routine will fail quietly.
(See C:\IDL\Catalyst\source\core\catlist__define.pro)
NAME:
CatList::INIT
PURPOSE:
This is the CatList object class creator method.
SYNTAX:
Called automatically when the object is created.
ARGUMENTS:
None.
KEYWORDS:
None.
(See C:\IDL\Catalyst\source\core\catlist__define.pro)
NAME:
CATLISTVALUE
PURPOSE:
This object is part of the Catalyst Library. It is a simple object used
to store a named value of any data type in a CatList object. It is
similar to a hash in the perl programming language.
This object is designed solely to be used by the CATLIST container
object and should not be called individually.
AUTHORS:
FANNING SOFTWARE CONSULTING BURRIDGE COMPUTING
1645 Sheely Drive 18 The Green South
Fort Collins Warborough, Oxon
CO 80526 USA OX10 7DN, ENGLAND
Phone: 970-221-0438 Phone: +44 (0)1865 858279
E-mail: davidf@dfanning.com E-mail: davidb@burridgecomputing.co.uk
SUPERCLASSES:
CATCONTAINER
IDL_CONTAINER
SYNTAX:
catListValueObject = Obj_New('CatListValue', parent, name, Value=value)
ARGUMENTS:
parent: The parent object - must be a CatList object (required)
name: The name of the value in the list (optional)
KEYWORDS:
VALUE: The variable to be assigned as the value of the object. If
no value is supplied, a NULL string is used.
CLASS_STRUCTURE:
class = { CatListValue, $
_value : PTR_NEW (), $
INHERITS CatContainer $
}
MODIFICATION_HISTORY:
Written by: David Burridge, 12th March 2003.
(See C:\IDL\Catalyst\source\core\catlistvalue__define.pro)
NAME:
CATLISTVALUE STRUCTURE DEFINITION
PURPOSE:
This procedure defines the CatListValue object structure.
SYNTAX:
None. See syntax for INIT method
ARGUMENTS:
None.
KEYWORDS:
None.
(See C:\IDL\Catalyst\source\core\catlistvalue__define.pro)
NAME:
CATLISTVALUE::ADD
PURPOSE:
This method overrides the default ADD method to prevent child objects
being added.
SYNTAX:
None.
ARGUMENTS:
None.
KEYWORDS:
SUCCESS: A flag indicating the success of the routine. If set, the
routine will fail quietly.
(See C:\IDL\Catalyst\source\core\catlistvalue__define.pro)
NAME:
CATLISTVALUE::CLEANUP
PURPOSE:
This function method cleans up the object upon destruction.
SYNTAX:
OBJ_DESTROY, defaultValueObj
ARGUMENTS:
None.
KEYWORDS:
None.
(See C:\IDL\Catalyst\source\core\catlistvalue__define.pro)
NAME:
CATLISTVALUE::GETVALUE
PURPOSE:
This function method retrieves the data value associated with the list entry.
SYNTAX:
value = valueObj -> GetValue ()
ARGUMENTS:
None.
KEYWORDS:
SUCCESS: A flag indicating the success of the routine. If set, the
routine will fail quietly.
(See C:\IDL\Catalyst\source\core\catlistvalue__define.pro)
NAME:
CATLISTVALUE::INIT
PURPOSE:
This function method initialises the object.
SYNTAX:
valueObj = OBJ_NEW ('CatListValue')
ARGUMENTS:
Parent: The parent object - must be a CatLists object (required)
Name: The name of the value in the list (optional)
KEYWORDS:
Value: The variable to be assigned to the first value (input). If
no value is supplied, a NULL string is used.
(See C:\IDL\Catalyst\source\core\catlistvalue__define.pro)
NAME:
CATLISTVALUE::SETVALUE
PURPOSE:
This procedure method sets the data value associated with the list entry.
SYNTAX:
valueObj -> SetValue, listValue
ARGUMENTS:
ListValue: The variable to be used as the value.
KEYWORDS:
SUCCESS: A flag indicating the success of the routine. If set, the
routine will fail quietly.
(See C:\IDL\Catalyst\source\core\catlistvalue__define.pro)
NAME:
CATTOOL
PURPOSE:
This object implements a tool object class. It contains a storage pointer for
the data before the tool is applied. This is so the result of the tool can be
undone later. And it contains a target field so it knows what object was the
target of the tool. The tool applies an operation to the target object.
AUTHORS:
FANNING SOFTWARE CONSULTING BURRIDGE COMPUTING
1645 Sheely Drive 18 The Green South
Fort Collins Warborough, Oxon
CO 80526 USA OX10 7DN, ENGLAND
Phone: 970-221-0438 Phone: +44 (0)1865 858279
E-mail: davidf@dfanning.com E-mail: davidb@burridgecomputing.co.uk
SUPERCLASSES:
CATATOM
CATCONTAINER
IDL_CONTAINER
SYNTAX:
toolObject = OBJ_NEW ('CATTOOL')
CLASS_STRUCTURE:
class = { CATTOOL, $ ; The object class name.
INHERITS CATATOM, $ ; Inherits CATATOM
_theCache: Ptr_New(), $ ; The pre-tool data location.
_noCache: 0L $ ; A flag that indicates the input data is not to be cached or stored.
_theTarget: Obj_New(), $ ; The tool target. The tool is APPLIED to the data in this object.
}
MODIFICATION_HISTORY:
Written by: David Fanning, 3 April 2003.
(See C:\IDL\Catalyst\source\core\cattool__define.pro)
NAME:
CATTOOL::CACHE
PURPOSE:
This method enables the CATTOOL storage pointer to be loaded with the pre-tool data.
SYNTAX:
toolObject -> Cache, theData
ARGUMENTS:
theData: The data to be cached or saved.
KEYWORDS:
NO_COPY: Set this keyword to transfer the data to the cache pointer
without making a copy.
(See C:\IDL\Catalyst\source\core\cattool__define.pro)
NAME:
CATTOOL::CLEANUP
PURPOSE:
This is the CATTOOL object class destructor method.
SYNTAX:
Called automatically when the object is destroyed thus:
OBJ_DESTROY, toolObject
ARGUMENTS:
None.
KEYWORDS:
None.
(See C:\IDL\Catalyst\source\core\cattool__define.pro)
NAME:
CATTOOL::GETPROPERTY
PURPOSE:
This method is used to get properties of the CATTOOL object
SYNTAX:
toolObject -> GETPROPERTY, CACHED_DATA=data
ARGUMENTS:
None.
KEYWORDS:
CACHED_DATA: The data cached in the storage pointer.
NOCACHE: The current setting of the noCache flag.
TARGET: A reference to the target object.
_REF_EXTRA: Any keyword appropriate for the superclass GETPROPERTY method.
(See C:\IDL\Catalyst\source\core\cattool__define.pro)
NAME:
CATTOOL::INIT
PURPOSE:
This method is called upon object creation.
SYNTAX:
Called automatically when the object is created thus:
toolObject = OBJ_NEW ('CATTOOL')
ARGUMENTS:
None.
KEYWORDS:
NOCACHE: Set this keyword to indicate that the input data should not be cached
or stored in the storage location.
TARGET: Set this keyword to an object reference for the target object. The tool is
applied to the data in this target.
_EXTRA: Any keyword appropriate for the INIT method of the superclass object.
(See C:\IDL\Catalyst\source\core\cattool__define.pro)
NAME:
CATTOOL::SETPROPERTY
PURPOSE:
This method enables the setting of the CATTOOL object class
properties.
SYNTAX:
toolObject -> SETPROPERTY, CACHED_DATA=cached_data
ARGUMENTS:
None.
KEYWORDS:
CACHED_DATA: The data stored in the cache.
NOCACHE: Set this keyword to indicate that the input data should not be cached
or stored in the storage location.
NO_COPY: Set this keyword to transfer the data to the cache without making a copy.
TARGET: Set this keyword to an object reference for the target object. The tool is
applied to the data in this target.
_EXTRA: Any keywords appropriate for the superclass SetProperty method.
(See C:\IDL\Catalyst\source\core\cattool__define.pro)
NAME:
CatToolList
PURPOSE:
This is object is part of the Catalyst Library. It presents a mechanism for
creating and managing lists of tools (objects that operate on others).
AUTHORS:
FANNING SOFTWARE CONSULTING BURRIDGE COMPUTING
1645 Sheely Drive 18 The Green South
Fort Collins Warborough, Oxon
CO 80526 USA OX10 7DN, ENGLAND
Phone: 970-221-0438 Phone: +44 (0)1865 858279
E-mail: davidf@dfanning.com E-mail: davidb@burridgecomputing.co.uk
SUPERCLASSES:
CATATOM
CATCONTAINER
IDL_CONTAINER
SYNTAX:
ToolListObject = Obj_New('CatToolList')
CLASS_STRUCTURE:
struct = {CatToolList, _current:0L, _limit:0L, INHERITS CatAtom}
MODIFICATION_HISTORY:
Written by: David Burridge, 29th April 2003
(See C:\IDL\Catalyst\source\core\cattoollist__define.pro)
NAME:
CatToolList::Add
PURPOSE:
This method overrides the default ADD method to ensure that objects added
to this list are ToolAtom objects. The new object becomes the "current"
tool.
Note that if the tool is not added to the end of the list (i.e. previous
operation was an UNDO), the remaining tools will be removed.
Since the validity of the items in the list depends on it being sequential,
addition of tools within the list (using the POSITION keyword) causes the
list to be truncated.
Note that the ADD method of the IDL_CONTAINER object is used.
This is to bypass all memory management of CatToolList objects. These just
need to be added to simple containers.
SYNTAX:
toolListObj -> Add, tool
ARGUMENTS:
TOOL: The tool to be added. This must be subclasses from CATTOOL.
KEYWORDS:
POSITION: The position that the tool should be added to the list. If this
keyword is set, the list will be truncated at the new tool.
(See C:\IDL\Catalyst\source\core\cattoollist__define.pro)
NAME:
CatToolList::CLEANUP
PURPOSE:
This is the CatToolList object class destructor method.
SYNTAX:
Called automatically when the object is destroyed.
ARGUMENTS:
None.
KEYWORDS:
None.
(See C:\IDL\Catalyst\source\core\cattoollist__define.pro)
NAME:
CatToolList::Get
PURPOSE:
This method overrides the default GET method so that a default GET (with
no POSITION or ALL keyword) gets the CURRENT tool (rather than the first).
SYNTAX:
currentTool = toolListObj -> Get ()
ARGUMENTS:
None.
KEYWORDS:
POSITION: The position that the tool should be added to the list. If this
keyword is set, the list will be truncated at the new tool.
ALL: Set this keyword to get all of the tools from the list.
(See C:\IDL\Catalyst\source\core\cattoollist__define.pro)
NAME:
CatToolList::GetProperty
PURPOSE:
This method exists so that properties of the object can be retrieved.
SYNTAX:
toolListObj -> Add, tool
ARGUMENTS:
None.
KEYWORDS:
CURRENT_INDEX: The current index into the tool list array.
CURRENT_TOOL: The current tool in the tool list array.
LIMIT: The current limit for the number of tools in this tool list.
_REF_EXTRA: Any extra keywords for superclass GETPROPERTY methods.
(See C:\IDL\Catalyst\source\core\cattoollist__define.pro)
NAME:
CatToolList::INIT
PURPOSE:
This is the CatToolList object class creator method.
SYNTAX:
Called automatically when the object is created.
ARGUMENTS:
PARENT: The parent object that will contain the tool list.
KEYWORDS:
None.
(See C:\IDL\Catalyst\source\core\cattoollist__define.pro)
NAME:
CatToolList::Redo
PURPOSE:
This method includes a previously "undone" tool back into the tool list.
SYNTAX:
toolListObj -> Redo
ARGUMENTS:
None.
KEYWORDS:
ALL: Set this keyword to REDO all undone items in the list, starting from the current item.
(See C:\IDL\Catalyst\source\core\cattoollist__define.pro)
NAME:
CatToolList::Remove
PURPOSE:
This method overrides the default REMOVE method. The last object in the list becomes
the "current" tool.
Note that the REMOVE method of the IDL_CONTAINER object is used.
This is to bypass all memory management of CatToolList objects. These just
need to be removed from simple containers.
SYNTAX:
toolListObj -> Remove, Position=pos
ARGUMENTS:
None.
KEYWORDS:
POSITION: The position of the tool to remove from the list.
(See C:\IDL\Catalyst\source\core\cattoollist__define.pro)
NAME:
CatToolList::SetProperty
PURPOSE:
This method exists so that properties of the object can be set.
SYNTAX:
toolListObj -> SetProperty, Limit=10
ARGUMENTS:
None.
KEYWORDS:
LIMIT: The current limit for the number of tools in this tool list.
_F_EXTRA: Any extra keywords for superclass SETPROPERTY methods.
(See C:\IDL\Catalyst\source\core\cattoollist__define.pro)
NAME:
CatToolList::Undo
PURPOSE:
This method UNDOes a tool from tool list.
SYNTAX:
toolListObj -> Undo
ARGUMENTS:
None.
KEYWORDS:
ALL: Set this keyword to UNDO all items in the list, starting from the current item.
(See C:\IDL\Catalyst\source\core\cattoollist__define.pro)
NAME:
COLORTOOL
PURPOSE:
The purpose of the ColorTool object is to allow the user to construct and manage
a color table. Standard color tables can be loaded, drawing colors can be
specified by name and value, etc. Calling the DRAW method on a Colortool object causes
that object's color table to be loaded in IDL's hardware color table. A fundamental
principle of the Catalyst Library is that every piece of data should have associated
with it a color table by which it can be displayed, and a coordinate system which will
establish a data coordinate system for the data. The COLORTOOL performs the former function.
It can be set and retrieved from data objects by using the COLOR_OBJECT keyword in
SetProperty and GetProperty methods. ColorTool objects are often inherited by objects.
For example, if you add a data object to a draw widget, the data object is likely to
inherit the ColorTool object of the draw widget. This makes it easy to establish a
consistent color scheme for all objects being displayed in a single draw widget.
AUTHOR:
FANNING SOFTWARE CONSULTING BURRIDGE COMPUTING
1645 Sheely Drive 18 The Green South
Fort Collins, CO 80526 USA Warborough, Oxon, OX10 7DN England
Phone: 970-221-0438 Phone: +44 (0) 1865 858 279
E-mail: davidf@dfanning.com davidb@burridgecomputing.co.uk
SUPERCLASSES:
CATATOM
CATCONTAINER
IDL_CONTAINER
SYNTAX:
colorObject = Obj_New('COLORTOOL')
CLASS_STRUCTURE:
class = { COLORTOOL, $ ; The COLORTOOL object definition.
INHERITS CATATOM, $ ; Inherits the CATATOM object class.
_brewer: 0B, $ ; Flag that indicates a brewer color table.
_r: BytArr(256), $ ; The red color table vector.
_g: BytArr(256), $ ; The green color table vector.
_b: BytArr(256), $ ; The blue color table vector.
_colornames: Ptr_New(), $ ; The names of "known" colors.
_rvalue: Ptr_New(), $ ; The red color values associated with color names.
_gvalue: Ptr_New(), $ ; The red color values associated with color names.
_bvalue: Ptr_New(), $ ; The red color values associated with color names.
_colorfile: "", $ ; The name of the color table file to read.
_ncolors: 0L, $ ; The number of colors in standard color table.
_bottom: 0L, $ ; The starting index of the standard color table.
_scTLB: Obj_New(), $ ; The SHOWCOLORS tlb object.
_selTLB: Obj_New(), $ ; The SELECTCOLORS tlb object.
_xcTLB: Obj_New(), $ ; The XCOLORS tlb object.
_xc_registerName: "", $ ; The name with which the XCOLORS dialog is registered.
_ctindex: 0L, $ ; The current color table index.
_r_old: BytArr(256), $ ; The old red color table vector.
_g_old: BytArr(256), $ ; The old green color table vector.
_b_old: BytArr(256) $ ; The old blue color table vector.
}
MESSAGES:
COLORTOOL_TABLECHANGE: A message with this title is sent when color table vectors are
changed in the object. In additon to the message, a DATA keyword is
used to pass an anonymous structure containing the current R, G, and
B color table vectors, along with the BOTTOM index for loading the vectors.
COLORTOOL_SETPROPERTY: A message with this title is sent any time the SetProperty method is
called. No data is sent. Message recipients can call the GetPropery
method on the message SENDER to obtain appropriate information.
MODIFICATION_HISTORY:
Written by: David W. Fanning, 13 March 2003.
Added system color names to GETCOLOR method. DWF. 23 Jan 2004.
Modified the way ShowColors method works if a ShowColors window is on the display. Now
current colors are always displayed when ShowColors is called. DWF, 26 Jan 2004.
Added Stretch method to object. DWF, 26 Jan 2004.
Added support for 8-bit displays to GETCOLOR method. DWF. 25 Aug 2004.
Added support for BREWER color tables. 25 June 2008. DWF.
Added PICKCOLORNAME method. 7 July 2008. DWF.
Additional changes to BREWER support. 25 October 2008. DWF.
(See C:\IDL\Catalyst\source\core\colortool__define.pro)
NAME:
COLORTOOL::AddNamedColor
PURPOSE:
This method adds a color to the internal list of named colors.
SYNTAX:
colorObject -> AddNamedColor, color, colorName
or
colorObject -> AddNamedColor, r, g, b, colorName
ARGUMENTS:
color: A long integer (or integer array) represeting a 24-bit color.
colorname: The name of the color. The color *must* have a name!
r: The red component (or array of components) of the color.
g: The green component (or array of components) of the color.
b: The blue component (or array of components) of the color.
KEYWORDS:
None.
(See C:\IDL\Catalyst\source\core\colortool__define.pro)
NAME:
COLORTOOL::CLEANUP
PURPOSE:
This is the COLORTOOL object class destructor method.
SYNTAX:
Called automatically when the object is destroyed.
ARGUMENTS:
None.
KEYWORDS:
None.
(See C:\IDL\Catalyst\source\core\colortool__define.pro)
NAME:
COLORTOOL::COLOR24to8
PURPOSE:
This method converts a 24-bit integer value representing a color to a
three-element array representing the equivalent RGB values of the 24-bit integer.
In other words, it is the inverse operation to Color8to24.
SYNTAX:
rgbcolor = colorObject -> Color24to8(color24)
ARGUMENTS:
color: A 24-bit long integer value representing a 24-bit color.
RETURN VALUE:
rgbcolor: A three-element array, representing the red, green, and blue components
of the 24-bit starting value. Or, if an array is passed in, a 3-by-n array
of color values.
KEYWORDS:
None.
(See C:\IDL\Catalyst\source\core\colortool__define.pro)
NAME:
COLORTOOL::COLOR8to24
PURPOSE:
This method converts a color triple to an equivalent 24-bit integer value.
SYNTAX:
color24 = colorObject -> Color8to24(color)
ARGUMENTS:
color: A [red, green, blue] color triple that describes a particular color.
The triple can be either a row or column vector of 3 elements or it
can be an N-by-3 array of color triples.
RETURN VALUE:
color24: A 24-bit value, representing the red, green, and blue components
of the 8-bit starting values.
KEYWORDS:
None.
(See C:\IDL\Catalyst\source\core\colortool__define.pro)
NAME:
COLORTOOL::CONGRID
PURPOSE:
This method is a slight variation of IDL's Congrid routine. Specifically,
it checks for a divide by zero that can occur occasionally in XCOLORS.
SYNTAX:
newArray = colorObject -> Congrid(array, x, y, z)
ARGUMENTS:
array: A 1, 2, or 3 dimensional array to resize.
Data Type : Any type except string or structure.
x: The new X dimension of the resized array.
Data Type : Int or Long (greater than or equal to 2).
y: The new Y dimension of the resized array. If the original
array has only 1 dimension then y is ignored. If the original
array has 2 or 3 dimensions then y MUST be present.
z: The new Z dimension of the resized array. If the original
array has only 1 or 2 dimensions then z is ignored. If the
original array has 3 dimensions then z MUST be present.
KEYWORDS:
CENTER: If this keyword is set, shift the interpolation so that points
in the input and output arrays are assumed to lie at the midpoint
of their coordinates rather than at their lower-left corner.
CUBIC: If specified and non-zero, "Cubic convolution"
interpolation is used. This is a more
accurate, but more time-consuming, form of interpolation.
CUBIC has no effect when used with 3 dimensional arrays.
If this parameter is negative and non-zero, it specifies the
value of the cubic interpolation parameter as described
in the INTERPOLATE function. Valid ranges are -1 <= Cubic < 0.
Positive non-zero values of CUBIC (e.g. specifying /CUBIC)
produce the default value of the interpolation parameter
which is -1.0.
INTERP: If set, causes linear interpolation to be used.
Otherwise, the nearest-neighbor method is used.
MINUS_ONE: If set, will prevent CONGRID from extrapolating one row or
column beyond the bounds of the input array. For example,
If the input array has the dimensions (i, j) and the
output array has the dimensions (x, y), then by
default the array is resampled by a factor of (i/x)
in the X direction and (j/y) in the Y direction.
If MINUS_ONE is present (AND IS NON-ZERO) then the array
will be resampled by the factors (i-1)/(x-1) and (j-1)/(y-1).
(See C:\IDL\Catalyst\source\core\colortool__define.pro)
NAME:
COLORTOOL::DRAW
PURPOSE:
This method loads the color table vectors in the hardware color table.
SYNTAX:
colorObject -> Draw
ARGUMENTS:
None.
KEYWORDS:
None.
(See C:\IDL\Catalyst\source\core\colortool__define.pro)
NAME:
COLORTOOL::EVENTHANDLER
PURPOSE:
An event handler method to handle widget events from the various graphical user interfaces
associated with the ColorTool Object.
SYNTAX:
Typically called from the EVENTDISPATCHER utility routine. All event objects are named,
and the CASE statement branches on the object's name.
ARGUMENTS:
Event: The event structure from a widget event.
Object: The object reference of the widget object that generated the event.
KEYWORDS:
None.
(See C:\IDL\Catalyst\source\core\colortool__define.pro)
NAME:
COLORTOOL::GETCOLOR
PURPOSE:
The purpose of this method is to obtain a drawing color
by name and in a device-decomposition independent way. To
see a list of color names available, type:
colorNames = colorObject -> GetColor(/Names) & Print, colorNames
SYNTAX:
result = colorObject -> GetColor(theColor, colorIndex)
EXAMPLE:
axisColor = colorObject -> GetColor("Green", !D.Table_Size-2)
backColor = colorObject -> GetColor("Charcoal", !D.Table_Size-3)
dataColor = colorObject -> GetColor("Yellow", !D.Table_Size-4)
Plot, Findgen(11), Color=axisColor, Background=backColor, /NoData
OPlot, Findgen(11), Color=dataColor
ARGUMENTS:
theColor: A string with the "name" of the color. To see a list
of the color names available set the NAMES keyword. This may
also be a vector of color names. Colors available are these:
Almond Antique White Aquamarine Beige Bisque Black
Blue Blue Violet Brown Burlywood Charcoal Chartreuse
Chocolate Coral Cornsilk Cyan Dark Goldenrod Dark Gray
Dark Green Dark Khaki Dark Orchid Dark Salmon Deep Pink Dodger Blue
Firebrick Forest Green Gold Goldenrod Gray Green
Green Yellow Honeydew Hot Pink Indian Red Ivory Khaki
Lavender Lawn Green Light Coral Light Cyan Light Gray Light Salmon
Light Yellow Lime Green Linen Magenta Maroon Medium Gray
Medium Orchid Moccasin Navy Olive Olive Drab Orange
Orange Red Orchid Pale Goldenrod Pale Green Papaya Peru
Pink Plum Powder Blue Purple Red Rose
Rosy Brown Royal Blue Saddle Brown Salmon Sandy Brown Sea Green
Seashell Sienna Sky Blue Slate Gray Snow Spring Green
Steel Blue Tan Thistle Tomato Turquoise Violet
Violet Red Wheat White Yellow
Also, these system color names are available in IDL 5.6 and higher:
Frame, Text, Active, Shadow, Highlight, Edge, Selected, Face.
The color WHITE is used if this parameter is absent or a color name is mis-spelled. To see a list
of the color names available in the program, type this:
Print, self -> GetColor(/Names), Format='(6A15)'
theColorIndex: The color table index (or vector of indices the same length
as the color name vector) where the specified color is loaded. The color table
index parameter should always be used if you wish to obtain a color value in a
color-decomposition-independent way in your code. See the NORMAL CALLING
SEQUENCE for details. If theColor is a vector, and theColorIndex is a scalar,
then the colors will be loaded starting at theColorIndex.
RETURN VALUE:
The value that is returned by this method depends upon the keywords
used to call it and on the version of IDL you are using. In general,
the return value will be either a color index number where the specified
color is loaded by the program, or a 24-bit color value that can be
decomposed into the specified color on true-color systems. (Or a vector
of such numbers.)
If you are running IDL 5.2 or higher, the program will determine which
return value to use, based on the color decomposition state at the time
the program is called. If you are running a version of IDL before IDL 5.2,
then the program will return the color index number. This behavior can
be overruled in all versions of IDL by setting the DECOMPOSED keyword.
If this keyword is 0, the program always returns a color index number. If
the keyword is 1, the program always returns a 24-bit color value.
If the TRIPLE keyword is set, the program always returns the color triple,
no matter what the current decomposition state or the value of the DECOMPOSED
keyword. Normally, the color triple is returned as a 1 by 3 column vector.
This is appropriate for loading into a color index with TVLCT:
IDL> TVLCT, FSC_Color('Yellow', /Triple), !P.Color
But sometimes (e.g, in object graphics applications) you want the color
returned as a row vector. In this case, you should set the ROW keyword
as well as the TRIPLE keyword:
viewobj= Obj_New('IDLgrView', Color=FSC_Color('charcoal', /Triple, /Row))
If the ALLCOLORS keyword is used, then instead of a single value, modified
as described above, then all the color values are returned in an array. In
other words, the return value will be either an NCOLORS-element vector of color
table index numbers, an NCOLORS-element vector of 24-bit color values, or
an NCOLORS-by-3 array of color triples.
If the NAMES keyword is set, the program returns a vector of
color names known to the program.
INPUT KEYWORD PARAMETERS:
ALLCOLORS: Set this keyword to return indices, or 24-bit values, or color
triples, for all the known colors, instead of for a single color.
DECOMPOSED: Set this keyword to 0 or 1 to force the return value to be
a color table index or a 24-bit color value, respectively.
NAMES: If this keyword is set, the return value of the function is
a ncolors-element string array containing the names of the colors.
These names would be appropriate, for example, in building
a list widget with the names of the colors. If the NAMES
keyword is set, the COLOR and INDEX parameters are ignored.
listID = Widget_List(baseID, Value=GetColor(/Names), YSize=16)
ROW: If this keyword is set, the return value of the function when the TRIPLE
keyword is set is returned as a row vector, rather than as the default
column vector. This is required, for example, when you are trying to
use the return value to set the color for object graphics objects. This
keyword is completely ignored, except when used in combination with the
TRIPLE keyword.
TRIPLE: Setting this keyword will force the return value of the function to
*always* be a color triple, regardless of color decomposition state or
visual depth of the machine. The value will be a three-element column
vector unless the ROW keyword is also set.
OUTPUT KEYWORD PARAMETERS:
CANCEL: This keyword is always set to 0, unless that SELECTCOLOR keyword is used.
Then it will correspond to the value of the CANCEL output keyword in PICKCOLORNAME.
NCOLORS: The number of colors recognized by the program. It will be 88 by default.
(See C:\IDL\Catalyst\source\core\colortool__define.pro)
NAME:
COLORTOOL::GETPROPERTY
PURPOSE:
This method obtains properties from the object.
SYNTAX:
colorObject -> GetProperty, RED=r, GREEN=g, BLUE=b
TVLCT, r, g, b
ARGUMENTS:
None.
KEYWORDS:
BLUE: The blue color vector.
BREWER: Is set, using Brewer Color Tables.
COLORPALETTE: A n-by-3 array containing the current color table vectors
CTINDEX: The current color table index number.
GREEN: The green color vector.
NCOLORS: The number of colors.
RED: The red color vector.
_REF_EXTRA: Any keyword appropriate for the GETPROPERTY method of the superclass object.
(See C:\IDL\Catalyst\source\core\colortool__define.pro)
NAME:
COLORTOOL::GUI_UPDATE
PURPOSE:
This method updates the colors in any COLORTOOL GUI that happens to
be open on the display.
SYNTAX:
colorObject -> GUI_Update
ARGUMENTS:
INFO: The information structure used by the XCOLORS method.
KEYWORDS:
None.
(See C:\IDL\Catalyst\source\core\colortool__define.pro)
NAME:
COLORTOOL::INIT
PURPOSE:
This method initiates the COLORTOOL object.
SYNTAX:
colorObject Obj_New('ColorTool')
ARGUMENTS:
colorIndex: The color table index number to load. A number between 0 and 40. If
missing, 0 is assumed.
KEYWORDS:
BREWER: Set this keyword to load the Brewer color tables.
This program will look first in the $IDL_DIR/resource/colors directory for
the color table file, and failing to find it there will look in the same
directory that the source code of this program is located, then in the current
directory. Finally, if it still can't find the file, it will ask you to locate it.
If you can't find it, the program will simply return without loading a color table.
NOTE: YOU WILL HAVE TO DOWNLOAD THE FSC_BREWER.TBL FILE FROM THE COYOTE LIBRARY AND
PLACE IT IN ONE OF THE THREE PLACES OUTLINED ABOVE:
http://www.dfanning.com/programs/fsc_brewer.tbl
BOTTOM: The starting location where the color table is loaded.
COLORFILE: The fully qualified file name of the file containing color tables. By default,
colorFile = Filepath(SubDirectory=['resource','colors'], 'colors1.tbl')
COLORPALETTE: An n-by-3 byte array containing the color palette to load.
NCOLORS: The number of colors in the color palette.
(See C:\IDL\Catalyst\source\core\colortool__define.pro)
NAME:
COLORTOOL::LOADCOLOR
PURPOSE:
This method loads a color value or values into the color table vectors.
All color vectors must be the same size.
SYNTAX:
colorObject -> LoadColor, colorName
or,
colorObject -> LoadColor, r, g, b
ARGUMENTS:
colorName: A scalar or vector of color names.
Or,
r: A scalar or vector of red values.
g: A scalar or vector of green values.
b: A scalar or vector of blue values.
KEYWORDS:
DRAW: If this keyword is set, the DRAW method is called after the colors
have been loaded.
INDEX: If a scalar, the starting index for loading the specified color vectors.
IF a vector, the indices of the specified colors. Must be the same size
as the color vectors. If absent, then set to !D.Table_Size - (N_Elements(r) + 1).
EXAMPLE:
colorObject -> LoadColor, 'red', Index=10
colorObject -> LoadColor, ['red','yellow'], Index=20
colorObject -> LoadColor, ['red','yellow'], Index=[30,35]
colorObject -> ShowColors
colorObject -> LoadColor, 255, 255, 0, Index=10
colorObject -> LoadColor, [255, 0], [255,255], [0,0], Index=20
colorObject -> LoadColor, [255, 0], [255,255], [0,0], Index=[30,35]
colorObject -> ShowColors
(See C:\IDL\Catalyst\source\core\colortool__define.pro)
NAME:
COLORTOOL::LOADCT
PURPOSE:
This method loads a pre-determined color table.
SYNTAX:
colorObject -> LoadCT, colorIndex
ARGUMENTS:
colorIndex: The color table index number to load. If absent, 0 is assumed
KEYWORDS:
DRAW: If this keyword is set, the DRAW method is called after the colors
have been loaded.
(See C:\IDL\Catalyst\source\core\colortool__define.pro)
NAME:
COLORTOOL::PICKCOLORNAME
PURPOSE:
This method allows the user to select a color name interactively.
SYNTAX:
theColor = colorObject -> PickColorName()
ARGUMENTS:
defaultColor: The name of the default color to be set to the "current color"
If not supplied, the color "white" is used.
RETURN_VALUE:
theColor: The name of the selected color.
KEYWORDS:
GROUP_LEADER: The group leader object or widget reference. The group leader MUST
be passed to make this a modal widget. If absent, the program will
try to block the IDL command line. But this is not guaranteed and
is not recommended.
INDEX: If this keyword is set to a color index, the selected color will
be loaded at that location in the internal color table.
TITLE: The title of the pop-up dialog widget.
(See C:\IDL\Catalyst\source\core\colortool__define.pro)
NAME:
COLORTOOL::RESET
PURPOSE:
This method allows resets the current color vectors to the old color vectors.
SYNTAX:
colorObject -> Reset
ARGUMENTS:
None.
KEYWORDS:
None.
(See C:\IDL\Catalyst\source\core\colortool__define.pro)
NAME:
COLORTOOL::REVERSE
PURPOSE:
This method allows the current color vectors to be reversed.
SYNTAX:
colorObject -> Reverse
ARGUMENTS:
None.
KEYWORDS:
DRAW: If this keyword is set, the DRAW method is called after the colors have been loaded.
(See C:\IDL\Catalyst\source\core\colortool__define.pro)
NAME:
COLORTOOL::SELECTCOLOR
PURPOSE:
This method allows the user to select a color interactively.
SYNTAX:
theColor = colorObject -> SelectColor()
ARGUMENTS:
defaultColor: The name of the default color to be set to the "current color",
or the RGB value (three-element array or 24-bit value) of the
default color. If not supplied, the color "white" is used.
RETURN_VALUE:
theColor: A three-element array, representing the RGB values of the selected color.
KEYWORDS:
GROUP_LEADER: The group leader object or widget reference. The group leader MUST
be passed to make this a modal widget. If absent, the program will
try to block the IDL command line. But this is not guaranteed and
is not recommended.
INDEX: If this keyword is set to a color index, the selected color will
be loaded at that location in the internal color table.
TITLE: The title of the pop-up dialog widget.
(See C:\IDL\Catalyst\source\core\colortool__define.pro)
NAME:
COLORTOOL::SETPROPERTY
PURPOSE:
This method allows properties of the object to be set.
SYNTAX:
TVLCT, r, g, b, /GET
colorObject -> SetProperty, RED=r, GREEN=g, BLUE=b
ARGUMENTS:
None.
KEYWORDS:
BLUE: The blue color vector.
BREWER: Use the brewer color tables.
BOTTOM: The bottom color index.
COLORFILE: The fully-qualified name of a color table file to open and display.
COLORPALETTE: A n-by-3 array containing the current color table vectors
GREEN: The green color vector.
INDEX: The color table index number.
NCOLORS: The number of colors in the color table.
RED: The red color vector.
_EXTRA: Any keyword appropriate for the SETPROPERTY method of the CATATOM object.
(See C:\IDL\Catalyst\source\core\colortool__define.pro)
NAME:
COLORTOOL::SHOWCOLORS
PURPOSE:
The purpose of this program is to allow the user to see the colors currently
loaded in the color table vectors. A window with the current colors will open
on the display.
SYNTAX:
colorObject -> ShowColors
ARGUMENTS:
None.
KEYWORDS:
TITLE: The title of the window.
(See C:\IDL\Catalyst\source\core\colortool__define.pro)
NAME:
COLORTOOL::STRETCH
PURPOSE:
This method stretches the current colortable between minValue and maxValue.
SYNTAX:
colorObject -> Stretch, minValue, maxValue
ARGUMENTS:
minValue: The minimum value of the stretch. 0 > minValue < maxValue < 256 .
maxValue: The maximum value of the stretch. 0 > minValue > maxValue < 256.
KEYWORDS:
DRAW: If this keyword is set, the DRAW method is called after the colors have been loaded.
(See C:\IDL\Catalyst\source\core\colortool__define.pro)
NAME:
COLORTOOL::XCOLORS
PURPOSE:
The purpose of this method is to interactively change color tables.
SYNTAX:
colorObject -> XColors
ARGUMENTS:
None.
KEYWORDS:
BREWER: Set this keyword if you wish to use the Brewer Colors, as
implemented by Mike Galloy in the file brewer.tbl, and implemented
here as fsc_brewer.tbl. See these references:
Brewer Colors: http://www.personal.psu.edu/cab38/ColorBrewer/ColorBrewer_intro.html
Mike Galloy Implementation: http://michaelgalloy.com/2007/10/30/colorbrewer.html
This program will look first in the $IDL_DIR/resource/colors directory for
the color table file, and failing to find it there will look in the same
directory that the source code of this program is located, then in your IDL path.
Finally, if it still can't find the file, it will ask you to locate it.
If you can't find it, the program will simply return without loading a color table.
NOTE: YOU WILL HAVE TO DOWNLOAD THE FSC_BREWER.TBL FILE FROM THE COYOTE LIBRARY AND
PLACE IT IN ONE OF THE THREE PLACES OUTLINED ABOVE:
http://www.dfanning.com/programs/fsc_brewer.tbl
DRAG: Set this keyword if you want colors loaded as you drag
the sliders. Default is to update colors only when you release
the sliders. Applies only to UNIX computers.
GROUP_LEADER: The group leader for this program. When the group
leader is destroyed, this program will be destroyed.
MODAL: Set this keyword (along with the GROUP_LEADER keyword) to
make the XCOLORS dialog a modal widget dialog. Note that NO
other events can occur until the XCOLORS program is destroyed
when in modal mode.
TITLE: This is the window title. It is "Load Color Tables" by
default.
XOFFSET: This is the X offset of the program on the display. The
program will be placed approximately in the middle of the display
by default.
YOFFSET: This is the Y offset of the program on the display. The
program will be placed approximately in the middle of the display
by default.
(See C:\IDL\Catalyst\source\core\colortool__define.pro)
NAME:
COLORTOOL::XCOLORS_UPDATE
PURPOSE:
This method updates the color tables for the XCOLORS method.
SYNTAX:
Called from the EVENT_HANDLER method when events occur in the XCOLORS method interface.
ARGUMENTS:
None.
KEYWORDS:
None.
(See C:\IDL\Catalyst\source\core\colortool__define.pro)