SATSHELL Example
S@
Home SATGUI SATSHELL SATFORM SATFILTER SATREPORT SATMYSQL License Download Examples Contact

A basic text editor.

User Guide

The following example assumes that the directories for both satshell and satedit are included in the PATH environment variable.

To start the application enter:

satshell satedit

When the application has started a screen similar to the following is displayed:

Main Editor Screen:

The menubar has two drop-down menus:

MenuOptions
NewClear text and initialise for new edit.
OpenDisplay file select dialog to open new file.
Save*Save edit to current open file.
Save AsSave edit to a new file.
ExitExit application.
HelpDisplay help-text window.
AboutDisplay "About Box".

(*) The Save option is not available until a file has been "opened" or "saved as".


New:

This option clears the text from the screen. The current filename is also cleared and the Save option is disabled. The editor is in the same state as when first run.


Open:

The file select dialog is displayed:

A file may be selected by a double-click on its name -or- by entering a name using the keyboard. If a filename is entered which does not exist a warning message is displayed.

If, for example, the "license" file is selected the following screen is displayed:

NOTE: The title bar shows the name of the current file.


Save:

The displayed text is saved to the current file. This option is not available until a file has been "opened" or "saved as".


Save As:

The file save dialog is displayed:

Select the directory you wish to save the file in (if neccessary), then enter the required filename using the keyboard. If a filename is entered which already exists a warning message is displayed.

When the file has been saved the title bar is updated to show the name of the current file.


Exit:

The application window is closed.


Help:

This option creates a new window containing the SATEDIT help text:

The text may be scrolled using the scroll bar. Alternatively, a single-click on one of the hypertext links (shown in blue) will jump to the indicated section.

For example: If the "Menu Options" link is selected the following screen is displayed:

Note: The directories containing both satshell and satedit must be on the PATH for the help text to be displayed.


About:

The "About Box" is displayed:

Press the "OK" button to clear the "About Box".

Source Code

#===========================================================#
# SCRIPT  : satedit                                         #
# PURPOSE : Basic text editor.                              #
#-----------------------------------------------------------#
# If using Bourne or Korn shell, the "-e" option for the    #
# "echo" commands is NOT required.                          #
#===========================================================#

#-------------------------------------------------------#
# Display main screen: Display main editor screen.      #
#-------------------------------------------------------#
main() {

cat << !
newScreen {{"SATEDIT"} 70x21}
addMenu {
   {File
      {New newedit}
      {Open {openfile file:open} fileselect(.)}
      {}
      {Save {savefile edit_text current_file} group(opened)}
      {Save_As {saveasfile edit_text file:save_as} filesave(.)}
      {}
      {Exit exit}
   }
   {Help
      {Help displayhelptext}
      {About about}
   }
}
addText {edit_text 1,1 74x22 courier(10) edit outline xyscroll}
!

}

#------------------------------------------------------#
# Clear edit screen and initialise for new edit.       #
#------------------------------------------------------#
newedit() {

cat << !
addData  {current_file ""}
setTitle {"SATEDIT:"}
setItem  {edit_text {}}
setGroup {}
unlock
!

}

#------------------------------------------------------#
# Open file and load into main editor screen.          #
#------------------------------------------------------#
openfile() {

cat << !
addData  {current_file "$1"}
setTitle {"SATEDIT: `basename $1`"}
setGroup {opened}
!

gawk '
BEGIN {printf "setItem {edit_text {"}
      {print}
END   {print "}};unlock"}' $1

}

#------------------------------------------------------#
# Save text to currently open file.                    #
#------------------------------------------------------#
savefile() {

echo -e "$1\c" > $2
echo "unlock"

}

#------------------------------------------------------#
# Save text to a file with a different name.           #
#------------------------------------------------------#
saveasfile() {

echo -e "$1\c" > $2
cat << !
addData  {current_file "$2"}
setTitle {"SATEDIT: `basename $2`"}
setGroup {opened}
unlock
!

}

