TDEConfig XT Tutorial - Revision history

Blu256: Added full config key types table

2022-04-16T15:48:26Z

Added full config key types table

Show changes

Blu256: /* .kcfgc files */ default values for booleans

2022-04-16T11:07:13Z

.kcfgc files: default values for booleans

Blu256: /* .kcfgc files */ Update table based on tdeconfig_compiler source code

2022-04-16T10:56:45Z

.kcfgc files: Update table based on tdeconfig_compiler source code

Blu256: /* Adjusting the Makefile.am */ Update for CMake

2022-04-16T10:31:12Z

Adjusting the Makefile.am: Update for CMake

Blu256: Restore some original formatting

2022-04-16T10:28:51Z

Restore some original formatting

Blu256: /* Example */ K -> TDE

2022-01-06T15:43:35Z

Example: K -> TDE

Blu256: Small fixes, added illustration

2022-01-06T13:59:45Z

Small fixes, added illustration

Blu256: Blu256 moved page KConfig Tutorial to TDEConfig XT Tutorial: More appropriate naming

2022-01-06T13:55:56Z

Blu256 moved page KConfig Tutorial to TDEConfig XT Tutorial: More appropriate naming

Blu256: Added KConfig tutorial from the old KDE Developer site

2022-01-06T13:55:09Z

Added KConfig tutorial from the old KDE Developer site

New page

This tutorial will introduce you to the main concepts of the '''TDEConfig XT''' configuration framework and will show you how to efficiently use it in your application.

This tutorial assumes that reader has already developed a TDE application and is familiar with TDEConfig. Basic understanding of XML and concepts behind DTD's is also required.

In this tutorial the more advanced and optional features of TDEConfig XT and their descriptions are marked by italic text. If you'll decide to skip them during the first reading, make sure you'll come back to them at some point.

= Generic overview =

The main idea behind TDEConfig XT is to make the life of application developers easier while making the administration of large TDE installations more manageable.

The four basic parts of the new framework are:

* TDEConfigSkeleton - a class in the <tt>tdecore</tt> library which grants a more flexible access to the configuration options,
* XML file containing information about configuration options (the .kcfg file)
* An ini like file which provides the code generation options (the .kcfgc file)
* <tt>tdeconfig_compiler</tt> - which generates C++ source code from .kcfg and .kcfgs files. The generated class is based on TDEConfigSkeleton and provides an API for the application to access its configuration data.

= DTD Structure of a .kcfg file =

