path: root/wizards/source/sfdocuments/SF_Form.xba

<?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_Form" script:language="StarBasic" script:moduleType="normal">REM =======================================================================================================================
REM ===			The ScriptForge library and its associated libraries are part of the LibreOffice project.				===
REM	===						The SFDocuments library is one of the associated libraries.									===
REM ===					Full documentation is available on https://help.libreoffice.org/								===
REM =======================================================================================================================

Option Compatible
Option ClassModule

Option Explicit

&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;
&apos;&apos;&apos;	SF_Form
&apos;&apos;&apos;	=======
&apos;&apos;&apos;		Management of forms defined in LibreOffice documents. Supported types are Base, Calc and Writer documents.
&apos;&apos;&apos;		For Base documents, it includes the management of subforms
&apos;&apos;&apos;		Each instance of the current class represents a single form or a single subform
&apos;&apos;&apos;
&apos;&apos;&apos;		A form may optionally be (understand &quot;is often&quot;) linked to a data source manageable with the SFDatabases.Database service
&apos;&apos;&apos;		The current service offers a rapid access to that service
&apos;&apos;&apos;		
&apos;&apos;&apos;		Definitions:
&apos;&apos;&apos;
&apos;&apos;&apos;			FormDocument:
&apos;&apos;&apos;				For usual documents, there is only 1 form document. It is in fact the document itself.
&apos;&apos;&apos;				A Base document may contain an unlimited number of form documents.
&apos;&apos;&apos;					In the Base terminology they are called &quot;forms&quot;. This could create some confusion.
&apos;&apos;&apos;					They can be organized in folders. Their name is then always the full path of folders + form
&apos;&apos;&apos;					with the slash (&quot;/&quot;) as path separator
&apos;&apos;&apos;				A FormDocument is a set of Forms. Form names are visible in the user interface thanks to the form navigator
&apos;&apos;&apos;					Often there is only 1 Form present in a FormDocument. Having more, however, might improve
&apos;&apos;&apos;					the user experience significantly
&apos;&apos;&apos;
&apos;&apos;&apos;			Form: WHERE IT IS ABOUT IN THE CURRENT &quot;Form&quot; SERVICE
&apos;&apos;&apos;				Is an abstract set of Controls in an OPEN FormDocument
&apos;&apos;&apos;				Each form is usually linked to one single dataset (table, query or Select statement),
&apos;&apos;&apos;				located in any database (provided the user may access it)
&apos;&apos;&apos;					A usual document may contain several forms. Each of which may have its own data source (database + dataset)
&apos;&apos;&apos;					A Base form document may contain several forms. Each of which may address its own dataset. The database however is unique
&apos;&apos;&apos;				A form is defined by its owning FormDocument and its FormName or FormIndex
&apos;&apos;&apos;
&apos;&apos;&apos;		Service invocations:
&apos;&apos;&apos;
&apos;&apos;&apos;			REM the form is stored in a not-Base document (Calc, Writer)	
&apos;&apos;&apos;			Dim oDoc As Object, myForm As Object
&apos;&apos;&apos;				Set oDoc = CreateScriptService(&quot;SFDocuments.Document&quot;, ThisComponent)
&apos;&apos;&apos;				Set myForm = oDoc.Forms(&quot;Form1&quot;)
&apos;&apos;&apos;				&apos;	or, alternatively, when there is only 1 form
&apos;&apos;&apos;				Set myForm = oDoc.Forms(0)	
&apos;&apos;&apos;
&apos;&apos;&apos;			REM the form is stored in one of the FormDocuments of a Base document
&apos;&apos;&apos;			Dim oDoc As Object, myForm As Object, mySubForm As Object
&apos;&apos;&apos;				Set oDoc = CreateScriptService(&quot;SFDocuments.Document&quot;, ThisDatabaseDocument)
&apos;&apos;&apos;				oDoc.OpenFormDocument(&quot;thisFormDocument&quot;)
&apos;&apos;&apos;				Set myForm = oDoc.Forms(&quot;thisFormDocument&quot;, &quot;MainForm&quot;)
&apos;&apos;&apos;				&apos;	or, alternatively, when there is only 1 form
&apos;&apos;&apos;				Set myForm = oDoc.Forms(&quot;thisFormDocument&quot;, 0)
&apos;&apos;&apos;				&apos;	To access a subform: myForm and mySubForm become distinct instances of the current class
&apos;&apos;&apos;				Set mySubForm = myForm.SubForms(&quot;mySubForm&quot;)
&apos;&apos;&apos;
&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;&apos;

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

Private Const FORMDEADERROR		=	&quot;FORMDEADERROR&quot;

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

Private [Me]				As Object
Private [_Parent]			As Object
Private ObjectType			As String		&apos; Must be Form
Private ServiceName			As String

