Quelle  SF_DialogControl.xba   Sprache: unbekannt

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE script:module PUBLIC "-//OpenOffice.org//DTD OfficeDocument 1.0//EN" "module.dtd">
<script:module xmlns:script="http://openoffice.org/2000/script" script:name="SF_DialogControl" script:language="StarBasic" script:moduleType="normal">REM =======================================================================================================================
REM ===   The ScriptForge library and its associated libraries are part of the LibreOffice project.    ===
REM ===      The SFDialogs library is one of the associated libraries.         ===
REM ===     Full documentation is available on https://help.libreoffice.org/        ===
REM =======================================================================================================================

Option Compatible
Option ClassModule

Option Explicit

'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
''' SF_DialogControl
''' ================
'''  Manage the controls belonging to a dialog defined with the Basic IDE
'''  Each instance of the current class represents a single control within a dialog box
'''
'''  The focus is clearly set on getting and setting the values displayed by the controls of the dialog box,
'''  not on their formatting. The latter is easily accessible via the XControlModel and XControlView
'''  UNO objects.
'''  Essentially a single property "Value" maps many alternative UNO properties depending each on
'''  the control type.
'''
'''  A special attention is given to controls with types TreeControl and TableControl
'''   It is easy with the API proposed in the current class to populate a tree, either
'''    - branch by branch (CreateRoot and AddSubNode), or
'''    - with a set of branches at once (AddSubtree)
'''   Additionally populating a TreeControl can be done statically or dynamically
'''
'''   With the method SetTableData(), feed a tablecontrol with a sortable and selectable
'''   array of data. Columns and rows may receive a header. Column widths are adjusted manually by the user or
'''   with the same method. Alignments can be set as well by script.
'''
'''  Service invocation:
'''   Dim myDialog As Object, myControl As Object
'''    Set myDialog = CreateScriptService("SFDialogs.Dialog", "GlobalScope", myLibrary, DialogName)
'''    Set myControl = myDialog.Controls("myTextBox")
'''    myControl.Value = "Dialog started at " & Now()
'''    myDialog.Execute()
'''    ' ... process the controls actual values
'''    myDialog.Terminate()
'''
'''  Detailed user documentation:
'''   https://help.libreoffice.org/latest/en-US/text/sbasic/shared/03/sf_dialogcontrol.html?DbPAR=BASIC
'''
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

REM ================================================================== EXCEPTIONS

Private Const CONTROLTYPEERROR  = "CONTROLTYPEERROR"
Private Const TEXTFIELDERROR  = "TEXTFIELDERROR"

REM ============================================================= PRIVATE MEMBERS

Private [Me]    As Object
Private [_Parent]   As Object
Private ObjectType   As String  ' Must be DIALOGCONTROL
Private ServiceName   As String

' Control naming
Private _Name    As String
Private _IndexOfNames  As Long   ' Index in ElementNames array. Used to access SF_Dialog._ControlCache
Private _DialogName   As String  ' Parent dialog name

' Control UNO references
Private _ControlModel  As Object  ' com.sun.star.awt.XControlModel
Private _ControlView  As Object  ' com.sun.star.awt.XControl - stardiv.Toolkit.UnoDialogControl
Private _TreeDataModel  As Object  ' com.sun.star.awt.tree.MutableTreeDataModel
Private _GridColumnModel As Object  ' com.sun.star.awt.grid.XGridColumnModel
Private _GridDataModel  As Object  ' com.sun.star.awt.grid.XGridDataModel

' Control attributes
Private _ImplementationName As String
Private _ControlType  As String  ' One of the CTLxxx constants

' Control initial position and dimensions in APPFONT units
Private _Left    As Long
Private _Top    As Long
Private _Width    As Long
Private _Height    As Long

' Tree control on-select and on-expand attributes
' Tree controls may be associated with events not defined in the Basic IDE
Private _OnNodeSelected  As String  ' Script to invoke when a node is selected
Private _OnNodeExpanded  As String  ' Script to invoke when a node is expanded
Private _SelectListener  As Object  ' com.sun.star.view.XSelectionChangeListener
Private _ExpandListener  As Object  ' com.sun.star.awt.tree.XTreeExpansionListener

' Updatable events
Private _ActionListener  As Object  ' com.sun.star.awt.XActionListener
Private _OnActionPerformed As String  ' Script to invoke when action triggered
Private _ActionCounter  As Integer  ' Counts the number of events set on the listener
' ---
Private _AdjustmentListener As Object  ' com.sun.star.awt.XAdjustmentListener
Private _OnAdjustmentValueChanged As String ' Script to invoke when scrollbar value has changed
Private _AdjustmentCounter As Integer  ' Counts the number of events set on the listener
' ---
Private _FocusListener  As Object  ' com.sun.star.awt.XFocusListener
Private _OnFocusGained  As String  ' Script to invoke when control gets focus
Private _OnFocusLost  As String  ' Script to invoke when control loses focus
Private _FocusCounter  As Integer  ' Counts the number of events set on the listener
' ---
Private _ItemListener  As Object  ' com.sun.star.awt.XItemListener
Private _OnItemStateChanged As String  ' Script to invoke when status of item changes
Private _ItemCounter  As Integer  ' Counts the number of events set on the listener
' ---
Private _KeyListener  As Object  ' com.sun.star.awt.XKeyListener
Private _OnKeyPressed  As String  ' Script to invoke when Key clicked in control
Private _OnKeyReleased  As String  ' Script to invoke when Key released in control
Private _KeyCounter   As Integer  ' Counts the number of events set on the listener
' ---
Private _MouseListener  As Object  ' com.sun.star.awt.XMouseListener
Private _OnMouseEntered  As String  ' Script to invoke when mouse enters control
Private _OnMouseExited  As String  ' Script to invoke when mouse leaves control
Private _OnMousePressed  As String  ' Script to invoke when mouse clicked in control
Private _OnMouseReleased As String  ' Script to invoke when mouse released in control
Private _MouseCounter  As Integer  ' Counts the number of events set on the listener
' ---
Private _MouseMotionListener As Object  ' com.sun.star.awt.XMouseMotionListener
Private _OnMouseDragged  As String  ' Script to invoke when mouse is dragged from the control
Private _OnMouseMoved  As String  ' Script to invoke when mouse is moved across the control
Private _MouseMotionCounter As Integer ' Counts the number of events set on the listener
' ---
Private _TabPageContainerListener As Object ' com.sun.star.awt.XTabPageContainerListener
Private _OnTabSelected  As String  ' Script to invoke when a new tab is selected
Private _TabPageContainerCounter As Integer ' Counts the number of events set on the listener
' ---
Private _TextListener  As Object  ' com.sun.star.awt.XTextListener
Private _OnTextChanged  As String  ' Script to invoke when textual content has changed
Private _TextCounter  As Integer  ' Counts the number of events set on the listener

' Table control attributes
Private _ColumnWidths  As Variant  ' Array of column widths

' TabPageContainer attributes
Private _TabHeaders   As Variant  ' Array of tab page headers as strings

REM ============================================================ MODULE CONSTANTS

Private Const CTLBUTTON    = "Button"
Private Const CTLCHECKBOX   = "CheckBox"
Private Const CTLCOMBOBOX   = "ComboBox"
Private Const CTLCURRENCYFIELD  = "CurrencyField"
Private Const CTLDATEFIELD   = "DateField"
Private Const CTLFILECONTROL  = "FileControl"
Private Const CTLFIXEDLINE   = "FixedLine"
Private Const CTLFIXEDTEXT   = "FixedText"
Private Const CTLFORMATTEDFIELD  = "FormattedField"
Private Const CTLGROUPBOX   = "GroupBox"
Private Const CTLHYPERLINK   = "Hyperlink"
Private Const CTLIMAGECONTROL  = "ImageControl"
Private Const CTLLISTBOX   = "ListBox"
Private Const CTLNUMERICFIELD  = "NumericField"
Private Const CTLPATTERNFIELD  = "PatternField"
Private Const CTLPROGRESSBAR  = "ProgressBar"
Private Const CTLRADIOBUTTON  = "RadioButton"
Private Const CTLSCROLLBAR   = "ScrollBar"
Private Const CTLTABLECONTROL  = "TableControl"
Private Const CTLTABPAGECONTAINER = "TabPageContainer"
Private Const CTLTEXTFIELD   = "TextField"
Private Const CTLTIMEFIELD   = "TimeField"
Private Const CTLTREECONTROL  = "TreeControl"

REM ====================================================== CONSTRUCTOR/DESTRUCTOR

REM -----------------------------------------------------------------------------
Private Sub Class_Initialize()
 Set [Me] = Nothing
 Set [_Parent] = Nothing
 ObjectType = "DIALOGCONTROL"
 ServiceName = "SFDialogs.DialogControl"
 _Name = ""
 _IndexOfNames = -1
 _DialogName = ""
 Set _ControlModel = Nothing
 Set _ControlView = Nothing
 Set _TreeDataModel = Nothing
 Set _GridColumnModel = Nothing
 Set _GridDataModel = Nothing
 _ImplementationName = ""
 _ControlType = ""

 _Left = SF_DialogUtils.MINPOSITION
 _Top = SF_DialogUtils.MINPOSITION
 _Width = -1
 _Height = -1

 _OnNodeSelected = ""
 _OnNodeExpanded = ""
 Set _SelectListener = Nothing
 Set _ExpandListener = Nothing

 Set _ActionListener = Nothing
 _OnActionPerformed = ""
 _ActionCounter = 0
 Set _AdjustmentListener = Nothing
 _OnAdjustmentValueChanged = ""
 _AdjustmentCounter = 0
 Set _FocusListener = Nothing
 _OnFocusGained = ""
 _OnFocusLost = ""
 _FocusCounter = 0
 Set _KeyListener = Nothing
 _OnKeyPressed = ""
 _OnKeyReleased = ""
 _KeyCounter = 0
 Set _MouseListener = Nothing
 _OnMouseEntered = ""
 _OnMouseExited = ""
 _OnMousePressed = ""
 _OnMouseReleased = ""
 _MouseCounter = 0
 Set _MouseMotionListener = Nothing
 _OnMouseDragged = ""
 _OnMouseMoved = ""
 _MouseMotionCounter = 0
 Set _ItemListener = Nothing
 _OnItemStateChanged = ""
 _ItemCounter = 0
 Set _TabPageContainerListener = Nothing
 _OnTabSelected = ""
 _TabPageContainerCounter = 0
 Set _TextListener = Nothing
 _OnTextChanged = ""
 _TextCounter = 0

 _ColumnWidths = Array()
 _TabHeaders = Array()
End Sub  ' SFDialogs.SF_DialogControl Constructor

REM -----------------------------------------------------------------------------
Private Sub Class_Terminate()
 Call Class_Initialize()
End Sub  ' SFDialogs.SF_DialogControl Destructor

REM -----------------------------------------------------------------------------
Public Function Dispose() As Variant
 Call Class_Terminate()
 Set Dispose = Nothing
End Function ' SFDialogs.SF_DialogControl Explicit Destructor

REM ================================================================== PROPERTIES

REM -----------------------------------------------------------------------------
Property Get Border() As Variant
''' The Border property refers to the surrounding of the control: 3D, FLAT or NONE
 Border = _PropertyGet("Border", "")