The structure of the .kcfg file is described by its DTD (kcfg.dtd - available from here (please note that browsers do not display DTD's in a visual form, download the dtd directly and view it like a text file) or the kdecore library). Please go through it before you go any further.

Lets create a simple kcfg file. Please reference the code below as we go through each step.

<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE kcfg SYSTEM "http://www.kde.org/standards/kcfg/1.0/kcfg.dtd">
<kcfg>
<kcfgfile name="kjotsrc"/>
<group name="kjots">
<entry name="SplitterSizes" type="IntList">
<label>How the main window is divided.</label>
</entry>
<entry name="Width" type="Int">
<label>Width of the main window.</label>
<default>600</default>
</entry>
<entry name="Height" type="Int">
<label>Height of the main window.</label>
<default>400</default>
</entry>
<entry name="OpenBooks" type="StringList">
<label>All books that are opened.</label>
</entry>
<entry name="CurrentBook" type="String">
<label>The book currently opened.</label>
</entry>
<entry name="Font" type="Font">
<label>The font used to display the contents of books.</label>
<default code="true">KGlobalSettings::generalFont()</default>
</entry>
</group>
</kcfg>
</syntaxhighlight>

Use your favorite code editor to open a your_application_name .kcfg file (of course replacing your_application_name with the name of the application you want to convert to TDEConfig XT).

Start that file by opening the <code><kcfgfile></code> tag which contains the <tt>name</tt> attribute with the value corresponding to the actual TDEConfig file which it describes. (The actual TDEConfig file are the rc files).

Add the optional <code><include></code> tags which may contain C++ header files that are needed to compile the code required to compute the default values.

The remaining entries in the XML file are grouped by the tag <code><group></code> which describes the corresponding groups in the configuration file.

The individual entries must have at least a name or a key. The name is used to create accessor and modifier functions. It's also used as the key in the config file. If <code><key></code> is given, but not <code><name></code>, the name is constructed by removing all spaces from the <code><key></code> contents.

Always add a label or a whatsthis tags to your application in which you describe the configuration options. The label tag is used for short descriptions of the entry, while <tt>whatsthis</tt> contains more verbose documentation. It's important for tools  which can be used by systems administrators to setup machines over on the network.

An entry must also have a type. The list of allowable types is specified in the DTD and loosely follows the list of types supported by the TQVariant with exception of the clearly binary types (e.g. Pixmap, Image...) which are not supported. Besides those basic type the following special types are supported and include:

{| class="wikitable"
! Type
! Decription
|-
| '''Path'''
| This is a string that is specially treated as a file-path. In particular paths in the home directory are prefixed with $HOME when being stored in the configuration file.
|-
| '''Enum'''
| This indicates an enumeration. The possible enum values should be provided via the <choices> tag. Enum values are accessed as integers by the application but stored as string in the configuration file. This makes it possible to add more values at a later date without breaking compatibility.
|-
| '''IntList'''
| This indicates a list of integers. This information is provided to the application as TQValueList<int>. Useful for storing TQSplitter geometries.
|}

An entry can optionally have a default value which is used as default when the value isn't specified in any config file. Default values are interpreted as literal constant values. If a default value needs to be computed or if it needs to be obtained from a function call, the <code><default></code> tag should contain the <tt>code="true"</tt> attribute. The contents of the <code><default></code> tag is then considered to be a C++ expression.

Additional code for computing default values can be provided via the <code><code></code> tag. The contents of the <code><code></code> tag is inserted as-is. A typical use for this is to compute a common default value which can then be referenced by multiple entries that follow.

= .kcfgc files =

After creating a .kcfg file create a .kcfgc file which describes the C++ file generation options. The .kcfgc file is a simple ini file with the typical "entry=value" format. To create a simple .kcfgc file follow these steps:

* Open a new file in your favorite text editor.
* Start it with the "File=your_application_name.kcfg" entry which specifies where the configuration options for your application are stored.
* Add the "ClassName=YourConfigClassName" entry which specifies the name of the class that will be generated from the .kcfg file. Remember that the generated class will be derived from TDEConfigSkeleton. PLease make sure that YourConfigClassName is not a class name already used in your application. Save this file under yourconfigclassname.kcfgc. This will ensure the generation of the yourconfigclassname.{h,cpp} files where your configuration class will reside.
* Add any additional entries, which your application might need. Those additional entries include:

{| class="wikitable"
! Entry
! Description
|-
| '''NameSpace'''
| Specifies the namespace in which the generated config class should reside.
|-
| '''Inherits'''
| If you need the generated class to inherit your custom class.
|-
| '''Singleton'''
| If the configuration class should be a singleton.
|-
| '''MemberVariables'''
| Specifies the access to the member variables, default is private.
|-
| '''ItemAccessors'''
| Relates to the above item, if member variables are public then it might make little sense to generate accessors. By default they are generated.
|-
| '''Mutators'''
| Similar to the above one, but applies to the mutator methods.
|-
| '''GlobalEnums'''
| Specifies whether the enums should be class wide of whether they should be always explicitly prefixed with their type name.
|}

= Adjusting the Makefile.am =

{{Outdated}}

After creating the .kcfg and .kcfgc files the next step is to adjust the Makefile.am to let tdeconfig_compiler generate the required class at compile time.

Fortunately those changes are trivial and require only two steps:

* Add the .kcfgc file to your_application_name_SOURCES entry,
* Add an entry looking as follows:

kde_kcfg_DATA = your_application_name.kcfg

The first assures that the configuration class is properly generated the second that the .kcfg is actually being installed and can be used by tools like the TDEConfigEditor.

= Use and Dialogs =

After making all of the above changes you're ready to use TDEConfig XT. The tdeconfig_compiler generated header file will have the name equal to the value you've specified in the kcfgc ClassName attribute plus the ".h" extension. Simply include that file whereever you want to access your configuration options.

The use will depend on whether you have added the <tt>Singleton=true</tt> entry to your kcfgc file.

One the nicest features of the TDEConfig XT is its seamless integration with the Qt Designer generated dialogs. You can do that by using KConfigDialog. The steps to do that are as follows:

* Create the TDEConfigDialog and pass the instance of your configuration data as one of the arguments. The construct would look like the following example:

<syntaxhighlight lang="cpp-qt">
TDEConfigDialog* dialog = new TDEConfigDialog( this, "settings", YourAppSettings::self() );
</syntaxhighlight>

: assuming that YourAppSettings is the value of the ClassName variable from the kcfgc file and the settings class is a singelton.

* In TQt Designer create widgets which should be used to configure your options. In order to make those widgets interact with the kcfg you have name each one of them using the following scheme:
Prefix the Name of the widget which should control one of the options with "kcfg_"
Append the "name" attribute value from your kcfg file which corresponds to option the given widget should control.

* Add the TQt Designer generated widget to the TDEConfigDialog.
* Show the dialog when you're done.

= Example =

Here's an example usage of TDEConfig XT for the application named Example. With the following example.kcfg file:

<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE kcfg SYSTEM"http://www.kde.org/standards/kcfg/1.0/kcfg.dtd">
<kcfg> <kcfgfile name="examplerc"/>
<group name="network">
<entry name="ServerName" type="String">
<label>Defines the sample server.</label>
</entry>
<entry name="Port" type="Int">
<label>Defines the server port</label>
<default>21</default>
</entry>
</group>
</kcfg>
</syntaxhighlight>

And here's how to actually use the generated class. for the given kcfgc file.

<syntaxhighlight lang="ini">
File=example.kcfg
ClassName=ExampleSettings
Singleton=true
Mutators=true
</syntaxhighlight>

The header files wouldn't change, but the cpp files must now contain the following code to access and store the configuration data:

<syntaxhighlight lang="cpp-qt">
...
#include <ExampleSettings.h>
...
void ExampleClass::readConfig() {
m_server = ExampleSettings::serverName();
m_port = ExampleSettings::port();
}
void ExampleClass:saveSettings() {
ExampleSettings::setServerName( m_server );
ExampleSettings::setPort( m_port );
ExampleSettings::writeConfig();
}
</syntaxhighlight>

To add a dialog you need to create a TQt Designer widget with the widget names corresponding to the names of the options they should edit and prefixed with "kcfg_". It could be something along the lines of :
sample dialog

And you can use the dialog with the following code:

<syntaxhighlight lang="cpp-qt">
//An instance of your dialog could be already created and could be cached,
//in which case you want to display the cached dialog instead of creating
//another one
if ( TDEConfigDialog::showDialog( "settings" ) )
return;

//TDEConfigDialog didn't find an instance of this dialog, so lets create it :
TDEConfigDialog* dialog = new KConfigDialog( this, "settings",
ExampleSettings::self() );
ExampleDesignerWidget* confWdg =
new ExampleDesignerWidget( 0, "Example" );

dialog->addPage( confWdg, i18n("Example"), "example" );

//User edited the configuration - update your local copies of the
//configuration data
connect( dialog, SIGNAL(settingsChanged()),
this, SLOT(updateConfiguration()) );

dialog->show();
</syntaxhighlight>

And that's all it takes. You can have a look at KReversi and KTron code in the <tt>tdegames</tt> module to see a live example of TDEConfig XT!

= Final remarks =
TDEConfig XT is a very easy, extensible and flexible configuration framework. Hopefully this tutorial will make this great framework more understandable for you.

== Common Pitfalls and Tips ==

* Do not forget to add the <tt>type</tt> attribute to the <code><entry></code> tag in your .kcfg file.
* Always try to add both the <code><label></code> and <code><whatsthis></code> tags to each entry.
* Try to use the <tt>code</tt> specifiers in the .kcfg as seldom as possible. We might soon deprecate them.
* Putting the <tt>MemberVariables=public</tt> in your .kcfgc is usually a bad idea - you'll avoid accidental changes to those members by using the aggregation and forcing the use of the mutators.
** If your application doesn't have one central object (created before and destructed after; all others) then always put the Singleton=true entry in your .kcfgs file.

<small>
'''Copyright notice'''

Originally written by Zack Rusin <zack@kde.org>

Tutorial imported from [http://web.archive.org/web/20070203132425/http://developer.kde.org/documentation/tutorials/kconfigxt/kconfigxt.html KDE Developer Documentation].
</small>

[[Category:Developers]]
[[Category:Tutorials]]

@@ Line 115: / Line 115: @@
 |}
-= Adjusting the Makefile.am =
+= Adjusting the CMakeLists.txt =
+The only thing you have to do is to add your .kcfgc file to your program's sources.
-{{Outdated|2021|01|06|reason=Makefile.am rules}}
+For example, this is an excerpt from the <tt>CMakeLists.txt</tt> for the Kicker taskbar:
+<syntaxhighlight lang="cmake">
+set( ${target}_SRCS
+  taskbarsettings.kcfgc taskcontainer.cpp taskbar.cpp
+  taskbarcontainer.cpp taskbarcontainer.skel
+)
+tde_add_library( ${target} SHARED AUTOMOC
+  SOURCES ${${target}_SRCS}
+  # [...]
+)
+</syntaxhighlight>
+<!--
 After creating the .kcfg and .kcfgc files the next step is to adjust the Makefile.am to let tdeconfig_compiler generate the required class at compile time.
@@ Line 129: / Line 144: @@
 The first assures that the configuration class is properly generated the second that the .kcfg is actually being installed and can be used by tools like the TDEConfigEditor.
+-->
 = Use and Dialogs =

@@ Line 53: / Line 53: @@
 </syntaxhighlight>
-Use your favorite code editor to open a your_application_name .kcfg file (of course replacing your_application_name with the name of the application you want to convert to TDEConfig XT).
+# Use your favorite code editor to open a your_application_name .kcfg file (of course replacing your_application_name with the name of the application you want to convert to TDEConfig XT).
+# Start that file by opening the <code>&lt;kcfgfile&gt;</code> tag which contains the <tt>name</tt> attribute with the value corresponding to the actual TDEConfig file which it describes. (The actual TDEConfig file are the rc files).
+# ''Add the optional <code>&lt;include&gt;</code> tags which may contain C++ header files that are needed to compile the code required to compute the default values.''
+# The remaining entries in the XML file are grouped by the tag <code>&lt;group&gt;</code> which describes the corresponding groups in the configuration file.
+:# The individual entries must have at least a name or a key. The name is used to create accessor and modifier functions. It's also used as the key in the config file. If <code>&lt;key&gt;</code> is given, but not <code>&lt;name&gt;</code>, the name is constructed by removing all spaces from the <code>&lt;key&gt;</code> contents.
-Start that file by opening the <code>&lt;kcfgfile&gt;</code> tag which contains the <tt>name</tt> attribute with the value corresponding to the actual TDEConfig file which it describes. (The actual TDEConfig file are the rc files).
+:# Always add a label or a whatsthis tags to your application in which you describe the configuration options. The label tag is used for short descriptions of the entry, while <tt>whatsthis</tt> contains more verbose documentation. It's important for tools <!-- like KConfigEditor - what's this? --> which can be used by systems administrators to setup machines over on the network.
+:# An entry must also have a type. The list of allowable types is specified in the DTD and loosely follows the list of types supported by the TQVariant with exception of the clearly binary types (e.g. Pixmap, Image...) which are not supported. Besides those basic type the following special types are supported and include:
-Add the optional <code>&lt;include&gt;</code> tags which may contain C++ header files that are needed to compile the code required to compute the default values.
-The remaining entries in the XML file are grouped by the tag <code>&lt;group&gt;</code> which describes the corresponding groups in the configuration file.
-The individual entries must have at least a name or a key. The name is used to create accessor and modifier functions. It's also used as the key in the config file. If <code>&lt;key&gt;</code> is given, but not <code>&lt;name&gt;</code>, the name is constructed by removing all spaces from the <code>&lt;key&gt;</code> contents.
-Always add a label or a whatsthis tags to your application in which you describe the configuration options. The label tag is used for short descriptions of the entry, while <tt>whatsthis</tt> contains more verbose documentation. It's important for tools <!-- like KConfigEditor - what's this? --> which can be used by systems administrators to setup machines over on the network.
-An entry must also have a type. The list of allowable types is specified in the DTD and loosely follows the list of types supported by the TQVariant with exception of the clearly binary types (e.g. Pixmap, Image...) which are not supported. Besides those basic type the following special types are supported and include:
 {| class="wikitable"
@@ Line 81: / Line 76: @@
 |}
-An entry can optionally have a default value which is used as default when the value isn't specified in any config file. Default values are interpreted as literal constant values. If a default value needs to be computed or if it needs to be obtained from a function call, the <code>&lt;default&gt;</code> tag should contain the <tt>code="true"</tt> attribute. The contents of the <code>&lt;default&gt;</code> tag is then considered to be a C++ expression.
+''An entry can optionally have a default value which is used as default when the value isn't specified in any config file. Default values are interpreted as literal constant values. If a default value needs to be computed or if it needs to be obtained from a function call, the <code>&lt;default&gt;</code> tag should contain the <tt>code="true"</tt> attribute. The contents of the <code>&lt;default&gt;</code> tag is then considered to be a C++ expression.''
-Additional code for computing default values can be provided via the <code>&lt;code&gt;</code> tag. The contents of the <code>&lt;code&gt;</code> tag is inserted as-is. A typical use for this is to compute a common default value which can then be referenced by multiple entries that follow.
+''Additional code for computing default values can be provided via the <code>&lt;code&gt;</code> tag. The contents of the <code>&lt;code&gt;</code> tag is inserted as-is. A typical use for this is to compute a common default value which can then be referenced by multiple entries that follow.''
 = .kcfgc files =

@@ Line 93: / Line 93: @@
 {| class="wikitable"
 !  Key
-!  Type
+!  Type (default value)
 !  Description
 |-
@@ Line 109: / Line 109: @@
 |-
 |  '''Singleton'''
-|  Boolean
+|  Boolean (false)
 |  If the configuration class should be a singleton.
 |-
@@ Line 121: / Line 121: @@
 |-
 |  '''ItemAccessors'''
-|  Boolean
+|  Boolean (false)
 |  Relates to the above item. If member variables are public then it might make little sense to generate accessors. By default they are generated.
 |-
 |  '''Mutators'''
 |  StringList
-|  List of properties for which to generate mutators. If this is empty or unset, mutators are generated for all properties.
+|  List of properties for which to generate mutators.  The special value "true" generates mutators for all properties. By default no mutators are generated.
 |-
 |  '''GlobalEnums'''
-|  Boolean
+|  Boolean (false)
 |  Specifies whether the enums should be class wide of whether they should be always explicitly prefixed with their type name.
 |-
 |  '''CustomAdditions'''
-|  Boolean
+|  Boolean (false)
 |  If enabled, it looks for a special source file with addons which can be used to add extra functions and variables to the class. The name of the file consists from the filename of the .kcfgc file, minus the extension, plus the string "_addons.h".
 |-
@@ Line 141: / Line 141: @@
 |-
 |  '''SetUserTexts'''
-|  Boolean
+|  Boolean (false)
 |  This enables internationalization for the <code>&lt;label&gt;</code> and <code>&lt;whatsthis&gt;</code> elements.
 |}

@@ Line 82: / Line 82: @@
 = .kcfgc files =
-After creating a .kcfg file create a .kcfgc file which describes the C++ file generation options. The .kcfgc file is a simple ini file with the typical "entry=value" format. To create a simple .kcfgc file follow these steps:
+After creating a .kcfg file create a .kcfgc file which describes the C++ file generation options. The .kcfgc file is a simple ini file with the typical <code>entry = value</code> format. To create a simple .kcfgc file follow these steps:
 * Open a new file in your favorite text editor.
-* Start it with the "File=your_application_name.kcfg" entry which specifies where the configuration options for your application are stored.
+* Start it with the <code>File=your_application_name.kcfg</code> entry which specifies where the configuration options for your application are stored.
-* Add the "ClassName=YourConfigClassName" entry which specifies the name of the class that will be generated from the .kcfg file. Remember that the generated class will be derived from TDEConfigSkeleton. PLease make sure that YourConfigClassName is not a class name already used in your application. Save this file under yourconfigclassname.kcfgc. This will ensure the generation of the yourconfigclassname.{h,cpp} files where your configuration class will reside.
+* Add the <code>ClassName = YourConfigClassName</code> entry which specifies the name of the class that will be generated from the .kcfg file. Remember that the generated class will be derived from TDEConfigSkeleton. PLease make sure that <tt>YourConfigClassName</tt> is not a class name already used in your application. Save this file under <tt>yourconfigclassname.kcfgc</tt>. This will ensure the generation of the yourconfigclassname.{h,cpp} files where your configuration class will reside.
-* Add any additional entries, which your application might need. Those additional entries include:
+* Add any additional entries, which your application might need.
+This is a list of keys understood by <tt>tdeconfig_compiler</tt>:
 {| class="wikitable"
-!  Entry
+!  Key
+!  Type
 !  Description
 |-
-| '''NameSpace'''
+|  '''NameSpace'''
+|  String
 |  Specifies the namespace in which the generated config class should reside.
+|-
+|  '''ClassName'''
+|  String
+|  Specifies the name of the class that will be generated from the .kcfg file
 |-
 |  '''Inherits'''
+|  String
 |  If you need the generated class to inherit your custom class.
 |-
 |  '''Singleton'''
+|  Boolean
 |  If the configuration class should be a singleton.
+|-
+|  '''Visibility'''
+|  String
+|  Specifies the visibility of the generated class.
 |-
 |  '''MemberVariables'''
+|  String
-|  Specifies the access to the member variables, default is private.
+|  Specifies the access to the member variables, default is <tt>private</tt>. A special value is "dpointer", which stores members in a private class, accessed privately by a pointer <tt>d</tt>.
 |-
 |  '''ItemAccessors'''
+|  Boolean
-|  Relates to the above item, if member variables are public then it might make little sense to generate accessors. By default they are generated.
+|  Relates to the above item. If member variables are public then it might make little sense to generate accessors. By default they are generated.
 |-
 |  '''Mutators'''
+|  StringList
-|  Similar to the above one, but applies to the mutator methods.
+|  List of properties for which to generate mutators. If this is empty or unset, mutators are generated for all properties.
 |-
 |  '''GlobalEnums'''
+|  Boolean
 |  Specifies whether the enums should be class wide of whether they should be always explicitly prefixed with their type name.
+|-
+|  '''CustomAdditions'''
+|  Boolean
+|  If enabled, it looks for a special source file with addons which can be used to add extra functions and variables to the class. The name of the file consists from the filename of the .kcfgc file, minus the extension, plus the string "_addons.h".
+|-
+|  '''IncludeFiles'''
+|  StringList
+|  This is a list of files to be included in the class source.
+|-
+|  '''SetUserTexts'''
+|  Boolean
+|  This enables internationalization for the <code>&lt;label&gt;</code> and <code>&lt;whatsthis&gt;</code> elements.
 |}

@@ Line 218: / Line 218: @@
 //TDEConfigDialog didn't find an instance of this dialog, so lets create it :
-TDEConfigDialog* dialog = new KConfigDialog( this, "settings",
+TDEConfigDialog* dialog = new TDEConfigDialog( this, "settings",
                                            ExampleSettings::self() );
 ExampleDesignerWidget* confWdg =

@@ Line 122: / Line 122: @@
 = Adjusting the Makefile.am =
-{{Outdated}}
+{{Outdated|2021|01|06|reason=Makefile.am rules}}
 After creating the .kcfg and .kcfgc files the next step is to adjust the Makefile.am to let tdeconfig_compiler generate the required class at compile time.
@@ Line 152: / Line 152: @@
 * In TQt Designer create widgets which should be used to configure your options. In order to make those widgets interact with the kcfg you have name each one of them using the following scheme:
-        Prefix the Name of the widget which should control one of the options with "kcfg_"
+** Prefix the Name of the widget which should control one of the options with "kcfg_"
-        Append the "name" attribute value from your kcfg file which corresponds to option the given widget should control.
+** Append the "name" attribute value from your kcfg file which corresponds to option the given widget should control.
 * Add the TQt Designer generated widget to the TDEConfigDialog.
@@ Line 204: / Line 204: @@
 </syntaxhighlight>
-To add a dialog you need to create a TQt Designer widget with the widget names corresponding to the names of the options they should edit and prefixed with "kcfg_". It could be something along the lines of :
+To add a dialog you need to create a TQt Designer widget with the widget names corresponding to the names of the options they should edit and prefixed with "kcfg_". It could be something along the lines of:
-sample dialog
+[[File:Kcdialog.png]]
 And you can use the dialog with the following code: