.. _userguide-commands:

*******************
Commands management
*******************


Add commands to stage (graphical mode)
======================================

In *graphical* mode the addition of a command can be done in several ways:

* Via the dedicated drop-down list in toolbar,
* Via the *Commands* main menu,
* Via the context menu on the stage,
* Via the search dialog for commands (see below).

The commands are sorted by *category* (*Mesh*, *Material* ...).

When a command is added to the stage, the commands are **automatically** sorted
by *category* and taking into account the dependencies between them. It is not
possible to change the order of the commands in the *Data Settings* tab.
If dependencies between commands are added or removed, the order of commands
is *automatically* recalculated.


.. _search-panel:

Search command
--------------

.. |see_all| image:: /images/see_all.png

The search panel is accessible via the *Show All* item |see_all| in the
*Commands* menu.

The search panel shows all the commands grouped by *category*.
The *search* field is used to filter out the commands.

.. note::
    Depending on the version of *Code_Aster* being used, the *categories* can
    be additionally split to the *sub-categories*, which appear as enclosed
    groups in the search panel.

You can then add a command to the selected *graphical* stage by double-clicking
on the command name, or by clicking the *OK* or *Apply* button.

.. figure:: /images/search_command.png
    :alt: Show All dialog
    :align: center

    **Show All dialog**


Favorites category
------------------

The user is able to put most oftenly used commands to the **Favorites**
category.

To add a command to the *Favorites* category:

* Open the :ref:`search panel <search-panel>`,
* Select a command,
* Use *Add to Favorites* context menu item.

The *Favorites* category is available as:

* Main menu *Commands > Favorites*,
* Dedicated drop-down list in the *Commands* toolbar,
* A group in the search panel (which appears on a very first place),
* An item in the context menu for the stage in the *Data Settings* tab.

To remove a command from the *Favorites* category:

* Open the :ref:`search panel <search-panel>`,
* Select a command,
* Use *Remove from Favorites* context menu item.

.. warning::
    If *Favorites* category is empty, it is not shown in the toolbar, main menu
    and search panel.


Rename command
--------------

Commands are added to a study with the default name.
You can rename command by editing it or by selecting it in the *Data Settings*
tab and then pressing *F2* key or invoking *Rename* item from the context menu.


Edit command
------------

.. |hide_unused| image:: /images/eye_off.png
.. |command_help| image:: /images/command_help.png
.. |edit_comment| image:: /images/edit_comment.png
.. |whats_this| image:: /images/whats_this.png
.. |use_translations| image:: /images/use_translations.png

To edit a command, double-click the item in the *Data Settings* tab, or select
a command and press *F4* or invoke *Edit* item from the context menu.

.. figure:: /images/edit_command.png
    :alt: Edit command
    :align: center

    **Edit command**


The *Name* field is used to rename the command.

The |command_help| button opens a documentation on the command. This operation
is also available in the *Edit* main menu and in context menu in *Data Settings*
tab.

The |hide_unused| button allows to display only selected parameters.

The |edit_comment| button allows
:ref:`adding comment to a command <edit-comment>`.

The |use_translations| button switches ON/OFF
:ref:`business-oriented translations <business-translations>`.

The |whats_this| button allows to display a description of selected keyword:

.. figure:: /images/show_whats_this.png
    :alt: What's This
    :align: center

    **What's This**


The user can then enter the parameters of the command by checking the box of
the parameter to be filled in and then specifying its value.

.. note::
    Mandatory parameters are followed by a red asterisk (see `Model` on the
    previous image).

The parameter value can be given via either a text or numeric field, a drop-down
list or, for more complex parameters, an *Edit* button to access a subscreen for
editing this parameter.

The following screen shows the editing of the `Timestepping` parameter.

.. figure:: /images/edit_command_sub.png
    :alt: Edition of parameter
    :align: center

    **Edition of parameter**


.. hint::
    The second line (`Linear thermal analysis > Timestepping`) allows you to
    find your way through the sequence of screens.


Delete or copy command
----------------------

You can delete a command or duplicate it by using the corresponding toolbar
buttons, menus, or keyboard shortcuts (*Del* and *Ctrl+D* respectively).

.. important::
    The order of the commands and the validation are carried out during the
    suppression of a command to check that the integrity of the stage is
    respected.


Activate / deactivate command
-----------------------------

A command can be temporarily removed from the stage by using *Deactivate*
operation. Deactivated commands are shown grayed in the *Data Settings* tab.

.. figure:: /images/deactivated_command.png
    :alt: Deactivated command
    :align: center

    **Deactivated command**


All usual operations are allowed for deactivated commands; however, they are
not shown in the drop-down selectors when editing other commands. In addition,
when stage is converted to the *text* mode or exported to a command file,
deactivated commands appear as comment blocks.

Deactivated command can be re-activated via the *Activate* operation.

*Deactivate* and *Activate* operations are available in:

* *Edit* main menu,
* Context menu of a command in *Data Settings* tab.


.. _edit-comment:

Add comment
-----------

The button |edit_comment| edits the comment associated with the command.
This button is available in the *Commands* toolbar, in the command editing
panel, in main menu and in the context menu.

.. figure:: /images/comment_command.png
    :alt: Edit comment
    :align: center

    **Edit comment**


Variables
---------

.. |add_variable| image:: /images/add_variable.png
.. |edit_variable| image:: /images/edit_variable.png

The button |add_variable| adds a variable to the stage. This button is available
in the *Commands* toolbar, in main menu and in the context menu.

You can then edit the variable by entering its value.
The value of the variable can be defined by an expression.

.. figure:: /images/define_variable.png
    :alt: Create variable
    :align: center

    **Create variable**


.. |choose_variable| image:: /images/choose_variable.png

Variables can then be used for commands definition.
When editing a control field, choose the |choose_variable| icon to the right of
the input field. The input field is then replaced by a drop-down list in which
you can select the variable to use.

.. figure:: /images/use_variable.png
    :alt: Use variable
    :align: center

    **Use variable**


.. _business-translations:

Use translation of the *Code_Aster* terms
-----------------------------------------

The icon |use_translations| allows switching ON/OFF business-oriented
translations of the *Code_Aster* terms.

.. figure:: /images/business_translations.png
    :alt: Use of business-oriented translations
    :align: center

    **Use of business-oriented translations**


Clipboard operations
====================

Standard clipboard operations *Copy*, *Cut* and *Paste* are applicable to the
commands:

* *Copy* (*Ctrl+C*): copies selected command to the clipboard,
* *Cut* (*Ctrl+X*): removes selected command from the stage and puts it to the
  clipboard,
* *Paste* (*Ctrl+P*): inserts a command from the clipboard to the selected
  stage.

These operations are also available in the *Edit* main menu and context menu.


Edition in text mode
====================

In *text* mode, the stage is managed as a whole and the commands that compose
it are not displayed in the *Data Settings* tab under the stage item.

To edit the commands for a stage in *text* mode, double-click on the stage item
in the *Data Settings* tab, press *F4* or use *Edit* context menu command to
open the text editor.

.. figure:: /images/text_mode.png
    :alt: Edit stage in text mode
    :align: center

    **Edit stage in text mode**

.. note::
    It is possible to use either an internal editor or an external editor
    program (see :ref:`userguide-preferences`).

In addition to editing command file representing the stage in *text* mode, the
user is able to declare the concepts which are created in the study by this
stage (lower part of the dialog on above picture). The concepts entered here
will be available for the selection in the following *graphical* stages.

.. warning::
    Application cannot check that concepts declared by the user are actually
    created by the stage. This is the responsibility of the user to provide
    correct information.

.. important::
    User can also declare concepts created in the *text* stage with the
    *Edit concepts* operation which is available in *Edit* main menu and in
    the context menu for the stage in the *Data Settings* tab.
