; $Id: davegr__define.pro,v 1.17 2006/04/27 17:18:42 azuah Exp $
;###############################################################################
;
; CLASS NAME:
;   DaveGr
;
; PURPOSE:
;   This DaveGr class defines an entity which consists of one or more
;   datasets and all the necessary properties or attributes to display
;   or plot the dataset(s). A dataset is contained in a DaveDat
;   object and can be manipulated using that class' methods.
;
; CATEGORY:
;   Data Browser
;
; SUPERCLASSES:
;   IDL_CONTAINER
;
; PUBLIC METHODS:
;   Add
;   Get
;   Remove
;   Set
;
; AUTHOR:
;   Richard Tumanjong Azuah
;   NIST Center for Neutron Research
;   100 Bureau Drive, Gaithersburg, MD 20899
;   United States
;   azuah@nist.gov; (301) 9755604
;   Nov, 2002
;
; LICENSE:
;  The software in this file is written by an employee of 
;  National Institute of Standards and Technology 
;  as part of the DAVE software project.
;
;  The DAVE software package is not subject to copyright protection
;  and is in the public domain. It should be considered as an
;  experimental neutron scattering data reduction, visualization, and
;  analysis system. As such, the authors assume no responsibility
;  whatsoever for its use, and make no guarantees, expressed or
;  implied, about its quality, reliability, or any other
;  characteristic. The use of certain trade names or commercial
;  products does not imply any endorsement of a particular product,
;  nor does it imply that the named product is necessarily the best
;  product for the stated purpose. We would appreciate acknowledgment
;  if the DAVE software is used or if the code in this file is
;  included in another product.
;
;###############################################################################



;===============================================================================
; DaveGr::Cleanup
;
; PURPOSE:
;   Cleanup method for objects of this class
;
; PARAMETERS:
;
pro DaveGr::cleanup

; remove reference to DaveDat objects in container.
; The remove method also decrement nReferences for the data objects (each DaveDat object
; keeps track of the nos of references made to it)
self->remove, /all

;nData = self->count()
;while (nData gt 0) do begin
;    nData = nData - 1
;    void = self->get(dataRef=dataRef,position=nData)
;    void = dataRef->set(/remRef)
;    self->remove, dataRef
;endwhile

; and destroy the container
self->IDL_CONTAINER::cleanup

; free ptr to misc GUI attributes
ptr_free, self.guiAttribsPtr

end
;-------------------------------------------------------------------------------



;===============================================================================
; DaveGr::Init
;
; PURPOSE:
;   Initialization method for objects of this class
;
; PARAMETERS:
;
; KEYWORDS:
;   dataRef [in] - An object reference (or array of references) to
;                  DaveDat* object(s) representing the data to be
;                  plotted.
;
;   title [in] - text to be used for the main plot title
;
;   nameTag [in] - A string name tag used for identifying this
;                  object's icon in a widget application.
;
;   label [in] - A variable (an ANNOTATE structure) specifying a text
;                label to be associated with the DaveGr object created.
;
;   bgColor [in] - an [R,G,B] vector of byte values to be used as the
;                  background color when displaying this object.
;
;   xColor [in] - an [R,G,B] vector of byte values specifying the
;                 x-axis color.
;
;   xFont [in] - a string specifying a valid font family name for the
;                x-axis.
;
;   xFontSize [in] - an integer specifying a valid fontsize for the
;                    x-axis.
;
;   xLabel [in] - a string specifying the label for the x-axis.
;
;   xLineSize [in] - a float specifying a valid line thickness for
;                    drawing the x-axis.
;
;   zColor [in] - dependent-axis equivalent of xColor
;
;   zFont [in] - dependent-axis equivalent of xFont
;
;   zFontSize [in] - dependent-axis equivalent of xFontSize
;
;   zLabel [in] - dependent-axis equivalent of xLabel
;
;   zLineSize [in] -dependent-axis equivalent of xLineSize
;
; RETURN VALUE:
;   0 => failure
;   1 => success.
;
function DaveGr::init, dataRef=dataRef, title=title, label=label, nameTag=nameTag, bgColor=bgColor, $
        xColor=xColor,xFont=xFont,xFontSize=xFontSize,xLabel=xLabel,xLineSize=xLineSize, $
        zColor=zColor,zFont=zFont,zFontSize=zFontSize,zLabel=zLabel,zLineSize=zLineSize

; reset !error_state structure, ie clear all errors
message,/reset

if (self->IDL_CONTAINER::init() ne 1) then return, 0 ; base class initialization

if (n_elements(xFont) gt 0) then begin
    if (vartype(xFont) eq 'STRING') then self.xFont = xFont
endif else self.xFont = 'HELVETICA'

if (n_elements(xFontSize) gt 0) then begin
    self.xFontSize = xFontSize
endif else self.xFontSize = 11.0

if (n_elements(xLineSize) gt 0) then begin
    self.xLineSize = xLineSize
endif else self.xLineSize = 1.0

if (n_elements(xColor) gt 0) then begin
    dim = size(xColor)
    if ( (dim[0] eq 1) and (dim[1] eq 3)) then self.xColor = xColor
endif else self.xColor = [0b,0b,0b]

if (n_elements(zFont) gt 0) then begin
    if (vartype(zFont) eq 'STRING') then self.zFont = zFont
endif else self.zFont = 'HELVETICA'

if (n_elements(zFontSize) gt 0) then begin
    self.zFontSize = zFontSize
endif else self.zFontSize = 11.0

if (n_elements(zLineSize) gt 0) then begin
    self.zLineSize = zLineSize
endif else self.zLineSize = 1.0

if (n_elements(zColor) gt 0) then begin
    dim = size(zColor)
    if ( (dim[0] eq 1) and (dim[1] eq 3)) then self.zColor = zColor
