HTML Dialog: Difference between revisions

Latest revision as of 17:46, 1 May 2024

This object is used display a dialog to the user. The dialog is defined using a HTML web page and can collect information from the user as well as display it. The system works by associating variables within the script with HTML elements within the dialog. When the dialog is closed, the current values of edit boxes, check boxes etc. can be examined. As well as passively collecting all the data once the dialog is closed, callbacks into the lua code can be made when the user clicks on a button, selects a file or tool or chooses from a list.

Button Callbacks

If a button on the dialog has class=LuaButton, when the user clicks on the button, HTML_Dialog will search the calling script for a method with the signature

function OnLuaButton_BUTTON_ID(dialog)

where BUTTON_ID is the id of the button pressed and dialog is the HTML_Dialog object the button was pressed on.

For Example

For HTML: 
  <input class="LuaButton" id="TestButton1" type=button value="Press Me!">

For Lua: 
  function OnLuaButton_TestButton1(dialog)
    MessageBox("User pressed TestButton1")
    local cur_num_machines = dialog:GetIntegerField("MachineCount")
    return true 
  end

NOTE: The callback functions MUST have return true at the end or you will get script errors! If a specific handler is not found for the button an attempt will be made to call a generic handler with the signature

Example Code:

 function OnLuaButton_XXXX(element_id, dialog)
    MessageBox(Button with id = "   element   " was pressed!")
    local cur_num_machines = dialog:GetIntegerField("MachineCount")
    return true 
  end

For Example:

In HTML: 
  <input class="LuaButton" id="TestButton1" type=button value="Press Me!">

In Lua: 
  function OnLuaButton_TestButton1(dialog) MessageBox("User pressed TestButton1")
    local cur_num_machines = dialog:GetIntegerField("MachineCount")
    return true 
  end

Callbacks

DirectoryPicker Callbacks

When a DirectoryPicker is used to pick a directory, HTML_Dialog will will search the calling script for a method with the signature

function OnDirectoryPicker_PICKER_ID(dialog)

where PICKER_ID is the id of the directory picker button pressed and dialog is the HTML_Dialog object the button was pressed on.

FilePicker Callbacks

When a FilePicker is used to pick a file, HTML_Dialog will will search the calling script for a method with the signature

function OnFilePicker_PICKER_ID(dialog)

where PICKER_ID is the id of the file picker button pressed and dialog is the HTML_Dialog object the button was pressed on.

ToolPicker Callbacks

When a ToolPicker is used to pick a tool, HTML_Dialog will will search the calling script for a method with the signature

function OnToolPicker_PICKER_ID(dialog)

where PICKER_ID is the id of the tool picker button pressed and dialog is the HTML_Dialog object the button was pressed on.

Selector or DropDownList Callbacks

When a Selector or DropDownList is used to pick a value, HTML_Dialog will will search the calling script for a method with the signature

function OnLuaSelector_ELEMENT_ID(dialog)

where ELEMENT_ID is the id of the selector or dropdown list button pressed and dialog is the HTML_Dialog object the list was seelcted on. If a specific handler is not found for the list an attempt will be made to call a generic handler with the signature

Example Code:

 function OnLuaSelector_XXXX(element_id, dialog)
   local selected_value = dialog:GetDropDownListValue(element_id)
   MessageBox("Value " ..  selected_value .. " was selected from List with id = " ..  element_id)
   return true
 end -- function end

Constructor

HTML_Dialog(bool local_html, string html, integer width, integer height, string dialog_name)

Create a new dialog object , specifying the source for the HTML and the dialog size and title. local_html (bool) true if the next argument (html) contains all the html code for the dialog in the string. If false the html string is the path to the html file.

html (string) local_html was true, contains all the html code for the dialog in the string. If local_html was false the html string is the path to the html file. The path must be fully qualified and is usually built up from the scripts location as shown in the example below.

width (integer) width of the dialog in pixels

height (integer) height of the dialog in pixels

dialog_name (string) name for dialog displayed in title bar

Example Code:

 function main(script_path)
   local html_path = "file:"   script_path about.htm"
   local dialog = HTML_Dialog(false, html_path, 800, 600, "About Gadgets")
   dialog:ShowDialog()
 end -- function end

Properties

.WindowWidth

Interaction: Read Only

Returns: (integer) Width of dialog window in pixels when user closed the dialog.

For Example:

-- On closed of the dialog place:
  DisplayMessageBox("X= " .. tostring(dialog.WindowWidth) .. "\n" .. 
                    "Y= " .. tostring(dialog.WindowHeight)
                   )

.WindowHeight

Interaction: Read Only

Returns: (integer) Height of dialog window in pixels when user closed the dialog.

For Example:

-- On closed of the dialog place:
  DisplayMessageBox("X= " .. tostring(dialog.WindowWidth) .. "\n" .. 
                    "Y= " .. tostring(dialog.WindowHeight)
                   )
   or

DialogWindow.AboutXY = tostring(dialog.WindowWidth) .. " x " .. tostring(dialog.WindowHeight)

Methods

:AddCheckBox(string element_ id, bool value)

Sets a check box element (input box displaying a check box) in the HTML with id=element_id to passed value.

element_id (string) Id of the element in HTML to set to value (id=element_id in HTML)

value(bool) true to check box, false to leave unchecked

For Example:

For HTML: <INPUT class="LuaButton" 
                      type="checkbox" 
                      checked ID="CreatePreviewCheck" 
                      value='active'> Create a preview

For Lua: dialog:AddCheckBox("CreatePreviewCheck", true)

:AddDirectoryPicker(string element_ id, string buddy_name, bool buddy_is_edit)

Sets a button on the dialog to act as a directory chooser. When the user presses the button, a dialog is displayed to allow them to select a directory or folder. When the selection dialog is closed the buddy field (which can either be an edit box or a label) is updated with the path to the directory or folder chosen.

NOTE: The <Button > element MUST have a class = DirectoryPicker set

The button MUST have class = DirectoryPicker

element_id (string) id of the button element in HTML to use (id=element_id in HTML)

element_name (string) name of the button element in HTML is Required (name=element_name in HTML)

buddy_name (string) id of associated label or edit field which will hold the value the user picks

buddy_is_edit(bool) true if the buddy field is an edit field (added with AddTextField), false if buddy is a label field (added with AddLabelField).

Example of TextField (Revised: Mar 13, 2024)

For HTML: For picker associated with an edit field:
   <input name="textfield" type="text" size="40" maxlength="128" id="DirNameEdit"> 
   <input class="DirectoryPicker" id="ChooseDirButton1" name="ChooseDirButton1" type=button value="Choose"> 

Lua for picker associated with an editable text field:
   dialog:AddTextField("DirNameEdit", "c:\\temp");
   dialog:AddDirectoryPicker("ChooseDirButton1", "DirNameEdit", true);

Example of LabelField (Revised: Mar 13, 2024)

HTML for picker associated with a label field:
   <span id="DirNameLabel">< or span>
   <input class="DirectoryPicker" id="ChooseDirButton2" name="ChooseDirButton2" type=button value="Choose">

For Lua: For picker associated with a label field:
    dialog:AddLabelField("DirNameLabel", "c:\\");
    dialog:AddDirectoryPicker("ChooseDirButton2", "DirNameLabel", false);

:AddDoubleField(string element_ id, double value)

Sets a text box element (text input box displaying a double value) in the HTML with id=element_id to passed value.

element_id (string) Id of the element in HTML to set to value (id=element_id in HTML)

value(double) value to set for element in HTML

Example:

HTML: <input name="textfield</q> type="text</q> size="8</q> maxlength="8</q> ID="MachineCost</q>> 
 Lua: dialog:AddDoubleField("MachineCost</q>, 6495.12)

:AddDropDownList(string element_ id, string default_value)

Sets a dropdown list in the HTML (type=select) with id=element_id to passed value.

element_id (string) Id of the element in HTML to set to value (id=element_id in HTML)

value (string) initial value to set for element in HTML

Example

HTML: 
  <select id="ProductList" >
    <option value="1">first</option>
    <option value="2" selected>second</option>
    <option value="3" >third</option> 
  </select>

Lua:
  dialog:AddDropDownList("ProductList"     , "Aspire") 
  dialog:AddDropDownListValue("ProductList", "Cut2D") 
  dialog:AddDropDownListValue("ProductList", "VCarve Pro") 
  dialog:AddDropDownListValue("ProductList", "Aspire") 
  dialog:AddDropDownListValue("ProductList", "Cut3D") 
  dialog:AddDropDownListValue("ProductList", "PhotoVCarve")
 
------------------------------------------------------------------
 myList = {"Aspire", "Cut2D","VCarve Pro","Cut3D","PhotoVCarve" }

 dialog:AddDropDownList("ProductList", "Aspire")
 
 for i=1, #myList do
   dialog:AddDropDownListValue("ProductList", myList[i])
 end -- for loop end

:AddDropDownListValue(string element_ id, string value)

Add a value to a dropdown list n the HTML (type=select) with id=element_id to passed value. The element_id (string) Id of the select list in HTML to add value to (id=element_id in HTML)

value (string)value to add to list of values

Example (Revised: Apr 1, 2023)

HTML: 
  <select id="ProductList" ></select>

Lua:
 myList = {"Aspire", "Cut2D","VCarve Pro","Cut3D","PhotoVCarve" }

 dialog:AddDropDownList("ProductList", "Aspire")
 
 for i=1, #myList do
   dialog:AddDropDownListValue("ProductList", myList[i])
 end -- for loop end

:AddFilePicker(bool File_can_be_new, string element_ id, string buddy_name, bool buddy_is_edit)

Sets a button on the dialog to act as a file chooser. When the user presses the button a dialog is displayed to allow them to select a file. When the selection dialog is closed the buddy field (which can either be an edit box or a label) is updated with the path to file chosen.

NOTE: The <Button > element MUST have a class = FilePicker set

element_id (string) Id of the button element in HTML to use (id=element_id in HTML). The button MUST have class = FilePicker

buddy_name (string) id of associated label or edit field which will hold the value the user picks

buddy_is_edit (bool) true if the buddy field is an edit field (added with AddTextField), false if buddy is a label field (added with AddLabelField).

Example of TextField (Revised: Mar 13, 2024)

HTML: 
  For picker associated with an edit text field:
      <input name="textfield" type="text" size="40" maxlength="128" id="FileNameEdit">
      <input clase="FilePicker" id="ChooseFileButton1" name="ChooseFileButton1" type=button value="Choose">

Lua:
  For picker associated with new file and an editable text field:
     dialog:AddTextField("FileNameEdit", "c:\\temp")
     dialog:AddDirectoryPicker(true, "ChooseFileButton1", "FileNameEdit", true) 

Lua:
  For picker associated with existing file and an editable text field:
     dialog:AddTextField("FileNameEdit", "c:\\temp")
     dialog:AddDirectoryPicker(false, "ChooseFileButton1", "FileNameEdit", true)

Example of LabelField (Revised: Mar 13, 2024)

HTML:
 For picker associated with a label field:
    <span id="FileNameLabel">< or span>
     <imput class="FilePicker" id="ChooseFileButton2" name="ChooseFileButton2" type=button value="Choose" > 
 
 Lua:
   For picker associated with new file and a label field:
     dialog:AddLabelField("FileNameLabel", "c:\\")
     dialog:AddFilePicker(true, "ChooseFileButton2", "FileNameLabel", false) 
 
 Lua: 
   For picker associated with existing file and a label field:
     dialog:AddLabelField("FileNameLabel", "c:\\")
     dialog:AddFilePicker(false, "ChooseFileButton2", "FileNameLabel", false)

:AddIntegerField(string element_ id, integer value)

Sets a text box element (text input box displaying an integer value) in the HTML with id=element_id to passed value.

element_id (string) Id of the element in HTML to set to value (id=element_id in HTML)

value (integer) value to set for element in HTML

Example:

HTML:
  <input name="textfield" type="text" size="4" maxlength="8" ID="MachineCount"> 

Lua:
 dialog:AddIntegerField("MachineCount", 1)

:AddLabelField(string element_ id,string value)

Sets a text element in the HTML with id=element_id to passed value

element_id (string) Id of the element in HTML to set to value (id=element_id in HTML)

value (string) Value to set for element in HTML

Example:

HTML: 
  <span id="WelcomeText">Welcome to our first test HTML dialog <br>created via Lua </span>

Lua: 
  dialog:AddLabelField("WelcomeText", "Welcome to my <b>Lua< or b> HTML dialog")

:AddRadioGroup(string element_ id, int default_index)

Sets a radio group in the HTML (type=radio) with id=element_id to passed value. Note that the radio index is one based, so the first item in the group is 1.

element_id (string) Id of the element in HTML to set to value (id=element_id in HTML)

default_index (integer) index of radio button to check in HTML (1 based)

Example:

HTML: 
  Type of Machine
    <input class="LuaButton" type="radio" name="MachineType" ID="MachineRadio1"> Engraver
    <input class="LuaButton" type="radio" name="MachineType" ID="MachineRadio2"> Router
    <input class="LuaButton" type="radio" name="MachineType" ID="MachineRadio3"> CNC Mill

Lua:
  dialog:AddRadioGroup("MachineType", 2)

:AddTextField(string element_ id, string value)

Sets a text element (text input box) in the HTML with id=element_id to passed value.

element_id (string)Id of the element in HTML to set to value (id=element_id in HTML) value (string) value to set for element in HTML

Example:

HTML:
  <input name="textfield" type="text" size="20" maxlength="8" ID="MachineName"> 

Lua:
  dialog:AddTextField("MachineName", "Rosy")

:AddToolEditor(string element_ id, string buddy_name)

Sets a button on the dialog to act as a tool editor. When the user presses the button, the tool editor dialog is displayed to allow them to edit the tool chosen by the associated buddy ToolPicker. The buddy field which MUST be a ToolPicker added with AddToolPickers has the path to the tool chosen by the tool picker. element_id (string)Id of the button element in HTML to use (id=element_id in HTML). The button MUST have class = ToolPicker buddy_name (string) id of associated tool picker which will hold the path to the tool the user picks.

:AddToolPicker(string element_ id, string buddy_name, string ToolDBId tooldb_id)

Sets a button on the dialog to act as a tool chooser. When the user presses the button the tool database dialog is displayed to allow them to select a tool. When the selection dialog is closed the buddy field which MUST be a label added with AddLabelField is updated with the path to the tool chosen.

element_id (string) Id of the button element in HTML to use (id=element_id in HTML). The button MUST have class = ToolPicker

buddy_name (string) Id of associated label field which will hold the path to the tool the user picks. default_tool_name (string) default tool name and path in the tool database usually saved from a previous selection by the tool picker.

Example:

HTML:
 ---------------------------------------------------------------
  CCS Sample:
    .ToolPicker {
	font-weight:bold;
	text-align:center;
	font-family:Arial, Helvetica, sans-serif;
        font-size:12px;
     }
     .ToolNameLabel {
	font-family:Arial, Helvetica, sans-serif;
	font-weight:bold;
	font-size:10px;
	text-align:left;
      }
 ---------------------------------------------------------------
  Button Sample:
    <td width="120" align="right" nowrap class="h1-r">Tool:</td>
    <td nowrap="nowrap" class="ToolNameLabel"><span id = "ToolNameLabel">-</span></td>
    <td width="49" nowrap class="ToolPicker"><input id = "ToolChooseButton" class = "ToolPicker" name = "ToolChooseButton" type = "button" value = "Tool"></td>

 ---------------------------------------------------------------
 For Lua: For picker associated with a label field:
                                    dialog:AddLabelField("ToolNameLabel",", ");
                                    dialog:AddToolPicker("ToolChooseButton", "ToolNameLabel"," ")
                                    dialog:AddToolPickerValidToolType("ToolChooseButton",     Tool.END_MILL)
                                    dialog:AddToolPickerValidToolType("ToolChooseButton",     BALL_NOSE)

:AddToolPickerValidToolType(string element_ id, integer tool_type)

Used to add valid tool types for the tool database. See below for a list of valid values

element_id (string)Id of the toolpicker element in HTML to add valid type to (id=element_id in HTML). The button MUST have class = ToolPicker tool_type (integer) Integer indicating a type of tool which will be valid for selection.

Choose from:

Tool.BALL_NOSE

Tool.END_MILL

Tool.RADIUSED_END_MILL

Tool.VBIT

Tool.ENGRAVING

Tool.RADIUSED_ENGRAVING

Tool.THROUGH_DRILL

Tool.FORM_TOOL

Tool.DIAMOND_DRAG

Tool.RADIUSED_FLAT_ENGRAVING

:ClearToolPickerValidToolType(string element_ id)

Used to clear list of valid tool types for the tool database.

element_id (string)Id of the toolpicker element in HTML to clear(id=element_id in HTML). The button MUST have class = ToolPicker

:GetCheckBox(string id)

Returns: a boolean containing current value of a check box in the HTML with id=element_id . The field MUST have been created with a previous call to AddCheckBox before the dialog was displayed.

element_id (string)Id of the element in HTML to get to value for (id= element_id in HTML)

Example Code:

 Project.Debugger = dialog:GetCheckBox("Project.Debugger")

:GetDropDownListValue(string id)

Returns: a string containing current value of a dropdown list (select element) in the HTML with id=element_id . The field must have been created with a previous call to AddDropDownList before the dialog was displayed.

element_id (string)Id of the element in HTML to get value for (id= element_id in HTML)

Example Code:

 Local CabCount = dialog:GetDropDownListValue("CabCount")

:GetDoubleField(string id)

Returns: a double containing current value of a text input box displaying a double value in the HTML with id=element_id . The field must have been created with a previous call to AddDoubleField before the dialog was displayed.

element_id (string)Id of the element in HTML to get value for (id= element_id in HTML)

Example Code:

 Local CabHeight = dialog:GetDoubleField("CabHeight")

:GetIntegerField(string id)

Returns: an integer containing current value of a text input box displaying an integer value in the HTML with id=element_id . The field must have been created with a previous call to AddIntegerField before the dialog was displayed.

element_id (string)Id of the element in HTML to get value for (id= element_id in HTML)

Example Code:

 DXF.RowCount   = dialog:GetIntegerField("DXF.RowCount")

:GetLabelField(string id)

Returns: a string containing current value of an element in the HTML with id=element_id . The field must have been created with a previous call to AddLabelField before the dialog was displayed. 
element_id (string) Id of the element in HTML to get value for (id= element_id in HTML)

:GetRadioIndex(string id)

Returns: an integer containing current value of a radio group  in the HTML with id=element_id . The field must have been created with a previous call to AddRadioGroup before the dialog was displayed.

element_id (string)Id of the element in HTML to get  value for (id= element_id in HTML)

:GetTextField(string id)

Returns: a string containing current value of a text input box element in the HTML with id=element_id . The field must have been created with a previous call to AddTextField before the dialog was displayed.

element_id (string) Id of the element in HTML to get value for (id= element_id in HTML)

Example Code:

 DXF.CSVPath = dialog:GetTextField("DXF.CSVPath")

:GetTool (string element_ id)

Returns: the Tool selected by the ToolPicker with the passed id.

element_id (string)Id of the button element in HTML to use (id=element_id in HTML). The button MUST have class = ToolPicker

:SetInnerHtml(string element_ id, string html)

Sets the inner html for an element on the dialog.

element_id (string)Id of the element in HTML to set inner html for (id= element_id in HTML) html (string) new inner html for the element

:SetOuterHtml(string element_ id, string html)

Sets the outer html for an element on the dialog. This can replace the complete element definition

element_id (string)Id of the element in HTML to set outer html for (id= element_id in HTML)

html (string) new outer html for the element

:UpdateCheckBox(string element_ id, bool value)

Update check box in the HTML with id=element_id to passed value. The field must have been created with a previous call to AddCheckBox before the dialog was displayed. This method is used within callbacks from the dialog, while the dialog is still visible.