&apos;	Form location
Private _Name				As String		&apos; Internal name of the form
Private _FormType			As Integer		&apos; One of the ISxxxFORM constants
Private _SheetName			As String		&apos; Name as the sheet containing the form (Calc only)
Private _FormDocumentName	As String		&apos; The hierarchical name of the containing form document (Base only)
Private _FormDocument		As Object		&apos; com.sun.star.comp.sdb.Content - the containing form document
	&apos;	The form topmost container
Private _Component			As Object		&apos; com.sun.star.lang.XComponent or com.sun.star.comp.dba.ODatabaseDocument

&apos;	EVents management
Private _CacheIndex			As Long			&apos; Index in central cache storage
Private _IssuedFromEvent	As Boolean		&apos; When True instance is always presumed alive

&apos;	Form UNO references
&apos;		The entry to the interactions with the form. Validity checked by the _IsStillAlive() method
&apos;		Each method or property requiring that the form is opened should first invoke that method
Private _Form				As Object		&apos; com.sun.star.form.XForm or com.sun.star.comp.forms.ODatabaseForm
Private _Database			As Object		&apos; Database class instance

&apos;	Form attributes

&apos;	Persistent storage for controls
Private _ControlCache		As Variant		&apos; Array of control objects sorted like ElementNames of XForm

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

Const ISDOCFORM				=	1			&apos; Form is stored in a Writer document
Const ISCALCFORM			=	2			&apos; Form is stored in a Calc document
Const ISBASEFORM			=	3			&apos; Form is stored in a Base document
Const ISSUBFORM				=	4			&apos; Form is a subform of a form or of another subform
Const ISUNDEFINED			=	-1			&apos; Undefined form type

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

REM -----------------------------------------------------------------------------
Private Sub Class_Initialize()
	Set [Me] = Nothing
	Set [_Parent] = Nothing
	ObjectType = &quot;Form&quot;
	ServiceName = &quot;SFDocuments.Form&quot;
	_Name = &quot;&quot;
	_SheetName = &quot;&quot;
	_FormDocumentName = &quot;&quot;
	Set _FormDocument = Nothing
	_FormType = ISUNDEFINED
	_CacheIndex = -1
	_IssuedFromEvent = False
	Set _Form = Nothing
	Set _Database = Nothing
	_ControlCache = Array()
End Sub		&apos;	SFDocuments.SF_Form Constructor

REM -----------------------------------------------------------------------------
Private Sub Class_Terminate()
	Call Class_Initialize()
End Sub		&apos;	SFDocuments.SF_Form Destructor

REM -----------------------------------------------------------------------------
Public Function Dispose() As Variant
	If Not IsNull(_Database) And (_FormType = ISDOCFORM Or _FormType = ISCALCFORM) Then
		Set _Database = _Database.Dispose()
	End If
	SF_Register._CleanCacheEntry(_CacheIndex)
	Call Class_Terminate()
	Set Dispose = Nothing
End Function	&apos;	SFDocuments.SF_Form Explicit Destructor

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

REM -----------------------------------------------------------------------------
Property Get Caption() As Variant
&apos;&apos;&apos;	The Caption property refers to the title of the Form
	Caption = _PropertyGet(&quot;Caption&quot;)
End Property	&apos;	SFDocuments.SF_Form.Caption (get)

REM -----------------------------------------------------------------------------
Property Let Caption(Optional ByVal pvCaption As Variant)
&apos;&apos;&apos;	Set the updatable property Caption
	_PropertySet(&quot;Caption&quot;, pvCaption)
End Property	&apos;	SFDocumentsDialog.SF_Form.Caption (let)

REM -----------------------------------------------------------------------------
Property Get Height() As Variant
&apos;&apos;&apos;	The Height property refers to the height of the Form box
	Height = _PropertyGet(&quot;Height&quot;)
End Property	&apos;	SFDocuments.SF_Form.Height (get)

REM -----------------------------------------------------------------------------
Property Let Height(Optional ByVal pvHeight As Variant)
&apos;&apos;&apos;	Set the updatable property Height
	_PropertySet(&quot;Height&quot;, pvHeight)
End Property	&apos;	SFDocuments.SF_Form.Height (let)

REM -----------------------------------------------------------------------------
Property Get Name() As String
&apos;&apos;&apos;	Return the name of the actual Form
	Name = _PropertyGet(&quot;Name&quot;)
End Property	&apos;	SFDocuments.SF_Form.Name

REM -----------------------------------------------------------------------------
Property Get Visible() As Variant
&apos;&apos;&apos;	The Visible property is False before the Execute() statement
	Visible = _PropertyGet(&quot;Visible&quot;)
End Property	&apos;	SFDocuments.SF_Form.Visible (get)