#-------------------------------------------------------#
# Help text: Display help text screen.                  #
#-------------------------------------------------------#
helptext() {

cat << !
newScreen {{"SATEDIT: Help"} 40x20}
addText {help_text 1,1 34x18 outline yscroll}
setItem {help_text {
<label top><font helvetica><size 18><b><u>SATEDIT HELP</u></b><size 10>
<label contents>
<b><u>Contents:</u></b>

<link overview>Overview</link>
<link menuoptions>Menu Options</link>

The blue text above indicates that these are
either links to other parts of this help text,
or actions which will invoke an external
command. In this case they are both links to
other parts of the help text currently loaded
in this text item.

A single click on one of the links will move the
display to put the corresponding label as close
to the top of the screen as possible.
<label overview>
<b><u>Overview:</u></b> (<link contents>Goto Contents</link>)

SATEDIT is an application intended to
demonstrate the following SATSHELL
features:-

* The text item in both edit and read modes.
* Drop down menus.
* File select and save dialogs.
* Calling SATSHELL from a SATSHELL.
* Emulating a dialog box using a grid item.

This help text forms the main part of the text
item read mode and tag processing demonstration.
<label menuoptions>
<b><u>Menu Options:</u></b> (<link contents>Goto Contents</link>)

The following options are availble under the File
menu:-

<b>New</b> Prepares editor for new document.
     Text and open filename are cleared.

<b>Open</b> Open existing file.
     The file select dialog is displayed.

<b>Save</b> Saves currently open file.
     This option is not availble until a file
     is opened or "saved as".

<b>Save As</b> Saves current text as a new file.
     The file save dialog is displayed.

<b>Exit</b> Exits the editor.

<link top>Goto Top</link>
}}
!

}

#-------------------------------------------------------#
# Display help text using new shell.                    #
#-------------------------------------------------------#
displayhelptext() {

satshell.tcl satedit help &

echo "unlock"

}

#-------------------------------------------------------#
# Display "About" box: Emulate pop-up using grid item.  #
#-------------------------------------------------------#
about() {

cat << !
addGrid {about 20,6 18 {
   {{!SATEDIT_Version_1.0 yellow black}}
   {{!This_is_a_SATSHELL\ndemonstration_application.\n\nCopyright_(c)_2002\nAdrian_Davis gray}}
   {{OK}}
   } aboutclear
}
unlock
!

}

#-------------------------------------------------------#
# Clear/delete about box display.                       #
#-------------------------------------------------------#
aboutclear() {

echo "remove about;unlock"

}

#------------#
# Initialise #
#------------#

if [ "$1" = "help" ]
then
   helptext
else
   main
fi

#-----------#
# Main Loop #
#-----------#
while true
do
   read Command
   [ -z "$Command" ] && exit
   eval "$Command"
done

#---------------#
# End of script #
#---------------#

Comments

This aplication consists of eleven sections:

  1. A function to display the main edit screen. (main).
  2. A function to clear the edit text and initialise for a new edit. (newedit).
  3. A function to read a file into the editor. (openfile).
  4. A function to save the edited text to the current file. (savefile).
  5. A function to save the edited text to a new/different file. (saveasfile).
  6. A function to create a "help text" display. (helptext).
  7. A function to display the "help text" in a new window. (displayhelptext).
  8. A function to display the "About Box". (about).
  9. A function to clear the "About Box".(aboutclear).
  10. Code to display the initial screen (Initialise).
  11. Code to read and run Action commands (Main Loop).


main - Display main editor screen.

main() {

Define the main function.

cat << !

A shell script "here" document is used to write SAT/DL commands to Standard Output. This will be read and interpreted by SATSHELL.

newScreen {{"SATEDIT:"} 70x21}

Clear the screen/message line, set the application screen size to 70 characters by 21 rows, and set the window title to "SATEDIT:".

addMenu {
   {File
      {New newedit}
      {Open {openfile file:open} fileselect(.)}
      {}
      {Save {savefile edit_text current_file} group(opened)}
      {Save_As {saveasfile edit_text file:save_as} filesave(.)}
      {}
      {Exit exit}
   }
   {Help
      {Help displayhelptext}
      {About about}
   }
}

Add a menu bar with two drop-down menus:

addText {edit_text 1,1 74x22 courier(10) edit outline xyscroll}

Add an edit type text item called edit_text with its top left corner at column 1, row 1 which is 74 characters wide and 22 lines deep, the text to be displayed in a courier size 10 font. The text item also has an outline and both horizontal and vertical scrollbars (xyscroll).

Note: The width of an editable text item depends on the font used.

!

End the "here" document.

}

