FUNCTION
The moduleObj is a class for the GUIB module. See the documentation on the ::guib::moduleObj class.
NAME
::guib::moduleObj -- a class for the GUIB module
PURPOSE
It is the class for the GUIB module. The GUI constructed by the
GUIB is embedded inside the "module" keyword, for example:
module #auto -title "Simple GUI -script {
...
}
The "module" keyword construct the moduleObj object, which holds the
whole GUI.
IS-A
::guib::keywordObj
METHODS
1. GUIB-KEYWORDS::
1.1 object keywords:
page
namelist
group
optional
required
line
1.2 item keywords:
var
auxilvar
dimension
text
table
keyword
help
1.3 event-driven keywords:
tracevar
widget
groupwidget
widgetconfigure
widgetcget
keywordconfigure
1.4 getsets keywords, i.e. keyword associated with the variables:
varvalue
vartextvalue
varref
varset
dimvalue
dimtextvalue
dimref
dimset
tablevalue
tabletextvalue
tableref
tableset
1.5 special keywords:
readfilter
writefilter
postprocess
this
loaddata
valueToTextvalue
textvalueToValue
1.6 decoration keywords:
packwidgets
separator
2. PUBLIC METHODS
setModuleFile -- stores the full pathname of a module-definition file
getModuleFile -- gets the full pathname of a module-definition file
loaddataGetInfo -- return the value _loaddata array for a give variable
makeSimpleTplwGUI -- constructs a simple toplevel standalone GUI with File menu
makeEmbedGUI -- make a non-standalone GUI into a given contained widget
saveAs -- query for file and save the input into it queried file
save -- save the input into current file
print -- similar to "save" but instead prints to stdout
getOutput -- similar to "print" but instead returns the content
saveToVar -- store the value of all GUIB-variables into GUIB-variables
openFile -- opens an input-file and calls readFile
readFile -- reads an input-file from a given file-channel
readFileError -- method for dealing with file-read errors
readFileWrongFormat -- method for dealing with wrong-formatted input file
isNotDisabledWidget -- checks is a given widget associated with a particular input-variable is not disabled
getWidgetFromVarident -- returns a widget-pathname of a given input-variable
varnameToVarident -- tries to return a GUIB-variable's identifier on the basis of "varName"
indentinfo -- returns a queried information for a given keyword (i.e. based on identifier)
optionSetDefault -- ...
loadFromVar -- inverse of saveToVar, i.e., it varsets GUIB-variables from the variables
getAllVar -- returns all defined GUIB_variables
3. PROTECTED/PRIVATE METHDOS
3.1 methods connected to guib::keywordObj class
_setCurrentObj -- stores a current object and its type into currentObj, currentObjType variables
_getCurrentObj -- gets current object
_getCurrentObjType -- gets current object's type
3.2 methods connected to input variables
_addVaridentWidget -- adds a variable & widget pair to varidentWidgetList variable
_addVaridentObj -- adds a variable and the object to whome the variable belong to to varidentObjList variable
_getObjFromVarident -- returns the object associated with a given variable's identifier
3.3 auxiliary methods for GUIB keywords
_manageNameObj -- manages all the job for name-object type keywords
_manageVoidObj -- manages all the job for void-object type keywords
_manageKeyword -- manages all the job for item type keywords
_separator -- manages all the job for "separator" keyword
_widget -- manages all the job for the "widget" keyword
_groupwidget -- manages all the job for the "groupwidget" keyword
_groupwidget__disableAll -- disables all given widgets
_groupwidget__enableAll -- enables all given widgets
_tracevar -- {varIdent mode}
_traceCmd -- these two methods manage the job for "tracevar" keyword
3.4 methods for manipulating variable's widgets
_getAfterWidget -- returns the variables' widgets that follows after a given variable's widget
_deleteDisabledWid -- removes the widget from the disabledWidList list
_addDisabledWid -- add a given variable's widget to disabledWidList
3.5 methods for building the GUI's widgets
_buildGUI -- recursively builds the GUI
_buildGUI_constructItem -- subroutine of _buildGUI for managing the widgets of item's keyword
_configurePage -- configures the pages of tabnotebooks
_packSide -- returns the pack-side of a given widget
3.6 methods connected with the "Open" menu
_open -- recursively reads the input file
_openCompareStr -- reads a string from input-line and compares it to a given string according to "-nocase" status
_openReadNamelistVar -- reads the next name of a variable in the namelist
_openReadNamelistValue -- reads the next value of a variable in the namelist
_openReadKeyword -- reads keyword from the input according to "-nocase" status
_openSyntaxError -- method for dealing with file-read errors
3.7 methods connected with the "Save" menu
_manageSave -- wrapper for "_save" method
_save -- does the job for "save" method, that is, stores the output into the "output" variable recursively
_clearOutput -- clears the output (must be used before constructing the output)
_appendOutput -- append a given string to the output, that is, to the "output" variable
_getOutput -- returns the value of the "output" variable, which holds the content of the output
_saveToVar -- does the job for "saveToVar" method
3.8 methods connected to GUIB keyword identifier
_makeIdent -- makes a unique GUIB-variables identifier (used for undefined-variables)
_isUniqueIdent -- checks if ident is unique
_addIdent -- adds (registers) identifier
_checkIdentChars -- checks if identifier string contains only ^[[:alnum:]_.:]+$ type characters
3.9 other options
optionSetDefault -- set dafule value for a given option
_loadFromVar -- ...
COMMANDS
_validateFmtString -- construct the formated string and check it against the format specifiers
_comafy -- transforms the strings of type array(elem) to array,elem
_openGets -- read a line of input (skips all the empty lines)
_expandArgs -- returns option-value pairs in a non-listed form, i.e. opt1 val1 opt2 val2 ..., and not {op1 val1 opt2 val2 ...}
_findKeywordObjType -- checks if a given object-type is present in the stack
NAME
::guib::moduleObj::setModuleFile -- stores the full pathname of the module-file
USAGE
setModuleFile file
DESCRIPTION
This method stores the full pathname of the file that holds the
module definition. The path of the filename is stored in as
absolute pathname.
ARGUMENTS
file -- file-name of module-file
EXAMPLE
$moduleObj setModuleFile $moduleFile
NAME
::guib::moduleObj::getModuleFile -- returns the absolute pathname of the module-file
ARGUMENTS
None.
RETURN VALUE
Absolute pathname of the module-file.
EXAMPLE
set moduleFile [$moduleObj getModuleFile]
NAME
::guib::moduleObj::_setCurrentObj -- set the current GUIB object
USAGE
_setCurrentObj obj type
DESCRIPTION
Some keywords of module GUIB definition script define the new objects.
This is how the nesting of keywords is implemented. This method stores
the newly created object (name and type) as a current one.
ARGUMENTS
obj -- keywordObj's object name
type -- keywordObj's object type (e.g. page, namelist, ...)
RETURN VALUE
The object name
EXAMPLE
$moduleObj _setCurrentObj $childObj $key
NAME
::guib::moduleObj::_getCurrentObj -- returns the current keywordObj's object name
ARGUMENTS
None.
RETURN VALUE
The current object name
EXAMPLE
set childObj [$moduleObj _getCurrentObj]
NAME
::guib::moduleObj::_getCurrentObjType -- returns the current object type
ARGUMENTS
None.
RETURN VALUE
The current object type
EXAMPLE
set childObjType [$moduleObj _getCurrentObjType]
NAME
::guib::moduleObj::_addVaridentWidget -- adds a new variable-widget pair to a list
USAGE
_addVaridentWidget varIdent widgetName
ARGUMENTS
varIdent -- the GUIB-variable's identifier
widgetName -- the path of the variable's widget
RETURN VALUE
The added variable-widget pair.
EXAMPLE
$moduleObj _addVaridentWidget $varIdent $widgetPath
NAME
::guib::moduleObj::_addVaridentObj -- adds a new variable-object pair to a list
USAGE
_addVaridentObj varIdent obj
ARGUMENTS
varIdent -- the GUIB-variable's identifier
obj -- the associated keywordObj's object
RETURN VALUE
The added variable-object pair.
EXAMPLE
$moduleObj _addVaridentObj $varIdent $obj
NAME
::guib::moduleObj::getWidgetFromVarident -- returns the widget pathname which is associated with a variable
USAGE
getWidgetFromVarident varIdent
ARGUMENTS
varIdent -- the GUIB-variable's identifier
RETURN VALUE
The widget pathname associated with the variable.
EXAMPLE
set widget [$moduleObj getWidgetFromVarident $varIdent]
NAME
::guib::moduleObj::varnameToVarident -- tries to return a GUIB-variable's identifier on the basis of "varName"
USAGE
varnameToVarident obj varName ?nocase?
ARGUMENTS
obj -- keywordObj object pointer
varName -- the name of the variable (i.e. value of -variable option of a given obj's keyword)
nocase -- compare the varName-ident case sensitively/insensitively (must be 0|1)
RETURN VALUE
The identifier of a GUIB's variable
EXAMPLE
set ident [$moduleObj varnameToVarident $obj $varName 1]
NAME
::guib::moduleObj::_getObjFromVarident -- returns the object associated with a given variable's identifier
USAGE
_getObjFromVarident varIdent
ARGUMENTS
varIdent -- the GUIB-variable's identifier
RETURN VALUE
The keywordObj's object-name that holds the variable.
EXAMPLE
set obj [$moduleObj _getObjFromVarident $varIdent]
NAME
::guib::moduleObj::_getAfterWidget -- returns the widget after the specified one
USAGE
_getAfterWidget widget
ARGUMENTS
widget -- path-name of the widget
RETURN VALUE
The widget-pathname of the widget which is after the specified one
EXAMPLE
set widget [$moduleObj _getAfterWidget $thisWidgetName]
NAME
::guib::moduleObj::_manageKeyword -- does all for the GUIB item-type kewyords
USAGE
_manageKeyword obj key ident code
DESCRIPTION
This is a kernel method for processing the GUIB item-type
keywordslike var, dimension, keyword. This proc is called from
"var", "keyword", "dimension", etc. methods.
ARGUMENTS
obj -- the keywordObj's object to whom the current item-keyword belong
key -- the type (name) of the item-keyword (i.e. var, dimension, ...)
code -- code of the keyword
RETURN VALUE
None.
EXAMPLE
_manageKeyword obj key code
NAME
::guib::moduleObj::_manageNameObj -- manages all the job for name-object type keywords
USAGE
_manageNameObj key ident args
DESCRIPTION
This is a kernel method for processing the GUIB name-object like
page and namelist. The nameobject are the one whose keyword
has the -name option (e.g. page -name "Page #.1" {...script...}).
This method is called inside "page" or "namelist" methods and then it
manages the keywords content and stores it.
ARGUMENTS
key -- the type (name) of the object-keyword (i.e. namelist, group, ...)
args -- the code of the object-keyword
RETURN VALUE
None.
EXAMPLE
_manageNameObj page $args
NAME
::guib::moduleObj::_manageVoidObj -- manages all the job for void-object type keywords
USAGE
_manageVoidObj key code
DESCRIPTION
This is a kernel method for processing the GUIB void-objects like
"optional" and "required". The void-objects are the one whose keyword
doesn't have the -name option (e.g. required {...script...}).
This method is called inside "optional" or "required" methods and then it
manages the keywords content and stores it.
ARGUMENTS
key -- the type (name) of the object-keyword (i.e. namelist, group, ...)
args -- the code of the object-keyword
RETURN VALUE
None.
EXAMPLE
_manageVoidObj required $code
NAME
::guib::moduleObj::loaddataGetInfo -- return the value _loaddata array for a give variable
USAGE
loaddataGetInfo varIdent
DESCRIPTION
We would like to load a GUIB table from file. Hence in a module file a "loaddata" keyword was specified as "loaddata varIdent cmd buttonText". Then kind of "Load from file" button-widget will appear in the GUI. The "loaddataGetInfo" method is used to retrieve the "cmd" and "buttonText" of a given varIdent.
ARGUMENTS
varIdent -- identifier of the GUIB variable for which to load data
RETURN VALUE
Returns the loaddata's "varIdent cmd buttonText", where "cmd" is the "Load from file" command, and "buttonText" is the text that appear in the "Load from file" button.
EXAMPLE
set info [loaddataGetInfo $myTable]
NAME
::guib::moduleObj::_clearOutput -- clears the output (must be used before constructing the output)
USAGE
_clearOutput
DESCRIPTION
The _clearOutput prepares everything for making a new output. The output is constructed in such a way that it is appended by pieces to "output" variable. At the end the content of the "output" variable can be saved to file (save,saveAs) or printed to stdout (print).
RETURN VALUE
None.
NAME
::guib::moduleObj::_appendOutput -- append a given text to the output, that is, to the "output" variable
USAGE
_appendOutput text
DESCRIPTION
The _appendOutput method is used during the construction of the output with the recursive _save method.
RETURN VALUE
None.
NAME
::guib::moduleObj::_getOutput -- returns the value of the "output" variable
USAGE
_getOutput
RETURN VALUE
The value of the "output" variable.
EXAMPLE
set outputContent [_getOutput]
NAME
::guib::moduleObj::_makeIdent -- makes a unique GUIB-variables identifier
USAGE
_makeIdent string
DESCRIPTION
Makes a unique GUIB-variables identifier (used for undefined-variables).
RETURN VALUE
The unique identifier.
EXAMPLE
set ident [_makeIdent myVar]
SOURCE
NAME
::guib::moduleObj::_isUniqueIdent -- checks if ident is unique
USAGE
_makeIdent ident
ARGUMENTS
ident -- the identifier (of GUIB keyword)
RETURN VALUE
Returns 1 if ident is unique, and 0 otherwise.
EXAMPLE
set unique [_isUniqueIdent myIdent]
SOURCE
NAME
::guib::moduleObj::_addIdent -- add (register) identifier
USAGE
_addIdent ident
ARGUMENTS
ident -- the identifier (of GUIB keyword)
RETURN VALUE
Value of ident.
EXAMPLE
_addIdentt myIdent
SOURCE
NAME
::guib::moduleObj::_checkIdentChars -- checks if identifier string contains only ^[[:alnum:]_.:]+$ type characters
USAGE
_checkIdentChars ident ?allowComma?
ARGUMENTS
ident -- the identifier (of GUIB keyword)
RETURN VALUE
None.
EXAMPLE
_checkIdentChars myIdent
SOURCE
NAME
::guib::moduleObj::isNotDisabledWidget -- checks if widget is in a not present in disabledWidList list
USAGE
isNotDisabledWidget widget
DESCRIPTION
The "disabledWidList" list is used by "_widget" method to keep a record on disabled widgets. This method checks if a given widget is not present on the list of disabled widgets.
RETURN VALUE
Returns 1 when widget is not found in disabledWidList, otherwise returns 0.
EXAMPLE
set widgetState [$moduleObj isNotDisabledWidget $widget]
NAME
::guib::moduleObj::_deleteDisabledWid -- removes the widget from the disabledWidList list
USAGE
_deleteDisabledWid widget
DESCRIPTION
The "disabledWidList" list is used by "_widget" method to keep a record on disabled widgets. This method removes a given widget from the list of disabled widgets.
RETURN VALUE
None.
EXAMPLE
$moduleObj _deleteDisabledWid $widget
NAME
::guib::moduleObj::_addDisabledWid -- adds the widget to the disabledWidList list
USAGE
_addDisabledWid widget
DESCRIPTION
The "disabledWidList" list is used by "_widget" method to keep a record on disabled widgets. This method adds a given widget to the list of disabled widgets.
RETURN VALUE
None.
EXAMPLE
$moduleObj _addDisabledWid $widget
NAME
::guib::moduleObj::_validateFmtString -- construct the formated string and check it against the format specifiers
PURPOSE
This proc constructs formated string and checks it against the
format specifiers. The possible format errors are caught. If format
error occurs then the saveError variable is set to 1 and an error
message is raised in tk_messageBox for notification.
RETURN VALUE
The format string.
EXAMPLE
set string [_validateFmtString [list format "%s %s" $value1 $value2]
NAME
::guib::moduleObj::_comafy -- tranforms the strings of type a(1) to a,1
USAGE
_comafy var
RETURN VALUE
The transformed string, i.e. a(1) is transformed to a,1
EXAMPLE
set a3 [_comafy a(3)]
NAME
::guib::moduleObj::_findKeywordObjType
USAGE
::guib::moduleObj::_findKeyowrdObjType obj key
DESCRIPTION
This proc search for the requested object in the
nesting-stack. It returns 1 if the object was found and 0 otherwise.
RETURN VALUE
Returns 1 if the object was found and 0 otherwise.
EXAMPLE
_findKeywordObjType $obj $key
NAME
::guib::moduleObj::_expandArgs -- expands the args arument
USAGE
_expandArgs code
DESCRIPTION
Some GUIB keywords can have the two forms:
var varIdent -variable varName -label "VarName:"
or
var varIdent { -variable varName -label "VarName:" }
Hence this proc is used to axpand the second form of args, which is
the transformed to first form.
RETURN VALUE
The transformed string, i.e. a(1) si transformed to a,1
EXAMPLE
set a3 [_expandArgs a(3)]
SOURCE
body ::guib::moduleObj::_expandArgs {code} {
if { [llength $code] == 1 } {
# syntax: var { -option value -option value }
return [lindex $code 0]
} else {
# syntax: var -option value -option value
return $code
}
}
NAME
::guib::moduleObj::saveToVar -- store the value of all GUIB-variables into GUIB-variables
USAGE
saveToVar ?namespace_scope?
RETURN VALUE
None.
EXAMPLE
$this saveToVar ::myNamespace