REM -----------------------------------------------------------------------------
Property Let Visible(Optional ByVal pvVisible As Variant)
&apos;&apos;&apos;	Set the updatable property Visible
	_PropertySet(&quot;Visible&quot;, pvVisible)
End Property	&apos;	SFDocuments.SF_Form.Visible (let)

REM -----------------------------------------------------------------------------
Property Get Width() As Variant
&apos;&apos;&apos;	The Width property refers to the Width of the Form box
	Width = _PropertyGet(&quot;Width&quot;)
End Property	&apos;	SFDocuments.SF_Form.Width (get)

REM -----------------------------------------------------------------------------
Property Let Width(Optional ByVal pvWidth As Variant)
&apos;&apos;&apos;	Set the updatable property Width
	_PropertySet(&quot;Width&quot;, pvWidth)
End Property	&apos;	SFDocuments.SF_Form.Width (let)

REM -----------------------------------------------------------------------------
Property Get XForm() As Object
&apos;&apos;&apos;	The XForm property returns the XForm UNO object of the Form
	XForm = _PropertyGet(&quot;XForm&quot;)
End Property	&apos;	SFDocuments.SF_Form.XForm (get)

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

REM -----------------------------------------------------------------------------
Public Function Activate() As Boolean
&apos;&apos;&apos;	Set the focus on the current Form instance
&apos;&apos;&apos;	Probably called from after an event occurrence or to focus on an open Base form document
&apos;&apos;&apos;	If the parent document is ...
&apos;&apos;&apos;		Calc		Activate the corresponding sheet
&apos;&apos;&apos;		Writer		Activate the parent document
&apos;&apos;&apos;		Base		Activate the parent form document
&apos;&apos;&apos;	Args:
&apos;&apos;&apos;	Returns:
&apos;&apos;&apos;		True if focusing is successful
&apos;&apos;&apos;	Example:
&apos;&apos;&apos;			myForm.Activate()

Dim bActivate As Boolean		&apos;	Return value
Dim oContainer As Object		&apos;	com.sun.star.awt.XWindow
Const cstThisSub = &quot;SFDocuments.Form.Activate&quot;
Const cstSubArgs = &quot;&quot;

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

Check:
	If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
		If Not _IsStillAlive() Then GoTo Finally
	End If
Try:
	Select Case _FormType
		Case ISDOCFORM		:	bActivate = [_Parent].Activate()
		Case ISCALCFORM		:	bActivate = [_Parent].Activate(_SheetName)
		Case ISBASEFORM
			Set oContainer = _FormDocument.Component.CurrentController.Frame.ContainerWindow
			With oContainer
				If .isVisible() = False Then .setVisible(True)
				.IsMinimized = False
				.setFocus()
				.toFront()				&apos;	Force window change in Linux
				Wait 1					&apos;	Bypass desynchro issue in Linux
			End With
			bActivate = True
	End Select

Finally:
	Activate = bActivate
	ScriptForge.SF_Utils._ExitFunction(cstThisSub)
	Exit Function
Catch:
	GoTo Finally
End Function	&apos;	SFDocuments.SF_Form.Activate

REM -----------------------------------------------------------------------------
Public Function CloseFormDocument() As Boolean
&apos;&apos;&apos;	Close the form document containing the actual form instance
&apos;&apos;&apos;	The form instance is disposed
&apos;&apos;&apos;	The method does nothing if the actual form is not located in a Base form document
&apos;&apos;&apos;	Args:
&apos;&apos;&apos;	Returns:
&apos;&apos;&apos;		True if closure is successful
&apos;&apos;&apos;	Example:
&apos;&apos;&apos;			myForm.CloseFormDocument()

Dim bClose As Boolean			&apos;	Return value
Dim oContainer As Object		&apos;	com.sun.star.awt.XWindow
Const cstThisSub = &quot;SFDocuments.Form.CloseFormDocument&quot;
Const cstSubArgs = &quot;&quot;

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

Check:
	If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
		If Not _IsStillAlive() Then GoTo Finally
	End If
Try:
	Select Case _FormType
		Case ISDOCFORM, ISCALCFORM, ISSUBFORM
		Case ISBASEFORM
			_FormDocument.close()
			Dispose()
			bClose = True
	End Select

Finally:
	CloseFormDocument = bClose
	ScriptForge.SF_Utils._ExitFunction(cstThisSub)
	Exit Function
Catch:
	GoTo Finally
End Function	&apos;	SFDocuments.SF_Form.CloseFormDocument