endif else self.zColor = [0b,0b,0b]

if (n_elements(bgColor) gt 0) then begin
    dim = size(bgColor)
    if ( (dim[0] eq 1) and (dim[1] eq 3)) then self.bgColor = bgColor
endif else self.bgColor = [255b,255b,255b]

if (n_elements(dataRef) gt 0) then begin
    valid = ['DAVEDAT1D','DAVEDAT2D']
    ;self.nData = 0
    for i=0,n_elements(dataRef)-1 do begin
        ;if (self.nData+1 ge self.nDataMax) then break
        res = where(valid eq vartype(dataRef[i]), count)
        if (count) then begin
            self->add, dataRef[i] ; the add method also increments dataRef's nos of references
            ;void = (dataRef[i])->set(/addRef) ; increment nos of references by 1
            if (i eq 0) then begin
                ;; transfer data axes label to plot axes labels
                if ((dataRef[i])->get(xLabel=xl,zLabel=zl,xUnits=xu,zUnits=zu,nameTag=ntag)) then begin
                    self.xLabel = (strlen(xu) gt 0)? xl+' ('+xu+')' : xl
                    self.zLabel = (strlen(zu) gt 0)? zl+' ('+zu+')' : zl
                    self.nameTag = ntag
                endif
            endif
        endif ;else begin
            ;!error_state.msg = 'DaveGr::init: invalid object reference (dataRef) passed'
            ;!error_state.code = -1
            ;return, 0
        ;endelse
    endfor
endif

if (n_elements(xLabel) gt 0) then begin
    if (vartype(xLabel) eq 'STRING') then self.xLabel = xLabel
endif

if (n_elements(zLabel) gt 0) then begin
    if (vartype(zLabel) eq 'STRING') then self.zLabel = zLabel
endif

if (n_elements(nameTag) gt 0) then begin
    if (vartype(nameTag) eq 'STRING') then self.nameTag = nameTag
endif


self.maxLabel = 20

if (n_elements(nlabel)) then self.nlabel = nlabel < self.maxLabel

if (n_elements(label) gt 0) then begin
    ;; make sure label is a valid ANNOTATE structure
    if (vartype(label) eq 'ANNOTATE') then begin
        len = n_elements(label) < self.maxLabel
        self.label[0:len-1] = label[0:len-1]
        self.nlabel = len
    endif
endif else begin
    for i=0,self.maxLabel-1 do begin
        self.label[i].font = 'HELVETICA'
        self.label[i].fontSize = 10.0
        self.label[i].position = [0.5,0.5]
        self.label[i].alignment = 0.0
    endfor
endelse

if (n_elements(title) gt 0) then begin
    ;; make sure title is a valid ANNOTATE structure
    if (vartype(title) eq 'ANNOTATE') then begin
        self.title = title
    endif
endif else begin
    self.title.text = self.nameTag
    self.title.font = 'HELVETICA'
    self.title.fontSize = 14.0
    self.title.position = [0.5,0.90]
    self.title.alignment = 0.5
endelse

; ptr to a structure of misc. GUI/widget settings
self.guiAttribsPtr = ptr_new(/allocate_heap)

return, 1

end
;-------------------------------------------------------------------------------



;===============================================================================
; DaveGr__define
;
; PURPOSE:
;   Class structure definition procedure
;
; PARAMETERS:
;
; KEYWORDS:
;
pro DaveGr__define

; Structure to represent a text label
def_label = {annotate, $
             text:"", $         ; text to be displayed
             position:[0.5,0.5,0.0], $ ; location of 'text' in normalised coordinates
             alignment:0.0, $   ; text alignment
             color: [0b,0b,0b], $ ; 'text' color
             font:'', $         ; font 
             fontSize:10.0 $    ; charsize for text display
             }     

; Structure to represent miscellaneous axis graphic attributes and settings
void = {miscGrAttribs, $
        minimum:0.0, $          ; minimum value to be displayed
        maximum:0.0, $          ; maximum value to be displayed
        tickInterval:0.0, $     ; major tick interval
        useCustomFlag:0b , $    ; flag indicates if above limits should be used
        scaleFactor:0.0, $      ; a scale factor to be applied to axis
        logFlag:0, $            ; flag: 0==>linear; 1==>log10
        decimalPlaces:0b, $     ; number of decimal places to display
        tickDir:0b, $           ; tic direction: 0==>inwards; 1==>outwards
        tickLen:0.0, $          ; tick length as a percentage of the axis
        minorTicks:0b $         ; number of minor ticks to display
        }        

; maximum number of text labels
maxLabel = 20

void = {DaveGr, $
        nameTag:'', $           ; a string name tag for object
        xLabel:'', $
        xColor:[0b,0b,0b], $
        xFont:'', $
        xFontSize:12.0, $
        xLineSize:1.0, $
        xMiscAttribs:{miscGrAttribs}, $ ;
        zLabel:'', $
        zColor:[0b,0b,0b], $
        zFont:'', $
        zFontSize:12.0, $
        zLineSize:1.0, $
        zMiscAttribs:{miscGrAttribs}, $ ;
        bgColor:[255b,255b,255b], $
        title:{annotate}, $     ; Main plot title
        nLabel:0, $             ; nos of defined labels
        maxLabel:maxLabel, $    ; maximum nos of misc labels
        label:replicate(def_label,maxLabel), $ ; Placeholders for miscellaneous text labels
        guiAttribsPtr:ptr_new(), $ ; ptr to an annonymous structure to hold misc. GUI properties
        visRef:obj_new(), $     ; object ref to the visualization widget object
        inherits IDL_CONTAINER $
        }
end