End Property ' SFDialogs.SF_DialogControl.Border (get)

REM -----------------------------------------------------------------------------
Property Let Border(Optional ByVal pvBorder As Variant)
''' Set the updatable property Border
 _PropertySet("Border", pvBorder)
End Property ' SFDialogs.SF_DialogControl.Border (let)

REM -----------------------------------------------------------------------------
Property Get Cancel() As Variant
''' The Cancel property specifies if a command button has or not the behaviour of a Cancel button.
 Cancel = _PropertyGet("Cancel", False)
End Property ' SFDialogs.SF_DialogControl.Cancel (get)

REM -----------------------------------------------------------------------------
Property Let Cancel(Optional ByVal pvCancel As Variant)
''' Set the updatable property Cancel
 _PropertySet("Cancel", pvCancel)
End Property ' SFDialogs.SF_DialogControl.Cancel (let)

REM -----------------------------------------------------------------------------
Property Get Caption() As Variant
''' The Caption property refers to the text associated with the control
 Caption = _PropertyGet("Caption", "")
End Property ' SFDialogs.SF_DialogControl.Caption (get)

REM -----------------------------------------------------------------------------
Property Let Caption(Optional ByVal pvCaption As Variant)
''' Set the updatable property Caption
 _PropertySet("Caption", pvCaption)
End Property ' SFDialogs.SF_DialogControl.Caption (let)

REM -----------------------------------------------------------------------------
Property Get ControlType() As String
''' Return the type of the actual control: "CheckBox", "TextField", "DateField", ...
 ControlType = _PropertyGet("ControlType")
End Property ' SFDialogs.SF_DialogControl.ControlType

REM -----------------------------------------------------------------------------
Property Get CurrentNode() As Variant
''' The CurrentNode property returns the currently selected node
''' It returns Empty when there is no node selected
''' When there are several selections, it returns the topmost node among the selected ones
 CurrentNode = _PropertyGet("CurrentNode", "")
End Property ' SFDialogs.SF_DialogControl.CurrentNode (get)

REM -----------------------------------------------------------------------------
Property Let CurrentNode(Optional ByVal pvCurrentNode As Variant)
''' Set a single selection in a tree control
 _PropertySet("CurrentNode", pvCurrentNode)
End Property ' SFDialogs.SF_DialogControl.CurrentNode (let)

REM -----------------------------------------------------------------------------
Property Get Default() As Variant
''' The Default property specifies whether a command button is the default (OK) button.
 Default = _PropertyGet("Default", False)
End Property ' SFDialogs.SF_DialogControl.Default (get)

REM -----------------------------------------------------------------------------
Property Let Default(Optional ByVal pvDefault As Variant)
''' Set the updatable property Default
 _PropertySet("Default", pvDefault)
End Property ' SFDialogs.SF_DialogControl.Default (let)

REM -----------------------------------------------------------------------------
Property Get Enabled() As Variant
''' The Enabled property specifies if the control is accessible with the cursor.
 Enabled = _PropertyGet("Enabled")
End Property ' SFDialogs.SF_DialogControl.Enabled (get)

REM -----------------------------------------------------------------------------
Property Let Enabled(Optional ByVal pvEnabled As Variant)
''' Set the updatable property Enabled
 _PropertySet("Enabled", pvEnabled)
End Property ' SFDialogs.SF_DialogControl.Enabled (let)

REM -----------------------------------------------------------------------------
Property Get Format() As Variant
''' The Format property specifies the format in which to display dates and times.
 Format = _PropertyGet("Format", "")
End Property ' SFDialogs.SF_DialogControl.Format (get)

REM -----------------------------------------------------------------------------
Property Let Format(Optional ByVal pvFormat As Variant)
''' Set the updatable property Format
 _PropertySet("Format", pvFormat)
End Property ' SFDialogs.SF_DialogControl.Format (let)

REM -----------------------------------------------------------------------------
Property Get Height() As Variant
''' The Height property refers to the height of the control
 Height = _PropertyGet("Height")
End Property ' SFDialogs.SF_DialogControl.Height (get)

REM -----------------------------------------------------------------------------
Property Let Height(Optional ByVal pvHeight As Variant)
''' Set the updatable property Height
 _PropertySet("Height", pvHeight)
End Property ' SFDialogs.SF_DialogControl.Height (let)

REM -----------------------------------------------------------------------------
Property Get ListCount() As Long
''' The ListCount property specifies the number of rows in a list box or a combo box
 ListCount = _PropertyGet("ListCount", 0)
End Property ' SFDialogs.SF_DialogControl.ListCount (get)

REM -----------------------------------------------------------------------------
Property Get ListIndex() As Variant
''' The ListIndex property specifies which item is selected in a list box or combo box.
''' In case of multiple selection, the index of the first one is returned or only one is set
 ListIndex = _PropertyGet("ListIndex", -1)
End Property ' SFDialogs.SF_DialogControl.ListIndex (get)

REM -----------------------------------------------------------------------------
Property Let ListIndex(Optional ByVal pvListIndex As Variant)
''' Set the updatable property ListIndex
 _PropertySet("ListIndex", pvListIndex)
End Property ' SFDialogs.SF_DialogControl.ListIndex (let)

REM -----------------------------------------------------------------------------
Property Get Locked() As Variant
''' The Locked property specifies if a control is read-only
 Locked = _PropertyGet("Locked", False)
End Property ' SFDialogs.SF_DialogControl.Locked (get)

REM -----------------------------------------------------------------------------
Property Let Locked(Optional ByVal pvLocked As Variant)
''' Set the updatable property Locked
 _PropertySet("Locked", pvLocked)
End Property ' SFDialogs.SF_DialogControl.Locked (let)

REM -----------------------------------------------------------------------------
Property Get MultiSelect() As Variant
''' The MultiSelect property specifies whether a user can make multiple selections in a listbox
 MultiSelect = _PropertyGet("MultiSelect", False)
End Property ' SFDialogs.SF_DialogControl.MultiSelect (get)

REM -----------------------------------------------------------------------------
Property Let MultiSelect(Optional ByVal pvMultiSelect As Variant)
''' Set the updatable property MultiSelect
 _PropertySet("MultiSelect", pvMultiSelect)
End Property ' SFDialogs.SF_DialogControl.MultiSelect (let)

REM -----------------------------------------------------------------------------
Property Get Name() As String
''' Return the name of the actual control
 Name = _PropertyGet("Name")
End Property ' SFDialogs.SF_DialogControl.Name

REM -----------------------------------------------------------------------------
Property Get OnActionPerformed() As Variant
''' Get the script associated with the OnActionPerformed event
 OnActionPerformed = _PropertyGet("OnActionPerformed")
End Property ' SFDialogs.SF_DialogControl.OnActionPerformed (get)

REM -----------------------------------------------------------------------------
Property Let OnActionPerformed(Optional ByVal pvActionPerformed As Variant)
''' Set the updatable property OnActionPerformed
 _PropertySet("OnActionPerformed", pvActionPerformed)
End Property ' SFDialogs.SF_DialogControl.OnActionPerformed (let)

REM -----------------------------------------------------------------------------
Property Get OnAdjustmentValueChanged() As Variant
''' Get the script associated with the OnAdjustmentValueChanged event
 OnAdjustmentValueChanged = _PropertyGet("OnAdjustmentValueChanged")
End Property ' SFDialogs.SF_DialogControl.OnAdjustmentValueChanged (get)

REM -----------------------------------------------------------------------------
Property Let OnAdjustmentValueChanged(Optional ByVal pvAdjustmentValueChanged As Variant)
''' Set the updatable property OnAdjustmentValueChanged
 _PropertySet("OnAdjustmentValueChanged", pvAdjustmentValueChanged)
End Property ' SFDialogs.SF_DialogControl.OnAdjustmentValueChanged (let)

REM -----------------------------------------------------------------------------
Property Get OnFocusGained() As Variant
''' Get the script associated with the OnFocusGained event
 OnFocusGained = _PropertyGet("OnFocusGained")
End Property ' SFDialogs.SF_DialogControl.OnFocusGained (get)

REM -----------------------------------------------------------------------------
Property Let OnFocusGained(Optional ByVal pvOnFocusGained As Variant)
''' Set the updatable property OnFocusGained
 _PropertySet("OnFocusGained", pvOnFocusGained)
End Property ' SFDialogs.SF_DialogControl.OnFocusGained (let)

REM -----------------------------------------------------------------------------
Property Get OnFocusLost() As Variant
''' Get the script associated with the OnFocusLost event
 OnFocusLost = _PropertyGet("OnFocusLost")
End Property ' SFDialogs.SF_DialogControl.OnFocusLost (get)

REM -----------------------------------------------------------------------------
Property Let OnFocusLost(Optional ByVal pvOnFocusLost As Variant)
''' Set the updatable property OnFocusLost
 _PropertySet("OnFocusLost", pvOnFocusLost)
End Property ' SFDialogs.SF_DialogControl.OnFocusLost (let)

REM -----------------------------------------------------------------------------
Property Get OnItemStateChanged() As Variant
''' Get the script associated with the OnItemStateChanged event
 OnItemStateChanged = _PropertyGet("OnItemStateChanged")
End Property ' SFDialogs.SF_DialogControl.OnItemStateChanged (get)

REM -----------------------------------------------------------------------------
Property Let OnItemStateChanged(Optional ByVal pvItemStateChanged As Variant)
''' Set the updatable property OnItemStateChanged
 _PropertySet("OnItemStateChanged", pvItemStateChanged)
End Property ' SFDialogs.SF_DialogControl.OnItemStateChanged (let)

REM -----------------------------------------------------------------------------
Property Get OnKeyPressed() As Variant
''' Get the script associated with the OnKeyPressed event
 OnKeyPressed = _PropertyGet("OnKeyPressed")
End Property ' SFDialogs.SF_DialogControl.OnKeyPressed (get)

REM -----------------------------------------------------------------------------
Property Let OnKeyPressed(Optional ByVal pvOnKeyPressed As Variant)
''' Set the updatable property OnKeyPressed
 _PropertySet("OnKeyPressed", pvOnKeyPressed)
End Property ' SFDialogs.SF_DialogControl.OnKeyPressed (let)

REM -----------------------------------------------------------------------------
Property Get OnKeyReleased() As Variant
''' Get the script associated with the OnKeyReleased event
 OnKeyReleased = _PropertyGet("OnKeyReleased")
End Property ' SFDialogs.SF_DialogControl.OnKeyReleased (get)

REM -----------------------------------------------------------------------------
Property Let OnKeyReleased(Optional ByVal pvOnKeyReleased As Variant)
''' Set the updatable property OnKeyReleased
 _PropertySet("OnKeyReleased", pvOnKeyReleased)
End Property ' SFDialogs.SF_DialogControl.OnKeyReleased (let)

REM -----------------------------------------------------------------------------
Property Get OnMouseDragged() As Variant
''' Get the script associated with the OnMouseDragged event
 OnMouseDragged = _PropertyGet("OnMouseDragged")
End Property ' SFDialogs.SF_DialogControl.OnMouseDragged (get)

REM -----------------------------------------------------------------------------
Property Let OnMouseDragged(Optional ByVal pvOnMouseDragged As Variant)
''' Set the updatable property OnMouseDragged
 _PropertySet("OnMouseDragged", pvOnMouseDragged)
End Property ' SFDialogs.SF_DialogControl.OnMouseDragged (let)

REM -----------------------------------------------------------------------------
Property Get OnMouseEntered() As Variant
''' Get the script associated with the OnMouseEntered event
 OnMouseEntered = _PropertyGet("OnMouseEntered")
End Property ' SFDialogs.SF_DialogControl.OnMouseEntered (get)

REM -----------------------------------------------------------------------------
Property Let OnMouseEntered(Optional ByVal pvOnMouseEntered As Variant)
''' Set the updatable property OnMouseEntered
 _PropertySet("OnMouseEntered", pvOnMouseEntered)
End Property ' SFDialogs.SF_DialogControl.OnMouseEntered (let)

REM -----------------------------------------------------------------------------
Property Get OnMouseExited() As Variant
''' Get the script associated with the OnMouseExited event
 OnMouseExited = _PropertyGet("OnMouseExited")
End Property ' SFDialogs.SF_DialogControl.OnMouseExited (get)

REM -----------------------------------------------------------------------------
Property Let OnMouseExited(Optional ByVal pvOnMouseExited As Variant)
''' Set the updatable property OnMouseExited
 _PropertySet("OnMouseExited", pvOnMouseExited)
End Property ' SFDialogs.SF_DialogControl.OnMouseExited (let)

REM -----------------------------------------------------------------------------
Property Get OnMouseMoved() As Variant
''' Get the script associated with the OnMouseMoved event
 OnMouseMoved = _PropertyGet("OnMouseMoved")
End Property ' SFDialogs.SF_DialogControl.OnMouseMoved (get)

REM -----------------------------------------------------------------------------
Property Let OnMouseMoved(Optional ByVal pvOnMouseMoved As Variant)
''' Set the updatable property OnMouseMoved
 _PropertySet("OnMouseMoved", pvOnMouseMoved)
End Property ' SFDialogs.SF_DialogControl.OnMouseMoved (let)

REM -----------------------------------------------------------------------------
Property Get OnMousePressed() As Variant
''' Get the script associated with the OnMousePressed event
 OnMousePressed = _PropertyGet("OnMousePressed")
End Property ' SFDialogs.SF_DialogControl.OnMousePressed (get)

REM -----------------------------------------------------------------------------
Property Let OnMousePressed(Optional ByVal pvOnMousePressed As Variant)
''' Set the updatable property OnMousePressed
 _PropertySet("OnMousePressed", pvOnMousePressed)
End Property ' SFDialogs.SF_DialogControl.OnMousePressed (let)

REM -----------------------------------------------------------------------------
Property Get OnMouseReleased() As Variant
''' Get the script associated with the OnMouseReleased event
 OnMouseReleased = _PropertyGet("OnMouseReleased")
End Property ' SFDialogs.SF_DialogControl.OnMouseReleased (get)

REM -----------------------------------------------------------------------------
Property Let OnMouseReleased(Optional ByVal pvOnMouseReleased As Variant)
''' Set the updatable property OnMouseReleased
 _PropertySet("OnMouseReleased", pvOnMouseReleased)
End Property ' SFDialogs.SF_DialogControl.OnMouseReleased (let)

REM -----------------------------------------------------------------------------
Property Get OnNodeExpanded() As Variant
''' Get the script associated with the OnNodeExpanded event
 OnNodeExpanded = _PropertyGet("OnNodeExpanded")
End Property ' SFDialogs.SF_DialogControl.OnNodeExpanded (get)

REM -----------------------------------------------------------------------------
Property Let OnNodeExpanded(Optional ByVal pvOnNodeExpanded As Variant)
''' Set the updatable property OnNodeExpanded
 _PropertySet("OnNodeExpanded", pvOnNodeExpanded)
End Property ' SFDialogs.SF_DialogControl.OnNodeExpanded (let)

REM -----------------------------------------------------------------------------
Property Get OnNodeSelected() As Variant
''' Get the script associated with the OnNodeSelected event
 OnNodeSelected = _PropertyGet("OnNodeSelected")
End Property ' SFDialogs.SF_DialogControl.OnNodeSelected (get)

REM -----------------------------------------------------------------------------
Property Let OnNodeSelected(Optional ByVal pvOnNodeSelected As Variant)
''' Set the updatable property OnNodeSelected
 _PropertySet("OnNodeSelected", pvOnNodeSelected)
End Property ' SFDialogs.SF_DialogControl.OnNodeSelected (let)

REM -----------------------------------------------------------------------------
Property Get OnTabSelected() As Variant
''' Get the script associated with the OnTabSelected event
 OnTabSelected = _PropertyGet("OnTabSelected")
End Property ' SFDialogs.SF_DialogControl.OnTabSelected (get)

REM -----------------------------------------------------------------------------
Property Let OnTabSelected(Optional ByVal pvTextChanged As Variant)
''' Set the updatable property OnTabSelected
 _PropertySet("OnTabSelected", pvTextChanged)
End Property ' SFDialogs.SF_DialogControl.OnTabSelected (let)

REM -----------------------------------------------------------------------------
Property Get OnTextChanged() As Variant
''' Get the script associated with the OnTextChanged event
 OnTextChanged = _PropertyGet("OnTextChanged")
End Property ' SFDialogs.SF_DialogControl.OnTextChanged (get)

REM -----------------------------------------------------------------------------
Property Let OnTextChanged(Optional ByVal pvTextChanged As Variant)
''' Set the updatable property OnTextChanged
 _PropertySet("OnTextChanged", pvTextChanged)
End Property ' SFDialogs.SF_DialogControl.OnTextChanged (let)

REM -----------------------------------------------------------------------------
Property Get Page() As Variant
''' A dialog may have several pages that can be traversed by the user step by step. The Page property of the Dialog object defines which page of the dialog is active.
''' The Page property of a control defines the page of the dialog on which the control is visible.
''' For example, if a control has a page value of 1, it is only visible on page 1 of the dialog.
''' If the page value of the dialog is increased from 1 to 2, then all controls with a page value of 1 disappear and all controls with a page value of 2 become visible.
 Page = _PropertyGet("Page")
End Property ' SFDialogs.SF_DialogControl.Page (get)

REM -----------------------------------------------------------------------------
Property Let Page(Optional ByVal pvPage As Variant)
''' Set the updatable property Page
 _PropertySet("Page", pvPage)
End Property ' SFDialogs.SF_DialogControl.Page (let)

REM -----------------------------------------------------------------------------
Property Get Parent() As Object
''' Return the Parent dialog object of the actual control
 Parent = _PropertyGet("Parent", Nothing)
End Property ' SFDialogs.SF_DialogControl.Parent

REM -----------------------------------------------------------------------------
Property Get Picture() As Variant
''' The Picture property specifies a bitmap or other type of graphic to be displayed on the specified control
 Picture = _PropertyGet("Picture", "")
End Property ' SFDialogs.SF_DialogControl.Picture (get)

REM -----------------------------------------------------------------------------
Property Let Picture(Optional ByVal pvPicture As Variant)
''' Set the updatable property Picture
 _PropertySet("Picture", pvPicture)
End Property ' SFDialogs.SF_DialogControl.Picture (let)

REM -----------------------------------------------------------------------------
Property Get RootNode() As Variant
''' The RootNode property returns the last root node of a tree control
 RootNode = _PropertyGet("RootNode", "")
End Property ' SFDialogs.SF_DialogControl.RootNode (get)

REM -----------------------------------------------------------------------------
Property Get RowSource() As Variant
''' The RowSource property specifies the data contained in a combobox or a listbox
''' as a zero-based array of string values
 RowSource = _PropertyGet("RowSource", "")
End Property ' SFDialogs.SF_DialogControl.RowSource (get)

REM -----------------------------------------------------------------------------
Property Let RowSource(Optional ByVal pvRowSource As Variant)
''' Set the updatable property RowSource
 _PropertySet("RowSource", pvRowSource)
End Property ' SFDialogs.SF_DialogControl.RowSource (let)

REM -----------------------------------------------------------------------------
Property Get TabIndex() As Variant
''' The TabIndex property specifies a control's place in the tab order in the dialog
''' Zero or negative means no tab set in the control
 TabIndex = _PropertyGet("TabIndex", -1)
End Property ' SFDialogs.SF_DialogControl.TabIndex (get)

REM -----------------------------------------------------------------------------
Property Let TabIndex(Optional ByVal pvTabIndex As Variant)
''' Set the updatable property TabIndex
 _PropertySet("TabIndex", pvTabIndex)
End Property ' SFDialogs.SF_DialogControl.TabIndex (let)

REM -----------------------------------------------------------------------------
Property Get Text() As Variant
''' The Text property specifies the actual content of the control like it is displayed on the screen
 Text = _PropertyGet("Text", "")
End Property ' SFDialogs.SF_DialogControl.Text (get)

REM -----------------------------------------------------------------------------
Property Get TipText() As Variant
''' The TipText property specifies the text that appears in a screentip when you hold the mouse pointer over a control
 TipText = _PropertyGet("TipText", "")
End Property ' SFDialogs.SF_DialogControl.TipText (get)

REM -----------------------------------------------------------------------------
Property Let TipText(Optional ByVal pvTipText As Variant)
''' Set the updatable property TipText
 _PropertySet("TipText", pvTipText)
End Property ' SFDialogs.SF_DialogControl.TipText (let)

REM -----------------------------------------------------------------------------
Property Get TripleState() As Variant
''' The TripleState property specifies how a check box will display Null values
''' When True, the control will cycle through states for Yes, No, and Null values. The control appears dimmed (grayed) when its Value property is set to Null.
''' When False, the control will cycle through states for Yes and No values. Null values display as if they were No values.
 TripleState = _PropertyGet("TripleState", False)
End Property ' SFDialogs.SF_DialogControl.TripleState (get)

REM -----------------------------------------------------------------------------
Property Let TripleState(Optional ByVal pvTripleState As Variant)
''' Set the updatable property TripleState
 _PropertySet("TripleState", pvTripleState)
End Property ' SFDialogs.SF_DialogControl.TripleState (let)

REM -----------------------------------------------------------------------------
Property Get URL() As Variant
''' The URL property refers to the URL to open when the control is clicked
 URL = _PropertyGet("URL", "")
End Property ' SFDialogs.SF_DialogControl.URL (get)

REM -----------------------------------------------------------------------------
Property Let URL(Optional ByVal pvURL As Variant)
''' Set the updatable property URL
 _PropertySet("URL", pvURL)
End Property ' SFDialogs.SF_DialogControl.URL (let)

REM -----------------------------------------------------------------------------
Property Get Value() As Variant
''' The Value property specifies the data contained in the control
 Value = _PropertyGet("Value", Empty)
End Property ' SFDialogs.SF_DialogControl.Value (get)

REM -----------------------------------------------------------------------------
Property Let Value(Optional ByVal pvValue As Variant)
''' Set the updatable property Value
 _PropertySet("Value", pvValue)
End Property ' SFDialogs.SF_DialogControl.Value (let)

REM -----------------------------------------------------------------------------
Property Get Visible() As Variant
''' The Visible property specifies if the control is accessible with the cursor.
 Visible = _PropertyGet("Visible", True)
End Property ' SFDialogs.SF_DialogControl.Visible (get)

REM -----------------------------------------------------------------------------
Property Let Visible(Optional ByVal pvVisible As Variant)
''' Set the updatable property Visible
 _PropertySet("Visible", pvVisible)
End Property ' SFDialogs.SF_DialogControl.Visible (let)

REM -----------------------------------------------------------------------------
Property Get Width() As Variant
''' The Width property refers to the Width of the control
 Width = _PropertyGet("Width")
End Property ' SFDialogs.SF_DialogControl.Width (get)

REM -----------------------------------------------------------------------------
Property Let Width(Optional ByVal pvWidth As Variant)
''' Set the updatable property Width
 _PropertySet("Width", pvWidth)
End Property ' SFDialogs.SF_DialogControl.Width (let)

REM -----------------------------------------------------------------------------
Property Get X() As Variant
''' The X property refers to the X coordinate of the top-left corner of the control
 X = _PropertyGet("X")
End Property ' SFDialogs.SF_DialogControl.X (get)

REM -----------------------------------------------------------------------------
Property Let X(Optional ByVal pvX As Variant)
''' Set the updatable property X
 _PropertySet("X", pvX)
End Property ' SFDialogs.SF_DialogControl.X (let)

REM -----------------------------------------------------------------------------
Property Get Y() As Variant
''' The Y property refers to the Y coordinate of the top-left corner of the control
 Y = _PropertyGet("Y")
End Property ' SFDialogs.SF_DialogControl.Y (get)

REM -----------------------------------------------------------------------------
Property Let Y(Optional ByVal pvY As Variant)
''' Set the updatable property Y
 _PropertySet("Y", pvY)
End Property ' SFDialogs.SF_DialogControl.Y (let)

REM -----------------------------------------------------------------------------
Property Get XControlModel() As Object
''' The XControlModel property returns the model UNO object of the control
 XControlModel = _PropertyGet("XControlModel", Nothing)
End Property ' SFDialogs.SF_DialogControl.XControlModel (get)

REM -----------------------------------------------------------------------------
Property Get XControlView() As Object
''' The XControlView property returns the view UNO object of the control
 XControlView = _PropertyGet("XControlView", Nothing)
End Property ' SFDialogs.SF_DialogControl.XControlView (get)

REM -----------------------------------------------------------------------------
Property Get XGridColumnModel() As Object
''' The XGridColumnModel property returns the mutable data model UNO object of the tree control
 XGridColumnModel = _PropertyGet("XGridColumnModel", Nothing)
End Property ' SFDialogs.SF_DialogControl.XGridColumnModel (get)

REM -----------------------------------------------------------------------------
Property Get XGridDataModel() As Object
''' The XGridDataModel property returns the mutable data model UNO object of the tree control
 XGridDataModel = _PropertyGet("XGridDataModel", Nothing)
End Property ' SFDialogs.SF_DialogControl.XGridDataModel (get)

REM -----------------------------------------------------------------------------
Property Get XTreeDataModel() As Object
''' The XTreeDataModel property returns the mutable data model UNO object of the tree control
 XTreeDataModel = _PropertyGet("XTreeDataModel", Nothing)
End Property ' SFDialogs.SF_DialogControl.XTreeDataModel (get)

REM ===================================================================== METHODS

REM -----------------------------------------------------------------------------
Public Function AddSubNode(Optional ByRef ParentNode As Variant _
        , Optional ByVal DisplayValue As Variant _
        , Optional ByRef DataValue As Variant _
        ) As Variant
''' Return a new node of the tree control subordinate to a parent node
''' Args:
'''  ParentNode: A node UNO object, of type com.sun.star.awt.tree.XMutableTreeNode
'''  DisplayValue: the text appearing in the control box
'''  DataValue: any value associated with the new node. Default = Empty
''' Returns:
'''  The new node UNO object: com.sun.star.awt.tree.XMutableTreeNode
''' Examples:
'''  Dim myTree As Object, myNode As Object, theRoot As Object
'''   Set myTree = myDialog.Controls("myTreeControl")
'''   Set theRoot = myTree.CreateRoot("Tree top")
'''   Set myNode = myTree.AddSubNode(theRoot, "A branch ...")

Dim oNode As Object    ' Return value
Const cstThisSub = "SFDialogs.DialogControl.AddSubNode"
Const cstSubArgs = "ParentNode, DisplayValue, [DataValue=Empty]"

 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
 Set oNode = Nothing

Check:
 If IsMissing(DataValue) Then DataValue = Empty
 If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
  If _ControlType <> CTLTREECONTROL Then GoTo CatchType
  If Not ScriptForge.SF_Utils._Validate(ParentNode, "ParentNode", V_OBJECT) Then GoTo Catch
  If ScriptForge.SF_Session.UnoObjectType(ParentNode) <> "toolkit.MutableTreeNode" Then GoTo Catch
  If Not ScriptForge.SF_Utils._Validate(DisplayValue, "DisplayValue", V_STRING) Then GoTo Catch
 End If

Try:
 With _TreeDataModel
  Set oNode = .createNode(DisplayValue, True)
  oNode.DataValue = DataValue
  ParentNode.appendChild(oNode)
 End With

Finally:
 Set AddSubNode = oNode
 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
 Exit Function
Catch:
 GoTo Finally
CatchType:
 ScriptForge.SF_Exception.RaiseFatal(CONTROLTYPEERROR, _Name, _DialogName, _ControlType, "AddSubNode")
 GoTo Finally
End Function ' SFDialogs.SF_DialogControl.AddSubNode

REM -----------------------------------------------------------------------------
Public Function AddSubTree(Optional ByRef ParentNode As Variant _
        , Optional ByRef FlatTree As Variant _
        , Optional ByVal WithDataValue As Variant _
        ) As Boolean
''' Return True when a subtree, subordinate to a parent node, could be inserted successfully in a tree control
''' If the parent node had already child nodes before calling this method, the child nodes are erased
''' Args:
'''  ParentNode: A node UNO object,  of type com.sun.star.awt.tree.XMutableTreeNode
'''  FlatTree: a 2D array sorted on the columns containing the DisplayValues
'''    Flat tree  >>>>  Resulting subtree
'''    A1 B1 C1     |__ A1  
'''    A1 B1 C2      |__ B1 
'''    A1 B2 C3       |__ C1
'''    A2 B3 C4       |__ C2
'''    A2 B3 C5      |__ B2 
'''    A3 B4 C6       |__ C3
'''           |__ A2  
'''            |__ B3 
'''             |__ C4
'''             |__ C5
'''           |__ A3  
'''            |__ B4 
'''             |__ C6
'''   Typically, such an array can be issued by the GetRows method applied on the SFDatabases.Database service
'''   when an array item containing the text to be displayed is = "" or is empty/null,
'''    no new subnode is created and the remainder of the row is skipped
'''   When AddSubTree() is called from a Python script, FlatTree may be an array of arrays
'''  WithDataValue:
'''   When False (default), every column of FlatTree contains the text to be displayed in the tree control
'''   When True, the texts to be displayed (DisplayValue) are in columns 0, 2, 4, ...
'''    while the DataValues are in columns 1, 3, 5, ...
''' Returns:
'''  True when successful
''' Examples:
'''  Dim myTree As Object, theRoot As Object, oDb As Object, vData As Variant
'''   Set myTree = myDialog.Controls("myTreeControl")
'''   Set theRoot = myTree.CreateRoot("By product category")
'''   Set oDb = CreateScriptService("SFDatabases.Database", "/home/.../mydatabase.odb")
'''   vData = oDb.GetRows("SELECT [Category].[Name], [Category].[ID], [Product].[Name], [Product].[ID] " _
'''    & "FROM [Category], [Product] WHERE [Product].[CategoryID] = [Category].[ID] " _
'''    & "ORDER BY [Category].[Name], [Product].[Name]")
'''   myTree.AddSubTree(theRoot, vData, WithDataValue := True)

Dim bSubTree As Boolean    ' Return value
Dim oNode As Object     ' com.sun.star.awt.tree.XMutableTreeNode
Dim oNewNode As Object    ' com.sun.star.awt.tree.XMutableTreeNode
Dim lChildCount As Long    ' Number of children nodes of a parent node
Dim iStep As Integer    ' 1 when WithDataValue = False, 2 otherwise
Dim iDims As Integer    ' Number of dimensions of FlatTree
Dim lMin1 As Long     ' Lower bound (rows)
Dim lMin2 As Long     ' Lower bounds (cols)
Dim lMax1 As Long     ' Upper bound (rows)
Dim lMax2 As Long     ' Upper bounds (cols)
Dim vFlatItem As Variant   ' A single FlatTree item: FlatTree(i, j)
Dim vFlatItem2 As Variant   ' A single FlatTree item
Dim bChange As Boolean    ' When True, the item in FlatTree is different from the item above
Dim sValue As String    ' Alias for display values
Dim i As Long, j As Long
Const cstThisSub = "SFDialogs.DialogControl.AddSubTree"
Const cstSubArgs = "ParentNode, FlatTree, [WithDataValue=False]"

 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
 bSubTree = False

Check:
 If IsMissing(WithDataValue) Or IsEmpty(WithDataValue) Then WithDataValue = False
 If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
  If _ControlType <> CTLTREECONTROL Then GoTo CatchType
  If Not ScriptForge.SF_Utils._Validate(ParentNode, "ParentNode", V_OBJECT) Then GoTo Catch
  If ScriptForge.SF_Session.UnoObjectType(ParentNode) <> "toolkit.MutableTreeNode" Then GoTo Catch
  If Not ScriptForge.SF_Utils._ValidateArray(FlatTree, "FlatTree") Then GoTo Catch ' Dimensions checked below
  If Not ScriptForge.SF_Utils._Validate(WithDataValue, "WithDataValue", V_BOOLEAN) Then GoTo Catch
 End If

Try:
 With _TreeDataModel
  ' Clean subtree
  lChildCount = ParentNode.getChildCount()
  For i = 1 To lChildCount
   ParentNode.removeChildByIndex(0)  ' This cleans all subtrees too
  Next i

  ' Determine bounds
  iDims = ScriptForge.SF_Array.CountDims(FlatTree)
  Select Case iDims
   Case -1, 0  : GoTo Catch
   Case 1     ' Called probably from Python
    lMin1 = LBound(FlatTree, 1)   : lMax1 = UBound(FlatTree, 1)
    If Not IsArray(FlatTree(0)) Then GoTo Catch
    If UBound(FlatTree(0)) < LBound(FlatTree(0)) Then GoTo Catch ' No columns
    lMin2 = LBound(FlatTree(0))   : lMax2 = UBound(FlatTree(0))
   Case 2
    lMin1 = LBound(FlatTree, 1)   : lMax1 = UBound(FlatTree, 1)
    lMin2 = LBound(FlatTree, 2)   : lMax2 = UBound(FlatTree, 2)
   Case Else  : GoTo Catch
  End Select

  ' Build a new subtree
  iStep = Iif(WithDataValue, 2, 1)
  For i = lMin1 To lMax1
   bChange = ( i = 0 )
   ' Restart from the parent node at each i-iteration
   Set oNode = ParentNode
   For j = lMin2 To lMax2 Step iStep ' Array columns
    If iDims = 1 Then vFlatItem = FlatTree(i)(j) Else vFlatItem = FlatTree(i, j)
    If vFlatItem = "" Or IsNull(vFlatItem) Or IsEmpty(vFlatItem) Then
     Set oNode = Nothing
     Exit For  ' Exit j-loop
    End If
    If Not bChange Then
     If iDims = 1 Then vFlatItem2 = FlatTree(i - 1)(j) Else vFlatItem2 = FlatTree(i - 1, j)
     bChange = ( vFlatItem <> vFlatItem2 )
    End If
    If bChange Then  ' Create new subnode at tree depth = j
     If VarType(vFlatItem) = V_STRING Then sValue = vFlatItem Else sValue = ScriptForge.SF_String.Represent(vFlatItem)
     Set oNewNode = .createNode(sValue, True)
     If WithDataValue Then
      If iDims = 1 Then vFlatItem2 = FlatTree(i)(j + 1) Else vFlatItem2 = FlatTree(i, j + 1)
      oNewNode.DataValue = vFlatItem2
     End If
     oNode.appendChild(oNewNode)
     Set oNode = oNewNode
    Else
     ' Position next current node on last child of actual current node
     lChildCount = oNode.getChildCount()
     If lChildCount > 0 Then Set oNode = oNode.getChildAt(lChildCount - 1) Else Set oNode = Nothing
    End If
   Next j
  Next i
  bSubTree = True
 End With

Finally:
 AddSubTree = bSubTree
 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
 Exit Function
Catch:
 GoTo Finally
CatchType:
 ScriptForge.SF_Exception.RaiseFatal(CONTROLTYPEERROR, _Name, _DialogName, _ControlType, "AddSubTree")
 GoTo Finally
End Function ' SFDialogs.SF_DialogControl.AddSubTree

REM -----------------------------------------------------------------------------
Public Function CreateRoot(Optional ByVal DisplayValue As Variant _
        , Optional ByRef DataValue As Variant _
        ) As Variant
''' Return a new root node of the tree control. The new tree root is inserted below pre-existing root nodes
''' Args:
'''  DisplayValue: the text appearing in the control box
'''  DataValue: any value associated with the root node. Default = Empty
''' Returns:
'''  The new root node as a UNO object of type com.sun.star.awt.tree.XMutableTreeNode
''' Examples:
'''  Dim myTree As Object, myNode As Object
'''   Set myTree = myDialog.Controls("myTreeControl")
'''   Set myNode = myTree.CreateRoot("Tree starts here ...")

Dim oRoot As Object    ' Return value
Const cstThisSub = "SFDialogs.DialogControl.CreateRoot"
Const cstSubArgs = "DisplayValue, [DataValue=Empty]"

 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
 Set oRoot = Nothing

Check:
 If IsMissing(DataValue) Then DataValue = Empty
 If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
  If _ControlType <> CTLTREECONTROL Then GoTo CatchType
  If Not ScriptForge.SF_Utils._Validate(DisplayValue, "DisplayValue", V_STRING) Then GoTo Catch
 End If

Try:
 With _TreeDataModel
  Set oRoot = .createNode(DisplayValue, True)
  oRoot.DataValue = DataValue
  .setRoot(oRoot)
  ' To be visible, a root must have contained at least 1 child. Create a fictive one and erase it.
  ' This behaviour does not seem related to the RootDisplayed property ??
  oRoot.appendChild(.createNode("Something", False))
  oRoot.removeChildByIndex(0)
 End With

Finally:
 Set CreateRoot = oRoot
 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
 Exit Function
Catch:
 GoTo Finally
CatchType:
 ScriptForge.SF_Exception.RaiseFatal(CONTROLTYPEERROR, _Name, _DialogName, _ControlType, "CreateRoot")
 GoTo Finally
End Function ' SFDialogs.SF_DialogControl.CreateRoot

REM -----------------------------------------------------------------------------
Public Function FindNode(Optional ByVal DisplayValue As String _
       , Optional ByRef DataValue As Variant _
       , Optional ByVal CaseSensitive As Boolean _
       ) As Object
''' Traverses the tree and find recursively, starting from the root, a node meeting some criteria
''' Either (1 match is enough):
'''  having its DisplayValue like DisplayValue
'''  having its DataValue = DataValue
''' Comparisons may be or not case-sensitive
''' The first matching occurrence is returned
''' Args:
'''  DisplayValue: the pattern to be matched
'''  DataValue: a string, a numeric value or a date or Empty (if not applicable)
'''  CaseSensitive: applicable on both criteria. Default = False
''' Returns:
'''  The found node of type com.sun.star.awt.tree.XMutableTreeNode or Nothing if not found
''' Examples:
'''  Dim myTree As Object, myNode As Object
'''   Set myTree = myDialog.Controls("myTreeControl")
'''   Set myNode = myTree.FindNode("*Sophie*", CaseSensitive := True)