REM -----------------------------------------------------------------------------
Public Function Controls(Optional ByVal ControlName As Variant) As Variant
&apos;&apos;&apos;	Return either
&apos;&apos;&apos;		- the list of the controls contained in the Form
&apos;&apos;&apos;		- a Form control object based on its name
&apos;&apos;&apos;	Args:
&apos;&apos;&apos;		ControlName: a valid control name as a case-sensitive string. If absent the list is returned
&apos;&apos;&apos;	Returns:
&apos;&apos;&apos;		A zero-base array of strings if ControlName is absent
&apos;&apos;&apos;		An instance of the SF_FormControl class if ControlName exists
&apos;&apos;&apos;	Exceptions:
&apos;&apos;&apos;		ControlName is invalid
&apos;&apos;&apos;	Example:
&apos;&apos;&apos;			Dim myForm As Object, myList As Variant, myControl As Object
&apos;&apos;&apos;				Set myForm = CreateScriptService(&quot;SFDocuments.Form&quot;, Container, Library, FormName)
&apos;&apos;&apos;				myList = myForm.Controls()
&apos;&apos;&apos;				Set myControl = myForm.Controls(&quot;myTextBox&quot;)

Dim oControl As Object				&apos;	The new control class instance
Dim lIndexOfNames As Long			&apos;	Index in ElementNames array. Used to access _ControlCache
Dim vControl As Variant				&apos;	Alias of _ControlCache entry
Const cstThisSub = &quot;SFDocuments.Form.Controls&quot;
Const cstSubArgs = &quot;[ControlName]&quot;

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

Check:
	If IsMissing(ControlName) Or IsEmpty(ControlName) Then ControlName = &quot;&quot;
	If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
		If Not _IsStillAlive() Then GoTo Finally
		If Not ScriptForge.SF_Utils._Validate(ControlName, &quot;ControlName&quot;, V_STRING) Then GoTo Finally
	End If

Try:
	If Len(ControlName) = 0 Then
	Else
	End If

Finally:
	ScriptForge.SF_Utils._ExitFunction(cstThisSub)
	Exit Function
Catch:
	GoTo Finally
CatchNotFound:
	ScriptForge.SF_Utils._Validate(ControlName, &quot;ControlName&quot;, V_STRING, _FormModel.getElementNames())
	GoTo Finally
End Function	&apos;	SFDocuments.SF_Form.Controls

REM -----------------------------------------------------------------------------
Public Function GetDatabase(Optional ByVal User As Variant _
								, Optional ByVal Password As Variant _
								) As Object
&apos;&apos;&apos;	Returns a Database instance (service = SFDatabases.Database) giving access
&apos;&apos;&apos;	to the execution of SQL commands on the database defined and/or stored in
&apos;&apos;&apos;	the actual Base document
&apos;&apos;&apos;	Each form has its own database connection, except within Base documents where
&apos;&apos;&apos;	they all share the same connection
&apos;&apos;&apos;	Args:
&apos;&apos;&apos;		User, Password: the login parameters as strings. Defaults = &quot;&quot;
&apos;&apos;&apos;	Returns:
&apos;&apos;&apos;		A SFDatabases.Database instance or Nothing
&apos;&apos;&apos;	Example:
&apos;&apos;&apos;		Dim myDb As Object
&apos;&apos;&apos;			Set myDb = oForm.GetDatabase()

Dim FSO As Object				&apos;	Alias for SF_FileSystem
Dim sUser As String				&apos;	Alias for User
Dim sPassword As String			&apos;	Alias for Password
Const cstThisSub = &quot;SFDocuments.Form.GetDatabase&quot;
Const cstSubArgs = &quot;[User=&quot;&quot;&quot;&quot;], [Password=&quot;&quot;&quot;&quot;]&quot;

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

Check:
	If IsMissing(User) Or IsEmpty(User) Then User = &quot;&quot;
	If IsMissing(Password) Or IsEmpty(Password) Then Password = &quot;&quot;
	If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
		If Not [_Parent]._IsStillAlive(True) Then GoTo Finally
		If Not ScriptForge.SF_Utils._Validate(User, &quot;User&quot;, V_STRING) Then GoTo Finally
		If Not ScriptForge.SF_Utils._Validate(Password, &quot;Password&quot;, V_STRING) Then GoTo Finally
	End If

Try:
	&apos;	Adjust connection arguments
	If Len(User) = 0 Then
		If ScriptForge.SF_Session.HasUnoProperty(_Form, &quot;User&quot;) Then sUser = _Form.User Else sUser = &quot;&quot;
	Else
		sUser = User
	End If
	If Len(sUser) + Len(Password) = 0 Then
		If ScriptForge.SF_Session.HasUnoProperty(_Form, &quot;Password&quot;) Then sPassword = _Form.Password Else sPassword = Password
	End If

	&apos;	Connect to database, avoiding multiple requests
	If IsNull(_Database) Then		&apos;	1st connection request from the current form instance
		If _FormType = ISBASEFORM Then
			&apos;	Fetch the shared connection
			Set _Database = [_Parent].GetDatabase(User, Password)
		ElseIf Len(_Form.DataSOurceName) = 0 Then	&apos;	There is no database linked with the form
			&apos;	Return Nothing
		Else
			&apos;	Check if DataSourceName is a file or a registered name and create database instance accordingly
			Set FSO = ScriptForge.SF_FileSystem
			If FSO.FileExists(FSO._ConvertFromUrl(_Form.DataSourceName)) Then
				Set _Database = ScriptForge.SF_Services.CreateScriptService(&quot;SFDatabases.Database&quot; _
								, _Form.DataSourceName, , , sUser, sPassword)
			Else
				Set _Database = ScriptForge.SF_Services.CreateScriptService(&quot;SFDatabases.Database&quot; _
								, , _Form.DataSourceName, , sUser, sPassword)
			End If
			If IsNull(_Database) Then GoTo CatchConnect
		End If
	Else
	EndIf

Finally:
	Set GetDatabase = _Database
	ScriptForge.SF_Utils._ExitFunction(cstThisSub)
	Exit Function
Catch:
	GoTo Finally
CatchConnect:
	ScriptForge.SF_Exception.RaiseFatal(DBCONNECTERROR, &quot;User&quot;, User, &quot;Password&quot;, Password, [_Super]._FileIdent())
	GoTo Finally
End Function	&apos;	SFDocuments.SF_Form.GetDatabase

REM -----------------------------------------------------------------------------
Public Function GetProperty(Optional ByVal PropertyName As Variant) As Variant
&apos;&apos;&apos;	Return the actual value of the given property
&apos;&apos;&apos;	Args:
&apos;&apos;&apos;		PropertyName: the name of the property as a string
&apos;&apos;&apos;	Returns:
&apos;&apos;&apos;		The actual value of the property
&apos;&apos;&apos;	Exceptions:
&apos;&apos;&apos;		ARGUMENTERROR		The property does not exist
&apos;&apos;&apos;	Examples:
&apos;&apos;&apos;		oDlg.GetProperty(&quot;Caption&quot;)

Const cstThisSub = &quot;SFDocuments.Form.GetProperty&quot;
Const cstSubArgs = &quot;&quot;

	If 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, &quot;PropertyName&quot;, V_STRING, Properties()) Then GoTo Catch
	End If

Try:
	GetProperty = _PropertyGet(PropertyName)

Finally:
	SF_Utils._ExitFunction(cstThisSub)
	Exit Function
Catch:
	GoTo Finally
End Function	&apos;	SFDocuments.SF_Form.GetProperty

REM -----------------------------------------------------------------------------
Public Function Methods() As Variant
&apos;&apos;&apos;	Return the list of public methods of the Form service as an array

	Methods = Array( _
					&quot;Activate&quot; _
					, &quot;CloseForm&quot; _
					, &quot;Controls&quot; _
					, &quot;First&quot; _
					, &quot;GetDatabase&quot; _
					, &quot;Last&quot; _
					, &quot;Move&quot; _
					, &quot;New&quot; _
					, &quot;Next&quot; _
					, &quot;Previous&quot; _
					, &quot;Refresh&quot; _
					, &quot;Requery&quot; _
					, &quot;SubForms&quot; _
					)

End Function	&apos;	SFDocuments.SF_Form.Methods

REM -----------------------------------------------------------------------------
Public Function Properties() As Variant
&apos;&apos;&apos;	Return the list or properties of the Form class as an array

	Properties = Array( _
					&quot;AllowAdditions&quot; _
					, &quot;AllowDeletions&quot; _
					, &quot;AllowEdits&quot; _
					, &quot;Bookmark&quot; _
					, &quot;Caption&quot; _
					, &quot;CurrentRecord&quot; _
					, &quot;Filter&quot; _
					, &quot;FilterOn&quot; _
					, &quot;Height&quot; _
					, &quot;IsLoaded&quot; _
					, &quot;LinkChildFields&quot; _
					, &quot;LinkParentFields&quot; _
					, &quot;Name&quot; _
					, &quot;OnApproveCursorMove&quot; _
					, &quot;OnApproveParameter&quot; _
					, &quot;OnApproveReset&quot; _
					, &quot;OnApproveRowChange&quot; _
					, &quot;OnApproveSubmit&quot; _
					, &quot;OnConfirmDelete&quot; _
					, &quot;OnCursorMoved&quot; _
					, &quot;OnErrorOccurred&quot; _
					, &quot;OnLoaded&quot; _
					, &quot;OnReloaded&quot; _
					, &quot;OnReloading&quot; _
					, &quot;OnResetted&quot; _
					, &quot;OnRowChanged&quot; _
					, &quot;OnUnloaded&quot; _
					, &quot;OnUnloading&quot; _
					, &quot;OrderBy&quot; _
					, &quot;OrderByOn&quot; _
					, &quot;Parent&quot; _
					, &quot;RecordSource&quot; _
					, &quot;Visible&quot; _
					, &quot;Width&quot; _
					, &quot;XForm&quot; _
					)

End Function	&apos;	SFDocuments.SF_Form.Properties

REM -----------------------------------------------------------------------------
Public Function SetProperty(Optional ByVal PropertyName As Variant _
								, Optional ByRef Value As Variant _
								) As Boolean
&apos;&apos;&apos;	Set a new value to the given property
&apos;&apos;&apos;	Args:
&apos;&apos;&apos;		PropertyName: the name of the property as a string
&apos;&apos;&apos;		Value: its new value
&apos;&apos;&apos;	Exceptions
&apos;&apos;&apos;		ARGUMENTERROR		The property does not exist

Const cstThisSub = &quot;SFDocuments.Form.SetProperty&quot;
Const cstSubArgs = &quot;PropertyName, Value&quot;

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

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

Try:
	SetProperty = _PropertySet(PropertyName, Value)
				Set UI = ScriptForge.SF_Services.CreateScriptService(&quot;ScriptForge.UI&quot;)

Finally:
	SF_Utils._ExitFunction(cstThisSub)
	Exit Function
Catch:
	GoTo Finally
End Function	&apos;	SFDocuments.SF_Form.SetProperty

REM =========================================================== PRIVATE FUNCTIONS

REM -----------------------------------------------------------------------------
Public Function _GetEventName(ByVal psProperty As String) As String
&apos;&apos;&apos;	Return the LO internal event name derived from the SF property name
&apos;&apos;&apos;	The SF property name is not case sensitive, while the LO name is case-sensitive
&apos;	Corrects the typo on ErrorOccur(r?)ed, if necessary

Dim vProperties As Variant			&apos;	Array of class properties
Dim sProperty As String				&apos;	Correctly cased property name

	vProperties = Properties()
	sProperty = vProperties(ScriptForge.SF_Array.IndexOf(vProperties, psProperty, SortOrder := &quot;ASC&quot;))

	_GetEventName = LCase(Mid(sProperty, 3, 1)) &amp; Right(sProperty, Len(sProperty) - 3)
	
End Function	&apos;	SFDocuments.SF_Form._GetEventName

REM -----------------------------------------------------------------------------
Private Function _GetListener(ByVal psEventName As String) As String
&apos;&apos;&apos;	Getting/Setting macros triggered by events requires a Listener-EventName pair
&apos;&apos;&apos;	Return the X...Listener corresponding with the event name in argument

	Select Case UCase(psEventName)
		Case Else
			_GetListener = &quot;&quot;
	End Select
	
End Function	&apos;	SFDocuments.SF_Form._GetListener

REM -----------------------------------------------------------------------------
Private Sub _GetParents()
&apos;&apos;&apos;	When the current instance is created top-down, the parents are completely defined
&apos;&apos;&apos;	and nothing should be done in this method
&apos;&apos;&apos;	When the a class instance is created in a (form/control) event, it is the opposite
&apos;&apos;&apos;	The current method rebuilds the missing members in the instance from the bottom
&apos;&apos;&apos;	Members potentially to collect are:
&apos;&apos;&apos;		- _FormType
&apos;&apos;&apos;		- [_Parent], the immediate parent: a form or a document instance
&apos;&apos;&apos;		+ Only when the _FormType is a main form
&apos;&apos;&apos;			- _SheetName (Calc only)
&apos;&apos;&apos;			- _FormDocumentName (Base only)
&apos;&apos;&apos;			- _FormDocument, the topmost form collection
&apos;&apos;&apos;			- _Component, the containing document
&apos;&apos;&apos;	They must be identified only starting from the _Form UNO object
&apos;&apos;&apos;
&apos;&apos;&apos;	The method is called from the _Initialize() method at instance creation

Dim oParent As Object				&apos;	Successive bottom-up parents
Dim sType As String					&apos;	UNO object type
Dim sPersistentName As String		&apos;	The Obj... name of a Base form
Dim iLevel As Integer				&apos;	When = 1 =&gt; first parent
Dim oSession As Object				:	Set oSession = ScriptForge.SF_Session

	On Local Error GoTo Finally		&apos;	Being probably called from events, this method should avoid failures
	&apos;	When the form type is known, the upper part of the branch is not scanned
	If _FormType &lt;&gt; ISUNDEFINED Then GoTo Finally

