======================================
Working with SpWML from code
======================================

Basic operation
=================

It will be easier to understand if you check the sample below.
https://pub.dev/packages/simple_widget_markup/example

One of the SpWML parameters contain above sample is "sid".
For example, a block with "sid:deleteButton" can be retrieved from the Dart code as follows.

.. code-block:: none
   
   BtnElement delBtn = builder.getElement("deleteButton") as BtnElement;

See :ref:`Classes and Methods <classes_and_methods>` to see what types there are and what parameters they have.
The "BtnElement" part changes depending on what you want to get. This is mentioned on the page above.
Basically, except for some abbreviations, the class is named "SpWML type name + Element".

Each class has almost the same parameters as similar classes in Flutter, and by rewriting the class parameters as follows,
You can control almost everything from code.

.. code-block:: none
   
   BtnElement runBtn = builder.getElement("runButton") as BtnElement;
   runBtn.elParams.p.normalBtnParams?.style = const ButtonStyle();
   runBtn.textParams.p.isSelectable = true;

There are various types of parameters, but they are all named xxParams,
Basically what you use in that class is defined with the name elParams.
Exceptions are Text type Element, such as textParams, tfParams, and rubyParams.
The parameter common to all elements is spwmlParams.
Access to "params" is not recommended as it is a parameter used internally.

In addition, frequently used variables may be implemented in element methods.
If there is an implementation, please use it. It may be safer to operate.  

Furthermore, if you use the automatic code generation function of the SpWML editor, you can automatically generate most of the necessary code from SpWML, so it may be better to use that first.

https://simple-widget-markup-editor.web.app/

----

State management
==================

SpWML switched to state management using simple_managers after version 20.

https://pub.dev/packages/simple_managers

By giving SpWMLBlilder the required manager class in the layout, the state will be automatically managed.
Each manager class included in simple_managers supports serialization.
Easy to save and restore.

By using the StateManager added in version 3.0.0 of the simple_managers package, all states are managed for each sid and can be serialized and deserialized all at once.  

.. code-block:: none

   SpWMLBlilder b = SpWMLBlilder(layout);
   b.setStateManager(Manager class stored in class variables etc.);
   // or b.setManager(the manager class you want to use);

----

Integration with Flutter widgets
=================================

Using the struct :ref:`block <block>` you can embed widgets inside like this:
By using this, if the screen parts created by the designer with the design tool are converted to Flutter Widgets, you can be easily embedded.

.. code-block:: none

   SpWMLBuilder b = SpWMLBuilder(layout);
   b.replace (Target block sid, Widget);
   Widget compiledWidget = b.build(context);

Use this when reusing existing code or embedding special screen parts that are difficult to write in a static language.

----

Create a dialog with SpWML
===================================

SpWML can create dialogs as well as main screens.
Added in version 21.0.0, SpWMLDialog makes it easy to create even complex dialogs.

.. code-block:: none

   SpWMLBuilder b = SpWMLBuilder(layout);
   b.setStateManager(Manager class stored in class variables etc.);
   // or b.setManager(the manager class you want to use);
   showDialog(
        context: context,
        builder: (context) {
          return SpWMLDialog(
            b,
            const Text('Dialog title'),
            width: 320, // The dialog width
            cancelBtnCallback: (close) {
              close();
            },
            okBtnCallback: (close) {
              close();
            },
          );
        });
   
You don't need to create your own dialog class every time anymore.
Even for dialogs with state, the state is automatically managed by the manager class.