End the function definition.


newedit - Clear text and initailise for new edit.

newdit() {

Define the newedit function.

cat << !

A shell script "here" document is used to write SAT/DL commands to Standard Output. This will be read and interpreted by SATSHELL.

addData  {current_file ""}

Set the SATSHELL current_file data item to null. Data items can be considered as SAT/DL variables. This data item is used to store the filename which will be passed as parameters to actions.

setTitle {"SATEDIT"}

Set the window title to SATEDIT:. This has the effect of clearing the current filename from the titlebar.

setItem  {edit_text {}}

Set the edit_text text item to null. This has the effect of deleting all text.

setGroup {}

Set current group to null. The Save option from the File menu is only active when the current group is set to opened. Setting the current group to null has the effect of disabling the Save option.

!

End the "here" document.

}

End the function definition.


openfile - Open file and load into main editor screen.

openfile() {

Define the openfile function.

cat << !

A shell script "here" document is used to write SAT/DL commands to Standard Output. This will be read and interpreted by SATSHELL.

addData  {current_file "$1"}

Set the SATSHELL current_file data item to the name of the selected file. Data items can be considered as SAT/DL variables. This data item is used to store the filename which will be passed as parameters to actions.

setTitle {"SATEDIT: `basename $1`"}

Set the window title to "SATEDIT: `basename $1`". This will display the name of the current file in the window titlebar.

setGroup {opened}

Set current group to opened. The Save option from the File menu is only active when the current group is set to opened. Setting the current group to opened has the effect of enabling the Save option.

!

End the "here" document.

gawk '
BEGIN {printf "setItem {edit_text {"}
      {print}
END   {print "}};unlock"}' $1

Format the contents of the current file into a SAT/DL setItem command. The unlock is required because SATSHELL "locks" the application window when an Action is triggered to prevent new Actions while the current is being processed.

}

End the function definition.


savefile - Save text to currently open file.

savefile() {

Define the savefile function.

echo -e "$1\c" > $2

Write the contents of edit_text ($1) to the current file ($2). Do not use the "-e" option when using the Bourne or Korn shells.

Note: Newlines in text items are passed as "\n". When using the bash shell the "-e" option is required in order to translate "\n" into a newline. This option should not be used with Bourne shell (sh) or Korn shell (ksh).

echo "unlock"

The unlock is required because SATSHELL "locks" the application window when an Action is triggered to prevent new Actions while the current is being processed.

}

End the function definition.


saveasfile - Save text to a file with a different name.

saveasfile() {

Define the saveasfile function.

echo -e "$1\c" > $2

Write the contents of edit_text ($1) to the new current file ($2). Do not use the "-e" option when using the Bourne or Korn shells.

Note: Newlines in text items are passed as "\n". When using the bash shell the "-e" option is required in order to translate "\n" into a newline. This option should not be used with Bourne shell (sh) or Korn shell (ksh).

cat << !

A shell script "here" document is used to write SAT/DL commands to Standard Output. This will be read and interpreted by SATSHELL.

addData  {current_file "$2"}

Set the SATSHELL current_file data item to the name of the selected file. Data items can be considered as SAT/DL variables. This data item is used to store the filename which will be passed as parameters to actions.

setTitle {"SATEDIT: `basename $2`"}

Set the window title to "SATEDIT: `basename $2`". This will display the name of the current file in the window titlebar.

setGroup {opened}

Set current group to opened. The Save option from the File menu is only active when the current group is set to opened. Setting the current group to opened has the effect of enabling the Save option.

!

End the "here" document.

}

End the function definition.


helptext - Display help text screen.