Try:
	&apos;	The whole branch is scanned bottom-up
	If oSession.HasUnoProperty(_Form, &quot;Parent&quot;) Then Set oParent = _Form.Parent Else Set oParent = Nothing
	_FormType = ISUNDEFINED
	iLevel = 1

	Do While Not IsNull(oParent)
		sType = SF_Session.UnoObjectType(oParent)
		Select Case sType
			&apos;	Collect at each level the needed info
			Case &quot;com.sun.star.comp.forms.ODatabaseForm&quot;	&apos;	The parent _Form of a subform
				If iLevel = 1 Then
					_FormType = ISSUBFORM
					Set [_Parent] = SF_Register._NewForm(oParent)
					&apos;	The parent form could be a main form
					[_Parent]._Initialize()
					&apos;	Everything is in the parent, stop scan
					Exit Sub
				End If
			Case &quot;com.sun.star.form.OFormsCollection&quot;		&apos;	The collection of forms inside a drawpage
			Case &quot;SwXTextDocument&quot;							&apos;	The parent document: a Writer document or a Base form document
				If oParent.Identifier = &quot;com.sun.star.sdb.FormDesign&quot; Then
					sPersistentName = ScriptForge._GetPropertyValue(oParent.Args, &quot;HierarchicalDocumentName&quot;)
				ElseIf oParent.Identifier = &quot;com.sun.star.text.TextDocument&quot; Then
					_FormType = ISDOCFORM
					Set [_Parent] = ScriptForge.SF_Services.CreateScriptService(&quot;SFDocuments.Document&quot;, oParent)
					Set _Component = [_Parent]._Component
				End If
			Case &quot;ScModelObj&quot;								&apos;	The parent document: a Calc document
				_FormType = ISCALCFORM
				Set [_Parent] = ScriptForge.SF_Services.CreateScriptService(&quot;SFDocuments.Document&quot;, oParent)
				Set _Component = oParent
				&apos;	The triggered form event is presumed to be located in the (drawpage of the) active sheet
				_SheetName = [_Parent].XSpreadsheet(&quot;~&quot;)
			Case &quot;com.sun.star.comp.dba.ODatabaseDocument&quot;	&apos;	The Base document
				_FormType = ISBASEFORM
				Set [_Parent] = ScriptForge.SF_Services.CreateScriptService(&quot;SFDocuments.Document&quot;, oParent)
				Set _Component = oParent
				If IsNull([_Parent]._FormDocuments) Then Set [_Parent]._FormDocuments = _Component.getFormDocuments()
				Set _FormDocument = [_Parent]._FindByPersistentName([_Parent]._FormDocuments, sPersistentName)
			Case Else
		End Select
		If oSession.HasUnoProperty(oParent, &quot;Parent&quot;) Then Set oParent = oParent.Parent Else Set oParent = Nothing
		iLevel = iLevel + 1
	Loop

Finally:
	Exit Sub
End Sub	&apos;	SFDocuments.SF_Form._GetParents

REM -----------------------------------------------------------------------------
Public Sub _Initialize()
&apos;&apos;&apos;	Achieve the creation of a SF_Form instance
&apos;&apos;&apos;		- complete the missing private members
&apos;&apos;&apos;		- store the new instance in the cache

	
	_GetParents()
	_CacheIndex = SF_Register._AddFormToCache(_Form, [Me])

End Sub			&apos;	SFDocuments.SF_Form._Initialize

REM -----------------------------------------------------------------------------
Private Function _IsStillAlive(Optional ByVal pbError As Boolean) As Boolean
&apos;&apos;&apos;	Return True if the Form is still open
&apos;&apos;&apos;	If dead the actual instance is disposed
&apos;&apos;&apos;	and the execution is cancelled when pbError = True (default)
&apos;&apos;&apos;	Args:
&apos;&apos;&apos;		pbError: if True (default), raise a fatal error

Dim bAlive As Boolean		&apos;	Return value
Dim sName As String			&apos;	Alias of _Name
Dim sId As String			&apos;	Alias of FileIdent

Check:
	On Local Error GoTo Catch		&apos;	Anticipate DisposedException errors or alike
	If IsMissing(pbError) Then pbError = True

Try:
	If _IssuedFromEvent Then		&apos;	Instance is presumed alive when issued from an event
		bAlive = True
	Else
		&apos;	For usual documents, check that the parent document is still open
		&apos;	For Base forms and subforms, check the openness of the main form
		Select Case _FormType
			Case ISDOCFORM, ISCALCFORM
				bAlive = [_Parent]._IsStillAlive(pbError)
			Case ISBASEFORM, ISSUBFORM
				&apos;	A form that has never been opened has no component
				&apos;	If ever opened and closed afterwards, it keeps the Component but loses its Controller
				bAlive = Not IsNull(_FormDocument.Component)
				If bAlive Then bAlive = Not IsNull(_FormDocument.Component.CurrentController)
		End Select
		If Not bAlive Then GoTo Catch
	End If