Dim oNode As Object    ' Return value
Const cstThisSub = "SFDialogs.DialogControl.FindNode"
Const cstSubArgs = "[DisplayValue=""""], [DataValue=Empty], [CaseSensitive=False]"

 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
 Set oNode = Nothing

Check:
 If IsMissing(DisplayValue) Or IsEmpty(DisplayValue) Then DisplayValue = ""
 If IsMissing(DataValue) Then DataValue = Empty
 If IsMissing(CaseSensitive) Or IsEmpty(CaseSensitive) Then CaseSensitive = False
 If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
  If _ControlType <> CTLTREECONTROL Then GoTo CatchType
  If Not ScriptForge.SF_Utils._Validate(DisplayValue, "DisplayValue", V_STRING) Then GoTo Catch
  If Not ScriptForge.SF_Utils._Validate(CaseSensitive, "CaseSensitive", ScriptForge.V_BOOLEAN) Then GoTo Catch
 End If

Try:
 Set oNode = _FindNode(_TreeDataModel.getRoot(), DisplayValue, DataValue, CaseSensitive)

Finally:
 Set FindNode = oNode
 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
 Exit Function
Catch:
 GoTo Finally
CatchType:
 ScriptForge.SF_Exception.RaiseFatal(CONTROLTYPEERROR, _Name, _DialogName, _ControlType, "FindNode")
 GoTo Finally
End Function ' SFDialogs.SF_DialogControl.FindNode

REM -----------------------------------------------------------------------------
Public Function GetProperty(Optional ByVal PropertyName As Variant) As Variant
''' Return the actual value of the given property
''' Args:
'''  PropertyName: the name of the property as a string
''' Returns:
'''  The actual value of the property
'''  If the property does not exist, returns Null
''' Exceptions:
'''  see the exceptions of the individual properties
''' Examples:
'''  myModel.GetProperty("MyProperty")

Const cstThisSub = "SFDialogs.DialogControl.GetProperty"
Const cstSubArgs = ""

 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
 GetProperty = Null

Check:
 If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
  If Not ScriptForge.SF_Utils._Validate(PropertyName, "PropertyName", V_STRING, Properties()) Then GoTo Catch
 End If

Try:
 GetProperty = _PropertyGet(PropertyName)

Finally:
 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
 Exit Function
Catch:
 GoTo Finally
End Function ' SFDialogs.SF_DialogControl.GetProperty

REM -----------------------------------------------------------------------------
Public Function Methods() As Variant
''' Return the list of public methods of the Model service as an array

 Methods = Array( _
     "AddSubNode" _
     , "AddSubTree" _
     , "CreateRoot" _
     , "FindNode" _
     , "SetFocus" _
     , "WriteLine" _
     )

End Function ' SFDialogs.SF_DialogControl.Methods

REM -----------------------------------------------------------------------------
Public Function Properties() As Variant
''' Return the list or properties of the Timer class as an array

 Properties = Array( _
     "Border" _
     , "Cancel" _
     , "Caption" _
     , "ControlType" _
     , "CurrentNode" _
     , "Default" _
     , "Enabled" _
     , "Format" _
     , "Height" _
     , "ListCount" _
     , "ListIndex" _
     , "Locked" _
     , "MultiSelect" _
     , "Name" _
     , "OnActionPerformed" _
     , "OnAdjustmentValueChanged" _
     , "OnFocusGained" _
     , "OnFocusLost" _
     , "OnItemStateChanged" _
     , "OnKeyPressed" _
     , "OnKeyReleased" _
     , "OnMouseDragged" _
     , "OnMouseEntered" _
     , "OnMouseExited" _
     , "OnMouseMoved" _
     , "OnMousePressed" _
     , "OnMouseReleased" _
     , "OnNodeExpanded" _
     , "OnNodeSelected" _
     , "OnTabSelected" _
     , "OnTextChanged" _
     , "Page" _
     , "Parent" _
     , "Picture" _
     , "RootNode" _
     , "RowSource" _
     , "TabIndex" _
     , "Text" _
     , "TipText" _
     , "TripleState" _
     , "URL" _
     , "Value" _
     , "Visible" _
     , "Width" _
     , "X" _
     , "XControlModel" _
     , "XControlView" _
     , "XGridColumnModel" _
     , "XGridDataModel" _
     , "XTreeDataModel" _
     , "Y" _
     )

End Function ' SFDialogs.SF_DialogControl.Properties

REM -----------------------------------------------------------------------------
Public Function Resize(Optional ByVal Left As Variant _
        , Optional ByVal Top As Variant _
        , Optional ByVal Width As Variant _
        , Optional ByVal Height As Variant _
        ) As Boolean
''' Move the top-left corner of the control to new coordinates and/or modify its dimensions
''' Without arguments, the method resets the initial dimensions and position
''' Attributes denoting the position and size of a control are expressed in "Map AppFont" units.
''' Map AppFont units are device and resolution independent.
''' One Map AppFont unit is equal to one eighth of the average character (Systemfont) height and one quarter of the average character width.
''' The dialog editor (= the Basic IDE) also uses Map AppFont units.
''' Args:
'''  Left : the horizontal distance from the top-left corner. It may be negative.
'''  Top : the vertical distance from the top-left corner. It may be negative.
'''  Width : the horizontal width of the rectangle containing the Dialog. It must be positive.
'''  Height : the vertical height of the rectangle containing the Dialog. It must be positive.
'''  Missing arguments are left unchanged.
''' Returns:
'''  True when successful
''' Examples:
'''  myControl.Resize(100, 200, Height := 600) ' Width is not changed

Try:
 Resize = SF_DialogUtils._Resize([Me], Left, Top, Width, Height)

End Function ' SFDialogss.SF_Dialog.Resize

REM -----------------------------------------------------------------------------
Public Function SetFocus() As Boolean
''' Set the focus on the current Control instance
''' Probably called from after an event occurrence
''' Args:
''' Returns:
'''  True if focusing is successful
''' Example:
'''  Dim oDlg As Object, oControl As Object
'''   Set oDlg = CreateScriptService(,, "myControl") ' Control stored in current document's standard library
'''   Set oControl = oDlg.Controls("thisControl")
'''   oControl.SetFocus()

Dim bSetFocus As Boolean  ' Return value
Const cstThisSub = "SFDialogs.DialogControl.SetFocus"
Const cstSubArgs = ""

 If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
 bSetFocus = False

Check:
 If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
  If Not [_Parent]._IsStillAlive() Then GoTo Finally
 End If

Try:
 If Not IsNull(_ControlView) Then
  _ControlView.setFocus()
  bSetFocus = True
 End If

Finally:
 SetFocus = bSetFocus
 ScriptForge.SF_Utils._ExitFunction(cstThisSub)
 Exit Function
Catch:
 GoTo Finally
End Function ' SFControls.SF_DialogControl.SetFocus

REM -----------------------------------------------------------------------------
Public Function SetProperty(Optional ByVal PropertyName As Variant _
        , Optional ByRef Value As Variant _
        ) As Boolean
''' Set a new value to the given property
''' Args:
'''  PropertyName: the name of the property as a string
'''  Value: its new value
''' Exceptions
--> --------------------

--> maximum size reached

--> --------------------