helptext() {

Define the helptext function.

cat << !

A shell script "here" document is used to write SAT/DL commands to Standard Output. This will be read and interpreted by SATSHELL.

newScreen {{"SATEDIT: Help"} 40x20}

Clear the screen/message line, set the application screen size to 40 characters by 20 rows, and set the window title to "SATEDIT: Help".

addText {help_text 1,1 34x18 outline yscroll}

Add a text item called help_text with its top left corner at column 1, row 1 which is 34 characters wide and 18 lines deep. The text item also has an outline and a vertical scrollbar (yscroll).

setItem {help_text {
<label top><font helvetica><size 18><b><u>SATEDIT HELP</u></b><size 10>
<label contents>
<b><u>Contents:</u></b>

<link overview>Overview</link>
<link menuoptions>Menu Options</link>

The blue text above indicates that these are
either links to other parts of this help text,
or actions which will invoke an external
command. In this case they are both links to
other parts of the help text currently loaded
in this text item.

A single click on one of the links will move the
display to put the corresponding label as close
to the top of the screen as possible.
<label overview>
<b><u>Overview:</u></b> (<link contents>Goto Contents</link>)

SATEDIT is an application intended to
demonstrate the following SATSHELL
features:-

* The text item in both edit and read modes.
* Drop down menus.
* File select and save dialogs.
* Calling SATSHELL from a SATSHELL.
* Emulating a dialog box using a grid item.

This help text forms the main part of the text
item read mode and tag processing demonstration.
<label menuoptions>
<b><u>Menu Options:</u></b> (<link contents>Goto Contents</link>)

The following options are availble under the File
menu:-

<b>New</b> Prepares editor for new document.
     Text and open filename are cleared.

<b>Open</b> Open existing file.
     The file select dialog is displayed.

<b>Save</b> Saves currently open file.
     This option is not availble until a file
     is opened or "saved as".

<b>Save As</b> Saves current text as a new file.
     The file save dialog is displayed.

<b>Exit</b> Exits the editor.

<link top>Goto Top</link>
}}

Set the help_text text item. This text item contains text which uses tags to define attributes and links (See Text Item Tags).

Note: The text to be added using the setItem must be enclosed in braces "{}" not quotes.

!

End the "here" document.

}

End the function definition.


displayhelptext - Display help text using new shell.

displayhelptext() {

Define the displayhelptext function.

satshell.tcl satedit help &

Start another copy of satshell as a background process. The help parameter causes the helptext screen to be displayed instead of the normal edit screen.

echo "unlock"

The unlock is required because SATSHELL "locks" the application window when an Action is triggered to prevent new Actions while the current is being processed.

}

End the function definition.


about - Emulate pop-up using grid item.

about() {

Define the about function.

cat << !

A shell script "here" document is used to write SAT/DL commands to Standard Output. This will be read and interpreted by SATSHELL.

addGrid {about 20,6 18 {
   {{!SATEDIT_Version_1.0 yellow black}}
   {{!This_is_a_SATSHELL\ndemonstration_application.\n\nCopyright_(c)_2002\nAdrian_Davis gray}}
   {{OK}}
   } aboutclear
}

Add a grid item called about with its top left corner at column 20, row 6 which has a cell width of 18 characters. The grid has three rows, each with a single cell. The first row displays the text "SATEDIT Version 1.0" in yellow text on a black background. The second row displays "This is a SATSHELL demonstration application. Copyright (c) 2002 Adrian Davis" across 5 lines on a gray background. The third row is a button with an "OK" label. When the button is pressed the aboutclear function is run.

Note: In the grid item underscores will be replaced with spaces and "\n" will create a new line.

unlock

The unlock is required because SATSHELL "locks" the application window when an Action is triggered to prevent new Actions while the current is being processed.

!

End the "here" document.

}

End the function definition.


aboutclear - Clear/delete about box display.

aboutclear() {

Define the aboutclear function.

echo "remove about;unlock"

remove the about item. The unlock is required because SATSHELL "locks" the application window when an Action is triggered to prevent new Actions while the current is being processed.

Note: Each line can contain more than one SAT/DL command if separated by a semi colon ";".

}

End the function definition.


"Initialise" - Select and display "main" or "help" screen.

if [ "$1" = "help" ]
then
   helptext
else
   main
fi

If the first parameter ($1) to the SATEDIT script is "help" display helptext, otherwise display the main edit screen.


"Main Loop" - Read and run Action commands.

while true
do

Start a "Do forever" loop.

   read Command

Read an Action command from standard input.

   [ -z "$Command" ] && exit

If the "Command" is null then the application window has closed, so exit the script. This check is important as the script will not otherwise terminate when the window is closed.

   eval "$Command"

Run the Action command.

Note: The "$Command" must be enclosed in double quotes.

done

End of the "Do forever" loop.


Copyright © 2003
Adrian Davis.