Finally:
	_IsStillAlive = bAlive
	Exit Function
Catch:
	bAlive = False
	On Error GoTo 0
	&apos;	Keep error message elements before disposing the instance
	sName = _SheetName &amp; _FormDocumentName		&apos;	At least one of them is a zero-length string
	sName = Iif(Len(sName) &gt; 0, &quot;[&quot; &amp; sName &amp; &quot;].&quot;, &quot;&quot;) &amp; _Name
	sId = [_Parent]._FileIdent()
	&apos;	Dispose the actual forms instance
	Dispose()
	&apos;	Display error message
	If pbError Then ScriptForge.SF_Exception.RaiseFatal(FORMDEADERROR, sName, sId)
	GoTo Finally
End Function	&apos;	SFDocuments.SF_Form._IsStillAlive

REM -----------------------------------------------------------------------------
Private Function _PropertyGet(Optional ByVal psProperty As String) As Variant
&apos;&apos;&apos;	Return the value of the named property
&apos;&apos;&apos;	Args:
&apos;&apos;&apos;		psProperty: the name of the property

Static oSession As Object		&apos;	Alias of SF_Session
Dim cstThisSub As String
Const cstSubArgs = &quot;&quot;

	cstThisSub = &quot;SFDocuments.Form.get&quot; &amp; psProperty
	If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch

	ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs)
	If Not _IsStillAlive() Then GoTo Finally

	If IsNull(oSession) Then Set oSession = ScriptForge.SF_Services.CreateScriptService(&quot;Session&quot;)
	Select Case UCase(psProperty)
		Case UCase(&quot;Caption&quot;)
		Case UCase(&quot;Height&quot;)
		Case UCase(&quot;Name&quot;)
		Case UCase(&quot;Parent&quot;)
			_PropertyGet = [_Parent]
		Case UCase(&quot;Visible&quot;)
		Case UCase(&quot;Width&quot;)
		Case UCase(&quot;XForm&quot;)
			Set _PropertyGet = _Form
		Case Else
			_PropertyGet = Null
	End Select

Finally:
	ScriptForge.SF_Utils._ExitFunction(cstThisSub)
	Exit Function
Catch:
	GoTo Finally
End Function	&apos;	SFDocuments.SF_Form._PropertyGet

REM -----------------------------------------------------------------------------
Private Function _PropertySet(Optional ByVal psProperty As String _
								, Optional ByVal pvValue As Variant _
								) As Boolean
&apos;&apos;&apos;	Set the new value of the named property
&apos;&apos;&apos;	Args:
&apos;&apos;&apos;		psProperty: the name of the property
&apos;&apos;&apos;		pvValue: the new value of the given property
&apos;&apos;&apos;	Returns:
&apos;&apos;&apos;		True if successful

Dim bSet As Boolean							&apos;	Return value
Static oSession As Object					&apos;	Alias of SF_Session
Dim cstThisSub As String
Const cstSubArgs = &quot;Value&quot;

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

	cstThisSub = &quot;SFDocuments.Form.set&quot; &amp; psProperty
	ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs)
	If Not _IsStillAlive() Then GoTo Finally

	If IsNull(oSession) Then Set oSession = ScriptForge.SF_Services.CreateScriptService(&quot;Session&quot;)
	bSet = True
	Select Case UCase(psProperty)
		Case UCase(&quot;Caption&quot;)
		Case UCase(&quot;Height&quot;)
		Case UCase(&quot;Visible&quot;)
		Case UCase(&quot;Width&quot;)
		Case Else
			bSet = False
	End Select

Finally:
	_PropertySet = bSet
	ScriptForge.SF_Utils._ExitFunction(cstThisSub)
	Exit Function
Catch:
	GoTo Finally
End Function	&apos;	SFDocuments.SF_Form._PropertySet

REM -----------------------------------------------------------------------------
Private Function _Repr() As String
&apos;&apos;&apos;	Convert the Model instance to a readable string, typically for debugging purposes (DebugPrint ...)
&apos;&apos;&apos;	Args:
&apos;&apos;&apos;	Return:
&apos;&apos;&apos;		&quot;[Form]: Name&quot;

Dim sParent As String		&apos;	To recognize the parent

	sParent = _SheetName &amp; _FormDocumentName		&apos;	At least one of them is a zero-length string
	_Repr = &quot;[Form]: &quot; &amp; Iif(Len(sParent) &gt; 0, sParent &amp; &quot;...&quot;, &quot;&quot;) &amp; _Name

End Function	&apos;	SFDocuments.SF_Form._Repr

REM ============================================ END OF SFDOCUMENTS.SF_FORM
</script:module>