comet.CDialog
*******************************************************************************

.. py:class:: comet.CDialog

This section describes all functions for the CDialog class.

For creating a dialog you need a dialog specification, which is a JSON string.
CDialog manages the dialog specification internally through the class functions, so there is no need for manual creating and editing.
To create a CDialog instance from either an existing specification string, or an empty dialog, use :py:func:`.dialog.create`.

Each control widget (checkbox, textfield, etc...) may appear multiple times in the specification, but must have a unique ID (string) within it's own type. Afterwards, the dialog specification is used to build the dialog when :py:meth:`.show` is called.
After the dialog has closed or an dialog event has been caught in a callback function, control results can be fetched using the *get*.. functions (:py:meth:`.getCheckBoxValue`, ...)

:priint-important:`IDs with the prefix '%!'' are reserved for internal use and must not be used for elements.`

.. container:: priint-block-important
	
	For technical reasons all *get* functions (e.g. :py:meth:`.getCheckBoxValue`) will return values for the last opened dialog, which is not necessarily the calling CDialog object.

.. seealso::
	:py:mod:`.dialog`

Methods
===============================================================================

.. automethod:: comet.CDialog.setTitle
.. automethod:: comet.CDialog.setSize
.. automethod:: comet.CDialog.addLabel
.. automethod:: comet.CDialog.addCheckBox
.. automethod:: comet.CDialog.addIntField
.. automethod:: comet.CDialog.addFloatField
.. automethod:: comet.CDialog.addTextField
.. automethod:: comet.CDialog.addMultilineTextField
.. automethod:: comet.CDialog.addMultilineTextInfo
.. automethod:: comet.CDialog.addDropDown
.. automethod:: comet.CDialog.addDefaultButtons
.. automethod:: comet.CDialog.show
.. automethod:: comet.CDialog.getConfirmingButton
.. automethod:: comet.CDialog.getCheckBoxValue
.. automethod:: comet.CDialog.getTextFieldValue
.. automethod:: comet.CDialog.getMultiLineTextFieldValue
.. automethod:: comet.CDialog.getFloatFieldValue
.. automethod:: comet.CDialog.getIntFieldValue
.. automethod:: comet.CDialog.getDropDownValue
.. automethod:: comet.CDialog.getSpecification

Special methods
===============================================================================

.. automethod:: comet.CDialog.__repr__
	
Examples
===============================================================================

.. code-block:: python
	:caption: Create a dialog with all available controls. At the end, the user's input is retrieved and used in the script. 

	#!py
	#pragma plain
	import comet

	def main():
		#Create a new dialog instance
		dialog: comet.CDialog = comet.dialog.create()

		#Set up the dialog properties
		dialog.setTitle('Dialog Demo')		#Set the title of the dialog
		dialog.setSize(360, 400)			#Set the dimensions of the dialog
		
		#Add various UI components to the dialog
		dialog.addLabel('label1', 'This is a basic dialog framework demo', 40.0, 20.0, 250.0, 30.0)

		#Add a checkbox
		dialog.addCheckBox('cb1', 'This is a checkbox', True, 40.0, 60.0, 200.0, 20.0)

		#Add a textfield
		dialog.addTextField('tf1', 'This is a textfield', 40.0, 90.0, 200.0, 20.0)
		
		#Add float and integer input fields with labels
		dialog.addLabel('label2', 'This is a floatfield:', 40.0, 120.0, 130.0, 20.0)
		dialog.addFloatField('ff1', 10.5, 160.0, 120.0, 75.0, 20.0)
		dialog.addLabel('label3', 'This is an intfield:', 40.0, 150.0, 130.0, 20.0)
		dialog.addIntField('if1', 333, 160.0, 150.0, 75.0, 20.0)
		
		#Add a dropdown menu
		#Define entries for the dropdown menu, including a separator
		dropDownEntries: list[str] = [
			'Entry one',
			'Entry two',
			'-',  #Separator
			'Entry three',
			'Entry four',
		]
		dialog.addLabel('label4', 'This is a dropdown:', 40.0, 190.0, 130.0, 20.0)
		dialog.addDropDown('dd1', dropDownEntries, 0, 160.0, 190.0, 125.0, 20.0)
		
		#Add a multi-line text field
		dialog.addMultilineTextField('mtf1', 'This is a \nmulti-\nline-\ntextfield', 40.0, 230.0, 200.0, 75.0)
		
		#Add default buttons (OK and Cancel)
		dialog.addDefaultButtons()
		
		#Show the dialog
		dialog.show()

		#Retrieve user input from all controls and display them in a message box
		comet.dialog.showMessage(
			f'Dialog results:\n'
			f'Closed by confirm button: {dialog.getConfirmingButton()}\n'
			f'Checkbox "cb1": {dialog.getCheckBoxValue("cb1")}\n'
			f'Textfield "tf1": {dialog.getTextFieldValue("tf1")}\n'
			f'Multiline Textfield "mtf1": {dialog.getMultiLineTextFieldValue("mtf1")}\n'
			f'Floatfield "ff1": {dialog.getFloatFieldValue("ff1")}\n'
			f'Intfield "if1": {dialog.getIntFieldValue("if1")}\n'
			f'Dropdown "dd1": {dialog.getDropDownValue("dd1")}'
		)

		return 0